ForgeFlux/activitypub-federation-rust
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

move files

Browse source
This commit is contained in:
Felix Ableitner 2023-03-06 02:17:34 +01:00
parent d5ecab1b61
commit 32394696a5
44 changed files with 730 additions and 631 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

382
README.md
View file

@ -3,6 +3,8 @@ Activitypub-Federation
[![Build Status](https://drone.join-lemmy.org/api/badges/LemmyNet/activitypub-federation-rust/status.svg)](https://drone.join-lemmy.org/LemmyNet/activitypub-federation-rust) [![Build Status](https://drone.join-lemmy.org/api/badges/LemmyNet/activitypub-federation-rust/status.svg)](https://drone.join-lemmy.org/LemmyNet/activitypub-federation-rust)
[![Crates.io](https://img.shields.io/crates/v/activitypub-federation.svg)](https://crates.io/crates/activitypub-federation) [![Crates.io](https://img.shields.io/crates/v/activitypub-federation.svg)](https://crates.io/crates/activitypub-federation)
<!-- be sure to keep this file in sync with docs/01_intro.md -->
A high-level framework for [ActivityPub](https://www.w3.org/TR/activitypub/) federation in Rust. The goal is to encapsulate all basic functionality, so that developers can easily use the protocol without any prior knowledge. A high-level framework for [ActivityPub](https://www.w3.org/TR/activitypub/) federation in Rust. The goal is to encapsulate all basic functionality, so that developers can easily use the protocol without any prior knowledge.
The ActivityPub protocol is a decentralized social networking protocol. It allows web servers to exchange data using JSON over HTTP. Data can be fetched on demand, and also delivered directly to inboxes for live updates. The ActivityPub protocol is a decentralized social networking protocol. It allows web servers to exchange data using JSON over HTTP. Data can be fetched on demand, and also delivered directly to inboxes for live updates.
@ -15,388 +17,10 @@ While Activitypub is not in widespread use yet, is has the potential to form the
- **Censorship resistance**: Current social media platforms are under the control of a few corporations and are actively being censored as revealed by the [Twitter Files](https://jordansather.substack.com/p/running-list-of-all-twitter-files). This would be much more difficult on a federated network, as it would require the cooperation of every single instance administrator. Additionally, users who are affected by censorship can create their own websites and stay connected with the network. - **Censorship resistance**: Current social media platforms are under the control of a few corporations and are actively being censored as revealed by the [Twitter Files](https://jordansather.substack.com/p/running-list-of-all-twitter-files). This would be much more difficult on a federated network, as it would require the cooperation of every single instance administrator. Additionally, users who are affected by censorship can create their own websites and stay connected with the network.
- **Low barrier to entry**: All it takes to host a federated website are a small server, a domain and a TLS certificate. All of this is easily in the reach of individual hobbyists. There is also some technical knowledge needed, but this can be avoided with managed hosting platforms. - **Low barrier to entry**: All it takes to host a federated website are a small server, a domain and a TLS certificate. All of this is easily in the reach of individual hobbyists. There is also some technical knowledge needed, but this can be avoided with managed hosting platforms.
Below is a complete guide that explains how to create a federated project from scratch. [Visit the documentation](https://docs.rs/activitypub_federation/0.3.5/activitypub_federation/) for a full guide that explains how to create a federated project from scratch.
Feel free to open an issue if you have any questions regarding this crate. You can also join the Matrix channel [#activitystreams](https://matrix.to/#/%23activitystreams:matrix.asonix.dog) for discussion about Activitypub in Rust. Additionally check out [Socialhub forum](https://socialhub.activitypub.rocks/) for general ActivityPub development. Feel free to open an issue if you have any questions regarding this crate. You can also join the Matrix channel [#activitystreams](https://matrix.to/#/%23activitystreams:matrix.asonix.dog) for discussion about Activitypub in Rust. Additionally check out [Socialhub forum](https://socialhub.activitypub.rocks/) for general ActivityPub development.
## Overview
It is recommended to read the [W3C Activitypub standard document](https://www.w3.org/TR/activitypub/) which explains in detail how the protocol works. Note that it includes a section about client to server interactions, this functionality is not implemented by any major Fediverse project. Other relevant standard documents are [Activitystreams](https://www.w3.org/ns/activitystreams) and [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/). Its a good idea to keep these around as references during development.
This crate provides high level abstractions for the core functionality of Activitypub: fetching, sending and receiving data, as well as handling HTTP signatures. It was built from the experience of developing [Lemmy](https://join-lemmy.org/) which is the biggest Fediverse project written in Rust. Nevertheless it very generic and appropriate for any type of application wishing to implement the Activitypub protocol.
There are two examples included to see how the library altogether:
- `local_federation`: Creates two instances which run on localhost and federate with each other. This setup is ideal for quick development and well as automated tests.
- `live_federation`: A minimal application which can be deployed on a server and federate with other platforms such as Mastodon. For this it needs run at the root of a (sub)domain which is available over HTTPS. Edit `main.rs` to configure the server domain and your Fediverse handle. Once started, it will automatically send a message to you and log any incoming messages.
To see how this library is used in production, have a look at the [Lemmy federation code](https://github.com/LemmyNet/lemmy/tree/main/crates/apub).
## Federating users
This library intentionally doesn't include any predefined data structures for federated data. The reason is that each federated application is different, and needs different data formats. Activitypub also doesn't define any specific data structures, but provides a few mandatory fields and many which are optional. For this reason it works best to let each application define its own data structures, and take advantage of serde for (de)serialization. This means we don't use `json-ld` which Activitypub is based on, but that doesn't cause any problems in practice.
The first thing we need to federate are users. Its easiest to get started by looking at the data sent by other platforms. Here we fetch an account from Mastodon, ignoring the many optional fields. This curl command is generally very helpful to inspect and debug federated services.
```text
$ curl -H 'Accept: application/activity+json' https://mastodon.social/@LemmyDev | jq
{
"id": "https://mastodon.social/users/LemmyDev",
"type": "Person",
"preferredUsername": "LemmyDev",
"name": "Lemmy",
"inbox": "https://mastodon.social/users/LemmyDev/inbox",
"outbox": "https://mastodon.social/users/LemmyDev/outbox",
"publicKey": {
"id": "https://mastodon.social/users/LemmyDev#main-key",
"owner": "https://mastodon.social/users/LemmyDev",
"publicKeyPem": "..."
},
...
}
```
TODO: is outbox required by mastodon?
The most important fields are:
- `id`: Unique identifier for this object. At the same time it is the URL where we can fetch the object from
- `type`: The type of this object
- `preferredUsername`: Immutable username which was chosen at signup and is used in URLs as well as in mentions like `@LemmyDev@mastodon.social`
- `name`: Displayname which can be freely changed at any time
- `inbox`: URL where incoming activities are delivered to, treated in a later section
see xx document for a definition of each field
- `publicKey`: Key which is used for [HTTP Signatures](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures)
Refer to [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/) for further details and description of other fields. You can also inspect many other URLs on federated platforms with the given curl command.
Based on this we can define the following minimal struct to (de)serialize a `Person` with serde.
```rust
# use activitypub_federation::protocol::public_key::PublicKey;
# use activitypub_federation::core::object_id::ObjectId;
# use serde::{Deserialize, Serialize};
# use activitystreams_kinds::actor::PersonType;
# use url::Url;
# use activitypub_federation::traits::tests::DbUser;
#[derive(Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Person {
id: ObjectId<DbUser>,
#[serde(rename = "type")]
kind: PersonType,
preferred_username: String,
name: String,
inbox: Url,
outbox: Url,
public_key: PublicKey,
}
```
`ObjectId` is a wrapper for `Url` which helps to fetch data from a remote server, and convert it to `DbUser` which is the type that's stored in our local database. It also helps with caching data so that it doesn't have to be refetched every time.
`PersonType` is an enum with a single variant `Person`. It is used to deserialize objects in a typesafe way: If the JSON type value does not match the string `Person`, deserialization fails. This helps in places where we don't know the exact data type that is being deserialized, as you will see later.
Besides we also need a second struct to represent the data which gets stored in our local database (for example PostgreSQL). This is necessary because the data format used by SQL is very different from that used by that from Activitypub. It is organized by an integer primary key instead of a link id. Nested structs are complicated to represent and easier if flattened. Some fields like `type` don't need to be stored at all. On the other hand, the database contains fields which can't be federated, such as the private key and a boolean indicating if the item is local or remote.
```rust
# use url::Url;
pub struct DbUser {
pub id: i32,
pub name: String,
pub display_name: String,
pub password_hash: Option<String>,
pub email: Option<String>,
pub apub_id: Url,
pub inbox: Url,
pub outbox: Url,
pub local: bool,
public_key: String,
private_key: Option<String>,
}
```
Field names and other details of this type can be chosen freely according to your requirements. It only matters that the required data is being stored. Its important that this struct doesn't represent only local users who registered directly on our website, but also remote users that are registered on other instances and federated to us. The `local` column helps to easily distinguish both. It can also be distinguished from the domain of the `apub_id` URL, but that would be a much more expensive operation. All users have a `public_key`, but only local users have a `private_key`. On the other hand, `password_hash` and `email` are only present for local users. inbox` and `outbox` URLs need to be stored because each implementation is free to choose its own format for them, so they can't be regenerated on the fly.
In larger projects it makes sense to split this data in two. One for data relevant to local users (`password_hash`, `email` etc) and one for data that is shared by both local and federated users (`apub_id`, `public_key` etc).
Finally we need to implement the traits [ApubObject](crate::traits::ApubObject) and [Actor](crate::traits::Actor) for `DbUser`. These traits are used to convert between `Person` and `DbUser` types. [ApubObject::from_apub](crate::traits::ApubObject::from_apub) must store the received object in database, so that it can later be retrieved without network calls using [ApubObject::read_from_apub_id](crate::traits::ApubObject::read_from_apub_id). Refer to the documentation for more details.
## Configuration and fetching data
Next we need to do some configuration. Most importantly we need to specify the domain where the federated instance is running. It should be at the domain root and available over HTTPS for production. See the documentation for a list of config options. The parameter `user_data` is for anything that your application requires in handler functions, such as database connection handle, configuration etc.
```
# use activitypub_federation::config::FederationConfig;
# let db_connection = ();
# let _ = actix_rt::System::new();
let config = FederationConfig::builder()
.domain("example.com")
.app_data(db_connection)
.build()?;
# Ok::<(), anyhow::Error>(())
```
With this we can already fetch data from remote servers:
```no_run
# use activitypub_federation::core::object_id::ObjectId;
# use activitypub_federation::traits::tests::DbUser;
# use activitypub_federation::config::FederationConfig;
# let db_connection = activitypub_federation::traits::tests::DbConnection;
# let _ = actix_rt::System::new();
# actix_rt::Runtime::new().unwrap().block_on(async {
let config = FederationConfig::builder().domain("example.com").app_data(db_connection).build()?;
let user_id = ObjectId::<DbUser>::new("https://mastodon.social/@LemmyDev")?;
let data = config.to_request_data();
let user = user_id.dereference(&data).await;
assert!(user.is_ok());
# Ok::<(), anyhow::Error>(())
}).unwrap()
```
`dereference` retrieves the object JSON at the given URL, and uses serde to convert it to `Person`. It then calls your method `ApubObject::from_apub` which inserts it in the database and returns a `DbUser` struct. `request_data` contains the federation config as well as a counter of outgoing HTTP requests. If this counter exceeds the configured maximum, further requests are aborted in order to avoid recursive fetching which could allow for a denial of service attack.
After dereferencing a remote object, it is stored in the local database and can be retrieved using [ObjectId::dereference_local](crate::core::object_id::ObjectId::dereference_local) without any network requests. This is important for performance reasons and for searching.
## Federating posts
We repeat the same steps taken above for users in order to federate our posts.
```text
$ curl -H 'Accept: application/activity+json' https://mastodon.social/@LemmyDev/109790106847504642 | jq
{
"id": "https://mastodon.social/users/LemmyDev/statuses/109790106847504642",
"type": "Note",
"content": "<p><a href=\"https://mastodon.social/tags/lemmy\" ...",
"attributedTo": "https://mastodon.social/users/LemmyDev",
"to": [
"https://www.w3.org/ns/activitystreams#Public"
],
"cc": [
"https://mastodon.social/users/LemmyDev/followers"
],
}
```
The most important fields are:
- `id`: Unique identifier for this object. At the same time it is the URL where we can fetch the object from
- `type`: The type of this object
- `content`: Post text in HTML format
- `attributedTo`: ID of the user who created this post
- `to`, `cc`: Who the object is for. The special "public" URL indicates that everyone can view it. It also gets delivered to followers of the LemmyDev account.
Just like for `Person` before, we need to implement a protocol type and a database type, then implement trait `ApubObject`. See the example for details.
## HTTP endpoints
The next step is to allow other servers to fetch our actors and objects. For this we need to create an HTTP route, most commonly at the same path where the actor or object can be viewed in a web browser. On this path there should be another route which responds to requests with header `Accept: application/activity+json` and serves the JSON data. This needs to be done for all actors and objects. Note that only local items should be served in this way.
```no_run
# use std::net::SocketAddr;
# use activitypub_federation::config::FederationConfig;
# use activitypub_federation::protocol::context::WithContext;
# use activitypub_federation::core::axum::json::ApubJson;
# use anyhow::Error;
# use activitypub_federation::traits::tests::Person;
# use activitypub_federation::config::RequestData;
# use activitypub_federation::traits::tests::DbConnection;
# use axum::extract::Path;
# use activitypub_federation::config::ApubMiddleware;
# use axum::routing::get;
# use crate::activitypub_federation::traits::ApubObject;
# use axum::headers::ContentType;
# use activitypub_federation::APUB_JSON_CONTENT_TYPE;
# use axum::TypedHeader;
# use axum::response::IntoResponse;
# use http::HeaderMap;
# async fn generate_user_html(_: String, _: RequestData<DbConnection>) -> axum::response::Response { todo!() }
#[actix_rt::main]
async fn main() -> Result<(), Error> {
let data = FederationConfig::builder()
.domain("example.com")
.app_data(DbConnection)
.build()?;
let app = axum::Router::new()
.route("/user/:name", get(http_get_user))
.layer(ApubMiddleware::new(data));
let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
tracing::debug!("listening on {}", addr);
axum::Server::bind(&addr)
.serve(app.into_make_service())
.await?;
Ok(())
}
async fn http_get_user(
header_map: HeaderMap,
Path(name): Path<String>,
data: RequestData<DbConnection>,
) -> impl IntoResponse {
let accept = header_map.get("accept").map(|v| v.to_str().unwrap());
if accept == Some(APUB_JSON_CONTENT_TYPE) {
let db_user = data.read_local_user(name).await.unwrap();
let apub_user = db_user.into_apub(&data).await.unwrap();
ApubJson(WithContext::new_default(apub_user)).into_response()
}
else {
generate_user_html(name, data).await
}
}
```
There are a couple of things going on here. Like before we are constructing the federation config with our domain and application data. We pass this to a middleware to make it available in request handlers, then listening on a port with the axum webserver.
The `http_get_user` method allows retrieving a user profile from `/user/:name`. It checks the `accept` header, and compares it to the one used by Activitypub (`application/activity+json`). If it matches, the user is read from database and converted to Activitypub json format. The `context` field is added (`WithContext` for `json-ld` compliance), and it is converted to a JSON response with header `content-type: application/activity+json` using `ApubJson`. It can now be retrieved with the command `curl -H 'Accept: application/activity+json' ...` introduced earlier, or with `ObjectId`.
If the `accept` header doesn't match, it renders the user profile as HTML for viewing in a web browser.
## Webfinger
Webfinger can resolve a handle like `@nutomic@lemmy.ml` into an ID like `https://lemmy.ml/u/nutomic` which can be used by Activitypub. Webfinger is not part of the ActivityPub standard, but the fact that Mastodon requires it makes it de-facto mandatory. It is defined in [RFC 7033](https://www.rfc-editor.org/rfc/rfc7033). Implementing it basically means handling requests of the form`https://mastodon.social/.well-known/webfinger?resource=acct:LemmyDev@mastodon.social`.
To do this we can implement the following HTTP handler which must be bound to path `.well-known/webfinger`.
```rust
# use serde::Deserialize;
# use axum::{extract::Query, Json};
# use activitypub_federation::config::RequestData;
# use activitypub_federation::webfinger::Webfinger;
# use anyhow::Error;
# use activitypub_federation::traits::tests::DbConnection;
# use activitypub_federation::webfinger::extract_webfinger_name;
# use activitypub_federation::webfinger::build_webfinger_response;
#[derive(Deserialize)]
struct WebfingerQuery {
resource: String,
}
async fn webfinger(
Query(query): Query<WebfingerQuery>,
data: RequestData<DbConnection>,
) -> Result<Json<Webfinger>, Error> {
let name = extract_webfinger_name(&query.resource, &data)?;
let db_user = data.read_local_user(name).await?;
Ok(Json(build_webfinger_response(query.resource, db_user.apub_id)))
}
```
The resolve a user via webfinger call the following method:
```rust
# use activitypub_federation::traits::tests::DbConnection;
# use activitypub_federation::config::FederationConfig;
# use activitypub_federation::webfinger::webfinger_resolve_actor;
# use activitypub_federation::traits::tests::DbUser;
# let db_connection = DbConnection;
# let _ = actix_rt::System::new();
# actix_rt::Runtime::new().unwrap().block_on(async {
# let config = FederationConfig::builder().domain("example.com").app_data(db_connection).build()?;
# let data = config.to_request_data();
let user: DbUser = webfinger_resolve_actor("nutomic@lemmy.ml", &data).await?;
# Ok::<(), anyhow::Error>(())
# }).unwrap();
```
Note that webfinger queries don't contain a leading `@`. `webfinger_resolve_actor` fetches the webfinger response, finds the matching actor ID, fetches the actor using [ObjectId::dereference](crate::core::object_id::ObjectId::dereference) and converts it with [ApubObject::from_apub](crate::traits::ApubObject::from_apub). It is possible tha there are multiple Activitypub IDs returned for a single webfinger query in case of multiple actors with the same name (for example Lemmy permits group and person with the same name). In this case `webfinger_resolve_actor` automatically loops and returns the first item which can be dereferenced successfully to the given type.
## Sending and receiving activities
TODO: continue here
```text
#[derive(Deserialize, Serialize, Clone, Debug)]
#[serde(rename_all = "camelCase")]
pub struct Follow {
pub actor: ObjectId<DbUser>,
pub object: ObjectId<DbUser>,
#[serde(rename = "type")]
pub kind: FollowType,
pub id: Url,
}
```
## Fetching remote object with unknown type
It is sometimes necessary to fetch from a URL, but we don't know the exact type of object it will return. An example is the search field in most federated platforms, which allows pasting and `id` URL and fetches it from the origin server. It can implemented in the following way:
```no_run
# use activitypub_federation::traits::tests::{DbUser, DbPost};
# use activitypub_federation::core::object_id::ObjectId;
# use activitypub_federation::traits::ApubObject;
# use activitypub_federation::config::FederationConfig;
# use serde::{Deserialize, Serialize};
# use activitypub_federation::traits::tests::DbConnection;
# use activitypub_federation::config::RequestData;
# use url::Url;
# use activitypub_federation::traits::tests::{Person, Note};
pub enum SearchableDbObjects {
User(DbUser),
Post(DbPost)
}
#[derive(Deserialize, Serialize)]
#[serde(untagged)]
pub enum SearchableApubObjects {
Person(Person),
Note(Note)
}
#[async_trait::async_trait]
impl ApubObject for SearchableDbObjects {
type DataType = DbConnection;
type ApubType = SearchableApubObjects;
type Error = anyhow::Error;
async fn read_from_apub_id(
object_id: Url,
data: &RequestData<Self::DataType>,
) -> Result<Option<Self>, Self::Error> {
Ok(None)
}
async fn into_apub(
self,
data: &RequestData<Self::DataType>,
) -> Result<Self::ApubType, Self::Error> {
unimplemented!();
}
async fn from_apub(
apub: Self::ApubType,
data: &RequestData<Self::DataType>,
) -> Result<Self, Self::Error> {
use SearchableDbObjects::*;
match apub {
SearchableApubObjects::Person(p) => Ok(User(DbUser::from_apub(p, data).await?)),
SearchableApubObjects::Note(n) => Ok(Post(DbPost::from_apub(n, data).await?)),
}
}
}
#[actix_rt::main]
async fn main() -> Result<(), anyhow::Error> {
# let config = FederationConfig::builder().domain("example.com").app_data(DbConnection).build().unwrap();
# let data = config.to_request_data();
let query = "https://example.com/id/413";
let query_result = ObjectId::<SearchableDbObjects>::new(query)?
.dereference(&data)
.await?;
match query_result {
SearchableDbObjects::Post(post) => {} // retrieved object is a post
SearchableDbObjects::User(user) => {} // object is a user
};
Ok(())
}
```
What this does is...
## License ## License
Licensed under [AGPLv3](/LICENSE). Licensed under [AGPLv3](/LICENSE).

17
docs/01_intro.md Normal file
View file

@ -0,0 +1,17 @@
<!-- be sure to keep this file in sync with README.md -->
A high-level framework for [ActivityPub](https://www.w3.org/TR/activitypub/) federation in Rust. The goal is to encapsulate all basic functionality, so that developers can easily use the protocol without any prior knowledge.
The ActivityPub protocol is a decentralized social networking protocol. It allows web servers to exchange data using JSON over HTTP. Data can be fetched on demand, and also delivered directly to inboxes for live updates.
While Activitypub is not in widespread use yet, is has the potential to form the basis of the next generation of social media. This is because it has a number of major advantages compared to existing platforms and alternative technologies:
- **Interoperability**: Imagine being able to comment under a Youtube video directly from twitter.com, and having the comment shown under the video on youtube.com. Or following a Subreddit from Facebook. Such functionality is already available on the equivalent Fediverse platforms, thanks to common usage of Activitypub.
- **Ease of use**: From a user perspective, decentralized social media works almost identically to existing websites: a website with email and password based login. Unlike pure peer-to-peer networks, it is not necessary to handle private keys or install any local software.
- **Open ecosystem**: All existing Fediverse software is open source, and there are no legal or bureaucratic requirements to start federating. That means anyone can create or fork federated software. In this way different software platforms can exist in the same network according to the preferences of different user groups. It is not necessary to target the lowest common denominator as with corporate social media.
- **Censorship resistance**: Current social media platforms are under the control of a few corporations and are actively being censored as revealed by the [Twitter Files](https://jordansather.substack.com/p/running-list-of-all-twitter-files). This would be much more difficult on a federated network, as it would require the cooperation of every single instance administrator. Additionally, users who are affected by censorship can create their own websites and stay connected with the network.
- **Low barrier to entry**: All it takes to host a federated website are a small server, a domain and a TLS certificate. All of this is easily in the reach of individual hobbyists. There is also some technical knowledge needed, but this can be avoided with managed hosting platforms.
Below you can find a complete guide that explains how to create a federated project from scratch.
Feel free to open an issue if you have any questions regarding this crate. You can also join the Matrix channel [#activitystreams](https://matrix.to/#/%23activitystreams:matrix.asonix.dog) for discussion about Activitypub in Rust. Additionally check out [Socialhub forum](https://socialhub.activitypub.rocks/) for general ActivityPub development.

12
docs/02_overview.md Normal file
View file

@ -0,0 +1,12 @@
## Overview
It is recommended to read the [W3C Activitypub standard document](https://www.w3.org/TR/activitypub/) which explains in detail how the protocol works. Note that it includes a section about client to server interactions, this functionality is not implemented by any major Fediverse project. Other relevant standard documents are [Activitystreams](https://www.w3.org/ns/activitystreams) and [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/). Its a good idea to keep these around as references during development.
This crate provides high level abstractions for the core functionality of Activitypub: fetching, sending and receiving data, as well as handling HTTP signatures. It was built from the experience of developing [Lemmy](https://join-lemmy.org/) which is the biggest Fediverse project written in Rust. Nevertheless it very generic and appropriate for any type of application wishing to implement the Activitypub protocol.
There are two examples included to see how the library altogether:
- `local_federation`: Creates two instances which run on localhost and federate with each other. This setup is ideal for quick development and well as automated tests.
- `live_federation`: A minimal application which can be deployed on a server and federate with other platforms such as Mastodon. For this it needs run at the root of a (sub)domain which is available over HTTPS. Edit `main.rs` to configure the server domain and your Fediverse handle. Once started, it will automatically send a message to you and log any incoming messages.
To see how this library is used in production, have a look at the [Lemmy federation code](https://github.com/LemmyNet/lemmy/tree/main/crates/apub).

88
docs/03_federating_users.md Normal file
View file

@ -0,0 +1,88 @@
## Federating users
This library intentionally doesn't include any predefined data structures for federated data. The reason is that each federated application is different, and needs different data formats. Activitypub also doesn't define any specific data structures, but provides a few mandatory fields and many which are optional. For this reason it works best to let each application define its own data structures, and take advantage of serde for (de)serialization. This means we don't use `json-ld` which Activitypub is based on, but that doesn't cause any problems in practice.
The first thing we need to federate are users. Its easiest to get started by looking at the data sent by other platforms. Here we fetch an account from Mastodon, ignoring the many optional fields. This curl command is generally very helpful to inspect and debug federated services.
```text
$ curl -H 'Accept: application/activity+json' https://mastodon.social/@LemmyDev | jq
{
"id": "https://mastodon.social/users/LemmyDev",
"type": "Person",
"preferredUsername": "LemmyDev",
"name": "Lemmy",
"inbox": "https://mastodon.social/users/LemmyDev/inbox",
"outbox": "https://mastodon.social/users/LemmyDev/outbox",
"publicKey": {
"id": "https://mastodon.social/users/LemmyDev#main-key",
"owner": "https://mastodon.social/users/LemmyDev",
"publicKeyPem": "..."
},
...
}
```
The most important fields are:
- `id`: Unique identifier for this object. At the same time it is the URL where we can fetch the object from
- `type`: The type of this object
- `preferredUsername`: Immutable username which was chosen at signup and is used in URLs as well as in mentions like `@LemmyDev@mastodon.social`
- `name`: Displayname which can be freely changed at any time
- `inbox`: URL where incoming activities are delivered to, treated in a later section
see xx document for a definition of each field
- `publicKey`: Key which is used for [HTTP Signatures](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures)
Refer to [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/) for further details and description of other fields. You can also inspect many other URLs on federated platforms with the given curl command.
Based on this we can define the following minimal struct to (de)serialize a `Person` with serde.
```rust
# use activitypub_federation::protocol::public_key::PublicKey;
# use activitypub_federation::fetch::object_id::ObjectId;
# use serde::{Deserialize, Serialize};
# use activitystreams_kinds::actor::PersonType;
# use url::Url;
# use activitypub_federation::traits::tests::DbUser;
#[derive(Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Person {
id: ObjectId<DbUser>,
#[serde(rename = "type")]
kind: PersonType,
preferred_username: String,
name: String,
inbox: Url,
outbox: Url,
public_key: PublicKey,
}
```
`ObjectId` is a wrapper for `Url` which helps to fetch data from a remote server, and convert it to `DbUser` which is the type that's stored in our local database. It also helps with caching data so that it doesn't have to be refetched every time.
`PersonType` is an enum with a single variant `Person`. It is used to deserialize objects in a typesafe way: If the JSON type value does not match the string `Person`, deserialization fails. This helps in places where we don't know the exact data type that is being deserialized, as you will see later.
Besides we also need a second struct to represent the data which gets stored in our local database (for example PostgreSQL). This is necessary because the data format used by SQL is very different from that used by that from Activitypub. It is organized by an integer primary key instead of a link id. Nested structs are complicated to represent and easier if flattened. Some fields like `type` don't need to be stored at all. On the other hand, the database contains fields which can't be federated, such as the private key and a boolean indicating if the item is local or remote.
```rust
# use url::Url;
pub struct DbUser {
pub id: i32,
pub name: String,
pub display_name: String,
pub password_hash: Option<String>,
pub email: Option<String>,
pub apub_id: Url,
pub inbox: Url,
pub outbox: Url,
pub local: bool,
public_key: String,
private_key: Option<String>,
}
```
Field names and other details of this type can be chosen freely according to your requirements. It only matters that the required data is being stored. Its important that this struct doesn't represent only local users who registered directly on our website, but also remote users that are registered on other instances and federated to us. The `local` column helps to easily distinguish both. It can also be distinguished from the domain of the `apub_id` URL, but that would be a much more expensive operation. All users have a `public_key`, but only local users have a `private_key`. On the other hand, `password_hash` and `email` are only present for local users. inbox` and `outbox` URLs need to be stored because each implementation is free to choose its own format for them, so they can't be regenerated on the fly.
In larger projects it makes sense to split this data in two. One for data relevant to local users (`password_hash`, `email` etc.) and one for data that is shared by both local and federated users (`apub_id`, `public_key` etc).
Finally we need to implement the traits [ApubObject](crate::traits::ApubObject) and [Actor](crate::traits::Actor) for `DbUser`. These traits are used to convert between `Person` and `DbUser` types. [ApubObject::from_apub](crate::traits::ApubObject::from_apub) must store the received object in database, so that it can later be retrieved without network calls using [ApubObject::read_from_apub_id](crate::traits::ApubObject::read_from_apub_id). Refer to the documentation for more details.

28
docs/04_federating_posts.md Normal file
View file

@ -0,0 +1,28 @@
## Federating posts
We repeat the same steps taken above for users in order to federate our posts.
```text
$ curl -H 'Accept: application/activity+json' https://mastodon.social/@LemmyDev/109790106847504642 | jq
{
"id": "https://mastodon.social/users/LemmyDev/statuses/109790106847504642",
"type": "Note",
"content": "<p><a href=\"https://mastodon.social/tags/lemmy\" ...",
"attributedTo": "https://mastodon.social/users/LemmyDev",
"to": [
"https://www.w3.org/ns/activitystreams#Public"
],
"cc": [
"https://mastodon.social/users/LemmyDev/followers"
],
}
```
The most important fields are:
- `id`: Unique identifier for this object. At the same time it is the URL where we can fetch the object from
- `type`: The type of this object
- `content`: Post text in HTML format
- `attributedTo`: ID of the user who created this post
- `to`, `cc`: Who the object is for. The special "public" URL indicates that everyone can view it. It also gets delivered to followers of the LemmyDev account.
Just like for `Person` before, we need to implement a protocol type and a database type, then implement trait `ApubObject`. See the example for details.

16
docs/05_configuration.md Normal file
View file

@ -0,0 +1,16 @@
## Configuration
Next we need to do some configuration. Most importantly we need to specify the domain where the federated instance is running. It should be at the domain root and available over HTTPS for production. See the documentation for a list of config options. The parameter `user_data` is for anything that your application requires in handler functions, such as database connection handle, configuration etc.
```
# use activitypub_federation::config::FederationConfig;
# let db_connection = ();
# let _ = actix_rt::System::new();
let config = FederationConfig::builder()
.domain("example.com")
.app_data(db_connection)
.build()?;
# Ok::<(), anyhow::Error>(())
```
`debug` is necessary to test federation with http and localhost URLs, but it should never be used in production. The `worker_count` value can be adjusted depending on the instance size. A lower value saves resources on a small instance, while a higher value is necessary on larger instances to keep up with send jobs. `url_verifier` can be used to implement a domain blacklist.

94
docs/06_http_endpoints_axum.md Normal file
View file

@ -0,0 +1,94 @@
## HTTP endpoints
The next step is to allow other servers to fetch our actors and objects. For this we need to create an HTTP route, most commonly at the same path where the actor or object can be viewed in a web browser. On this path there should be another route which responds to requests with header `Accept: application/activity+json` and serves the JSON data. This needs to be done for all actors and objects. Note that only local items should be served in this way.
```no_run
# use std::net::SocketAddr;
# use activitypub_federation::config::FederationConfig;
# use activitypub_federation::protocol::context::WithContext;
# use activitypub_federation::axum::json::ApubJson;
# use anyhow::Error;
# use activitypub_federation::traits::tests::Person;
# use activitypub_federation::config::RequestData;
# use activitypub_federation::traits::tests::DbConnection;
# use axum::extract::Path;
# use activitypub_federation::config::ApubMiddleware;
# use axum::routing::get;
# use crate::activitypub_federation::traits::ApubObject;
# use axum::headers::ContentType;
# use activitypub_federation::APUB_JSON_CONTENT_TYPE;
# use axum::TypedHeader;
# use axum::response::IntoResponse;
# use http::HeaderMap;
# async fn generate_user_html(_: String, _: RequestData<DbConnection>) -> axum::response::Response { todo!() }
#[actix_rt::main]
async fn main() -> Result<(), Error> {
let data = FederationConfig::builder()
.domain("example.com")
.app_data(DbConnection)
.build()?;
let app = axum::Router::new()
.route("/user/:name", get(http_get_user))
.layer(ApubMiddleware::new(data));
let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
tracing::debug!("listening on {}", addr);
axum::Server::bind(&addr)
.serve(app.into_make_service())
.await?;
Ok(())
}
async fn http_get_user(
header_map: HeaderMap,
Path(name): Path<String>,
data: RequestData<DbConnection>,
) -> impl IntoResponse {
let accept = header_map.get("accept").map(|v| v.to_str().unwrap());
if accept == Some(APUB_JSON_CONTENT_TYPE) {
let db_user = data.read_local_user(name).await.unwrap();
let apub_user = db_user.into_apub(&data).await.unwrap();
ApubJson(WithContext::new_default(apub_user)).into_response()
}
else {
generate_user_html(name, data).await
}
}
```
There are a couple of things going on here. Like before we are constructing the federation config with our domain and application data. We pass this to a middleware to make it available in request handlers, then listening on a port with the axum webserver.
The `http_get_user` method allows retrieving a user profile from `/user/:name`. It checks the `accept` header, and compares it to the one used by Activitypub (`application/activity+json`). If it matches, the user is read from database and converted to Activitypub json format. The `context` field is added (`WithContext` for `json-ld` compliance), and it is converted to a JSON response with header `content-type: application/activity+json` using `ApubJson`. It can now be retrieved with the command `curl -H 'Accept: application/activity+json' ...` introduced earlier, or with `ObjectId`.
If the `accept` header doesn't match, it renders the user profile as HTML for viewing in a web browser.
We also need to implement a webfinger endpoint, which can resolve a handle like `@nutomic@lemmy.ml` into an ID like `https://lemmy.ml/u/nutomic` that can be used by Activitypub. Webfinger is not part of the ActivityPub standard, but the fact that Mastodon requires it makes it de-facto mandatory. It is defined in [RFC 7033](https://www.rfc-editor.org/rfc/rfc7033). Implementing it basically means handling requests of the form`https://mastodon.social/.well-known/webfinger?resource=acct:LemmyDev@mastodon.social`.
To do this we can implement the following HTTP handler which must be bound to path `.well-known/webfinger`.
```rust
# use serde::Deserialize;
# use axum::{extract::Query, Json};
# use activitypub_federation::config::RequestData;
# use activitypub_federation::fetch::webfinger::Webfinger;
# use anyhow::Error;
# use activitypub_federation::traits::tests::DbConnection;
# use activitypub_federation::fetch::webfinger::extract_webfinger_name;
# use activitypub_federation::fetch::webfinger::build_webfinger_response;
#[derive(Deserialize)]
struct WebfingerQuery {
resource: String,
}
async fn webfinger(
Query(query): Query<WebfingerQuery>,
data: RequestData<DbConnection>,
) -> Result<Json<Webfinger>, Error> {
let name = extract_webfinger_name(&query.resource, &data)?;
let db_user = data.read_local_user(name).await?;
Ok(Json(build_webfinger_response(query.resource, db_user.apub_id)))
}
```

44
docs/07_fetching_data.md Normal file
View file

@ -0,0 +1,44 @@
## Fetching data
After setting up our structs, implementing traits and initializing configuration, we can easily fetch data from remote servers:
```no_run
# use activitypub_federation::fetch::object_id::ObjectId;
# use activitypub_federation::traits::tests::DbUser;
# use activitypub_federation::config::FederationConfig;
# let db_connection = activitypub_federation::traits::tests::DbConnection;
# let _ = actix_rt::System::new();
# actix_rt::Runtime::new().unwrap().block_on(async {
let config = FederationConfig::builder()
.domain("example.com")
.app_data(db_connection)
.build()?;
let user_id = ObjectId::<DbUser>::new("https://mastodon.social/@LemmyDev")?;
let data = config.to_request_data();
let user = user_id.dereference(&data).await;
assert!(user.is_ok());
# Ok::<(), anyhow::Error>(())
}).unwrap()
```
`dereference` retrieves the object JSON at the given URL, and uses serde to convert it to `Person`. It then calls your method `ApubObject::from_apub` which inserts it in the database and returns a `DbUser` struct. `request_data` contains the federation config as well as a counter of outgoing HTTP requests. If this counter exceeds the configured maximum, further requests are aborted in order to avoid recursive fetching which could allow for a denial of service attack.
After dereferencing a remote object, it is stored in the local database and can be retrieved using [ObjectId::dereference_local](crate::fetch::object_id::ObjectId::dereference_local) without any network requests. This is important for performance reasons and for searching.
We can similarly dereference a user over webfinger with the following method. It fetches the webfinger response from `.well-known/webfinger` and then fetches the actor using [ObjectId::dereference](crate::fetch::object_id::ObjectId::dereference) as above.
```rust
# use activitypub_federation::traits::tests::DbConnection;
# use activitypub_federation::config::FederationConfig;
# use activitypub_federation::fetch::webfinger::webfinger_resolve_actor;
# use activitypub_federation::traits::tests::DbUser;
# let db_connection = DbConnection;
# let _ = actix_rt::System::new();
# actix_rt::Runtime::new().unwrap().block_on(async {
# let config = FederationConfig::builder().domain("example.com").app_data(db_connection).build()?;
# let data = config.to_request_data();
let user: DbUser = webfinger_resolve_actor("nutomic@lemmy.ml", &data).await?;
# Ok::<(), anyhow::Error>(())
# }).unwrap();
```
Note that webfinger queries don't contain a leading `@`. It is possible tha there are multiple Activitypub IDs returned for a single webfinger query in case of multiple actors with the same name (for example Lemmy permits group and person with the same name). In this case `webfinger_resolve_actor` automatically loops and returns the first item which can be dereferenced successfully to the given type.

84
docs/08_receiving_activities.md Normal file
View file

@ -0,0 +1,84 @@
## Sending and receiving activities
Activitypub propagates actions across servers using `Activities`. For this each actor has an inbox and a public/private key pair. We already defined a `Person` actor with keypair. Whats left is to define an activity. This is similar to the way we defined `Person` and `Note` structs before. In this case we need to implement the [ActivityHandler](trait@crate::traits::ActivityHandler) trait.
```
# use serde::{Deserialize, Serialize};
# use url::Url;
# use anyhow::Error;
# use async_trait::async_trait;
# use activitypub_federation::fetch::object_id::ObjectId;
# use activitypub_federation::traits::tests::{DbConnection, DbUser};
# use activitystreams_kinds::activity::FollowType;
# use activitypub_federation::traits::ActivityHandler;
# use activitypub_federation::config::RequestData;
# async fn send_accept() -> Result<(), Error> { Ok(()) }
#[derive(Deserialize, Serialize, Clone, Debug)]
#[serde(rename_all = "camelCase")]
pub struct Follow {
pub actor: ObjectId<DbUser>,
pub object: ObjectId<DbUser>,
#[serde(rename = "type")]
pub kind: FollowType,
pub id: Url,
}
#[async_trait]
impl ActivityHandler for Follow {
type DataType = DbConnection;
type Error = Error;
fn id(&self) -> &Url {
&self.id
}
fn actor(&self) -> &Url {
self.actor.inner()
}
async fn receive(self, data: &RequestData<Self::DataType>) -> Result<(), Self::Error> {
let actor = self.actor.dereference(data).await?;
let followed = self.object.dereference(data).await?;
data.add_follower(followed, actor).await?;
Ok(())
}
}
```
In this case there is no need to convert to a database type, because activities don't need to be stored in the database in full. Instead we dereference the involved user accounts, and create a follow relation in the database.
Next its time to setup the actual HTTP handler for the inbox. For this we first define an enum of all activities which are accepted by the actor. Then we just need to define an HTTP endpoint at the path of our choice (identical to `Person.inbox` defined earlier). This endpoint needs to hand received data over to [receive_activity](crate::axum::inbox::receive_activity). This method verifies the HTTP signature, checks the blocklist with [FederationConfigBuilder::url_verifier](crate::config::FederationConfigBuilder::url_verifier) and more. If everything is valid, the activity is passed to the `receive` method we defined above.
```
# use axum::response::IntoResponse;
# use activitypub_federation::axum::inbox::{ActivityData, receive_activity};
# use activitypub_federation::config::RequestData;
# use activitypub_federation::protocol::context::WithContext;
# use activitypub_federation::traits::ActivityHandler;
# use activitypub_federation::traits::tests::{DbConnection, DbUser, Follow};
# use serde::{Deserialize, Serialize};
# use url::Url;
#[derive(Deserialize, Serialize, Debug)]
#[serde(untagged)]
#[enum_delegate::implement(ActivityHandler)]
pub enum PersonAcceptedActivities {
Follow(Follow),
}
async fn http_post_user_inbox(
data: RequestData<DbConnection>,
activity_data: ActivityData,
) -> impl IntoResponse {
receive_activity::<WithContext<PersonAcceptedActivities>, DbUser, DbConnection>(
activity_data,
&data,
)
.await.unwrap()
}
```
The `PersonAcceptedActivities` works by attempting to parse the received JSON data with each variant in order. The first variant which parses without errors is used for receiving. This means you should avoid defining multiple activities in a way that they might conflict and parse the same data.
Activity enums can also be nested.

47
docs/09_sending_activities.md Normal file
View file

@ -0,0 +1,47 @@
## Sending activities
To send an activity we need to initialize our previously defined struct, and pick an actor for sending. We also need a list of all actors that should receive the activity.
```
# use activitypub_federation::config::FederationConfig;
# use activitypub_federation::activity_queue::send_activity;
# use activitypub_federation::http_signatures::generate_actor_keypair;
# use activitypub_federation::traits::Actor;
# use activitypub_federation::fetch::object_id::ObjectId;
# use activitypub_federation::traits::tests::{DB_USER, DbConnection, Follow};
# let _ = actix_rt::System::new();
# actix_rt::Runtime::new().unwrap().block_on(async {
# let db_connection = DbConnection;
# let config = FederationConfig::builder()
# .domain("example.com")
# .app_data(db_connection)
# .build()?;
# let data = config.to_request_data();
# let recipient = DB_USER.clone();
// Each actor has a keypair. Generate it on signup and store it in the database.
let keypair = generate_actor_keypair()?;
let activity = Follow {
actor: ObjectId::new("https://lemmy.ml/u/nutomic")?,
object: recipient.apub_id.clone().into(),
kind: Default::default(),
id: "https://lemmy.ml/activities/321".try_into()?
};
let inboxes = vec![recipient.shared_inbox_or_inbox()];
send_activity(activity, keypair.private_key, inboxes, &data).await?;
# Ok::<(), anyhow::Error>(())
# }).unwrap()
```
The list of inboxes gets deduplicated (important for shared inbox). All inboxes on the local
domain and those which fail the [crate::config::UrlVerifier] check are excluded from delivery.
For each remaining inbox a background tasks is created. It signs the HTTP header with the given
private key. Finally the activity is delivered to the inbox.
It is possible that delivery fails because the target instance is temporarily unreachable. In
this case the task is scheduled for retry after a certain waiting time. For each task delivery
is retried up to 3 times after the initial attempt. The retry intervals are as follows:
- one minute, in case of service restart
- one hour, in case of instance maintenance
- 2.5 days, in case of major incident with rebuild from backup
In case [crate::config::FederationConfigBuilder::debug] is enabled, no background thread is used but activities are sent directly on the foreground. This makes it easier to catch delivery errors and avoids complicated steps to await delivery in tests.

76
docs/10_fetching_objects_with_unknown_type.md Normal file
View file

@ -0,0 +1,76 @@
## Fetching remote object with unknown type
It is sometimes necessary to fetch from a URL, but we don't know the exact type of object it will return. An example is the search field in most federated platforms, which allows pasting and `id` URL and fetches it from the origin server. It can be implemented in the following way:
```no_run
# use activitypub_federation::traits::tests::{DbUser, DbPost};
# use activitypub_federation::fetch::object_id::ObjectId;
# use activitypub_federation::traits::ApubObject;
# use activitypub_federation::config::FederationConfig;
# use serde::{Deserialize, Serialize};
# use activitypub_federation::traits::tests::DbConnection;
# use activitypub_federation::config::RequestData;
# use url::Url;
# use activitypub_federation::traits::tests::{Person, Note};
pub enum SearchableDbObjects {
User(DbUser),
Post(DbPost)
}
#[derive(Deserialize, Serialize)]
#[serde(untagged)]
pub enum SearchableApubObjects {
Person(Person),
Note(Note)
}
#[async_trait::async_trait]
impl ApubObject for SearchableDbObjects {
type DataType = DbConnection;
type ApubType = SearchableApubObjects;
type Error = anyhow::Error;
async fn read_from_apub_id(
object_id: Url,
data: &RequestData<Self::DataType>,
) -> Result<Option<Self>, Self::Error> {
Ok(None)
}
async fn into_apub(
self,
data: &RequestData<Self::DataType>,
) -> Result<Self::ApubType, Self::Error> {
unimplemented!();
}
async fn from_apub(
apub: Self::ApubType,
data: &RequestData<Self::DataType>,
) -> Result<Self, Self::Error> {
use SearchableDbObjects::*;
match apub {
SearchableApubObjects::Person(p) => Ok(User(DbUser::from_apub(p, data).await?)),
SearchableApubObjects::Note(n) => Ok(Post(DbPost::from_apub(n, data).await?)),
}
}
}
#[actix_rt::main]
async fn main() -> Result<(), anyhow::Error> {
# let config = FederationConfig::builder().domain("example.com").app_data(DbConnection).build().unwrap();
# let data = config.to_request_data();
let query = "https://example.com/id/413";
let query_result = ObjectId::<SearchableDbObjects>::new(query)?
.dereference(&data)
.await?;
match query_result {
SearchableDbObjects::Post(post) => {} // retrieved object is a post
SearchableDbObjects::User(user) => {} // object is a user
};
Ok(())
}
```
This is similar to the way receiving activities are handled in the previous section. The remote JSON is fetched, and received using the first enum variant which can successfully deserialize the data.

2
examples/local_federation/activities/accept.rs
View file

@ -1,7 +1,7 @@
use crate::{activities::follow::Follow, instance::DatabaseHandle, objects::person::DbUser}; use crate::{activities::follow::Follow, instance::DatabaseHandle, objects::person::DbUser};
use activitypub_federation::{ use activitypub_federation::{
config::RequestData, config::RequestData,
core::object_id::ObjectId, fetch::object_id::ObjectId,
kinds::activity::AcceptType, kinds::activity::AcceptType,
traits::ActivityHandler, traits::ActivityHandler,
}; };

2
examples/local_federation/activities/create_post.rs
View file

@ -5,7 +5,7 @@ use crate::{
}; };
use activitypub_federation::{ use activitypub_federation::{
config::RequestData, config::RequestData,
core::object_id::ObjectId, fetch::object_id::ObjectId,
kinds::activity::CreateType, kinds::activity::CreateType,
protocol::helpers::deserialize_one_or_many, protocol::helpers::deserialize_one_or_many,
traits::{ActivityHandler, ApubObject}, traits::{ActivityHandler, ApubObject},

2
examples/local_federation/activities/follow.rs
View file

@ -6,7 +6,7 @@ use crate::{
}; };
use activitypub_federation::{ use activitypub_federation::{
config::RequestData, config::RequestData,
core::object_id::ObjectId, fetch::object_id::ObjectId,
kinds::activity::FollowType, kinds::activity::FollowType,
traits::{ActivityHandler, Actor}, traits::{ActivityHandler, Actor},
}; };

4
examples/local_federation/actix_web/http.rs
View file

@ -4,11 +4,11 @@ use crate::{
objects::person::{DbUser, PersonAcceptedActivities}, objects::person::{DbUser, PersonAcceptedActivities},
}; };
use activitypub_federation::{ use activitypub_federation::{
actix_web::inbox::receive_activity,
config::{ApubMiddleware, FederationConfig, RequestData}, config::{ApubMiddleware, FederationConfig, RequestData},
core::actix_web::inbox::receive_activity, fetch::webfinger::{build_webfinger_response, extract_webfinger_name},
protocol::context::WithContext, protocol::context::WithContext,
traits::ApubObject, traits::ApubObject,
webfinger::{build_webfinger_response, extract_webfinger_name},
APUB_JSON_CONTENT_TYPE, APUB_JSON_CONTENT_TYPE,
}; };
use actix_web::{web, web::Bytes, App, HttpRequest, HttpResponse, HttpServer}; use actix_web::{web, web::Bytes, App, HttpRequest, HttpResponse, HttpServer};

7
examples/local_federation/axum/http.rs
View file

@ -4,11 +4,14 @@ use crate::{
objects::person::{DbUser, Person, PersonAcceptedActivities}, objects::person::{DbUser, Person, PersonAcceptedActivities},
}; };
use activitypub_federation::{ use activitypub_federation::{
axum::{
inbox::{receive_activity, ActivityData},
json::ApubJson,
},
config::{ApubMiddleware, FederationConfig, RequestData}, config::{ApubMiddleware, FederationConfig, RequestData},
core::axum::{inbox::receive_activity, json::ApubJson, ActivityData}, fetch::webfinger::{build_webfinger_response, extract_webfinger_name, Webfinger},
protocol::context::WithContext, protocol::context::WithContext,
traits::ApubObject, traits::ApubObject,
webfinger::{build_webfinger_response, extract_webfinger_name, Webfinger},
}; };
use axum::{ use axum::{
extract::{Path, Query}, extract::{Path, Query},

7
examples/local_federation/objects/person.rs
View file

@ -6,16 +6,13 @@ use crate::{
utils::generate_object_id, utils::generate_object_id,
}; };
use activitypub_federation::{ use activitypub_federation::{
config::RequestData,
core::{
activity_queue::send_activity, activity_queue::send_activity,
config::RequestData,
fetch::{object_id::ObjectId, webfinger::webfinger_resolve_actor},
http_signatures::generate_actor_keypair, http_signatures::generate_actor_keypair,
object_id::ObjectId,
},
kinds::actor::PersonType, kinds::actor::PersonType,
protocol::{context::WithContext, public_key::PublicKey}, protocol::{context::WithContext, public_key::PublicKey},
traits::{ActivityHandler, Actor, ApubObject}, traits::{ActivityHandler, Actor, ApubObject},
webfinger::webfinger_resolve_actor,
}; };
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
use std::fmt::Debug; use std::fmt::Debug;

2
examples/local_federation/objects/post.rs
View file

@ -1,7 +1,7 @@
use crate::{error::Error, generate_object_id, instance::DatabaseHandle, objects::person::DbUser}; use crate::{error::Error, generate_object_id, instance::DatabaseHandle, objects::person::DbUser};
use activitypub_federation::{ use activitypub_federation::{
config::RequestData, config::RequestData,
core::object_id::ObjectId, fetch::object_id::ObjectId,
kinds::{object::NoteType, public}, kinds::{object::NoteType, public},
protocol::helpers::deserialize_one_or_many, protocol::helpers::deserialize_one_or_many,
traits::ApubObject, traits::ApubObject,

58
src/core/activity_queue.rs → src/activity_queue.rs
View file

@ -1,9 +1,13 @@
//! Queue for signing and sending outgoing activities with retry
//!
#![doc = include_str!("../docs/09_sending_activities.md")]
use crate::{ use crate::{
config::RequestData, config::RequestData,
core::http_signatures::sign_request,
error::Error, error::Error,
http_signatures::sign_request,
reqwest_shim::ResponseExt,
traits::ActivityHandler, traits::ActivityHandler,
utils::reqwest_shim::ResponseExt,
APUB_JSON_CONTENT_TYPE, APUB_JSON_CONTENT_TYPE,
}; };
use anyhow::anyhow; use anyhow::anyhow;
@ -29,59 +33,13 @@ use std::{
use tracing::{debug, info, warn}; use tracing::{debug, info, warn};
use url::Url; use url::Url;
/// Signs and delivers outgoing activities with retry. /// Send a new activity to the given inboxes
///
/// The list of inboxes gets deduplicated (important for shared inbox). All inboxes on the local
/// domain and those which fail the [crate::config::UrlVerifier] check are excluded from delivery.
/// For each remaining inbox a background tasks is created. It signs the HTTP header with the given
/// private key. Finally the activity is delivered to the inbox.
///
/// It is possible that delivery fails because the target instance is temporarily unreachable. In
/// this case the task is scheduled for retry after a certain waiting time. For each task delivery
/// is retried up to 3 times after the initial attempt. The retry intervals are as follows:
/// - one minute, for service restart
/// - one hour, for instance maintenance
/// - 2.5 days, for major incident with rebuild from backup
///
/// In case [crate::config::FederationConfigBuilder::debug] is enabled, no background thread is used but activities
/// are sent directly on the foreground. This makes it easier to catch delivery errors and avoids
/// complicated steps to await delivery.
/// ///
/// - `activity`: The activity to be sent, gets converted to json /// - `activity`: The activity to be sent, gets converted to json
/// - `private_key`: Private key belonging to the actor who sends the activity, for signing HTTP /// - `private_key`: Private key belonging to the actor who sends the activity, for signing HTTP
/// signature. Generated with [crate::core::http_signatures::generate_actor_keypair]. /// signature. Generated with [crate::http_signatures::generate_actor_keypair].
/// - `inboxes`: List of actor inboxes that should receive the activity. Should be built by calling /// - `inboxes`: List of actor inboxes that should receive the activity. Should be built by calling
/// [crate::traits::Actor::shared_inbox_or_inbox] for each target actor. /// [crate::traits::Actor::shared_inbox_or_inbox] for each target actor.
///
/// ```
/// # use activitypub_federation::config::FederationConfig;
/// # use activitypub_federation::core::activity_queue::send_activity;
/// # use activitypub_federation::core::http_signatures::generate_actor_keypair;
/// # use activitypub_federation::traits::Actor;
/// # use activitypub_federation::core::object_id::ObjectId;
/// # use activitypub_federation::traits::tests::{DB_USER, DbConnection, Follow};
/// # let _ = actix_rt::System::new();
/// # actix_rt::Runtime::new().unwrap().block_on(async {
/// # let db_connection = DbConnection;
/// # let config = FederationConfig::builder()
/// # .domain("example.com")
/// # .app_data(db_connection)
/// # .build()?;
/// # let data = config.to_request_data();
/// # let recipient = DB_USER.clone();
/// // Each actor has a keypair. Generate it on signup and store it in the database.
/// let keypair = generate_actor_keypair()?;
/// let activity = Follow {
/// actor: ObjectId::new("https://lemmy.ml/u/nutomic")?,
/// object: recipient.apub_id.clone().into(),
/// kind: Default::default(),
/// id: "https://lemmy.ml/activities/321".try_into()?
/// };
/// let inboxes = vec![recipient.shared_inbox_or_inbox()];
/// send_activity(activity, keypair.private_key, inboxes, &data).await?;
/// # Ok::<(), anyhow::Error>(())
/// # }).unwrap()
/// ```
pub async fn send_activity<Activity, Datatype>( pub async fn send_activity<Activity, Datatype>(
activity: Activity, activity: Activity,
private_key: String, private_key: String,

10
src/core/actix_web/inbox.rs → src/actix_web/inbox.rs
View file

@ -1,10 +1,10 @@
//! Handles incoming activities, verifying HTTP signatures and other checks
use crate::{ use crate::{
config::RequestData, config::RequestData,
core::{
http_signatures::{verify_inbox_hash, verify_signature},
object_id::ObjectId,
},
error::Error, error::Error,
fetch::object_id::ObjectId,
http_signatures::{verify_inbox_hash, verify_signature},
traits::{ActivityHandler, Actor, ApubObject}, traits::{ActivityHandler, Actor, ApubObject},
}; };
use actix_web::{web::Bytes, HttpRequest, HttpResponse}; use actix_web::{web::Bytes, HttpRequest, HttpResponse};
@ -55,7 +55,7 @@ mod test {
use super::*; use super::*;
use crate::{ use crate::{
config::FederationConfig, config::FederationConfig,
core::http_signatures::sign_request, http_signatures::sign_request,
traits::tests::{DbConnection, DbUser, Follow, DB_USER_KEYPAIR}, traits::tests::{DbConnection, DbUser, Follow, DB_USER_KEYPAIR},
}; };
use actix_web::test::TestRequest; use actix_web::test::TestRequest;

0
src/core/actix_web/middleware.rs → src/actix_web/middleware.rs
View file

5
src/actix_web/mod.rs Normal file
View file

@ -0,0 +1,5 @@
//! Utilities for using this library with actix-web framework
pub mod inbox;
#[doc(hidden)]
pub mod middleware;

58
src/core/axum/inbox.rs → src/axum/inbox.rs
View file

@ -1,19 +1,26 @@
//! Handles incoming activities, verifying HTTP signatures and other checks
//!
#![doc = include_str!("../../docs/08_receiving_activities.md")]
use crate::{ use crate::{
config::RequestData, config::RequestData,
core::{
axum::ActivityData,
http_signatures::{verify_inbox_hash, verify_signature},
object_id::ObjectId,
},
error::Error, error::Error,
fetch::object_id::ObjectId,
http_signatures::{verify_inbox_hash, verify_signature},
traits::{ActivityHandler, Actor, ApubObject}, traits::{ActivityHandler, Actor, ApubObject},
}; };
use axum::{
async_trait,
body::{Bytes, HttpBody},
extract::FromRequest,
http::{Request, StatusCode},
response::{IntoResponse, Response},
};
use http::{HeaderMap, Method, Uri};
use serde::de::DeserializeOwned; use serde::de::DeserializeOwned;
use tracing::debug; use tracing::debug;
/// Handles incoming activities, verifying HTTP signatures and other checks /// Handles incoming activities, verifying HTTP signatures and other checks
///
/// After successful validation, activities are passed to respective [trait@ActivityHandler].
pub async fn receive_activity<Activity, ActorT, Datatype>( pub async fn receive_activity<Activity, ActorT, Datatype>(
activity_data: ActivityData, activity_data: ActivityData,
data: &RequestData<Datatype>, data: &RequestData<Datatype>,
@ -49,4 +56,41 @@ where
Ok(()) Ok(())
} }
/// Contains all data that is necessary to receive an activity from an HTTP request
#[derive(Debug)]
pub struct ActivityData {
headers: HeaderMap,
method: Method,
uri: Uri,
body: Vec<u8>,
}
#[async_trait]
impl<S, B> FromRequest<S, B> for ActivityData
where
Bytes: FromRequest<S, B>,
B: HttpBody + Send + 'static,
S: Send + Sync,
<B as HttpBody>::Error: std::fmt::Display,
<B as HttpBody>::Data: Send,
{
type Rejection = Response;
async fn from_request(req: Request<B>, _state: &S) -> Result<Self, Self::Rejection> {
let (parts, body) = req.into_parts();
// this wont work if the body is an long running stream
let bytes = hyper::body::to_bytes(body)
.await
.map_err(|err| (StatusCode::INTERNAL_SERVER_ERROR, err.to_string()).into_response())?;
Ok(Self {
headers: parts.headers,
method: parts.method,
uri: parts.uri,
body: bytes.to_vec(),
})
}
}
// TODO: copy tests from actix-web inbox and implement for axum as well // TODO: copy tests from actix-web inbox and implement for axum as well

34
src/core/axum/json.rs → src/axum/json.rs
View file

@ -1,25 +1,27 @@
//! Wrapper struct to respond with `application/activity+json` in axum handlers
//!
//! ```
//! # use anyhow::Error;
//! # use axum::extract::Path;
//! # use activitypub_federation::axum::json::ApubJson;
//! # use activitypub_federation::protocol::context::WithContext;
//! # use activitypub_federation::config::RequestData;
//! # use activitypub_federation::traits::ApubObject;
//! # use activitypub_federation::traits::tests::{DbConnection, DbUser, Person};
//! async fn http_get_user(Path(name): Path<String>, data: RequestData<DbConnection>) -> Result<ApubJson<WithContext<Person>>, Error> {
//! let user: DbUser = data.read_local_user(name).await?;
//! let person = user.into_apub(&data).await?;
//!
//! Ok(ApubJson(WithContext::new_default(person)))
//! }
//! ```
use crate::APUB_JSON_CONTENT_TYPE; use crate::APUB_JSON_CONTENT_TYPE;
use axum::response::IntoResponse; use axum::response::IntoResponse;
use http::header; use http::header;
use serde::Serialize; use serde::Serialize;
/// Wrapper struct to respond with `application/activity+json` in axum handlers /// Wrapper struct to respond with `application/activity+json` in axum handlers
///
/// ```
/// # use anyhow::Error;
/// # use axum::extract::Path;
/// # use activitypub_federation::core::axum::json::ApubJson;
/// # use activitypub_federation::protocol::context::WithContext;
/// # use activitypub_federation::config::RequestData;
/// # use activitypub_federation::traits::ApubObject;
/// # use activitypub_federation::traits::tests::{DbConnection, DbUser, Person};
/// async fn http_get_user(Path(name): Path<String>, data: RequestData<DbConnection>) -> Result<ApubJson<WithContext<Person>>, Error> {
/// let user: DbUser = data.read_local_user(name).await?;
/// let person = user.into_apub(&data).await?;
///
/// Ok(ApubJson(WithContext::new_default(person)))
/// }
/// ```
#[derive(Debug, Clone, Copy, Default)] #[derive(Debug, Clone, Copy, Default)]
pub struct ApubJson<Json: Serialize>(pub Json); pub struct ApubJson<Json: Serialize>(pub Json);

0
src/core/axum/middleware.rs → src/axum/middleware.rs
View file

8
src/axum/mod.rs Normal file
View file

@ -0,0 +1,8 @@
//! Utilities for using this library with axum web framework
//!
#![doc = include_str!("../../docs/06_http_endpoints_axum.md")]
pub mod inbox;
pub mod json;
#[doc(hidden)]
pub mod middleware;

45
src/config.rs
View file

@ -1,8 +1,24 @@
//! Configuration for this library, with various federation settings
//!
//! Use [FederationConfig::builder](crate::config::FederationConfig::builder) to initialize it.
//!
//! ```
//! # use activitypub_federation::config::FederationConfig;
//! # let _ = actix_rt::System::new();
//! let settings = FederationConfig::builder()
//! .domain("example.com")
//! .app_data(())
//! .http_fetch_limit(50)
//! .worker_count(16)
//! .build()?;
//! # Ok::<(), anyhow::Error>(())
//! ```
use crate::{ use crate::{
core::activity_queue::create_activity_queue, activity_queue::create_activity_queue,
error::Error, error::Error,
traits::ActivityHandler,
protocol::verification::verify_domains_match, protocol::verification::verify_domains_match,
traits::ActivityHandler,
}; };
use async_trait::async_trait; use async_trait::async_trait;
use background_jobs::Manager; use background_jobs::Manager;
@ -17,21 +33,7 @@ use std::{
}; };
use url::Url; use url::Url;
/// Various settings related to Activitypub federation. /// Configuration for this library, with various federation related settings
///
/// Use [FederationSettings.builder()] to initialize this.
///
/// ```
/// # use activitypub_federation::config::FederationConfig;
/// # let _ = actix_rt::System::new();
/// let settings = FederationConfig::builder()
/// .domain("example.com")
/// .app_data(())
/// .http_fetch_limit(50)
/// .worker_count(16)
/// .build()?;
/// # Ok::<(), anyhow::Error>(())
/// ```
#[derive(Builder, Clone)] #[derive(Builder, Clone)]
#[builder(build_fn(private, name = "partial_build"))] #[builder(build_fn(private, name = "partial_build"))]
pub struct FederationConfig<T: Clone> { pub struct FederationConfig<T: Clone> {
@ -42,7 +44,7 @@ pub struct FederationConfig<T: Clone> {
/// or configuration. /// or configuration.
pub(crate) app_data: T, pub(crate) app_data: T,
/// Maximum number of outgoing HTTP requests per incoming HTTP request. See /// Maximum number of outgoing HTTP requests per incoming HTTP request. See
/// [crate::utils::fetch_object_http] for more details. /// [crate::fetch::object_id::ObjectId] for more details.
#[builder(default = "20")] #[builder(default = "20")]
pub(crate) http_fetch_limit: i32, pub(crate) http_fetch_limit: i32,
#[builder(default = "reqwest::Client::default().into()")] #[builder(default = "reqwest::Client::default().into()")]
@ -54,8 +56,7 @@ pub struct FederationConfig<T: Clone> {
pub(crate) worker_count: u64, pub(crate) worker_count: u64,
/// Run library in debug mode. This allows usage of http and localhost urls. It also sends /// Run library in debug mode. This allows usage of http and localhost urls. It also sends
/// outgoing activities synchronously, not in background thread. This helps to make tests /// outgoing activities synchronously, not in background thread. This helps to make tests
/// more consistent. /// more consistent. Do not use for production.
/// Do not use for production.
#[builder(default = "false")] #[builder(default = "false")]
pub(crate) debug: bool, pub(crate) debug: bool,
/// Timeout for all HTTP requests. HTTP signatures are valid for 10s, so it makes sense to /// Timeout for all HTTP requests. HTTP signatures are valid for 10s, so it makes sense to
@ -246,7 +247,9 @@ clone_trait_object!(UrlVerifier);
/// Stores data for handling one specific HTTP request. /// Stores data for handling one specific HTTP request.
/// ///
/// Most importantly this contains a counter for outgoing HTTP requests. This is necessary to /// It gives acess to the `app_data` which was passed to [FederationConfig::builder].
///
/// Additionally it contains a counter for outgoing HTTP requests. This is necessary to
/// prevent denial of service attacks, where an attacker triggers fetching of recursive objects. /// prevent denial of service attacks, where an attacker triggers fetching of recursive objects.
/// ///
/// <https://www.w3.org/TR/activitypub/#security-recursive-objects> /// <https://www.w3.org/TR/activitypub/#security-recursive-objects>

4
src/core/actix_web/mod.rs
View file

@ -1,4 +0,0 @@
/// Handles incoming activities, verifying HTTP signatures and other checks
pub mod inbox;
#[doc(hidden)]
pub mod middleware;

53
src/core/axum/mod.rs
View file

@ -1,53 +0,0 @@
use axum::{
async_trait,
body::{Bytes, HttpBody},
extract::FromRequest,
http::{Request, StatusCode},
response::{IntoResponse, Response},
};
use http::{HeaderMap, Method, Uri};
/// Handles incoming activities, verifying HTTP signatures and other checks
pub mod inbox;
/// Wrapper struct to respond with `application/activity+json` in axum handlers
pub mod json;
#[doc(hidden)]
pub mod middleware;
/// Contains everything that is necessary to verify HTTP signatures and receive an
/// activity, including the request body.
#[derive(Debug)]
pub struct ActivityData {
headers: HeaderMap,
method: Method,
uri: Uri,
body: Vec<u8>,
}
#[async_trait]
impl<S, B> FromRequest<S, B> for ActivityData
where
Bytes: FromRequest<S, B>,
B: HttpBody + Send + 'static,
S: Send + Sync,
<B as HttpBody>::Error: std::fmt::Display,
<B as HttpBody>::Data: Send,
{
type Rejection = Response;
async fn from_request(req: Request<B>, _state: &S) -> Result<Self, Self::Rejection> {
let (parts, body) = req.into_parts();
// this wont work if the body is an long running stream
let bytes = hyper::body::to_bytes(body)
.await
.map_err(|err| (StatusCode::INTERNAL_SERVER_ERROR, err.to_string()).into_response())?;
Ok(Self {
headers: parts.headers,
method: parts.method,
uri: parts.uri,
body: bytes.to_vec(),
})
}
}

14
src/core/mod.rs
View file

@ -1,14 +0,0 @@
/// Queue for sending outgoing activities
pub mod activity_queue;
/// Everything related to creation and verification of HTTP signatures, used to authenticate activities
pub mod http_signatures;
/// Typed wrapper for Activitypub Object ID which helps with dereferencing and caching
pub mod object_id;
/// Utilities for using this library with axum web framework
#[cfg(feature = "axum")]
pub mod axum;
/// Utilities for using this library with actix-web framework
#[cfg(feature = "actix-web")]
pub mod actix_web;

4
src/error.rs
View file

@ -1,6 +1,8 @@
//! Error messages returned by this library
use displaydoc::Display; use displaydoc::Display;
/// Error messages returned by this library. /// Error messages returned by this library
#[derive(thiserror::Error, Debug, Display)] #[derive(thiserror::Error, Debug, Display)]
pub enum Error { pub enum Error {
/// Object was not found in local database /// Object was not found in local database

20
src/utils/mod.rs → src/fetch/mod.rs
View file

@ -1,20 +1,22 @@
use crate::{ //! Utilities for fetching data from other servers
config::RequestData, //!
error::Error, #![doc = include_str!("../../docs/07_fetching_data.md")]
utils::reqwest_shim::ResponseExt,
APUB_JSON_CONTENT_TYPE, use crate::{config::RequestData, error::Error, reqwest_shim::ResponseExt, APUB_JSON_CONTENT_TYPE};
};
use http::StatusCode; use http::StatusCode;
use serde::de::DeserializeOwned; use serde::de::DeserializeOwned;
use std::sync::atomic::Ordering; use std::sync::atomic::Ordering;
use tracing::info; use tracing::info;
use url::Url; use url::Url;
pub(crate) mod reqwest_shim; /// Typed wrapper for Activitypub Object ID which helps with dereferencing and caching
pub mod object_id;
/// Resolves identifiers of the form `name@example.com`
pub mod webfinger;
/// Fetch a remote object over HTTP and convert to `Kind`. /// Fetch a remote object over HTTP and convert to `Kind`.
/// ///
/// [crate::core::object_id::ObjectId::dereference] wraps this function to add caching and /// [crate::fetch::object_id::ObjectId::dereference] wraps this function to add caching and
/// conversion to database type. Only use this function directly in exceptional cases where that /// conversion to database type. Only use this function directly in exceptional cases where that
/// behaviour is undesired. /// behaviour is undesired.
/// ///
@ -22,7 +24,7 @@ pub(crate) mod reqwest_shim;
/// If the value exceeds [FederationSettings.http_fetch_limit], the request is aborted with /// If the value exceeds [FederationSettings.http_fetch_limit], the request is aborted with
/// [Error::RequestLimit]. This prevents denial of service attacks where an attack triggers /// [Error::RequestLimit]. This prevents denial of service attacks where an attack triggers
/// infinite, recursive fetching of data. /// infinite, recursive fetching of data.
pub async fn fetch_object_http<T: Clone, Kind: DeserializeOwned>( async fn fetch_object_http<T: Clone, Kind: DeserializeOwned>(
url: &Url, url: &Url,
data: &RequestData<T>, data: &RequestData<T>,
) -> Result<Kind, Error> { ) -> Result<Kind, Error> {

6
src/core/object_id.rs → src/fetch/object_id.rs
View file

@ -1,4 +1,4 @@
use crate::{config::RequestData, error::Error, traits::ApubObject, utils::fetch_object_http}; use crate::{config::RequestData, error::Error, fetch::fetch_object_http, traits::ApubObject};
use anyhow::anyhow; use anyhow::anyhow;
use chrono::{Duration as ChronoDuration, NaiveDateTime, Utc}; use chrono::{Duration as ChronoDuration, NaiveDateTime, Utc};
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
@ -20,7 +20,7 @@ use url::Url;
/// infinite, recursive fetching of data. /// infinite, recursive fetching of data.
/// ///
/// ``` /// ```
/// # use activitypub_federation::core::object_id::ObjectId; /// # use activitypub_federation::fetch::object_id::ObjectId;
/// # use activitypub_federation::config::FederationConfig; /// # use activitypub_federation::config::FederationConfig;
/// # use activitypub_federation::error::Error::NotFound; /// # use activitypub_federation::error::Error::NotFound;
/// # use activitypub_federation::traits::tests::{DbConnection, DbUser}; /// # use activitypub_federation::traits::tests::{DbConnection, DbUser};
@ -233,7 +233,7 @@ where
#[cfg(test)] #[cfg(test)]
pub mod tests { pub mod tests {
use super::*; use super::*;
use crate::{core::object_id::should_refetch_object, traits::tests::DbUser}; use crate::{fetch::object_id::should_refetch_object, traits::tests::DbUser};
#[test] #[test]
fn test_deserialize() { fn test_deserialize() {

5
src/webfinger.rs → src/fetch/webfinger.rs
View file

@ -1,9 +1,8 @@
use crate::{ use crate::{
config::RequestData, config::RequestData,
core::object_id::ObjectId,
error::{Error, Error::WebfingerResolveFailed}, error::{Error, Error::WebfingerResolveFailed},
fetch::{fetch_object_http, object_id::ObjectId},
traits::{Actor, ApubObject}, traits::{Actor, ApubObject},
utils::fetch_object_http,
APUB_JSON_CONTENT_TYPE, APUB_JSON_CONTENT_TYPE,
}; };
use anyhow::anyhow; use anyhow::anyhow;
@ -90,7 +89,7 @@ where
/// ///
/// ``` /// ```
/// # use url::Url; /// # use url::Url;
/// # use activitypub_federation::webfinger::build_webfinger_response; /// # use activitypub_federation::fetch::webfinger::build_webfinger_response;
/// let subject = "acct:nutomic@lemmy.ml".to_string(); /// let subject = "acct:nutomic@lemmy.ml".to_string();
/// let url = Url::parse("https://lemmy.ml/u/nutomic")?; /// let url = Url::parse("https://lemmy.ml/u/nutomic")?;
/// build_webfinger_response(subject, url); /// build_webfinger_response(subject, url);

9
src/core/http_signatures.rs → src/http_signatures.rs
View file

@ -1,3 +1,10 @@
//! Generating keypairs, creating and verifying signatures
//!
//! Signature creation and verification is handled internally in the library. See
//! [send_activity](crate::activity_queue::send_activity) and
//! [receive_activity (actix-web)](crate::actix_web::inbox::receive_activity) /
//! [receive_activity (axum)](crate::axum::inbox::receive_activity).
use crate::{ use crate::{
error::{Error, Error::ActivitySignatureInvalid}, error::{Error, Error::ActivitySignatureInvalid},
protocol::public_key::main_key_id, protocol::public_key::main_key_id,
@ -87,7 +94,7 @@ static CONFIG2: Lazy<http_signature_normalization::Config> =
Lazy::new(http_signature_normalization::Config::new); Lazy::new(http_signature_normalization::Config::new);
/// Verifies the HTTP signature on an incoming inbox request. /// Verifies the HTTP signature on an incoming inbox request.
pub fn verify_signature<'a, H>( pub(crate) fn verify_signature<'a, H>(
headers: H, headers: H,
method: &Method, method: &Method,
uri: &Uri, uri: &Uri,

31
src/lib.rs
View file

@ -1,22 +1,29 @@
#![doc = include_str!("../README.md")] #![doc = include_str!("../docs/01_intro.md")]
#![doc = include_str!("../docs/02_overview.md")]
#![doc = include_str!("../docs/03_federating_users.md")]
#![doc = include_str!("../docs/04_federating_posts.md")]
#![doc = include_str!("../docs/05_configuration.md")]
#![doc = include_str!("../docs/06_http_endpoints_axum.md")]
#![doc = include_str!("../docs/07_fetching_data.md")]
#![doc = include_str!("../docs/08_receiving_activities.md")]
#![doc = include_str!("../docs/09_sending_activities.md")]
#![doc = include_str!("../docs/10_fetching_objects_with_unknown_type.md")]
#![deny(missing_docs)] #![deny(missing_docs)]
/// Configuration for this library pub mod activity_queue;
#[cfg(feature = "actix-web")]
pub mod actix_web;
#[cfg(feature = "axum")]
pub mod axum;
pub mod config; pub mod config;
/// Contains main library functionality
pub mod core;
/// Error messages returned by this library.
pub mod error; pub mod error;
/// Data structures which help to define federated messages pub mod fetch;
pub mod http_signatures;
pub mod protocol; pub mod protocol;
/// Traits which need to be implemented for federated data types pub(crate) mod reqwest_shim;
pub mod traits; pub mod traits;
/// Some utility functions
pub mod utils;
/// Resolves identifiers of the form `name@example.com`
pub mod webfinger;
pub use activitystreams_kinds as kinds; pub use activitystreams_kinds as kinds;
/// Mime type for Activitypub, used for `Accept` and `Content-Type` HTTP headers /// Mime type for Activitypub data, used for `Accept` and `Content-Type` HTTP headers
pub static APUB_JSON_CONTENT_TYPE: &str = "application/activity+json"; pub static APUB_JSON_CONTENT_TYPE: &str = "application/activity+json";

40
src/protocol/context.rs
View file

@ -1,3 +1,24 @@
//! Wrapper for federated structs which handles `@context` field.
//!
//! This wrapper can be used when sending Activitypub data, to automatically add `@context`. It
//! avoids having to repeat the `@context` property on every struct, and getting multiple contexts
//! in nested structs.
//!
//! ```
//! # use activitypub_federation::protocol::context::WithContext;
//! #[derive(serde::Serialize)]
//! struct Note {
//! content: String
//! }
//! let note = Note {
//! content: "Hello world".to_string()
//! };
//! let note_with_context = WithContext::new_default(note);
//! let serialized = serde_json::to_string(&note_with_context)?;
//! assert_eq!(serialized, r#"{"@context":[["https://www.w3.org/ns/activitystreams"]],"content":"Hello world"}"#);
//! Ok::<(), serde_json::error::Error>(())
//! ```
use crate::{ use crate::{
config::RequestData, config::RequestData,
protocol::helpers::deserialize_one_or_many, protocol::helpers::deserialize_one_or_many,
@ -12,25 +33,6 @@ use url::Url;
const DEFAULT_CONTEXT: &str = "[\"https://www.w3.org/ns/activitystreams\"]"; const DEFAULT_CONTEXT: &str = "[\"https://www.w3.org/ns/activitystreams\"]";
/// Wrapper for federated structs which handles `@context` field. /// Wrapper for federated structs which handles `@context` field.
///
/// This wrapper can be used when sending Activitypub data, to automatically add `@context`. It
/// avoids having to repeat the `@context` property on every struct, and getting multiple contexts
/// in nested structs.
///
/// ```
/// # use activitypub_federation::protocol::context::WithContext;
/// #[derive(serde::Serialize)]
/// struct Note {
/// content: String
/// }
/// let note = Note {
/// content: "Hello world".to_string()
/// };
/// let note_with_context = WithContext::new_default(note);
/// let serialized = serde_json::to_string(&note_with_context)?;
/// assert_eq!(serialized, r#"{"@context":[["https://www.w3.org/ns/activitystreams"]],"content":"Hello world"}"#);
/// Ok::<(), serde_json::error::Error>(())
/// ```
#[derive(Serialize, Deserialize, Debug)] #[derive(Serialize, Deserialize, Debug)]
pub struct WithContext<T> { pub struct WithContext<T> {
#[serde(rename = "@context")] #[serde(rename = "@context")]

2
src/protocol/helpers.rs
View file

@ -1,3 +1,5 @@
//! Serde deserialization functions which help to receive differently shaped data
use serde::{Deserialize, Deserializer}; use serde::{Deserialize, Deserializer};
/// Deserialize JSON single value or array into Vec. /// Deserialize JSON single value or array into Vec.

6
src/protocol/mod.rs
View file

@ -1,9 +1,7 @@
/// Wrapper for federated structs which handles `@context` field //! Data structures which help to define federated messages
pub mod context; pub mod context;
/// Serde deserialization functions which help to receive differently shaped data
pub mod helpers; pub mod helpers;
/// Struct which is used to federate actor key for HTTP signatures
pub mod public_key; pub mod public_key;
pub mod values; pub mod values;
/// Verify that received data is valid
pub mod verification; pub mod verification;

2
src/protocol/public_key.rs
View file

@ -1,3 +1,5 @@
//! Struct which is used to federate actor key for HTTP signatures
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
use url::Url; use url::Url;

11
src/protocol/values.rs
View file

@ -1,13 +1,9 @@
//! Single value enums used to receive JSON with specific expected string values
//!
//! The enums here serve to limit a json string value to a single, hardcoded value which can be //! The enums here serve to limit a json string value to a single, hardcoded value which can be
//! verified at compilation time. When using it as the type of a struct field, the struct can only //! verified at compilation time. When using it as the type of a struct field, the struct can only
//! be constructed or deserialized if the field has the exact same value. //! be constructed or deserialized if the field has the exact same value.
//! //!
//! If we used String as the field type, any value would be accepted, and we would have to check
//! manually at runtime that it contains the expected value.
//!
//! The enums in `activitystreams::activity::kind` work in the same way, and can be used to
//! distinguish different activity types.
//!
//! In the example below, `MyObject` can only be constructed or //! In the example below, `MyObject` can only be constructed or
//! deserialized if `media_type` is `text/markdown`, but not if it is `text/html`. //! deserialized if `media_type` is `text/markdown`, but not if it is `text/html`.
//! //!
@ -30,6 +26,9 @@
//! let from_html = from_str::<MyObject>(markdown_html); //! let from_html = from_str::<MyObject>(markdown_html);
//! assert!(from_html.is_err()); //! assert!(from_html.is_err());
//! ``` //! ```
//!
//! The enums in [activitystreams_kinds] work in the same way, and can be used to
//! distinguish different activity types.
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};

10
src/protocol/verification.rs
View file

@ -1,13 +1,13 @@
use crate::{ //! Verify that received data is valid
error::Error,
}; use crate::error::Error;
use url::Url; use url::Url;
/// Check that both urls have the same domain. If not, return UrlVerificationError. /// Check that both urls have the same domain. If not, return UrlVerificationError.
/// ///
/// ``` /// ```
/// # use url::Url; /// # use url::Url;
/// # use activitypub_federation::utils::verify_domains_match; /// # use activitypub_federation::protocol::verification::verify_domains_match;
/// let a = Url::parse("https://example.com/abc")?; /// let a = Url::parse("https://example.com/abc")?;
/// let b = Url::parse("https://sample.net/abc")?; /// let b = Url::parse("https://sample.net/abc")?;
/// assert!(verify_domains_match(&a, &b).is_err()); /// assert!(verify_domains_match(&a, &b).is_err());
@ -24,7 +24,7 @@ pub fn verify_domains_match(a: &Url, b: &Url) -> Result<(), Error> {
/// ///
/// ``` /// ```
/// # use url::Url; /// # use url::Url;
/// # use activitypub_federation::utils::verify_urls_match; /// # use activitypub_federation::protocol::verification::verify_urls_match;
/// let a = Url::parse("https://example.com/abc")?; /// let a = Url::parse("https://example.com/abc")?;
/// let b = Url::parse("https://example.com/123")?; /// let b = Url::parse("https://example.com/123")?;
/// assert!(verify_urls_match(&a, &b).is_err()); /// assert!(verify_urls_match(&a, &b).is_err());

0
src/utils/reqwest_shim.rs → src/reqwest_shim.rs
View file

8
src/traits.rs
View file

@ -1,3 +1,5 @@
//! Traits which need to be implemented for federated data types
use crate::config::RequestData; use crate::config::RequestData;
use async_trait::async_trait; use async_trait::async_trait;
use chrono::NaiveDateTime; use chrono::NaiveDateTime;
@ -124,7 +126,7 @@ pub trait ApubObject: Sized {
/// ``` /// ```
/// # use activitystreams_kinds::activity::FollowType; /// # use activitystreams_kinds::activity::FollowType;
/// # use url::Url; /// # use url::Url;
/// # use activitypub_federation::core::object_id::ObjectId; /// # use activitypub_federation::fetch::object_id::ObjectId;
/// # use activitypub_federation::config::RequestData; /// # use activitypub_federation::config::RequestData;
/// # use activitypub_federation::traits::ActivityHandler; /// # use activitypub_federation::traits::ActivityHandler;
/// # use activitypub_federation::traits::tests::{DbConnection, DbUser}; /// # use activitypub_federation::traits::tests::{DbConnection, DbUser};
@ -229,10 +231,8 @@ where
pub mod tests { pub mod tests {
use super::*; use super::*;
use crate::{ use crate::{
core::{ fetch::object_id::ObjectId,
http_signatures::{generate_actor_keypair, Keypair}, http_signatures::{generate_actor_keypair, Keypair},
object_id::ObjectId,
},
protocol::public_key::PublicKey, protocol::public_key::PublicKey,
}; };
use activitystreams_kinds::{activity::FollowType, actor::PersonType}; use activitystreams_kinds::{activity::FollowType, actor::PersonType};