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 or Comment depending on inReplyTo.
    • 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 object content * raw_content will be the source content
  • if the object has no object.source property: * _media_type will be text/html * rendered_content will be the object content * 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.