kopia lustrzana https://gitlab.com/jaywink/federation
149 wiersze
5.8 KiB
ReStructuredText
149 wiersze
5.8 KiB
ReStructuredText
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 :ref:`example-projects`.
|
|
|
|
.. _diaspora:
|
|
|
|
Diaspora
|
|
--------
|
|
|
|
This library only supports the `current renewed version <http://diaspora.github.io/diaspora_federation/>`_ 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:
|
|
|
|
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:
|
|
|
|
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 <https://matrix.org/blog/2020/12/18/introducing-cerulean>`_
|
|
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 :ref:`usage-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.
|