annotate doc/components.rst @ 3728:b15644cae50d

component AP gateway: JID/node ⟺ AP outbox conversion: - convert a combination of JID and optional pubsub node to AP actor handle (see `getJIDAndNode` for details) and vice versa - the gateway now provides a Pubsub service - retrieve pubsub node and convert it to AP collection, AP pagination is converted to RSM - do the opposite: convert AP collection to pubsub and handle RSM request. Due to ActivityStream collection pagination limitations, some RSM request produce inefficient requests, but caching should be used most of the time in the future and avoid the problem. - set specific name to HTTP Server - new `local_only` setting (`True` by default) to indicate if the gateway can request or not XMPP Pubsub nodes from other servers - disco info now specifies important features such as Pubsub RSM, and nodes metadata ticket 363
author Goffi <goffi@goffi.org>
date Tue, 25 Jan 2022 17:54:06 +0100
parents a1eff4e32848
children 643622ff1492
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3678
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
1 .. _components:
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
2
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
3 ===================
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
4 Libervia Components
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
5 ===================
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
6
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
7 Libervia can act as an XMPP server component, which can be seen as a generic plugin for
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
8 XMPP servers.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
9
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
10 This page explains which components are available and how to use them.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
11
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
12 Running a component
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
13 ===================
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
14
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
15 Components are linked to a Libervia profile in the same way as normal clients.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
16
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
17 To run a component, you'll need to know its *entry point*, which is the name of the import
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
18 name of plugin managing it. The entry point to use will be specified in the component
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
19 installation documentation.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
20
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
21 You'll also have to declare the component on your XMPP server, this is a server dependent
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
22 step and you'll have to check your server documentation for details. You'll have to
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
23 specify a **shared secret** (can also be named simply *password*) that must be set both on
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
24 the XMPP server and as the XMPP password of the Libervia profile.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
25
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
26 Here is a list of relevant documentation for most common servers:
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
27
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
28 ejabberd
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
29 https://docs.ejabberd.im/admin/configuration/listen-options/
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
30
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
31 MongooseIm
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
32 https://esl.github.io/MongooseDocs/latest/configuration/listen/#xmpp-components-listenservice
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
33
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
34 OpenFire
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
35 use the web-based admin panel
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
36
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
37 Prosody
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
38 https://prosody.im/doc/components
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
39
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
40 Tigase
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
41 https://docs.tigase.net/tigase-server/stable-snapshot/Administration_Guide/webhelp/externalComponentConfiguration.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
42
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
43
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
44 On Libervia, setup is done with Libervia CLI's :ref:`profile create <li_profile_create>`
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
45 command.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
46
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
47 You'll usually want to have the component to start automatically when the backend
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
48 is started, for this you must unset the profile password (not to be confused with the XMPP
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
49 password which is the one also set on the server configuration) with ``-p ""`` and set
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
50 auto-connection with ``-A``.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
51
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
52 You'll specify the XMPP password (also named *shared secret* in `XEP-0144`_ terminology)
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
53 with ``-x <your_shared_secret>`` and the JID to use with ``-j
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
54 <component_subdomain>.<server.tld>``.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
55
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
56 The component entry point is specified with ``-C <entry_point>``.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
57
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
58 .. _XEP-0144: https://xmpp.org/extensions/xep-0114.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
59
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
60 example
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
61 -------
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
62
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
63 Louise wants to run an ActivityPub gateway on her server ``example.org`` with the JID
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
64 ``ap.example.org``. The shared secret is ``xmpp_rocks`` and she wants the component to
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
65 start automatically with the backend, thus she doesn't set a profile password. The
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
66 entry-point for ActivityPub component is ``ap-gateway``, and she wants to use the same
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
67 name for the profile. To do this, she enters the following command::
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
68
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
69 $ li profile create ap-gateway -j ap.example.org -p "" -x xmpp_rocks -C ap-gateway -A
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
70
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
71 The component will then be started next time Libervia Backend is launched. If Louise
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
72 wants to connect it immediately, she can use::
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
73
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
74 $ li profile connect -cp ap-gateway
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
75
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
76 Available Components
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
77 ====================
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
78
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
79 Below is a list of currently available components in Libervia, and instructions on what
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
80 they do and how to use them.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
81
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
82
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
83 File Sharing
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
84 ------------
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
85
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
86 **entry_point:** ``file-sharing``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
87
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
88 File Sharing component manage the hosting of user files. Users can upload file there using
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
89 either `Jingle File Transfer`_ or `HTTP File Upload`_.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
90
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
91 There is no limit to the size of files which can be uploaded, but administrators can set a
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
92 quota to limit the space that can be used.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
93
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
94 Files can be retrieved using `File Information Sharing`_, and deleted using `Ad-Hoc Commands`_.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
95
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
96 Files can be shared with a public HTTP link, or made available only to a specified list of
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
97 entities (JIDs). Permissions can be set through Ad-Hoc Commands.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
98
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
99 .. _Jingle File Transfer: https://xmpp.org/extensions/
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
100 .. _HTTP File Upload: https://xmpp.org/extensions/xep-0363.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
101 .. _File Information Sharing: https://xmpp.org/extensions/xep-0329.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
102 .. _Ad-Hoc Commands: https://xmpp.org/extensions/xep-0050.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
103
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
104 Configuration
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
105 ~~~~~~~~~~~~~
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
106
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
107 All options are to be set in ``[component file-sharing]`` section.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
108
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
109 ``http_upload_port``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
110 port to use for HTTP File Upload
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
111
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
112 **default**: 8888
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
113
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
114 ``http_upload_connection_type``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
115 either ``http`` or ``https``.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
116
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
117 **default**: ``https``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
118
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
119 Note that HTTP Upload should always be ``https`` to end-user, the ``http`` option is to
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
120 be used only if you use a HTTP server as a proxy, and this server is already set for
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
121 TLS.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
122
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
123 ``http_upload_public_facing_url``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
124 must be set to the URL that end-user will see. Notably useful if the component is behind
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
125 a proxy.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
126
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
127 **default**: ``https://<component host>:<http_upload_port``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
128
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
129 ``quotas_json``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
130 a JSON object indicating quotas to use for users. The object can have 3 keys:
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
131
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
132 ``admins``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
133 quotas to use for administrators (i.e. profiles set in ``admins_list``)
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
134
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
135 ``users``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
136 quotas to use for normal users (i.e. non admin profiles)
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
137
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
138 ``jids``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
139 per-jid specific quotas. The value is a JSON object where key is a user bare jid and
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
140 value is a quota.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
141
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
142 Quotas can be either ``null`` for unlimited space, or a size value (`SI prefixes and
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
143 binary prefixes`_ can be used).
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
144
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
145 example::
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
146
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
147 quotas_json = {
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
148 "admins": null,
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
149 "users": "50 Mio",
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
150 "jids": {"pierre@example.org": "1 Gio"}
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
151 }
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
152
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
153 .. _SI prefixes and binary prefixes: https://en.wikipedia.org/wiki/Octet_(computing)#Unit_multiples
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
154
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
155
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
156 ActivityPub Gateway
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
157 -------------------
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
158
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
159 **entry_point:** ``ap-gateway``
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
160
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
161 .. note::
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
162
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
163 this component is currently in active development, and not yet usable for end-user. This
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
164 documentation will be updated during evolution of component.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
165
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
166 You can follow the development by reading `Libervia Progress Notes`_.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
167
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
168 .. _Libervia Progress Notes: https://www.goffi.org/tag/Libervia%20progress
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
169
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
170 This gateway will provide a bidirectional gateway between XMPP and `ActivityPub`_ (or AP
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
171 below). That means that user from XMPP will be able to follow actors or comments messages
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
172 from any software compatible with ActivityPub protocol, and vice versa.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
173
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
174 .. _ActivityPub: https://activitypub.rocks/
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
175
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
176 .. note::
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
177
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
178 this component is mostly tested with Prosody as XMPP server reference, and Mastodon as
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
179 AP server reference, but it should work with any XMPP or AP server.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
180
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
181 The component launches a HTTP server (necessary to communicate with AP software). This
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
182 server needs to handle HTTP requests made at paths ``/.well-known/webfinger`` and ``/_ap``
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
183 (or the ``ap_path`` set in configuration, see below). If the component is not directly
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
184 facing internet (e.g. integrated in an existing website though a proxy), you'll have to
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
185 redirect the requests made to those path to the HTTP server (i.e. to component host at the
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
186 port set at ``http_port``, see configuration below). Please check your HTTP server
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
187 documentation to find how this must be done.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
188
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
189 how to address an AP actor from XMPP
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
190 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
191
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
192 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
193 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
194 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
195
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
196 `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
197 must be escaped with ``\40``.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
198
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
199 .. _XEP-0106: JID Escaping
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
200
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
201 **example**
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
202
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
203 If Louise wants to talk to Pierre which is on the ``example.net`` AP server, she can use
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
204 her XMPP AP gateway which is at ``ap.example.org``. Pierre AP's actor identifier is
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
205 ``pierre@example.net``, Louise can access it via the JID
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
206 ``pierre\40example.net@ap.example.org``.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
207
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
208 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
209 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
210 ``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
211 actor identifier rather than an XMPP JID.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
212
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
213 how to address an XMPP entity from AP
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
214 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
215
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
216 To access an XMPP entity, just use its bare JID as AP actor.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
217
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
218 **example**
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
219
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
220 If Pierre wants to talk Louise, he can directly use the JID which is the same as the AP
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
221 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
222 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
223
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
224 .. note::
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
225
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
226 Currently the gateway only uses bare JID, and character set must be recognised by the
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
227 AP software to be used. This will evolve in the close future to have a way to access
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
228 various XMPP Pubsub nodes.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
229
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
230 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
231 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
232
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
233
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
234 using the component
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
235 ~~~~~~~~~~~~~~~~~~~
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
236
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
237 The component is currently only usable for development purpose, and it can be used with
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
238 the following method (with can be accessed through the ``APSend`` bridge method, client is
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
239 then replaced by the ``profile`` name, as last argument):
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
240
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
241 .. automethod:: sat.plugins.plugin_comp_ap_gateway.APGateway.publishMessage
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
242
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
243 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
244 <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
245 use the D-Bus bridge).
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
246
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
247 example
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
248 ~~~~~~~
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
249
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
250 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
251 ``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
252 Louise can use the following command::
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
253
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
254 $ li debug bridge method -c APSend '"{\"node\": \"https://example.net/@pierre/106986412193109832\", \"content\": \"A lille hello from XMPP\"}","pierre\\40example.net@ap.example.org", "louise"'
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
255
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
256 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
257 object.