Mercurial > libervia-backend
annotate doc/components.rst @ 4243:e47e29511d57
cli (remote-control): new `remote-control` command:
2 subcommands are available: `send` to control remotely a device, and `receive` to be
controlled.
Documentation will follow.
rel 436
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Sat, 11 May 2024 13:52:43 +0200 |
| parents | d6837db456fd |
| children | 57ff857bf96e |
| 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 | |
|
3978
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
247 ``html_redirect_dict`` |
| 3984 | 248 A dictionary used to redirect HTTP requests when it's not an ActivityPub request (i.e. |
|
3978
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
249 when the ``Accept`` header is not set to ``application/json``). Several ActivityPub |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
250 implementations link to original server when clicking on some links such as post author |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
251 or item ID, and this result in a request to the corresponding ActivityPub endpoint, but |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
252 made to retrieve HTML instead of ActivityPub JSON data. |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
253 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
254 By default, this request is showing the corresponding AP JSON data, but if you set HTML |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
255 redirection, you can redirect the page to your XMPP client web frontend (or anything |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
256 making sense), which results in better user experience. |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
257 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
258 The expected dictionary is a mapping URL request types to destination URL. |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
259 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
260 The URL request types is the first path element after ``ap_path``, it can be: |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
261 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
262 ``actor`` |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
263 Actor information. It should link to the profile page of the corresponding XMPP entity |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
264 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
265 ``item`` |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
266 A specific publication. It should link to the rendered item |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
267 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
268 ``followers`` |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
269 Entities publicly subscribed to the actor. It is usually not used for redirection. |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
270 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
271 ``following`` |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
272 Entities that the actor is publicly subscribed to. It is usually not used for |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
273 redirection. |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
274 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
275 In the target URL you can uses template values in curly braces (something like |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
276 ``{item}``). The values that you can use are: |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
277 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
278 ``jid`` |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
279 Full JID corresponding to the AP actor. |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
280 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
281 ``jid_user`` |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
282 Only the user part of the JID (what is before the ``@``) |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
283 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
284 ``node`` |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
285 Name of the pubsub node corresponding to the AP actor. |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
286 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
287 ``item`` |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
288 ID of the XMPP pubsub item. |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
289 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
290 You can use a slash ``/`` followed by a part of a node name to filter only on specific |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
291 nodes. For instance, if you want to redirect microblog items to a different URL that |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
292 event items, you can use ``item/urn:xmpp:microblog:0`` and ``item/urn:xmpp:events:0``, |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
293 the first redirection to match will be used. Note that anything containing the filter |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
294 value will match, thus you can also use ``item/microblog`` (but it then would match an |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
295 event which has ``microblog`` in is node name). |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
296 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
297 You can also use a dictionary as value instead of the target URL. This can be useful to |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
298 filter on an other value than the node name, if you want to make specific redirection |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
299 for a particular user for instance. If you use a dictionary, you must use a ``url`` key |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
300 with the target URL (which may have template values as usual), and you may use a |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
301 ``filters`` key mapping to an other dictionary where each key is a filter on a specific |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
302 template value (in other words: key is the template value, like ``jid`` or ``node``, and |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
303 value is the filter to match). |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
304 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
305 *examples* |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
306 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
307 Redirect actor page to ``/profile/<JID user part>``, blogs items to ``/blog/<full |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
308 JID>/<node name>/<item id>`` and events items to ``/event/<full JID>/<node name>/<item |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
309 id>`` :: |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
310 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
311 html_redirect_dict = { |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
312 "actor": "/profile/{jid_user}", |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
313 "item/microblog": "/blog/{jid}/{node}/{item}", |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
314 "item/events": "/event/{jid}/{node}/{item}" |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
315 } |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
316 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
317 Redirect items of user ``louise@example.org`` to ``/b/<item>``:: |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
318 |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
319 html_redirect_dict = { |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
320 "item": { |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
321 "url": "/b/{item}", |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
322 filters: { |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
323 "jid": "louise@example.org" |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
324 } |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
325 } |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
326 } |
|
97fbe11c4476
doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents:
3910
diff
changeset
|
327 |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
328 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
329 .. _ap-actor-from-xmpp: |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
330 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
331 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
|
332 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
333 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
334 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
|
335 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
|
336 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
|
337 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
338 `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
|
339 must be escaped with ``\40``. |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
340 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
341 .. _XEP-0106: JID Escaping |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
342 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
343 **example** |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
344 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
345 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
|
346 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
|
347 ``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
|
348 ``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
|
349 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
350 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
|
351 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
|
352 ``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
|
353 actor identifier rather than an XMPP JID. |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
354 |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
355 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
356 .. _xmpp-node-from-ap: |
|
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 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
|
359 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
360 |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
361 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
|
362 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
363 - 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
|
364 - 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
|
365 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
366 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
367 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
|
368 like this: |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
369 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
370 - 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
|
371 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
|
372 JID can be directly used as AP actor handle |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
373 - 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
|
374 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
|
375 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
|
376 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
|
377 ``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
|
378 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
|
379 - 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
|
380 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
|
381 from entity: ``some_node--some_user@example.org`` |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
382 - 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
|
383 special encoding (see below). |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
384 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
385 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
|
386 |
|
4077
d6837db456fd
refactoring: fix names in doc following modules hierarchy refactoring
Goffi <goffi@goffi.org>
parents:
4037
diff
changeset
|
387 .. automethod:: libervia.backend.plugins.plugin_comp_ap_gateway.APGateway.get_jid_and_node |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
388 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
389 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
390 .. [#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
|
391 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
|
392 handles, according to `RFC7565`_, should |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
393 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
|
394 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
395 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
|
396 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
|
397 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
|
398 way to encode characters had to be found. |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
399 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
400 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
|
401 https://github.com/mastodon/mastodon/issues/17222 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
402 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
403 .. _RFC7565: https://datatracker.ietf.org/doc/html/rfc7565 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
404 .. [#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
|
405 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
406 **example** |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
407 |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
408 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
|
409 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
|
410 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
|
411 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
412 .. note:: |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
413 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
414 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
|
415 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
|
416 |
|
3910
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
417 .. _ap-ad-hoc: |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
418 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
419 Ad-Hoc Commands |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
420 ~~~~~~~~~~~~~~~ |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
421 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
422 The gateway supports `XEP-0050 (Ad-Hoc Commands)`_. For now, only the following node is |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
423 provided: |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
424 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
425 ``https://libervia.org/ap_gateway/xmpp_jid_node_2_ap_actor`` |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
426 Convert XMPP JID and Node to corresponding virtual actor. Node is optional. |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
427 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
428 .. _XEP-0050 (Ad-Hoc Commands): https://xmpp.org/extensions/xep-0050.html |
|
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
429 |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
430 Getting AP Message from XMPP |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
431 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
432 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
433 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
|
434 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
|
435 :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
|
436 as regular XMPP blog items. |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
437 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
438 .. note:: |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
439 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
440 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
|
441 `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
|
442 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
|
443 will then be cached, and efficiently delivered. |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
444 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
445 .. _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
|
446 .. _RSM: https://xmpp.org/extensions/xep-0059.html |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
447 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
448 Getting XMPP Items from ActivityPub |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
449 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
450 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
451 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
|
452 :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
|
453 handle in AP implementations, e.g.: ``@louise@example.org``). |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
454 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
455 .. note:: |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
456 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
457 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
|
458 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
|
459 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
|
460 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
461 |
|
3746
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
462 .. _ap-xmpp-threads-conversion: |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
463 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
464 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
|
465 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
466 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
467 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
|
468 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
|
469 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
|
470 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
|
471 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
472 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
|
473 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
|
474 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
|
475 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
|
476 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
|
477 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
478 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
|
479 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
480 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
|
481 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
|
482 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
|
483 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
|
484 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
485 root message ┑ |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
486 ┕ 1 ┑ |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
487 ┕ 2 ┑ |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
488 ┕ 3 ┑ |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
489 ┕ 4 ┑ |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
490 ┕ 5 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
491 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
492 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
|
493 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
|
494 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
495 root message ┑ |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
496 ┕ 1 ┑ |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
497 ┝ 2 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
498 ┝ 3 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
499 ┝ 4 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
500 ┕ 5 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
501 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
502 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
|
503 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
|
504 |
|
fa3dc4ed7906
doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents:
3734
diff
changeset
|
505 .. _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
|
506 |
|
3772
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
507 Publishing an Item |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
508 ~~~~~~~~~~~~~~~~~~ |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
509 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
510 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
|
511 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
|
512 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
|
513 AP and XMPP end users. |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
514 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
515 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
|
516 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
|
517 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
|
518 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
519 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
|
520 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
|
521 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
|
522 that Louise has initially published. |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
523 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
524 Following, Subscribing and Cache |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
525 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
526 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
527 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
|
528 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
|
529 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
|
530 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
|
531 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
|
532 pagination). |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
533 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
534 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
|
535 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
|
536 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
537 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
|
538 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
|
539 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
540 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
|
541 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
542 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
|
543 *follow* activity on AP side, and vice versa. |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
544 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
545 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
|
546 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
|
547 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
|
548 specific topic or published at specific time range. |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
549 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
550 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
|
551 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
552 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
|
553 will be subscribed to or unsubscribed from. |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
554 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
555 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
|
556 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
557 .. _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
|
558 .. _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
|
559 .. _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
|
560 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
561 Following/Followers Collections and Public Pubsub Subscription |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
562 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
563 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
564 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
|
565 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
566 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
|
567 microblog node. |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
568 |
|
98ba02637436
doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents:
3746
diff
changeset
|
569 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
|
570 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
|
571 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
|
572 |
|
3810
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
573 .. _ap-message_delivery: |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
574 |
|
3786
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
575 Messages Delivery |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
576 ~~~~~~~~~~~~~~~~~ |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
577 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
578 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
|
579 (Microblogging over XMPP)`_ when suitable) or to XMPP messages (`<message>` stanzas, i.e. |
| 3790 | 580 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
|
581 other direction (XMPP → ActivityPub). |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
582 |
| 3790 | 583 A received AP item will be converted to an XMPP pubsub item if any of the following |
| 584 conditions is fulfilled: | |
|
3786
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
585 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
586 - it is addressed to the special `*public* collection`_ |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
587 - it is addressed to a local *followers* collection |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
588 |
| 3790 | 589 A received AP item will be converted to an XMPP message if all the following conditions |
| 590 are fulfilled: | |
|
3786
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
591 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
592 - it is **not** addressed to the special *public* collection |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
593 - it is **not** addressed to a any local *followers* collection. |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
594 |
| 3790 | 595 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
|
596 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
|
597 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
|
598 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
599 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
|
600 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
|
601 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
|
602 item will have the special *public* collection added. |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
603 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
604 .. note:: |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
605 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
606 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
|
607 privacy as XMPP. |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
608 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
609 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
|
610 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
|
611 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
612 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
|
613 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
|
614 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
|
615 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
|
616 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
|
617 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
618 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
|
619 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
|
620 ActivityPub and its implementations evolve. |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
621 |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
622 .. _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
|
623 .. _*public* collection: https://www.w3.org/TR/activitypub/#public-addressing |
|
cebfdfff3e99
doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents:
3772
diff
changeset
|
624 .. _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
|
625 |
|
3810
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
626 Message/Item Retraction |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
627 ~~~~~~~~~~~~~~~~~~~~~~~ |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
628 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
629 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
|
630 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
|
631 be notified of the retraction. |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
632 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
633 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
|
634 be sent to subscribers. |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
635 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
636 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
|
637 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
|
638 and vice versa). |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
639 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
640 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
|
641 XEPs. |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
642 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
643 .. note:: |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
644 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
645 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
|
646 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
|
647 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
648 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
|
649 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
|
650 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
|
651 (and not only ActivityPub or XMPP). |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
652 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
653 Be sure to understand that before sending anything sensitive. |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
654 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
655 .. note:: |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
656 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
657 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
|
658 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
|
659 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
|
660 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
661 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
|
662 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
|
663 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
664 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
|
665 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
|
666 silently, you may not be notified). |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
667 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
668 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
|
669 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
|
670 items. |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
671 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
672 .. _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
|
673 .. _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
|
674 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
675 Blocking an User |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
676 ~~~~~~~~~~~~~~~~ |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
677 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
678 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
|
679 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
|
680 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
681 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
|
682 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
|
683 :ref:`libervia-cli_blocking`). |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
684 |
|
29380ef68dbe
doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents:
3790
diff
changeset
|
685 .. _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
|
686 |
|
3827
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
687 Identity and Avatar |
|
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
688 ~~~~~~~~~~~~~~~~~~~ |
|
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
689 |
|
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
690 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
|
691 |
| 3838 | 692 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
|
693 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
|
694 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
|
695 (it's generally a self-description of users). |
|
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
696 |
|
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
697 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
|
698 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
|
699 for future requests. |
|
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
700 |
|
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
701 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
|
702 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
|
703 |
|
23b53ac87e0f
doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents:
3810
diff
changeset
|
704 .. _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
|
705 .. _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
|
706 .. _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
|
707 |
| 3838 | 708 Mentions |
| 709 ~~~~~~~~ | |
| 710 | |
| 711 Mentions are converted by the gateway under some conditions explained below. | |
| 712 | |
| 713 When receiving an AP item which converts to a pubsub item (i.e. not a direct message), for | |
| 714 any local user mentioned (using a tag of type ``Mention``) or directly specified in a | |
| 715 target field (``to``, ``bto``, ``cc`` or ``bcc``), a `XEP-0372 (References)`_ type mention | |
| 716 will be emitted. | |
| 717 | |
| 718 This is not done for direct message as the recipients are already specified, and sending | |
| 719 reference is most probably not desired for a private message. | |
| 720 | |
| 721 In the direction XMPP 🠞 ActivityPub, it's more complicated because XMPP sends references | |
| 722 separately from the pubsub item, while ActivityPub links them in the same item. | |
| 723 | |
| 724 If a XEP-0372 reference targeting an AP actor is received and anchor a pubsub item, the | |
| 725 item will be looked after in cache. If found, it will be converted to an AP item, a | |
| 726 mention will be added, and the item will be delivered to the mentioned entity. | |
| 727 | |
| 728 This only works if the mentioned actor is on a server which has not already received the | |
| 729 original item, because otherwise the AP implementation will most probably ignore the new | |
| 730 item which has the same ID. | |
| 731 | |
| 732 It is hard to avoid sending first published item, then the same item with the reference, | |
| 733 because XEP-0372 references are received after the published items. | |
| 734 | |
| 735 To work around that, when an XMPP blog item is received, its body is scanned to find | |
| 736 ``@user@server.tld`` type mention, and if found a mention is automatically added to the | |
| 737 resulting AP item. | |
| 738 | |
| 739 It is not ideal to parse the body, but that's an acceptable trade-off to make mention | |
| 740 working. This behaviour is activated by default, but can be deactivated by setting | |
| 741 ``auto_mentions`` option to ``false``. Auto mentions are only used for pubsub items, and | |
| 742 not for direct messages for the same reason as mention are not checked in AP direct | |
| 743 messages (see above). | |
| 744 | |
| 745 .. note:: | |
| 746 | |
| 747 For auto mentions, it's the AP actor handle which must be used, not the corresponding | |
| 748 virtual JID. | |
| 749 | |
| 750 If you want to mention ``louise@example.org`` then you must use directly | |
| 751 ``@louise@example.org``, and NOT something like | |
| 752 ``@louise\40example.org@ap.example.net``. | |
| 753 | |
| 754 To mention XMPP entities, your client must use XEP-0372 references directly. | |
| 755 | |
| 756 .. _XEP-0372 (References): https://xmpp.org/extensions/xep-0372.html | |
| 757 | |
|
3874
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
758 Repeat/Share/Reboost |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
759 ~~~~~~~~~~~~~~~~~~~~ |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
760 |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
761 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
|
762 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
|
763 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
|
764 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
|
765 |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
766 .. _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
|
767 |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
768 Noticed/Like |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
769 ~~~~~~~~~~~~ |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
770 |
|
3892
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
771 AP's ``Like`` activity is converted on the XMPP side to "`XEP-0470 (Pubsub |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
772 Attachments)`_". ``Like`` is converted to ``noticed`` attachment, meaning that it used in |
|
3874
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
773 to indicate that something has been seen and taken into account, without really indication |
|
3892
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
774 if the content is liked or disliked (see XEP-0470 § Foreword: `"noticed" instead of "like" |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
775 or "favourite"`_ for the rational). |
|
3874
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
776 |
|
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
777 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
|
778 |
|
3892
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
779 .. _XEP-0470 (Pubsub Attachments): https://xmpp.org/extensions/xep-0470.html |
|
3874
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
780 .. _XMPP Council: https://xmpp.org/about/xmpp-standards-foundation/ |
|
3892
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
781 .. _"noticed" instead of "like" or "favourite": https://xmpp.org/extensions/xep-0470.html#noticed-foreword |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
782 |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
783 Reactions |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
784 ~~~~~~~~~ |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
785 |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
786 Reactions are not specified in `base ActivityPub specification`_. However `Pleroma`_, a |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
787 software implemeting ActivityPub, implements them using a non standardised (yet?) |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
788 ``EmojiReact`` activity. Liberva AP Gateway use it to handle reactions. |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
789 |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
790 On the XMPP side, `XEP-0470 (Pubsub Attachments)`_ is once again used. |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
791 |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
792 Libervia also implements `XEP-0444 (Message Reactions)`_ for messages, but because Pleroma |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
793 doesn't handle reactions for direct messages, this is not used in the Libervia AP gateway. |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
794 If in the future an AP implementation uses reactions on direct messages, it will be |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
795 straightforward to add it in the AP gateway. |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
796 |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
797 .. _base ActivityPub specification: https://www.w3.org/TR/activitypub/ |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
798 .. _Pleroma: https://pleroma.social/ |
|
ba78cc0c8d59
doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents:
3885
diff
changeset
|
799 .. _XEP-0444 (Message Reactions): https://xmpp.org/extensions/xep-0444.html |
|
3874
c2b292d30c66
doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents:
3838
diff
changeset
|
800 |
|
3910
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
801 Events |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
802 ~~~~~~ |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
803 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
804 This gateway manages events. On the XMPP side, the ``Events`` protoXEP is used, on AP side |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
805 ``Event`` objects are used. `Mobilizon`_ is used as reference implementation here. |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
806 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
807 .. note:: |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
808 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
809 The ``Events`` protoXEP has been proposed but not published or reviewed by XMPP council |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
810 yet. The current version is availale at https://github.com/xsf/xeps/pull/1206 and |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
811 hopefully it will eventually become an official experimental XEP. The code and this |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
812 documentation will be updated as the standard evolves. |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
813 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
814 To retrieve AP events from XMPP, use the corresponding virtual JID as explained in |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
815 :ref:`ap-actor-from-xmpp` with the event node (which is ``urn:xmpp:events:0``). |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
816 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
817 *example:* |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
818 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
819 To retrieve events from AP actor with the handle ``somebody@mobilizon.example``, throught |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
820 the ``ap.example.org`` gateway, the ``somebody\40mobilizon.example@ap.example.org`` JID |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
821 can be used with the ``urn:xmpp:events:0`` node. |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
822 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
823 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
824 To retrieve XMPP events from AP, you need to the virtual actor corresponding to the JID |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
825 of the pubsub/PEP service with the event node (starting with ``urn:xmpp:events:0``), as |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
826 explained in :ref:`xmpp-node-from-ap`. You can use :ref:`ap-ad-hoc` to easily convert your |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
827 JID/node combination to a virtual AP actor. Note that the resulting virtual actor is |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
828 unaesthetic due to the presence of event node and the constraints explained in |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
829 :ref:`xmpp-node-from-ap`. |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
830 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
831 To retrieve the link to the XMPP item from AP, you can use the ID from the generated AP |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
832 object. The ID can also be constructed by hand by using the URL |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
833 ``https://<ap_gateway_public_domain>/_ap/<virtual_actor>/<event_item_id>``. |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
834 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
835 *example:* |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
836 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
837 to retrieve from AP the XMPP event at pubsub service ``pubsub.example.net`` on node |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
838 ``urn:xmpp:events:0/party`` with item ID ``picnic_abd1``, and using the AP gateway with |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
839 public url ``https://ap.example.net``, the following link can be used:: |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
840 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
841 https://ap.example.net/_ap/___urn.3Axmpp.3Aevents.3A0.2Fparty---pubsub.2eexample.2enet@ap.tazar3.int/picnic_abd1 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
842 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
843 If you paste it in an AP implementation featuring events (e.g. Mobilizon), the event |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
844 should appear and you should be able to comment it and participate to it. |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
845 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
846 Event comments are supported, the node to use is indicated in the event XMPP item as |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
847 specified in the protoXEP, this should be transparent to end-user. |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
848 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
849 Participation to an event is supported through the RSVP mechanism on XMPP and with |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
850 ``Join`` and ``Leave`` activities on AP. Note that XMPP allows more nuances with its RSVP |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
851 mechanism (it's possible to say if someone will "maybe" attend an event, and to request |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
852 any kind of extra informations) while AP only indicates if one will attend or not an |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
853 event. |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
854 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
855 |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
856 .. _Mobilizon: https://joinmobilizon.org/ |
|
199598223f82
doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents:
3892
diff
changeset
|
857 |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
858 Using the Component (for developers) |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
859 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
860 |
|
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
861 Publication of AP items can be tested using the following method (with can be accessed |
|
4037
524856bd7b19
massive refactoring to switch from camelCase to snake_case:
Goffi <goffi@goffi.org>
parents:
3984
diff
changeset
|
862 through the ``ap_send`` bridge method, client is then replaced by the ``profile`` name, as |
|
3734
643622ff1492
doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents:
3683
diff
changeset
|
863 last argument): |
|
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
864 |
|
4077
d6837db456fd
refactoring: fix names in doc following modules hierarchy refactoring
Goffi <goffi@goffi.org>
parents:
4037
diff
changeset
|
865 .. automethod:: libervia.backend.plugins.plugin_comp_ap_gateway.APGateway.publish_message |
|
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
866 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
867 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
|
868 <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
|
869 use the D-Bus bridge). |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
870 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
871 example |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
872 ~~~~~~~ |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
873 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
874 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
|
875 ``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
|
876 Louise can use the following command:: |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
877 |
|
4037
524856bd7b19
massive refactoring to switch from camelCase to snake_case:
Goffi <goffi@goffi.org>
parents:
3984
diff
changeset
|
878 $ li debug bridge method -c ap_send '"{\"node\": \"https://example.net/@pierre/106986412193109832\", \"content\": \"A lille hello from XMPP\"}","pierre\\40example.net@ap.example.org", "louise"' |
|
3683
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
879 |
|
a1eff4e32848
doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents:
3678
diff
changeset
|
880 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
|
881 object. |