Mercurial > libervia-backend
annotate doc/components.rst @ 3909:3c3275a6dc8f
doc (cli/event): update doc following changes:
rel 372
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Thu, 22 Sep 2022 12:01:44 +0200 |
| parents | ba78cc0c8d59 |
| children | 199598223f82 |
| 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 .. note:: |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
162 |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
163 this component is currently in active development, and not yet fully functional. This |
|
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
164 documentation will be updated during evolution of component. |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
165 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
166 You can follow the development by reading `Libervia Progress Notes`_. |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
167 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
168 .. _Libervia Progress Notes: https://www.goffi.org/tag/Libervia%20progress |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
169 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
170 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
|
171 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
|
172 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
|
173 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
174 .. _ActivityPub: https://activitypub.rocks/ |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
175 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
176 .. note:: |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
177 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
178 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
|
179 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
|
180 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
181 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
|
182 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
|
183 (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
|
184 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
|
185 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
|
186 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
|
187 documentation to find how this must be done. |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
188 |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
189 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
190 Configuration |
|
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 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
193 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
|
194 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
195 ``public_url`` |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
196 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
|
197 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
198 **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
|
199 an error is raised. |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
200 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
201 ``http_port`` |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
202 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
|
203 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
|
204 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
|
205 ``80`` port to the port specified here. |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
206 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
207 **default**: ``8123`` |
|
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 ``http_connection_type`` |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
210 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
|
211 already handles HTTPS, you may want to use ``http``. |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
212 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
213 **default**: ``https`` |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
214 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
215 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
|
216 is only to be used with an HTTPS proxy. |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
217 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
218 ``local_only`` |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
219 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
|
220 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
|
221 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
|
222 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
|
223 ``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
|
224 ``buenaventura@example.net`` won't (note the different domain). |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
225 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
226 Most of time, ``local_only`` should be used. |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
227 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
228 **default**: ``true`` |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
229 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
230 ``ap_path`` |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
231 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
|
232 default value. |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
233 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
234 **default**: ``_ap`` |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
235 |
|
3746
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
236 ``comments_max_depth`` |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
237 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
|
238 :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
|
239 |
| 3838 | 240 ``auto_mentions`` |
| 241 A boolean value indicating if received XMPP pubsub blog items bodies must be scanned to | |
| 242 find ``@user@server.tld`` type mentions. If mentions are found, they'll be added to the | |
| 243 resulting AP items. | |
| 244 | |
| 245 **default**: ``true`` | |
| 246 | |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
247 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
248 .. _ap-actor-from-xmpp: |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
249 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
250 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
|
251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
252 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
253 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
|
254 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
|
255 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
|
256 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
257 `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
|
258 must be escaped with ``\40``. |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
259 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
260 .. _XEP-0106: JID Escaping |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
261 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
262 **example** |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
263 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
264 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
|
265 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
|
266 ``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
|
267 ``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
|
268 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
269 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
|
270 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
|
271 ``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
|
272 actor identifier rather than an XMPP JID. |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
273 |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
274 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
275 .. _xmpp-node-from-ap: |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
276 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
277 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
|
278 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
279 |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
280 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
|
281 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
282 - 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
|
283 - 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
|
284 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
285 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
286 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
|
287 like this: |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
288 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
289 - 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
|
290 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
|
291 JID can be directly used as AP actor handle |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
292 - 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
|
293 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
|
294 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
|
295 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
|
296 ``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
|
297 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
|
298 - 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
|
299 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
|
300 from entity: ``some_node--some_user@example.org`` |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
301 - 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
|
302 special encoding (see below). |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
303 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
304 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
|
305 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
306 .. automethod:: sat.plugins.plugin_comp_ap_gateway.APGateway.getJIDAndNode |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
307 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
308 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
309 .. [#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
|
310 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
|
311 handles, according to `RFC7565`_, should |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
312 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
|
313 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
314 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
|
315 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
|
316 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
|
317 way to encode characters had to be found. |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
318 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
319 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
|
320 https://github.com/mastodon/mastodon/issues/17222 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
321 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
322 .. _RFC7565: https://datatracker.ietf.org/doc/html/rfc7565 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
323 .. [#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
|
324 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
325 **example** |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
326 |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
327 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
|
328 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
|
329 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
|
330 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
331 .. note:: |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
332 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
333 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
|
334 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
|
335 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
336 |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
337 Getting AP Message from XMPP |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
338 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
339 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
340 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
|
341 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
|
342 :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
|
343 as regular XMPP blog items. |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
344 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
345 .. note:: |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
346 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
347 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
|
348 `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
|
349 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
|
350 will then be cached, and efficiently delivered. |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
351 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
352 .. _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
|
353 .. _RSM: https://xmpp.org/extensions/xep-0059.html |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
354 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
355 Getting XMPP Items from ActivityPub |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
356 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
357 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
358 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
|
359 :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
|
360 handle in AP implementations, e.g.: ``@louise@example.org``). |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
361 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
362 .. note:: |
|
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 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
|
365 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
|
366 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
|
367 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
368 |
|
3746
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
369 .. _ap-xmpp-threads-conversion: |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
370 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
371 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
|
372 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
373 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
374 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
|
375 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
|
376 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
|
377 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
|
378 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
379 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
|
380 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
|
381 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
|
382 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
|
383 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
|
384 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
385 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
|
386 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
387 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
|
388 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
|
389 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
|
390 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
|
391 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
392 root message ┑ |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
393 ┕ 1 ┑ |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
394 ┕ 2 ┑ |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
395 ┕ 3 ┑ |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
396 ┕ 4 ┑ |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
397 ┕ 5 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
398 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
399 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
|
400 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
|
401 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
402 root message ┑ |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
403 ┕ 1 ┑ |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
404 ┝ 2 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
405 ┝ 3 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
406 ┝ 4 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
407 ┕ 5 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
408 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
409 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
|
410 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
|
411 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
412 .. _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
|
413 |
|
3772
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
414 Publishing an Item |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
415 ~~~~~~~~~~~~~~~~~~ |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
416 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
417 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
|
418 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
|
419 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
|
420 AP and XMPP end users. |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
421 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
422 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
|
423 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
|
424 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
|
425 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
426 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
|
427 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
|
428 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
|
429 that Louise has initially published. |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
430 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
431 Following, Subscribing and Cache |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
432 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
433 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
434 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
|
435 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
|
436 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
|
437 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
|
438 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
|
439 pagination). |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
440 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
441 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
|
442 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
|
443 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
444 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
|
445 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
|
446 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
447 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
|
448 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
449 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
|
450 *follow* activity on AP side, and vice versa. |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
451 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
452 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
|
453 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
|
454 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
|
455 specific topic or published at specific time range. |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
456 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
457 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
|
458 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
459 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
|
460 will be subscribed to or unsubscribed from. |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
461 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
462 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
|
463 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
464 .. _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
|
465 .. _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
|
466 .. _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
|
467 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
468 Following/Followers Collections and Public Pubsub Subscription |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
469 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
470 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
471 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
|
472 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
473 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
|
474 microblog node. |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
475 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
476 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
|
477 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
|
478 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
|
479 |
|
3810
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
480 .. _ap-message_delivery: |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
481 |
|
3786
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
482 Messages Delivery |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
483 ~~~~~~~~~~~~~~~~~ |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
484 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
485 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
|
486 (Microblogging over XMPP)`_ when suitable) or to XMPP messages (`<message>` stanzas, i.e. |
| 3790 | 487 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
|
488 other direction (XMPP → ActivityPub). |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
489 |
| 3790 | 490 A received AP item will be converted to an XMPP pubsub item if any of the following |
| 491 conditions is fulfilled: | |
|
3786
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
492 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
493 - it is addressed to the special `*public* collection`_ |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
494 - it is addressed to a local *followers* collection |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
495 |
| 3790 | 496 A received AP item will be converted to an XMPP message if all the following conditions |
| 497 are fulfilled: | |
|
3786
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
498 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
499 - it is **not** addressed to the special *public* collection |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
500 - it is **not** addressed to a any local *followers* collection. |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
501 |
| 3790 | 502 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
|
503 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
|
504 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
|
505 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
506 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
|
507 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
|
508 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
|
509 item will have the special *public* collection added. |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
510 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
511 .. note:: |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
512 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
513 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
|
514 privacy as XMPP. |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
515 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
516 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
|
517 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
|
518 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
519 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
|
520 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
|
521 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
|
522 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
|
523 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
|
524 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
525 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
|
526 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
|
527 ActivityPub and its implementations evolve. |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
528 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
529 .. _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
|
530 .. _*public* collection: https://www.w3.org/TR/activitypub/#public-addressing |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
531 .. _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
|
532 |
|
3810
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
533 Message/Item Retraction |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
534 ~~~~~~~~~~~~~~~~~~~~~~~ |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
535 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
536 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
|
537 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
|
538 be notified of the retraction. |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
539 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
540 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
|
541 be sent to subscribers. |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
542 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
543 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
|
544 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
|
545 and vice versa). |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
546 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
547 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
|
548 XEPs. |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
549 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
550 .. note:: |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
551 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
552 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
|
553 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
|
554 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
555 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
|
556 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
|
557 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
|
558 (and not only ActivityPub or XMPP). |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
559 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
560 Be sure to understand that before sending anything sensitive. |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
561 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
562 .. note:: |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
563 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
564 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
|
565 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
|
566 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
|
567 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
568 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
|
569 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
|
570 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
571 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
|
572 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
|
573 silently, you may not be notified). |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
574 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
575 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
|
576 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
|
577 items. |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
578 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
579 .. _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
|
580 .. _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
|
581 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
582 Blocking an User |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
583 ~~~~~~~~~~~~~~~~ |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
584 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
585 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
|
586 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
|
587 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
588 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
|
589 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
|
590 :ref:`libervia-cli_blocking`). |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
591 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
592 .. _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
|
593 |
|
3827
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
594 Identity and Avatar |
|
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
595 ~~~~~~~~~~~~~~~~~~~ |
|
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
596 |
|
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
597 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
|
598 |
| 3838 | 599 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
|
600 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
|
601 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
|
602 (it's generally a self-description of users). |
|
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
603 |
|
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
604 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
|
605 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
|
606 for future requests. |
|
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
607 |
|
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
608 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
|
609 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
|
610 |
|
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
611 .. _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
|
612 .. _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
|
613 .. _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
|
614 |
| 3838 | 615 Mentions |
| 616 ~~~~~~~~ | |
| 617 | |
| 618 Mentions are converted by the gateway under some conditions explained below. | |
| 619 | |
| 620 When receiving an AP item which converts to a pubsub item (i.e. not a direct message), for | |
| 621 any local user mentioned (using a tag of type ``Mention``) or directly specified in a | |
| 622 target field (``to``, ``bto``, ``cc`` or ``bcc``), a `XEP-0372 (References)`_ type mention | |
| 623 will be emitted. | |
| 624 | |
| 625 This is not done for direct message as the recipients are already specified, and sending | |
| 626 reference is most probably not desired for a private message. | |
| 627 | |
| 628 In the direction XMPP 🠞 ActivityPub, it's more complicated because XMPP sends references | |
| 629 separately from the pubsub item, while ActivityPub links them in the same item. | |
| 630 | |
| 631 If a XEP-0372 reference targeting an AP actor is received and anchor a pubsub item, the | |
| 632 item will be looked after in cache. If found, it will be converted to an AP item, a | |
| 633 mention will be added, and the item will be delivered to the mentioned entity. | |
| 634 | |
| 635 This only works if the mentioned actor is on a server which has not already received the | |
| 636 original item, because otherwise the AP implementation will most probably ignore the new | |
| 637 item which has the same ID. | |
| 638 | |
| 639 It is hard to avoid sending first published item, then the same item with the reference, | |
| 640 because XEP-0372 references are received after the published items. | |
| 641 | |
| 642 To work around that, when an XMPP blog item is received, its body is scanned to find | |
| 643 ``@user@server.tld`` type mention, and if found a mention is automatically added to the | |
| 644 resulting AP item. | |
| 645 | |
| 646 It is not ideal to parse the body, but that's an acceptable trade-off to make mention | |
| 647 working. This behaviour is activated by default, but can be deactivated by setting | |
| 648 ``auto_mentions`` option to ``false``. Auto mentions are only used for pubsub items, and | |
| 649 not for direct messages for the same reason as mention are not checked in AP direct | |
| 650 messages (see above). | |
| 651 | |
| 652 .. note:: | |
| 653 | |
| 654 For auto mentions, it's the AP actor handle which must be used, not the corresponding | |
| 655 virtual JID. | |
| 656 | |
| 657 If you want to mention ``louise@example.org`` then you must use directly | |
| 658 ``@louise@example.org``, and NOT something like | |
| 659 ``@louise\40example.org@ap.example.net``. | |
| 660 | |
| 661 To mention XMPP entities, your client must use XEP-0372 references directly. | |
| 662 | |
| 663 .. _XEP-0372 (References): https://xmpp.org/extensions/xep-0372.html | |
| 664 | |
|
3874
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
665 Repeat/Share/Reboost |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
666 ~~~~~~~~~~~~~~~~~~~~ |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
667 |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
668 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
|
669 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
|
670 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
|
671 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
|
672 |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
673 .. _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
|
674 |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
675 Noticed/Like |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
676 ~~~~~~~~~~~~ |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
677 |
|
3892
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
678 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
|
679 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
|
680 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
|
681 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
|
682 or "favourite"`_ for the rational). |
|
3874
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
683 |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
684 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
|
685 |
|
3892
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
686 .. _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
|
687 .. _XMPP Council: https://xmpp.org/about/xmpp-standards-foundation/ |
|
3892
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
688 .. _"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
|
689 |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
690 Reactions |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
691 ~~~~~~~~~ |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
692 |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
693 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
|
694 software implemeting ActivityPub, implements them using a non standardised (yet?) |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
695 ``EmojiReact`` activity. Liberva AP Gateway use it to handle reactions. |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
696 |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
697 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
|
698 |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
699 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
|
700 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
|
701 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
|
702 straightforward to add it in the AP gateway. |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
703 |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
704 .. _base ActivityPub specification: https://www.w3.org/TR/activitypub/ |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
705 .. _Pleroma: https://pleroma.social/ |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
706 .. _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
|
707 |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
708 Using the Component (for developers) |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
709 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
710 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
711 Publication of AP items can be tested using the following method (with can be accessed |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
712 through the ``APSend`` bridge method, client is then replaced by the ``profile`` name, as |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
713 last argument): |
|
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
714 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
715 .. automethod:: sat.plugins.plugin_comp_ap_gateway.APGateway.publishMessage |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
716 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
717 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
|
718 <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
|
719 use the D-Bus bridge). |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
720 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
721 example |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
722 ~~~~~~~ |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
723 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
724 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
|
725 ``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
|
726 Louise can use the following command:: |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
727 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
728 $ li debug bridge method -c APSend '"{\"node\": \"https://example.net/@pierre/106986412193109832\", \"content\": \"A lille hello from XMPP\"}","pierre\\40example.net@ap.example.org", "louise"' |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
729 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
730 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
|
731 object. |