Mercurial > prosody-modules
annotate mod_http_roster_admin/README.markdown @ 2782:8fd37f0e108c
mod_firewall: Don't interpret format specifiers in LOG
May include untrusted input (e.g. $(stanza)), and there is no
legitimate way to provide additional parameters anyway.
author | Matthew Wild <mwild1@gmail.com> |
---|---|
date | Wed, 04 Oct 2017 10:54:52 +0100 (2017-10-04) |
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). |