kopia lustrzana https://gitlab.com/jaywink/federation
127 wiersze
4.4 KiB
ReStructuredText
127 wiersze
4.4 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 alpha - all the basic
|
|
things work but there are likely to be a lot of compatibility issues with other ActivityPub
|
|
implementations.
|
|
* 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 from the above objects
|
|
* Follow, Accept Follow, Undo Follow
|
|
* Announce
|
|
|
|
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
|
|
* ``_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 object ``content`` run through a HTML2Markdown renderer
|
|
|
|
For outbound entities, ``raw_content`` is expected to be in ``text/markdown``,
|
|
specifically CommonMark. When sending payloads, ``raw_content`` will be rendered via
|
|
the ``commonmark`` library into ``object.content``. The original ``raw_content``
|
|
will be added to the ``object.source`` property.
|
|
|
|
Images
|
|
......
|
|
|
|
Any images referenced in the ``raw_content`` of outbound entities will be extracted
|
|
into ``object.attachment`` objects, for receivers that don't support inline images.
|
|
These attachments will have a ``pyfed:inlineImage`` property set to ``true`` to
|
|
indicate the image has been extrated from the content. Receivers should ignore the
|
|
inline image attachments if they support showing ``<img>`` HTML tags or the markdown
|
|
content in ``object.source``.
|
|
|
|
For inbound entities we do this automatically by not including received attachments in
|
|
the entity ``_children`` attribute.
|
|
|
|
.. _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.
|