mirror of
https://github.com/versia-pub/docs.git
synced 2025-12-06 06:18:19 +01:00
Revise federation docs
This commit is contained in:
Jesse Wierzbinski
parent
b1089770c2
commit
802f44183b
|
|
@ -1,36 +1,40 @@
|
|||
# Federation
|
||||
|
||||
The Lysand protocol is only useful when it is federated. This section describes how federation works in Lysand.
|
||||
This section elucidates how federation operates within Lysand.
|
||||
|
||||
Federation in Lysand is based on the HTTP protocol. Servers communicate with each other by sending HTTP requests to one another.
|
||||
objects
|
||||
These requests are usually `POST` requests containing a JSON object in the body. This JSON object **MUST BE** a valid Lysand object.
|
||||
Lysand's federation is built upon the HTTP stack. Servers interact with each other by exchanging HTTP requests.
|
||||
|
||||
Servers that receive invalid Lysand objects **SHOULD** discard this object as invalid.
|
||||
These requests are predominantly `POST` requests that carry a JSON object in the body. This JSON object **MUST** conform to the Lysand object schema.
|
||||
|
||||
Servers that receive non-conforming Lysand objects **SHOULD** disregard these objects as invalid, and return a `400 Bad Request` response code (these could include debugging information in the response body).
|
||||
|
||||
> [!NOTE]
|
||||
> Values such as ``https://example.com/users/uuid` are example implementations and not a guide on how an implementation should format a URI. These must follow the rules outlined in [the base spec](../spec.md).
|
||||
>
|
||||
## User Actor Endpoints
|
||||
|
||||
A server is trying to get the profile of a user on another server. User discovery is done as specified in [User Discovery](/federation/user-discovery).
|
||||
When a server aims to retrieve the profile of a user on a differentserver, it follows the process outlined in [User Discovery](user-discovery).
|
||||
|
||||
Once the requesting server has discovered the endpoints of the server, it can send a `GET` request to the user's endpoint to discover the user's actor.
|
||||
Upon discovering the target server's endpoints, the requesting server can issue a `GET` request to the user's endpoint to retrieve the user's actor.
|
||||
|
||||
In the above example, to discover user information, the requesting server **MUST** send a `GET` request to the endpoint `https://example.com/users/uuid` with the headers `Accept: application/json`. To sign the request, the server may use either the [Server Actor](/federation/server-actor) or a requesting user's actor as appropriate.
|
||||
For instance, to fetch user information, the requesting server **MUST** send a `GET` request to the endpoint `https://example.com/users/uuid` with the required headers. The server can use either the [Server Actor](/federation/server-actor) or a requesting user's actor to sign the request, as appropriate depending on which actor the request is associated with.
|
||||
|
||||
The server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid User object.
|
||||
The server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid [Actor](../objects/actors) object.
|
||||
|
||||
> **Note**: Servers are not required to implement the functionality between certain endpoints such as dislikes or featured notes, but they **MUST** at least return an empty collection for these endpoints. Servers may also discard any objects they do not handle, but should return a success response code.
|
||||
> [!NOTE]
|
||||
> While servers are not obligated to implement functionality between certain endpoints such as dislikes or featured notes, they **MUST** at least return an empty collection for these endpoints. Servers may also disregard any objects they do not handle, but should return a success response code.
|
||||
|
||||
## User Inbox
|
||||
|
||||
Once the requesting server has discovered the endpoints of the server, it can send a `POST` request to the `inbox` endpoint to send an object to the user. This is similar to how objects are sent in ActivityPub.
|
||||
After the requesting server has discovered the target server's endpoints, it can issue a `POST` request to the `inbox` endpoint to transmit an object to the user. This process mirrors how objects are sent in ActivityPub.
|
||||
|
||||
Typically, the inbox can be located on the same URL as the user's actor, but this is not required. The server **MUST** specify the inbox URL in the actor object.
|
||||
Typically, the inbox can be found at the same URL as the user's actor, but this is not a requirement. The server **MUST** specify the inbox URL in the actor object.
|
||||
|
||||
Example inbox URL: `https://example.com/users/uuid/inbox`
|
||||
|
||||
The requesting server **MUST** send a `POST` request to the endpoint `https://example.com/users/uuid/inbox` with the headers `Content-Type: application/json` and `Accept: application/json`.
|
||||
|
||||
The body of the request **MUST** be a valid Lysand object.
|
||||
The body of the request **MUST** contain a valid Lysand object.
|
||||
|
||||
Example with cURL (without signature):
|
||||
```bash
|
||||
|
|
@ -44,11 +48,11 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
|
|||
}' https://example.com/users/uuid/inbox
|
||||
```
|
||||
|
||||
The server **MUST** respond with a `200 OK` response code if no error occurred.
|
||||
The server **MUST** respond with a `200 OK` response code if the operation was successful.
|
||||
|
||||
## User Outbox
|
||||
|
||||
Users in Lysand have an outbox, which is a list of objects that the user has posted. This is similar to the outbox in ActivityPub.
|
||||
In Lysand, users have an outbox, which is a list of objects that the user has posted. This is akin to the outbox in ActivityPub.
|
||||
|
||||
The server **MUST** specify the outbox URL in the actor object.
|
||||
|
||||
|
|
@ -56,7 +60,7 @@ Example outbox URL: `https://example.com/users/uuid/outbox`
|
|||
|
||||
The requesting server **MUST** send a `GET` request to the outbox endpoint (`https://example.com/users/uuid/outbox`) with the headers `Accept: application/json`.
|
||||
|
||||
The server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid Collection object containing Publications.
|
||||
The server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid [Collection](../structures/collection) object containing [Publications](../objects/publications).
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -90,7 +94,8 @@ These publications **MUST BE** ordered from newest to oldest, in descending orde
|
|||
|
||||
Users in Lysand have a list of followers, which is a list of users that follow the user. This is similar to the followers list in ActivityPub.
|
||||
|
||||
> **Note:** If you do not want to display this list publically, you can make the followers endpoint return an empty collection.
|
||||
> [!NOTE]
|
||||
> If you prefer not to display this list publicly, you can configure the followers endpoint to return an empty collection.
|
||||
|
||||
The server **MUST** specify the followers URL in the actor object.
|
||||
|
||||
|
|
@ -98,13 +103,14 @@ Example followers URL: `https://example.com/users/731bae4a-9279-4b11-bd8f-f30af7
|
|||
|
||||
The requesting server **MUST** send a `GET` request to the followers endpoint (`https://example.com/users/731bae4a-9279-4b11-bd8f-f30af7bec755/followers`) with the headers `Accept: application/json`.
|
||||
|
||||
The server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid Collection object containing Actors. This collection may be empty.
|
||||
The server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid [Collection](../structures/collection) object containing [Actors](../objects/actors). This collection may be empty.
|
||||
|
||||
## User Following
|
||||
|
||||
Users in Lysand have a list of following, which is a list of users that the user follows. This is similar to the following list in ActivityPub.
|
||||
Users in Lysand have a followlist, which is a list of users that the user follows. This is similar to the following list in ActivityPub.
|
||||
|
||||
> **Note:** If you do not want to display this list publically, you can make the following endpoint return an empty collection.
|
||||
> [!NOTE]
|
||||
> If you prefer not to display this list publicly, you can configure the following endpoint to return an empty collection.
|
||||
|
||||
The server **MUST** specify the following URL in the actor object.
|
||||
|
||||
|
|
@ -112,13 +118,13 @@ Example following URL: `https://example.com/users/731bae4a-9279-4b11-bd8f-f30af7
|
|||
|
||||
The requesting server **MUST** send a `GET` request to the following endpoint (`https://example.com/users/731bae4a-9279-4b11-bd8f-f30af7bec755/following`) with the headers `Accept: application/json`.
|
||||
|
||||
The server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid Collection object containing Actors. This collection may be empty.
|
||||
The server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid [Collection](../structures/collection) object containing [Actors](../objects/actors). This collection may be empty.
|
||||
|
||||
## User Featured Publications
|
||||
|
||||
Users in Lysand have a list of featured publications, which is a list of publications that the user has pinned or are important. This is similar to the featured publications list in ActivityPub.
|
||||
Users in Lysand have a list of featured publications, which is a list of publications that the user has pinned or deemed important. This is similar to the featured publications list in ActivityPub.
|
||||
|
||||
> **Note:** If you do not want to display this list publically, you can make the featured publications endpoint return an empty collection.
|
||||
> **Note:** If you prefer not to display this list publicly, you can configure the featured publications endpoint to return an empty collection.
|
||||
|
||||
The server **MUST** specify the featured publications URL in the actor object.
|
||||
|
||||
|
|
@ -126,13 +132,13 @@ Example featured publications URL: `https://example.com/users/731bae4a-9279-4b11
|
|||
|
||||
The requesting server **MUST** send a `GET` request to the featured publications endpoint (`https://example.com/users/731bae4a-9279-4b11-bd8f-f30af7bec755/featured`) with the headers `Accept: application/json`.
|
||||
|
||||
The server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid Collection object containing Publications. This collection may be empty.
|
||||
The server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid [Collection](../structures/collection) object containing [Publications](../objects/publications). This collection may be empty.
|
||||
|
||||
## User Likes
|
||||
|
||||
Users in Lysand have a list of likes, which is a list of posts that the user has liked. This is similar to the likes list in ActivityPub.
|
||||
|
||||
> **Note:** If you do not want to display this list publically, you can make the likes endpoint return an empty collection.
|
||||
> **Note:** If you prefer not to display this list publicly, you can configure the likes endpoint to return an empty collection.
|
||||
|
||||
The server **MUST** specify the likes URL in the actor object.
|
||||
|
||||
|
|
@ -140,14 +146,14 @@ Example likes URL: `https://example.com/users/731bae4a-9279-4b11-bd8f-f30af7bec7
|
|||
|
||||
The requesting server **MUST** send a `GET` request to the likes endpoint (`https://example.com/users/731bae4a-9279-4b11-bd8f-f30af7bec755/likes`) with the headers `Accept: application/json`.
|
||||
|
||||
The server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid Collection object containing Publications. This collection may be empty.
|
||||
The server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid [Collection](../structures/collection) object containing [Publications](../objects/publications). This collection may be empty.
|
||||
|
||||
|
||||
## User Dislikes
|
||||
|
||||
Users in Lysand have a list of dislikes, which is a list of posts that the user has disliked. This is similar to the dislikes list in ActivityPub.
|
||||
|
||||
> **Note:** If you do not want to display this list publically, you can make the dislikes endpoint return an empty collection.
|
||||
> **Note:** If you prefer not to display this list publicly, you can configure the dislikes endpoint to return an empty collection.
|
||||
|
||||
The server **MUST** specify the dislikes URL in the actor object.
|
||||
|
||||
|
|
@ -155,20 +161,21 @@ Example dislikes URL: `https://example.com/users/731bae4a-9279-4b11-bd8f-f30af7b
|
|||
|
||||
The requesting server **MUST** send a `GET` request to the dislikes endpoint (`https://example.com/users/731bae4a-9279-4b11-bd8f-f30af7bec755/dislikes`) with the headers `Accept: application/json`.
|
||||
|
||||
The server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid Collection object containing Publications. This collection may be empty.
|
||||
The server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid [Collection](../structures/collection) object containing [Publications](../objects/publications). This collection may be empty.
|
||||
|
||||
## Server Discovery
|
||||
|
||||
> **Note:** The terms "the server" and "the requesting server" are used in this section. "The server" refers to the server that is being discovered, and "the requesting server" refers to the server that is trying to discover the server.
|
||||
> [!NOTE]
|
||||
> The terms "the server" and "the requesting server" are used in this section. "The server" refers to the server that is being discovered, and "the requesting server" refers to the server that is attempting to discover the server.
|
||||
|
||||
To discover the metadata of a server, the requesting server **MUST** send a `GET` request to the endpoint `https://example.com/.well-known/lysand`.
|
||||
To retrieve the metadata of a server, the requesting server **MUST** send a `GET` request to the endpoint `https://example.com/.well-known/lysand`.
|
||||
|
||||
The requesting server **MUST** send the following headers with the request:
|
||||
```
|
||||
Accept: application/json
|
||||
```
|
||||
|
||||
The server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid `ServerMetadata` object.
|
||||
The server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid [ServerMetadata](../objects/server-metadata) object.
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -185,4 +192,4 @@ Example:
|
|||
"org.lysand:is_cat"
|
||||
]
|
||||
}
|
||||
```
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue