2016-10-02 10:08:37 +00:00
Usage
=====
Entities
--------
2019-10-05 22:57:24 +00:00
Federation has it's own base entity classes. When incoming messages are processed, the
protocol specific entity mappers transform the messages into our base entities. In
reverse, when creating outgoing payloads, outgoing protocol specific messages are
constructed from the base entities.
2016-10-02 10:08:37 +00:00
Entity types are as follows below.
.. autoclass :: federation.entities.base.Comment
2017-07-21 21:02:33 +00:00
.. autoclass :: federation.entities.base.Follow
2016-10-02 10:08:37 +00:00
.. autoclass :: federation.entities.base.Image
.. autoclass :: federation.entities.base.Post
.. autoclass :: federation.entities.base.Profile
.. autoclass :: federation.entities.base.Reaction
.. autoclass :: federation.entities.base.Relationship
.. autoclass :: federation.entities.base.Retraction
2017-08-17 18:33:18 +00:00
.. autoclass :: federation.entities.base.Share
2016-10-02 10:08:37 +00:00
Protocol entities
.................
2019-10-05 22:57:24 +00:00
Each protocol additionally has it's own variants of the base entities, for example
Diaspora entities in `` federation.entities.diaspora.entities `` . All the protocol
specific entities subclass the base entities so you can safely work with for example
`` DiasporaPost `` and use `` isinstance(obj, Post) `` .
2016-10-02 10:08:37 +00:00
2019-10-05 22:57:24 +00:00
When creating incoming objects from messages, protocol specific entity classes are
returned. This is to ensure protocol specific extra attributes or methods are
passed back to the caller.
2016-10-02 10:08:37 +00:00
2019-10-05 22:57:24 +00:00
For sending messages out, either base or protocol specific entities can be passed
to the outbound senders.
2016-10-02 10:08:37 +00:00
2019-10-05 22:57:24 +00:00
If you need the correct protocol speficic entity class from the base entity,
each protocol will define a `` get_outbound_entity `` function.
2016-10-02 10:08:37 +00:00
2019-10-05 22:57:24 +00:00
.. autofunction :: federation.entities.activitypub.mappers.get_outbound_entity
2016-10-02 10:08:37 +00:00
.. autofunction :: federation.entities.diaspora.mappers.get_outbound_entity
2019-09-08 19:48:47 +00:00
Federation identifiers
......................
2019-10-05 22:57:24 +00:00
All entities have an `` id `` to guarantee them a unique name in the network.
The format of the `` id `` depends on the protocol in question.
2019-09-08 19:48:47 +00:00
2019-09-08 20:08:18 +00:00
* ActivityPub: maps to the object `` id `` (whether wrapped in an Activity or not)
2019-09-08 19:48:47 +00:00
* Diaspora: maps to `` guid `` for the entity.
Profiles
++++++++
Profiles are uniquely identified by the `` id `` as above. Additionally for Diaspora they always have a `` handle `` .
ActivityPub profiles can also have a `` handle `` but it is optional.
A handle will always be in email like format, without the `@`
to outgoing payloads where needed.
Creator and owner identifiers
.............................
All entities except `` Profile `` have an `` actor_id `` which tells who created this object or activity. The format
depends on the protocol
in question.
* ActivityPub: maps to Object `` attributedTo `` or Activity `` actor_id `` .
* Diaspora: maps to entity `` author ``
Activity identifiers
....................
Entities which are an activity on something, for example creating, updating, deleting, following, etc, should have
an `` activity_id `` given to be able to send out to the ActivityPub protocol.
Mentions
........
Entities store mentions in the list `` _mentions `` . The list is a simple list of strings which will be either
an URL format `` profile.id `` or handle, as per above examples.
The syntax for a mention in text is URL format `` @{<profile.id>} `` or `` @{<profile.handle>} `` .
The GUID format `` profile.id `` cannot be used for a mention.
Examples:
::
# profile.handle
Hello @{user@domain.tld}!
# profile.id in URL format
Hello @{https://domain.tld/user}
It is suggested `` profile.handle `` syntax is used always for textual mentions unless handles are not available.
Inbound
+++++++
Mentions are added to the entity `` _mentions `` list when processing inbound entities. For ActivityPub they will be
extracted from `` Mention `` tags and for Diaspora extracted from the text using the Diaspora mention format.
Outbound
++++++++
Mentions can be given in the `` _mentions `` list. If not given, they will be extracted from the textual content
using the above formats in the example.
For ActivityPub they will be added as `` Mention `` tags before sending. If the mention is in handle format,
a WebFinger fetch will be made to find the profile URL format ID.
For Diaspora they will be added to the text
in the correct format, if not found. If they are found in the text in non-Diaspora format, they will be converted
before sending.
2016-10-02 10:08:37 +00:00
Discovery
---------
2019-10-05 22:57:24 +00:00
Federation provides many generators to allow providing discovery documents.
They have been made as Pythonic as possible so that library users don't have to
meddle with the various documents and their internals.
2016-10-02 10:08:37 +00:00
2019-10-05 22:57:24 +00:00
The protocols themselves are too complex to document within this library,
please consult protocol documentation on what kind of discovery documents are expected to
be served by the application.
2016-10-02 10:08:37 +00:00
Generators
..........
Helper methods
++++++++++++++
2018-04-07 18:58:56 +00:00
.. autofunction :: federation.hostmeta.fetchers.fetch_nodeinfo_document
.. autofunction :: federation.hostmeta.fetchers.fetch_nodeinfo2_document
.. autofunction :: federation.hostmeta.fetchers.fetch_statisticsjson_document
2016-10-02 10:08:37 +00:00
.. autofunction :: federation.hostmeta.generators.generate_host_meta
.. autofunction :: federation.hostmeta.generators.generate_legacy_webfinger
.. autofunction :: federation.hostmeta.generators.generate_hcard
2018-04-08 10:54:54 +00:00
.. autofunction :: federation.hostmeta.generators.generate_nodeinfo2_document
2016-10-02 10:08:37 +00:00
.. autofunction :: federation.hostmeta.generators.get_nodeinfo_well_known_document
Generator classes
+++++++++++++++++
.. autoclass :: federation.hostmeta.generators.DiasporaHostMeta
.. autoclass :: federation.hostmeta.generators.DiasporaWebFinger
.. autoclass :: federation.hostmeta.generators.DiasporaHCard
2020-12-20 15:55:01 +00:00
.. autoclass :: federation.hostmeta.generators.MatrixClientWellKnown
.. autoclass :: federation.hostmeta.generators.MatrixServerWellKnown
2016-10-02 10:08:37 +00:00
.. autoclass :: federation.hostmeta.generators.NodeInfo
2018-09-30 13:20:03 +00:00
.. autoclass :: federation.hostmeta.generators.RFC7033Webfinger
2016-10-02 10:08:37 +00:00
.. autoclass :: federation.hostmeta.generators.SocialRelayWellKnown
Fetchers
--------
High level utility functions to fetch remote objects. These should be favoured instead of protocol specific utility functions.
2017-10-20 22:31:56 +00:00
.. autofunction :: federation.fetchers.retrieve_remote_content
2016-10-02 10:08:37 +00:00
.. autofunction :: federation.fetchers.retrieve_remote_profile
Inbound
-------
2019-10-05 22:57:24 +00:00
High level utility functions to pass incoming messages to. These should be favoured
instead of protocol specific utility functions.
2016-10-02 10:08:37 +00:00
.. autofunction :: federation.inbound.handle_receive
Outbound
--------
High level utility functions to pass outbound entities to. These should be favoured instead of protocol specific utility functions.
2017-05-06 21:20:57 +00:00
.. autofunction :: federation.outbound.handle_send
2016-10-02 10:08:37 +00:00
2018-02-15 16:44:18 +00:00
Django
------
Some ready provided views and URL configuration exist for Django.
2019-10-05 22:57:24 +00:00
Note! Django is not part of the normal requirements for this library.
It must be installed separately.
2018-02-15 16:44:18 +00:00
2018-09-30 17:47:52 +00:00
.. autofunction :: federation.entities.activitypub.django.views.activitypub_object_view
2018-09-30 13:20:03 +00:00
.. autofunction :: federation.hostmeta.django.generators.rfc7033_webfinger_view
2020-12-20 15:55:01 +00:00
.. autofunction :: federation.hostmeta.django.generators.matrix_client_wellknown_view
.. autofunction :: federation.hostmeta.django.generators.matrix_server_wellknown_view
2018-04-08 10:54:54 +00:00
.. autofunction :: federation.hostmeta.django.generators.nodeinfo2_view
2018-02-15 16:44:18 +00:00
2020-12-21 21:09:29 +00:00
.. _usage-configuration:
2018-02-15 16:44:18 +00:00
Configuration
.............
To use the Django views, ensure a modern version of Django is installed and add the views to your URL config for example as follows. The URL's must be mounted on root if Diaspora protocol support is required.
::
url(r"", include("federation.hostmeta.django.urls")),
Some settings need to be set in Django settings. An example is below:
::
FEDERATION = {
"base_url": "https://myserver.domain.tld,
2018-09-30 17:47:52 +00:00
"get_object_function": "myproject.utils.get_object",
2019-03-17 01:17:10 +00:00
"get_private_key_function": "myproject.utils.get_private_key",
2018-07-31 21:44:30 +00:00
"get_profile_function": "myproject.utils.get_profile",
2020-12-20 15:55:01 +00:00
"matrix_config_function": "myproject.utils.matrix_config_funct",
2018-04-08 10:54:54 +00:00
"nodeinfo2_function": "myproject.utils.get_nodeinfo2_data",
2018-10-08 20:59:25 +00:00
"process_payload_function": "myproject.utils.process_payload",
2018-02-21 20:21:55 +00:00
"search_path": "/search/?q=",
2019-09-03 19:51:41 +00:00
"tags_path": "/tags/:tag:",
2018-02-15 16:44:18 +00:00
}
* `` base_url `` is the base URL of the server, ie protocol://domain.tld.
2018-10-10 19:43:17 +00:00
* `` get_object_function `` should be the full path to a function that will return the object matching the ActivityPub ID for the request object passed to this function.
2019-03-17 01:17:10 +00:00
* `` get_private_key_function `` should be the full path to a function that will accept a federation ID (url, handle or guid) and return the private key of the user (as an RSA object). Required for example to sign outbound messages in some cases.
2020-01-18 00:17:35 +00:00
* `` get_profile_function `` should be the full path to a function that should return a `` Profile `` entity. The function should take one or more keyword arguments: `` fid `` , `` handle `` , `` guid `` or `` request `` . It should look up a profile with one or more of the provided parameters.
2020-12-20 15:55:01 +00:00
* `` matrix_config_function `` (optional) function that returns a Matrix configuration dictionary, with the following objects:
::
{
# Location of the homeserver (not server name)
"homeserver_base_url": "https://matrix.domain.tld",
# Homeserver domain and port (not server domain)
"homeserver_domain_with_port": "matrix.domain.tld:443",
2020-12-23 22:58:13 +00:00
# Homeserver name
"homeserver_name": "domain.tld",
2020-12-21 21:09:29 +00:00
# Appservice details
"appservice": {
# Unique ID to register with at the homeserver. Don't change this after creating.
"id": "uniqueid",
2020-12-24 13:36:38 +00:00
# Short code (a-z only), used for various things like namespacing
"shortcode": "federatedapp",
2020-12-21 21:09:29 +00:00
# Secret token for communication
"token": "secret_token",
},
2020-12-20 15:55:01 +00:00
# (Optional) location of identity server
"identity_server_base_url": "https://id.domain.tld",
# (Optional) other keys to include in the client well-known (must be a dictionary)
"client_wellknown_other_keys": {
"org.foo.key" "barfoo",
},
2020-12-21 20:05:43 +00:00
# (Optional) registration shared secret
"registration_shared_secret": "supersecretstring",
2020-12-20 15:55:01 +00:00
}
2018-04-08 10:54:54 +00:00
* `` nodeinfo2_function `` (optional) function that returns data for generating a `NodeInfo2 document <https://github.com/jaywink/nodeinfo2> `_ . Once configured the path `` /.well-known/x-nodeinfo2 `` will automatically generate a NodeInfo2 document. The function should return a `` dict `` corresponding to the NodeInfo2 schema, with the following minimum items:
::
{server:
baseUrl
name
software
version
}
openRegistrations
2018-10-09 19:53:54 +00:00
* `` process_payload_function `` (optional) function that takes in a request object. It should return `` True `` if successful (or placed in queue for processing later) or `` False `` in case of any errors.
2018-02-21 20:21:55 +00:00
* `` search_path `` (optional) site search path which ends in a parameter for search input, for example "/search?q="
2019-09-03 19:51:41 +00:00
* `` tags_path `` (optional) path format to view items for a particular tag. `` :tag: `` will be replaced with the tag (without `` # `` ).
2016-10-02 10:08:37 +00:00
Protocols
---------
2018-09-30 17:47:52 +00:00
The code for opening and creating protocol messages lives under each protocol module in `` federation.protocols `` .
2016-10-02 10:08:37 +00:00
Each protocol defines a `` protocol.Protocol `` class under it's own module. This is expected to contain certain methods that are used by the higher level functions that are called on incoming messages and when sending outbound messages. Everything that is needed to transform an entity into a message payload and vice versa should be here.
Instead of calling methods directly for a specific protocol, higher level generic functions should be normally used.
Utils
-----
Various utils are provided for internal and external usage.
2019-10-05 22:57:24 +00:00
ActivityPub
...........
.. autofunction :: federation.utils.activitypub.retrieve_and_parse_content
.. autofunction :: federation.utils.activitypub.retrieve_and_parse_document
.. autofunction :: federation.utils.activitypub.retrieve_and_parse_profile
2016-10-02 10:08:37 +00:00
Diaspora
........
2017-10-20 22:31:56 +00:00
.. autofunction :: federation.utils.diaspora.fetch_public_key
2018-02-15 16:44:18 +00:00
.. autofunction :: federation.utils.diaspora.generate_diaspora_profile_id
2017-10-20 22:31:56 +00:00
.. autofunction :: federation.utils.diaspora.get_fetch_content_endpoint
2018-02-12 21:23:38 +00:00
.. autofunction :: federation.utils.diaspora.get_private_endpoint
2018-02-15 16:44:18 +00:00
.. autofunction :: federation.utils.diaspora.get_public_endpoint
2017-10-22 11:40:12 +00:00
.. autofunction :: federation.utils.diaspora.parse_diaspora_uri
2018-02-15 16:44:18 +00:00
.. autofunction :: federation.utils.diaspora.parse_profile_diaspora_id
2016-10-02 10:08:37 +00:00
.. autofunction :: federation.utils.diaspora.parse_profile_from_hcard
2017-10-20 22:31:56 +00:00
.. autofunction :: federation.utils.diaspora.retrieve_and_parse_content
2018-04-08 10:54:54 +00:00
.. autofunction :: federation.utils.diaspora.retrieve_and_parse_diaspora_webfinger
2016-10-02 10:08:37 +00:00
.. autofunction :: federation.utils.diaspora.retrieve_and_parse_profile
.. autofunction :: federation.utils.diaspora.retrieve_diaspora_hcard
.. autofunction :: federation.utils.diaspora.retrieve_diaspora_host_meta
2020-12-21 20:05:43 +00:00
Matrix
......
.. autofunction :: federation.utils.matrix.register_dendrite_user
2016-10-02 10:08:37 +00:00
Network
.......
.. autofunction :: federation.utils.network.fetch_document
.. autofunction :: federation.utils.network.send_document
2019-10-05 22:57:24 +00:00
Protocols
.........
.. autofunction :: federation.utils.protocols.identify_recipient_protocol
2016-10-02 10:08:37 +00:00
Exceptions
----------
Various custom exception classes might be returned.
.. autoexception :: federation.exceptions.EncryptedMessageError
.. autoexception :: federation.exceptions.NoSenderKeyFoundError
.. autoexception :: federation.exceptions.NoSuitableProtocolFoundError
2017-05-01 15:58:29 +00:00
.. autoexception :: federation.exceptions.SignatureVerificationError
