Mercurial > libervia-backend
annotate doc/components.rst @ 4351:6a0a081485b8
plugin autocrypt: Autocrypt protocol implementation:
Implementation of autocrypt: `autocrypt` header is checked, and if present and no public
key is known for the peer, the key is imported.
`autocrypt` header is also added to outgoing message (only if an email gateway is
detected).
For the moment, the JID is use as identifier, but the real email used by gateway should be
used in the future.
rel 456
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Fri, 28 Feb 2025 09:23:35 +0100 |
| parents | 35d41de5b2aa |
| children | 382dc6e62b6e |
| 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 |
|
4348
35d41de5b2aa
doc (component): document use of Gateway Relayed Encryption:
Goffi <goffi@goffi.org>
parents:
4340
diff
changeset
|
972 End-to-End Encryption |
|
35d41de5b2aa
doc (component): document use of Gateway Relayed Encryption:
Goffi <goffi@goffi.org>
parents:
4340
diff
changeset
|
973 ~~~~~~~~~~~~~~~~~~~~~ |
|
35d41de5b2aa
doc (component): document use of Gateway Relayed Encryption:
Goffi <goffi@goffi.org>
parents:
4340
diff
changeset
|
974 |
|
35d41de5b2aa
doc (component): document use of Gateway Relayed Encryption:
Goffi <goffi@goffi.org>
parents:
4340
diff
changeset
|
975 The gateway supports end-to-end encryption through the Gateway Relayed Encryption |
|
35d41de5b2aa
doc (component): document use of Gateway Relayed Encryption:
Goffi <goffi@goffi.org>
parents:
4340
diff
changeset
|
976 specification. This works by indicating to client how to format and encrypt the message |
|
35d41de5b2aa
doc (component): document use of Gateway Relayed Encryption:
Goffi <goffi@goffi.org>
parents:
4340
diff
changeset
|
977 (in technical terms, it's by telling it to use MIME and OpenPGP) before sending it to the |
|
35d41de5b2aa
doc (component): document use of Gateway Relayed Encryption:
Goffi <goffi@goffi.org>
parents:
4340
diff
changeset
|
978 gateway. This only works with clients implementing this specification. |
|
35d41de5b2aa
doc (component): document use of Gateway Relayed Encryption:
Goffi <goffi@goffi.org>
parents:
4340
diff
changeset
|
979 |
|
35d41de5b2aa
doc (component): document use of Gateway Relayed Encryption:
Goffi <goffi@goffi.org>
parents:
4340
diff
changeset
|
980 |
|
35d41de5b2aa
doc (component): document use of Gateway Relayed Encryption:
Goffi <goffi@goffi.org>
parents:
4340
diff
changeset
|
981 .. note:: |
|
35d41de5b2aa
doc (component): document use of Gateway Relayed Encryption:
Goffi <goffi@goffi.org>
parents:
4340
diff
changeset
|
982 |
|
35d41de5b2aa
doc (component): document use of Gateway Relayed Encryption:
Goffi <goffi@goffi.org>
parents:
4340
diff
changeset
|
983 Gateway Relayed Encryption is not yet an official XEP, it will be evaluated by XMPP |
|
35d41de5b2aa
doc (component): document use of Gateway Relayed Encryption:
Goffi <goffi@goffi.org>
parents:
4340
diff
changeset
|
984 council to see if it gets an official number in coming weeks. |
|
35d41de5b2aa
doc (component): document use of Gateway Relayed Encryption:
Goffi <goffi@goffi.org>
parents:
4340
diff
changeset
|
985 |
|
4340
ea72364131d5
doc (components): Update Email Gateway documentation:
Goffi <goffi@goffi.org>
parents:
4319
diff
changeset
|
986 |
|
4319
ef29fa1d9d69
doc (components): update doc to show headers support:
Goffi <goffi@goffi.org>
parents:
4312
diff
changeset
|
987 .. _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
|
988 .. _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
|
989 .. _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
|
990 .. _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
|
991 .. _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
|
992 |