annotate doc/components.rst @ 3739:0a87cae85746

tools (utils): fix `getRepositoryData` crash: - use `hg_path` to be sure to use the right executable - better exception handling
author Goffi <goffi@goffi.org>
date Tue, 22 Mar 2022 17:00:42 +0100
parents 643622ff1492
children fa3dc4ed7906
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3678
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
1 .. _components:
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
2
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
3 ===================
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
4 Libervia Components
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
5 ===================
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
6
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
7 Libervia can act as an XMPP server component, which can be seen as a generic plugin for
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
8 XMPP servers.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
9
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
10 This page explains which components are available and how to use them.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
11
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
12 Running a component
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
13 ===================
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
14
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
15 Components are linked to a Libervia profile in the same way as normal clients.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
16
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
17 To run a component, you'll need to know its *entry point*, which is the name of the import
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
18 name of plugin managing it. The entry point to use will be specified in the component
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
19 installation documentation.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
20
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
21 You'll also have to declare the component on your XMPP server, this is a server dependent
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
22 step and you'll have to check your server documentation for details. You'll have to
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
23 specify a **shared secret** (can also be named simply *password*) that must be set both on
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
24 the XMPP server and as the XMPP password of the Libervia profile.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
25
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
26 Here is a list of relevant documentation for most common servers:
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
27
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
28 ejabberd
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
29 https://docs.ejabberd.im/admin/configuration/listen-options/
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
30
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
31 MongooseIm
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
32 https://esl.github.io/MongooseDocs/latest/configuration/listen/#xmpp-components-listenservice
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
33
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
34 OpenFire
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
35 use the web-based admin panel
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
36
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
37 Prosody
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
38 https://prosody.im/doc/components
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
39
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
40 Tigase
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
41 https://docs.tigase.net/tigase-server/stable-snapshot/Administration_Guide/webhelp/externalComponentConfiguration.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
42
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
43
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
44 On Libervia, setup is done with Libervia CLI's :ref:`profile create <li_profile_create>`
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
45 command.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
46
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
47 You'll usually want to have the component to start automatically when the backend
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
48 is started, for this you must unset the profile password (not to be confused with the XMPP
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
49 password which is the one also set on the server configuration) with ``-p ""`` and set
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
50 auto-connection with ``-A``.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
51
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
52 You'll specify the XMPP password (also named *shared secret* in `XEP-0144`_ terminology)
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
53 with ``-x <your_shared_secret>`` and the JID to use with ``-j
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
54 <component_subdomain>.<server.tld>``.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
55
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
56 The component entry point is specified with ``-C <entry_point>``.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
57
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
58 .. _XEP-0144: https://xmpp.org/extensions/xep-0114.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
59
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
60 example
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
61 -------
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
62
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
63 Louise wants to run an ActivityPub gateway on her server ``example.org`` with the JID
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
64 ``ap.example.org``. The shared secret is ``xmpp_rocks`` and she wants the component to
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
65 start automatically with the backend, thus she doesn't set a profile password. The
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
66 entry-point for ActivityPub component is ``ap-gateway``, and she wants to use the same
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
67 name for the profile. To do this, she enters the following command::
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
68
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
69 $ li profile create ap-gateway -j ap.example.org -p "" -x xmpp_rocks -C ap-gateway -A
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
70
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
71 The component will then be started next time Libervia Backend is launched. If Louise
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
72 wants to connect it immediately, she can use::
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
73
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
74 $ li profile connect -cp ap-gateway
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
75
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
76 Available Components
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
77 ====================
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
78
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
79 Below is a list of currently available components in Libervia, and instructions on what
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
80 they do and how to use them.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
81
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
82
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
83 File Sharing
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
84 ------------
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
85
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
86 **entry_point:** ``file-sharing``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
87
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
88 File Sharing component manage the hosting of user files. Users can upload file there using
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
89 either `Jingle File Transfer`_ or `HTTP File Upload`_.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
90
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
91 There is no limit to the size of files which can be uploaded, but administrators can set a
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
92 quota to limit the space that can be used.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
93
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
94 Files can be retrieved using `File Information Sharing`_, and deleted using `Ad-Hoc Commands`_.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
95
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
96 Files can be shared with a public HTTP link, or made available only to a specified list of
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
97 entities (JIDs). Permissions can be set through Ad-Hoc Commands.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
98
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
99 .. _Jingle File Transfer: https://xmpp.org/extensions/
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
100 .. _HTTP File Upload: https://xmpp.org/extensions/xep-0363.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
101 .. _File Information Sharing: https://xmpp.org/extensions/xep-0329.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
102 .. _Ad-Hoc Commands: https://xmpp.org/extensions/xep-0050.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
103
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
104 Configuration
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
105 ~~~~~~~~~~~~~
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
106
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
107 All options are to be set in ``[component file-sharing]`` section.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
108
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
109 ``http_upload_port``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
110 port to use for HTTP File Upload
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
111
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
112 **default**: 8888
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
113
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
114 ``http_upload_connection_type``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
115 either ``http`` or ``https``.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
116
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
117 **default**: ``https``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
118
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
119 Note that HTTP Upload should always be ``https`` to end-user, the ``http`` option is to
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
120 be used only if you use a HTTP server as a proxy, and this server is already set for
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
121 TLS.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
122
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
123 ``http_upload_public_facing_url``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
124 must be set to the URL that end-user will see. Notably useful if the component is behind
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
125 a proxy.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
126
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
127 **default**: ``https://<component host>:<http_upload_port``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
128
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
129 ``quotas_json``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
130 a JSON object indicating quotas to use for users. The object can have 3 keys:
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
131
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
132 ``admins``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
133 quotas to use for administrators (i.e. profiles set in ``admins_list``)
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
134
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
135 ``users``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
136 quotas to use for normal users (i.e. non admin profiles)
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
137
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
138 ``jids``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
139 per-jid specific quotas. The value is a JSON object where key is a user bare jid and
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
140 value is a quota.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
141
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
142 Quotas can be either ``null`` for unlimited space, or a size value (`SI prefixes and
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
143 binary prefixes`_ can be used).
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
144
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
145 example::
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
146
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
147 quotas_json = {
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
148 "admins": null,
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
149 "users": "50 Mio",
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
150 "jids": {"pierre@example.org": "1 Gio"}
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
151 }
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
152
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
153 .. _SI prefixes and binary prefixes: https://en.wikipedia.org/wiki/Octet_(computing)#Unit_multiples
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
154
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
155
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
156 ActivityPub Gateway
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
157 -------------------
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
158
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
159 **entry_point:** ``ap-gateway``
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
160
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
161 .. note::
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
162
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
163 this component is currently in active development, and not yet fully functional. This
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
164 documentation will be updated during evolution of component.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
165
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
166 You can follow the development by reading `Libervia Progress Notes`_.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
167
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
168 .. _Libervia Progress Notes: https://www.goffi.org/tag/Libervia%20progress
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
169
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
170 This gateway will provide a bidirectional gateway between XMPP and `ActivityPub`_ (or AP
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
171 below). That means that user from XMPP will be able to follow actors or comments messages
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
172 from any software compatible with ActivityPub protocol, and vice versa.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
173
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
174 .. _ActivityPub: https://activitypub.rocks/
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
175
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
176 .. note::
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
177
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
178 this component is mostly tested with Prosody as XMPP server reference, and Mastodon as
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
179 AP server reference, but it should work with any XMPP or AP server.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
180
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
181 The component launches a HTTP server (necessary to communicate with AP software). This
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
182 server needs to handle HTTP requests made at paths ``/.well-known/webfinger`` and ``/_ap``
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
183 (or the ``ap_path`` set in configuration, see below). If the component is not directly
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
184 facing internet (e.g. integrated in an existing website though a proxy), you'll have to
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
185 redirect the requests made to those path to the HTTP server (i.e. to component host at the
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
186 port set at ``http_port``, see configuration below). Please check your HTTP server
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
187 documentation to find how this must be done.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
188
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
189
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
190 Configuration
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
191 ~~~~~~~~~~~~~
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
192
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
193 All options are to be set in ``[component ap-gateway]`` section.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
194
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
195 ``public_url``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
196 Main user-facing domain of the HTTP server, this will be used to construct all AP URLs
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
197
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
198 **default**: if not set, ``xmpp_domain`` is used. If ``xmpp_domain`` is not set either,
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
199 an error is raised.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
200
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
201 ``http_port``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
202 port where the HTTP server should listen. Port ``80`` is not used directly as it would
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
203 require root privileges, and it is strongly recommended against launching Libervia under
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
204 a privileged account. An HTTP Proxy or a port redirection should be set to redirect the
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
205 ``80`` port to the port specified here.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
206
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
207 **default**: ``8123``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
208
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
209 ``http_connection_type``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
210 either ``http`` or ``https``. If you have a HTTP proxy such as Apache or NGINX which
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
211 already handles HTTPS, you may want to use ``http``.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
212
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
213 **default**: ``https``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
214
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
215 Note that the HTTP server should always use ``https`` with end-user, the ``http`` option
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
216 is only to be used with an HTTPS proxy.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
217
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
218 ``local_only``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
219 A boolean value indicating if the gateway is allowed to convert pubsub node from
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
220 external XMPP service or not. A JID is considered external if its domain part doesn't
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
221 end with the gateway's server. For instance, if a gateway ``ap.example.org`` is set on
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
222 the server ``example.org``, the JIDs ``pierre@example.org`` or
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
223 ``some-node@pubsub.example.org`` will be considered local, but
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
224 ``buenaventura@example.net`` won't (note the different domain).
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
225
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
226 Most of time, ``local_only`` should be used.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
227
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
228 **default**: ``true``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
229
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
230 ``ap_path``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
231 Path prefix to use for ActivityPub request. It's usually not necessary to change the
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
232 default value.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
233
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
234 **default**: ``_ap``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
235
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
236
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
237 .. _ap-actor-from-xmpp:
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
238
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
239 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
240 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
241
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
242 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
243 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
244 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
245
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
246 `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
247 must be escaped with ``\40``.
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 .. _XEP-0106: JID Escaping
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
250
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
251 **example**
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
252
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
253 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
254 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
255 ``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
256 ``pierre\40example.net@ap.example.org``.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
257
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
258 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
259 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
260 ``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
261 actor identifier rather than an XMPP JID.
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
262
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
263
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
264 .. _xmpp-node-from-ap:
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
265
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
266 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
267 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
268
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
269 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
270
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
271 - 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
272 - 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
273
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
274
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
275 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
276 like this:
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
277
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
278 - 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
279 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
280 JID can be directly used as AP actor handle
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
281 - 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
282 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
283 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
284 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
285 ``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
286 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
287 - 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
288 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
289 from entity: ``some_node--some_user@example.org``
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
290 - 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
291 special encoding (see below).
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
292
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
293 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
294
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
295 .. automethod:: sat.plugins.plugin_comp_ap_gateway.APGateway.getJIDAndNode
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
296
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
297
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
298 .. [#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
299 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
300 handles, according to `RFC7565`_, should
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
301 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
302
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
303 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
304 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
305 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
306 way to encode characters had to be found.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
307
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
308 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
309 https://github.com/mastodon/mastodon/issues/17222
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
310
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
311 .. _RFC7565: https://datatracker.ietf.org/doc/html/rfc7565
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
312 .. [#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
313
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
314 **example**
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
315
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
316 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
317 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
318 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
319
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
320 .. note::
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
321
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
322 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
323 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
324
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
325
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
326 Getting AP Message from XMPP
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
327 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 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
330 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
331 :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
332 as regular XMPP blog items.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
333
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
334 .. note::
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
335
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
336 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
337 `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
338 anybody subscribe to the gateway node (i.e. follow the AP actor), as the collection
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
339 will then be cached, and efficiently delivered. Note that subscription/following is NOT
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
340 IMPLEMENTED YET, but will be in the close future.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
341
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
342 .. _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
343 .. _RSM: https://xmpp.org/extensions/xep-0059.html
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
344
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
345 .. note::
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
346
3734
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
347 Only "root" items are currectly converted, i.e. items which are not replies to other
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
348 objects. Replies will be managed in the close future with AP collections caching.
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
349
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
350 Getting XMPP Items from ActivityPub
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
351 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
352
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
353 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
354 :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
355 handle in AP implementations, e.g.: ``@louise@example.org``).
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
356
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
357 .. note::
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
358
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
359 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
360 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
361 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
362
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 Using the Component (for developers)
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
365 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
366
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
367 Publication of AP items can be tested using the following method (with can be accessed
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
368 through the ``APSend`` bridge method, client is then replaced by the ``profile`` name, as
643622ff1492 doc (components): update AP component documentation:
Goffi <goffi@goffi.org>
parents: 3683
diff changeset
369 last argument):
3683
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
370
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
371 .. 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
372
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
373 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
374 <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
375 use the D-Bus bridge).
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
376
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
377 example
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
378 ~~~~~~~
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
379
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
380 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
381 ``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
382 Louise can use the following command::
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
383
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
384 $ 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
385
a1eff4e32848 doc (components): base documentation for AP Gateway:
Goffi <goffi@goffi.org>
parents: 3678
diff changeset
386 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
387 object.