Software / code / prosody-modules
Annotate
mod_client_proxy/README.markdown @ 4876:0f5f2d4475b9
mod_http_xep227: Add support for import via APIs rather than direct store manipulation
In particular this transitions PEP nodes and data to be imported via mod_pep's
APIs, fixing issues with importing at runtime while PEP data may already be
live in RAM.
Next obvious candidate for this approach is rosters, so clients get immediate
roster pushes and other special handling (such as emitting subscribes to reach
the desired subscription state).
| author | Matthew Wild <mwild1@gmail.com> |
|---|---|
| date | Tue, 18 Jan 2022 17:01:18 +0000 |
| parent | 4318:3dd7840cb923 |
| rev | line source |
|---|---|
|
3098
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
1 --- |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
2 labels: |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
3 - 'Stage-Alpha' |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
4 summary: 'Proxy multiple client resources behind a single component' |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
5 ... |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
6 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
7 What it does |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
8 ============ |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
9 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
10 This module must be used as a component. For example: |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
11 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
12 Component "proxy.domain.example" "client_proxy" |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
13 target_address = "some-user@some-domain.example" |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
14 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
15 All IQ requests against the proxy host (in the above example: |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
16 proxy.domain.example) are sent to a random resource of the target address (in |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
17 the above example: some-user@some-domain.example). The entity behind the |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
18 target address is called the "implementing client". |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
19 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
20 The IQ requests are JAT-ed (JAT: Jabber Address Translation) so that when the |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
21 implementing client answers the IQ request, it is sent back to the component, |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
22 which reverts the translation and routes the reply back to the user. |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
23 |
|
4318
3dd7840cb923
mod_client_proxy: Fix typo in readme
Jonas Schäfer <jonas@wielicki.name>
parents:
3102
diff
changeset
|
24 Let us assume that user@some-domain.example sends a request. The |
|
3098
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
25 proxy.domain.example component has the client_proxy module loaded and proxies to |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
26 some-user@some-domain.example. some-user@some-domain.example has two resources, |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
27 /a and /b. |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
28 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
29 user -> component: |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
30 <iq type='get' id='1234' to='proxy.domain.example' from='user@some-domain.example/abc'> |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
31 component -> implementing client: |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
32 <iq type='get' id='1234' to='some-user@some-domain.example/a' from='proxy.domain.example/encoded-from'> |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
33 implementing client -> component: |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
34 <iq type='result' id='1234' to='proxy.domain.example/encoded-from' from='some-user@some-domain.example/a'> |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
35 component -> user: |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
36 <iq type='result' id='1234' to='user@some-domain.example/abc' from='proxy.domain.example'> |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
37 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
38 The encoded-from resource used in the exchange between the proxy component |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
39 and the implementing client is an implementation-defined string which allows |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
40 the proxy component to revert the JAT. |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
41 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
42 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
43 Use cases |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
44 ========= |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
45 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
46 * Implementation of services within clients instead of components, thus making |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
47 use of the more advanced authentication features. |
|
3102
f04dbfad5407
mod_client_proxy: extend readme
Jonas Wielicki <jonas@wielicki.name>
parents:
3098
diff
changeset
|
48 * Load-balancing requests to different client resources. |
|
3098
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
49 * General evilness |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
50 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
51 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
52 Configuration |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
53 ============= |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
54 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
55 To use this module, it needs to be loaded on a component: |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
56 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
57 Component "proxy.yourdomain.example" "client_proxy" |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
58 target_address = "implementation@yourdomain.example" |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
59 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
60 It will then send a subscription request to implementation@yourdomain.example |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
61 which MUST be accepted: this is required so that the component can detect the |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
62 resources to which IQ requests can be dispatched. |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
63 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
64 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
65 Limitations |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
66 =========== |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
67 |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
68 * It does not handle presence or message stanzas. |
|
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
69 * It does not allow the implementing client to initiate IQ requests |
