author | Kim Alvefur <zash@zash.se> |
Sat, 27 Aug 2022 15:39:38 +0200 | |
changeset 5020 | 964de9997552 |
parent 3011 | af1b3cef52e1 |
permissions | -rw-r--r-- |
2315 | 1 |
--- |
2 |
labels: |
|
3 |
- 'Stage-Beta' |
|
4 |
summary: Delegate roster management to an external service |
|
5 |
... |
|
2165 | 6 |
|
2316
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2315
diff
changeset
|
7 |
*NOTE: THIS MODULE IS RELEASED UNDER THE MOZILLA PUBLIC LICENSE VERSION 2.* |
2165 | 8 |
|
9 |
Normally the XMPP server will store and maintain the users' contact |
|
10 |
rosters. This module lets you delegate roster management to an external |
|
11 |
service. |
|
12 |
||
13 |
Prosody will make an HTTP request to fetch the roster from the external |
|
14 |
service. The service will need to notify Prosody whenever a user's roster |
|
15 |
changes, so that Prosody can fetch a new roster for that user. |
|
16 |
||
2316
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2315
diff
changeset
|
17 |
## Configuring this module |
2165 | 18 |
|
19 |
This module relies on `mod_storage_memory` and `mod_block_subscriptions`. |
|
20 |
||
21 |
In `.parts/prosody/etc/prosody/prosody.cfg.lua`, where your particular |
|
22 |
`VirtualHost` is being configured, add the following: |
|
23 |
||
3011
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
24 |
``` lua |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
25 |
modules_enabled = { |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
26 |
"http_roster_admin", |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
27 |
"block_subscriptions", |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
28 |
"storage_memory", |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
29 |
"http_files" |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
30 |
} |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
31 |
modules_disabled = { |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
32 |
-- Prosody will get the roster from the backend app, |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
33 |
-- so we disable the default roster module. |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
34 |
"roster" |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
35 |
} |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
36 |
storage = { roster = "memory" } |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
37 |
http_roster_url = "http://localhost/contacts/%s" -- %s will be replaced by an URL-encoded username |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
38 |
``` |
2165 | 39 |
|
40 |
The `http_roster_url` parameter needs to be configured to point to the |
|
41 |
URL in the backend application which returns users' contacts rosters. |
|
42 |
||
43 |
In this URL, the pattern `%s` is replaced by an URL-encoded username. |
|
44 |
||
45 |
When the user *john* then connects to Prosody, and `http_roster_url` is |
|
46 |
set to “http://app.example.org/contacts/%s”, then Prosody will make a |
|
47 |
GET request to http://app.example.org/contacts/john |
|
48 |
||
3010
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
49 |
## Protocol |
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
50 |
|
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
51 |
### Fetching rosters (Prosody to web app) |
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
52 |
|
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
53 |
Prosody considers the web application to always hold the most accurate and up-to-date |
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
54 |
version of the user's roster. When a user first connects, Prosody fetches the roster |
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
55 |
from the web application and caches it internally. |
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
56 |
|
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
57 |
Prosody will make a GET request to the URL specified in Prosody's configuration parameter |
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
58 |
'http_roster_url'. In this URL, the pattern '%s' is replaced by an URL-encoded username. |
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
59 |
|
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
60 |
For example, when the user 'john' connects to Prosody, and http_roster_url is set |
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
61 |
to "http://app.example.com/contacts/%s", Prosody will make a GET request to "http://app.example.com/contacts/john". |
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
62 |
|
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
63 |
The web app must return a JSON object, where each key is the JID of a contact, and the corresponding |
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
64 |
value is data about that contact. |
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
65 |
|
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
66 |
If the user 'john' has friends 'marie' and 'michael', the web app would return a HTTP '200 OK' response |
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
67 |
with the following contents: |
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
68 |
|
3011
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
69 |
``` json |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
70 |
{ |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
71 |
"marie@example.com": { |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
72 |
"name": "Marie" |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
73 |
}, |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
74 |
|
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
75 |
"michael@example.com": { |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
76 |
"name": "Michael" |
3010
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
77 |
} |
3011
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
78 |
} |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
79 |
``` |
3010
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
80 |
|
e6f91e00b507
mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents:
2316
diff
changeset
|
81 |
### Notifying Prosody of roster changes |
2165 | 82 |
|
83 |
The external service needs to notify Prosody whenever a user's roster |
|
84 |
changes. To do this, it must make an HTTP POST request to either: |
|
85 |
||
2316
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2315
diff
changeset
|
86 |
- http://localhost:5280/roster_admin/refresh |
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2315
diff
changeset
|
87 |
- https://localhost:5281/roster_admin/refresh |
2165 | 88 |
|
89 |
Make sure that the "http_files" module is enabled in Prosody's configuration, |
|
90 |
for the above URLs to served. |
|
91 |
||
92 |
Ports 5280/5281 can be firewalled and the web server (i.e. Apache or Nginx) |
|
93 |
can be configured to reverse proxy those URLs to for example |
|
94 |
https://example.org/http-bind. |
|
95 |
||
96 |
The contents of the POST should be a JSON encoded array of usernames whose |
|
97 |
rosters have changed. |
|
98 |
||
99 |
For example, if user ‘john’ became friends with ‘aaron’, both john’s |
|
100 |
contact list and aaron’s contact lists have changed: |
|
101 |
||
3011
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
102 |
``` json |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
103 |
["john", "aaron"] |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
104 |
``` |
2165 | 105 |
|
106 |
When the operation is complete Prosody will reply with a summary of the |
|
107 |
operation - a JSON object containing: |
|
108 |
||
2316
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2315
diff
changeset
|
109 |
- **status**: either “ok” (success) or “error” (operation completely failed) |
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2315
diff
changeset
|
110 |
- **message**: A human-readable message (for logging and debugging purposes) |
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2315
diff
changeset
|
111 |
- **updated**: The number of rosters successfully updated |
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2315
diff
changeset
|
112 |
- **errors**: The number of rosters that failed to update |
2165 | 113 |
|
114 |
Example: |
|
115 |
||
3011
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
116 |
``` json |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
117 |
{ |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
118 |
"status": "ok", |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
119 |
"message": "roster update complete", |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
120 |
"updated": 2, |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
121 |
"errors": 0 |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
122 |
} |
af1b3cef52e1
mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents:
3010
diff
changeset
|
123 |
``` |
2165 | 124 |
|
125 |
Prosody may also return status codes `400` or `500` in case of errors (such |
|
126 |
as a missing/malformed body). |