[Documentation] Update glossary, expand entry for dereferencing (#542)

* Update glossary, expand entry for dereferencing

* Add glossary as separate file
This commit is contained in:
tobi 2022-05-04 14:33:24 +02:00 committed by GitHub
parent d2b7c89d24
commit 807a8e1cf6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 74 additions and 28 deletions

View file

@ -0,0 +1,73 @@
# Glossary
This document describes some commonly-used terms in discussions of federation.
## `ActivityPub`
A decentralized social networking protocol based on the ActivityStreams data format. See [here](https://www.w3.org/TR/activitypub/).
GoToSocial uses the ActivityPub protocol to communicate between GtS servers, and with other federated servers like Mastodon, Pixelfed, etc.
## `ActivityStreams`
A model/data format for representing potential and completed activities using JSON. See [here](https://www.w3.org/TR/activitystreams-core/).
GoToSocial uses the ActivityStreams data model to 'speak' ActivityPub with other servers.
## `Actor`
An actor is an ActivityStreams object that is capable of performing some Activity like following, liking, creating a post, reblogging, etc. See [here](https://www.w3.org/TR/activitypub/#actors).
In GoToSocial, each account/user is an actor.
## `Dereference`
To 'dereference' a post or a profile means to make an HTTP call to the server that hosts that post or profile, in order to obtain its ActivityStreams representation.
GoToSocial 'dereferences' posts and profiles on remote servers, in order to convert them to models that GoToSocial can understand and work with.
Here's a more detailed explanation with some examples:
Let's say that someone on an ActivityPub server searches for the username `@tobi@goblin.technology`.
Their server would then do a webfinger lookup at `goblin.technology` for the username `tobi`, at the following URL:
```text
https://goblin.technology/.well-known/webfinger?resource=acct:tobi@goblin.technology
```
The `goblin.technology` server would give back some JSON in response; something like this:
```json
{
"subject": "acct:tobi@goblin.technology",
"aliases": [
"https://goblin.technology/users/tobi",
"https://goblin.technology/@tobi"
],
"links": [
{
"rel": "http://webfinger.net/rel/profile-page",
"type": "text/html",
"href": "https://goblin.technology/@tobi"
},
{
"rel": "self",
"type": "application/activity+json",
"href": "https://goblin.technology/users/tobi"
}
]
}
```
Under the links section the requesting server would look for a link of type `application/activity+json`, which denotes the ActivityStreams representation of the user. In this case, the URL is:
```text
https://goblin.technology/users/tobi
```
The above URL is a *reference* to the activitypub representation of the user/Actor `tobi` on the `goblin.technology` instance. It's called a reference because it doesn't contain all of the information about that user, it's only a reference point for where that information can be found.
Now, the requesting server will make a request to that URL in order to obtain a fuller representation of `@tobi@goblin.technology`, which complies to the ActivityPub spec. In other words, the server now follows a *reference* to get to the thing it references. This makes it *not a reference anymore*, hence the term *dereferencing*.
For an analogy, consider what happens when you look something up in the index of a book: first you get the page number that the material you're interested in is on, which is a reference. Then you turn to the referenced page to see the content, which is dereferencing.

View file

@ -9,31 +9,3 @@ Not all of the servers you 'federate' with will be running GoToSocial: popular i
This federated approach also means that you aren't beholden to arbitrary rules from some gigantic corporation potentially thousands of miles away. Your server has its own rules and culture; your fellow server residents are your neighbors; you will likely get to know your server admins and moderators, or be an admin yourself. This federated approach also means that you aren't beholden to arbitrary rules from some gigantic corporation potentially thousands of miles away. Your server has its own rules and culture; your fellow server residents are your neighbors; you will likely get to know your server admins and moderators, or be an admin yourself.
GoToSocial advocates for many small, weird, specialist servers where people can feel at home, rather than a few big and generic ones where one person's voice can get lost in the crowd. GoToSocial advocates for many small, weird, specialist servers where people can feel at home, rather than a few big and generic ones where one person's voice can get lost in the crowd.
## Glossary
Some commonly-used terms in discussions of federation, and their meanings.
### `ActivityPub`
A decentralized social networking protocol based on the ActivityStreams data format. See [here](https://www.w3.org/TR/activitypub/).
GoToSocial uses the ActivityPub protocol to communicate between GtS servers, and with other federated servers like Mastodon, Pixelfed, etc.
### `ActivityStreams`
A model/data format for representing potential and completed activities using JSON. See [here](https://www.w3.org/TR/activitystreams-core/).
GoToSocial uses the ActivityStreams data model to 'speak' ActivityPub with other servers.
### `Actor`
An actor is an ActivityStreams object that is capable of performing some Activity like following, liking, creating a post, reblogging, etc. See [here](https://www.w3.org/TR/activitypub/#actors).
In GoToSocial, each account/user is an actor.
### `Dereference`
To 'dereference' a post or a profile means to make an HTTP call to the server that hosts that post or profile, in order to obtain its ActivityStreams representation.
GoToSocial 'dereferences' posts and profiles on remote servers, in order to convert them to models that GoToSocial can understand and work with.

View file

@ -43,6 +43,7 @@ nav:
- "user_guide/password_management.md" - "user_guide/password_management.md"
- "Federation": - "Federation":
- "federation/index.md" - "federation/index.md"
- "federation/glossary.md"
- "federation/security.md" - "federation/security.md"
- "federation/behaviors/outbox.md" - "federation/behaviors/outbox.md"
- "federation/behaviors/conversation_threads.md" - "federation/behaviors/conversation_threads.md"