Protocols¶
Currently three protocols are being focused on.
- Diaspora is considered to be stable with most of the protocol implemented.
- ActivityPub support should be considered as beta - all the basic things work and we are fixing incompatibilities as they are identified.
- Matrix support cannot be considered usable as of yet.
For example implementations in real life projects check Projects using federation.
Diaspora¶
This library only supports the current renewed version of the protocol. Compatibility for the legacy version was dropped in version 0.18.0.
The feature set supported is the following:
Webfinger, hCard and other discovery documents
NodeInfo 1.0 documents
Social-Relay documents
Magic envelopes, signatures and other transport method related necessities
Entities as follows:
- Comment
- Like
- Photo
- Profile
- Retraction
- StatusMessage
- Contact
- Reshare
ActivityPub¶
Features currently supported:
Webfinger
Objects and activities as follows:
- Actor (Person outbound, Person, Organization, Service inbound)
- Note, Article and Page (Create, Delete, Update)
* These become a
Post
orComment
depending oninReplyTo
. - Attachment images, (inbound only for audios and videos) from the above objects
- Follow, Accept Follow, Undo Follow
- Announce
- Inbound Peertube Video objects translated as
Post
.
Inbound processing of reply collections, for platforms that implement it.
Link, Like, View, Signature, PropertyValue, IdentityProof and Emojis objects are only processed for inbound payloads currently. Outbound processing requires support by the client application.
Namespace¶
All payloads over ActivityPub sent can be identified with by checking @context
which will include the pyfed: https://docs.jasonrobinson.me/ns/python-federation
namespace.
Content media type¶
The following keys will be set on the entity based on the source
property existing:
- if the object has an
object.source
property: *_media_type
will be the source media type (only text/markdown is supported). *rendered_content
will be the objectcontent
*raw_content
will be the sourcecontent
- if the object has no
object.source
property: *_media_type
will betext/html
*rendered_content
will be the objectcontent
*raw_content
will be empty
The contentMap
property is processed but content language selection is not implemented yet.
For outbound entities, raw_content
is expected to be in text/markdown
,
specifically CommonMark. The client applications are expected to provide the
rendered content for protocols that require it (e.g. ActivityPub).
When sending payloads, object.contentMap
will be set to rendered_content
and raw_content
will be added to the object.source
property.
Medias¶
Any images referenced in the raw_content
of outbound entities will be extracted
into object.attachment
object. For receivers that don’t support inline images,
image attachments will have a pyfed:inlineImage
property set to true
to
indicate the image has been extracted from the content. Receivers should ignore the
inline image attachments if they support showing <img>
HTML tags or the markdown
content in object.source
. Outbound audio and video attachments currently lack
support from client applications.
For inbound entities we do this automatically by not including received image attachments in
the entity _children
attribute. Audio and video are passed through the client application.
Hashtags and mentions¶
For outbound payloads, client applications must add/set the hashtag/mention value to
the class
attribute of rendered content linkified hashtags/mentions. These will be
used to help build the corresponding Hashtag
and Mention
objects.
For inbound payloads, if a markdown source is provided, hashtags/mentions will be extracted
through the same method used for Diaspora. If only HTML content is provided, the a
tags
will be marked with a data-[hashtag|mention]
attribute (based on the provided Hashtag/Mention
objects) to facilitate the href
attribute modifications lient applications might
wish to make. This should ensure links can be replaced regardless of how the HTML is structured.
Matrix¶
The aim of Matrix support in this library is not to provide instant messaging but to wrap the parts of the Matrix protocol that specifically are especially useful for social media applications. The current ongoing work on Ceruelan provides much of what will be implemented in this library.
This library doesn’t aim to be a homeserver or provide any part of the server to server API. The plan is to provide an appservice to hook onto a separate homeserver that deals with all the complex protocol related details. This library will then aim to abstract much of what the appservice gives or takes behind the same API as is provided for the other protocols.
Currently support is being added, please visit back in future versions.
NOTE! Current features also assume Django is configured, though this is likely to not be the case in the future.
Appservice¶
To generate the appservice registration file you must ensure you’ve added the relevant configuration (see Configuration).
Then launch a Django shell inside your project and run the following:
from federation.protocols.matrix.appservice import print_registration_yaml
print_registration_yaml()
This YAML needs to be registered with the linked Matrix homeserver as instructed in the relevant homeserver documentation.