Mercurial > prosody-modules
annotate mod_http_roster_admin/README.markdown @ 2631:2bfa7d476092
mod_http_roster_admin: Don't call callback if it's nil
| author | JC Brand <jc@opkode.com> |
|---|---|
| date | Tue, 21 Mar 2017 09:43:03 +0000 |
| parents | 234d679076c4 |
| children | e6f91e00b507 |
| rev | line source |
|---|---|
| 2311 | 1 --- |
| 2 labels: | |
| 3 - 'Stage-Beta' | |
| 4 summary: Delegate roster management to an external service | |
| 5 ... | |
| 2161 | 6 |
|
2312
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2311
diff
changeset
|
7 *NOTE: THIS MODULE IS RELEASED UNDER THE MOZILLA PUBLIC LICENSE VERSION 2.* |
| 2161 | 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 | |
|
2312
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2311
diff
changeset
|
17 ## Configuring this module |
| 2161 | 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 | |
| 24 modules_enabled = { | |
| 25 "http_roster_admin", | |
| 26 "block_subscriptions", | |
| 27 "storage_memory", | |
| 28 "http_files" | |
| 29 } | |
| 30 modules_disabled = { | |
| 31 -- Prosody will get the roster from the backend app, | |
| 32 -- so we disable the default roster module. | |
| 33 "roster" | |
| 34 } | |
| 35 storage = { roster = "memory" } | |
| 36 http_roster_url = "http://localhost/contacts/%s" -- %s will be replaced by an URL-encoded username | |
| 37 | |
| 38 The `http_roster_url` parameter needs to be configured to point to the | |
| 39 URL in the backend application which returns users' contacts rosters. | |
| 40 | |
| 41 In this URL, the pattern `%s` is replaced by an URL-encoded username. | |
| 42 | |
| 43 When the user *john* then connects to Prosody, and `http_roster_url` is | |
| 44 set to “http://app.example.org/contacts/%s”, then Prosody will make a | |
| 45 GET request to http://app.example.org/contacts/john | |
| 46 | |
|
2312
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2311
diff
changeset
|
47 ## Notifying Prosody of roster changes |
| 2161 | 48 |
| 49 The external service needs to notify Prosody whenever a user's roster | |
| 50 changes. To do this, it must make an HTTP POST request to either: | |
| 51 | |
|
2312
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2311
diff
changeset
|
52 - http://localhost:5280/roster_admin/refresh |
|
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2311
diff
changeset
|
53 - https://localhost:5281/roster_admin/refresh |
| 2161 | 54 |
| 55 Make sure that the "http_files" module is enabled in Prosody's configuration, | |
| 56 for the above URLs to served. | |
| 57 | |
| 58 Ports 5280/5281 can be firewalled and the web server (i.e. Apache or Nginx) | |
| 59 can be configured to reverse proxy those URLs to for example | |
| 60 https://example.org/http-bind. | |
| 61 | |
| 62 The contents of the POST should be a JSON encoded array of usernames whose | |
| 63 rosters have changed. | |
| 64 | |
| 65 For example, if user ‘john’ became friends with ‘aaron’, both john’s | |
| 66 contact list and aaron’s contact lists have changed: | |
| 67 | |
| 68 ["john", "aaron"] | |
| 69 | |
| 70 When the operation is complete Prosody will reply with a summary of the | |
| 71 operation - a JSON object containing: | |
| 72 | |
|
2312
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2311
diff
changeset
|
73 - **status**: either “ok” (success) or “error” (operation completely failed) |
|
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2311
diff
changeset
|
74 - **message**: A human-readable message (for logging and debugging purposes) |
|
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2311
diff
changeset
|
75 - **updated**: The number of rosters successfully updated |
|
234d679076c4
Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents:
2311
diff
changeset
|
76 - **errors**: The number of rosters that failed to update |
| 2161 | 77 |
| 78 Example: | |
| 79 | |
| 80 { | |
| 81 "status": "ok", | |
| 82 "message": "roster update complete", | |
| 83 "updated": 2, | |
| 84 "errors": 0 | |
| 85 } | |
| 86 | |
| 87 Prosody may also return status codes `400` or `500` in case of errors (such | |
| 88 as a missing/malformed body). |