Mercurial > prosody-modules

annotate mod_http_roster_admin/README.markdown @ 4154:a2d5834d4a9e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge
author Kim Alvefur <zash@zash.se>
date Sat, 26 Sep 2020 14:45:08 +0200
parents af1b3cef52e1
children
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
3007
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
24 ``` lua
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
25 modules_enabled = {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
26 "http_roster_admin",
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
27 "block_subscriptions",
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
28 "storage_memory",
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
29 "http_files"
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
30 }
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
31 modules_disabled = {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
32 -- Prosody will get the roster from the backend app,
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
33 -- so we disable the default roster module.
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
34 "roster"
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
35 }
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
36 storage = { roster = "memory" }
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
37 http_roster_url = "http://localhost/contacts/%s" -- %s will be replaced by an URL-encoded username
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
38 ```
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
39
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
40 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
41 URL in the backend application which returns users' contacts rosters.
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 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
44
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
45 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
46 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
47 GET request to http://app.example.org/contacts/john
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
48
3006
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
49 ## Protocol
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
50
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
51 ### Fetching rosters (Prosody to web app)
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
52
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
53 Prosody considers the web application to always hold the most accurate and up-to-date
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
54 version of the user's roster. When a user first connects, Prosody fetches the roster
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
55 from the web application and caches it internally.
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
56
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
57 Prosody will make a GET request to the URL specified in Prosody's configuration parameter
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
58 'http_roster_url'. In this URL, the pattern '%s' is replaced by an URL-encoded username.
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
59
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
60 For example, when the user 'john' connects to Prosody, and http_roster_url is set
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
61 to "http://app.example.com/contacts/%s", Prosody will make a GET request to "http://app.example.com/contacts/john".
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
62
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
63 The web app must return a JSON object, where each key is the JID of a contact, and the corresponding
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
64 value is data about that contact.
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
65
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
66 If the user 'john' has friends 'marie' and 'michael', the web app would return a HTTP '200 OK' response
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
67 with the following contents:
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
68
3007
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
69 ``` json
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
70 {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
71 "marie@example.com": {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
72 "name": "Marie"
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
73 },
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
74
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
75 "michael@example.com": {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
76 "name": "Michael"
3006
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
77 }
3007
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
78 }
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
79 ```
3006
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
80
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
81 ### Notifying Prosody of roster changes
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
82
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
83 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
84 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
85
2312
234d679076c4 Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents: 2311
diff changeset
86 - http://localhost:5280/roster_admin/refresh
234d679076c4 Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents: 2311
diff changeset
87 - https://localhost:5281/roster_admin/refresh
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
88
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
89 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
90 for the above URLs to served.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
91
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
92 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
93 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
94 https://example.org/http-bind.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
95
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
96 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
97 rosters have changed.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
98
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
99 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
100 contact list and aaron’s contact lists have changed:
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
101
3007
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
102 ``` json
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
103 ["john", "aaron"]
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
104 ```
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
105
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
106 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
107 operation - a JSON object containing:
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
108
2312
234d679076c4 Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents: 2311
diff changeset
109 - **status**: either “ok” (success) or “error” (operation completely failed)
234d679076c4 Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents: 2311
diff changeset
110 - **message**: A human-readable message (for logging and debugging purposes)
234d679076c4 Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents: 2311
diff changeset
111 - **updated**: The number of rosters successfully updated
234d679076c4 Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents: 2311
diff changeset
112 - **errors**: The number of rosters that failed to update
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
113
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
114 Example:
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
115
3007
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
116 ``` json
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
117 {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
118 "status": "ok",
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
119 "message": "roster update complete",
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
120 "updated": 2,
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
121 "errors": 0
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
122 }
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
123 ```
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
124
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
125 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
126 as a missing/malformed body).