Mercurial > libervia-backend
annotate doc/components.rst @ 4294:a0ed5c976bf8 default tip @
component conferences, plugin XEP-0167, XEP-0298: add stream user metadata:
A/V conference now adds user metadata about the stream it is forwarding through XEP-0298.
This is parsed and added to metadata during confirmation on client side.
rel 448
author | Goffi <goffi@goffi.org> |
---|---|
date | Tue, 06 Aug 2024 23:43:11 +0200 |
parents | 6276242736c3 |
children |
rev | line source |
---|---|
3678 | 1 .. _components: |
2 | |
3 =================== | |
4 Libervia Components | |
5 =================== | |
6 | |
7 Libervia can act as an XMPP server component, which can be seen as a generic plugin for | |
8 XMPP servers. | |
9 | |
10 This page explains which components are available and how to use them. | |
11 | |
12 Running a component | |
13 =================== | |
14 | |
15 Components are linked to a Libervia profile in the same way as normal clients. | |
16 | |
17 To run a component, you'll need to know its *entry point*, which is the name of the import | |
18 name of plugin managing it. The entry point to use will be specified in the component | |
19 installation documentation. | |
20 | |
21 You'll also have to declare the component on your XMPP server, this is a server dependent | |
22 step and you'll have to check your server documentation for details. You'll have to | |
23 specify a **shared secret** (can also be named simply *password*) that must be set both on | |
24 the XMPP server and as the XMPP password of the Libervia profile. | |
25 | |
26 Here is a list of relevant documentation for most common servers: | |
27 | |
28 ejabberd | |
29 https://docs.ejabberd.im/admin/configuration/listen-options/ | |
30 | |
31 MongooseIm | |
32 https://esl.github.io/MongooseDocs/latest/configuration/listen/#xmpp-components-listenservice | |
33 | |
34 OpenFire | |
35 use the web-based admin panel | |
36 | |
37 Prosody | |
38 https://prosody.im/doc/components | |
39 | |
40 Tigase | |
41 https://docs.tigase.net/tigase-server/stable-snapshot/Administration_Guide/webhelp/externalComponentConfiguration.html | |
42 | |
43 | |
44 On Libervia, setup is done with Libervia CLI's :ref:`profile create <li_profile_create>` | |
45 command. | |
46 | |
47 You'll usually want to have the component to start automatically when the backend | |
48 is started, for this you must unset the profile password (not to be confused with the XMPP | |
49 password which is the one also set on the server configuration) with ``-p ""`` and set | |
50 auto-connection with ``-A``. | |
51 | |
52 You'll specify the XMPP password (also named *shared secret* in `XEP-0144`_ terminology) | |
53 with ``-x <your_shared_secret>`` and the JID to use with ``-j | |
54 <component_subdomain>.<server.tld>``. | |
55 | |
56 The component entry point is specified with ``-C <entry_point>``. | |
57 | |
58 .. _XEP-0144: https://xmpp.org/extensions/xep-0114.html | |
59 | |
60 example | |
61 ------- | |
62 | |
63 Louise wants to run an ActivityPub gateway on her server ``example.org`` with the JID | |
64 ``ap.example.org``. The shared secret is ``xmpp_rocks`` and she wants the component to | |
65 start automatically with the backend, thus she doesn't set a profile password. The | |
66 entry-point for ActivityPub component is ``ap-gateway``, and she wants to use the same | |
67 name for the profile. To do this, she enters the following command:: | |
68 | |
69 $ li profile create ap-gateway -j ap.example.org -p "" -x xmpp_rocks -C ap-gateway -A | |
70 | |
71 The component will then be started next time Libervia Backend is launched. If Louise | |
72 wants to connect it immediately, she can use:: | |
73 | |
74 $ li profile connect -cp ap-gateway | |
75 | |
76 Available Components | |
77 ==================== | |
78 | |
79 Below is a list of currently available components in Libervia, and instructions on what | |
80 they do and how to use them. | |
81 | |
82 | |
83 File Sharing | |
84 ------------ | |
85 | |
86 **entry_point:** ``file-sharing`` | |
87 | |
88 File Sharing component manage the hosting of user files. Users can upload file there using | |
89 either `Jingle File Transfer`_ or `HTTP File Upload`_. | |
90 | |
91 There is no limit to the size of files which can be uploaded, but administrators can set a | |
92 quota to limit the space that can be used. | |
93 | |
94 Files can be retrieved using `File Information Sharing`_, and deleted using `Ad-Hoc Commands`_. | |
95 | |
96 Files can be shared with a public HTTP link, or made available only to a specified list of | |
97 entities (JIDs). Permissions can be set through Ad-Hoc Commands. | |
98 | |
99 .. _Jingle File Transfer: https://xmpp.org/extensions/ | |
100 .. _HTTP File Upload: https://xmpp.org/extensions/xep-0363.html | |
101 .. _File Information Sharing: https://xmpp.org/extensions/xep-0329.html | |
102 .. _Ad-Hoc Commands: https://xmpp.org/extensions/xep-0050.html | |
103 | |
104 Configuration | |
105 ~~~~~~~~~~~~~ | |
106 | |
107 All options are to be set in ``[component file-sharing]`` section. | |
108 | |
109 ``http_upload_port`` | |
110 port to use for HTTP File Upload | |
111 | |
112 **default**: 8888 | |
113 | |
114 ``http_upload_connection_type`` | |
115 either ``http`` or ``https``. | |
116 | |
117 **default**: ``https`` | |
118 | |
119 Note that HTTP Upload should always be ``https`` to end-user, the ``http`` option is to | |
120 be used only if you use a HTTP server as a proxy, and this server is already set for | |
121 TLS. | |
122 | |
123 ``http_upload_public_facing_url`` | |
124 must be set to the URL that end-user will see. Notably useful if the component is behind | |
125 a proxy. | |
126 | |
127 **default**: ``https://<component host>:<http_upload_port`` | |
128 | |
129 ``quotas_json`` | |
130 a JSON object indicating quotas to use for users. The object can have 3 keys: | |
131 | |
132 ``admins`` | |
133 quotas to use for administrators (i.e. profiles set in ``admins_list``) | |
134 | |
135 ``users`` | |
136 quotas to use for normal users (i.e. non admin profiles) | |
137 | |
138 ``jids`` | |
139 per-jid specific quotas. The value is a JSON object where key is a user bare jid and | |
140 value is a quota. | |
141 | |
142 Quotas can be either ``null`` for unlimited space, or a size value (`SI prefixes and | |
143 binary prefixes`_ can be used). | |
144 | |
145 example:: | |
146 | |
147 quotas_json = { | |
148 "admins": null, | |
149 "users": "50 Mio", | |
150 "jids": {"pierre@example.org": "1 Gio"} | |
151 } | |
152 | |
153 .. _SI prefixes and binary prefixes: https://en.wikipedia.org/wiki/Octet_(computing)#Unit_multiples | |
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
154 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
155 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
156 ActivityPub Gateway |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
157 ------------------- |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
158 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
159 **entry_point:** ``ap-gateway`` |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
160 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
161 This gateway will provide a bidirectional gateway between XMPP and `ActivityPub`_ (or AP |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
162 below). That means that user from XMPP will be able to follow actors or comments messages |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
163 from any software compatible with ActivityPub protocol, and vice versa. |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
164 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
165 .. _ActivityPub: https://activitypub.rocks/ |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
166 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
167 .. note:: |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
168 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
169 this component is mostly tested with Prosody as XMPP server reference, and Mastodon as |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
170 AP server reference, but it should work with any XMPP or AP server. |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
171 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
172 The component launches a HTTP server (necessary to communicate with AP software). This |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
173 server needs to handle HTTP requests made at paths ``/.well-known/webfinger`` and ``/_ap`` |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
174 (or the ``ap_path`` set in configuration, see below). If the component is not directly |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
175 facing internet (e.g. integrated in an existing website though a proxy), you'll have to |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
176 redirect the requests made to those path to the HTTP server (i.e. to component host at the |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
177 port set at ``http_port``, see configuration below). Please check your HTTP server |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
178 documentation to find how this must be done. |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
179 |
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
180 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
181 Configuration |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
182 ~~~~~~~~~~~~~ |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
183 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
184 All options are to be set in ``[component ap-gateway]`` section. |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
185 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
186 ``public_url`` |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
187 Main user-facing domain of the HTTP server, this will be used to construct all AP URLs |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
188 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
189 **default**: if not set, ``xmpp_domain`` is used. If ``xmpp_domain`` is not set either, |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
190 an error is raised. |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
191 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
192 ``http_port`` |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
193 port where the HTTP server should listen. Port ``80`` is not used directly as it would |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
194 require root privileges, and it is strongly recommended against launching Libervia under |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
195 a privileged account. An HTTP Proxy or a port redirection should be set to redirect the |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
196 ``80`` port to the port specified here. |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
197 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
198 **default**: ``8123`` |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
199 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
200 ``http_connection_type`` |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
201 either ``http`` or ``https``. If you have a HTTP proxy such as Apache or NGINX which |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
202 already handles HTTPS, you may want to use ``http``. |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
203 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
204 **default**: ``https`` |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
205 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
206 Note that the HTTP server should always use ``https`` with end-user, the ``http`` option |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
207 is only to be used with an HTTPS proxy. |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
208 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
209 ``local_only`` |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
210 A boolean value indicating if the gateway is allowed to convert pubsub node from |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
211 external XMPP service or not. A JID is considered external if its domain part doesn't |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
212 end with the gateway's server. For instance, if a gateway ``ap.example.org`` is set on |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
213 the server ``example.org``, the JIDs ``pierre@example.org`` or |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
214 ``some-node@pubsub.example.org`` will be considered local, but |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
215 ``buenaventura@example.net`` won't (note the different domain). |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
216 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
217 Most of time, ``local_only`` should be used. |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
218 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
219 **default**: ``true`` |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
220 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
221 ``ap_path`` |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
222 Path prefix to use for ActivityPub request. It's usually not necessary to change the |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
223 default value. |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
224 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
225 **default**: ``_ap`` |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
226 |
3746
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
227 ``comments_max_depth`` |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
228 An integer value indicating the maximum number of comment nodes that can be created. See |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
229 :ref:`ap-xmpp-threads-conversion` |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
230 |
3838 | 231 ``auto_mentions`` |
232 A boolean value indicating if received XMPP pubsub blog items bodies must be scanned to | |
233 find ``@user@server.tld`` type mentions. If mentions are found, they'll be added to the | |
234 resulting AP items. | |
235 | |
236 **default**: ``true`` | |
237 | |
4260
57ff857bf96e
doc (components/AP Gateway): document new `http_sign_get` configuration option.
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
238 ``http_sign_get`` |
57ff857bf96e
doc (components/AP Gateway): document new `http_sign_get` configuration option.
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
239 A boolean value indicating if HTTP ``GET`` request made to AP implementations must be |
57ff857bf96e
doc (components/AP Gateway): document new `http_sign_get` configuration option.
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
240 signed. Some AP implementations require those requests to be signed, notably Mastodon |
57ff857bf96e
doc (components/AP Gateway): document new `http_sign_get` configuration option.
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
241 when "secure mode" is activated. |
57ff857bf96e
doc (components/AP Gateway): document new `http_sign_get` configuration option.
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
242 |
57ff857bf96e
doc (components/AP Gateway): document new `http_sign_get` configuration option.
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
243 **default**: ``true`` |
57ff857bf96e
doc (components/AP Gateway): document new `http_sign_get` configuration option.
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
244 |
3978
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
245 ``html_redirect_dict`` |
3984 | 246 A dictionary used to redirect HTTP requests when it's not an ActivityPub request (i.e. |
3978
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
247 when the ``Accept`` header is not set to ``application/json``). Several ActivityPub |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
248 implementations link to original server when clicking on some links such as post author |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
249 or item ID, and this result in a request to the corresponding ActivityPub endpoint, but |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
250 made to retrieve HTML instead of ActivityPub JSON data. |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
251 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
252 By default, this request is showing the corresponding AP JSON data, but if you set HTML |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
253 redirection, you can redirect the page to your XMPP client web frontend (or anything |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
254 making sense), which results in better user experience. |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
255 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
256 The expected dictionary is a mapping URL request types to destination URL. |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
257 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
258 The URL request types is the first path element after ``ap_path``, it can be: |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
259 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
260 ``actor`` |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
261 Actor information. It should link to the profile page of the corresponding XMPP entity |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
262 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
263 ``item`` |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
264 A specific publication. It should link to the rendered item |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
265 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
266 ``followers`` |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
267 Entities publicly subscribed to the actor. It is usually not used for redirection. |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
268 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
269 ``following`` |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
270 Entities that the actor is publicly subscribed to. It is usually not used for |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
271 redirection. |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
272 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
273 In the target URL you can uses template values in curly braces (something like |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
274 ``{item}``). The values that you can use are: |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
275 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
276 ``jid`` |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
277 Full JID corresponding to the AP actor. |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
278 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
279 ``jid_user`` |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
280 Only the user part of the JID (what is before the ``@``) |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
281 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
282 ``node`` |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
283 Name of the pubsub node corresponding to the AP actor. |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
284 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
285 ``item`` |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
286 ID of the XMPP pubsub item. |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
287 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
288 You can use a slash ``/`` followed by a part of a node name to filter only on specific |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
289 nodes. For instance, if you want to redirect microblog items to a different URL that |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
290 event items, you can use ``item/urn:xmpp:microblog:0`` and ``item/urn:xmpp:events:0``, |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
291 the first redirection to match will be used. Note that anything containing the filter |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
292 value will match, thus you can also use ``item/microblog`` (but it then would match an |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
293 event which has ``microblog`` in is node name). |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
294 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
295 You can also use a dictionary as value instead of the target URL. This can be useful to |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
296 filter on an other value than the node name, if you want to make specific redirection |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
297 for a particular user for instance. If you use a dictionary, you must use a ``url`` key |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
298 with the target URL (which may have template values as usual), and you may use a |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
299 ``filters`` key mapping to an other dictionary where each key is a filter on a specific |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
300 template value (in other words: key is the template value, like ``jid`` or ``node``, and |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
301 value is the filter to match). |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
302 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
303 *examples* |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
304 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
305 Redirect actor page to ``/profile/<JID user part>``, blogs items to ``/blog/<full |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
306 JID>/<node name>/<item id>`` and events items to ``/event/<full JID>/<node name>/<item |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
307 id>`` :: |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
308 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
309 html_redirect_dict = { |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
310 "actor": "/profile/{jid_user}", |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
311 "item/microblog": "/blog/{jid}/{node}/{item}", |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
312 "item/events": "/event/{jid}/{node}/{item}" |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
313 } |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
314 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
315 Redirect items of user ``louise@example.org`` to ``/b/<item>``:: |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
316 |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
317 html_redirect_dict = { |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
318 "item": { |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
319 "url": "/b/{item}", |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
320 filters: { |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
321 "jid": "louise@example.org" |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
322 } |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
323 } |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
324 } |
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
325 |
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
326 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
327 .. _ap-actor-from-xmpp: |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
328 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
329 How to Address an AP Actor from XMPP |
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
330 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
331 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
332 When addressing an ActivityPub actor from XMPP, you must use a JID corresponding to the |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
333 actor. The domain part of the JID correspond to the gateway JID (the one set in gateway |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
334 profile), while the local part (before the ``@``) is used to specify the AP actor. |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
335 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
336 `XEP-0106`_ (JID Escaping) is used to indicate the AP actor identifier, thus the ``@`` |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
337 must be escaped with ``\40``. |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
338 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
339 .. _XEP-0106: JID Escaping |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
340 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
341 **example** |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
342 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
343 If Louise wants to talk to Pierre which is on the ``example.net`` AP server, she can use |
3885
18ff4f75f0e6
doc (components): the word "handle" is more adapted here
Goffi <goffi@goffi.org>
parents:
3874
diff
changeset
|
344 her XMPP AP gateway which is at ``ap.example.org``. Pierre AP's actor handle is |
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
345 ``pierre@example.net``, Louise can access it via the JID |
3810
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
346 ``pierre\40example.net@ap.example.org`` (we call it *virtual JID* of the AP actor). |
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
347 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
348 Of course, this is a bit cumbersome to do by hand, it is expected that XMPP clients will |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
349 do the (un)escaping automatically for end-user, in a way that Louise could enter |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
350 ``pierre@example.net`` directly, with an indicator to show that this is an ActivityPub |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
351 actor identifier rather than an XMPP JID. |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
352 |
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
353 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
354 .. _xmpp-node-from-ap: |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
355 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
356 How to Address an XMPP Entity from AP |
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
357 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
358 |
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
359 To access an XMPP entity, it is a little bit more complicated for 2 reasons: |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
360 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
361 - XMPP use a wider range of allowed characters than most AP implementations [#AP_chars]_. |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
362 - to get XMPP items, we need 2 data: the entity JID, and a pubsub node |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
363 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
364 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
365 However, Libervia AP gateway tries to make it as user friendly as possible, thus it works |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
366 like this: |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
367 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
368 - in the most common case, one just wants to access the personal blog of a user, and basic |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
369 ASCII characters (with possibly ``-``, ``_`` or ``.``) are used. in this case, the XMPP |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
370 JID can be directly used as AP actor handle |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
371 - when a pubsub node needs to be specified it is most of time with a pubsub JID which has |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
372 not user part (something like ``pubsub.example.org``). In this case, the pubsub node can |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
373 be used as AP actor handle's user part, Libervia will use XMPP discovery to know that |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
374 it's a pubsub service. So if you want to access the blog named ``xmpp_news`` at |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
375 ``pubsub.example.org``, you can use the handle ``xmpp_news@pubsub.example.org`` (be sure |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
376 that the domain ``pubsub.example.org`` links to the Libervia AP gateway HTTP server) |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
377 - if you want to use a specific node with an entity which already has a user part, then a |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
378 special encoding must be used, where ``---`` (three dashes) are used to separate node |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
379 from entity: ``some_node--some_user@example.org`` |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
380 - if you need to use special characters, then you'll have to use ``___`` followed by the |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
381 special encoding (see below). |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
382 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
383 The encoding is explained in the documentation of the following method: |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
384 |
4077
d6837db456fd
refactoring: fix names in doc following modules hierarchy refactoring
Goffi <goffi@goffi.org>
parents:
4037
diff
changeset
|
385 .. automethod:: libervia.backend.plugins.plugin_comp_ap_gateway.APGateway.get_jid_and_node |
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
386 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
387 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
388 .. [#AP_chars] Most if not all AP implementations use webfinger `acct` URI as a de-facto |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
389 standard to manage user-friendly handles (something like ``user@example.org``). Those |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
390 handles, according to `RFC7565`_, should |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
391 manage a wide variety of characters thanks to the support of percent-encoding. |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
392 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
393 Unfortunately, at least one of the most-used AP implementation (Mastodon, which is used |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
394 a reference implementation for this gateway), only uses a limited subset of allowed |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
395 characters. In addition, Mastodon needs an associated handle [#m_wf]_ thus an alternate |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
396 way to encode characters had to be found. |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
397 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
398 An issue has been opened to improve this situation on Mastodon bug tracker: |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
399 https://github.com/mastodon/mastodon/issues/17222 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
400 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
401 .. _RFC7565: https://datatracker.ietf.org/doc/html/rfc7565 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
402 .. [#m_wf] https://docs.joinmastodon.org/spec/webfinger/ |
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
403 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
404 **example** |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
405 |
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
406 If Pierre wants to talk to Louise, he can directly use the JID which is the same as the AP |
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
407 actor identifier, i.e. ``louise@example.org`` (note that on AP software, a ``@`` prefix is |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
408 often required, thus Pierre will look for ``@louise@example.org``). |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
409 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
410 .. note:: |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
411 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
412 The actor endpoint can also be used directly in AP software (in the example above, it |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
413 would be by default ``https://example.org/_ap/actor/louise%40example.org``). |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
414 |
3910
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
415 .. _ap-ad-hoc: |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
416 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
417 Ad-Hoc Commands |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
418 ~~~~~~~~~~~~~~~ |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
419 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
420 The gateway supports `XEP-0050 (Ad-Hoc Commands)`_. For now, only the following node is |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
421 provided: |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
422 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
423 ``https://libervia.org/ap_gateway/xmpp_jid_node_2_ap_actor`` |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
424 Convert XMPP JID and Node to corresponding virtual actor. Node is optional. |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
425 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
426 .. _XEP-0050 (Ad-Hoc Commands): https://xmpp.org/extensions/xep-0050.html |
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
427 |
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
428 Getting AP Message from XMPP |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
429 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
430 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
431 To retrieve ActivityPub messages of an actor from an XMPP client with blogging |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
432 capabilities (like Libervia or Movim), just use the associated JID as explained in |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
433 :ref:`ap-actor-from-xmpp`. The actor messages (from ``outbox`` collection) should appear |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
434 as regular XMPP blog items. |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
435 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
436 .. note:: |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
437 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
438 Due to limitation of `ActivityStream Collection Paging`_, the conversion from XMPP |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
439 `RSM`_ requests is inneficient beyond first or last page. This problem is avoided if |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
440 anybody subscribe to the gateway node (i.e. follow the AP actor), as the collection |
3772
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
441 will then be cached, and efficiently delivered. |
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
442 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
443 .. _ActivityStream Collection Paging: https://www.w3.org/TR/activitystreams-core/#h-paging |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
444 .. _RSM: https://xmpp.org/extensions/xep-0059.html |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
445 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
446 Getting XMPP Items from ActivityPub |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
447 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
448 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
449 To get XMPP items from an ActivityPub implementation, just use the handle as explained at |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
450 :ref:`xmpp-node-from-ap` (often handle searches are triggered with a ``@`` before the |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
451 handle in AP implementations, e.g.: ``@louise@example.org``). |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
452 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
453 .. note:: |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
454 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
455 Some AP implementations such as Mastodon don't retrieve existing items, but only keep |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
456 new ones once an actor is followed. That means that you won't see any message published |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
457 before your entity is followed. Other implementations may work differently. |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
458 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
459 |
3746
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
460 .. _ap-xmpp-threads-conversion: |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
461 |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
462 ActivyPub to XMPP Discussion Threads Conversion |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
463 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
464 |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
465 By default, each (micro)blog publication converted from ActivityPub to XMPP Pubsub is |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
466 associated with a comment node (see `XEP-0277 comments`_) to allow user to post a reply on |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
467 any on them. This result in a "tree-like" comments threading model, which is similar to |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
468 what you can see on popular website such as Reddit, Hacker News, or LinuxFr. |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
469 |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
470 However, some XMPP clients may not play nicely with this kind of threading model. To work |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
471 around this, the ``comments_max_depth`` option allows to limit the maximum number of |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
472 thread. It is an integer value which indicate how many comments nodes may exist for a root |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
473 post. If set to ``1``, only one comment node will be made, and ActivityPub items below |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
474 this level will be moved to this single XMPP pubsub comment node. |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
475 |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
476 The default value of ``0`` means unlimited max depth. |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
477 |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
478 An example can probably make it more clear. Imagine that you have a message ``root |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
479 message``, with a comment to it named ``1``, a comment to ``1`` named ``2`` and so on |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
480 until ``5``. With ``comments_max_depth`` set to ``0``, you'll have one comment node per |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
481 item, resulting in following threads model:: |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
482 |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
483 root message ┑ |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
484 ┕ 1 ┑ |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
485 ┕ 2 ┑ |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
486 ┕ 3 ┑ |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
487 ┕ 4 ┑ |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
488 ┕ 5 |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
489 |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
490 With ``comments_max_depth`` set to ``2``, only 2 nodes will be created, and items below |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
491 depth ``2`` will be put on the same level:: |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
492 |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
493 root message ┑ |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
494 ┕ 1 ┑ |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
495 ┝ 2 |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
496 ┝ 3 |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
497 ┝ 4 |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
498 ┕ 5 |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
499 |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
500 This way, admins can configure the model which suits best the clients which is expected to |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
501 be mainly used on the instance. |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
502 |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
503 .. _XEP-0277 comments: https://xmpp.org/extensions/xep-0277.html#comments |
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
504 |
3772
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
505 Publishing an Item |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
506 ~~~~~~~~~~~~~~~~~~ |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
507 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
508 To publish a new item (e.g. a blog post), you just need to publish normally on your own |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
509 PEP/pubsub node, AP actors following you will be notified. To reply to an AP item, just |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
510 publish to the corresponding pubsub node managed by the gateway. This is transparent for |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
511 AP and XMPP end users. |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
512 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
513 For instance, if Pierre has posted an interesting message on his AP server, and Louise |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
514 wants to reply to it, she just use a client to reply on the comments node of this message, |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
515 this will be delivered as an AP object to Pierre's AP server. |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
516 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
517 On the other hand, if Louise is publishing a new blog post on her XMPP server, Pierre will |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
518 receive corresponding AP object because he's following her. If Pierre answer using his AP |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
519 client, the corresponding message will be published on the comments node of the message |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
520 that Louise has initially published. |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
521 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
522 Following, Subscribing and Cache |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
523 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
524 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
525 When you try to access an uncached AP collection from XMPP (e.g. blog posts), a best |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
526 effort is done to translate XMPP pagination (which uses `XEP-0059 (Result Set |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
527 Management)`_) to the less powerful `AP Collection Paging`_. This is inefficient due to |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
528 technical limitations (page size can't be specified in AP, there is not standard way to |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
529 request item after or before a specific ID, implementations may not implement reverse |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
530 pagination). |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
531 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
532 That's one of the reason why whenever possible, collections are cached locally. Once |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
533 cached, it's easier to return items according to complex requests. |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
534 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
535 However, to cache correctly an AP collection, you need to keep it in sync, and thus to |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
536 receive update when something change (e.g. a new blog item is published). |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
537 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
538 In AP, this is done by following an actor, in XMPP this correspond to a node subscription. |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
539 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
540 When you subscribe to a blog node managed by this gateway, this will be translated to a |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
541 *follow* activity on AP side, and vice versa. |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
542 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
543 When an AP actor is followed, its *outbox* collection (i.e. message published), are |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
544 automatically cached, and will be updated when events will be received. That means that |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
545 you can use pubsub cache search on followed actors, e.g. to retrieve all items about a |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
546 specific topic or published at specific time range. |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
547 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
548 Reciprocally, unsubscribing from a node will *unfollow* the corresponding AP actor. |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
549 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
550 If an AP actor is following or unfollowing an actor mapping an XMPP entity, they nodes |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
551 will be subscribed to or unsubscribed from. |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
552 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
553 All subscriptions are made public as specified by `XEP-0465 (Pubsub Public Subscriptions)`_. |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
554 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
555 .. _XEP-0059 (Result Set Management): https://xmpp.org/extensions/xep-0059.html |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
556 .. _AP Collection Paging: https://www.w3.org/TR/activitystreams-core/#h-paging |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
557 .. _XEP-0465 (Pubsub Public Subscriptions): https://xmpp.org/extensions/inbox/pubsub-public-subscriptions.html |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
558 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
559 Following/Followers Collections and Public Pubsub Subscription |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
560 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
561 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
562 The AP *following* collection is mapped to `XEP-0465 (Pubsub Public Subscriptions)`_. |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
563 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
564 In the same spirit, the AP *followers* collection correspond to public subscribers to the |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
565 microblog node. |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
566 |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
567 Because AP doesn't send any event when *following* or *followers* collections are |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
568 modified, those collections can't be cached, and thus the translation to public pubsub |
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
569 subscriptions is done as best as possible given the constraints. |
3746
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
570 |
3810
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
571 .. _ap-message_delivery: |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
572 |
3786
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
573 Messages Delivery |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
574 ~~~~~~~~~~~~~~~~~ |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
575 |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
576 The gateway can convert AP publications to either XMPP pubsub items (using `XEP-0277 |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
577 (Microblogging over XMPP)`_ when suitable) or to XMPP messages (`<message>` stanzas, i.e. |
3790 | 578 the ones used for instant messaging). Of course it also converts in a similar way in the |
3786
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
579 other direction (XMPP → ActivityPub). |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
580 |
3790 | 581 A received AP item will be converted to an XMPP pubsub item if any of the following |
582 conditions is fulfilled: | |
3786
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
583 |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
584 - it is addressed to the special `*public* collection`_ |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
585 - it is addressed to a local *followers* collection |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
586 |
3790 | 587 A received AP item will be converted to an XMPP message if all the following conditions |
588 are fulfilled: | |
3786
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
589 |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
590 - it is **not** addressed to the special *public* collection |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
591 - it is **not** addressed to a any local *followers* collection. |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
592 |
3790 | 593 In other words, if an AP item is addressed directly to one or more local users, is not |
3786
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
594 public and is not addressed to a *followers* collection, it will be converted to an XMPP |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
595 message, otherwise it will be converted to an XMPP pubsub item. |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
596 |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
597 The behaviour is symmetric, thus if you send an XMPP message it will be converted to an AP |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
598 item which will be only addressed to your recipient. If you write using XMPP pubsub, the |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
599 suitable followers collections of the target AP actor will be automatically added, and the |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
600 item will have the special *public* collection added. |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
601 |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
602 .. note:: |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
603 |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
604 ActivyPub doesn't do any kind of `end-to-end encryption`_, it is **not** the same level of |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
605 privacy as XMPP. |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
606 |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
607 Messages will be at minimum readable by the administrators of the AP gateway and of the |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
608 ActivyPub server of the destinee. Be sure to understand that before sending messages. |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
609 |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
610 If you need more privacy, you need to use either XMPP only (without the ActivityPub |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
611 gateway) with clients implementing correctly end-to-end encryption, or an other |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
612 software. Depending of the level of pricacy required, you may want to use |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
613 authentication by a separated channel, a client which has been audited, encryption by |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
614 default, etc. This is beyond the scope of this AP gateway documentation. |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
615 |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
616 In short, don't use ActivityPub if you need a high level of privacy. This is a current |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
617 protocol limitation, and there is nothing that this gateway can do about this until |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
618 ActivityPub and its implementations evolve. |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
619 |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
620 .. _XEP-0277 (Microblogging over XMPP): https://xmpp.org/extensions/xep-0277.html |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
621 .. _*public* collection: https://www.w3.org/TR/activitypub/#public-addressing |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
622 .. _end-to-end encryption: https://en.wikipedia.org/wiki/End-to-end_encryption |
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
623 |
3810
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
624 Message/Item Retraction |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
625 ~~~~~~~~~~~~~~~~~~~~~~~ |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
626 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
627 If you retract a pubsub item (e.g. a blog post), that is followed by ActivityPub actors, |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
628 a suitable `Delete` activity will be emitted. In other words, the ActivityPub servers will |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
629 be notified of the retraction. |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
630 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
631 Similarly if an AP actor is deleting an item, a suitable `XEP-0060 retraction event`_ will |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
632 be sent to subscribers. |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
633 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
634 In the case of direct messages (see :ref:`ap-message_delivery`), `XEP-0424 (Message |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
635 Retraction)`_ is used in both reception (AP ``Delete`` activity is converted to XEP-0424 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
636 and vice versa). |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
637 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
638 All of this should be transparent to users as long as their clients support the mentioned |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
639 XEPs. |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
640 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
641 .. note:: |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
642 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
643 When retracting a message/item, a retraction request (or equivalent AP "Delete" |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
644 activity) is sent, so the other end clients **may** delete the item. |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
645 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
646 However, there is no way to be sure that the item will be actually deleted: once |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
647 something is sent on the network, any recipient can see it, copy it, share it, etc. |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
648 There is no way to forbid that, and this is true for software, decentralized or not |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
649 (and not only ActivityPub or XMPP). |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
650 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
651 Be sure to understand that before sending anything sensitive. |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
652 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
653 .. note:: |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
654 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
655 When deleting an item on ActivityPub, the item is often replaced by a "tombstone", and |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
656 it's not possible to send a new item with the same ID. Some software (it's at least the |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
657 case with Mastodon), will silently reject the item, and thus people won't see it. |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
658 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
659 This is a different behaviour from XMPP where you can publish a pubsub item, retract |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
660 it, and publish a new item with the same ID. |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
661 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
662 Thus if you retract an item, be sure to publish any new one with new and unique ID, |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
663 otherwise the item may not appear to ActivityPub users (and as the item may be rejected |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
664 silently, you may not be notified). |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
665 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
666 However this should not be a problem in the vast majority of cases, as most XMPP client |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
667 implementing pubsub or pubsub service will generate automatically unique IDs for new |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
668 items. |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
669 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
670 .. _XEP-0060 retraction event: https://xmpp.org/extensions/xep-0060.html#publisher-delete |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
671 .. _XEP-0424 (Message Retraction): https://xmpp.org/extensions/xep-0424.html |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
672 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
673 Blocking an User |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
674 ~~~~~~~~~~~~~~~~ |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
675 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
676 You can block AP actors using :ref:`its virtual JID <ap-actor-from-xmpp>` in the same way |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
677 as for any XMPP entity, by using `XEP-0191 (Blocking Command)`_. |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
678 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
679 This is done at the XMPP server level and your server must support it. From client side, |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
680 many clients support it, and you can use Libervia CLI to do it from command-line (see |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
681 :ref:`libervia-cli_blocking`). |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
682 |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
683 .. _XEP-0191 (Blocking Command): https://xmpp.org/extensions/xep-0191.html |
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
684 |
3827
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
685 Identity and Avatar |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
686 ~~~~~~~~~~~~~~~~~~~ |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
687 |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
688 The gateway does the conversion between XMPP identity and AP actor metadata. |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
689 |
3838 | 690 XMPP "identity" is actually a compilation of data coming from various locations and in |
3827
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
691 particular `XEP-0292 (vCard4 Over XMPP)`_. In those data, vCard's ``nickname`` (first |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
692 found) is used as AP ``name`` field, and vCard's ``note`` is used as AP's ``summary`` |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
693 (it's generally a self-description of users). |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
694 |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
695 For avatars, `XEP-0084 (User Avatar)`_ is used (and actor's ``icon`` field is used on AP |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
696 side). Avatars are downloaded the first time that they are requested, and kept in cache |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
697 for future requests. |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
698 |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
699 Even if XEP-0292 and XEP-0084 are the main XEPs used, Libervia checks various locations, |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
700 and other extensions like `XEP-0054 (vcard-temp)`_ may be used as fallback. |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
701 |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
702 .. _XEP-0292 (vCard4 Over XMPP): https://xmpp.org/extensions/xep-0292.html |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
703 .. _XEP-0084 (User Avatar): https://xmpp.org/extensions/xep-0084.html |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
704 .. _XEP-0054 (vcard-temp): https://xmpp.org/extensions/xep-0054.html |
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
705 |
3838 | 706 Mentions |
707 ~~~~~~~~ | |
708 | |
709 Mentions are converted by the gateway under some conditions explained below. | |
710 | |
711 When receiving an AP item which converts to a pubsub item (i.e. not a direct message), for | |
712 any local user mentioned (using a tag of type ``Mention``) or directly specified in a | |
713 target field (``to``, ``bto``, ``cc`` or ``bcc``), a `XEP-0372 (References)`_ type mention | |
714 will be emitted. | |
715 | |
716 This is not done for direct message as the recipients are already specified, and sending | |
717 reference is most probably not desired for a private message. | |
718 | |
719 In the direction XMPP 🠞 ActivityPub, it's more complicated because XMPP sends references | |
720 separately from the pubsub item, while ActivityPub links them in the same item. | |
721 | |
722 If a XEP-0372 reference targeting an AP actor is received and anchor a pubsub item, the | |
723 item will be looked after in cache. If found, it will be converted to an AP item, a | |
724 mention will be added, and the item will be delivered to the mentioned entity. | |
725 | |
726 This only works if the mentioned actor is on a server which has not already received the | |
727 original item, because otherwise the AP implementation will most probably ignore the new | |
728 item which has the same ID. | |
729 | |
730 It is hard to avoid sending first published item, then the same item with the reference, | |
731 because XEP-0372 references are received after the published items. | |
732 | |
733 To work around that, when an XMPP blog item is received, its body is scanned to find | |
734 ``@user@server.tld`` type mention, and if found a mention is automatically added to the | |
735 resulting AP item. | |
736 | |
737 It is not ideal to parse the body, but that's an acceptable trade-off to make mention | |
738 working. This behaviour is activated by default, but can be deactivated by setting | |
739 ``auto_mentions`` option to ``false``. Auto mentions are only used for pubsub items, and | |
740 not for direct messages for the same reason as mention are not checked in AP direct | |
741 messages (see above). | |
742 | |
743 .. note:: | |
744 | |
745 For auto mentions, it's the AP actor handle which must be used, not the corresponding | |
746 virtual JID. | |
747 | |
748 If you want to mention ``louise@example.org`` then you must use directly | |
749 ``@louise@example.org``, and NOT something like | |
750 ``@louise\40example.org@ap.example.net``. | |
751 | |
752 To mention XMPP entities, your client must use XEP-0372 references directly. | |
753 | |
754 .. _XEP-0372 (References): https://xmpp.org/extensions/xep-0372.html | |
755 | |
3874
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
756 Repeat/Share/Reboost |
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
757 ~~~~~~~~~~~~~~~~~~~~ |
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
758 |
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
759 The repeat feature (also named "share", or "boost") which consist of republishing an item |
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
760 of interest under our own account to make it visible to our subscribers, is done on the |
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
761 XMPP side with `XEP-0277 § Repeating a Post`_, and on the AP side it's an ``Announce`` |
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
762 activity. Conversion is done in both directions and should be transparent to user. |
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
763 |
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
764 .. _XEP-0277 § Repeating a Post: https://xmpp.org/extensions/xep-0277.html#repeat |
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
765 |
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
766 Noticed/Like |
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
767 ~~~~~~~~~~~~ |
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
768 |
3892
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
769 AP's ``Like`` activity is converted on the XMPP side to "`XEP-0470 (Pubsub |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
770 Attachments)`_". ``Like`` is converted to ``noticed`` attachment, meaning that it used in |
3874
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
771 to indicate that something has been seen and taken into account, without really indication |
3892
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
772 if the content is liked or disliked (see XEP-0470 § Foreword: `"noticed" instead of "like" |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
773 or "favourite"`_ for the rational). |
3874
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
774 |
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
775 As usual, conversion is done in both ways. |
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
776 |
3892
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
777 .. _XEP-0470 (Pubsub Attachments): https://xmpp.org/extensions/xep-0470.html |
3874
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
778 .. _XMPP Council: https://xmpp.org/about/xmpp-standards-foundation/ |
3892
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
779 .. _"noticed" instead of "like" or "favourite": https://xmpp.org/extensions/xep-0470.html#noticed-foreword |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
780 |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
781 Reactions |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
782 ~~~~~~~~~ |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
783 |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
784 Reactions are not specified in `base ActivityPub specification`_. However `Pleroma`_, a |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
785 software implemeting ActivityPub, implements them using a non standardised (yet?) |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
786 ``EmojiReact`` activity. Liberva AP Gateway use it to handle reactions. |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
787 |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
788 On the XMPP side, `XEP-0470 (Pubsub Attachments)`_ is once again used. |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
789 |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
790 Libervia also implements `XEP-0444 (Message Reactions)`_ for messages, but because Pleroma |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
791 doesn't handle reactions for direct messages, this is not used in the Libervia AP gateway. |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
792 If in the future an AP implementation uses reactions on direct messages, it will be |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
793 straightforward to add it in the AP gateway. |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
794 |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
795 .. _base ActivityPub specification: https://www.w3.org/TR/activitypub/ |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
796 .. _Pleroma: https://pleroma.social/ |
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
797 .. _XEP-0444 (Message Reactions): https://xmpp.org/extensions/xep-0444.html |
3874
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
798 |
3910
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
799 Events |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
800 ~~~~~~ |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
801 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
802 This gateway manages events. On the XMPP side, the ``Events`` protoXEP is used, on AP side |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
803 ``Event`` objects are used. `Mobilizon`_ is used as reference implementation here. |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
804 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
805 .. note:: |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
806 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
807 The ``Events`` protoXEP has been proposed but not published or reviewed by XMPP council |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
808 yet. The current version is availale at https://github.com/xsf/xeps/pull/1206 and |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
809 hopefully it will eventually become an official experimental XEP. The code and this |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
810 documentation will be updated as the standard evolves. |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
811 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
812 To retrieve AP events from XMPP, use the corresponding virtual JID as explained in |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
813 :ref:`ap-actor-from-xmpp` with the event node (which is ``urn:xmpp:events:0``). |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
814 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
815 *example:* |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
816 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
817 To retrieve events from AP actor with the handle ``somebody@mobilizon.example``, throught |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
818 the ``ap.example.org`` gateway, the ``somebody\40mobilizon.example@ap.example.org`` JID |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
819 can be used with the ``urn:xmpp:events:0`` node. |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
820 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
821 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
822 To retrieve XMPP events from AP, you need to the virtual actor corresponding to the JID |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
823 of the pubsub/PEP service with the event node (starting with ``urn:xmpp:events:0``), as |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
824 explained in :ref:`xmpp-node-from-ap`. You can use :ref:`ap-ad-hoc` to easily convert your |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
825 JID/node combination to a virtual AP actor. Note that the resulting virtual actor is |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
826 unaesthetic due to the presence of event node and the constraints explained in |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
827 :ref:`xmpp-node-from-ap`. |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
828 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
829 To retrieve the link to the XMPP item from AP, you can use the ID from the generated AP |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
830 object. The ID can also be constructed by hand by using the URL |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
831 ``https://<ap_gateway_public_domain>/_ap/<virtual_actor>/<event_item_id>``. |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
832 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
833 *example:* |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
834 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
835 to retrieve from AP the XMPP event at pubsub service ``pubsub.example.net`` on node |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
836 ``urn:xmpp:events:0/party`` with item ID ``picnic_abd1``, and using the AP gateway with |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
837 public url ``https://ap.example.net``, the following link can be used:: |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
838 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
839 https://ap.example.net/_ap/___urn.3Axmpp.3Aevents.3A0.2Fparty---pubsub.2eexample.2enet@ap.tazar3.int/picnic_abd1 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
840 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
841 If you paste it in an AP implementation featuring events (e.g. Mobilizon), the event |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
842 should appear and you should be able to comment it and participate to it. |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
843 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
844 Event comments are supported, the node to use is indicated in the event XMPP item as |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
845 specified in the protoXEP, this should be transparent to end-user. |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
846 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
847 Participation to an event is supported through the RSVP mechanism on XMPP and with |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
848 ``Join`` and ``Leave`` activities on AP. Note that XMPP allows more nuances with its RSVP |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
849 mechanism (it's possible to say if someone will "maybe" attend an event, and to request |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
850 any kind of extra informations) while AP only indicates if one will attend or not an |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
851 event. |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
852 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
853 |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
854 .. _Mobilizon: https://joinmobilizon.org/ |
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
855 |
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
856 Using the Component (for developers) |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
857 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
858 |
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
859 Publication of AP items can be tested using the following method (with can be accessed |
4037
524856bd7b19
massive refactoring to switch from camelCase to snake_case:
Goffi <goffi@goffi.org>
parents:
3984
diff
changeset
|
860 through the ``ap_send`` bridge method, client is then replaced by the ``profile`` name, as |
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
861 last argument): |
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
862 |
4077
d6837db456fd
refactoring: fix names in doc following modules hierarchy refactoring
Goffi <goffi@goffi.org>
parents:
4037
diff
changeset
|
863 .. automethod:: libervia.backend.plugins.plugin_comp_ap_gateway.APGateway.publish_message |
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
864 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
865 The method can be used either with CLI's :ref:`debug bridge method |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
866 <li_debug_bridge_method>` or with any D-Bus tool like ``qdbus`` or ``d-feet`` (only if you |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
867 use the D-Bus bridge). |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
868 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
869 example |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
870 ~~~~~~~ |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
871 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
872 On its ``example.net`` Mastodon instance, Pierre has published a message with the id |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
873 ``https://example.net/@pierre/106986412193109832``. To send a reply to this message, |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
874 Louise can use the following command:: |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
875 |
4037
524856bd7b19
massive refactoring to switch from camelCase to snake_case:
Goffi <goffi@goffi.org>
parents:
3984
diff
changeset
|
876 $ li debug bridge method -c ap_send '"{\"node\": \"https://example.net/@pierre/106986412193109832\", \"content\": \"A lille hello from XMPP\"}","pierre\\40example.net@ap.example.org", "louise"' |
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
877 |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
878 Note the double escaping, one for the shell argument, and the other to specify JSON |
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
879 object. |
4279
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
880 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
881 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
882 Audio/Video Conferences |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
883 ----------------------- |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
884 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
885 **entry_point:** ``conferences`` |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
886 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
887 This component integrates a service to run multiparty audio/video conferences over XMPP. |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
888 The service is called a "Selective Forwarding Unit" (SFU), and it's main role is to |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
889 distribute participants' audio and video streams. |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
890 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
891 The component currently integrates the `Galène project`_, as it is a complete, simple, and |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
892 easy to install service. Other projects may be integrated in the future if the need |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
893 arises. |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
894 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
895 .. note:: |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
896 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
897 This component is **work in progress** and under heavy development. |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
898 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
899 Please ensure that Galène is already installed on your device. |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
900 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
901 If the ``galene`` executable is not in your ``PATH`` environment variable, you can specify its |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
902 location using the ``galene_path`` option (see below). |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
903 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
904 Note that Galène will be automatically started and stopped by the component, you don't |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
905 have to start it yourself. |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
906 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
907 Configuration |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
908 ~~~~~~~~~~~~~ |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
909 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
910 All options are to be set in the ``[component conferences]`` section. |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
911 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
912 ``galene_path`` |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
913 The path to the Galène executable, if it is not in the `PATH` environment variable. |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
914 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
915 **default**: Look for ``galene`` in the ``PATH`` |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
916 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
917 ``http_port`` |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
918 The port used by the Galène HTTP server. |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
919 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
920 **default**: 9443 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
921 |
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
922 .. _Galène project: https://galene.org/ |