Federation
This page describes how instances in a Versia network exchange data.
Federation is built on the HyperText Transfer Protocol (HTTP) and the JavaScript Object Notation (JSON) data format. Instances communicate with each other by sending and receiving JSON payloads over HTTP.
Related Pages
Inboxes
The closest ActivityPub equivalent is the shared inbox. Versia has no inbox for each user, and sends entities without wrapping them in activities. See Other Protocols.
Every Instance has one HTTP endpoint called an inbox (/.versia/v0.7/inbox), which receives messages for all of its users. Messages are sent to it as JSON payloads over HTTP POST requests. See the Inbox Endpoint.
Let’s consider the following example:
Alice, on the instance alice.example, sends a message to Bob on the instance bob.example.
To perform this action, Alice’s instance sends a POST request to Bob’s instance’s inbox endpoint. This request contains the entity that Alice wants to send to Bob, such as a Note, with the appropriate metadata to ensure the message is valid.
Bob’s instance receives the message and processes it according to the rules defined in the Validation document.
Delivery
A sender MUST deliver each entity to the instances hosting the users below. It MAY also deliver it to other instances that may fetch it, and MAY skip instances it refuses to federate with.
| Entity | Delivered to |
|---|---|
| User, after a change | The user’s subscribers |
| Subscribe, Unsubscribe | The target |
| SubscribeAccept, SubscribeReject | The subscriber |
Changing an entity or sending a Delete for it goes to the same audience, as it stands at that moment.
Extensions state the delivery rules for their own entities on their own pages.
Access
Requests identify an instance, not a user, so access is decided per instance. An instance MUST NOT serve an entity to an instance that may not fetch it, and MUST answer such a request with a 404 Not Found status code, so as not to reveal that the entity exists.
| Entity | May be fetched by |
|---|---|
| User | Any instance |
An instance that fetches an entity MUST apply the same limits to its own users.
Collections list only the items the requesting instance may fetch. Transient entities cannot be fetched at all. Extensions state the access rules for their own entities on their own pages. An extension MAY add to who can fetch an entity, and MUST state it on its page. It MUST NOT take anyone away.
Ordering
Delivery order is not guaranteed. An instance can receive a Like before the Note it refers to.
A receiver SHOULD fetch referenced entities it does not have. If it cannot, it MAY retry later or drop the entity.
An entity with nothing to apply to, such as a SubscribeAccept with no pending request, MUST be ignored, and is not an error.