versia-pub/docs
2
0
Fork 0
mirror of https://github.com/versia-pub/docs.git synced 2025-12-06 06:18:19 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

Finish extensions pages

Browse source
This commit is contained in:
Jesse Wierzbinski 2023-11-25 17:48:19 -10:00
parent 37f3528f7f
commit 9c942fdc4a
No known key found for this signature in database
9 changed files with 629 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

85
docs/extensions.md Normal file
View file

@ -0,0 +1,85 @@
# Protocol Extensions
Lysand supports protocol extensions, which are extensions to the protocol that are not part of the core protocol. They are meant to be used to extend the protocol with new features. Extensions are namespaced.
Protocol extensions can be added to a object as follows:
```json5
{
// ...
"extensions": {
"com.organization.name:key": "value"
}
// ...
}
```
The `extensions` field is an object that contains a list of extensions. Each extension is a key-value pair, where the key is the extension name, and the value is the extension value.
The extension name **MUST** be a string that contains the reverse domain name of the organization that created the extension, followed by a colon, followed by the name of the extension. For example, `com.example:extension_name`.
The extension name **MUST** be unique across the organization namespace (I.E., it should be unique for each organization).
The extension value **MAY** be any valid JSON value. It is up to the servers to decide of they want to implement extensions or not.
For example, a server may implement an extension that allows users to geotag an object. The extension name may be `org.geotagger:geotag`, and the extension value may be a string that contains the geotag.
```json5
{
// ...
"extensions": {
"org.geotagger:geotag": "40.7128° N, 74.0060° W"
}
// ...
}
```
Lysand heavily recommends that extensions are documented and standardized, and that servers do not implement extensions that are not documented or standardized by their author.
## Adding New Object Types
Lysand supports adding new object types via extensions. This is useful for adding new types of objects to the protocol, such as polls or events.
Every new object type added **MUST** have `Extension` as its object type, and **MUST** have a `extension_type` field that contains the extension name of the object type.
The extension name of the object type is formatted as follows:
```
com.organization.name:extension/Type
```
For example, if a server wants to add a new object type called `Poll`, the extension name would be `com.example:poll/Poll`.
Custom types **MUST** start with a capital letter, **MUST** be alphanumeric values (with PascalCase used instead of spaces) and **MUST** be unique across all extensions.
Custom types **MUST** be unique in their organization namespace (I.E., it should be unique for each organization).
An example is given in the following object:
```json5
{
"type": "Extension",
"extension_type": "com.example:poll/Poll",
"id": "6f27bc77-58ee-4c9b-b804-8cc1c1182fa9",
"uri": "https://example.com/actions/6f27bc77-58ee-4c9b-b804-8cc1c1182fa9",
"author": "https://example.com/users/6e0204a2-746c-4972-8602-c4f37fc63bbe",
"created_at": "2021-01-01T00:00:00.000Z",
"question": "What is your favourite colour?",
"options": [
"Red",
"Blue",
"Green"
]
}
```
## Official Protocol Extensions
Lysand has a few official extensions that are part of the core protocol. These extensions are standardized and documented, and servers **SHOULD** implement them if they implement the core protocol (however they are not required to do so).
These include:
- [Custom Emojis](/extensions/custom-emojis)
- [Reactions](/extensions/reactions)
- [Polls](/extensions/polls)
- [Is Cat](/extensions/is-cat)
- [Server Endorsement](/extensions/server-endorsement)
- [Reports](/extensions/reports)

58
docs/extensions/custom-emojis.md Normal file
View file

@ -0,0 +1,58 @@
# Custom Emojis
Please see [Custom Emojis](/structures/custom-emoji) for more information about the Custom Emojis type. The extension is implemented as such:
```json5
{
// ...
"extensions": {
"org.lysand:custom_emojis": {
"emojis": [
{
"name": "happy_face",
"url": [
{
"content": "https://cdn.example.com/emojis/happy_face.webp",
"content_type": "image/webp"
}
]
},
// ...
]
}
}
// ...
}
```
That is, the extension name is `org.lysand:custom_emojis`, and the extension value is an object that contains a list of emojis.
## Applying Custom Emojis
Clients **MUST** apply custom emojis to the following fields of the following objects:
- `Publication.contents`
- `Publication.subject`
- `Actor.bio`
- `Actor.display_name`
A custom emoji is formatted inside a text string as follows:
```
:emoji_name:
```
For example, if a user wants to use the `happy_face` emoji, they would type:
```
:happy_face:
```
Clients **MUST** replace the `:emoji_name:` with the appropriate emoji. If the client does not support custom emojis, it **SHOULD** display the `:emoji_name:` as-is.
If the client supports Custom Emojis, but does not support the emoji that the user is trying to use (such as with an incompatible MIME type), it **SHOULD** display the `:emoji_name:` as-is.
When rendered as images, Custom Emojis **SHOULD** have proper alt text for accessibility. The alt text **SHOULD** be the alt text of the emoji, if it has one. If the emoji does not have an alt text, the alt text **SHOULD** be the name of the emoji.
Example in HTML:
```html
Hello, world! <img src="https://cdn.example.com/emojis/happy_face.webp" alt="A happy face emoji." title="A happy face emoji.">
```

