mirror of
https://github.com/versia-pub/docs.git
synced 2025-12-06 06:18:19 +01:00
feat: 📝 Add federation example docs
This commit is contained in:
Jesse Wierzbinski
parent
90e360d713
commit
f3a8792693
174
app/federation/example/page.mdx
Normal file
174
app/federation/example/page.mdx
Normal file
|
|
@ -0,0 +1,174 @@
|
|||
export const metadata = {
|
||||
title: 'Federation Example',
|
||||
description:
|
||||
'A description of how a typical federation flow might look like',
|
||||
}
|
||||
|
||||
# Example
|
||||
|
||||
This page describes a typical federation flow between two servers, `a.social` and `b.social`, in several different contexts. {{ className: 'lead' }}
|
||||
|
||||
<Note>
|
||||
All examples, domains, names and timestamps are **fictional** and are used **for illustrative purposes only**.
|
||||
|
||||
Some details have been slightly simplified for clarity.
|
||||
</Note>
|
||||
|
||||
## Sending a Note
|
||||
|
||||
`@alice` on `a.social` creates a note with the following content:
|
||||
|
||||
```markdown
|
||||
Hello, @joe@b.social! How are you doing today?
|
||||
```
|
||||
|
||||
`@alice` has mentioned `@joe@b.social` in the note.
|
||||
|
||||
### Resolving the Mention
|
||||
|
||||
`a.social` resolves the mention by querying `b.social` for the user `joe` using WebFinger.
|
||||
|
||||
```bash {{ title: "cURL example" }}
|
||||
curl https://b.social/.well-known/webfinger?resource=acct:joe@b.social -H "Accept: application/json"
|
||||
```
|
||||
|
||||
`b.social` responds with the following JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"subject": "acct:joe@b.social",
|
||||
"links": [
|
||||
{ // [!code focus:5]
|
||||
"rel": "self",
|
||||
"type": "application/json",
|
||||
"href": "https://b.social/users/joe"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
In a real Versia implementation, usernames would **not** be included in user profile's URL, as they can be changed. Instead, the `id` could be used.
|
||||
|
||||
This is done for simplicity in this example.
|
||||
</Note>
|
||||
|
||||
### Fetching the User
|
||||
|
||||
`a.social` fetches the user profile of `joe` from `b.social` using the URL provided in the WebFinger response.
|
||||
|
||||
```bash
|
||||
curl https://b.social/users/joe \
|
||||
-H "Accept: application/json" \
|
||||
-H "User-Agent: CoolServer/1.0 (https://coolserver.com)" \
|
||||
# The request is signed by a.social's instance private key
|
||||
-H "Versia-Signature: /CjB2L9bcvRg+uP19B4/rqy7Ji9/cqMFPlL3GVCIndnQjYyOpBzJEAl9weDnXm7Jrqa3y6sBC+EYWKThO2r9Bw==" \
|
||||
-H "Versia-Signed-By: https://a.social/users/alice" \
|
||||
-H "Versia-Signed-At: 1729241687"
|
||||
```
|
||||
|
||||
`b.social` responds with the following JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "bde22zi3ca8762", // [!code focus:10]
|
||||
"type": "User",
|
||||
"uri": "https://b.social/users/joe",
|
||||
"created_at": "2024-10-13T18:48:19Z",
|
||||
"avatar": {
|
||||
"image/webp": {
|
||||
"content": "https://cdn.b.social/avatars/joe.webp",
|
||||
"remote": true
|
||||
}
|
||||
},
|
||||
"collections": {
|
||||
"featured": "https://b.social/users/joe/featured",
|
||||
"followers": "https://b.social/users/joe/followers",
|
||||
"following": "https://b.social/users/joe/following",
|
||||
"outbox": "https://b.social/users/joe/outbox"
|
||||
}, // [!code focus:9]
|
||||
"display_name": "Joe Swanson (Winter Arc :gigachad:)",
|
||||
"inbox": "https://b.social/inbox",
|
||||
"public_key": {
|
||||
"actor": "https://b.social/users/joe",
|
||||
"algorithm": "ed25519",
|
||||
"key": "MCowBQYDK2VwAyEAOSCcfsde0Ya3vf/P6lzgK0pA8qCISqneaze3omLlQCQ="
|
||||
},
|
||||
"username": "joe",
|
||||
"extensions": {
|
||||
"pub.versia:custom_emojis": {
|
||||
"emojis": [
|
||||
{
|
||||
"name": ":gigachad:",
|
||||
"content": {
|
||||
"image/png": {
|
||||
"content": "https://cdn.b.social/emojis/gigachad.png",
|
||||
"remote": true
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
`a.social` now has the user profile of `joe` and can display the note with the correct user information.
|
||||
|
||||
### Serializing the Note
|
||||
|
||||
Finally, `a.social` serializes the note to send it to `joe`.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "782addd9-c051-4eea-8ba4-23d561d0c5bb", // [!code focus:6]
|
||||
"type": "Note",
|
||||
"uri": "https://a.social/notes/782addd9-c051-4eea-8ba4-23d561d0c5bb",
|
||||
"created_at": "2024-12-01T12:19:06Z",
|
||||
"author": "https://a.social/users/alice",
|
||||
"category": "microblog",
|
||||
"collections": {
|
||||
"replies": "https://a.social/notes/782addd9-c051-4eea-8ba4-23d561d0c5bb/replies",
|
||||
"quotes": "https://a.social/notes/782addd9-c051-4eea-8ba4-23d561d0c5bb/quotes"
|
||||
}, // [!code focus:11]
|
||||
"content": {
|
||||
"text/html": {
|
||||
"content": "Hello, <a class=\"u-url mention\" href=\"https://b.social/users/joe\">@joe@b.social</a>! How are you doing today?",
|
||||
"remote": false,
|
||||
},
|
||||
"text/plain": {
|
||||
"content": "Hello, @joe@b.social! How are you doing today?",
|
||||
"remote": false,
|
||||
}
|
||||
},
|
||||
"group": "public",
|
||||
"mentions": [ // [!code focus:3]
|
||||
"https://b.social/users/joe"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
It is now time for `a.social` to send the note to `joe`.
|
||||
|
||||
### Sending the Note
|
||||
|
||||
`a.social` sends the note to `joe`'s inbox at `b.social`.
|
||||
|
||||
```bash
|
||||
curl -X POST https://b.social/inbox \
|
||||
-H "Content-Type: application/json; charset=utf-8" \
|
||||
-H "Accept: application/json" \
|
||||
-H "User-Agent: CoolerServer/1.0 (https://coolerserver.com)" \
|
||||
# The request is signed by Alice's private key
|
||||
-H "Versia-Signature: 9BrfplAPVH6OEqlV5eX7MazaZAInSCPODZcBEvMliBi/OwfbCAsezlb0O9jUX9ZcbBA68ThA4WUgS9V+42rfAQ==" \
|
||||
-H "Versia-Signed-By: https://a.social/users/alice" \
|
||||
-H "Versia-Signed-At: 1733051946"
|
||||
```
|
||||
|
||||
`b.social` responds with a `202 Accepted` status code.
|
||||
|
||||
### Displaying the Note
|
||||
|
||||
The software on `b.social` processes the note and shows it to `joe` using whatever interface it has.
|
||||
|
||||
`joe` can now see the note from `@alice` on `a.social` and respond to it.
|
||||
|
|
@ -268,6 +268,7 @@ export const navigation: NavGroup[] = [
|
|||
{ title: "Validation", href: "/federation/validation" },
|
||||
{ title: "Discovery", href: "/federation/discovery" },
|
||||
{ title: "Delegation", href: "/federation/delegation" },
|
||||
{ title: "Example", href: "/federation/example" },
|
||||
],
|
||||
},
|
||||
{
|
||||
|
|
|
|||
|
|
@ -31,6 +31,7 @@ const highlighter = await createHighlighter({
|
|||
"html",
|
||||
"json5",
|
||||
"jsonc",
|
||||
"markdown",
|
||||
"bash",
|
||||
"php",
|
||||
"python",
|
||||
|
|
|
|||
Loading…
Reference in a new issue