aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorKim Alvefur <zash@zash.se>2019-11-16 16:52:31 +0100
committerKim Alvefur <zash@zash.se>2019-11-16 16:52:31 +0100
commit908f5b61c55e4cba39e61ac415b0fca384a1095d (patch)
tree6e391ff6608608f181e42c92ee6dfd7c534da255 /doc
parentc4c38d2f01d5f2711b527c7c2412250ed6c58738 (diff)
parentfd9ccf20d5b652dbad1f37cecd540661f4642ee6 (diff)
downloadprosody-908f5b61c55e4cba39e61ac415b0fca384a1095d.tar.gz
prosody-908f5b61c55e4cba39e61ac415b0fca384a1095d.zip
Merge 0.11->trunk
Diffstat (limited to 'doc')
-rw-r--r--doc/coding_style.md804
-rw-r--r--doc/coding_style.txt33
-rw-r--r--doc/doap.xml531
-rw-r--r--doc/net.server.lua21
-rw-r--r--doc/storage.tld3
5 files changed, 1359 insertions, 33 deletions
diff --git a/doc/coding_style.md b/doc/coding_style.md
new file mode 100644
index 00000000..f9a10ece
--- /dev/null
+++ b/doc/coding_style.md
@@ -0,0 +1,804 @@
+
+# Prosody Coding Style Guide
+
+This style guides lists the coding conventions used in the
+[Prosody](https://prosody.im/) project. It is based heavily on the [style guide used by the LuaRocks project](https://github.com/luarocks/lua-style-guide).
+
+## Indentation and formatting
+
+* Prosody code is indented with tabs at the start of the line, a single
+ tab per logical indent level:
+
+```lua
+for i, pkg in ipairs(packages) do
+ for name, version in pairs(pkg) do
+ if name == searched then
+ print(version);
+ end
+ end
+end
+```
+
+Tab width is configurable in editors, so never assume a particular width.
+Specically this means you should not mix tabs and spaces, or use tabs for
+alignment of items at different indentation levels.
+
+* Use LF (Unix) line endings.
+
+## Comments
+
+* Comments are encouraged where necessary to explain non-obvious code.
+
+* In general comments should be used to explain 'why', not 'how'
+
+### Comment tags
+
+A comment may be prefixed with one of the following tags:
+
+* **FIXME**: Indicates a serious problem with the code that should be addressed
+* **TODO**: Indicates an open task, feature request or code restructuring that
+ is primarily of interest to developers (otherwise it should be in the
+ issue tracker).
+* **COMPAT**: Must be used on all code that is present only for backwards-compatibility,
+ and may be removed one day. For example code that is added to support old
+ or buggy third-party software or dependencies.
+
+**Example:**
+
+```lua
+-- TODO: implement method
+local function something()
+ -- FIXME: check conditions
+end
+
+```
+
+## Variable names
+
+* Variable names with larger scope should be more descriptive than those with
+smaller scope. One-letter variable names should be avoided except for very
+small scopes (less than ten lines) or for iterators.
+
+* `i` should be used only as a counter variable in for loops (either numeric for
+or `ipairs`).
+
+* Prefer more descriptive names than `k` and `v` when iterating with `pairs`,
+unless you are writing a function that operates on generic tables.
+
+* Use `_` for ignored variables (e.g. in for loops:)
+
+```lua
+for _, item in ipairs(items) do
+ do_something_with_item(item);
+end
+```
+
+* Generally all identifiers (variables and function names) should use `snake_case`,
+ i.e. lowercase words joined by `_`.
+
+```lua
+-- bad
+local OBJEcttsssss = {}
+local thisIsMyObject = {}
+local c = function()
+ -- ...stuff...
+end
+
+-- good
+local this_is_my_object = {};
+
+local function do_that_thing()
+ -- ...stuff...
+end
+```
+
+> **Rationale:** The standard library uses lowercase APIs, with `joinedlowercase`
+names, but this does not scale too well for more complex APIs. `snake_case`
+tends to look good enough and not too out-of-place along side the standard
+APIs.
+
+```lua
+for _, name in pairs(names) do
+ -- ...stuff...
+end
+```
+
+* Prefer using `is_` when naming boolean functions:
+
+```lua
+-- bad
+local function evil(alignment)
+ return alignment < 100
+end
+
+-- good
+local function is_evil(alignment)
+ return alignment < 100;
+end
+```
+
+* `UPPER_CASE` is to be used sparingly, with "constants" only.
+
+> **Rationale:** "Sparingly", since Lua does not have real constants. This
+notation is most useful in libraries that bind C libraries, when bringing over
+constants from C.
+
+* Do not use uppercase names starting with `_`, they are reserved by Lua.
+
+## Tables
+
+* When creating a table, prefer populating its fields all at once, if possible:
+
+```lua
+local player = { name = "Jack", class = "Rogue" };
+```
+
+* Items should be separated by commas. If there are many items, put each
+ key/value on a separate line and use a semi-colon after each item (including
+ the last one):
+
+```lua
+local player = {
+ name = "Jack";
+ class = "Rogue";
+}
+```
+
+> **Rationale:** This makes the structure of your tables more evident at a glance.
+Trailing semi-colons make it quicker to add new fields and produces shorter diffs.
+
+* Use plain `key` syntax whenever possible, use `["key"]` syntax when using names
+that can't be represented as identifiers and avoid mixing representations in
+a declaration:
+
+```lua
+local mytable = {
+ ["1394-E"] = val1;
+ ["UTF-8"] = val2;
+ ["and"] = val2;
+}
+```
+
+## Strings
+
+* Use `"double quotes"` for strings; use `'single quotes'` when writing strings
+that contain double quotes.
+
+```lua
+local name = "Prosody";
+local sentence = 'The name of the program is "Prosody"';
+```
+
+> **Rationale:** Double quotes are used as string delimiters in a larger number of
+programming languages. Single quotes are useful for avoiding escaping when
+using double quotes in literals.
+
+## Line lengths
+
+* There are no hard or soft limits on line lengths. Line lengths are naturally
+limited by using one statement per line. If that still produces lines that are
+too long (e.g. an expression that produces a line over 256-characters long,
+for example), this means the expression is too complex and would do better
+split into subexpressions with reasonable names.
+
+> **Rationale:** No one works on VT100 terminals anymore. If line lengths are a proxy
+for code complexity, we should address code complexity instead of using line
+breaks to fit mind-bending statements over multiple lines.
+
+## Function declaration syntax
+
+* Prefer function syntax over variable syntax. This helps differentiate between
+named and anonymous functions.
+
+```lua
+-- bad
+local nope = function(name, options)
+ -- ...stuff...
+end
+
+-- good
+local function yup(name, options)
+ -- ...stuff...
+end
+```
+
+* Perform validation early and return as early as possible.
+
+```lua
+-- bad
+local function is_good_name(name, options, arg)
+ local is_good = #name > 3
+ is_good = is_good and #name < 30
+
+ -- ...stuff...
+
+ return is_good
+end
+
+-- good
+local function is_good_name(name, options, args)
+ if #name < 3 or #name > 30 then
+ return false;
+ end
+
+ -- ...stuff...
+
+ return true;
+end
+```
+
+## Function calls
+
+* Even though Lua allows it, generally you should not omit parentheses
+ for functions that take a unique string literal argument.
+
+```lua
+-- bad
+local data = get_data"KRP"..tostring(area_number)
+-- good
+local data = get_data("KRP"..tostring(area_number));
+local data = get_data("KRP")..tostring(area_number);
+```
+
+> **Rationale:** It is not obvious at a glace what the precedence rules are
+when omitting the parentheses in a function call. Can you quickly tell which
+of the two "good" examples in equivalent to the "bad" one? (It's the second
+one).
+
+* You should not omit parenthesis for functions that take a unique table
+argument on a single line. You may do so for table arguments that span several
+lines.
+
+```lua
+local an_instance = a_module.new {
+ a_parameter = 42;
+ another_parameter = "yay";
+}
+```
+
+> **Rationale:** The use as in `a_module.new` above occurs alone in a statement,
+so there are no precedence issues.
+
+## Table attributes
+
+* Use dot notation when accessing known properties.
+
+```lua
+local luke = {
+ jedi = true;
+ age = 28;
+}
+
+-- bad
+local is_jedi = luke["jedi"]
+
+-- good
+local is_jedi = luke.jedi;
+```
+
+* Use subscript notation `[]` when accessing properties with a variable or if using a table as a list.
+
+```lua
+local vehicles = load_vehicles_from_disk("vehicles.dat")
+
+if vehicles["Porsche"] then
+ porsche_handler(vehicles["Porsche"]);
+ vehicles["Porsche"] = nil;
+end
+for name, cars in pairs(vehicles) do
+ regular_handler(cars);
+end
+```
+
+> **Rationale:** Using dot notation makes it clearer that the given key is meant
+to be used as a record/object field.
+
+## Functions in tables
+
+* When declaring modules and classes, declare functions external to the table definition:
+
+```lua
+local my_module = {};
+
+function my_module.a_function(x)
+ -- code
+end
+```
+
+* When declaring metatables, declare function internal to the table definition.
+
+```lua
+local version_mt = {
+ __eq = function(a, b)
+ -- code
+ end;
+ __lt = function(a, b)
+ -- code
+ end;
+}
+```
+
+> **Rationale:** Metatables contain special behavior that affect the tables
+they're assigned (and are used implicitly at the call site), so it's good to
+be able to get a view of the complete behavior of the metatable at a glance.
+
+This is not as important for objects and modules, which usually have way more
+code, and which don't fit in a single screen anyway, so nesting them inside
+the table does not gain much: when scrolling a longer file, it is more evident
+that `check_version` is a method of `Api` if it says `function Api:check_version()`
+than if it says `check_version = function()` under some indentation level.
+
+## Variable declaration
+
+* Always use `local` to declare variables.
+
+```lua
+-- bad
+superpower = get_superpower()
+
+-- good
+local superpower = get_superpower();
+```
+
+> **Rationale:** Not doing so will result in global variables to avoid polluting
+the global namespace.
+
+## Variable scope
+
+* Assign variables with the smallest possible scope.
+
+```lua
+-- bad
+local function good()
+ local name = get_name()
+
+ test()
+ print("doing stuff..")
+
+ --...other stuff...
+
+ if name == "test" then
+ return false
+ end
+
+ return name
+end
+
+-- good
+local bad = function()
+ test();
+ print("doing stuff..");
+
+ --...other stuff...
+
+ local name = get_name();
+
+ if name == "test" then
+ return false;
+ end
+
+ return name;
+end
+```
+
+> **Rationale:** Lua has proper lexical scoping. Declaring the function later means that its
+scope is smaller, so this makes it easier to check for the effects of a variable.
+
+## Conditional expressions
+
+* False and nil are falsy in conditional expressions. Use shortcuts when you
+can, unless you need to know the difference between false and nil.
+
+```lua
+-- bad
+if name ~= nil then
+ -- ...stuff...
+end
+
+-- good
+if name then
+ -- ...stuff...
+end
+```
+
+* Avoid designing APIs which depend on the difference between `nil` and `false`.
+
+* Use the `and`/`or` idiom for the pseudo-ternary operator when it results in
+more straightforward code. When nesting expressions, use parentheses to make it
+easier to scan visually:
+
+```lua
+local function default_name(name)
+ -- return the default "Waldo" if name is nil
+ return name or "Waldo";
+end
+
+local function brew_coffee(machine)
+ return (machine and machine.is_loaded) and "coffee brewing" or "fill your water";
+end
+```
+
+Note that the `x and y or z` as a substitute for `x ? y : z` does not work if
+`y` may be `nil` or `false` so avoid it altogether for returning booleans or
+values which may be nil.
+
+## Blocks
+
+* Use single-line blocks only for `then return`, `then break` and `function return` (a.k.a "lambda") constructs:
+
+```lua
+-- good
+if test then break end
+
+-- good
+if not ok then return nil, "this failed for this reason: " .. reason end
+
+-- good
+use_callback(x, function(k) return k.last end);
+
+-- good
+if test then
+ return false
+end
+
+-- bad
+if test < 1 and do_complicated_function(test) == false or seven == 8 and nine == 10 then do_other_complicated_function() end
+
+-- good
+if test < 1 and do_complicated_function(test) == false or seven == 8 and nine == 10 then
+ do_other_complicated_function();
+ return false;
+end
+```
+
+* Separate statements onto multiple lines. Use semicolons as statement terminators.
+
+```lua
+-- bad
+local whatever = "sure"
+a = 1 b = 2
+
+-- good
+local whatever = "sure";
+a = 1;
+b = 2;
+```
+
+## Spacing
+
+* Use a space after `--`.
+
+```lua
+--bad
+-- good
+```
+
+* Always put a space after commas and between operators and assignment signs:
+
+```lua
+-- bad
+local x = y*9
+local numbers={1,2,3}
+numbers={1 , 2 , 3}
+numbers={1 ,2 ,3}
+local strings = { "hello"
+ , "Lua"
+ , "world"
+ }
+dog.set( "attr",{
+ age="1 year",
+ breed="Bernese Mountain Dog"
+})
+
+-- good
+local x = y * 9;
+local numbers = {1, 2, 3};
+local strings = {
+ "hello";
+ "Lua";
+ "world";
+}
+dog.set("attr", {
+ age = "1 year";
+ breed = "Bernese Mountain Dog";
+});
+```
+
+* Indent tables and functions according to the start of the line, not the construct:
+
+```lua
+-- bad
+local my_table = {
+ "hello",
+ "world",
+ }
+using_a_callback(x, function(...)
+ print("hello")
+ end)
+
+-- good
+local my_table = {
+ "hello";
+ "world";
+}
+using_a_callback(x, function(...)
+ print("hello");
+end)
+```
+
+> **Rationale:** This keep indentation levels aligned at predictable places. You don't
+need to realign the entire block if something in the first line changes (such as
+replacing `x` with `xy` in the `using_a_callback` example above).
+
+* The concatenation operator gets a pass for avoiding spaces:
+
+```lua
+-- okay
+local message = "Hello, "..user.."! This is your day # "..day.." in our platform!";
+```
+
+> **Rationale:** Being at the baseline, the dots already provide some visual spacing.
+
+* No spaces after the name of a function in a declaration or in its arguments:
+
+```lua
+-- bad
+local function hello ( name, language )
+ -- code
+end
+
+-- good
+local function hello(name, language)
+ -- code
+end
+```
+
+* Add blank lines between functions:
+
+```lua
+-- bad
+local function foo()
+ -- code
+end
+local function bar()
+ -- code
+end
+
+-- good
+local function foo()
+ -- code
+end
+
+local function bar()
+ -- code
+end
+```
+
+* Avoid aligning variable declarations:
+
+```lua
+-- bad
+local a = 1
+local long_identifier = 2
+
+-- good
+local a = 1;
+local long_identifier = 2;
+```
+
+> **Rationale:** This produces extra diffs which add noise to `git blame`.
+
+* Alignment is occasionally useful when logical correspondence is to be highlighted:
+
+```lua
+-- okay
+sys_command(form, UI_FORM_UPDATE_NODE, "a", FORM_NODE_HIDDEN, false);
+sys_command(form, UI_FORM_UPDATE_NODE, "sample", FORM_NODE_VISIBLE, false);
+```
+
+## Typing
+
+* In non-performance critical code, it can be useful to add type-checking assertions
+for function arguments:
+
+```lua
+function manif.load_manifest(repo_url, lua_version)
+ assert(type(repo_url) == "string");
+ assert(type(lua_version) == "string" or not lua_version);
+
+ -- ...
+end
+```
+
+* Use the standard functions for type conversion, avoid relying on coercion:
+
+```lua
+-- bad
+local total_score = review_score .. ""
+
+-- good
+local total_score = tostring(review_score);
+```
+
+## Errors
+
+* Functions that can fail for reasons that are expected (e.g. I/O) should
+return `nil` and a (string) error message on error, possibly followed by other
+return values such as an error code.
+
+* On errors such as API misuse, an error should be thrown, either with `error()`
+or `assert()`.
+
+## Modules
+
+Follow [these guidelines](http://hisham.hm/2014/01/02/how-to-write-lua-modules-in-a-post-module-world/) for writing modules. In short:
+
+* Always require a module into a local variable named after the last component of the module’s full name.
+
+```lua
+local bar = require("foo.bar"); -- requiring the module
+
+bar.say("hello"); -- using the module
+```
+
+* Don’t rename modules arbitrarily:
+
+```lua
+-- bad
+local skt = require("socket")
+```
+
+> **Rationale:** Code is much harder to read if we have to keep going back to the top
+to check how you chose to call a module.
+
+* Start a module by declaring its table using the same all-lowercase local
+name that will be used to require it. You may use an LDoc comment to identify
+the whole module path.
+
+```lua
+--- @module foo.bar
+local bar = {};
+```
+
+* Try to use names that won't clash with your local variables. For instance, don't
+name your module something like “size”.
+
+* Use `local function` to declare _local_ functions only: that is, functions
+that won’t be accessible from outside the module.
+
+That is, `local function helper_foo()` means that `helper_foo` is really local.
+
+* Public functions are declared in the module table, with dot syntax:
+
+```lua
+function bar.say(greeting)
+ print(greeting);
+end
+```
+
+> **Rationale:** Visibility rules are made explicit through syntax.
+
+* Do not set any globals in your module and always return a table in the end.
+
+* If you would like your module to be used as a function, you may set the
+`__call` metamethod on the module table instead.
+
+> **Rationale:** Modules should return tables in order to be amenable to have their
+contents inspected via the Lua interactive interpreter or other tools.
+
+* Requiring a module should cause no side-effect other than loading other
+modules and returning the module table.
+
+* A module should not have state. If a module needs configuration, turn
+ it into a factory. For example, do not make something like this:
+
+```lua
+-- bad
+local mp = require "MessagePack"
+mp.set_integer("unsigned")
+```
+
+and do something like this instead:
+
+```lua
+-- good
+local messagepack = require("messagepack");
+local mpack = messagepack.new({integer = "unsigned"});
+```
+
+* The invocation of require may omit parentheses around the module name:
+
+```lua
+local bla = require "bla";
+```
+
+## Metatables, classes and objects
+
+If creating a new type of object that has a metatable and methods, the
+metatable and methods table should be separate, and the metatable name
+should end with `_mt`.
+
+```lua
+local mytype_methods = {};
+local mytype_mt = { __index = mytype_methods };
+
+function mytype_methods:add_new_thing(thing)
+end
+
+local function new()
+ return setmetatable({}, mytype_mt);
+end
+
+return { new = new };
+```
+
+* Use the method notation when invoking methods:
+
+```
+-- bad
+my_object.my_method(my_object)
+
+-- good
+my_object:my_method();
+```
+
+> **Rationale:** This makes it explicit that the intent is to use the function as a method.
+
+* Do not rely on the `__gc` metamethod to release resources other than memory.
+If your object manage resources such as files, add a `close` method to their
+APIs and do not auto-close via `__gc`. Auto-closing via `__gc` would entice
+users of your module to not close resources as soon as possible. (Note that
+the standard `io` library does not follow this recommendation, and users often
+forget that not closing files immediately can lead to "too many open files"
+errors when the program runs for a while.)
+
+> **Rationale:** The garbage collector performs automatic *memory* management,
+dealing with memory only. There is no guarantees as to when the garbage
+collector will be invoked, and memory pressure does not correlate to pressure
+on other resources.
+
+## File structure
+
+* Lua files should be named in all lowercase.
+
+* Tests should be in a top-level `spec` directory. Prosody uses
+[Busted](http://olivinelabs.com/busted/) for testing.
+
+## Static checking
+
+All code should pass [luacheck](https://github.com/mpeterv/luacheck) using
+the `.luacheckrc` provided in the Prosody repository, and using miminal
+inline exceptions.
+
+* luacheck warnings of class 211, 212, 213 (unused variable, argument or loop
+variable) may be ignored, if the unused variable was added explicitly: for
+example, sometimes it is useful, for code understandability, to spell out what
+the keys and values in a table are, even if you're only using one of them.
+Another example is a function that needs to follow a given signature for API
+reasons (e.g. a callback that follows a given format) but doesn't use some of
+its arguments; it's better to spell out in the argument what the API the
+function implements is, instead of adding `_` variables.
+
+```
+local foo, bar = some_function(); --luacheck: ignore 212/foo
+print(bar);
+```
+
+* luacheck warning 542 (empty if branch) can also be ignored, when a sequence
+of `if`/`elseif`/`else` blocks implements a "switch/case"-style list of cases,
+and one of the cases is meant to mean "pass". For example:
+
+```lua
+if warning >= 600 and warning <= 699 then
+ print("no whitespace warnings");
+elseif warning == 542 then --luacheck: ignore 542
+ -- pass
+else
+ print("got a warning: "..warning);
+end
+```
+
+> **Rationale:** This avoids writing negated conditions in the final fallback
+case, and it's easy to add another case to the construct without having to
+edit the fallback.
+
diff --git a/doc/coding_style.txt b/doc/coding_style.txt
deleted file mode 100644
index af44da1a..00000000
--- a/doc/coding_style.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-This file describes some coding styles to try and adhere to when contributing to this project.
-Please try to follow, and feel free to fix code you see not following this standard.
-
-== Indentation ==
-
- 1 tab indentation for all blocks
-
-== Spacing ==
-
-No space between function names and parenthesis and parenthesis and parameters:
-
- function foo(bar, baz)
-
-Single space between braces and key/value pairs in table constructors:
-
- { foo = "bar", bar = "foo" }
-
-== Local variable naming ==
-
-In this project there are many places where use of globals is restricted, and locals used for faster access.
-
-Local versions of standard functions should follow the below form:
-
- math.random -> m_random
- string.char -> s_char
-
-== Miscellaneous ==
-
-Single-statement blocks may be written on one line when short
-
- if foo then bar(); end
-
-'do' and 'then' keywords should be placed at the end of the line, and never on a line by themself.
diff --git a/doc/doap.xml b/doc/doap.xml
new file mode 100644
index 00000000..673e0c23
--- /dev/null
+++ b/doc/doap.xml
@@ -0,0 +1,531 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:foaf="http://xmlns.com/foaf/0.1/" xmlns:xmpp="https://linkmauve.fr/ns/xmpp-doap#" xml:lang="en">
+ <Project xmlns="http://usefulinc.com/ns/doap#">
+ <name>Prosody IM</name>
+ <shortdesc>Lightweight XMPP server</shortdesc>
+ <description>Prosody is a server for Jabber/XMPP written in Lua. It aims to be easy to use and light on resources. For developers, it aims to give a flexible system on which to rapidly develop added functionality or rapidly prototype new protocols.</description>
+ <created>2008-08-22</created>
+ <category rdf:resource="https://linkmauve.fr/ns/xmpp-doap#category-xmpp"/>
+ <category rdf:resource="https://linkmauve.fr/ns/xmpp-doap#category-jabber"/>
+ <category rdf:resource="https://linkmauve.fr/ns/xmpp-doap#category-server"/>
+ <homepage rdf:resource="https://prosody.im/"/>
+ <download-page rdf:resource="https://prosody.im/download/"/>
+ <license rdf:resource="https://hg.prosody.im/trunk/file/tip/COPYING"/>
+ <bug-database rdf:resource="https://issues.prosody.im/"/>
+ <support-forum rdf:resource="xmpp:prosody@conference.prosody.im?join"/>
+ <repository>
+ <HgRepository>
+ <location rdf:resource="https://hg.prosody.im/trunk/"/>
+ <browse rdf:location="https://hg.prosody.im/trunk/"/>
+ </HgRepository>
+ </repository>
+ <programming-langauge>Lua</programming-langauge>
+ <programming-langauge>C</programming-langauge>
+ <os>Linux</os>
+ <os>macOS</os>
+ <os>FreeBSD</os>
+ <os>OpenBSD</os>
+ <os>NetBSD</os>
+ <maintainer>
+ <foaf:Person>
+ <foaf:name>Matthew Wild</foaf:name>
+ <foaf:nick>MattJ</foaf:nick>
+ <foaf:homepage>https://matthewwild.co.uk/</foaf:homepage>
+ </foaf:Person>
+ </maintainer>
+ <maintainer>
+ <foaf:Person>
+ <foaf:name>Waqas Hussain</foaf:name>
+ <foaf:nick>waqas</foaf:nick>
+ </foaf:Person>
+ </maintainer>
+ <maintainer>
+ <foaf:Person>
+ <foaf:name>Kim Alvefur</foaf:name>
+ <foaf:nick>Zash</foaf:nick>
+ <foaf:homepage>https://www.zash.se/</foaf:homepage>
+ </foaf:Person>
+ </maintainer>
+ <implements rdf:resource="https://www.rfc-editor.org/info/rfc5802"/>
+ <implements rdf:resource="https://www.rfc-editor.org/info/rfc6120"/>
+ <implements rdf:resource="https://www.rfc-editor.org/info/rfc6121"/>
+ <implements rdf:resource="https://www.rfc-editor.org/info/rfc6122"/>
+ <implements rdf:resource="https://www.rfc-editor.org/info/rfc6455"/>
+ <implements rdf:resource="https://www.rfc-editor.org/info/rfc7395"/>
+ <!-- Added in hg:0bbbc9042361 released in 0.6.0 -->
+ <implements rdf:resource="https://datatracker.ietf.org/doc/draft-cridland-xmpp-session/"/>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0004.html"/>
+ <xmpp:version>2.9</xmpp:version>
+ <xmpp:status>complete</xmpp:status>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0009.html"/>
+ <xmpp:since>0.4</xmpp:since>
+ <xmpp:until>0.7</xmpp:until>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0012.html"/>
+ <xmpp:version>2.0</xmpp:version>
+ <xmpp:since>0.1</xmpp:since>
+ <xmpp:note>mod_lastactivity and mod_uptime</xmpp:note>
+ <xmpp:status>complete</xmpp:status>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0016.html"/>
+ <xmpp:since>0.7</xmpp:since>
+ <xmpp:until>0.10</xmpp:until>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0030.html"/>
+ <xmpp:since>0.10</xmpp:since>
+ <xmpp:status>complete</xmpp:status>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0045.html"/>
+ <xmpp:version>1.32.0</xmpp:version>
+ <xmpp:since>0.3</xmpp:since>
+ <xmpp:status>partial</xmpp:status>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0049.html"/>
+ <xmpp:version>1.2</xmpp:version>
+ <xmpp:since>0.1</xmpp:since>
+ <xmpp:status>complete</xmpp:status>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0050.html"/>
+ <xmpp:since>0.8</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0054.html"/>
+ <xmpp:since>0.1</xmpp:since>
+ <xmpp:status>complete</xmpp:status>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0060.html"/>
+ <xmpp:version>1.15.8</xmpp:version>
+ <xmpp:since>0.9</xmpp:since>
+ <xmpp:status>partial</xmpp:status>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0065.html"/>
+ <xmpp:version>1.8.1</xmpp:version>
+ <xmpp:since>0.7</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0068.html"/>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0077.html"/>
+ <xmpp:since>0.1</xmpp:since>
+ <xmpp:version>2.4</xmpp:version>
+ <xmpp:status>complete</xmpp:status>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0078.html"/>
+ <xmpp:version>2.5</xmpp:version>
+ <xmpp:since>0.1</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0080.html"/>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0082.html"/>
+ <xmpp:version>1.1</xmpp:version>
+ <xmpp:since>0.1</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0084.html"/>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0090.html"/>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0091.html"/>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0092.html"/>
+ <xmpp:version>1.1</xmpp:version>
+ <xmpp:since>0.1</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0106.html"/>
+ <xmpp:since>0.9</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0107.html"/>
+ <xmpp:note>via XEP-0163</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0108.html"/>
+ <xmpp:note>via XEP-0163</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0114.html"/>
+ <xmpp:version>1.6</xmpp:version>
+ <xmpp:since>0.4</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0115.html"/>
+ <xmpp:since>0.8</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0118.html"/>
+ <xmpp:note>via XEP-0163</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0122.html"/>
+ <xmpp:version>1.0.2</xmpp:version>
+ <xmpp:since>0.11</xmpp:since>
+ <xmpp:status>partial</xmpp:status>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0124.html"/>
+ <xmpp:since>0.2</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0126.html"/>
+ <xmpp:until>0.10</xmpp:until>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0128.html"/>
+ <xmpp:since>0.9</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0133.html"/>
+ <xmpp:since>0.7</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0138.html"/>
+ <xmpp:version>2.0</xmpp:version>
+ <xmpp:since>0.6</xmpp:since>
+ <xmpp:until>0.10</xmpp:until>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0153.html"/>
+ <xmpp:version>1.1</xmpp:version>
+ <xmpp:since>0.11</xmpp:since>
+ <xmpp:note>via XEP-0398</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0157.html"/>
+ <xmpp:version>1.0.1</xmpp:version>
+ <xmpp:since>0.10</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0160.html"/>
+ <xmpp:version>1.0.1</xmpp:version>
+ <xmpp:since>0.1</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0163.html"/>
+ <xmpp:version>1.2.1</xmpp:version>
+ <xmpp:since>0.5</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0170.html"/>
+ <xmpp:version>1.0</xmpp:version>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0172.html"/>
+ <xmpp:note>via XEP-0163</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0175.html"/>
+ <xmpp:version>1.2</xmpp:version>
+ <xmpp:since>0.4</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0178.html"/>
+ <xmpp:version>1.1</xmpp:version>
+ <xmpp:since>0.9</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0182.html"/>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0185.html"/>
+ <xmpp:version>1.0</xmpp:version>
+ <xmpp:status>complete</xmpp:status>
+ <xmpp:since>0.9.10</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0189.html"/>
+ <xmpp:note>via XEP-0163</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0191.html"/>
+ <xmpp:version>1.3</xmpp:version>
+ <xmpp:status>complete</xmpp:status>
+ <xmpp:since>0.10</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0194.html"/>
+ <xmpp:note>via XEP-0163</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0195.html"/>
+ <xmpp:note>via XEP-0163</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0196.html"/>
+ <xmpp:note>via XEP-0163</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0197.html"/>
+ <xmpp:note>via XEP-0163</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0199.html"/>
+ <xmpp:version>2.0.1</xmpp:version>
+ <xmpp:since>0.1</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0202.html"/>
+ <xmpp:version>2.0</xmpp:version>
+ <xmpp:since>0.1</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0203.html"/>
+ <xmpp:version>2.0</xmpp:version>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0206.html"/>
+ <xmpp:version>1.2</xmpp:version>
+ <xmpp:since>0.2</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0212.html"/>
+ <xmpp:note>required level</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0220.html"/>
+ <xmpp:since>0.1</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0227.html"/>
+ <xmpp:since>0.7</xmpp:since>
+ <xmpp:note>Used in migrator tools</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0237.html"/>
+ <xmpp:since>0.4</xmpp:since>
+ <xmpp:note>implied by rfc6121</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0280.html"/>
+ <xmpp:version>0.12.1</xmpp:version>
+ <xmpp:status>complete</xmpp:status>
+ <xmpp:since>0.10</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0286.html"/>
+ <xmpp:since>0.11</xmpp:since>
+ <xmpp:note>mod_csi_simple</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0288.html"/>
+ <xmpp:version>1.0.1</xmpp:version>
+ <xmpp:status>complete</xmpp:status>
+ <xmpp:since>0.12</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0292.html"/>
+ <xmpp:version>0.10</xmpp:version>
+ <xmpp:status>complete</xmpp:status>
+ <xmpp:since>0.11</xmpp:since>
+ <xmpp:note>mod_vcard4, mod_vcard_legacy</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0302.html"/>
+ <xmpp:note>Core Server</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0313.html"/>
+ <xmpp:version>0.6.3</xmpp:version>
+ <xmpp:since>0.10</xmpp:since>
+ <xmpp:note>mod_mam, mod_muc_mam</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0318.html"/>
+ <xmpp:version>0.2</xmpp:version>
+ <xmpp:since>0.9</xmpp:since>
+ <xmpp:note>refers to inclusion of delay stamp in presence</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0352.html"/>
+ <xmpp:version>0.3.0</xmpp:version>
+ <xmpp:since>0.11</xmpp:since>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0368.html"/>
+ <xmpp:version>1.1.0</xmpp:version>
+ <xmpp:status>partial</xmpp:status>
+ <xmpp:since>0.2</xmpp:since>
+ <xmpp:note>legacy_ssl_ports</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0380.html"/>
+ <xmpp:version>0.3.0</xmpp:version>
+ <xmpp:since>0.11</xmpp:since>
+ <xmpp:note>Used in context of XEP-0352</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0384.html"/>
+ <xmpp:note>via XEP-0163, XEP-0222</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0398.html"/>
+ <xmpp:version>0.2.1</xmpp:version>
+ <xmpp:since>0.11</xmpp:since>
+ <xmpp:status>complete</xmpp:status>
+ <xmpp:note>mod_vcard_legacy</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ <implements>
+ <xmpp:SupportedXep>
+ <xmpp:xep rdf:resource="https://xmpp.org/extensions/xep-0410.html"/>
+ <xmpp:version>1.0.1</xmpp:version>
+ <xmpp:since>0.11</xmpp:since>
+ <xmpp:status>complete</xmpp:status>
+ <xmpp:note>Server Optimization</xmpp:note>
+ </xmpp:SupportedXep>
+ </implements>
+ </Project>
+</rdf:RDF>
diff --git a/doc/net.server.lua b/doc/net.server.lua
index 7342c549..aa9a4a9d 100644
--- a/doc/net.server.lua
+++ b/doc/net.server.lua
@@ -160,6 +160,26 @@ Returns:
local function addserver(address, port, listeners, pattern, sslctx)
end
+--[[ Binds and listens on the given address and port
+Mostly the same as addserver but with all optional arguments in a table
+
+Arguments:
+ - address: address to bind to, may be "*" to bind all addresses. will be resolved if it is a string.
+ - port: port to bind (as number)
+ - listeners: a table of listeners
+ - config: table of extra settings
+ - read_size: the amount of bytes to read or a read pattern
+ - tls_ctx: is a valid luasec constructor
+ - tls_direct: boolean true for direct TLS, false (or nil) for starttls
+
+Returns:
+ - handle
+ - nil, "an error message": on failure (e.g. out of file descriptors)
+]]
+local function listen(address, port, listeners, config)
+end
+
+
--[[ Wraps a lua-socket socket client socket in a handle.
The socket must be already connected to the remote end.
If `sslctx` is given, a SSL session will be negotiated before listeners are called.
@@ -255,4 +275,5 @@ return {
closeall = closeall;
hook_signal = hook_signal;
watchfd = watchfd;
+ listen = listen;
}
diff --git a/doc/storage.tld b/doc/storage.tld
index f1d33e58..057649a4 100644
--- a/doc/storage.tld
+++ b/doc/storage.tld
@@ -47,6 +47,9 @@ interface archive_store
-- Array of dates which do have messages (Optional?)
dates : ( self, string? ) -> ({ string }) | (nil, string)
+
+ -- Map of counts per "with" field
+ summary : ( self, string?, archive_query? ) -> ( { string : integer } ) | (nil, string)
end
-- This represents moduleapi