|
2311
|
1 ---
|
|
|
2 labels:
|
|
|
3 - 'Stage-Beta'
|
|
|
4 summary: Delegate roster management to an external service
|
|
|
5 ...
|
|
2161
|
6
|
|
|
7 NOTE: THIS MODULE IS RELEASED UNDER THE MOZILLA PUBLIC LICENSE VERSION 2.
|
|
|
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
|
|
|
17 Configuring this module
|
|
|
18 -----------------------
|
|
|
19
|
|
|
20 This module relies on `mod_storage_memory` and `mod_block_subscriptions`.
|
|
|
21
|
|
|
22 In `.parts/prosody/etc/prosody/prosody.cfg.lua`, where your particular
|
|
|
23 `VirtualHost` is being configured, add the following:
|
|
|
24
|
|
|
25 modules_enabled = {
|
|
|
26 "http_roster_admin",
|
|
|
27 "block_subscriptions",
|
|
|
28 "storage_memory",
|
|
|
29 "http_files"
|
|
|
30 }
|
|
|
31 modules_disabled = {
|
|
|
32 -- Prosody will get the roster from the backend app,
|
|
|
33 -- so we disable the default roster module.
|
|
|
34 "roster"
|
|
|
35 }
|
|
|
36 storage = { roster = "memory" }
|
|
|
37 http_roster_url = "http://localhost/contacts/%s" -- %s will be replaced by an URL-encoded username
|
|
|
38
|
|
|
39 The `http_roster_url` parameter needs to be configured to point to the
|
|
|
40 URL in the backend application which returns users' contacts rosters.
|
|
|
41
|
|
|
42 In this URL, the pattern `%s` is replaced by an URL-encoded username.
|
|
|
43
|
|
|
44 When the user *john* then connects to Prosody, and `http_roster_url` is
|
|
|
45 set to “http://app.example.org/contacts/%s”, then Prosody will make a
|
|
|
46 GET request to http://app.example.org/contacts/john
|
|
|
47
|
|
|
48 Notifying Prosody of roster changes
|
|
|
49 ***********************************
|
|
|
50
|
|
|
51 The external service needs to notify Prosody whenever a user's roster
|
|
|
52 changes. To do this, it must make an HTTP POST request to either:
|
|
|
53
|
|
|
54 * http://localhost:5280/roster_admin/refresh
|
|
|
55 * https://localhost:5281/roster_admin/refresh
|
|
|
56
|
|
|
57 Make sure that the "http_files" module is enabled in Prosody's configuration,
|
|
|
58 for the above URLs to served.
|
|
|
59
|
|
|
60 Ports 5280/5281 can be firewalled and the web server (i.e. Apache or Nginx)
|
|
|
61 can be configured to reverse proxy those URLs to for example
|
|
|
62 https://example.org/http-bind.
|
|
|
63
|
|
|
64 The contents of the POST should be a JSON encoded array of usernames whose
|
|
|
65 rosters have changed.
|
|
|
66
|
|
|
67 For example, if user ‘john’ became friends with ‘aaron’, both john’s
|
|
|
68 contact list and aaron’s contact lists have changed:
|
|
|
69
|
|
|
70 ```
|
|
|
71 ["john", "aaron"]
|
|
|
72 ```
|
|
|
73
|
|
|
74 When the operation is complete Prosody will reply with a summary of the
|
|
|
75 operation - a JSON object containing:
|
|
|
76
|
|
|
77 * **status**: either “ok” (success) or “error” (operation completely failed)
|
|
|
78 * **message**: A human-readable message (for logging and debugging purposes)
|
|
|
79 * **updated**: The number of rosters successfully updated
|
|
|
80 * **errors**: The number of rosters that failed to update
|
|
|
81
|
|
|
82 Example:
|
|
|
83
|
|
|
84 ```
|
|
|
85 {
|
|
|
86 "status": "ok",
|
|
|
87 "message": "roster update complete",
|
|
|
88 "updated": 2,
|
|
|
89 "errors": 0
|
|
|
90 }
|
|
|
91 ```
|
|
|
92
|
|
|
93 Prosody may also return status codes `400` or `500` in case of errors (such
|
|
|
94 as a missing/malformed body).
|
