Mercurial > libervia-backend

annotate doc/components.rst @ 3913:944f51f9c2b4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
core (xmpp): make `send` a blocking method, fix `sendMessageData` calls: original `send` method is blocking, and it is used as such by Wokkel and thus can't be changed to an async method easily. However, an Async method is necessary to have an async trigger at the very end of the send workflow for end-to-end encryption. To workaround that, `send` is an async method which call `a_send`, an async method which actually does the sending. This way legacy method can still call `send` while `a_send` can be await otherwise. Fix calls to `sendMessageData`: the method now being an `async` one, `ensureDeferred` had to be used in some calls.
author Goffi <goffi@goffi.org>
date Sat, 24 Sep 2022 16:31:39 +0200
parents 199598223f82
children 97fbe11c4476
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3678
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
1 .. _components:
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
2
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
3 ===================
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
4 Libervia Components
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
5 ===================
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
6
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
7 Libervia can act as an XMPP server component, which can be seen as a generic plugin for
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
8 XMPP servers.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
9
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
10 This page explains which components are available and how to use them.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
11
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
12 Running a component
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
13 ===================
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
14
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
15 Components are linked to a Libervia profile in the same way as normal clients.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
16
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
17 To run a component, you'll need to know its *entry point*, which is the name of the import
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
18 name of plugin managing it. The entry point to use will be specified in the component
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
19 installation documentation.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
20
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
21 You'll also have to declare the component on your XMPP server, this is a server dependent
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
22 step and you'll have to check your server documentation for details. You'll have to
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
23 specify a **shared secret** (can also be named simply *password*) that must be set both on
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
24 the XMPP server and as the XMPP password of the Libervia profile.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
25
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
26 Here is a list of relevant documentation for most common servers:
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
27
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
28 ejabberd
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
29 https://docs.ejabberd.im/admin/configuration/listen-options/
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
30
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
31 MongooseIm
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
32 https://esl.github.io/MongooseDocs/latest/configuration/listen/#xmpp-components-listenservice
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
33
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
34 OpenFire
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
35 use the web-based admin panel
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
36
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
37 Prosody
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
38 https://prosody.im/doc/components
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
39
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
40 Tigase
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
41 https://docs.tigase.net/tigase-server/stable-snapshot/Administration_Guide/webhelp/externalComponentConfiguration.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
42
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
43
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
44 On Libervia, setup is done with Libervia CLI's :ref:`profile create <li_profile_create>`
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
45 command.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
46
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
47 You'll usually want to have the component to start automatically when the backend
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
48 is started, for this you must unset the profile password (not to be confused with the XMPP
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
49 password which is the one also set on the server configuration) with ``-p ""`` and set
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
50 auto-connection with ``-A``.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
51
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
52 You'll specify the XMPP password (also named *shared secret* in `XEP-0144`_ terminology)
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
53 with ``-x <your_shared_secret>`` and the JID to use with ``-j
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
54 <component_subdomain>.<server.tld>``.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
55
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
56 The component entry point is specified with ``-C <entry_point>``.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
57
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
58 .. _XEP-0144: https://xmpp.org/extensions/xep-0114.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
59
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
60 example
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
61 -------
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
62
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
63 Louise wants to run an ActivityPub gateway on her server ``example.org`` with the JID
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
64 ``ap.example.org``. The shared secret is ``xmpp_rocks`` and she wants the component to
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
65 start automatically with the backend, thus she doesn't set a profile password. The
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
66 entry-point for ActivityPub component is ``ap-gateway``, and she wants to use the same
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
67 name for the profile. To do this, she enters the following command::
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
68
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
69 $ li profile create ap-gateway -j ap.example.org -p "" -x xmpp_rocks -C ap-gateway -A
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
70
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
71 The component will then be started next time Libervia Backend is launched. If Louise
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
72 wants to connect it immediately, she can use::
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
73
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
74 $ li profile connect -cp ap-gateway
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
75
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
76 Available Components
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
77 ====================
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
78
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
79 Below is a list of currently available components in Libervia, and instructions on what
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
80 they do and how to use them.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
81
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
82
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
83 File Sharing
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
84 ------------
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
85
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
86 **entry_point:** ``file-sharing``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
87
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
88 File Sharing component manage the hosting of user files. Users can upload file there using
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
89 either `Jingle File Transfer`_ or `HTTP File Upload`_.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
90
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
91 There is no limit to the size of files which can be uploaded, but administrators can set a
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
92 quota to limit the space that can be used.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
93
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
94 Files can be retrieved using `File Information Sharing`_, and deleted using `Ad-Hoc Commands`_.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
95
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
96 Files can be shared with a public HTTP link, or made available only to a specified list of
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
97 entities (JIDs). Permissions can be set through Ad-Hoc Commands.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
98
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
99 .. _Jingle File Transfer: https://xmpp.org/extensions/
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
100 .. _HTTP File Upload: https://xmpp.org/extensions/xep-0363.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
101 .. _File Information Sharing: https://xmpp.org/extensions/xep-0329.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
102 .. _Ad-Hoc Commands: https://xmpp.org/extensions/xep-0050.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
103
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
104 Configuration
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
105 ~~~~~~~~~~~~~
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
106
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
107 All options are to be set in ``[component file-sharing]`` section.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
108
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
109 ``http_upload_port``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
110 port to use for HTTP File Upload
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
111
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
112 **default**: 8888
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
113
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
114 ``http_upload_connection_type``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
115 either ``http`` or ``https``.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
116
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
117 **default**: ``https``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
118
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
119 Note that HTTP Upload should always be ``https`` to end-user, the ``http`` option is to
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
120 be used only if you use a HTTP server as a proxy, and this server is already set for
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
121 TLS.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
122
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
123 ``http_upload_public_facing_url``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
124 must be set to the URL that end-user will see. Notably useful if the component is behind
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
125 a proxy.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
126
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
127 **default**: ``https://<component host>:<http_upload_port``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
128
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
129 ``quotas_json``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
130 a JSON object indicating quotas to use for users. The object can have 3 keys:
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
131
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
132 ``admins``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
133 quotas to use for administrators (i.e. profiles set in ``admins_list``)
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
134
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
135 ``users``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
136 quotas to use for normal users (i.e. non admin profiles)
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
137
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
138 ``jids``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
139 per-jid specific quotas. The value is a JSON object where key is a user bare jid and
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
140 value is a quota.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
141
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
142 Quotas can be either ``null`` for unlimited space, or a size value (`SI prefixes and
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
143 binary prefixes`_ can be used).
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
144
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
145 example::
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
146
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
147 quotas_json = {
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
148 "admins": null,
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
149 "users": "50 Mio",
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
150 "jids": {"pierre@example.org": "1 Gio"}
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
151 }
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
152
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
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
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
240 ``auto_mentions``
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
241 A boolean value indicating if received XMPP pubsub blog items bodies must be scanned to
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
242 find ``@user@server.tld`` type mentions. If mentions are found, they'll be added to the
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
243 resulting AP items.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
244
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
245 **default**: ``true``
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
246
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
247
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
248 .. _ap-actor-from-xmpp:
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
249
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
250 How to Address an AP Actor from XMPP
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
252
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
253 When addressing an ActivityPub actor from XMPP, you must use a JID corresponding to the
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
254 actor. The domain part of the JID correspond to the gateway JID (the one set in gateway
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
255 profile), while the local part (before the ``@``) is used to specify the AP actor.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
256
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
257 `XEP-0106`_ (JID Escaping) is used to indicate the AP actor identifier, thus the ``@``
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
258 must be escaped with ``\40``.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
259
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
260 .. _XEP-0106: JID Escaping
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
261
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
262 **example**
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
263
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
264 If Louise wants to talk to Pierre which is on the ``example.net`` AP server, she can use
3885
18ff4f75f0e6 doc (components): the word "handle" is more adapted here
Goffi <goffi@goffi.org>
parents: 3874
diff changeset
265 her XMPP AP gateway which is at ``ap.example.org``. Pierre AP's actor handle is
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
266 ``pierre@example.net``, Louise can access it via the JID
3810
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
267 ``pierre\40example.net@ap.example.org`` (we call it *virtual JID* of the AP actor).
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
268
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
269 Of course, this is a bit cumbersome to do by hand, it is expected that XMPP clients will
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
270 do the (un)escaping automatically for end-user, in a way that Louise could enter
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
271 ``pierre@example.net`` directly, with an indicator to show that this is an ActivityPub
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
272 actor identifier rather than an XMPP JID.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
273
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
274
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
275 .. _xmpp-node-from-ap:
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
276
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
277 How to Address an XMPP Entity from AP
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
278 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
279
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
280 To access an XMPP entity, it is a little bit more complicated for 2 reasons:
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
281
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
282 - XMPP use a wider range of allowed characters than most AP implementations [#AP_chars]_.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
283 - to get XMPP items, we need 2 data: the entity JID, and a pubsub node
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
284
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
285
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
286 However, Libervia AP gateway tries to make it as user friendly as possible, thus it works
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
287 like this:
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
288
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
289 - in the most common case, one just wants to access the personal blog of a user, and basic
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
290 ASCII characters (with possibly ``-``, ``_`` or ``.``) are used. in this case, the XMPP
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
291 JID can be directly used as AP actor handle
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
292 - when a pubsub node needs to be specified it is most of time with a pubsub JID which has
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
293 not user part (something like ``pubsub.example.org``). In this case, the pubsub node can
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
294 be used as AP actor handle's user part, Libervia will use XMPP discovery to know that
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
295 it's a pubsub service. So if you want to access the blog named ``xmpp_news`` at
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
296 ``pubsub.example.org``, you can use the handle ``xmpp_news@pubsub.example.org`` (be sure
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
297 that the domain ``pubsub.example.org`` links to the Libervia AP gateway HTTP server)
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
298 - if you want to use a specific node with an entity which already has a user part, then a
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
299 special encoding must be used, where ``---`` (three dashes) are used to separate node
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
300 from entity: ``some_node--some_user@example.org``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
301 - if you need to use special characters, then you'll have to use ``___`` followed by the
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
302 special encoding (see below).
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
303
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
304 The encoding is explained in the documentation of the following method:
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
305
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
306 .. automethod:: sat.plugins.plugin_comp_ap_gateway.APGateway.getJIDAndNode
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
307
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
308
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
309 .. [#AP_chars] Most if not all AP implementations use webfinger `acct` URI as a de-facto
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
310 standard to manage user-friendly handles (something like ``user@example.org``). Those
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
311 handles, according to `RFC7565`_, should
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
312 manage a wide variety of characters thanks to the support of percent-encoding.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
313
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
314 Unfortunately, at least one of the most-used AP implementation (Mastodon, which is used
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
315 a reference implementation for this gateway), only uses a limited subset of allowed
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
316 characters. In addition, Mastodon needs an associated handle [#m_wf]_ thus an alternate
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
317 way to encode characters had to be found.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
318
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
319 An issue has been opened to improve this situation on Mastodon bug tracker:
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
320 https://github.com/mastodon/mastodon/issues/17222
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
321
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
322 .. _RFC7565: https://datatracker.ietf.org/doc/html/rfc7565
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
323 .. [#m_wf] https://docs.joinmastodon.org/spec/webfinger/
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
324
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
325 **example**
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
326
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
327 If Pierre wants to talk to Louise, he can directly use the JID which is the same as the AP
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
328 actor identifier, i.e. ``louise@example.org`` (note that on AP software, a ``@`` prefix is
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
329 often required, thus Pierre will look for ``@louise@example.org``).
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
330
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
331 .. note::
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
332
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
333 The actor endpoint can also be used directly in AP software (in the example above, it
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
334 would be by default ``https://example.org/_ap/actor/louise%40example.org``).
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
335
3910
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
336 .. _ap-ad-hoc:
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
337
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
338 Ad-Hoc Commands
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
339 ~~~~~~~~~~~~~~~
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
340
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
341 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
342 provided:
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
343
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
344 ``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
345 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
346
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
347 .. _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
348
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
349 Getting AP Message from XMPP
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
350 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
351
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
352 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
353 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
354 :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
355 as regular XMPP blog items.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
356
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
357 .. note::
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
358
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
359 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
360 `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
361 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
362 will then be cached, and efficiently delivered.
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
363
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
364 .. _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
365 .. _RSM: https://xmpp.org/extensions/xep-0059.html
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 Getting XMPP Items from ActivityPub
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
368 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 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
371 :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
372 handle in AP implementations, e.g.: ``@louise@example.org``).
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
373
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
374 .. note::
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
375
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
376 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
377 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
378 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
379
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
380
3746
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
381 .. _ap-xmpp-threads-conversion:
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
382
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
383 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
384 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
385
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
386 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
387 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
388 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
389 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
390
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
391 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
392 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
393 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
394 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
395 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
396
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
397 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
398
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
399 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
400 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
401 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
402 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
403
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
404 root message ┑
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
405 ┕ 1 ┑
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
406 ┕ 2 ┑
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
407 ┕ 3 ┑
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
408 ┕ 4 ┑
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
409 ┕ 5
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
410
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
411 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
412 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
413
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
414 root message ┑
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
415 ┕ 1 ┑
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
416 ┝ 2
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
417 ┝ 3
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
418 ┝ 4
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
419 ┕ 5
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
420
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
421 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
422 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
423
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
424 .. _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
425
3772
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
426 Publishing an Item
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
427 ~~~~~~~~~~~~~~~~~~
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
428
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
429 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
430 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
431 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
432 AP and XMPP end users.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
433
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
434 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
435 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
436 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
437
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
438 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
439 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
440 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
441 that Louise has initially published.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
442
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
443 Following, Subscribing and Cache
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
444 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
445
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
446 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
447 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
448 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
449 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
450 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
451 pagination).
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
452
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
453 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
454 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
455
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
456 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
457 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
458
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
459 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
460
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
461 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
462 *follow* activity on AP side, and vice versa.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
463
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
464 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
465 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
466 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
467 specific topic or published at specific time range.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
468
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
469 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
470
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
471 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
472 will be subscribed to or unsubscribed from.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
473
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
474 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
475
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
476 .. _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
477 .. _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
478 .. _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
479
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
480 Following/Followers Collections and Public Pubsub Subscription
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
481 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
482
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
483 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
484
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
485 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
486 microblog node.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
487
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
488 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
489 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
490 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
491
3810
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
492 .. _ap-message_delivery:
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
493
3786
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
494 Messages Delivery
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
495 ~~~~~~~~~~~~~~~~~
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
496
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
497 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
498 (Microblogging over XMPP)`_ when suitable) or to XMPP messages (`<message>` stanzas, i.e.
3790
24f70a29e382 doc (components): typo/spelling
Goffi <goffi@goffi.org>
parents: 3786
diff changeset
499 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
500 other direction (XMPP → ActivityPub).
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
501
3790
24f70a29e382 doc (components): typo/spelling
Goffi <goffi@goffi.org>
parents: 3786
diff changeset
502 A received AP item will be converted to an XMPP pubsub item if any of the following
24f70a29e382 doc (components): typo/spelling
Goffi <goffi@goffi.org>
parents: 3786
diff changeset
503 conditions is fulfilled:
3786
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
504
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
505 - it is addressed to the special `*public* collection`_
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
506 - it is addressed to a local *followers* collection
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
507
3790
24f70a29e382 doc (components): typo/spelling
Goffi <goffi@goffi.org>
parents: 3786
diff changeset
508 A received AP item will be converted to an XMPP message if all the following conditions
24f70a29e382 doc (components): typo/spelling
Goffi <goffi@goffi.org>
parents: 3786
diff changeset
509 are fulfilled:
3786
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
510
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
511 - it is **not** addressed to the special *public* collection
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
512 - it is **not** addressed to a any local *followers* collection.
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
513
3790
24f70a29e382 doc (components): typo/spelling
Goffi <goffi@goffi.org>
parents: 3786
diff changeset
514 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
515 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
516 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
517
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
518 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
519 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
520 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
521 item will have the special *public* collection added.
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
522
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
523 .. note::
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
524
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
525 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
526 privacy as XMPP.
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
527
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
528 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
529 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
530
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
531 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
532 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
533 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
534 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
535 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
536
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
537 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
538 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
539 ActivityPub and its implementations evolve.
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
540
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
541 .. _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
542 .. _*public* collection: https://www.w3.org/TR/activitypub/#public-addressing
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
543 .. _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
544
3810
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
545 Message/Item Retraction
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
546 ~~~~~~~~~~~~~~~~~~~~~~~
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
547
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
548 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
549 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
550 be notified of the retraction.
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
551
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
552 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
553 be sent to subscribers.
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
554
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
555 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
556 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
557 and vice versa).
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
558
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
559 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
560 XEPs.
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
561
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
562 .. note::
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
563
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
564 When 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
565 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
566
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
567 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
568 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
569 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
570 (and not only ActivityPub or XMPP).
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
571
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
572 Be sure to understand that before sending anything sensitive.
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
573
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
574 .. note::
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
575
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
576 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
577 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
578 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
579
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
580 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
581 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
582
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
583 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
584 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
585 silently, you may not be notified).
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
586
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
587 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
588 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
589 items.
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
590
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
591 .. _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
592 .. _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
593
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
594 Blocking an User
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
595 ~~~~~~~~~~~~~~~~
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
596
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
597 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
598 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
599
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
600 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
601 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
602 :ref:`libervia-cli_blocking`).
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
603
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
604 .. _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
605
3827
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
606 Identity and Avatar
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
607 ~~~~~~~~~~~~~~~~~~~
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
608
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
609 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
610
3838
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
611 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
612 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
613 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
614 (it's generally a self-description of users).
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
615
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
616 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
617 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
618 for future requests.
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
619
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
620 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
621 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
622
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
623 .. _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
624 .. _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
625 .. _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
626
3838
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
627 Mentions
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
628 ~~~~~~~~
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
629
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
630 Mentions are converted by the gateway under some conditions explained below.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
631
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
632 When receiving an AP item which converts to a pubsub item (i.e. not a direct message), for
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
633 any local user mentioned (using a tag of type ``Mention``) or directly specified in a
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
634 target field (``to``, ``bto``, ``cc`` or ``bcc``), a `XEP-0372 (References)`_ type mention
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
635 will be emitted.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
636
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
637 This is not done for direct message as the recipients are already specified, and sending
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
638 reference is most probably not desired for a private message.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
639
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
640 In the direction XMPP 🠞 ActivityPub, it's more complicated because XMPP sends references
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
641 separately from the pubsub item, while ActivityPub links them in the same item.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
642
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
643 If a XEP-0372 reference targeting an AP actor is received and anchor a pubsub item, the
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
644 item will be looked after in cache. If found, it will be converted to an AP item, a
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
645 mention will be added, and the item will be delivered to the mentioned entity.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
646
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
647 This only works if the mentioned actor is on a server which has not already received the
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
648 original item, because otherwise the AP implementation will most probably ignore the new
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
649 item which has the same ID.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
650
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
651 It is hard to avoid sending first published item, then the same item with the reference,
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
652 because XEP-0372 references are received after the published items.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
653
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
654 To work around that, when an XMPP blog item is received, its body is scanned to find
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
655 ``@user@server.tld`` type mention, and if found a mention is automatically added to the
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
656 resulting AP item.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
657
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
658 It is not ideal to parse the body, but that's an acceptable trade-off to make mention
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
659 working. This behaviour is activated by default, but can be deactivated by setting
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
660 ``auto_mentions`` option to ``false``. Auto mentions are only used for pubsub items, and
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
661 not for direct messages for the same reason as mention are not checked in AP direct
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
662 messages (see above).
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
663
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
664 .. note::
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
665
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
666 For auto mentions, it's the AP actor handle which must be used, not the corresponding
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
667 virtual JID.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
668
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
669 If you want to mention ``louise@example.org`` then you must use directly
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
670 ``@louise@example.org``, and NOT something like
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
671 ``@louise\40example.org@ap.example.net``.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
672
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
673 To mention XMPP entities, your client must use XEP-0372 references directly.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
674
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
675 .. _XEP-0372 (References): https://xmpp.org/extensions/xep-0372.html
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
676
3874
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
677 Repeat/Share/Reboost
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
678 ~~~~~~~~~~~~~~~~~~~~
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
679
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
680 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
681 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
682 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
683 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
684
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
685 .. _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
686
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
687 Noticed/Like
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
688 ~~~~~~~~~~~~
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
689
3892
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
690 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
691 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
692 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
693 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
694 or "favourite"`_ for the rational).
3874
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
695
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
696 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
697
3892
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
698 .. _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
699 .. _XMPP Council: https://xmpp.org/about/xmpp-standards-foundation/
3892
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
700 .. _"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
701
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
702 Reactions
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
703 ~~~~~~~~~
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
704
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
705 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
706 software implemeting ActivityPub, implements them using a non standardised (yet?)
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
707 ``EmojiReact`` activity. Liberva AP Gateway use it to handle reactions.
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
708
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
709 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
710
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
711 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
712 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
713 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
714 straightforward to add it in the AP gateway.
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
715
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
716 .. _base ActivityPub specification: https://www.w3.org/TR/activitypub/
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
717 .. _Pleroma: https://pleroma.social/
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
718 .. _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
719
3910
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
720 Events
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
721 ~~~~~~
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
722
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
723 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
724 ``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
725
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
726 .. note::
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
727
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
728 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
729 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
730 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
731 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
732
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
733 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
734 :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
735
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
736 *example:*
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
737
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
738 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
739 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
740 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
741
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
742
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
743 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
744 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
745 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
746 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
747 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
748 :ref:`xmpp-node-from-ap`.
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
749
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
750 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
751 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
752 ``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
753
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
754 *example:*
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
755
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
756 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
757 ``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
758 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
759
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
760 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
761
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
762 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
763 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
764
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
765 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
766 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
767
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
768 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
769 ``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
770 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
771 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
772 event.
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
773
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
774
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
775 .. _Mobilizon: https://joinmobilizon.org/
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
776
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
777 Using the Component (for developers)
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
778 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
779
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
780 Publication of AP items can be tested using the following method (with can be accessed
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
781 through the ``APSend`` bridge method, client is then replaced by the ``profile`` name, as
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
782 last argument):
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
783
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
784 .. automethod:: sat.plugins.plugin_comp_ap_gateway.APGateway.publishMessage
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
785
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
786 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
787 <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
788 use the D-Bus bridge).
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
789
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
790 example
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
791 ~~~~~~~
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
792
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
793 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
794 ``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
795 Louise can use the following command::
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
796
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
797 $ li debug bridge method -c APSend '"{\"node\": \"https://example.net/@pierre/106986412193109832\", \"content\": \"A lille hello from XMPP\"}","pierre\\40example.net@ap.example.org", "louise"'
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
798
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
799 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
800 object.