Mercurial > prosody-modules

comparison mod_http_roster_admin/README.markdown @ 2312:234d679076c4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Proper markdown syntax
author JC Brand <jcbrand@minddistrict.com>
date Wed, 28 Sep 2016 15:15:21 +0000
parents 73967121cf5e
children e6f91e00b507
comparison
equal deleted inserted replaced
2311:73967121cf5e 2312:234d679076c4
2 labels: 2 labels:
3 - 'Stage-Beta' 3 - 'Stage-Beta'
4 summary: Delegate roster management to an external service 4 summary: Delegate roster management to an external service
5 ... 5 ...
6 6
7 NOTE: THIS MODULE IS RELEASED UNDER THE MOZILLA PUBLIC LICENSE VERSION 2. 7 *NOTE: THIS MODULE IS RELEASED UNDER THE MOZILLA PUBLIC LICENSE VERSION 2.*
8 8
9 Normally the XMPP server will store and maintain the users' contact 9 Normally the XMPP server will store and maintain the users' contact
10 rosters. This module lets you delegate roster management to an external 10 rosters. This module lets you delegate roster management to an external
11 service. 11 service.
12 12
13 Prosody will make an HTTP request to fetch the roster from the external 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 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. 15 changes, so that Prosody can fetch a new roster for that user.
16 16
17 Configuring this module 17 ## Configuring this module
18 -----------------------
19 18
20 This module relies on `mod_storage_memory` and `mod_block_subscriptions`. 19 This module relies on `mod_storage_memory` and `mod_block_subscriptions`.
21 20
22 In `.parts/prosody/etc/prosody/prosody.cfg.lua`, where your particular 21 In `.parts/prosody/etc/prosody/prosody.cfg.lua`, where your particular
23 `VirtualHost` is being configured, add the following: 22 `VirtualHost` is being configured, add the following:
43 42
44 When the user *john* then connects to Prosody, and `http_roster_url` is 43 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 44 set to “http://app.example.org/contacts/%s”, then Prosody will make a
46 GET request to http://app.example.org/contacts/john 45 GET request to http://app.example.org/contacts/john
47 46
48 Notifying Prosody of roster changes 47 ## Notifying Prosody of roster changes
49 ***********************************
50 48
51 The external service needs to notify Prosody whenever a user's roster 49 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: 50 changes. To do this, it must make an HTTP POST request to either:
53 51
54 * http://localhost:5280/roster_admin/refresh 52 - http://localhost:5280/roster_admin/refresh
55 * https://localhost:5281/roster_admin/refresh 53 - https://localhost:5281/roster_admin/refresh
56 54
57 Make sure that the "http_files" module is enabled in Prosody's configuration, 55 Make sure that the "http_files" module is enabled in Prosody's configuration,
58 for the above URLs to served. 56 for the above URLs to served.
59 57
60 Ports 5280/5281 can be firewalled and the web server (i.e. Apache or Nginx) 58 Ports 5280/5281 can be firewalled and the web server (i.e. Apache or Nginx)
65 rosters have changed. 63 rosters have changed.
66 64
67 For example, if user ‘john’ became friends with ‘aaron’, both john’s 65 For example, if user ‘john’ became friends with ‘aaron’, both john’s
68 contact list and aaron’s contact lists have changed: 66 contact list and aaron’s contact lists have changed:
69 67
70 ```
71 ["john", "aaron"] 68 ["john", "aaron"]
72 ```
73 69
74 When the operation is complete Prosody will reply with a summary of the 70 When the operation is complete Prosody will reply with a summary of the
75 operation - a JSON object containing: 71 operation - a JSON object containing:
76 72
77 * **status**: either “ok” (success) or “error” (operation completely failed) 73 - **status**: either “ok” (success) or “error” (operation completely failed)
78 * **message**: A human-readable message (for logging and debugging purposes) 74 - **message**: A human-readable message (for logging and debugging purposes)
79 * **updated**: The number of rosters successfully updated 75 - **updated**: The number of rosters successfully updated
80 * **errors**: The number of rosters that failed to update 76 - **errors**: The number of rosters that failed to update
81 77
82 Example: 78 Example:
83 79
84 ```
85 { 80 {
86 "status": "ok", 81 "status": "ok",
87 "message": "roster update complete", 82 "message": "roster update complete",
88 "updated": 2, 83 "updated": 2,
89 "errors": 0 84 "errors": 0
90 } 85 }
91 ```
92 86
93 Prosody may also return status codes `400` or `500` in case of errors (such 87 Prosody may also return status codes `400` or `500` in case of errors (such
94 as a missing/malformed body). 88 as a missing/malformed body).