Mercurial > libervia-backend
annotate doc/components.rst @ 4340:ea72364131d5 default tip @
doc (components): Update Email Gateway documentation:
A section has been added to explain how attachments are handled.
fix 453
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Tue, 03 Dec 2024 00:53:18 +0100 |
| parents | ef29fa1d9d69 |
| 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 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
|
896 |
|
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
897 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
|
898 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
|
899 |
|
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
900 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
|
901 have to start it yourself. |
|
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
902 |
|
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
903 Configuration |
|
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
904 ~~~~~~~~~~~~~ |
|
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
905 |
|
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
906 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
|
907 |
|
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
908 ``galene_path`` |
|
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
909 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
|
910 |
|
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
911 **default**: Look for ``galene`` in the ``PATH`` |
|
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
912 |
|
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
913 ``http_port`` |
|
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
914 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
|
915 |
|
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
916 **default**: 9443 |
|
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
917 |
|
6276242736c3
doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents:
4260
diff
changeset
|
918 .. _Galène project: https://galene.org/ |
|
4304
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
919 |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
920 |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
921 Email Gateway |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
922 ------------- |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
923 |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
924 **entry_point:** ``email-gateway`` |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
925 |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
926 .. note:: |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
927 |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
928 This component is **work in progress** and under heavy development. |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
929 |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
930 This gateway links the email network and XMPP in both directions. It allows sending and |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
931 receiving emails using XMPP clients. |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
932 |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
933 The gateway uses an existing email account configured using IMAP4 and SMTP. IMAP4 is used |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
934 for reception and the server must support IMAP4 rev1 protocol with the "IDLE" extension |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
935 for real-time notifications. SMTP is used for sending emails. |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
936 |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
937 To use the gateway, one must register through `XEP-0100 (Gateway Interaction)`_. Once |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
938 registered, connection to the IMAP server is started immediately, and new emails in the |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
939 ``INBOX`` mailbox are received as XMPP messages. |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
940 |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
941 For the moment, mailboxes are used in read-only mode, meaning that the read status and |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
942 other attributes are not changed, and messages will appear normally in other MUA (email |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
943 clients). |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
944 |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
945 To send a message, just write to the corresponding JID. Email addresses are mapped to JIDs |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
946 using `XEP-0106 (JID Escaping)`_: the email is escaped and used as the user-part of the |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
947 gateway JID. |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
948 |
|
4312
e39c8e805488
doc (components): update doc to indicate support of addressing metadata.
Goffi <goffi@goffi.org>
parents:
4304
diff
changeset
|
949 Multicast addressing (i.e. the ``To``, ``CC`` and ``BCC`` email headers or their |
|
4319
ef29fa1d9d69
doc (components): update doc to show headers support:
Goffi <goffi@goffi.org>
parents:
4312
diff
changeset
|
950 `XEP-0033 (Extended Stanza Addressing)`_ XMPP equivalent) are supported and will be converted from and to XMPP. Other |
|
4312
e39c8e805488
doc (components): update doc to indicate support of addressing metadata.
Goffi <goffi@goffi.org>
parents:
4304
diff
changeset
|
951 metadata like ``Reply-To`` are also supported. You can use |
|
e39c8e805488
doc (components): update doc to indicate support of addressing metadata.
Goffi <goffi@goffi.org>
parents:
4304
diff
changeset
|
952 :ref:`libervia-cli_message_send` to specify those metadata when sending a message. |
|
e39c8e805488
doc (components): update doc to indicate support of addressing metadata.
Goffi <goffi@goffi.org>
parents:
4304
diff
changeset
|
953 |
|
4319
ef29fa1d9d69
doc (components): update doc to show headers support:
Goffi <goffi@goffi.org>
parents:
4312
diff
changeset
|
954 Some headers are converted between XMPP and email, such as the ``Keywords`` or the |
|
ef29fa1d9d69
doc (components): update doc to show headers support:
Goffi <goffi@goffi.org>
parents:
4312
diff
changeset
|
955 ``Importance`` ones. On XMPP side, `XEP-0131 (Stanza Headers and Internet Metadata)`_ is |
|
ef29fa1d9d69
doc (components): update doc to show headers support:
Goffi <goffi@goffi.org>
parents:
4312
diff
changeset
|
956 used. |
|
4312
e39c8e805488
doc (components): update doc to indicate support of addressing metadata.
Goffi <goffi@goffi.org>
parents:
4304
diff
changeset
|
957 |
|
4319
ef29fa1d9d69
doc (components): update doc to show headers support:
Goffi <goffi@goffi.org>
parents:
4312
diff
changeset
|
958 |
|
4340
ea72364131d5
doc (components): Update Email Gateway documentation:
Goffi <goffi@goffi.org>
parents:
4319
diff
changeset
|
959 Attachment Management |
|
ea72364131d5
doc (components): Update Email Gateway documentation:
Goffi <goffi@goffi.org>
parents:
4319
diff
changeset
|
960 ~~~~~~~~~~~~~~~~~~~~~ |
|
ea72364131d5
doc (components): Update Email Gateway documentation:
Goffi <goffi@goffi.org>
parents:
4319
diff
changeset
|
961 |
|
ea72364131d5
doc (components): Update Email Gateway documentation:
Goffi <goffi@goffi.org>
parents:
4319
diff
changeset
|
962 Email attachments are downloaded and stored by the gateway. Attachments can be managed |
|
ea72364131d5
doc (components): Update Email Gateway documentation:
Goffi <goffi@goffi.org>
parents:
4319
diff
changeset
|
963 individually, independent of the email message itself. They can be retrieved and deleted |
|
ea72364131d5
doc (components): Update Email Gateway documentation:
Goffi <goffi@goffi.org>
parents:
4319
diff
changeset
|
964 from the gateway (using `XEP-0498 (PubSub File Sharing)`_). |
|
ea72364131d5
doc (components): Update Email Gateway documentation:
Goffi <goffi@goffi.org>
parents:
4319
diff
changeset
|
965 |
|
ea72364131d5
doc (components): Update Email Gateway documentation:
Goffi <goffi@goffi.org>
parents:
4319
diff
changeset
|
966 .. note:: |
|
ea72364131d5
doc (components): Update Email Gateway documentation:
Goffi <goffi@goffi.org>
parents:
4319
diff
changeset
|
967 |
|
ea72364131d5
doc (components): Update Email Gateway documentation:
Goffi <goffi@goffi.org>
parents:
4319
diff
changeset
|
968 **Current Limitation:** Attachments are partially handled; while they can be retrieved |
|
ea72364131d5
doc (components): Update Email Gateway documentation:
Goffi <goffi@goffi.org>
parents:
4319
diff
changeset
|
969 and deleted, they are not yet sent with the message. This functionality will be added |
|
ea72364131d5
doc (components): Update Email Gateway documentation:
Goffi <goffi@goffi.org>
parents:
4319
diff
changeset
|
970 as development progresses. |
|
ea72364131d5
doc (components): Update Email Gateway documentation:
Goffi <goffi@goffi.org>
parents:
4319
diff
changeset
|
971 |
|
ea72364131d5
doc (components): Update Email Gateway documentation:
Goffi <goffi@goffi.org>
parents:
4319
diff
changeset
|
972 |
|
4319
ef29fa1d9d69
doc (components): update doc to show headers support:
Goffi <goffi@goffi.org>
parents:
4312
diff
changeset
|
973 .. _XEP-0033 (Extended Stanza Addressing): https://xmpp.org/extensions/xep-0033.html |
|
4304
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
974 .. _XEP-0100 (Gateway Interaction): https://xmpp.org/extensions/xep-0100.html |
|
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
975 .. _XEP-0106 (JID Escaping): https://xmpp.org/extensions/xep-0106.html |
|
4319
ef29fa1d9d69
doc (components): update doc to show headers support:
Goffi <goffi@goffi.org>
parents:
4312
diff
changeset
|
976 .. _XEP-0131 (Stanza Headers and Internet Metadata): https://xmpp.org/extensions/xep-0131.html |
|
4340
ea72364131d5
doc (components): Update Email Gateway documentation:
Goffi <goffi@goffi.org>
parents:
4319
diff
changeset
|
977 .. _XEP-0498 (Pubsub File Sharing): https://xmpp.org/extensions/xep-0498.html |
|
4304
92a886f31581
doc (components): new Email gateway documentation:
Goffi <goffi@goffi.org>
parents:
4279
diff
changeset
|
978 |