5
docs/extensions/events.md Normal file
View file

@ -0,0 +1,5 @@
# Events
With the Events extension, users can create events. This is useful for creating gatherings, such as meetups or parties.
This extension is planned but not yet drafted.

21
docs/extensions/is-cat.md Normal file
View file

@ -0,0 +1,21 @@
# Is Cat
> **Note:** This is a **silly** extension that is not meant to be taken very seriously.
With the Is Cat extension, users can tell other users if they are a cat or not. This is akin to Misskey's "IsCat" feature.
An Actor can indicate whether they are a cat or not with the following field:
```json5
{
"type": "User",
// ...
"extensions": {
"org.lysand:is_cat": {
"cat": true
}
}
}
```
Clients **SHOULD** render some graphic to indicate if a user is a cat or not, such as cat ears on the user's avatar.

212
docs/extensions/polls.md Normal file
View file

@ -0,0 +1,212 @@
# Polls
With the Polls extension, users can create polls. This is useful for asking questions to users, such as "What is your favourite colour?".
Polls are added as a new field under Publication Extensions, called `poll`. This field is an object that contains the poll information.
```json5
{
// ...
"extensions": {
"org.lysand:polls": {
"poll": {
"options": [
[
{
"content": "Red",
"content_type": "text/plain"
}
],
[
{
"content": "Blue",
"content_type": "text/plain"
}
],
[
{
"content": "Green",
"content_type": "text/plain"
}
]
],
"votes": [
9,
5,
0
],
"multiple_choice": false,
"expires_at": "2021-01-04T00:00:00.000Z"
}
}
}
// ...
}
```
These fields are described below.
> **Note:** There is no `question` field, because it is assumed that the question will be put in the `contents` field of the Publication. Clients are expected to render polls next to the contents of the Publication itself.
## Fields
### Options
The `options` field on a Poll object is an array that contains a list of `ContentFormat` arrays. It is used to represent the options of the poll.
The `options` field is required on all Poll extension fields
The `options` field **MUST** contain at least 2 options, and does not have an upper limit for the number of options.
> **Note:** Servers should limit the number of options to a reasonable number, perferably in a configurable manner, such as 10. This is to prevent abuse of the protocol by sending a large number of options.
### Votes
The `votes` field on a Poll object is an array that contains a list of integers. It is used to represent the number of votes for each option.
The `votes` field is required on all Poll extension fields.
### Multiple Choice
The `multiple_choice` field on a Poll object is a boolean that represents whether or not the poll is multiple choice. It is used to determine if the user can select multiple options.
The `multiple_choice` field is not required on all Poll extension fields. If it is not provided, it is assumed that the poll is not multiple choice.
### Expires At
The `expires_at` field on a Poll object is a string that represents the date and time that the poll expires. It is used to determine when the poll ends, and when to stop accepting votes.
The `expires_at` field is required on all Poll extension fields.
Clients **SHOULD** display the time remaining until the poll expires.
### Integration With Custom Emojis
If you implement both the Polls and the Custom Emojis extensions, you can use the Custom Emojis extension to add emojis to poll options.
Example:
```json5
{
// ...
"extensions": {
"org.lysand:polls": {
"poll": {
"options": [
[
{
"content": ":red:",
"content_type": "text/plain"
}
],
[
{
"content": ":blue:",
"content_type": "text/plain"
}
],
[
{
"content": ":green:",
"content_type": "text/plain"
}
]
],
"votes": [
9,
5,
0
],
"multiple_choice": false,
"expires_at": "2021-01-04T00:00:00.000Z"
}
},
"org.lysand:custom_emojis": {
"emojis": [
{
"name": "red",
"url": [
{
"content": "https://cdn.example.com/emojis/red.webp",
"content_type": "image/webp"
}
]
},
{
"name": "blue",
"url": [
{
"content": "https://cdn.example.com/emojis/blue.webp",
"content_type": "image/webp"
}
]
},
{
"name": "green",
"url": [
{
"content": "https://cdn.example.com/emojis/green.webp",
"content_type": "image/webp"
}
]
}
]
}
}
// ...
}
```
When rendering the poll options, clients **SHOULD** display emojis as recommended by the [Custom Emojis](/extensions/custom-emojis) extension.
### Poll Results
Clients **SHOULD** display poll results as a percentage of votes. For example, if 10 users voted for the first option, and 5 users voted for the second option, the first option should be displayed as 66.67%, and the second option should be displayed as 33.33%.
Clients **SHOULD** display the number of votes for each option.
Clients **SHOULD** display the total number of votes.
### Sending Votes
Clients **SHOULD** allow users to vote on polls. When a user votes on a poll, the client **MUST** send a `POST` request to the poll's Publication URI with the following JSON object in the body:
```json5
{
"type": "Extension",
"extension_type": "org.lysand:polls/Vote",
"id": "6b1586cf-1f83-4d85-8d70-a5dc9f213b3e",
"uri": "https://example.com/actions/6b1586cf-1f83-4d85-8d70-a5dc9f213b3e",
"author": "https://example.com/users/6e0204a2-746c-4972-8602-c4f37fc63bbe",
"poll": "https://example.com/publications/f08a124e-fe90-439e-8be4-15a428a72a19",
"option": 0
}
```
In return, the server **MUST** respond with a `200 OK` response code, and a JSON object in the body. This JSON object **MUST** be a valid `VoteResult` object.
```json5
{
"type": "Extension",
"extension_type": "org.lysand:polls/VoteResult",
"id": "d6eb84ea-cd13-43f9-9c54-01244da8e5e3",
"uri": "https://example.com/actions/d6eb84ea-cd13-43f9-9c54-01244da8e5e3",
"poll": "https://example.com/publications/f08a124e-fe90-439e-8be4-15a428a72a19",
"votes": [
10,
5,
0
]
}
```
If the poll is closed, the server **MUST** respond with a `403 Forbidden` response code.
The total amount of votes can be calculated by summing the `votes` array.
This amount **MUST** include the user's vote, and **SHOULD** be displayed to the user after voting.
### Poll Events
When a poll ends, a user that has voted in it **SHOULD** be notified of the results by the server.
The server **MAY** send a `GET` request to the poll's Publication URI to update its internal database.

