Mercurial > prosody-modules

annotate mod_http_roster_admin/README.markdown @ 2608:362ca94192ee

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_smacks: Add resumed session to event "smacks-hibernation-end" Older versions of this event only have the "intermediate" session in event.session (the one used to resume the existing session), but not the resumed one. This adds event.resumed which contains the resumed one alongside to event.session.
author tmolitor <thilo@eightysoft.de>
date Sat, 11 Mar 2017 01:37:28 +0100
parents 234d679076c4
children e6f91e00b507
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2311
73967121cf5e Add labels
JC Brand <jcbrand@minddistrict.com>
parents: 2310
diff changeset
1 ---
73967121cf5e Add labels
JC Brand <jcbrand@minddistrict.com>
parents: 2310
diff changeset
2 labels:
73967121cf5e Add labels
JC Brand <jcbrand@minddistrict.com>
parents: 2310
diff changeset
3 - 'Stage-Beta'
73967121cf5e Add labels
JC Brand <jcbrand@minddistrict.com>
parents: 2310
diff changeset
4 summary: Delegate roster management to an external service
73967121cf5e Add labels
JC Brand <jcbrand@minddistrict.com>
parents: 2310
diff changeset
5 ...
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
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
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
8
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
9 Normally the XMPP server will store and maintain the users' contact
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
10 rosters. This module lets you delegate roster management to an external
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
11 service.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
12
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
13 Prosody will make an HTTP request to fetch the roster from the external
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
14 service. The service will need to notify Prosody whenever a user's roster
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
15 changes, so that Prosody can fetch a new roster for that user.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
16
2312
234d679076c4 Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents: 2311
diff changeset
17 ## Configuring this module
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
18
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
19 This module relies on `mod_storage_memory` and `mod_block_subscriptions`.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
20
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
21 In `.parts/prosody/etc/prosody/prosody.cfg.lua`, where your particular
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
22 `VirtualHost` is being configured, add the following:
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
23
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
24 modules_enabled = {
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
25 "http_roster_admin",
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
26 "block_subscriptions",
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
27 "storage_memory",
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
28 "http_files"
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
29 }
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
30 modules_disabled = {
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
31 -- Prosody will get the roster from the backend app,
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
32 -- so we disable the default roster module.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
33 "roster"
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
34 }
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
35 storage = { roster = "memory" }
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
36 http_roster_url = "http://localhost/contacts/%s" -- %s will be replaced by an URL-encoded username
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
37
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
38 The `http_roster_url` parameter needs to be configured to point to the
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
39 URL in the backend application which returns users' contacts rosters.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
40
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
41 In this URL, the pattern `%s` is replaced by an URL-encoded username.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
42
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
43 When the user *john* then connects to Prosody, and `http_roster_url` is
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
44 set to “http://app.example.org/contacts/%s”, then Prosody will make a
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
45 GET request to http://app.example.org/contacts/john
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
46
2312
234d679076c4 Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents: 2311
diff changeset
47 ## Notifying Prosody of roster changes
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
48
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
49 The external service needs to notify Prosody whenever a user's roster
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
50 changes. To do this, it must make an HTTP POST request to either:
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
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
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
54
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
55 Make sure that the "http_files" module is enabled in Prosody's configuration,
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
56 for the above URLs to served.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
57
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
58 Ports 5280/5281 can be firewalled and the web server (i.e. Apache or Nginx)
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
59 can be configured to reverse proxy those URLs to for example
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
60 https://example.org/http-bind.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
61
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
62 The contents of the POST should be a JSON encoded array of usernames whose
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
63 rosters have changed.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
64
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
65 For example, if user ‘john’ became friends with ‘aaron’, both john’s
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
66 contact list and aaron’s contact lists have changed:
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
67
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
68 ["john", "aaron"]
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
69
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
70 When the operation is complete Prosody will reply with a summary of the
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
71 operation - a JSON object containing:
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
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
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
77
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
78 Example:
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
79
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
80 {
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
81 "status": "ok",
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
82 "message": "roster update complete",
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
83 "updated": 2,
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
84 "errors": 0
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
85 }
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
86
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
87 Prosody may also return status codes `400` or `500` in case of errors (such
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
88 as a missing/malformed body).