Add documentation for our ActivityPub implementation

Fixes #262
This commit is contained in:
Baptiste Gelez 2018-10-25 11:17:35 +01:00
parent 6efcba46ad
commit 175a9edb77
2 changed files with 196 additions and 0 deletions

195
docs/FEDERATION.md Normal file
View File

@ -0,0 +1,195 @@
# How Plume Federates
To federate with other Fediverse software (and itself), Plume uses various
protocols:
- [ActivityPub](http://activitypub.rocks/), as the main federation protocol.
- [WebFinger](https://webfinger.net/), to find other users and blog easily.
- [HTTP
Signatures](https://tools.ietf.org/id/draft-cavage-http-signatures-01.html), to
authenticate activities.
- [NodeInfo](http://nodeinfo.diaspora.software/), which is not part of the
federation itself, but that gives some metadata about each instance.
Currently, the following are federated:
- User profiles
- Blogs
- Articles
- Comments
- Likes
- Reshares
And these parts are not federated, but may be in the future:
- Media gallery
- Instance metadata
## WebFinger
WebFinger is used to discover remote profiles. When you open the page of an unknown
user (`/@/username@instance.tld`),
Plume will send a WebFinger request to the other instance, on the standard
`/.well-known/webfinger` endpoint. Plume
will ignore the `/.well-known/host-meta` endpoint (that can normally be used to
define another WebFinger endpoint),
and always use the standard URL.
Plume uses the [`webfinger`](https://crates.io/crates/webfinger) crate to serve
WebFinger informations and fetch them.
## HTTP Signatures
Plume check that each incoming Activity has been signed with the `actor`'s keypair.
To achieve that, it uses the `Signature` HTTP header. For more details on how this
header is generated, please refer to the [HTTP Signatures
Specification](https://tools.ietf.org/id/draft-cavage-http-signatures-01.html).
The `Digest` header should be present too, and used to generate the signature, so
that we can verify the body of the request too.
## NodeInfo
Plume exposes instance metadata with NodeInfo on the `/nodeinfo` URL.
*Example output*
```json
{
"version": "2.0",
"software": {
"name": "Plume",
"version": env!("CARGO_PKG_VERSION")
},
"protocols": ["activitypub"],
"services": {
"inbound": [],
"outbound": []
},
"openRegistrations": true,
"usage": {
"users": {
"total": User::count_local(&*conn)
},
"localPosts": Post::count_local(&*conn),
"localComments": Comment::count_local(&*conn)
},
"metadata": {}
}
```
## ActivityPub
Each user has a personal inbox at `/@/username/inbox`, and each instance has a shared
inbox at `/inbox`.
If available, Plume will use the shared inbox to deliver activities.
### Object representation
- `Note` represents a comment.
- `Article` is an article.
- `Person` is for users.
- `Group` is for blogs.
### Supported Activities
Plume 0.2.0 supports the following activity types.
#### Accept
Accepts a follow request.
It will be ignored when received, as Plume considered follow requests to be
immediatly approved in all cases (however, this will change in the future).
When a [`Follow`](#follow) activity is received, Plume will respond with this
activity.
- `actor` is the ID of the user accepting the request.
- `object` is the `Follow` object being accepted.
#### Announce
Reshares an article (not available for other objects).
Makes an user (`actor`) reshare a post (`object`).
- `actor` is the ID of the user who reshared the post.
- `object` is the ID of the post to reshare.
#### Create
Creates a new article or comment.
If `object` is an `Article`:
- `object.attibutedTo` is a list containing the ID of the authors and of the blog
in which this article have been published. If no blog ID is specified, the article
will be
rejected. The `actor` of the activity corresponds to the user that clicked the
"Publish" button, and should normally be one of the author in `attributedTo`.
- `object.name` is the title of the article.
- `object.content` is a string containing the HTML of the rendered article.
- `object.creationDate` is the date of the first publication of this article.
- `object.source` is a `Source` object, and its content is the Markdown source of
this article.
- `object.tag` is a list, and its elements are either:
- a `Hashtag` object, for the tag of the article (no difference is made between
global tags shown at the end of the article and hashtags in the article itself for
the
moment).
- a `Mention` object, for every actor that have been mentionned in this
article.
If `object` is a `Note`:
- `object.content` is the HTML source of the rendered comment.
- `object.inReplyTo` is the ID of the previous comment in the thread, or of the
post that is commented if there is no previous comment.
- `object.spoilerText` is a string to be displayed in place of the comment, unless
the reader explicitely express their will to see the actual content (what is called
*Content
Warning* in Mastodon)
- `object.tag` is a list of `Mention` that correspond to the mentionned users.
#### Delete
Deletes an object that was first created with a `Create` activity.
`object` is a `Tombstone`, and `object.id` the ID of the object to delete (either
an Article ID, or a Note ID).
#### Follow
When received, the actor is added to the follower list of the target.
These activities are immediatly accepted (see [`Accept`](#accept)) by Plume.
For blogs, they won't actually do anything else than sending back an `Accept`
activity: following a blog is not yet implemented.
- `actor` is the ID of an Actor, or a `Person` object. It represent the new
follower.
- `object` is the ID of the target user or blog.
#### Like
Can be used to add a like to an article.
- `actor` is the ID of the user liking the article.
- `object` is the ID of the post being liked.
#### Update
Updates an article.
- `object` is an `Article` object. It has no mandatory field other than `id`. Only
present fields will be updated.
- `object.id` is the ID the of the article being updated.
- `object.title` is the new title of the article.
- `object.content` is the updated HTML of the article.
- `object.subtitle` is the updated subtitle of the article.
- `object.source` is a `Source` object, and its `content` property is the updated
markdown of the article.
#### Undo
Cancels a previous action (either a like, reshare or follow).
- `object` is the `Announce`, `Follow` or `Like` to undo.

View File

@ -7,3 +7,4 @@
- [Making Plume available in your language](INTERNATIONALIZATION.md)
- [REST API reference](API.md)
- [`plm` CLI reference](CLI.md)
- [How Plume Federates](FEDERATION.md)