Mercurial > libervia-backend

annotate doc/components.rst @ 4291:39ac821ebbdb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
plugin XEP-0167: handle conferences: - SDP can now be answered by component instead of frontend. This is useful for A/V conferences component to handle A/V call jingle sessions. - new `call_update` and method, and `content-add` action preparation. This is not yet used by A/V conference, but it's a preparation for a potential future use. - Add NS_AV_CONFERENCES to features as required by the newly proposed A/V Conferences protoXEP. rel 447
author Goffi <goffi@goffi.org>
date Mon, 29 Jul 2024 03:31:09 +0200
parents 6276242736c3
children 92a886f31581
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 This gateway will provide a bidirectional gateway between XMPP and `ActivityPub`_ (or AP
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
162 below). That means that user from XMPP will be able to follow actors or comments messages
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
163 from any software compatible with ActivityPub protocol, and vice versa.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
164
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
165 .. _ActivityPub: https://activitypub.rocks/
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
166
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
167 .. note::
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
168
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
169 this component is mostly tested with Prosody as XMPP server reference, and Mastodon as
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
170 AP server reference, but it should work with any XMPP or AP server.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
171
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
172 The component launches a HTTP server (necessary to communicate with AP software). This
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
173 server needs to handle HTTP requests made at paths ``/.well-known/webfinger`` and ``/_ap``
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
174 (or the ``ap_path`` set in configuration, see below). If the component is not directly
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
175 facing internet (e.g. integrated in an existing website though a proxy), you'll have to
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
176 redirect the requests made to those path to the HTTP server (i.e. to component host at the
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
177 port set at ``http_port``, see configuration below). Please check your HTTP server
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
178 documentation to find how this must be done.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
179
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
180
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
181 Configuration
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
182 ~~~~~~~~~~~~~
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
183
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
184 All options are to be set in ``[component ap-gateway]`` section.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
185
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
186 ``public_url``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
187 Main user-facing domain of the HTTP server, this will be used to construct all AP URLs
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
188
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
189 **default**: if not set, ``xmpp_domain`` is used. If ``xmpp_domain`` is not set either,
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
190 an error is raised.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
191
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
192 ``http_port``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
193 port where the HTTP server should listen. Port ``80`` is not used directly as it would
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
194 require root privileges, and it is strongly recommended against launching Libervia under
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
195 a privileged account. An HTTP Proxy or a port redirection should be set to redirect the
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
196 ``80`` port to the port specified here.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
197
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
198 **default**: ``8123``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
199
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
200 ``http_connection_type``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
201 either ``http`` or ``https``. If you have a HTTP proxy such as Apache or NGINX which
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
202 already handles HTTPS, you may want to use ``http``.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
203
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
204 **default**: ``https``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
205
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
206 Note that the HTTP server should always use ``https`` with end-user, the ``http`` option
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
207 is only to be used with an HTTPS proxy.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
208
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
209 ``local_only``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
210 A boolean value indicating if the gateway is allowed to convert pubsub node from
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
211 external XMPP service or not. A JID is considered external if its domain part doesn't
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
212 end with the gateway's server. For instance, if a gateway ``ap.example.org`` is set on
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
213 the server ``example.org``, the JIDs ``pierre@example.org`` or
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
214 ``some-node@pubsub.example.org`` will be considered local, but
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
215 ``buenaventura@example.net`` won't (note the different domain).
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
216
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
217 Most of time, ``local_only`` should be used.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
218
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
219 **default**: ``true``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
220
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
221 ``ap_path``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
222 Path prefix to use for ActivityPub request. It's usually not necessary to change the
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
223 default value.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
224
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
225 **default**: ``_ap``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
226
3746
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
227 ``comments_max_depth``
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
228 An integer value indicating the maximum number of comment nodes that can be created. See
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
229 :ref:`ap-xmpp-threads-conversion`
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
230
3838
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
231 ``auto_mentions``
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
232 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
233 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
234 resulting AP items.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
235
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
236 **default**: ``true``
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
237
4260
57ff857bf96e doc (components/AP Gateway): document new `http_sign_get` configuration option.
Goffi <goffi@goffi.org>
parents: 4077
diff changeset
238 ``http_sign_get``
57ff857bf96e doc (components/AP Gateway): document new `http_sign_get` configuration option.
Goffi <goffi@goffi.org>
parents: 4077
diff changeset
239 A boolean value indicating if HTTP ``GET`` request made to AP implementations must be
57ff857bf96e doc (components/AP Gateway): document new `http_sign_get` configuration option.
Goffi <goffi@goffi.org>
parents: 4077
diff changeset
240 signed. Some AP implementations require those requests to be signed, notably Mastodon
57ff857bf96e doc (components/AP Gateway): document new `http_sign_get` configuration option.
Goffi <goffi@goffi.org>
parents: 4077
diff changeset
241 when "secure mode" is activated.
57ff857bf96e doc (components/AP Gateway): document new `http_sign_get` configuration option.
Goffi <goffi@goffi.org>
parents: 4077
diff changeset
242
57ff857bf96e doc (components/AP Gateway): document new `http_sign_get` configuration option.
Goffi <goffi@goffi.org>
parents: 4077
diff changeset
243 **default**: ``true``
57ff857bf96e doc (components/AP Gateway): document new `http_sign_get` configuration option.
Goffi <goffi@goffi.org>
parents: 4077
diff changeset
244
3978
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
245 ``html_redirect_dict``
3984
425d809a505b doc (components): typo
Goffi <goffi@goffi.org>
parents: 3978
diff changeset
246 A dictionary used to redirect HTTP requests when it's not an ActivityPub request (i.e.
3978
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
247 when the ``Accept`` header is not set to ``application/json``). Several ActivityPub
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
248 implementations link to original server when clicking on some links such as post author
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
249 or item ID, and this result in a request to the corresponding ActivityPub endpoint, but
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
250 made to retrieve HTML instead of ActivityPub JSON data.
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
251
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
252 By default, this request is showing the corresponding AP JSON data, but if you set HTML
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
253 redirection, you can redirect the page to your XMPP client web frontend (or anything
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
254 making sense), which results in better user experience.
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
255
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
256 The expected dictionary is a mapping URL request types to destination URL.
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
257
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
258 The URL request types is the first path element after ``ap_path``, it can be:
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
259
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
260 ``actor``
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
261 Actor information. It should link to the profile page of the corresponding XMPP entity
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
262
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
263 ``item``
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
264 A specific publication. It should link to the rendered item
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
265
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
266 ``followers``
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
267 Entities publicly subscribed to the actor. It is usually not used for redirection.
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
268
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
269 ``following``
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
270 Entities that the actor is publicly subscribed to. It is usually not used for
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
271 redirection.
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
272
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
273 In the target URL you can uses template values in curly braces (something like
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
274 ``{item}``). The values that you can use are:
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
275
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
276 ``jid``
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
277 Full JID corresponding to the AP actor.
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
278
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
279 ``jid_user``
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
280 Only the user part of the JID (what is before the ``@``)
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
281
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
282 ``node``
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
283 Name of the pubsub node corresponding to the AP actor.
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
284
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
285 ``item``
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
286 ID of the XMPP pubsub item.
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
287
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
288 You can use a slash ``/`` followed by a part of a node name to filter only on specific
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
289 nodes. For instance, if you want to redirect microblog items to a different URL that
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
290 event items, you can use ``item/urn:xmpp:microblog:0`` and ``item/urn:xmpp:events:0``,
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
291 the first redirection to match will be used. Note that anything containing the filter
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
292 value will match, thus you can also use ``item/microblog`` (but it then would match an
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
293 event which has ``microblog`` in is node name).
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
294
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
295 You can also use a dictionary as value instead of the target URL. This can be useful to
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
296 filter on an other value than the node name, if you want to make specific redirection
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
297 for a particular user for instance. If you use a dictionary, you must use a ``url`` key
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
298 with the target URL (which may have template values as usual), and you may use a
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
299 ``filters`` key mapping to an other dictionary where each key is a filter on a specific
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
300 template value (in other words: key is the template value, like ``jid`` or ``node``, and
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
301 value is the filter to match).
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
302
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
303 *examples*
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
304
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
305 Redirect actor page to ``/profile/<JID user part>``, blogs items to ``/blog/<full
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
306 JID>/<node name>/<item id>`` and events items to ``/event/<full JID>/<node name>/<item
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
307 id>`` ::
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
308
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
309 html_redirect_dict = {
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
310 "actor": "/profile/{jid_user}",
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
311 "item/microblog": "/blog/{jid}/{node}/{item}",
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
312 "item/events": "/event/{jid}/{node}/{item}"
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
313 }
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
314
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
315 Redirect items of user ``louise@example.org`` to ``/b/<item>``::
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
316
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
317 html_redirect_dict = {
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
318 "item": {
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
319 "url": "/b/{item}",
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
320 filters: {
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
321 "jid": "louise@example.org"
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
322 }
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
323 }
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
324 }
97fbe11c4476 doc (components/AP Gateway): `html_redirect_dict` option
Goffi <goffi@goffi.org>
parents: 3910
diff changeset
325
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
326
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
327 .. _ap-actor-from-xmpp:
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
328
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
329 How to Address an AP Actor from XMPP
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
330 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
331
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
332 When addressing an ActivityPub actor from XMPP, you must use a JID corresponding to the
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
333 actor. The domain part of the JID correspond to the gateway JID (the one set in gateway
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
334 profile), while the local part (before the ``@``) is used to specify the AP actor.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
335
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
336 `XEP-0106`_ (JID Escaping) is used to indicate the AP actor identifier, thus the ``@``
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
337 must be escaped with ``\40``.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
338
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
339 .. _XEP-0106: JID Escaping
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
340
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
341 **example**
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
342
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
343 If Louise wants to talk to Pierre which is on the ``example.net`` AP server, she can use
3885
18ff4f75f0e6 doc (components): the word "handle" is more adapted here
Goffi <goffi@goffi.org>
parents: 3874
diff changeset
344 her XMPP AP gateway which is at ``ap.example.org``. Pierre AP's actor handle is
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
345 ``pierre@example.net``, Louise can access it via the JID
3810
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
346 ``pierre\40example.net@ap.example.org`` (we call it *virtual JID* of the AP actor).
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
347
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
348 Of course, this is a bit cumbersome to do by hand, it is expected that XMPP clients will
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
349 do the (un)escaping automatically for end-user, in a way that Louise could enter
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
350 ``pierre@example.net`` directly, with an indicator to show that this is an ActivityPub
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
351 actor identifier rather than an XMPP JID.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
352
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
353
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
354 .. _xmpp-node-from-ap:
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
355
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
356 How to Address an XMPP Entity from AP
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
357 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
358
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
359 To access an XMPP entity, it is a little bit more complicated for 2 reasons:
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
360
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
361 - XMPP use a wider range of allowed characters than most AP implementations [#AP_chars]_.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
362 - to get XMPP items, we need 2 data: the entity JID, and a pubsub node
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
363
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
364
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
365 However, Libervia AP gateway tries to make it as user friendly as possible, thus it works
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
366 like this:
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
367
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
368 - in the most common case, one just wants to access the personal blog of a user, and basic
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
369 ASCII characters (with possibly ``-``, ``_`` or ``.``) are used. in this case, the XMPP
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
370 JID can be directly used as AP actor handle
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
371 - when a pubsub node needs to be specified it is most of time with a pubsub JID which has
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
372 not user part (something like ``pubsub.example.org``). In this case, the pubsub node can
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
373 be used as AP actor handle's user part, Libervia will use XMPP discovery to know that
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
374 it's a pubsub service. So if you want to access the blog named ``xmpp_news`` at
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
375 ``pubsub.example.org``, you can use the handle ``xmpp_news@pubsub.example.org`` (be sure
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
376 that the domain ``pubsub.example.org`` links to the Libervia AP gateway HTTP server)
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
377 - if you want to use a specific node with an entity which already has a user part, then a
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
378 special encoding must be used, where ``---`` (three dashes) are used to separate node
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
379 from entity: ``some_node--some_user@example.org``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
380 - if you need to use special characters, then you'll have to use ``___`` followed by the
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
381 special encoding (see below).
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
382
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
383 The encoding is explained in the documentation of the following method:
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
384
4077
d6837db456fd refactoring: fix names in doc following modules hierarchy refactoring
Goffi <goffi@goffi.org>
parents: 4037
diff changeset
385 .. automethod:: libervia.backend.plugins.plugin_comp_ap_gateway.APGateway.get_jid_and_node
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
386
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
387
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
388 .. [#AP_chars] Most if not all AP implementations use webfinger `acct` URI as a de-facto
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
389 standard to manage user-friendly handles (something like ``user@example.org``). Those
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
390 handles, according to `RFC7565`_, should
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
391 manage a wide variety of characters thanks to the support of percent-encoding.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
392
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
393 Unfortunately, at least one of the most-used AP implementation (Mastodon, which is used
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
394 a reference implementation for this gateway), only uses a limited subset of allowed
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
395 characters. In addition, Mastodon needs an associated handle [#m_wf]_ thus an alternate
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
396 way to encode characters had to be found.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
397
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
398 An issue has been opened to improve this situation on Mastodon bug tracker:
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
399 https://github.com/mastodon/mastodon/issues/17222
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
400
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
401 .. _RFC7565: https://datatracker.ietf.org/doc/html/rfc7565
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
402 .. [#m_wf] https://docs.joinmastodon.org/spec/webfinger/
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
403
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
404 **example**
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
405
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
406 If Pierre wants to talk to Louise, he can directly use the JID which is the same as the AP
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
407 actor identifier, i.e. ``louise@example.org`` (note that on AP software, a ``@`` prefix is
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
408 often required, thus Pierre will look for ``@louise@example.org``).
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
409
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
410 .. note::
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
411
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
412 The actor endpoint can also be used directly in AP software (in the example above, it
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
413 would be by default ``https://example.org/_ap/actor/louise%40example.org``).
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
414
3910
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
415 .. _ap-ad-hoc:
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
416
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
417 Ad-Hoc Commands
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
418 ~~~~~~~~~~~~~~~
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
419
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
420 The gateway supports `XEP-0050 (Ad-Hoc Commands)`_. For now, only the following node is
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
421 provided:
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
422
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
423 ``https://libervia.org/ap_gateway/xmpp_jid_node_2_ap_actor``
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
424 Convert XMPP JID and Node to corresponding virtual actor. Node is optional.
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
425
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
426 .. _XEP-0050 (Ad-Hoc Commands): https://xmpp.org/extensions/xep-0050.html
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
427
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
428 Getting AP Message from XMPP
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
429 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
430
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
431 To retrieve ActivityPub messages of an actor from an XMPP client with blogging
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
432 capabilities (like Libervia or Movim), just use the associated JID as explained in
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
433 :ref:`ap-actor-from-xmpp`. The actor messages (from ``outbox`` collection) should appear
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
434 as regular XMPP blog items.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
435
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
436 .. note::
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
437
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
438 Due to limitation of `ActivityStream Collection Paging`_, the conversion from XMPP
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
439 `RSM`_ requests is inneficient beyond first or last page. This problem is avoided if
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
440 anybody subscribe to the gateway node (i.e. follow the AP actor), as the collection
3772
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
441 will then be cached, and efficiently delivered.
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
442
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
443 .. _ActivityStream Collection Paging: https://www.w3.org/TR/activitystreams-core/#h-paging
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
444 .. _RSM: https://xmpp.org/extensions/xep-0059.html
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
445
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
446 Getting XMPP Items from ActivityPub
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
447 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
448
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
449 To get XMPP items from an ActivityPub implementation, just use the handle as explained at
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
450 :ref:`xmpp-node-from-ap` (often handle searches are triggered with a ``@`` before the
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
451 handle in AP implementations, e.g.: ``@louise@example.org``).
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
452
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
453 .. note::
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
454
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
455 Some AP implementations such as Mastodon don't retrieve existing items, but only keep
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
456 new ones once an actor is followed. That means that you won't see any message published
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
457 before your entity is followed. Other implementations may work differently.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
458
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
459
3746
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
460 .. _ap-xmpp-threads-conversion:
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
461
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
462 ActivyPub to XMPP Discussion Threads Conversion
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
463 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
464
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
465 By default, each (micro)blog publication converted from ActivityPub to XMPP Pubsub is
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
466 associated with a comment node (see `XEP-0277 comments`_) to allow user to post a reply on
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
467 any on them. This result in a "tree-like" comments threading model, which is similar to
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
468 what you can see on popular website such as Reddit, Hacker News, or LinuxFr.
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
469
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
470 However, some XMPP clients may not play nicely with this kind of threading model. To work
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
471 around this, the ``comments_max_depth`` option allows to limit the maximum number of
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
472 thread. It is an integer value which indicate how many comments nodes may exist for a root
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
473 post. If set to ``1``, only one comment node will be made, and ActivityPub items below
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
474 this level will be moved to this single XMPP pubsub comment node.
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
475
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
476 The default value of ``0`` means unlimited max depth.
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
477
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
478 An example can probably make it more clear. Imagine that you have a message ``root
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
479 message``, with a comment to it named ``1``, a comment to ``1`` named ``2`` and so on
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
480 until ``5``. With ``comments_max_depth`` set to ``0``, you'll have one comment node per
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
481 item, resulting in following threads model::
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
482
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
483 root message ┑
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
484 ┕ 1 ┑
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
485 ┕ 2 ┑
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
486 ┕ 3 ┑
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
487 ┕ 4 ┑
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
488 ┕ 5
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
489
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
490 With ``comments_max_depth`` set to ``2``, only 2 nodes will be created, and items below
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
491 depth ``2`` will be put on the same level::
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
492
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
493 root message ┑
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
494 ┕ 1 ┑
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
495 ┝ 2
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
496 ┝ 3
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
497 ┝ 4
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
498 ┕ 5
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
499
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
500 This way, admins can configure the model which suits best the clients which is expected to
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
501 be mainly used on the instance.
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
502
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
503 .. _XEP-0277 comments: https://xmpp.org/extensions/xep-0277.html#comments
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
504
3772
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
505 Publishing an Item
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
506 ~~~~~~~~~~~~~~~~~~
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
507
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
508 To publish a new item (e.g. a blog post), you just need to publish normally on your own
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
509 PEP/pubsub node, AP actors following you will be notified. To reply to an AP item, just
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
510 publish to the corresponding pubsub node managed by the gateway. This is transparent for
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
511 AP and XMPP end users.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
512
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
513 For instance, if Pierre has posted an interesting message on his AP server, and Louise
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
514 wants to reply to it, she just use a client to reply on the comments node of this message,
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
515 this will be delivered as an AP object to Pierre's AP server.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
516
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
517 On the other hand, if Louise is publishing a new blog post on her XMPP server, Pierre will
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
518 receive corresponding AP object because he's following her. If Pierre answer using his AP
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
519 client, the corresponding message will be published on the comments node of the message
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
520 that Louise has initially published.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
521
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
522 Following, Subscribing and Cache
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
523 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
524
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
525 When you try to access an uncached AP collection from XMPP (e.g. blog posts), a best
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
526 effort is done to translate XMPP pagination (which uses `XEP-0059 (Result Set
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
527 Management)`_) to the less powerful `AP Collection Paging`_. This is inefficient due to
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
528 technical limitations (page size can't be specified in AP, there is not standard way to
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
529 request item after or before a specific ID, implementations may not implement reverse
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
530 pagination).
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
531
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
532 That's one of the reason why whenever possible, collections are cached locally. Once
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
533 cached, it's easier to return items according to complex requests.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
534
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
535 However, to cache correctly an AP collection, you need to keep it in sync, and thus to
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
536 receive update when something change (e.g. a new blog item is published).
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
537
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
538 In AP, this is done by following an actor, in XMPP this correspond to a node subscription.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
539
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
540 When you subscribe to a blog node managed by this gateway, this will be translated to a
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
541 *follow* activity on AP side, and vice versa.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
542
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
543 When an AP actor is followed, its *outbox* collection (i.e. message published), are
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
544 automatically cached, and will be updated when events will be received. That means that
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
545 you can use pubsub cache search on followed actors, e.g. to retrieve all items about a
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
546 specific topic or published at specific time range.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
547
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
548 Reciprocally, unsubscribing from a node will *unfollow* the corresponding AP actor.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
549
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
550 If an AP actor is following or unfollowing an actor mapping an XMPP entity, they nodes
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
551 will be subscribed to or unsubscribed from.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
552
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
553 All subscriptions are made public as specified by `XEP-0465 (Pubsub Public Subscriptions)`_.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
554
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
555 .. _XEP-0059 (Result Set Management): https://xmpp.org/extensions/xep-0059.html
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
556 .. _AP Collection Paging: https://www.w3.org/TR/activitystreams-core/#h-paging
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
557 .. _XEP-0465 (Pubsub Public Subscriptions): https://xmpp.org/extensions/inbox/pubsub-public-subscriptions.html
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
558
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
559 Following/Followers Collections and Public Pubsub Subscription
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
560 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
561
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
562 The AP *following* collection is mapped to `XEP-0465 (Pubsub Public Subscriptions)`_.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
563
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
564 In the same spirit, the AP *followers* collection correspond to public subscribers to the
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
565 microblog node.
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
566
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
567 Because AP doesn't send any event when *following* or *followers* collections are
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
568 modified, those collections can't be cached, and thus the translation to public pubsub
98ba02637436 doc (components): update AP gateway documentation:
Goffi <goffi@goffi.org>
parents: 3746
diff changeset
569 subscriptions is done as best as possible given the constraints.
3746
fa3dc4ed7906 doc (components): documentation of `comments_max_depth` option and threads conversion:
Goffi <goffi@goffi.org>
parents: 3734
diff changeset
570
3810
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
571 .. _ap-message_delivery:
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
572
3786
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
573 Messages Delivery
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
574 ~~~~~~~~~~~~~~~~~
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
575
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
576 The gateway can convert AP publications to either XMPP pubsub items (using `XEP-0277
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
577 (Microblogging over XMPP)`_ when suitable) or to XMPP messages (`<message>` stanzas, i.e.
3790
24f70a29e382 doc (components): typo/spelling
Goffi <goffi@goffi.org>
parents: 3786
diff changeset
578 the ones used for instant messaging). Of course it also converts in a similar way in the
3786
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
579 other direction (XMPP → ActivityPub).
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
580
3790
24f70a29e382 doc (components): typo/spelling
Goffi <goffi@goffi.org>
parents: 3786
diff changeset
581 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
582 conditions is fulfilled:
3786
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
583
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
584 - it is addressed to the special `*public* collection`_
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
585 - it is addressed to a local *followers* collection
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
586
3790
24f70a29e382 doc (components): typo/spelling
Goffi <goffi@goffi.org>
parents: 3786
diff changeset
587 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
588 are fulfilled:
3786
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
589
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
590 - it is **not** addressed to the special *public* collection
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
591 - it is **not** addressed to a any local *followers* collection.
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
592
3790
24f70a29e382 doc (components): typo/spelling
Goffi <goffi@goffi.org>
parents: 3786
diff changeset
593 In other words, if an AP item is addressed directly to one or more local users, is not
3786
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
594 public and is not addressed to a *followers* collection, it will be converted to an XMPP
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
595 message, otherwise it will be converted to an XMPP pubsub item.
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
596
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
597 The behaviour is symmetric, thus if you send an XMPP message it will be converted to an AP
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
598 item which will be only addressed to your recipient. If you write using XMPP pubsub, the
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
599 suitable followers collections of the target AP actor will be automatically added, and the
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
600 item will have the special *public* collection added.
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
601
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
602 .. note::
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
603
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
604 ActivyPub doesn't do any kind of `end-to-end encryption`_, it is **not** the same level of
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
605 privacy as XMPP.
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
606
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
607 Messages will be at minimum readable by the administrators of the AP gateway and of the
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
608 ActivyPub server of the destinee. Be sure to understand that before sending messages.
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
609
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
610 If you need more privacy, you need to use either XMPP only (without the ActivityPub
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
611 gateway) with clients implementing correctly end-to-end encryption, or an other
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
612 software. Depending of the level of pricacy required, you may want to use
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
613 authentication by a separated channel, a client which has been audited, encryption by
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
614 default, etc. This is beyond the scope of this AP gateway documentation.
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
615
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
616 In short, don't use ActivityPub if you need a high level of privacy. This is a current
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
617 protocol limitation, and there is nothing that this gateway can do about this until
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
618 ActivityPub and its implementations evolve.
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
619
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
620 .. _XEP-0277 (Microblogging over XMPP): https://xmpp.org/extensions/xep-0277.html
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
621 .. _*public* collection: https://www.w3.org/TR/activitypub/#public-addressing
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
622 .. _end-to-end encryption: https://en.wikipedia.org/wiki/End-to-end_encryption
cebfdfff3e99 doc (components): message delivery documentation:
Goffi <goffi@goffi.org>
parents: 3772
diff changeset
623
3810
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
624 Message/Item Retraction
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
625 ~~~~~~~~~~~~~~~~~~~~~~~
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
626
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
627 If you retract a pubsub item (e.g. a blog post), that is followed by ActivityPub actors,
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
628 a suitable `Delete` activity will be emitted. In other words, the ActivityPub servers will
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
629 be notified of the retraction.
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
630
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
631 Similarly if an AP actor is deleting an item, a suitable `XEP-0060 retraction event`_ will
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
632 be sent to subscribers.
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
633
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
634 In the case of direct messages (see :ref:`ap-message_delivery`), `XEP-0424 (Message
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
635 Retraction)`_ is used in both reception (AP ``Delete`` activity is converted to XEP-0424
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
636 and vice versa).
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
637
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
638 All of this should be transparent to users as long as their clients support the mentioned
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
639 XEPs.
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
640
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
641 .. note::
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
642
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
643 When retracting a message/item, a retraction request (or equivalent AP "Delete"
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
644 activity) is sent, so the other end clients **may** delete the item.
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
645
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
646 However, there is no way to be sure that the item will be actually deleted: once
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
647 something is sent on the network, any recipient can see it, copy it, share it, etc.
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
648 There is no way to forbid that, and this is true for software, decentralized or not
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
649 (and not only ActivityPub or XMPP).
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
650
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
651 Be sure to understand that before sending anything sensitive.
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
652
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
653 .. note::
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
654
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
655 When deleting an item on ActivityPub, the item is often replaced by a "tombstone", and
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
656 it's not possible to send a new item with the same ID. Some software (it's at least the
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
657 case with Mastodon), will silently reject the item, and thus people won't see it.
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
658
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
659 This is a different behaviour from XMPP where you can publish a pubsub item, retract
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
660 it, and publish a new item with the same ID.
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
661
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
662 Thus if you retract an item, be sure to publish any new one with new and unique ID,
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
663 otherwise the item may not appear to ActivityPub users (and as the item may be rejected
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
664 silently, you may not be notified).
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
665
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
666 However this should not be a problem in the vast majority of cases, as most XMPP client
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
667 implementing pubsub or pubsub service will generate automatically unique IDs for new
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
668 items.
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
669
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
670 .. _XEP-0060 retraction event: https://xmpp.org/extensions/xep-0060.html#publisher-delete
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
671 .. _XEP-0424 (Message Retraction): https://xmpp.org/extensions/xep-0424.html
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
672
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
673 Blocking an User
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
674 ~~~~~~~~~~~~~~~~
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
675
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
676 You can block AP actors using :ref:`its virtual JID <ap-actor-from-xmpp>` in the same way
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
677 as for any XMPP entity, by using `XEP-0191 (Blocking Command)`_.
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
678
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
679 This is done at the XMPP server level and your server must support it. From client side,
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
680 many clients support it, and you can use Libervia CLI to do it from command-line (see
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
681 :ref:`libervia-cli_blocking`).
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
682
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
683 .. _XEP-0191 (Blocking Command): https://xmpp.org/extensions/xep-0191.html
29380ef68dbe doc (components): AP item retraction + blocking:
Goffi <goffi@goffi.org>
parents: 3790
diff changeset
684
3827
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
685 Identity and Avatar
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
686 ~~~~~~~~~~~~~~~~~~~
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
687
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
688 The gateway does the conversion between XMPP identity and AP actor metadata.
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
689
3838
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
690 XMPP "identity" is actually a compilation of data coming from various locations and in
3827
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
691 particular `XEP-0292 (vCard4 Over XMPP)`_. In those data, vCard's ``nickname`` (first
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
692 found) is used as AP ``name`` field, and vCard's ``note`` is used as AP's ``summary``
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
693 (it's generally a self-description of users).
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
694
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
695 For avatars, `XEP-0084 (User Avatar)`_ is used (and actor's ``icon`` field is used on AP
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
696 side). Avatars are downloaded the first time that they are requested, and kept in cache
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
697 for future requests.
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
698
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
699 Even if XEP-0292 and XEP-0084 are the main XEPs used, Libervia checks various locations,
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
700 and other extensions like `XEP-0054 (vcard-temp)`_ may be used as fallback.
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
701
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
702 .. _XEP-0292 (vCard4 Over XMPP): https://xmpp.org/extensions/xep-0292.html
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
703 .. _XEP-0084 (User Avatar): https://xmpp.org/extensions/xep-0084.html
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
704 .. _XEP-0054 (vcard-temp): https://xmpp.org/extensions/xep-0054.html
23b53ac87e0f doc (components/AP): identity and avatar:
Goffi <goffi@goffi.org>
parents: 3810
diff changeset
705
3838
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
706 Mentions
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
707 ~~~~~~~~
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
708
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
709 Mentions are converted by the gateway under some conditions explained below.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
710
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
711 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
712 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
713 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
714 will be emitted.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
715
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
716 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
717 reference is most probably not desired for a private message.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
718
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
719 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
720 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
721
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
722 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
723 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
724 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
725
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
726 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
727 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
728 item which has the same ID.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
729
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
730 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
731 because XEP-0372 references are received after the published items.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
732
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
733 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
734 ``@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
735 resulting AP item.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
736
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
737 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
738 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
739 ``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
740 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
741 messages (see above).
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
742
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
743 .. note::
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
744
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
745 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
746 virtual JID.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
747
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
748 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
749 ``@louise@example.org``, and NOT something like
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
750 ``@louise\40example.org@ap.example.net``.
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
751
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
752 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
753
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
754 .. _XEP-0372 (References): https://xmpp.org/extensions/xep-0372.html
9a53b513ae55 doc (components/AP): Mention:
Goffi <goffi@goffi.org>
parents: 3827
diff changeset
755
3874
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
756 Repeat/Share/Reboost
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
757 ~~~~~~~~~~~~~~~~~~~~
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
758
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
759 The repeat feature (also named "share", or "boost") which consist of republishing an item
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
760 of interest under our own account to make it visible to our subscribers, is done on the
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
761 XMPP side with `XEP-0277 § Repeating a Post`_, and on the AP side it's an ``Announce``
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
762 activity. Conversion is done in both directions and should be transparent to user.
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
763
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
764 .. _XEP-0277 § Repeating a Post: https://xmpp.org/extensions/xep-0277.html#repeat
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
765
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
766 Noticed/Like
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
767 ~~~~~~~~~~~~
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
768
3892
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
769 AP's ``Like`` activity is converted on the XMPP side to "`XEP-0470 (Pubsub
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
770 Attachments)`_". ``Like`` is converted to ``noticed`` attachment, meaning that it used in
3874
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
771 to indicate that something has been seen and taken into account, without really indication
3892
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
772 if the content is liked or disliked (see XEP-0470 § Foreword: `"noticed" instead of "like"
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
773 or "favourite"`_ for the rational).
3874
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
774
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
775 As usual, conversion is done in both ways.
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
776
3892
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
777 .. _XEP-0470 (Pubsub Attachments): https://xmpp.org/extensions/xep-0470.html
3874
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
778 .. _XMPP Council: https://xmpp.org/about/xmpp-standards-foundation/
3892
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
779 .. _"noticed" instead of "like" or "favourite": https://xmpp.org/extensions/xep-0470.html#noticed-foreword
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
780
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
781 Reactions
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
782 ~~~~~~~~~
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
783
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
784 Reactions are not specified in `base ActivityPub specification`_. However `Pleroma`_, a
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
785 software implemeting ActivityPub, implements them using a non standardised (yet?)
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
786 ``EmojiReact`` activity. Liberva AP Gateway use it to handle reactions.
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
787
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
788 On the XMPP side, `XEP-0470 (Pubsub Attachments)`_ is once again used.
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
789
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
790 Libervia also implements `XEP-0444 (Message Reactions)`_ for messages, but because Pleroma
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
791 doesn't handle reactions for direct messages, this is not used in the Libervia AP gateway.
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
792 If in the future an AP implementation uses reactions on direct messages, it will be
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
793 straightforward to add it in the AP gateway.
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
794
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
795 .. _base ActivityPub specification: https://www.w3.org/TR/activitypub/
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
796 .. _Pleroma: https://pleroma.social/
ba78cc0c8d59 doc (components/AP gateway): "reactions":
Goffi <goffi@goffi.org>
parents: 3885
diff changeset
797 .. _XEP-0444 (Message Reactions): https://xmpp.org/extensions/xep-0444.html
3874
c2b292d30c66 doc (components/AP gateway): "repeat" and "noticed/like":
Goffi <goffi@goffi.org>
parents: 3838
diff changeset
798
3910
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
799 Events
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
800 ~~~~~~
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
801
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
802 This gateway manages events. On the XMPP side, the ``Events`` protoXEP is used, on AP side
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
803 ``Event`` objects are used. `Mobilizon`_ is used as reference implementation here.
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
804
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
805 .. note::
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
806
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
807 The ``Events`` protoXEP has been proposed but not published or reviewed by XMPP council
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
808 yet. The current version is availale at https://github.com/xsf/xeps/pull/1206 and
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
809 hopefully it will eventually become an official experimental XEP. The code and this
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
810 documentation will be updated as the standard evolves.
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
811
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
812 To retrieve AP events from XMPP, use the corresponding virtual JID as explained in
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
813 :ref:`ap-actor-from-xmpp` with the event node (which is ``urn:xmpp:events:0``).
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
814
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
815 *example:*
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
816
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
817 To retrieve events from AP actor with the handle ``somebody@mobilizon.example``, throught
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
818 the ``ap.example.org`` gateway, the ``somebody\40mobilizon.example@ap.example.org`` JID
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
819 can be used with the ``urn:xmpp:events:0`` node.
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
820
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
821
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
822 To retrieve XMPP events from AP, you need to the virtual actor corresponding to the JID
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
823 of the pubsub/PEP service with the event node (starting with ``urn:xmpp:events:0``), as
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
824 explained in :ref:`xmpp-node-from-ap`. You can use :ref:`ap-ad-hoc` to easily convert your
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
825 JID/node combination to a virtual AP actor. Note that the resulting virtual actor is
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
826 unaesthetic due to the presence of event node and the constraints explained in
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
827 :ref:`xmpp-node-from-ap`.
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
828
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
829 To retrieve the link to the XMPP item from AP, you can use the ID from the generated AP
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
830 object. The ID can also be constructed by hand by using the URL
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
831 ``https://<ap_gateway_public_domain>/_ap/<virtual_actor>/<event_item_id>``.
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
832
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
833 *example:*
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
834
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
835 to retrieve from AP the XMPP event at pubsub service ``pubsub.example.net`` on node
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
836 ``urn:xmpp:events:0/party`` with item ID ``picnic_abd1``, and using the AP gateway with
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
837 public url ``https://ap.example.net``, the following link can be used::
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
838
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
839 https://ap.example.net/_ap/___urn.3Axmpp.3Aevents.3A0.2Fparty---pubsub.2eexample.2enet@ap.tazar3.int/picnic_abd1
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
840
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
841 If you paste it in an AP implementation featuring events (e.g. Mobilizon), the event
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
842 should appear and you should be able to comment it and participate to it.
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
843
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
844 Event comments are supported, the node to use is indicated in the event XMPP item as
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
845 specified in the protoXEP, this should be transparent to end-user.
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
846
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
847 Participation to an event is supported through the RSVP mechanism on XMPP and with
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
848 ``Join`` and ``Leave`` activities on AP. Note that XMPP allows more nuances with its RSVP
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
849 mechanism (it's possible to say if someone will "maybe" attend an event, and to request
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
850 any kind of extra informations) while AP only indicates if one will attend or not an
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
851 event.
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
852
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
853
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
854 .. _Mobilizon: https://joinmobilizon.org/
199598223f82 doc (components/AP Gateway): Ad-Hoc and Events:
Goffi <goffi@goffi.org>
parents: 3892
diff changeset
855
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
856 Using the Component (for developers)
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
857 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
858
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
859 Publication of AP items can be tested using the following method (with can be accessed
4037
524856bd7b19 massive refactoring to switch from camelCase to snake_case:
Goffi <goffi@goffi.org>
parents: 3984
diff changeset
860 through the ``ap_send`` bridge method, client is then replaced by the ``profile`` name, as
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
861 last argument):
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
862
4077
d6837db456fd refactoring: fix names in doc following modules hierarchy refactoring
Goffi <goffi@goffi.org>
parents: 4037
diff changeset
863 .. automethod:: libervia.backend.plugins.plugin_comp_ap_gateway.APGateway.publish_message
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
864
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
865 The method can be used either with CLI's :ref:`debug bridge method
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
866 <li_debug_bridge_method>` or with any D-Bus tool like ``qdbus`` or ``d-feet`` (only if you
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
867 use the D-Bus bridge).
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
868
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
869 example
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
870 ~~~~~~~
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
871
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
872 On its ``example.net`` Mastodon instance, Pierre has published a message with the id
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
873 ``https://example.net/@pierre/106986412193109832``. To send a reply to this message,
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
874 Louise can use the following command::
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
875
4037
524856bd7b19 massive refactoring to switch from camelCase to snake_case:
Goffi <goffi@goffi.org>
parents: 3984
diff changeset
876 $ li debug bridge method -c ap_send '"{\"node\": \"https://example.net/@pierre/106986412193109832\", \"content\": \"A lille hello from XMPP\"}","pierre\\40example.net@ap.example.org", "louise"'
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
877
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
878 Note the double escaping, one for the shell argument, and the other to specify JSON
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
879 object.
4279
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
880
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
881
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
882 Audio/Video Conferences
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
883 -----------------------
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
884
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
885 **entry_point:** ``conferences``
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
886
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
887 This component integrates a service to run multiparty audio/video conferences over XMPP.
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
888 The service is called a "Selective Forwarding Unit" (SFU), and it's main role is to
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
889 distribute participants' audio and video streams.
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
890
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
891 The component currently integrates the `Galène project`_, as it is a complete, simple, and
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
892 easy to install service. Other projects may be integrated in the future if the need
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
893 arises.
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
894
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
895 .. note::
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
896
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
897 This component is **work in progress** and under heavy development.
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
898
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
899 Please ensure that Galène is already installed on your device.
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
900
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
901 If the ``galene`` executable is not in your ``PATH`` environment variable, you can specify its
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
902 location using the ``galene_path`` option (see below).
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
903
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
904 Note that Galène will be automatically started and stopped by the component, you don't
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
905 have to start it yourself.
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
906
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
907 Configuration
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
908 ~~~~~~~~~~~~~
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
909
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
910 All options are to be set in the ``[component conferences]`` section.
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
911
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
912 ``galene_path``
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
913 The path to the Galène executable, if it is not in the `PATH` environment variable.
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
914
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
915 **default**: Look for ``galene`` in the ``PATH``
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
916
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
917 ``http_port``
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
918 The port used by the Galène HTTP server.
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
919
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
920 **default**: 9443
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
921
6276242736c3 doc (components): Documentation for the new `Conferences` component:
Goffi <goffi@goffi.org>
parents: 4260
diff changeset
922 .. _Galène project: https://galene.org/