Mercurial > prosody-modules

comparison mod_http_roster_admin/README @ 2161:95a9f2d234da

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add mod_http_roster_admin
author JC Brand <jc@opkode.com>
date Fri, 15 Apr 2016 16:59:27 +0000
parents
children
comparison
equal deleted inserted replaced
2160:394a62163a91 2161:95a9f2d234da
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).