134
docs/extensions/reactions.md Normal file
View file

@ -0,0 +1,134 @@
# Reactions
With the Reactions extension, users can react to objects with emojis. This is similar to how Facebook and Discord work.
Here is an example of a reaction to a post using this extension:
```json5
{
"type": "Extension",
"extension_type": "org.lysand:reactions/Reaction",
"id": "6f27bc77-58ee-4c9b-b804-8cc1c1182fa9",
"uri": "https://example.com/actions/6f27bc77-58ee-4c9b-b804-8cc1c1182fa9",
"author": "https://example.com/users/6e0204a2-746c-4972-8602-c4f37fc63bbe",
"created_at": "2021-01-01T00:00:00.000Z",
"object": "https://example.com/publications/f08a124e-fe90-439e-8be4-15a428a72a19",
"content": "😀",
}
```
## Fields
### Type
As with all new objects added by extensions, the `type` field **MUST BE** `Extension`.
The `extension_type` field **MUST** be `org.lysand:reactions/Reaction`.
### Object
The `object` field on a Reaction object is a string that represents the URI of the object that the user is reacting to. The `object` field is required on all Reaction objects.
### Content
The `content` field on a Reaction object is a string that represents the emoji that the user is reacting with. The `content` field is required on all Reaction objects.
Clients **SHOULD** check if the value of `content` is an emoji: if it is not an emoji and instead is text, depending on which other extensions are implemented, it **MAY** be a Custom Emoji.
> Please see [Reactions With Custom Emojis](#reactions-with-custom-emojis) for more information about custom emoji reactions.
### Getting Reactions
Clients can get reactions to an object by sending a `GET` request to the reaction `Collection`'s URI.
The URI of the reaction `Collection` **MUST** be specified as follows, inside a `Publication`:
```json5
{
// ...
"extensions": {
"org.lysand:reactions": {
"reactions": "https://example.com/publications/f08a124e-fe90-439e-8be4-15a428a72a19/reactions"
}
}
}
```
The `reactions` field is a string that represents the URI of the reaction `Collection`.
The server **MUST** respond with a `Collection` object that contains a list of `Reaction` objects, as such:
```json5
{
"type": "Collection",
"first": "https://example.com/publications/f08a124e-fe90-439e-8be4-15a428a72a19/reactions?page=1",
"last": "https://example.com/publications/f08a124e-fe90-439e-8be4-15a428a72a19/reactions?page=1",
"total_items": 1,
"items": [
{
"type": "Extension",
"extension_type": "org.lysand:reactions/Reaction",
"id": "6f27bc77-58ee-4c9b-b804-8cc1c1182fa9",
"uri": "https://example.com/actions/6f27bc77-58ee-4c9b-b804-8cc1c1182fa9",
"author": "https://example.com/users/6e0204a2-746c-4972-8602-c4f37fc63bbe",
"created_at": "2021-01-01T00:00:00.000Z",
"object": "https://example.com/publications/f08a124e-fe90-439e-8be4-15a428a72a19",
"content": "😀",
}
]
}
```
### Public Reaction Federation
If a user reacts to a Publication, the user's server **MUST** federate the reaction to all its followers. This is to ensure that all users see the reaction.
Note, however, that this does not mean that the reaction will be displayed to users. If the Publication that was reacted to is not visible to a user, the reaction **MUST NOT** be displayed to the user, even if the user follows the user that reacted to the Publication.
### Private Reaction Federation
If a user reacts to a Publication, the user's server **MUST** federate the reaction to the author of the Publication. This is to ensure that the author of the Publication sees the reaction.
### Reactions With Custom Emojis
If you implement both the Reactions and the Custom Emojis extensions, you can use the Custom Emojis extension to react with custom emojis.
The Reaction object needs to be modified as such:
```json5
{
"type": "Extension",
"extension_type": "org.lysand:reactions/Reaction",
"id": "6f27bc77-58ee-4c9b-b804-8cc1c1182fa9",
"uri": "https://example.com/actions/6f27bc77-58ee-4c9b-b804-8cc1c1182fa9",
"author": "https://example.com/users/6e0204a2-746c-4972-8602-c4f37fc63bbe",
"created_at": "2021-01-01T00:00:00.000Z",
"object": "https://example.com/publications/f08a124e-fe90-439e-8be4-15a428a72a19",
"content": ":happy_face:",
"extensions": {
"org.lysand:custom_emojis": {
"emojis": [
{
"name": "happy_face",
"url": [
{
"content": "https://cdn.example.com/emojis/happy_face.webp",
"content_type": "image/webp"
}
]
},
// ...
]
}
}
}
```
The only addiction to the Reaction object is the `extensions` field, which contains the Custom Emojis extension.
When rendering the Reaction object, clients **MUST** replace the `:emoji_name:` with the appropriate emoji. If the client does not support custom emojis, it **MUST** display the `:emoji_name:` as-is.
When rendered as images, Custom Emoji Reactions **SHOULD** have proper alt text for accessibility. The alt text **SHOULD** be the alt text of the emoji, if it has one. If the emoji does not have an alt text, the alt text **SHOULD** be the name of the emoji.
Example in HTML:
```html
<img src="https://cdn.example.com/emojis/happy_face.webp" alt="A happy face emoji." title="A happy face emoji.">
```

47
docs/extensions/reports.md Normal file
View file

@ -0,0 +1,47 @@
# Reports
The Reports extension allows users to report objects to their server. This is useful for reporting content that violates the server's rules to admin. (also called "flagging")
If the reporter and reportee are on the same server, there is no need for federation and reporting can happen directly. If the reporter and reportee are on different servers, the report **MUST** be federated to the reportee's server.
## Report Object
The report object is an object that contains information about the report. It is formatted as follows:
```json5
{
"type": "Extension",
"extension_type": "org.lysand:reports/Report",
"author": "https://example.com/users/6f3001a1-641b-4763-a9c4-a089852eec84",
"id": "6f3001a1-641b-4763-a9c4-a089852eec84",
"uri": "https://example.com/actions/f7bbf7fc-88d2-47dd-b241-5d1f770a10f0",
"objects": [
"https://test.com/publications/46f936a3-9a1e-4b02-8cde-0902a89769fa",
"https://test.com/publications/213d7c56-fb9b-4646-a4d2-7d70aa7d106a"
],
"reason": "spam",
"comment": "This is spam."
}
```
Report events **MUST** be sent to the server actor's inbox.
## Fields
### Objects
The `objects` field is an array that contains a list of the URIs of the objects that are being reported. This field is required on all Report objects.
If `objects` contains Actors, then these Actors **MUST** be treated as the reported actors.
If `objects` contains Publications, then these Publications **MUST** be treated as the reported objects.
`objects` can contain any URI to any kind of objects, however typically only Actors or Publications should be reportable
### Reason
The `reason` field is a string that represents the reason for the report. This field is required on all Report objects. This is meant to be a short summary of the report, such as `"spam"`, `"hate speech"`, `"tos violation"` or such.
### Comment
The `comment` field is a string that represents the comment of the report. This field is not required on a Report object. This is meant to be a longer description of the report, such as `"This user has been spamming my inbox with advertisements."`.

60
docs/extensions/server-endorsement.md
View file

@ -0,0 +1,60 @@
# Server Endorsement
The Server Endorsement extension allows servers to endorse other servers. This is useful as an alternative to open-air federation, where servers can endorse other servers that they trust. Only endorsed servers and the servers endorsed by those (up to a configurable depth) will be federated with.
## Endorsement Object
The endorsement object is an object that contains information about the endorsement. It is formatted as follows:
```json5
{
"type": "Extension",
"extension_type": "org.lysand:server_endorsement/Endorsement",
"author": "https://example.com/actor", // Should be the server actor
"id": "ed480922-b095-4f09-9da5-c995be8f5960",
"uri": "https://example.com/actions/ed480922-b095-4f09-9da5-c995be8f5960",
"server": "https://example.com",
}
```
The `server` field is a string that represents the URI of the server that is being endorsed. This URI **MUST** be the URI of the server's root endpoint. For example, `https://example.com`.
This URI **MUST** be HTTPS and **MUST NOT** be an IP address.
The `server` field is required on all Endorsement objects.
Endorsement objects **MUST** be sent to the server actor's inbox, whenever a new endorsement is made by the server admins.
### Author
The `author` field **MUST** be the server actor. This field is required so that servers can cryptographically sign the endorsement with the server actor's `public_key`.
## Endorsement Collection
The URI to the endorsement collection may be specified inside the server's metadata, inside `extensions`:
```json5
{
// ...
"extensions": {
"org.lysand:server_endorsement": {
"endorsements": "https://example.com/endorsements"
}
}
// ...
}
```
This should return a `Collection` object that contains a list of `Endorsement` objects.
## Behaviour Of Endorsements
When a server receives an endorsement, it **MUST** verify the signature of the endorsement. If the signature is invalid, the server **MUST** discard the endorsement. This goes the same for fetching the endorsement collection.
It is up to the server to decide what it does with the endorsement: Endorsements are designed to apply as a flexible whitelist for servers, with the admins choosing a couple of trusted servers when setting up for the first time and then adding more as they go.
Servers **SHOULD** show the endorsements that they have received to their admins, and allow them to accept or reject the endorsement. Ultimately, it is up to the admins to decide what to do with the endorsement.
Endorsements should be treated as a guarantee of trust: If a server endorses another server, it is saying that it trusts that server. Servers should not endorse servers that they do not trust.
Finally, servers **can** check the endorsed servers of the servers that they have endorsed, up to a configurable depth. This is to create a chain of trust, where servers can endorse servers that they trust, and servers that they trust can endorse servers that they trust, and so on.

8
docs/objects/server-metadata.md
View file

@ -119,4 +119,10 @@ Lysand heavily recommends that servers provide both the original format and a mo
Clients should display the most modern format that they support, such as WebP, AVIF, JXL, or HEIF. If the client does not support any modern formats, it should display the original format.
> **Note:** Servers may find it useful to use a CDN that can automatically convert images to modern formats, such as Cloudflare. This will offload image processing from the server, and improve performance for clients.
> **Note:** Servers may find it useful to use a CDN that can automatically convert images to modern formats, such as Cloudflare. This will offload image processing from the server, and improve performance for clients.
### Supported Extensions
The `supported_extensions` field on a Server Metadata object is an array that contains a list of extension names that the server supports.
The `supported_extensions` field is not required on all Server Metadata objects. If it is not provided, it is assumed that the server does not support any extensions.