versia-pub/docs
2
0
Fork 0
mirror of https://github.com/versia-pub/docs.git synced 2026-03-13 02:49:16 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

refactor: 📝 Update all extension to remove now-useless fields

Browse source
This commit is contained in:
Jesse Wierzbinski 2025-05-05 14:08:20 +02:00
parent 51c53824ad
commit d886b83e62
No known key found for this signature in database
27 changed files with 166 additions and 410 deletions
Download patch file Download diff file Expand all files Collapse all files

6
app/extensions/custom-emojis/page.mdx
View file

@ -15,7 +15,11 @@ The Custom Emojis extension adds support for adding personalized emojis to feder
<Property name="name" type="string" required={true}>
Emoji name, surrounded by identification characters (for example, colons: `:happy_face:`).
Name must match the regex `^[a-zA-Z0-9_-]+$`.
The following characters are allowed:
- `a-z`
- `A-Z`
- `0-9`
- `_`, `-`
Identification characters must not match the name regex (must not be alphanumeric/underscore/hyphen). There may only be two identification characters, one at the beginning and one at the end.
</Property>

7
app/extensions/delegation/page.mdx
View file

@ -26,13 +26,12 @@ This is useful as a way to centralize all of a user's many "alt accounts" into a
## Extension Definition
The Delegation extension uses an ID of `pub.versia:delegation`.
If the extension is present, exactly **one** of the fields **MUST** be specified:
<Row>
<Col>
<Properties name="Delegation">
The Delegation extension uses an ID of `pub.versia:delegation`.
If the extension is present, exactly **one** of the fields **MUST** be specified:
<Property name="delegator" type="Reference">
If this user performs actions on behalf on another user, **MUST** have a reference to that user.
</Property>

58
app/extensions/groups/page.mdx
View file

