mod_server_info/README.md
author Matthew Wild <mwild1@gmail.com>
Fri, 23 Feb 2024 22:47:05 +0000
changeset 5846 ed82916e5796
parent 5798 174c77da03f5
permissions -rw-r--r--
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
5798
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
5846
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
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: 5798
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: 5798
diff changeset
    19
5798
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
5846
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
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: 5798
diff changeset
    23
in the server info form.
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
diff changeset
    24
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
diff changeset
    25
A field has three required properties:
5798
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`
5846
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
diff changeset
    28
- `var` - the field name (see below)
5798
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 = {
5846
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
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: 5798
diff changeset
    36
	{ type = "text-single", var = "speed", value = "88" };
5798
174c77da03f5 mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
    37
5846
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
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: 5798
diff changeset
    39
	{ type = "text-single", var = "time", value = "01:21:00" };
5798
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
5846
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
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: 5798
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: 5798
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: 5798
diff changeset
    46
collisions.
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
diff changeset
    47
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
diff changeset
    48
## Developers
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
diff changeset
    49
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
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: 5798
diff changeset
    51
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
diff changeset
    52
```lua
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
diff changeset
    53
module:depends("server_info");
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
diff changeset
    54
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
diff changeset
    55
module:add_item("server-info-fields", {
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
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: 5798
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: 5798
diff changeset
    58
});
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
diff changeset
    59
```
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
diff changeset
    60
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
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: 5798
diff changeset
    62
5798
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
5846
ed82916e5796 mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents: 5798
diff changeset
    65
This module should be compatible with Prosody 0.12 and later.