Mercurial > libervia-backend
annotate doc/components.rst @ 3888:aa7197b67c26
component AP gateway: AP <=> XMPP reactions conversions:
- Pubsub Attachments plugin has been renamed to XEP-0470 following publication
- XEP-0470 has been updated to follow 0.2 changes
- AP reactions (as implemented in Pleroma) are converted to XEP-0470
- XEP-0470 events are converted to AP reactions (again, using "EmojiReact" from Pleroma)
- AP activities related to attachments (like/reactions) are cached in Libervia because
it's not possible to retrieve them from Pleroma instances once they have been emitted
(doing an HTTP get on their ID returns a 404). For now those cache are not flushed, this
should be improved in the future.
- `sharedInbox` is used when available. Pleroma returns a 500 HTTP error when ``to`` or
``cc`` are used in a direct inbox.
- reactions and like are not currently used for direct messages, because they can't be
emitted from Pleroma in this case, thus there is no point in implementing them for the
moment.
rel 371
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Wed, 31 Aug 2022 17:07:03 +0200 |
| parents | 18ff4f75f0e6 |
| children | ba78cc0c8d59 |
| 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 |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
678 AP's ``Like`` activity is converted on the XMPP side to "`Pubsub Attachment`_", which is |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
679 currently a "protoXEP", i.e. a specification proposed as a standard (not yet reviewed by |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
680 `XMPP Council`_). ``Like`` is converted to ``noticed`` attachment, meaning that it used in |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
681 to indicate that something has been seen and taken into account, without really indication |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
682 if the content is liked or disliked (see Pubsub Attachment § Foreword: `"noticed" instead |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
683 of "like" or "favourite"`_ for the rational). |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
684 |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
685 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
|
686 |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
687 .. _Pubsub Attachment: https://xmpp.org/extensions/inbox/pubsub-attachments.html |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
688 .. _XMPP Council: https://xmpp.org/about/xmpp-standards-foundation/ |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
689 .. _"noticed" instead of "like" or "favourite": https://xmpp.org/extensions/inbox/pubsub-attachments.html#noticed-foreword |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
690 |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
691 Using the Component (for developers) |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
692 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
693 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
694 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
|
695 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
|
696 last argument): |
|
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
697 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
698 .. 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
|
699 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
700 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
|
701 <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
|
702 use the D-Bus bridge). |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
703 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
704 example |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
705 ~~~~~~~ |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
706 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
707 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
|
708 ``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
|
709 Louise can use the following command:: |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
710 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
711 $ 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
|
712 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
713 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
|
714 object. |
|
3874
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
715 |