Libervia Components¶
Libervia can act as an XMPP server component, which can be seen as a generic plugin for XMPP servers.
This page explains which components are available and how to use them.
Running a component¶
Components are linked to a Libervia profile in the same way as normal clients.
To run a component, you’ll need to know its entry point, which is the name of the import name of plugin managing it. The entry point to use will be specified in the component installation documentation.
You’ll also have to declare the component on your XMPP server, this is a server dependent step and you’ll have to check your server documentation for details. You’ll have to specify a shared secret (can also be named simply password) that must be set both on the XMPP server and as the XMPP password of the Libervia profile.
Here is a list of relevant documentation for most common servers:
- ejabberd
https://docs.ejabberd.im/admin/configuration/listen-options/
- MongooseIm
https://esl.github.io/MongooseDocs/latest/configuration/listen/#xmpp-components-listenservice
- OpenFire
use the web-based admin panel
- Prosody
- Tigase
On Libervia, setup is done with Libervia CLI’s profile create command.
You’ll usually want to have the component to start automatically when the backend
is started, for this you must unset the profile password (not to be confused with the XMPP
password which is the one also set on the server configuration) with -p ""
and set
auto-connection with -A
.
You’ll specify the XMPP password (also named shared secret in XEP-0144 terminology)
with -x <your_shared_secret>
and the JID to use with -j
<component_subdomain>.<server.tld>
.
The component entry point is specified with -C <entry_point>
.
example¶
Louise wants to run an ActivityPub gateway on her server example.org
with the JID
ap.example.org
. The shared secret is xmpp_rocks
and she wants the component to
start automatically with the backend, thus she doesn’t set a profile password. The
entry-point for ActivityPub component is ap-gateway
, and she wants to use the same
name for the profile. To do this, she enters the following command:
$ li profile create ap-gateway -j ap.example.org -p "" -x xmpp_rocks -C ap-gateway -A
The component will then be started next time Libervia Backend is launched. If Louise wants to connect it immediately, she can use:
$ li profile connect -cp ap-gateway
Available Components¶
Below is a list of currently available components in Libervia, and instructions on what they do and how to use them.
File Sharing¶
entry_point: file-sharing
File Sharing component manage the hosting of user files. Users can upload file there using either Jingle File Transfer or HTTP File Upload.
There is no limit to the size of files which can be uploaded, but administrators can set a quota to limit the space that can be used.
Files can be retrieved using File Information Sharing, and deleted using Ad-Hoc Commands.
Files can be shared with a public HTTP link, or made available only to a specified list of entities (JIDs). Permissions can be set through Ad-Hoc Commands.
Configuration¶
All options are to be set in [component file-sharing]
section.
http_upload_port
port to use for HTTP File Upload
default: 8888
http_upload_connection_type
either
http
orhttps
.default:
https
Note that HTTP Upload should always be
https
to end-user, thehttp
option is to be used only if you use a HTTP server as a proxy, and this server is already set for TLS.http_upload_public_facing_url
must be set to the URL that end-user will see. Notably useful if the component is behind a proxy.
default:
https://<component host>:<http_upload_port
quotas_json
a JSON object indicating quotas to use for users. The object can have 3 keys:
admins
quotas to use for administrators (i.e. profiles set in
admins_list
)users
quotas to use for normal users (i.e. non admin profiles)
jids
per-jid specific quotas. The value is a JSON object where key is a user bare jid and value is a quota.
Quotas can be either
null
for unlimited space, or a size value (SI prefixes and binary prefixes can be used).example:
quotas_json = { "admins": null, "users": "50 Mio", "jids": {"pierre@example.org": "1 Gio"} }
ActivityPub Gateway¶
entry_point: ap-gateway
Note
this component is currently in active development, and not yet fully functional. This documentation will be updated during evolution of component.
You can follow the development by reading Libervia Progress Notes.
This gateway will provide a bidirectional gateway between XMPP and ActivityPub (or AP below). That means that user from XMPP will be able to follow actors or comments messages from any software compatible with ActivityPub protocol, and vice versa.
Note
this component is mostly tested with Prosody as XMPP server reference, and Mastodon as AP server reference, but it should work with any XMPP or AP server.
The component launches a HTTP server (necessary to communicate with AP software). This
server needs to handle HTTP requests made at paths /.well-known/webfinger
and /_ap
(or the ap_path
set in configuration, see below). If the component is not directly
facing internet (e.g. integrated in an existing website though a proxy), you’ll have to
redirect the requests made to those path to the HTTP server (i.e. to component host at the
port set at http_port
, see configuration below). Please check your HTTP server
documentation to find how this must be done.
Configuration¶
All options are to be set in [component ap-gateway]
section.
public_url
Main user-facing domain of the HTTP server, this will be used to construct all AP URLs
default: if not set,
xmpp_domain
is used. Ifxmpp_domain
is not set either, an error is raised.http_port
port where the HTTP server should listen. Port
80
is not used directly as it would require root privileges, and it is strongly recommended against launching Libervia under a privileged account. An HTTP Proxy or a port redirection should be set to redirect the80
port to the port specified here.default:
8123
http_connection_type
either
http
orhttps
. If you have a HTTP proxy such as Apache or NGINX which already handles HTTPS, you may want to usehttp
.default:
https
Note that the HTTP server should always use
https
with end-user, thehttp
option is only to be used with an HTTPS proxy.local_only
A boolean value indicating if the gateway is allowed to convert pubsub node from external XMPP service or not. A JID is considered external if its domain part doesn’t end with the gateway’s server. For instance, if a gateway
ap.example.org
is set on the serverexample.org
, the JIDspierre@example.org
orsome-node@pubsub.example.org
will be considered local, butbuenaventura@example.net
won’t (note the different domain).Most of time,
local_only
should be used.default:
true
ap_path
Path prefix to use for ActivityPub request. It’s usually not necessary to change the default value.
default:
_ap
comments_max_depth
An integer value indicating the maximum number of comment nodes that can be created. See ActivyPub to XMPP Discussion Threads Conversion
auto_mentions
A boolean value indicating if received XMPP pubsub blog items bodies must be scanned to find
@user@server.tld
type mentions. If mentions are found, they’ll be added to the resulting AP items.default:
true
html_redirect_dict
A dictionary used to redirect HTTP requests when it’s not an ActivityPub request (i.e. when the
Accept
header is not set toapplication/json
). Several ActivityPub implementations link to original server when clicking on some links such as post author or item ID, and this result in a request to the corresponding ActivityPub endpoint, but made to retrieve HTML instead of ActivityPub JSON data.By default, this request is showing the corresponding AP JSON data, but if you set HTML redirection, you can redirect the page to your XMPP client web frontend (or anything making sense), which results in better user experience.
The expected dictionary is a mapping URL request types to destination URL.
The URL request types is the first path element after
ap_path
, it can be:actor
Actor information. It should link to the profile page of the corresponding XMPP entity
item
A specific publication. It should link to the rendered item
followers
Entities publicly subscribed to the actor. It is usually not used for redirection.
following
Entities that the actor is publicly subscribed to. It is usually not used for redirection.
In the target URL you can uses template values in curly braces (something like
{item}
). The values that you can use are:jid
Full JID corresponding to the AP actor.
jid_user
Only the user part of the JID (what is before the
@
)node
Name of the pubsub node corresponding to the AP actor.
item
ID of the XMPP pubsub item.
You can use a slash
/
followed by a part of a node name to filter only on specific nodes. For instance, if you want to redirect microblog items to a different URL that event items, you can useitem/urn:xmpp:microblog:0
anditem/urn:xmpp:events:0
, the first redirection to match will be used. Note that anything containing the filter value will match, thus you can also useitem/microblog
(but it then would match an event which hasmicroblog
in is node name).You can also use a dictionary as value instead of the target URL. This can be useful to filter on an other value than the node name, if you want to make specific redirection for a particular user for instance. If you use a dictionary, you must use a
url
key with the target URL (which may have template values as usual), and you may use afilters
key mapping to an other dictionary where each key is a filter on a specific template value (in other words: key is the template value, likejid
ornode
, and value is the filter to match).examples
Redirect actor page to
/profile/<JID user part>
, blogs items to/blog/<full JID>/<node name>/<item id>
and events items to/event/<full JID>/<node name>/<item id>
html_redirect_dict = { "actor": "/profile/{jid_user}", "item/microblog": "/blog/{jid}/{node}/{item}", "item/events": "/event/{jid}/{node}/{item}" }
Redirect items of user
louise@example.org
to/b/<item>
:html_redirect_dict = { "item": { "url": "/b/{item}", filters: { "jid": "louise@example.org" } } }
How to Address an AP Actor from XMPP¶
When addressing an ActivityPub actor from XMPP, you must use a JID corresponding to the
actor. The domain part of the JID correspond to the gateway JID (the one set in gateway
profile), while the local part (before the @
) is used to specify the AP actor.
XEP-0106 (JID Escaping) is used to indicate the AP actor identifier, thus the @
must be escaped with \40
.
example
If Louise wants to talk to Pierre which is on the example.net
AP server, she can use
her XMPP AP gateway which is at ap.example.org
. Pierre AP’s actor handle is
pierre@example.net
, Louise can access it via the JID
pierre\40example.net@ap.example.org
(we call it virtual JID of the AP actor).
Of course, this is a bit cumbersome to do by hand, it is expected that XMPP clients will
do the (un)escaping automatically for end-user, in a way that Louise could enter
pierre@example.net
directly, with an indicator to show that this is an ActivityPub
actor identifier rather than an XMPP JID.
How to Address an XMPP Entity from AP¶
To access an XMPP entity, it is a little bit more complicated for 2 reasons:
XMPP use a wider range of allowed characters than most AP implementations [1].
to get XMPP items, we need 2 data: the entity JID, and a pubsub node
However, Libervia AP gateway tries to make it as user friendly as possible, thus it works like this:
in the most common case, one just wants to access the personal blog of a user, and basic ASCII characters (with possibly
-
,_
or.
) are used. in this case, the XMPP JID can be directly used as AP actor handlewhen a pubsub node needs to be specified it is most of time with a pubsub JID which has not user part (something like
pubsub.example.org
). In this case, the pubsub node can be used as AP actor handle’s user part, Libervia will use XMPP discovery to know that it’s a pubsub service. So if you want to access the blog namedxmpp_news
atpubsub.example.org
, you can use the handlexmpp_news@pubsub.example.org
(be sure that the domainpubsub.example.org
links to the Libervia AP gateway HTTP server)if you want to use a specific node with an entity which already has a user part, then a special encoding must be used, where
---
(three dashes) are used to separate node from entity:some_node--some_user@example.org
if you need to use special characters, then you’ll have to use
___
followed by the special encoding (see below).
The encoding is explained in the documentation of the following method:
- async APGateway.getJIDAndNode(ap_account: str) Tuple[JID, Optional[str]] ¶
Decode raw AP account handle to get XMPP JID and Pubsub Node
Username are case insensitive.
By default, the username correspond to local username (i.e. username from component’s server).
If local name’s domain is a pubsub service (and not PEP), the username is taken as a pubsub node.
If
---
is present in username, the part before is used as pubsub node, and the rest as a JID user part.If username starts with
___
, characters are encoded using period encoding (i.e. percent encoding where a.
is used instead of%
).This horror is necessary due to limitation in some AP implementation (notably Mastodon), cf. https://github.com/mastodon/mastodon/issues/17222
examples:
toto@example.org
=> JID = toto@example.org, node = None___toto.40example.net@example.org
=> JID = toto@example.net (this one is a non-local JID, and will work only if setingslocal_only
is False), node = Nonetoto@pubsub.example.org
(with pubsub.example.org being a pubsub service) => JID = pubsub.example.org, node = tototata---toto@example.org
=> JID = toto@example.org, node = tata___urn.3axmpp.3amicroblog.3a0@pubsub.example.org
(with pubsub.example.org being a pubsub service) ==> JID = pubsub.example.org, node = urn:xmpp:microblog:0- Parameters:
ap_account – ActivityPub account handle (
username@domain.tld
)
- @return: service JID and pubsub node
if pubsub node is None, default microblog pubsub node (and possibly other nodes that plugins may hanlde) will be used
- Raises:
ValueError – invalid account
PermissionError – non local jid is used when gateway doesn’t allow them
example
If Pierre wants to talk to Louise, he can directly use the JID which is the same as the AP
actor identifier, i.e. louise@example.org
(note that on AP software, a @
prefix is
often required, thus Pierre will look for @louise@example.org
).
Note
The actor endpoint can also be used directly in AP software (in the example above, it
would be by default https://example.org/_ap/actor/louise%40example.org
).
Ad-Hoc Commands¶
The gateway supports XEP-0050 (Ad-Hoc Commands). For now, only the following node is provided:
https://libervia.org/ap_gateway/xmpp_jid_node_2_ap_actor
Convert XMPP JID and Node to corresponding virtual actor. Node is optional.
Getting AP Message from XMPP¶
To retrieve ActivityPub messages of an actor from an XMPP client with blogging
capabilities (like Libervia or Movim), just use the associated JID as explained in
How to Address an AP Actor from XMPP. The actor messages (from outbox
collection) should appear
as regular XMPP blog items.
Note
Due to limitation of ActivityStream Collection Paging, the conversion from XMPP RSM requests is inneficient beyond first or last page. This problem is avoided if anybody subscribe to the gateway node (i.e. follow the AP actor), as the collection will then be cached, and efficiently delivered.
Getting XMPP Items from ActivityPub¶
To get XMPP items from an ActivityPub implementation, just use the handle as explained at
How to Address an XMPP Entity from AP (often handle searches are triggered with a @
before the
handle in AP implementations, e.g.: @louise@example.org
).
Note
Some AP implementations such as Mastodon don’t retrieve existing items, but only keep new ones once an actor is followed. That means that you won’t see any message published before your entity is followed. Other implementations may work differently.
ActivyPub to XMPP Discussion Threads Conversion¶
By default, each (micro)blog publication converted from ActivityPub to XMPP Pubsub is associated with a comment node (see XEP-0277 comments) to allow user to post a reply on any on them. This result in a “tree-like” comments threading model, which is similar to what you can see on popular website such as Reddit, Hacker News, or LinuxFr.
However, some XMPP clients may not play nicely with this kind of threading model. To work
around this, the comments_max_depth
option allows to limit the maximum number of
thread. It is an integer value which indicate how many comments nodes may exist for a root
post. If set to 1
, only one comment node will be made, and ActivityPub items below
this level will be moved to this single XMPP pubsub comment node.
The default value of 0
means unlimited max depth.
An example can probably make it more clear. Imagine that you have a message root
message
, with a comment to it named 1
, a comment to 1
named 2
and so on
until 5
. With comments_max_depth
set to 0
, you’ll have one comment node per
item, resulting in following threads model:
root message ┑
┕ 1 ┑
┕ 2 ┑
┕ 3 ┑
┕ 4 ┑
┕ 5
With comments_max_depth
set to 2
, only 2 nodes will be created, and items below
depth 2
will be put on the same level:
root message ┑
┕ 1 ┑
┝ 2
┝ 3
┝ 4
┕ 5
This way, admins can configure the model which suits best the clients which is expected to be mainly used on the instance.
Publishing an Item¶
To publish a new item (e.g. a blog post), you just need to publish normally on your own PEP/pubsub node, AP actors following you will be notified. To reply to an AP item, just publish to the corresponding pubsub node managed by the gateway. This is transparent for AP and XMPP end users.
For instance, if Pierre has posted an interesting message on his AP server, and Louise wants to reply to it, she just use a client to reply on the comments node of this message, this will be delivered as an AP object to Pierre’s AP server.
On the other hand, if Louise is publishing a new blog post on her XMPP server, Pierre will receive corresponding AP object because he’s following her. If Pierre answer using his AP client, the corresponding message will be published on the comments node of the message that Louise has initially published.
Following, Subscribing and Cache¶
When you try to access an uncached AP collection from XMPP (e.g. blog posts), a best effort is done to translate XMPP pagination (which uses XEP-0059 (Result Set Management)) to the less powerful AP Collection Paging. This is inefficient due to technical limitations (page size can’t be specified in AP, there is not standard way to request item after or before a specific ID, implementations may not implement reverse pagination).
That’s one of the reason why whenever possible, collections are cached locally. Once cached, it’s easier to return items according to complex requests.
However, to cache correctly an AP collection, you need to keep it in sync, and thus to receive update when something change (e.g. a new blog item is published).
In AP, this is done by following an actor, in XMPP this correspond to a node subscription.
When you subscribe to a blog node managed by this gateway, this will be translated to a follow activity on AP side, and vice versa.
When an AP actor is followed, its outbox collection (i.e. message published), are automatically cached, and will be updated when events will be received. That means that you can use pubsub cache search on followed actors, e.g. to retrieve all items about a specific topic or published at specific time range.
Reciprocally, unsubscribing from a node will unfollow the corresponding AP actor.
If an AP actor is following or unfollowing an actor mapping an XMPP entity, they nodes will be subscribed to or unsubscribed from.
All subscriptions are made public as specified by XEP-0465 (Pubsub Public Subscriptions).
Following/Followers Collections and Public Pubsub Subscription¶
The AP following collection is mapped to XEP-0465 (Pubsub Public Subscriptions).
In the same spirit, the AP followers collection correspond to public subscribers to the microblog node.
Because AP doesn’t send any event when following or followers collections are modified, those collections can’t be cached, and thus the translation to public pubsub subscriptions is done as best as possible given the constraints.
Messages Delivery¶
The gateway can convert AP publications to either XMPP pubsub items (using XEP-0277 (Microblogging over XMPP) when suitable) or to XMPP messages (<message> stanzas, i.e. the ones used for instant messaging). Of course it also converts in a similar way in the other direction (XMPP → ActivityPub).
A received AP item will be converted to an XMPP pubsub item if any of the following conditions is fulfilled:
it is addressed to the special *public* collection
it is addressed to a local followers collection
A received AP item will be converted to an XMPP message if all the following conditions are fulfilled:
it is not addressed to the special public collection
it is not addressed to a any local followers collection.
In other words, if an AP item is addressed directly to one or more local users, is not public and is not addressed to a followers collection, it will be converted to an XMPP message, otherwise it will be converted to an XMPP pubsub item.
The behaviour is symmetric, thus if you send an XMPP message it will be converted to an AP item which will be only addressed to your recipient. If you write using XMPP pubsub, the suitable followers collections of the target AP actor will be automatically added, and the item will have the special public collection added.
Note
ActivyPub doesn’t do any kind of end-to-end encryption, it is not the same level of privacy as XMPP.
Messages will be at minimum readable by the administrators of the AP gateway and of the ActivyPub server of the destinee. Be sure to understand that before sending messages.
If you need more privacy, you need to use either XMPP only (without the ActivityPub gateway) with clients implementing correctly end-to-end encryption, or an other software. Depending of the level of pricacy required, you may want to use authentication by a separated channel, a client which has been audited, encryption by default, etc. This is beyond the scope of this AP gateway documentation.
In short, don’t use ActivityPub if you need a high level of privacy. This is a current protocol limitation, and there is nothing that this gateway can do about this until ActivityPub and its implementations evolve.
Message/Item Retraction¶
If you retract a pubsub item (e.g. a blog post), that is followed by ActivityPub actors, a suitable Delete activity will be emitted. In other words, the ActivityPub servers will be notified of the retraction.
Similarly if an AP actor is deleting an item, a suitable XEP-0060 retraction event will be sent to subscribers.
In the case of direct messages (see Messages Delivery), XEP-0424 (Message
Retraction) is used in both reception (AP Delete
activity is converted to XEP-0424
and vice versa).
All of this should be transparent to users as long as their clients support the mentioned XEPs.
Note
When retracting a message/item, a retraction request (or equivalent AP “Delete” activity) is sent, so the other end clients may delete the item.
However, there is no way to be sure that the item will be actually deleted: once something is sent on the network, any recipient can see it, copy it, share it, etc. There is no way to forbid that, and this is true for software, decentralized or not (and not only ActivityPub or XMPP).
Be sure to understand that before sending anything sensitive.
Note
When deleting an item on ActivityPub, the item is often replaced by a “tombstone”, and it’s not possible to send a new item with the same ID. Some software (it’s at least the case with Mastodon), will silently reject the item, and thus people won’t see it.
This is a different behaviour from XMPP where you can publish a pubsub item, retract it, and publish a new item with the same ID.
Thus if you retract an item, be sure to publish any new one with new and unique ID, otherwise the item may not appear to ActivityPub users (and as the item may be rejected silently, you may not be notified).
However this should not be a problem in the vast majority of cases, as most XMPP client implementing pubsub or pubsub service will generate automatically unique IDs for new items.
Blocking an User¶
You can block AP actors using its virtual JID in the same way as for any XMPP entity, by using XEP-0191 (Blocking Command).
This is done at the XMPP server level and your server must support it. From client side, many clients support it, and you can use Libervia CLI to do it from command-line (see blocking: entities blocking).
Identity and Avatar¶
The gateway does the conversion between XMPP identity and AP actor metadata.
XMPP “identity” is actually a compilation of data coming from various locations and in
particular XEP-0292 (vCard4 Over XMPP). In those data, vCard’s nickname
(first
found) is used as AP name
field, and vCard’s note
is used as AP’s summary
(it’s generally a self-description of users).
For avatars, XEP-0084 (User Avatar) is used (and actor’s icon
field is used on AP
side). Avatars are downloaded the first time that they are requested, and kept in cache
for future requests.
Even if XEP-0292 and XEP-0084 are the main XEPs used, Libervia checks various locations, and other extensions like XEP-0054 (vcard-temp) may be used as fallback.
Mentions¶
Mentions are converted by the gateway under some conditions explained below.
When receiving an AP item which converts to a pubsub item (i.e. not a direct message), for
any local user mentioned (using a tag of type Mention
) or directly specified in a
target field (to
, bto
, cc
or bcc
), a XEP-0372 (References) type mention
will be emitted.
This is not done for direct message as the recipients are already specified, and sending reference is most probably not desired for a private message.
In the direction XMPP 🠞 ActivityPub, it’s more complicated because XMPP sends references separately from the pubsub item, while ActivityPub links them in the same item.
If a XEP-0372 reference targeting an AP actor is received and anchor a pubsub item, the item will be looked after in cache. If found, it will be converted to an AP item, a mention will be added, and the item will be delivered to the mentioned entity.
This only works if the mentioned actor is on a server which has not already received the original item, because otherwise the AP implementation will most probably ignore the new item which has the same ID.
It is hard to avoid sending first published item, then the same item with the reference, because XEP-0372 references are received after the published items.
To work around that, when an XMPP blog item is received, its body is scanned to find
@user@server.tld
type mention, and if found a mention is automatically added to the
resulting AP item.
It is not ideal to parse the body, but that’s an acceptable trade-off to make mention
working. This behaviour is activated by default, but can be deactivated by setting
auto_mentions
option to false
. Auto mentions are only used for pubsub items, and
not for direct messages for the same reason as mention are not checked in AP direct
messages (see above).
Note
For auto mentions, it’s the AP actor handle which must be used, not the corresponding virtual JID.
If you want to mention louise@example.org
then you must use directly
@louise@example.org
, and NOT something like
@louise\40example.org@ap.example.net
.
To mention XMPP entities, your client must use XEP-0372 references directly.
Noticed/Like¶
AP’s Like
activity is converted on the XMPP side to “XEP-0470 (Pubsub
Attachments)”. Like
is converted to noticed
attachment, meaning that it used in
to indicate that something has been seen and taken into account, without really indication
if the content is liked or disliked (see XEP-0470 § Foreword: “noticed” instead of “like”
or “favourite” for the rational).
As usual, conversion is done in both ways.
Reactions¶
Reactions are not specified in base ActivityPub specification. However Pleroma, a
software implemeting ActivityPub, implements them using a non standardised (yet?)
EmojiReact
activity. Liberva AP Gateway use it to handle reactions.
On the XMPP side, XEP-0470 (Pubsub Attachments) is once again used.
Libervia also implements XEP-0444 (Message Reactions) for messages, but because Pleroma doesn’t handle reactions for direct messages, this is not used in the Libervia AP gateway. If in the future an AP implementation uses reactions on direct messages, it will be straightforward to add it in the AP gateway.
Events¶
This gateway manages events. On the XMPP side, the Events
protoXEP is used, on AP side
Event
objects are used. Mobilizon is used as reference implementation here.
Note
The Events
protoXEP has been proposed but not published or reviewed by XMPP council
yet. The current version is availale at https://github.com/xsf/xeps/pull/1206 and
hopefully it will eventually become an official experimental XEP. The code and this
documentation will be updated as the standard evolves.
To retrieve AP events from XMPP, use the corresponding virtual JID as explained in
How to Address an AP Actor from XMPP with the event node (which is urn:xmpp:events:0
).
example:
To retrieve events from AP actor with the handle somebody@mobilizon.example
, throught
the ap.example.org
gateway, the somebody\40mobilizon.example@ap.example.org
JID
can be used with the urn:xmpp:events:0
node.
To retrieve XMPP events from AP, you need to the virtual actor corresponding to the JID
of the pubsub/PEP service with the event node (starting with urn:xmpp:events:0
), as
explained in How to Address an XMPP Entity from AP. You can use Ad-Hoc Commands to easily convert your
JID/node combination to a virtual AP actor. Note that the resulting virtual actor is
unaesthetic due to the presence of event node and the constraints explained in
How to Address an XMPP Entity from AP.
To retrieve the link to the XMPP item from AP, you can use the ID from the generated AP
object. The ID can also be constructed by hand by using the URL
https://<ap_gateway_public_domain>/_ap/<virtual_actor>/<event_item_id>
.
example:
to retrieve from AP the XMPP event at pubsub service pubsub.example.net
on node
urn:xmpp:events:0/party
with item ID picnic_abd1
, and using the AP gateway with
public url https://ap.example.net
, the following link can be used:
https://ap.example.net/_ap/___urn.3Axmpp.3Aevents.3A0.2Fparty---pubsub.2eexample.2enet@ap.tazar3.int/picnic_abd1
If you paste it in an AP implementation featuring events (e.g. Mobilizon), the event should appear and you should be able to comment it and participate to it.
Event comments are supported, the node to use is indicated in the event XMPP item as specified in the protoXEP, this should be transparent to end-user.
Participation to an event is supported through the RSVP mechanism on XMPP and with
Join
and Leave
activities on AP. Note that XMPP allows more nuances with its RSVP
mechanism (it’s possible to say if someone will “maybe” attend an event, and to request
any kind of extra informations) while AP only indicates if one will attend or not an
event.
Using the Component (for developers)¶
Publication of AP items can be tested using the following method (with can be accessed
through the APSend
bridge method, client is then replaced by the profile
name, as
last argument):
- async APGateway.publishMessage(client: SatXMPPEntity, mess_data: dict, service: JID) None ¶
Send an AP message
Note
This is a temporary method used for development only
- Parameters:
mess_data –
message data. Following keys must be set:
node
identifier of message which is being replied (this will correspond to pubsub node in the future)
content_xhtml
orcontent
message body (respectively in XHTML or plain text)
service – JID corresponding to the AP actor.
The method can be used either with CLI’s debug bridge method or with any D-Bus tool like qdbus
or d-feet
(only if you
use the D-Bus bridge).
example¶
On its example.net
Mastodon instance, Pierre has published a message with the id
https://example.net/@pierre/106986412193109832
. To send a reply to this message,
Louise can use the following command:
$ 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"'
Note the double escaping, one for the shell argument, and the other to specify JSON object.