Software /
code /
prosody-modules
Annotate
mod_server_info/README.md @ 5925:9ed02a4f6ff4
mod_invites_tracking: Don't bother storing anything for non-invite IBR
author | Matthew Wild <mwild1@gmail.com> |
---|---|
date | Wed, 08 May 2024 12:48:41 +0100 |
parent | 5866:ed82916e5796 |
rev | line source |
---|---|
5817
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 |
5866
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
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:
5817
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:
5817
diff
changeset
|
19 |
5817
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 |
5866
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
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:
5817
diff
changeset
|
23 in the server info form. |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
diff
changeset
|
24 |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
diff
changeset
|
25 A field has three required properties: |
5817
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` |
5866
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
diff
changeset
|
28 - `var` - the field name (see below) |
5817
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 = { |
5866
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
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:
5817
diff
changeset
|
36 { type = "text-single", var = "speed", value = "88" }; |
5817
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
37 |
5866
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
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:
5817
diff
changeset
|
39 { type = "text-single", var = "time", value = "01:21:00" }; |
5817
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 |
5866
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
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:
5817
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:
5817
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:
5817
diff
changeset
|
46 collisions. |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
diff
changeset
|
47 |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
diff
changeset
|
48 ## Developers |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
diff
changeset
|
49 |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
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:
5817
diff
changeset
|
51 |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
diff
changeset
|
52 ```lua |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
diff
changeset
|
53 module:depends("server_info"); |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
diff
changeset
|
54 |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
diff
changeset
|
55 module:add_item("server-info-fields", { |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
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:
5817
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:
5817
diff
changeset
|
58 }); |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
diff
changeset
|
59 ``` |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
diff
changeset
|
60 |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
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:
5817
diff
changeset
|
62 |
5817
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 |
5866
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5817
diff
changeset
|
65 This module should be compatible with Prosody 0.12 and later. |