Mercurial > prosody-modules

annotate mod_server_info/README.md @ 5853:97c9b76867ca

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_log_ringbuffer: Detach event handlers on logging reload (thanks Menel) Otherwise the global event handlers accumulate, one added each time logging is reoladed, and each invocation of the signal or event triggers one dump of each created ringbuffer.
author Kim Alvefur <zash@zash.se>
date Sun, 03 Mar 2024 11:23:40 +0100
parents ed82916e5796
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5794
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels:
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 - 'Stage-Alpha'
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 summary: Manually configure extended service discovery info
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5 ...
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 XEP-0128 defines a way for servers to provide custom information via service
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8 discovery. Various XEPs and plugins make use of this functionality, so that
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9 e.g. clients can look up necessary information.
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
11 This module allows the admin to manually configure service discovery
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
12 extensions in the config file. It may be useful as a way to advertise certain
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
13 information.
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
14
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
15 Everything configured here is publicly visible to other XMPP entities.
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16
5842
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
17 **Note:** This module was rewritten in February 2024, the configuration is not
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
18 compatible with the previous version of the module.
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
19
5794
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20 ## Configuration
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21
5842
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
22 The `server_info_extensions` option accepts a list of custom fields to include
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
23 in the server info form.
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
24
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
25 A field has three required properties:
5794
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27 - `type` - usually `text-single` or `list-multi`
5842
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
28 - `var` - the field name (see below)
5794
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29 - `value` the field value
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31 Example configuration:
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33 ``` lua
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34 server_info = {
5842
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
35 -- Advertise that our maximum speed is 88 mph
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
36 { type = "text-single", var = "speed", value = "88" };
5794
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37
5842
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
38 -- Advertise that the time is 1:20 AM and zero seconds
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
39 { type = "text-single", var = "time", value = "01:21:00" };
5794
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40 }
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41 ```
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42
5842
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
43 The `var` attribute is used to uniquely identify fields. Every `var` should be
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
44 registered with the XSF [form registry](https://xmpp.org/registrar/formtypes.html#http:--jabber.org-network-serverinfo),
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
45 or prefixed with a custom namespace using Clark notation, e.g. `{https://example.com}my-field-name`. This is to prevent
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
46 collisions.
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
47
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
48 ## Developers
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
49
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
50 Developers of other modules can add fields to the form at runtime:
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
51
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
52 ```lua
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
53 module:depends("server_info");
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
54
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
55 module:add_item("server-info-fields", {
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
56 { type = "text-single", var = "speed", value = "88" };
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
57 { type = "text-single", var = "time", value = "01:21:00" };
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
58 });
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
59 ```
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
60
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
61 Prosody will ensure they are removed if your module is unloaded.
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
62
5794
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63 ## Compatibility
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64
5842
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5794
diff changeset
65 This module should be compatible with Prosody 0.12 and later.