@ -36,12 +36,6 @@ Refer to [Note](/entities/note#entity-definition)'s `group` property for how not
It is similar to a [User](/entities/user)'s `manually_approves_followers` field.
</Note>
</Property>
<Property name="members" type="URI" required={true} typeLink="/types#uri">
URI of the group's members list. [URI Collection](/structures/collection#uri-collection) of [Users](/entities/user).
</Property>
<Property name="notes" type="URI" required={false} typeLink="/types#uri">
URI of the group's associated notes. [URI Collection](/structures/collection#uri-collection) of [Notes](/entities/note).
</Property>
</Properties>
</Col>
@ -68,6 +62,15 @@ Refer to [Note](/entities/note#entity-definition)'s `group` property for how not
</Col>
</Row>
### Collections
The following [Collections](/structures/collection) are available:
- `members`: [URI Collection](/structures/collection#uri-collection) of [Users](/entities/user) that are members of the group.
- `notes`: [URI Collection](/structures/collection#uri-collection) of [Notes](/entities/note) that are associated with the group.
These can be fetched using the [Federation API](/api/endpoints#entity-collections)
## Subscribing to Groups
[Users](/entities/user) may "subscribe" to a Group in order to receive all [Notes](/entities/note) posted to it. The mechanism by which federation is handled is described at [the end of this document](#federation).
@ -80,15 +83,16 @@ If the group accepts the subscription, the user will receive all notes posted to
Indicates that a [User](/entities/user) wishes to subscribe to a group.
<Warning>
This entity is a [**Transient Entity**](/entities#transient-entities).
</Warning>
<Row>
<Col>
<Properties name="GroupSubscribe">
<Property name="type" type="string" required={true}>
Must be `pub.versia:groups/Subscribe`.
</Property>
<Property name="uri" type="null" required={false}>
This is a [**Transient Entity**](/entities#transient-entities) and does not have a URI.
</Property>
<Property name="subscriber" type="URI" required={true} typeLink="/types#uri">
URI of the [User](/entities/user) subscribing to the group.
</Property>
@ -117,15 +121,16 @@ Indicates that a [User](/entities/user) wishes to subscribe to a group.
Indicates that a [User](/entities/user) wishes to unsubscribe from a group.
<Warning>
This entity is a [**Transient Entity**](/entities#transient-entities).
</Warning>
<Row>
<Col>
<Properties name="GroupUnsubscribe">
<Property name="type" type="string" required={true}>
Must be `pub.versia:groups/Unsubscribe`.
</Property>
<Property name="uri" type="null" required={false}>
This is a [**Transient Entity**](/entities#transient-entities) and does not have a URI.
</Property>
<Property name="subscriber" type="URI" required={true} typeLink="/types#uri">
URI of the [User](/entities/user) unsubscribing from the group.
</Property>
@ -152,7 +157,11 @@ Indicates that a [User](/entities/user) wishes to unsubscribe from a group.
### GroupSubscribeAccept
Indicates that a [Group](#entity-definition) has accepted a [User](/entities/user)'s subscription request. Should be signed by the instance hosting the group.
Indicates that a [Group](#entity-definition) has accepted a [User](/entities/user)'s subscription request. Should be sent by the instance hosting the group.
<Warning>
This entity is a [**Transient Entity**](/entities#transient-entities).
</Warning>
<Row>
<Col>
@ -160,9 +169,6 @@ Indicates that a [Group](#entity-definition) has accepted a [User](/entities/use
<Property name="type" type="string" required={true}>
Must be `pub.versia:groups/SubscribeAccept`.
</Property>
<Property name="uri" type="null" required={false}>
This is a [**Transient Entity**](/entities#transient-entities) and does not have a URI.
</Property>
<Property name="subscriber" type="URI" required={true} typeLink="/types#uri">
URI of the [User](/entities/user) subscribing to the group.
</Property>
@ -189,7 +195,11 @@ Indicates that a [Group](#entity-definition) has accepted a [User](/entities/use
### GroupSubscribeReject
Indicates that a [Group](#entity-definition) has rejected a [User](/entities/user)'s subscription request. Should be signed by the instance hosting the group.
Indicates that a [Group](#entity-definition) has rejected a [User](/entities/user)'s subscription request. Should be sent by the instance hosting the group.
<Warning>
This entity is a [**Transient Entity**](/entities#transient-entities).
</Warning>
<Row>
<Col>
@ -197,9 +207,6 @@ Indicates that a [Group](#entity-definition) has rejected a [User](/entities/use
<Property name="type" type="string" required={true}>
Must be `pub.versia:groups/SubscribeReject`.
</Property>
<Property name="uri" type="null" required={false}>
This is a [**Transient Entity**](/entities#transient-entities) and does not have a URI.
</Property>
<Property name="subscriber" type="URI" required={true} typeLink="/types#uri">
URI of the [User](/entities/user) subscribing to the group.
</Property>
@ -228,13 +235,17 @@ Indicates that a [Group](#entity-definition) has rejected a [User](/entities/use
Group federation represents a particularly challenging problem, as it requires a way to make sure every single [Note](/entities/note) posted to it is delivered to every single member of the group.
All [Notes](/entities/note) posted to a group (using the `group` field) must be sent to its instance's [shared inbox](/federation#inboxes). Groups do not have an inbox of their own.
All [Notes](/entities/note) posted to a group (using the `group` field) must be sent to its instance's [inbox](/api/endpoints#inbox).
Once this is done, the group's instance must then federate this [Note](/entities/note) to every member of the group. However, this cannot be done the "normal way", as the group's instance does not have the private key to [sign](/signatures) the [Note](/entities/note).
### GroupFederate
The `GroupFederate` entity allows a group to federate a note to all of its members, without needing to sign the note itself. It contains a URI to the note being federated, which must be fetched by the receiving instances. This entity is signed by the group's instance.
The `GroupFederate` entity allows a group to federate a note to all of its members, without needing to sign the note itself. It contains a URI to the note being federated, which must be fetched by the receiving instances. This entity is sent by the group's instance.
<Warning>
This entity is a [**Transient Entity**](/entities#transient-entities).
</Warning>
<Row>
<Col>
@ -242,9 +253,6 @@ The `GroupFederate` entity allows a group to federate a note to all of its membe
<Property name="type" type="string" required={true}>
Must be `pub.versia:groups/Federate`.
</Property>
<Property name="uri" type="null" required={false}>
This is a [**Transient Entity**](/entities#transient-entities) and does not have a URI.
</Property>
<Property name="note" type="URI" required={true} typeLink="/types#uri">
URI of the note to federate.
</Property>

63
app/extensions/instance-messaging/page.mdx
View file

@ -23,60 +23,21 @@ For example, let's consider the following scenario:
In this scenario, `jane.org` has no way of knowing what went wrong, as `joe.social` does not provide any feedback.
## Instance Metadata Extensions
This extension adds the following metadata to instances:
## Sending Messages
<Row>
<Col>
<Properties name="InstanceMessagingExtension">
<Property name="endpoint" type="string" required={true}>
The endpoint to send federation debug messages to.
To send a federation debug message, instances **should** make a `POST` request to the `/.versia/v0.6/messaging` endpoint with a simple text body containing a helpful message.
### Sending Messages
No signatures are required (either on the request or response), and no response body is expected.
To send a federation debug message, instances **should** make a `POST` request to the appropriate endpoint with a simple text body containing a helpful message.
```text {{ "title": "Helpful Message" }}
Validation failed for https://jane.org/users/nkGEd8eI98.
Reasons:
- `username` must be alphanumeric. Found invalid character `@`.
```
```text {{ "title": "Helpful Message" }}
Validation failed for https://jane.org/users/nkGEd8eI98.
Reasons:
- `username` must be alphanumeric. Found invalid character `@`.
```
Do not send useless messages, such as:
Do not send useless messages, such as:
```text {{ "title": "Unhelpful Message" }}
Federation failed.
```
</Property>
</Properties>
</Col>
<Col sticky>
```jsonc {{ "title": "Example Instance Metadata" }}
{
"type": "InstanceMetadata",
"name": "Jane.org",
"software": {
"name": "Versia Server",
"version": "0.7.0"
},
"compatibility": {
"versions": [
"0.5.0"
],
"extensions": [
"pub.versia:reactions",
"pub.versia:polls",
"pub.versia:reports",
"pub.versia:instance_messaging"
]
},
"host": "jane.org",
"created_at": "2021-07-01T00:00:00Z"
}
```
</Col>
</Row>
```text {{ "title": "Unhelpful Message" }}
Federation failed.
```

2
app/extensions/interaction-controls/page.mdx
View file

@ -99,7 +99,7 @@ Extensions **may** choose to register their own interaction types (such as `pub.
### Handling Permission Errors
Implementations that find a user attempting to create an interaction they are not allowed to **MUST** return a `403 Forbidden` HTTP status code when processing the Note during federation. The Note **must** also be discarded.
Implementations that find a user attempting to create an interaction they are not allowed to **MAY** return a `403 Forbidden` HTTP status code when processing the Note during federation, or use the [Instance Messaging](/extensions/instance-messaging) extension. The Note **must** be discarded.
It is important for implementations to backfill any related [Collections](/structures/collection)/[URI Collections](/structures/collection#uri-collection) (e.g. user followers) in order to not incorrectly reject Notes based off of outdated data.

32
app/extensions/likes/page.mdx
View file

@ -90,39 +90,15 @@ To undo a like or dislike, a [Delete](/entities/delete) entity should be used. T
The Likes extension adds the following collections to the [User](/entities/user) entity:
- `likes`: A [URI Collection](/structures/collection#uri-collection) of all the notes the user has liked.
- `dislikes`: A [URI Collection](/structures/collection#uri-collection) of all the notes the user has disliked.
```jsonc
{
"type": "User",
...
"collections": {
...
"pub.versia:likes/Likes": "https://example.com/users/6e0204a2-746c-4972-8602-c4f37fc63bbe/likes",
"pub.versia:likes/Dislikes": "https://example.com/users/6e0204a2-746c-4972-8602-c4f37fc63bbe/dislikes"
}
}
```
- `pub.versia:likes/Likes`: [URI Collection](/structures/collection#uri-collection) of all the notes the user has liked.
- `pub.versia:likes/Dislikes`: [URI Collection](/structures/collection#uri-collection) of all the notes the user has disliked.
## Note Collections
The Likes extension adds the following collections to the [Note](/entities/note) entity:
- `likes`: A [URI Collection](/structures/collection#uri-collection) of all the likes the note has received.
- `dislikes`: A [URI Collection](/structures/collection#uri-collection) of all the dislikes the note has received.
```jsonc
{
"type": "Note",
...
"collections": {
...
"pub.versia:likes/Likes": "https://example.com/notes/fmKZ763jzIU8/likes",
"pub.versia:likes/Dislikes": "https://example.com/notes/fmKZ763jzIU8/dislikes"
}
}
```
- `pub.versia:likes/Likes`: [URI Collection](/structures/collection#uri-collection) of all the likes the note has received.
- `pub.versia:likes/Dislikes`: [URI Collection](/structures/collection#uri-collection) of all the dislikes the note has received.
## Interaction Types

7
app/extensions/migration/page.mdx
View file

@ -30,12 +30,13 @@ Migration happens in three steps:
## Entity Definition
<Warning>
This entity is a [**Transient Entity**](/entities#transient-entities).
</Warning>
<Row>
<Col>
<Properties name="Migration">
<Property name="uri" type="null" required={false}>
This is a [**Transient Entity**](/entities#transient-entities) and does not have a URI.
</Property>
<Property name="type" type="string" required={true}>
Must be `pub.versia:migration/Migration`.
</Property>

4
app/extensions/page.mdx
View file

@ -7,7 +7,7 @@ export const metadata = {
Versia provides a set of core entities and structures to build a barebones social network. However, it is not possible nor desirable to cover every use case. This is where extensions come in, allowing parts of the system to be extended or replaced with custom functionality. {{ className: 'lead' }}
By design, extensions can be mitchmatched in any combination, without requiring any changes to the core system. This allows for a high degree of customization and flexibility. Implementations that do not support a particular extension can simply ignore it without any issues.
By design, extensions can be implemented in any combination, without requiring any changes to the core system. This allows for a high degree of customization and flexibility. Implementations that do not support a particular extension can simply ignore it without any issues.
Extensions **should** be standardized and publicly documented.
@ -90,7 +90,7 @@ Extensions can be found in two places: an [Entity](/entities#entity-definition)'
<Property name="other">
Other properties of the custom entity. These are specific to the extension, and should be documented by the extension author.
Note that `id`, `uri` and `created_at` are still required for custom entities, unless the extension author specifies otherwise.
Note that `id` and `created_at` are still required for custom entities, unless the extension author specifies otherwise.
</Property>
</Properties>
</Col>

13
app/extensions/reactions/page.mdx
View file

@ -53,18 +53,7 @@ User reactions are (like every other entity) federated to all followers, and can
The Likes extension adds the following collections to the [Note](/entities/note) entity:
- `reactions`: A [URI Collection](/structures/collection#uri-collection) of all the reactions to the note.
```jsonc
{
"type": "Note",
...
"collections": {
...
"pub.versia:reactions/Reactions": "https://example.com/publications/f08a124e-fe90-439e-8be4-15a428a72a19/reactions"
}
}
```
- `pub.versia:reactions/Reactions`: [URI Collection](/structures/collection#uri-collection) of all the reactions to the note.
## Interaction Types

7
app/extensions/reports/page.mdx
View file

@ -11,12 +11,13 @@ When an instance receives a report, it *should* be reviewed by a moderator or ad
## Entity Definition
<Warning>
This entity is a [**Transient Entity**](/entities#transient-entities).
</Warning>
<Row>
<Col>
<Properties name="Report">
<Property name="uri" type="null" required={false}>
This is a [**Transient Entity**](/entities#transient-entities) and does not have a URI.
</Property>
<Property name="type" type="string" required={true}>
Must be `pub.versia:reports/Report`.
</Property>

13
app/extensions/share/page.mdx
View file

@ -49,18 +49,7 @@ When a user shares a note, the note's original author **must** receive the entit
The Share extension adds the following collections to the [Note](/entities/note) entity:
- `shares`: A [URI Collection](/structures/collection#uri-collection) of all the shares of the note.
```jsonc
{
"type": "Note",
...
"collections": {
...
"pub.versia:share/Shares": "https://example.com/notes/fmKZ763jzIU8/shares"
}
}
```
- `pub.versia:share/Shares`: [URI Collection](/structures/collection#uri-collection) of all the shares of the note.
## Interaction Types

57
app/extensions/websockets/page.mdx
View file

@ -1,57 +0,0 @@
export const metadata = {
title: 'WebSocket Extension',
description:
'The WebSocket extension adds support for real-time communication between instances.',
}
# WebSockets Extension
<Note>
This document is **provided for informative purposes** and should not be used in a production environment. It is subject to change.
If internal testing proves unsuccessful at solving the problems with the HTTP delivery method, this document may be abandoned.
</Note>
Typically, communication between Versia instances is done via HTTP. However, HTTP suffers from some limitations, such as high latency and heavy overhead for small messages, making it less suitable for exchanging large amounts of entities at acceptable speeds. {{ className: 'lead' }}
This extension aims to address these limitations by adding support for the exchange of entities using WebSockets.
## Message Format
Messages sent over the WebSocket connection are JSON objects.
<Row>
<Col>
<Properties name="WebSocketMessage">
<Property name="signature" type="string" required={true}>
Same as the `Versia-Signature` header in HTTP requests.
</Property>
<Property name="signed_at" type="string" required={true}>
Same as the `Versia-Signed-At` header in HTTP requests.
</Property>
<Property name="signed_by" type="URI" required={true}>
Same as the `Versia-Signed-By` header in HTTP requests.
</Property>
<Property name="entity" type="Entity" required={true} typeLink="/entities">
Same as the request body in HTTP requests. Must be a string (stringified JSON), not JSON.
</Property>
</Properties>
</Col>
<Col sticky>
```jsonc {{ 'title': 'Example Message' }}
{
"signature": "/CjB2L9bcvRg+uP19B4/rqy7Ji9/cqMFPlL3GVCIndnQjYyOpBzJEAl9weDnXm7Jrqa3y6sBC+EYWKThO2r9Bw==",
"signed_at": "1729241807",
"signed_by": "https://bongo.social/users/63a00ab3-39b1-49eb-b88e-ed65d2361f3e",
"entity": "{\"id\":\"9a8928b6-2526-4979-aab1-ef2f88cd5700\",\"type\":\"Delete\",\"created_at\":\"2022-01-01T12:00:00Z\",\"author\":\"https://bongo.social/users/63a00ab3-39b1-49eb-b88e-ed65d2361f3e\",\"deleted\":\"https://bongo.social/notes/54059ce2-9332-46fa-bf6a-598b5493b81b\"}"
}
```
</Col>
</Row>
## Connection Establishment
...