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