├── .github └── CODEOWNERS ├── examples ├── live_federation │ ├── activities │ │ ├── mod.rs │ │ └── create_post.rs │ ├── objects │ │ ├── mod.rs │ │ ├── post.rs │ │ └── person.rs │ ├── error.rs │ ├── utils.rs │ ├── database.rs │ ├── http.rs │ └── main.rs ├── local_federation │ ├── objects │ │ ├── mod.rs │ │ ├── post.rs │ │ └── person.rs │ ├── activities │ │ ├── mod.rs │ │ ├── accept.rs │ │ ├── create_post.rs │ │ └── follow.rs │ ├── actix_web │ │ ├── mod.rs │ │ └── http.rs │ ├── axum │ │ ├── mod.rs │ │ └── http.rs │ ├── error.rs │ ├── utils.rs │ ├── main.rs │ └── instance.rs └── README.md ├── .rustfmt.toml ├── .gitignore ├── src ├── protocol │ ├── mod.rs │ ├── tombstone.rs │ ├── public_key.rs │ ├── values.rs │ ├── context.rs │ ├── verification.rs │ └── helpers.rs ├── axum │ ├── mod.rs │ ├── json.rs │ ├── middleware.rs │ └── inbox.rs ├── actix_web │ ├── http_compat.rs │ ├── mod.rs │ ├── response.rs │ ├── middleware.rs │ └── inbox.rs ├── lib.rs ├── fetch │ ├── collection_id.rs │ ├── mod.rs │ ├── object_id.rs │ └── webfinger.rs ├── reqwest_shim.rs ├── error.rs ├── traits │ ├── either.rs │ ├── tests.rs │ └── mod.rs └── activity_sending.rs ├── docs ├── 05_configuration.md ├── 04_federating_posts.md ├── 02_overview.md ├── 07_fetching_data.md ├── 01_intro.md ├── 10_fetching_objects_with_unknown_type.md ├── 09_sending_activities.md ├── 08_receiving_activities.md ├── 06_http_endpoints_axum.md └── 03_federating_users.md ├── .woodpecker.yml ├── README.md └── Cargo.toml /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @Nutomic @dessalines 2 | -------------------------------------------------------------------------------- /examples/live_federation/activities/mod.rs: -------------------------------------------------------------------------------- 1 | pub mod create_post; 2 | -------------------------------------------------------------------------------- /examples/live_federation/objects/mod.rs: -------------------------------------------------------------------------------- 1 | pub mod person; 2 | pub mod post; 3 | -------------------------------------------------------------------------------- /examples/local_federation/objects/mod.rs: -------------------------------------------------------------------------------- 1 | pub mod person; 2 | pub mod post; 3 | -------------------------------------------------------------------------------- /examples/local_federation/activities/mod.rs: -------------------------------------------------------------------------------- 1 | pub mod accept; 2 | pub mod create_post; 3 | pub mod follow; 4 | -------------------------------------------------------------------------------- /.rustfmt.toml: -------------------------------------------------------------------------------- 1 | edition = "2021" 2 | imports_layout = "HorizontalVertical" 3 | imports_granularity = "Crate" 4 | reorder_imports = true 5 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /target 2 | /.idea 3 | perf.data* 4 | flamegraph.svg 5 | 6 | # direnv 7 | /.direnv 8 | /.envrc 9 | 10 | # nix flake 11 | /flake.nix 12 | /flake.lock 13 | -------------------------------------------------------------------------------- /examples/local_federation/actix_web/mod.rs: -------------------------------------------------------------------------------- 1 | use crate::error::Error; 2 | use actix_web::ResponseError; 3 | 4 | pub(crate) mod http; 5 | 6 | impl ResponseError for Error {} 7 | -------------------------------------------------------------------------------- /src/protocol/mod.rs: -------------------------------------------------------------------------------- 1 | //! Data structures which help to define federated messages 2 | 3 | pub mod context; 4 | pub mod helpers; 5 | pub mod public_key; 6 | pub mod tombstone; 7 | pub mod values; 8 | pub mod verification; 9 | -------------------------------------------------------------------------------- /src/axum/mod.rs: -------------------------------------------------------------------------------- 1 | //! Utilities for using this library with axum web framework 2 | //! 3 | #![doc = include_str!("../../docs/06_http_endpoints_axum.md")] 4 | 5 | pub mod inbox; 6 | pub mod json; 7 | #[doc(hidden)] 8 | pub mod middleware; 9 | -------------------------------------------------------------------------------- /examples/local_federation/axum/mod.rs: -------------------------------------------------------------------------------- 1 | use crate::error::Error; 2 | use ::http::StatusCode; 3 | use axum::response::{IntoResponse, Response}; 4 | 5 | #[allow(clippy::diverging_sub_expression, clippy::items_after_statements)] 6 | pub mod http; 7 | 8 | impl IntoResponse for Error { 9 | fn into_response(self) -> Response { 10 | (StatusCode::INTERNAL_SERVER_ERROR, format!("{}", self.0)).into_response() 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /examples/live_federation/error.rs: -------------------------------------------------------------------------------- 1 | use std::fmt::{Display, Formatter}; 2 | 3 | /// Necessary because of this issue: https://github.com/actix/actix-web/issues/1711 4 | #[derive(Debug)] 5 | pub struct Error(pub(crate) anyhow::Error); 6 | 7 | impl Display for Error { 8 | fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result { 9 | std::fmt::Display::fmt(&self.0, f) 10 | } 11 | } 12 | 13 | impl From for Error 14 | where 15 | T: Into, 16 | { 17 | fn from(t: T) -> Self { 18 | Error(t.into()) 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /examples/local_federation/error.rs: -------------------------------------------------------------------------------- 1 | use std::fmt::{Display, Formatter}; 2 | 3 | /// Necessary because of this issue: https://github.com/actix/actix-web/issues/1711 4 | #[derive(Debug)] 5 | pub struct Error(pub(crate) anyhow::Error); 6 | 7 | impl Display for Error { 8 | fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result { 9 | std::fmt::Display::fmt(&self.0, f) 10 | } 11 | } 12 | 13 | impl From for Error 14 | where 15 | T: Into, 16 | { 17 | fn from(t: T) -> Self { 18 | Error(t.into()) 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /examples/live_federation/utils.rs: -------------------------------------------------------------------------------- 1 | use rand::{distributions::Alphanumeric, thread_rng, Rng}; 2 | use url::{ParseError, Url}; 3 | 4 | /// Just generate random url as object id. In a real project, you probably want to use 5 | /// an url which contains the database id for easy retrieval (or store the random id in db). 6 | pub fn generate_object_id(domain: &str) -> Result { 7 | let id: String = thread_rng() 8 | .sample_iter(&Alphanumeric) 9 | .take(7) 10 | .map(char::from) 11 | .collect(); 12 | Url::parse(&format!("https://{}/objects/{}", domain, id)) 13 | } 14 | -------------------------------------------------------------------------------- /examples/local_federation/utils.rs: -------------------------------------------------------------------------------- 1 | use rand::{distributions::Alphanumeric, thread_rng, Rng}; 2 | use url::{ParseError, Url}; 3 | 4 | /// Just generate random url as object id. In a real project, you probably want to use 5 | /// an url which contains the database id for easy retrieval (or store the random id in db). 6 | pub fn generate_object_id(domain: &str) -> Result { 7 | let id: String = thread_rng() 8 | .sample_iter(&Alphanumeric) 9 | .take(7) 10 | .map(char::from) 11 | .collect(); 12 | Url::parse(&format!("http://{}/objects/{}", domain, id)) 13 | } 14 | -------------------------------------------------------------------------------- /examples/live_federation/database.rs: -------------------------------------------------------------------------------- 1 | use crate::{objects::person::DbUser, Error}; 2 | use anyhow::anyhow; 3 | use std::sync::{Arc, Mutex}; 4 | 5 | pub type DatabaseHandle = Arc; 6 | 7 | /// Our "database" which contains all known users (local and federated) 8 | pub struct Database { 9 | pub users: Mutex>, 10 | } 11 | 12 | impl Database { 13 | pub fn local_user(&self) -> DbUser { 14 | let lock = self.users.lock().unwrap(); 15 | lock.first().unwrap().clone() 16 | } 17 | 18 | pub fn read_user(&self, name: &str) -> Result { 19 | let db_user = self.local_user(); 20 | if name == db_user.name { 21 | Ok(db_user) 22 | } else { 23 | Err(anyhow!("Invalid user {name}").into()) 24 | } 25 | } 26 | } 27 | -------------------------------------------------------------------------------- /src/protocol/tombstone.rs: -------------------------------------------------------------------------------- 1 | //! Tombstone is used to serve deleted objects 2 | 3 | use crate::kinds::object::TombstoneType; 4 | use serde::{Deserialize, Serialize}; 5 | use url::Url; 6 | 7 | /// Represents a local object that was deleted 8 | /// 9 | /// 10 | #[derive(Clone, Debug, Deserialize, Serialize)] 11 | #[serde(rename_all = "camelCase")] 12 | pub struct Tombstone { 13 | /// Id of the deleted object 14 | pub id: Url, 15 | #[serde(rename = "type")] 16 | pub(crate) kind: TombstoneType, 17 | } 18 | 19 | impl Tombstone { 20 | /// Create a new tombstone for the given object id 21 | pub fn new(id: Url) -> Tombstone { 22 | Tombstone { 23 | id, 24 | kind: TombstoneType::Tombstone, 25 | } 26 | } 27 | } 28 | -------------------------------------------------------------------------------- /docs/05_configuration.md: -------------------------------------------------------------------------------- 1 | ## Configuration 2 | 3 | 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. 4 | 5 | ``` 6 | # use activitypub_federation::config::FederationConfig; 7 | # let db_connection = (); 8 | # tokio::runtime::Runtime::new().unwrap().block_on(async { 9 | let config = FederationConfig::builder() 10 | .domain("example.com") 11 | .app_data(db_connection) 12 | .build().await?; 13 | # Ok::<(), anyhow::Error>(()) 14 | # }).unwrap() 15 | ``` 16 | 17 | `debug` is necessary to test federation with http and localhost URLs, but it should never be used in production. `url_verifier` can be used to implement a domain blacklist. 18 | -------------------------------------------------------------------------------- /src/actix_web/http_compat.rs: -------------------------------------------------------------------------------- 1 | //! Remove these conversion helpers after actix-web upgrades to http 1.0 2 | 3 | use std::str::FromStr; 4 | 5 | pub fn header_value(v: &http02::HeaderValue) -> http::HeaderValue { 6 | http::HeaderValue::from_bytes(v.as_bytes()).expect("can convert http types") 7 | } 8 | 9 | pub fn header_map<'a, H>(m: H) -> http::HeaderMap 10 | where 11 | H: IntoIterator, 12 | { 13 | let mut new_map = http::HeaderMap::new(); 14 | for (n, v) in m { 15 | new_map.insert( 16 | http::HeaderName::from_lowercase(n.as_str().as_bytes()) 17 | .expect("can convert http types"), 18 | header_value(v), 19 | ); 20 | } 21 | new_map 22 | } 23 | 24 | pub fn method(m: &http02::Method) -> http::Method { 25 | http::Method::from_bytes(m.as_str().as_bytes()).expect("can convert http types") 26 | } 27 | 28 | pub fn uri(m: &http02::Uri) -> http::Uri { 29 | http::Uri::from_str(&m.to_string()).expect("can convert http types") 30 | } 31 | -------------------------------------------------------------------------------- /src/protocol/public_key.rs: -------------------------------------------------------------------------------- 1 | //! Struct which is used to federate actor key for HTTP signatures 2 | 3 | use serde::{Deserialize, Serialize}; 4 | use url::Url; 5 | 6 | /// Public key of actors which is used for HTTP signatures. 7 | /// 8 | /// This needs to be federated in the `public_key` field of all actors. 9 | #[derive(Clone, Debug, Deserialize, Serialize, PartialEq)] 10 | #[serde(rename_all = "camelCase")] 11 | pub struct PublicKey { 12 | /// Id of this private key. 13 | pub id: String, 14 | /// ID of the actor that this public key belongs to 15 | pub owner: Url, 16 | /// The actual public key in PEM format 17 | pub public_key_pem: String, 18 | } 19 | 20 | impl PublicKey { 21 | /// Create a new [PublicKey] struct for the `owner` with `public_key_pem`. 22 | /// 23 | /// It uses an standard key id of `{actor_id}#main-key` 24 | pub(crate) fn new(owner: Url, public_key_pem: String) -> Self { 25 | let id = main_key_id(&owner); 26 | PublicKey { 27 | id, 28 | owner, 29 | public_key_pem, 30 | } 31 | } 32 | } 33 | 34 | pub(crate) fn main_key_id(owner: &Url) -> String { 35 | format!("{}#main-key", &owner) 36 | } 37 | -------------------------------------------------------------------------------- /docs/04_federating_posts.md: -------------------------------------------------------------------------------- 1 | ## Federating posts 2 | 3 | We repeat the same steps taken above for users in order to federate our posts. 4 | 5 | ```text 6 | $ curl -H 'Accept: application/activity+json' https://mastodon.social/@LemmyDev/109790106847504642 | jq 7 | { 8 | "id": "https://mastodon.social/users/LemmyDev/statuses/109790106847504642", 9 | "type": "Note", 10 | "content": "

( 21 | request: &HttpRequest, 22 | body: Option, 23 | data: &Data<::DataType>, 24 | ) -> Result::Error> 25 | where 26 | A: Object + Actor + Send + Sync, 27 | ::Error: From, 28 | for<'de2> ::Kind: Deserialize<'de2>, 29 | { 30 | let digest_header = request 31 | .headers() 32 | .get("Digest") 33 | .map(http_compat::header_value); 34 | verify_body_hash(digest_header.as_ref(), &body.unwrap_or_default())?; 35 | 36 | let headers = http_compat::header_map(request.headers()); 37 | let method = http_compat::method(request.method()); 38 | let uri = http_compat::uri(request.uri()); 39 | http_signatures::signing_actor(&headers, &method, &uri, data).await 40 | } 41 | -------------------------------------------------------------------------------- /.woodpecker.yml: -------------------------------------------------------------------------------- 1 | variables: 2 | - &rust_image "rust:1.81-bullseye" 3 | 4 | steps: 5 | cargo_fmt: 6 | image: rustdocker/rust:nightly 7 | commands: 8 | - /root/.cargo/bin/cargo fmt -- --check 9 | when: 10 | - event: pull_request 11 | 12 | cargo_clippy: 13 | image: *rust_image 14 | environment: 15 | CARGO_HOME: .cargo 16 | commands: 17 | - rustup component add clippy 18 | - cargo clippy --all-targets --all-features 19 | when: 20 | - event: pull_request 21 | 22 | cargo_test: 23 | image: *rust_image 24 | environment: 25 | CARGO_HOME: .cargo 26 | commands: 27 | - cargo test --all-features --no-fail-fast 28 | when: 29 | - event: pull_request 30 | 31 | cargo_doc: 32 | image: *rust_image 33 | environment: 34 | CARGO_HOME: .cargo 35 | commands: 36 | - cargo doc --all-features 37 | when: 38 | - event: pull_request 39 | 40 | cargo_run_actix_example: 41 | image: *rust_image 42 | environment: 43 | CARGO_HOME: .cargo 44 | commands: 45 | - cargo run --example local_federation actix-web 46 | when: 47 | - event: pull_request 48 | 49 | cargo_run_axum_example: 50 | image: *rust_image 51 | environment: 52 | CARGO_HOME: .cargo 53 | commands: 54 | - cargo run --example local_federation axum 55 | when: 56 | - event: pull_request 57 | -------------------------------------------------------------------------------- /examples/local_federation/activities/accept.rs: -------------------------------------------------------------------------------- 1 | use crate::{activities::follow::Follow, instance::DatabaseHandle, objects::person::DbUser}; 2 | use activitypub_federation::{ 3 | config::Data, 4 | fetch::object_id::ObjectId, 5 | kinds::activity::AcceptType, 6 | traits::Activity, 7 | }; 8 | use serde::{Deserialize, Serialize}; 9 | use url::Url; 10 | 11 | #[derive(Deserialize, Serialize, Debug)] 12 | #[serde(rename_all = "camelCase")] 13 | pub struct Accept { 14 | actor: ObjectId, 15 | object: Follow, 16 | #[serde(rename = "type")] 17 | kind: AcceptType, 18 | id: Url, 19 | } 20 | 21 | impl Accept { 22 | pub fn new(actor: ObjectId, object: Follow, id: Url) -> Accept { 23 | Accept { 24 | actor, 25 | object, 26 | kind: Default::default(), 27 | id, 28 | } 29 | } 30 | } 31 | 32 | #[async_trait::async_trait] 33 | impl Activity for Accept { 34 | type DataType = DatabaseHandle; 35 | type Error = crate::error::Error; 36 | 37 | fn id(&self) -> &Url { 38 | &self.id 39 | } 40 | 41 | fn actor(&self) -> &Url { 42 | self.actor.inner() 43 | } 44 | 45 | async fn verify(&self, _data: &Data) -> Result<(), Self::Error> { 46 | Ok(()) 47 | } 48 | 49 | async fn receive(self, _data: &Data) -> Result<(), Self::Error> { 50 | Ok(()) 51 | } 52 | } 53 | -------------------------------------------------------------------------------- /src/axum/json.rs: -------------------------------------------------------------------------------- 1 | //! Wrapper struct to respond with `application/activity+json` in axum handlers 2 | //! 3 | //! ``` 4 | //! # use anyhow::Error; 5 | //! # use axum::extract::Path; 6 | //! # use activitypub_federation::axum::json::FederationJson; 7 | //! # use activitypub_federation::protocol::context::WithContext; 8 | //! # use activitypub_federation::config::Data; 9 | //! # use activitypub_federation::traits::Object; 10 | //! # use activitypub_federation::traits::tests::{DbConnection, DbUser, Person}; 11 | //! async fn http_get_user(Path(name): Path, data: Data) -> Result>, Error> { 12 | //! let user: DbUser = data.read_local_user(&name).await?; 13 | //! let person = user.into_json(&data).await?; 14 | //! 15 | //! Ok(FederationJson(WithContext::new_default(person))) 16 | //! } 17 | //! ``` 18 | 19 | use crate::FEDERATION_CONTENT_TYPE; 20 | use axum::response::IntoResponse; 21 | use http::header; 22 | use serde::Serialize; 23 | 24 | /// Wrapper struct to respond with `application/activity+json` in axum handlers 25 | #[derive(Debug, Clone, Copy, Default)] 26 | pub struct FederationJson(pub Json); 27 | 28 | impl IntoResponse for FederationJson { 29 | fn into_response(self) -> axum::response::Response { 30 | let mut response = axum::response::Json(self.0).into_response(); 31 | response.headers_mut().insert( 32 | header::CONTENT_TYPE, 33 | FEDERATION_CONTENT_TYPE 34 | .parse() 35 | .expect("Parsing 'application/activity+json' should never fail"), 36 | ); 37 | response 38 | } 39 | } 40 | -------------------------------------------------------------------------------- /src/actix_web/response.rs: -------------------------------------------------------------------------------- 1 | //! Generate HTTP responses for Activitypub ojects 2 | 3 | use crate::{ 4 | protocol::{context::WithContext, tombstone::Tombstone}, 5 | FEDERATION_CONTENT_TYPE, 6 | }; 7 | use actix_web::HttpResponse; 8 | use http02::header::VARY; 9 | use serde::Serialize; 10 | use serde_json::Value; 11 | use url::Url; 12 | 13 | /// Generates HTTP response to serve the object for fetching from other instances. 14 | /// 15 | /// If possible use [Object.http_response] 16 | /// which also handles redirects for remote objects and deletions. 17 | /// 18 | /// `federation_context` is the value of `@context`. 19 | pub fn create_http_response( 20 | data: T, 21 | federation_context: &Value, 22 | ) -> Result { 23 | let json = serde_json::to_string_pretty(&WithContext::new(data, federation_context.clone()))?; 24 | 25 | Ok(HttpResponse::Ok() 26 | .content_type(FEDERATION_CONTENT_TYPE) 27 | .insert_header((VARY, "Accept")) 28 | .body(json)) 29 | } 30 | 31 | pub(crate) fn create_tombstone_response( 32 | id: Url, 33 | federation_context: &Value, 34 | ) -> Result { 35 | let tombstone = Tombstone::new(id); 36 | let json = 37 | serde_json::to_string_pretty(&WithContext::new(tombstone, federation_context.clone()))?; 38 | 39 | Ok(HttpResponse::Gone() 40 | .content_type(FEDERATION_CONTENT_TYPE) 41 | .status(actix_web::http::StatusCode::GONE) 42 | .insert_header((VARY, "Accept")) 43 | .body(json)) 44 | } 45 | 46 | pub(crate) fn redirect_remote_object(url: &Url) -> HttpResponse { 47 | let mut res = HttpResponse::PermanentRedirect(); 48 | res.insert_header((actix_web::http::header::LOCATION, url.as_str())); 49 | res.finish() 50 | } 51 | -------------------------------------------------------------------------------- /examples/local_federation/activities/create_post.rs: -------------------------------------------------------------------------------- 1 | use crate::{ 2 | instance::DatabaseHandle, 3 | objects::{person::DbUser, post::Note}, 4 | DbPost, 5 | }; 6 | use activitypub_federation::{ 7 | config::Data, 8 | fetch::object_id::ObjectId, 9 | kinds::activity::CreateType, 10 | protocol::helpers::deserialize_one_or_many, 11 | traits::{Activity, Object}, 12 | }; 13 | use serde::{Deserialize, Serialize}; 14 | use url::Url; 15 | 16 | #[derive(Deserialize, Serialize, Debug)] 17 | #[serde(rename_all = "camelCase")] 18 | pub struct CreatePost { 19 | pub(crate) actor: ObjectId, 20 | #[serde(deserialize_with = "deserialize_one_or_many")] 21 | pub(crate) to: Vec, 22 | pub(crate) object: Note, 23 | #[serde(rename = "type")] 24 | pub(crate) kind: CreateType, 25 | pub(crate) id: Url, 26 | } 27 | 28 | impl CreatePost { 29 | pub fn new(note: Note, id: Url) -> CreatePost { 30 | CreatePost { 31 | actor: note.attributed_to.clone(), 32 | to: note.to.clone(), 33 | object: note, 34 | kind: CreateType::Create, 35 | id, 36 | } 37 | } 38 | } 39 | 40 | #[async_trait::async_trait] 41 | impl Activity for CreatePost { 42 | type DataType = DatabaseHandle; 43 | type Error = crate::error::Error; 44 | 45 | fn id(&self) -> &Url { 46 | &self.id 47 | } 48 | 49 | fn actor(&self) -> &Url { 50 | self.actor.inner() 51 | } 52 | 53 | async fn verify(&self, data: &Data) -> Result<(), Self::Error> { 54 | DbPost::verify(&self.object, &self.id, data).await?; 55 | Ok(()) 56 | } 57 | 58 | async fn receive(self, data: &Data) -> Result<(), Self::Error> { 59 | DbPost::from_json(self.object, data).await?; 60 | Ok(()) 61 | } 62 | } 63 | -------------------------------------------------------------------------------- /examples/live_federation/http.rs: -------------------------------------------------------------------------------- 1 | use crate::{ 2 | database::DatabaseHandle, 3 | error::Error, 4 | objects::person::{DbUser, Person, PersonAcceptedActivities}, 5 | }; 6 | use activitypub_federation::{ 7 | axum::{ 8 | inbox::{receive_activity, ActivityData}, 9 | json::FederationJson, 10 | }, 11 | config::Data, 12 | fetch::webfinger::{build_webfinger_response, extract_webfinger_name, Webfinger}, 13 | protocol::context::WithContext, 14 | traits::Object, 15 | }; 16 | use axum::{ 17 | debug_handler, 18 | extract::{Path, Query}, 19 | response::{IntoResponse, Response}, 20 | Json, 21 | }; 22 | use http::StatusCode; 23 | use serde::Deserialize; 24 | 25 | impl IntoResponse for Error { 26 | fn into_response(self) -> Response { 27 | (StatusCode::INTERNAL_SERVER_ERROR, format!("{}", self.0)).into_response() 28 | } 29 | } 30 | 31 | #[debug_handler] 32 | pub async fn http_get_user( 33 | Path(name): Path, 34 | data: Data, 35 | ) -> Result>, Error> { 36 | let db_user = data.read_user(&name)?; 37 | let json_user = db_user.into_json(&data).await?; 38 | Ok(FederationJson(WithContext::new_default(json_user))) 39 | } 40 | 41 | #[debug_handler] 42 | pub async fn http_post_user_inbox( 43 | data: Data, 44 | activity_data: ActivityData, 45 | ) -> impl IntoResponse { 46 | receive_activity::, DbUser, DatabaseHandle>( 47 | activity_data, 48 | &data, 49 | ) 50 | .await 51 | } 52 | 53 | #[derive(Deserialize)] 54 | pub struct WebfingerQuery { 55 | resource: String, 56 | } 57 | 58 | #[debug_handler] 59 | pub async fn webfinger( 60 | Query(query): Query, 61 | data: Data, 62 | ) -> Result, Error> { 63 | let name = extract_webfinger_name(&query.resource, &data)?; 64 | let db_user = data.read_user(name)?; 65 | Ok(Json(build_webfinger_response( 66 | query.resource, 67 | db_user.ap_id.into_inner(), 68 | ))) 69 | } 70 | -------------------------------------------------------------------------------- /src/axum/middleware.rs: -------------------------------------------------------------------------------- 1 | use crate::config::{Data, FederationConfig, FederationMiddleware}; 2 | use axum::{body::Body, extract::FromRequestParts, http::Request, response::Response}; 3 | use http::{request::Parts, StatusCode}; 4 | use std::task::{Context, Poll}; 5 | use tower::{Layer, Service}; 6 | 7 | impl Layer for FederationMiddleware { 8 | type Service = FederationService; 9 | 10 | fn layer(&self, inner: S) -> Self::Service { 11 | FederationService { 12 | inner, 13 | config: self.0.clone(), 14 | } 15 | } 16 | } 17 | 18 | /// Passes [FederationConfig] to HTTP handlers, converting it to [Data] in the process 19 | #[doc(hidden)] 20 | #[derive(Clone)] 21 | pub struct FederationService { 22 | inner: S, 23 | config: FederationConfig, 24 | } 25 | 26 | impl Service> for FederationService 27 | where 28 | S: Service, Response = Response> + Send + 'static, 29 | S::Future: Send + 'static, 30 | T: Clone + Send + Sync + 'static, 31 | { 32 | type Response = S::Response; 33 | type Error = S::Error; 34 | type Future = S::Future; 35 | 36 | fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll> { 37 | self.inner.poll_ready(cx) 38 | } 39 | 40 | fn call(&mut self, mut request: Request) -> Self::Future { 41 | request.extensions_mut().insert(self.config.clone()); 42 | self.inner.call(request) 43 | } 44 | } 45 | 46 | impl FromRequestParts for Data 47 | where 48 | S: Send + Sync, 49 | T: Send + Sync, 50 | { 51 | type Rejection = (StatusCode, &'static str); 52 | 53 | async fn from_request_parts(parts: &mut Parts, _state: &S) -> Result { 54 | match parts.extensions.get::>() { 55 | Some(c) => Ok(c.to_request_data()), 56 | None => Err(( 57 | StatusCode::INTERNAL_SERVER_ERROR, 58 | "Missing extension, did you register FederationMiddleware?", 59 | )), 60 | } 61 | } 62 | } 63 | -------------------------------------------------------------------------------- /examples/live_federation/main.rs: -------------------------------------------------------------------------------- 1 | #![allow(clippy::unwrap_used)] 2 | 3 | use crate::{ 4 | database::Database, 5 | http::{http_get_user, http_post_user_inbox, webfinger}, 6 | objects::{person::DbUser, post::DbPost}, 7 | utils::generate_object_id, 8 | }; 9 | use activitypub_federation::config::{FederationConfig, FederationMiddleware}; 10 | use axum::{ 11 | routing::{get, post}, 12 | Router, 13 | }; 14 | use error::Error; 15 | use std::{ 16 | net::ToSocketAddrs, 17 | sync::{Arc, Mutex}, 18 | }; 19 | use tracing::log::{info, LevelFilter}; 20 | 21 | mod activities; 22 | mod database; 23 | mod error; 24 | #[allow(clippy::diverging_sub_expression, clippy::items_after_statements)] 25 | mod http; 26 | mod objects; 27 | mod utils; 28 | 29 | const DOMAIN: &str = "example.com"; 30 | const LOCAL_USER_NAME: &str = "alison"; 31 | const BIND_ADDRESS: &str = "localhost:8003"; 32 | 33 | #[tokio::main] 34 | async fn main() -> Result<(), Error> { 35 | env_logger::builder() 36 | .filter_level(LevelFilter::Warn) 37 | .filter_module("activitypub_federation", LevelFilter::Info) 38 | .filter_module("live_federation", LevelFilter::Info) 39 | .format_timestamp(None) 40 | .init(); 41 | 42 | info!("Setup local user and database"); 43 | let local_user = DbUser::new(DOMAIN, LOCAL_USER_NAME)?; 44 | let database = Arc::new(Database { 45 | users: Mutex::new(vec![local_user]), 46 | }); 47 | 48 | info!("Setup configuration"); 49 | let config = FederationConfig::builder() 50 | .domain(DOMAIN) 51 | .app_data(database) 52 | .build() 53 | .await?; 54 | 55 | info!("Listen with HTTP server on {BIND_ADDRESS}"); 56 | let config = config.clone(); 57 | let app = Router::new() 58 | .route("/{user}", get(http_get_user)) 59 | .route("/{user}/inbox", post(http_post_user_inbox)) 60 | .route("/.well-known/webfinger", get(webfinger)) 61 | .layer(FederationMiddleware::new(config)); 62 | 63 | let addr = BIND_ADDRESS 64 | .to_socket_addrs()? 65 | .next() 66 | .expect("Failed to lookup domain name"); 67 | let listener = tokio::net::TcpListener::bind(addr).await?; 68 | axum::serve(listener, app.into_make_service()).await?; 69 | 70 | Ok(()) 71 | } 72 | -------------------------------------------------------------------------------- /examples/local_federation/activities/follow.rs: -------------------------------------------------------------------------------- 1 | use crate::{ 2 | activities::accept::Accept, 3 | generate_object_id, 4 | instance::DatabaseHandle, 5 | objects::person::DbUser, 6 | }; 7 | use activitypub_federation::{ 8 | config::Data, 9 | fetch::object_id::ObjectId, 10 | kinds::activity::FollowType, 11 | traits::{Activity, Actor}, 12 | }; 13 | use serde::{Deserialize, Serialize}; 14 | use url::Url; 15 | 16 | #[derive(Deserialize, Serialize, Clone, Debug)] 17 | #[serde(rename_all = "camelCase")] 18 | pub struct Follow { 19 | pub(crate) actor: ObjectId, 20 | pub(crate) object: ObjectId, 21 | #[serde(rename = "type")] 22 | kind: FollowType, 23 | id: Url, 24 | } 25 | 26 | impl Follow { 27 | pub fn new(actor: ObjectId, object: ObjectId, id: Url) -> Follow { 28 | Follow { 29 | actor, 30 | object, 31 | kind: Default::default(), 32 | id, 33 | } 34 | } 35 | } 36 | 37 | #[async_trait::async_trait] 38 | impl Activity for Follow { 39 | type DataType = DatabaseHandle; 40 | type Error = crate::error::Error; 41 | 42 | fn id(&self) -> &Url { 43 | &self.id 44 | } 45 | 46 | fn actor(&self) -> &Url { 47 | self.actor.inner() 48 | } 49 | 50 | async fn verify(&self, _data: &Data) -> Result<(), Self::Error> { 51 | Ok(()) 52 | } 53 | 54 | // Ignore clippy false positive: https://github.com/rust-lang/rust-clippy/issues/6446 55 | #[allow(clippy::await_holding_lock)] 56 | async fn receive(self, data: &Data) -> Result<(), Self::Error> { 57 | // add to followers 58 | let local_user = { 59 | let mut users = data.users.lock().unwrap(); 60 | let local_user = users.first_mut().unwrap(); 61 | local_user.followers.push(self.actor.inner().clone()); 62 | local_user.clone() 63 | }; 64 | 65 | // send back an accept 66 | let follower = self.actor.dereference(data).await?; 67 | let id = generate_object_id(data.domain())?; 68 | let accept = Accept::new(local_user.ap_id.clone(), self, id.clone()); 69 | local_user 70 | .send(accept, vec![follower.shared_inbox_or_inbox()], false, data) 71 | .await?; 72 | Ok(()) 73 | } 74 | } 75 | -------------------------------------------------------------------------------- /src/protocol/values.rs: -------------------------------------------------------------------------------- 1 | //! Single value enums used to receive JSON with specific expected string values 2 | //! 3 | //! The enums here serve to limit a json string value to a single, hardcoded value which can be 4 | //! verified at compilation time. When using it as the type of a struct field, the struct can only 5 | //! be constructed or deserialized if the field has the exact same value. 6 | //! 7 | //! In the example below, `MyObject` can only be constructed or 8 | //! deserialized if `media_type` is `text/markdown`, but not if it is `text/html`. 9 | //! 10 | //! ``` 11 | //! use serde_json::from_str; 12 | //! use serde::{Deserialize, Serialize}; 13 | //! use activitypub_federation::protocol::values::MediaTypeMarkdown; 14 | //! 15 | //! #[derive(Deserialize, Serialize)] 16 | //! struct MyObject { 17 | //! content: String, 18 | //! media_type: MediaTypeMarkdown, 19 | //! } 20 | //! 21 | //! let markdown_json = r#"{"content": "**test**", "media_type": "text/markdown"}"#; 22 | //! let from_markdown = from_str::(markdown_json); 23 | //! assert!(from_markdown.is_ok()); 24 | //! 25 | //! let markdown_html = r#"{"content": "test", "media_type": "text/html"}"#; 26 | //! let from_html = from_str::(markdown_html); 27 | //! assert!(from_html.is_err()); 28 | //! ``` 29 | //! 30 | //! The enums in [activitystreams_kinds] work in the same way, and can be used to 31 | //! distinguish different activity types. 32 | 33 | use serde::{Deserialize, Serialize}; 34 | 35 | /// Media type for markdown text. 36 | /// 37 | /// 38 | #[derive(Clone, Debug, Deserialize, Serialize, PartialEq)] 39 | pub enum MediaTypeMarkdown { 40 | /// `text/markdown` 41 | #[serde(rename = "text/markdown")] 42 | Markdown, 43 | } 44 | 45 | /// Media type for HTML text. 46 | /// 47 | /// 48 | #[derive(Clone, Debug, Deserialize, Serialize, PartialEq)] 49 | pub enum MediaTypeHtml { 50 | /// `text/html` 51 | #[serde(rename = "text/html")] 52 | Html, 53 | } 54 | 55 | /// Media type which allows both markdown and HTML. 56 | #[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)] 57 | pub enum MediaTypeMarkdownOrHtml { 58 | /// `text/markdown` 59 | #[serde(rename = "text/markdown")] 60 | Markdown, 61 | /// `text/html` 62 | #[serde(rename = "text/html")] 63 | Html, 64 | } 65 | -------------------------------------------------------------------------------- /examples/live_federation/activities/create_post.rs: -------------------------------------------------------------------------------- 1 | use crate::{ 2 | database::DatabaseHandle, 3 | error::Error, 4 | objects::{person::DbUser, post::Note}, 5 | utils::generate_object_id, 6 | DbPost, 7 | }; 8 | use activitypub_federation::{ 9 | activity_sending::SendActivityTask, 10 | config::Data, 11 | fetch::object_id::ObjectId, 12 | kinds::activity::CreateType, 13 | protocol::{context::WithContext, helpers::deserialize_one_or_many}, 14 | traits::{Activity, Object}, 15 | }; 16 | use serde::{Deserialize, Serialize}; 17 | use url::Url; 18 | 19 | #[derive(Deserialize, Serialize, Debug)] 20 | #[serde(rename_all = "camelCase")] 21 | pub struct CreatePost { 22 | pub(crate) actor: ObjectId, 23 | #[serde(deserialize_with = "deserialize_one_or_many")] 24 | pub(crate) to: Vec, 25 | pub(crate) object: Note, 26 | #[serde(rename = "type")] 27 | pub(crate) kind: CreateType, 28 | pub(crate) id: Url, 29 | } 30 | 31 | impl CreatePost { 32 | pub async fn send(note: Note, inbox: Url, data: &Data) -> Result<(), Error> { 33 | print!("Sending reply to {}", ¬e.attributed_to); 34 | let create = CreatePost { 35 | actor: note.attributed_to.clone(), 36 | to: note.to.clone(), 37 | object: note, 38 | kind: CreateType::Create, 39 | id: generate_object_id(data.domain())?, 40 | }; 41 | let create_with_context = WithContext::new_default(create); 42 | let sends = 43 | SendActivityTask::prepare(&create_with_context, &data.local_user(), vec![inbox], data) 44 | .await?; 45 | for send in sends { 46 | send.sign_and_send(data).await?; 47 | } 48 | Ok(()) 49 | } 50 | } 51 | 52 | #[async_trait::async_trait] 53 | impl Activity for CreatePost { 54 | type DataType = DatabaseHandle; 55 | type Error = crate::error::Error; 56 | 57 | fn id(&self) -> &Url { 58 | &self.id 59 | } 60 | 61 | fn actor(&self) -> &Url { 62 | self.actor.inner() 63 | } 64 | 65 | async fn verify(&self, data: &Data) -> Result<(), Self::Error> { 66 | DbPost::verify(&self.object, &self.id, data).await?; 67 | Ok(()) 68 | } 69 | 70 | async fn receive(self, data: &Data) -> Result<(), Self::Error> { 71 | DbPost::from_json(self.object, data).await?; 72 | Ok(()) 73 | } 74 | } 75 | -------------------------------------------------------------------------------- /examples/local_federation/main.rs: -------------------------------------------------------------------------------- 1 | #![allow(clippy::unwrap_used)] 2 | 3 | use crate::{ 4 | instance::{listen, new_instance, Webserver}, 5 | objects::post::DbPost, 6 | utils::generate_object_id, 7 | }; 8 | use error::Error; 9 | use std::{env::args, str::FromStr}; 10 | use tokio::try_join; 11 | use tracing::log::{info, LevelFilter}; 12 | 13 | mod activities; 14 | #[cfg(feature = "actix-web")] 15 | mod actix_web; 16 | #[cfg(feature = "axum")] 17 | mod axum; 18 | mod error; 19 | mod instance; 20 | mod objects; 21 | mod utils; 22 | 23 | #[tokio::main] 24 | async fn main() -> Result<(), Error> { 25 | env_logger::builder() 26 | .filter_level(LevelFilter::Warn) 27 | .filter_module("activitypub_federation", LevelFilter::Info) 28 | .filter_module("local_federation", LevelFilter::Info) 29 | .format_timestamp(None) 30 | .init(); 31 | 32 | info!("Start with parameter `axum` or `actix-web` to select the webserver"); 33 | let webserver = args() 34 | .nth(1) 35 | .map(|arg| Webserver::from_str(&arg).unwrap()) 36 | .unwrap_or(Webserver::Axum); 37 | 38 | let (alpha, beta) = try_join!( 39 | new_instance("localhost:8001", "alpha".to_string()), 40 | new_instance("localhost:8002", "beta".to_string()) 41 | )?; 42 | listen(&alpha, &webserver)?; 43 | listen(&beta, &webserver)?; 44 | info!("Local instances started"); 45 | 46 | info!("Alpha user follows beta user via webfinger"); 47 | alpha 48 | .local_user() 49 | .follow("beta@localhost:8002", &alpha.to_request_data()) 50 | .await?; 51 | assert_eq!( 52 | beta.local_user().followers(), 53 | &vec![alpha.local_user().ap_id.inner().clone()] 54 | ); 55 | info!("Follow was successful"); 56 | 57 | info!("Beta sends a post to its followers"); 58 | let sent_post = DbPost::new("Hello world!".to_string(), beta.local_user().ap_id)?; 59 | beta.local_user() 60 | .post(sent_post.clone(), &beta.to_request_data()) 61 | .await?; 62 | let received_post = alpha.posts.lock().unwrap().first().cloned().unwrap(); 63 | info!("Alpha received post: {}", received_post.text); 64 | 65 | // assert that alpha received the post 66 | assert_eq!(received_post.text, sent_post.text); 67 | assert_eq!(received_post.ap_id.inner(), sent_post.ap_id.inner()); 68 | assert_eq!(received_post.creator.inner(), sent_post.creator.inner()); 69 | info!("Test completed"); 70 | Ok(()) 71 | } 72 | -------------------------------------------------------------------------------- /src/actix_web/middleware.rs: -------------------------------------------------------------------------------- 1 | use crate::config::{Data, FederationConfig, FederationMiddleware}; 2 | use actix_web::{ 3 | dev::{forward_ready, Payload, Service, ServiceRequest, ServiceResponse, Transform}, 4 | Error, 5 | FromRequest, 6 | HttpMessage, 7 | HttpRequest, 8 | }; 9 | use std::future::{ready, Ready}; 10 | 11 | impl Transform for FederationMiddleware 12 | where 13 | S: Service, Error = Error>, 14 | S::Future: 'static, 15 | B: 'static, 16 | T: Clone + Sync + 'static, 17 | { 18 | type Response = ServiceResponse; 19 | type Error = Error; 20 | type Transform = FederationService; 21 | type InitError = (); 22 | type Future = Ready>; 23 | 24 | fn new_transform(&self, service: S) -> Self::Future { 25 | ready(Ok(FederationService { 26 | service, 27 | config: self.0.clone(), 28 | })) 29 | } 30 | } 31 | 32 | /// Passes [FederationConfig] to HTTP handlers, converting it to [Data] in the process 33 | #[doc(hidden)] 34 | pub struct FederationService 35 | where 36 | S: Service, 37 | S::Future: 'static, 38 | T: Sync, 39 | { 40 | service: S, 41 | config: FederationConfig, 42 | } 43 | 44 | impl Service for FederationService 45 | where 46 | S: Service, Error = Error>, 47 | S::Future: 'static, 48 | B: 'static, 49 | T: Clone + Sync + 'static, 50 | { 51 | type Response = ServiceResponse; 52 | type Error = Error; 53 | type Future = S::Future; 54 | 55 | forward_ready!(service); 56 | 57 | fn call(&self, req: ServiceRequest) -> Self::Future { 58 | req.extensions_mut().insert(self.config.clone()); 59 | 60 | self.service.call(req) 61 | } 62 | } 63 | 64 | impl FromRequest for Data { 65 | type Error = Error; 66 | type Future = Ready>; 67 | 68 | fn from_request(req: &HttpRequest, _payload: &mut Payload) -> Self::Future { 69 | ready(match req.extensions().get::>() { 70 | Some(c) => Ok(c.to_request_data()), 71 | None => Err(actix_web::error::ErrorBadRequest( 72 | "Missing extension, did you register FederationMiddleware?", 73 | )), 74 | }) 75 | } 76 | } 77 | -------------------------------------------------------------------------------- /examples/README.md: -------------------------------------------------------------------------------- 1 | # Examples 2 | 3 | ## Local Federation 4 | 5 | Creates two instances which run on localhost and federate with each other. This setup is ideal for quick development and well as automated tests. In this case both instances run in the same process and are controlled from the main function. 6 | 7 | In case of Lemmy we are using the same setup for continuous integration tests, only that multiple instances are started with a bash script as different threads, and controlled over the API. 8 | 9 | Use one of the following commands to run the example with the specified web framework: 10 | 11 | `cargo run --example local_federation axum` 12 | 13 | `cargo run --example local_federation actix-web` 14 | 15 | ## Live Federation 16 | 17 | 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. 18 | 19 | Setup instructions: 20 | 21 | - Deploy the project to a server. For this you can clone the git repository on the server and execute `cargo run --example live_federation`. Alternatively run `cargo build --example live_federation` and copy the binary at `target/debug/examples/live_federation` to the server. 22 | - Create a TLS certificate. With Let's Encrypt certbot you can use a command like `certbot certonly --nginx -d 'example.com' -m '*your-email@domain.com*'` (replace with your actual domain and email). 23 | - Setup a reverse proxy which handles TLS and passes requests to the example project. With nginx you can use the following basic config, again using your actual domain: 24 | ``` 25 | server { 26 | listen 443 ssl http2; 27 | listen [::]:443 ssl http2; 28 | server_name example.com; 29 | ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; 30 | ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; 31 | location / { 32 | proxy_pass "http://localhost:8003"; 33 | proxy_set_header Host $host; 34 | } 35 | } 36 | ``` 37 | - Test with `curl -H 'Accept: application/activity+json' https://example.com/alison | jq` and `curl -H 'Accept: application/activity+json' "https://example.com/.well-known/webfinger?resource=acct:alison@example.com" | jq` that the server is setup correctly and serving correct responses. 38 | - Login to a Fediverse platform like Mastodon, and search for `@alison@example.com`, with the actual domain and username from your `main.rs`. If you send a message, it will automatically send a response. -------------------------------------------------------------------------------- /docs/02_overview.md: -------------------------------------------------------------------------------- 1 | ## Overview 2 | 3 | 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. 4 | 5 | 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. 6 | 7 | There are two examples included to see how the library altogether: 8 | 9 | - `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. 10 | - `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. 11 | 12 | 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). 13 | 14 | ### Security 15 | This framework does not inherently perform data sanitization upon receiving federated activity data. 16 | 17 | Please, never place implicit trust in the security of data received from the Fediverse. Always keep in mind that malicious entities can be easily created through anonymous fediverse handles. 18 | 19 | When implementing our crate in your application, ensure to incorporate data sanitization and validation measures before storing the received data in your database and using it in your user interface. This would significantly reduce the risk of malicious data or actions affecting your application's security and performance. 20 | 21 | This framework is designed to simplify your development process, but it's your responsibility to ensure the security of your application. Always follow best practices for data handling, sanitization, and security. 22 | -------------------------------------------------------------------------------- /src/lib.rs: -------------------------------------------------------------------------------- 1 | #![doc = include_str!("../docs/01_intro.md")] 2 | #![doc = include_str!("../docs/02_overview.md")] 3 | #![doc = include_str!("../docs/03_federating_users.md")] 4 | #![doc = include_str!("../docs/04_federating_posts.md")] 5 | #![doc = include_str!("../docs/05_configuration.md")] 6 | #![doc = include_str!("../docs/06_http_endpoints_axum.md")] 7 | #![doc = include_str!("../docs/07_fetching_data.md")] 8 | #![doc = include_str!("../docs/08_receiving_activities.md")] 9 | #![doc = include_str!("../docs/09_sending_activities.md")] 10 | #![doc = include_str!("../docs/10_fetching_objects_with_unknown_type.md")] 11 | #![deny(missing_docs)] 12 | 13 | pub mod activity_queue; 14 | pub mod activity_sending; 15 | #[cfg(feature = "actix-web")] 16 | pub mod actix_web; 17 | #[cfg(feature = "axum")] 18 | pub mod axum; 19 | pub mod config; 20 | pub mod error; 21 | pub mod fetch; 22 | pub mod http_signatures; 23 | pub mod protocol; 24 | pub(crate) mod reqwest_shim; 25 | pub mod traits; 26 | 27 | use crate::{ 28 | config::Data, 29 | error::Error, 30 | fetch::object_id::ObjectId, 31 | traits::{Activity, Actor, Object}, 32 | }; 33 | pub use activitystreams_kinds as kinds; 34 | 35 | use serde::{de::DeserializeOwned, Deserialize}; 36 | use url::Url; 37 | 38 | /// Mime type for Activitypub data, used for `Accept` and `Content-Type` HTTP headers 39 | pub const FEDERATION_CONTENT_TYPE: &str = "application/activity+json"; 40 | 41 | /// Deserialize incoming inbox activity to the given type, perform basic 42 | /// validation and extract the actor. 43 | async fn parse_received_activity( 44 | body: &[u8], 45 | data: &Data, 46 | ) -> Result<(A, ActorT), ::Error> 47 | where 48 | A: Activity + DeserializeOwned + Send + 'static, 49 | ActorT: Object + Actor + Send + Sync + 'static, 50 | for<'de2> ::Kind: serde::Deserialize<'de2>, 51 | ::Error: From + From<::Error>, 52 | ::Error: From, 53 | Datatype: Clone, 54 | { 55 | let activity: A = serde_json::from_slice(body).map_err(|err| { 56 | // Attempt to include activity id in error message 57 | let id = extract_id(body).ok(); 58 | Error::ParseReceivedActivity { err, id } 59 | })?; 60 | data.config.verify_url_and_domain(&activity).await?; 61 | let actor = ObjectId::::from(activity.actor().clone()) 62 | .dereference(data) 63 | .await?; 64 | Ok((activity, actor)) 65 | } 66 | 67 | /// Attempt to parse id field from serialized json 68 | fn extract_id(data: &[u8]) -> serde_json::Result { 69 | #[derive(Deserialize)] 70 | struct Id { 71 | id: Url, 72 | } 73 | Ok(serde_json::from_slice::(data)?.id) 74 | } 75 | -------------------------------------------------------------------------------- /examples/local_federation/axum/http.rs: -------------------------------------------------------------------------------- 1 | use crate::{ 2 | error::Error, 3 | instance::DatabaseHandle, 4 | objects::person::{DbUser, Person, PersonAcceptedActivities}, 5 | }; 6 | use activitypub_federation::{ 7 | axum::{ 8 | inbox::{receive_activity, ActivityData}, 9 | json::FederationJson, 10 | }, 11 | config::{Data, FederationConfig, FederationMiddleware}, 12 | fetch::webfinger::{build_webfinger_response, extract_webfinger_name, Webfinger}, 13 | protocol::context::WithContext, 14 | traits::Object, 15 | }; 16 | use axum::{ 17 | debug_handler, 18 | extract::{Path, Query}, 19 | response::IntoResponse, 20 | routing::{get, post}, 21 | Json, 22 | Router, 23 | }; 24 | use serde::Deserialize; 25 | use std::net::ToSocketAddrs; 26 | use tracing::info; 27 | 28 | pub fn listen(config: &FederationConfig) -> Result<(), Error> { 29 | let hostname = config.domain(); 30 | info!("Listening with axum on {hostname}"); 31 | let config = config.clone(); 32 | 33 | let app = Router::new() 34 | .route("/{user}/inbox", post(http_post_user_inbox)) 35 | .route("/{user}", get(http_get_user)) 36 | .route("/.well-known/webfinger", get(webfinger)) 37 | .layer(FederationMiddleware::new(config)); 38 | 39 | let addr = hostname 40 | .to_socket_addrs()? 41 | .next() 42 | .expect("Failed to lookup domain name"); 43 | let fut = async move { 44 | let listener = tokio::net::TcpListener::bind(addr).await.unwrap(); 45 | axum::serve(listener, app.into_make_service()) 46 | .await 47 | .unwrap(); 48 | }; 49 | 50 | tokio::spawn(fut); 51 | Ok(()) 52 | } 53 | 54 | #[debug_handler] 55 | async fn http_get_user( 56 | Path(name): Path, 57 | data: Data, 58 | ) -> Result>, Error> { 59 | let db_user = data.read_user(&name)?; 60 | let json_user = db_user.into_json(&data).await?; 61 | Ok(FederationJson(WithContext::new_default(json_user))) 62 | } 63 | 64 | #[debug_handler] 65 | async fn http_post_user_inbox( 66 | data: Data, 67 | activity_data: ActivityData, 68 | ) -> impl IntoResponse { 69 | receive_activity::, DbUser, DatabaseHandle>( 70 | activity_data, 71 | &data, 72 | ) 73 | .await 74 | } 75 | 76 | #[derive(Deserialize)] 77 | struct WebfingerQuery { 78 | resource: String, 79 | } 80 | 81 | #[debug_handler] 82 | async fn webfinger( 83 | Query(query): Query, 84 | data: Data, 85 | ) -> Result, Error> { 86 | let name = extract_webfinger_name(&query.resource, &data)?; 87 | let db_user = data.read_user(name)?; 88 | Ok(Json(build_webfinger_response( 89 | query.resource, 90 | db_user.ap_id.into_inner(), 91 | ))) 92 | } 93 | -------------------------------------------------------------------------------- /docs/07_fetching_data.md: -------------------------------------------------------------------------------- 1 | ## Fetching data 2 | 3 | After setting up our structs, implementing traits and initializing configuration, we can easily fetch data from remote servers: 4 | 5 | ```no_run 6 | # use activitypub_federation::fetch::object_id::ObjectId; 7 | # use activitypub_federation::traits::tests::DbUser; 8 | # use activitypub_federation::config::FederationConfig; 9 | # let db_connection = activitypub_federation::traits::tests::DbConnection; 10 | # tokio::runtime::Runtime::new().unwrap().block_on(async { 11 | let config = FederationConfig::builder() 12 | .domain("example.com") 13 | .app_data(db_connection) 14 | .build().await?; 15 | let user_id = ObjectId::::parse("https://mastodon.social/@LemmyDev")?; 16 | let data = config.to_request_data(); 17 | let user = user_id.dereference(&data).await; 18 | assert!(user.is_ok()); 19 | # Ok::<(), anyhow::Error>(()) 20 | # }).unwrap() 21 | ``` 22 | 23 | `dereference` retrieves the object JSON at the given URL, and uses serde to convert it to `Person`. It then calls your method `Object::from_json` 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. 24 | 25 | 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. 26 | 27 | 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. 28 | ```rust 29 | # use activitypub_federation::traits::tests::DbConnection; 30 | # use activitypub_federation::config::FederationConfig; 31 | # use activitypub_federation::fetch::webfinger::webfinger_resolve_actor; 32 | # use activitypub_federation::traits::tests::DbUser; 33 | # let db_connection = DbConnection; 34 | # tokio::runtime::Runtime::new().unwrap().block_on(async { 35 | # let config = FederationConfig::builder().domain("example.com").app_data(db_connection).build().await?; 36 | # let data = config.to_request_data(); 37 | let user: DbUser = webfinger_resolve_actor("ruud@lemmy.world", &data).await?; 38 | # Ok::<(), anyhow::Error>(()) 39 | # }).unwrap(); 40 | ``` 41 | 42 | Note that webfinger queries don't contain a leading `@`. It is possible that 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. 43 | -------------------------------------------------------------------------------- /docs/01_intro.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | 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. 4 | 5 | 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. 6 | 7 | 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: 8 | 9 | - **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. 10 | - **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. 11 | - **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. 12 | - **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. 13 | - **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. 14 | 15 | Below you can find a complete guide that explains how to create a federated project from scratch. 16 | 17 | 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. -------------------------------------------------------------------------------- /src/protocol/context.rs: -------------------------------------------------------------------------------- 1 | //! Wrapper for federated structs which handles `@context` field. 2 | //! 3 | //! This wrapper can be used when sending Activitypub data, to automatically add `@context`. It 4 | //! avoids having to repeat the `@context` property on every struct, and getting multiple contexts 5 | //! in nested structs. 6 | //! 7 | //! ``` 8 | //! # use activitypub_federation::protocol::context::WithContext; 9 | //! #[derive(serde::Serialize)] 10 | //! struct Note { 11 | //! content: String 12 | //! } 13 | //! let note = Note { 14 | //! content: "Hello world".to_string() 15 | //! }; 16 | //! let note_with_context = WithContext::new_default(note); 17 | //! let serialized = serde_json::to_string(¬e_with_context)?; 18 | //! assert_eq!(serialized, r#"{"@context":"https://www.w3.org/ns/activitystreams","content":"Hello world"}"#); 19 | //! Ok::<(), serde_json::error::Error>(()) 20 | //! ``` 21 | 22 | use crate::{config::Data, traits::Activity}; 23 | use serde::{Deserialize, Serialize}; 24 | use serde_json::Value; 25 | use url::Url; 26 | 27 | /// Default context used in Activitypub 28 | const DEFAULT_CONTEXT: &str = "https://www.w3.org/ns/activitystreams"; 29 | 30 | /// Wrapper for federated structs which handles `@context` field. 31 | #[derive(Serialize, Deserialize, Debug)] 32 | pub struct WithContext { 33 | #[serde(rename = "@context")] 34 | context: Value, 35 | #[serde(flatten)] 36 | inner: T, 37 | } 38 | 39 | impl WithContext { 40 | /// Create a new wrapper with the default Activitypub context. 41 | pub fn new_default(inner: T) -> WithContext { 42 | let context = Value::String(DEFAULT_CONTEXT.to_string()); 43 | WithContext::new(inner, context) 44 | } 45 | 46 | /// Create new wrapper with custom context. Use this in case you are implementing extensions. 47 | pub fn new(inner: T, context: Value) -> WithContext { 48 | WithContext { context, inner } 49 | } 50 | 51 | /// Returns the inner `T` object which this `WithContext` object is wrapping 52 | pub fn inner(&self) -> &T { 53 | &self.inner 54 | } 55 | } 56 | 57 | #[async_trait::async_trait] 58 | impl Activity for WithContext 59 | where 60 | T: Activity + Send + Sync, 61 | { 62 | type DataType = ::DataType; 63 | type Error = ::Error; 64 | 65 | fn id(&self) -> &Url { 66 | self.inner.id() 67 | } 68 | 69 | fn actor(&self) -> &Url { 70 | self.inner.actor() 71 | } 72 | 73 | async fn verify(&self, data: &Data) -> Result<(), Self::Error> { 74 | self.inner.verify(data).await 75 | } 76 | 77 | async fn receive(self, data: &Data) -> Result<(), Self::Error> { 78 | self.inner.receive(data).await 79 | } 80 | } 81 | 82 | impl Clone for WithContext 83 | where 84 | T: Clone, 85 | { 86 | fn clone(&self) -> Self { 87 | Self { 88 | context: self.context.clone(), 89 | inner: self.inner.clone(), 90 | } 91 | } 92 | } 93 | -------------------------------------------------------------------------------- /examples/local_federation/objects/post.rs: -------------------------------------------------------------------------------- 1 | use crate::{error::Error, generate_object_id, instance::DatabaseHandle, objects::person::DbUser}; 2 | use activitypub_federation::{ 3 | config::Data, 4 | fetch::object_id::ObjectId, 5 | kinds::{object::NoteType, public}, 6 | protocol::{helpers::deserialize_one_or_many, verification::verify_domains_match}, 7 | traits::Object, 8 | }; 9 | use serde::{Deserialize, Serialize}; 10 | use url::Url; 11 | 12 | #[derive(Clone, Debug)] 13 | pub struct DbPost { 14 | pub text: String, 15 | pub ap_id: ObjectId, 16 | pub creator: ObjectId, 17 | pub local: bool, 18 | } 19 | 20 | impl DbPost { 21 | pub fn new(text: String, creator: ObjectId) -> Result { 22 | let ap_id = generate_object_id(creator.inner().domain().unwrap())?.into(); 23 | Ok(DbPost { 24 | text, 25 | ap_id, 26 | creator, 27 | local: true, 28 | }) 29 | } 30 | } 31 | 32 | #[derive(Deserialize, Serialize, Debug)] 33 | #[serde(rename_all = "camelCase")] 34 | pub struct Note { 35 | #[serde(rename = "type")] 36 | kind: NoteType, 37 | id: ObjectId, 38 | pub(crate) attributed_to: ObjectId, 39 | #[serde(deserialize_with = "deserialize_one_or_many")] 40 | pub(crate) to: Vec, 41 | content: String, 42 | } 43 | 44 | #[async_trait::async_trait] 45 | impl Object for DbPost { 46 | type DataType = DatabaseHandle; 47 | type Kind = Note; 48 | type Error = Error; 49 | 50 | fn id(&self) -> &Url { 51 | self.ap_id.inner() 52 | } 53 | 54 | async fn read_from_id( 55 | object_id: Url, 56 | data: &Data, 57 | ) -> Result, Self::Error> { 58 | let posts = data.posts.lock().unwrap(); 59 | let res = posts 60 | .clone() 61 | .into_iter() 62 | .find(|u| u.ap_id.inner() == &object_id); 63 | Ok(res) 64 | } 65 | 66 | async fn into_json(self, data: &Data) -> Result { 67 | let creator = self.creator.dereference_local(data).await?; 68 | Ok(Note { 69 | kind: Default::default(), 70 | id: self.ap_id, 71 | attributed_to: self.creator, 72 | to: vec![public(), creator.followers_url()?], 73 | content: self.text, 74 | }) 75 | } 76 | 77 | async fn verify( 78 | json: &Self::Kind, 79 | expected_domain: &Url, 80 | _data: &Data, 81 | ) -> Result<(), Self::Error> { 82 | verify_domains_match(json.id.inner(), expected_domain)?; 83 | Ok(()) 84 | } 85 | 86 | async fn from_json(json: Self::Kind, data: &Data) -> Result { 87 | let post = DbPost { 88 | text: json.content, 89 | ap_id: json.id, 90 | creator: json.attributed_to, 91 | local: false, 92 | }; 93 | 94 | let mut lock = data.posts.lock().unwrap(); 95 | lock.push(post.clone()); 96 | Ok(post) 97 | } 98 | } 99 | -------------------------------------------------------------------------------- /src/protocol/verification.rs: -------------------------------------------------------------------------------- 1 | //! Verify that received data is valid 2 | 3 | use crate::{config::Data, error::Error, fetch::object_id::ObjectId, traits::Object}; 4 | use serde::Deserialize; 5 | use url::Url; 6 | 7 | /// Check that both urls have the same domain. If not, return UrlVerificationError. 8 | /// 9 | /// ``` 10 | /// # use url::Url; 11 | /// # use activitypub_federation::protocol::verification::verify_domains_match; 12 | /// let a = Url::parse("https://example.com/abc")?; 13 | /// let b = Url::parse("https://sample.net/abc")?; 14 | /// assert!(verify_domains_match(&a, &b).is_err()); 15 | /// # Ok::<(), url::ParseError>(()) 16 | /// ``` 17 | pub fn verify_domains_match(a: &Url, b: &Url) -> Result<(), Error> { 18 | if a.domain() != b.domain() { 19 | return Err(Error::UrlVerificationError("Domains do not match")); 20 | } 21 | Ok(()) 22 | } 23 | 24 | /// Check that both urls are identical. If not, return UrlVerificationError. 25 | /// 26 | /// ``` 27 | /// # use url::Url; 28 | /// # use activitypub_federation::protocol::verification::verify_urls_match; 29 | /// let a = Url::parse("https://example.com/abc")?; 30 | /// let b = Url::parse("https://example.com/123")?; 31 | /// assert!(verify_urls_match(&a, &b).is_err()); 32 | /// # Ok::<(), url::ParseError>(()) 33 | /// ``` 34 | pub fn verify_urls_match(a: &Url, b: &Url) -> Result<(), Error> { 35 | if a != b { 36 | return Err(Error::UrlVerificationError("Urls do not match")); 37 | } 38 | Ok(()) 39 | } 40 | 41 | /// Check that the given ID doesn't match the local domain. 42 | /// 43 | /// It is important to verify this to avoid local objects from being overwritten. In general 44 | /// locally created objects should be considered authorative, while incoming federated data 45 | /// is untrusted. Lack of such a check could allow an attacker to rewrite local posts. It could 46 | /// also result in an `object.local` field being overwritten with `false` for local objects, resulting in invalid data. 47 | /// 48 | /// ``` 49 | /// # use activitypub_federation::fetch::object_id::ObjectId; 50 | /// # use activitypub_federation::config::FederationConfig; 51 | /// # use activitypub_federation::protocol::verification::verify_is_remote_object; 52 | /// # use activitypub_federation::traits::tests::{DbConnection, DbUser}; 53 | /// # tokio::runtime::Runtime::new().unwrap().block_on(async { 54 | /// # let config = FederationConfig::builder().domain("example.com").app_data(DbConnection).build().await?; 55 | /// # let data = config.to_request_data(); 56 | /// let id = ObjectId::::parse("https://remote.com/u/name")?; 57 | /// assert!(verify_is_remote_object(&id, &data).is_ok()); 58 | /// # Ok::<(), anyhow::Error>(()) 59 | /// # }).unwrap(); 60 | /// ``` 61 | pub fn verify_is_remote_object( 62 | id: &ObjectId, 63 | data: &Data<::DataType>, 64 | ) -> Result<(), Error> 65 | where 66 | Kind: Object + Send + Sync + 'static, 67 | for<'de2> ::Kind: Deserialize<'de2>, 68 | { 69 | if id.is_local(data) { 70 | Err(Error::UrlVerificationError("Object is not remote")) 71 | } else { 72 | Ok(()) 73 | } 74 | } 75 | -------------------------------------------------------------------------------- /docs/10_fetching_objects_with_unknown_type.md: -------------------------------------------------------------------------------- 1 | ## Fetching remote object with unknown type 2 | 3 | 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: 4 | 5 | ```no_run 6 | # use activitypub_federation::traits::tests::{DbUser, DbPost}; 7 | # use activitypub_federation::fetch::object_id::ObjectId; 8 | # use activitypub_federation::traits::Object; 9 | # use activitypub_federation::config::FederationConfig; 10 | # use serde::{Deserialize, Serialize}; 11 | # use activitypub_federation::traits::tests::DbConnection; 12 | # use activitypub_federation::config::Data; 13 | # use url::Url; 14 | # use activitypub_federation::traits::tests::{Person, Note}; 15 | 16 | #[derive(Debug)] 17 | pub enum SearchableDbObjects { 18 | User(DbUser), 19 | Post(DbPost) 20 | } 21 | 22 | #[derive(Deserialize, Serialize, Debug)] 23 | #[serde(untagged)] 24 | pub enum SearchableObjects { 25 | Person(Person), 26 | Note(Note) 27 | } 28 | 29 | #[async_trait::async_trait] 30 | impl Object for SearchableDbObjects { 31 | type DataType = DbConnection; 32 | type Kind = SearchableObjects; 33 | type Error = anyhow::Error; 34 | 35 | fn id(&self) -> &Url { 36 | match self { 37 | SearchableDbObjects::User(p) => &p.federation_id, 38 | SearchableDbObjects::Post(n) => &n.federation_id, 39 | } 40 | } 41 | 42 | async fn read_from_id( 43 | object_id: Url, 44 | data: &Data, 45 | ) -> Result, Self::Error> { 46 | Ok(None) 47 | } 48 | 49 | async fn into_json( 50 | self, 51 | data: &Data, 52 | ) -> Result { 53 | unimplemented!(); 54 | } 55 | 56 | async fn verify(json: &Self::Kind, expected_domain: &Url, _data: &Data) -> Result<(), Self::Error> { 57 | Ok(()) 58 | } 59 | 60 | async fn from_json( 61 | json: Self::Kind, 62 | data: &Data, 63 | ) -> Result { 64 | use SearchableDbObjects::*; 65 | match json { 66 | SearchableObjects::Person(p) => Ok(User(DbUser::from_json(p, data).await?)), 67 | SearchableObjects::Note(n) => Ok(Post(DbPost::from_json(n, data).await?)), 68 | } 69 | } 70 | } 71 | 72 | #[tokio::main] 73 | async fn main() -> Result<(), anyhow::Error> { 74 | # let config = FederationConfig::builder().domain("example.com").app_data(DbConnection).build().await.unwrap(); 75 | # let data = config.to_request_data(); 76 | let query = "https://example.com/id/413"; 77 | let query_result = ObjectId::::parse(query)? 78 | .dereference(&data) 79 | .await?; 80 | match query_result { 81 | SearchableDbObjects::Post(post) => {} // retrieved object is a post 82 | SearchableDbObjects::User(user) => {} // object is a user 83 | }; 84 | Ok(()) 85 | } 86 | ``` 87 | 88 | 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. 89 | -------------------------------------------------------------------------------- /src/axum/inbox.rs: -------------------------------------------------------------------------------- 1 | //! Handles incoming activities, verifying HTTP signatures and other checks 2 | //! 3 | #![doc = include_str!("../../docs/08_receiving_activities.md")] 4 | 5 | use crate::{ 6 | config::Data, 7 | error::Error, 8 | http_signatures::verify_signature, 9 | parse_received_activity, 10 | traits::{Activity, Actor, Object}, 11 | }; 12 | use axum::{ 13 | body::Body, 14 | extract::FromRequest, 15 | http::{Request, StatusCode}, 16 | response::{IntoResponse, Response}, 17 | }; 18 | use http::{HeaderMap, Method, Uri}; 19 | use serde::de::DeserializeOwned; 20 | use tracing::debug; 21 | 22 | /// Handles incoming activities, verifying HTTP signatures and other checks 23 | pub async fn receive_activity( 24 | activity_data: ActivityData, 25 | data: &Data, 26 | ) -> Result<(), ::Error> 27 | where 28 | A: Activity + DeserializeOwned + Send + 'static, 29 | ActorT: Object + Actor + Send + Sync + 'static, 30 | for<'de2> ::Kind: serde::Deserialize<'de2>, 31 | ::Error: From + From<::Error>, 32 | ::Error: From, 33 | Datatype: Clone, 34 | { 35 | let (activity, actor) = 36 | parse_received_activity::(&activity_data.body, data).await?; 37 | 38 | verify_signature( 39 | &activity_data.headers, 40 | &activity_data.method, 41 | &activity_data.uri, 42 | actor.public_key_pem(), 43 | )?; 44 | 45 | debug!("Receiving activity {}", activity.id().to_string()); 46 | activity.verify(data).await?; 47 | activity.receive(data).await?; 48 | Ok(()) 49 | } 50 | 51 | /// Contains all data that is necessary to receive an activity from an HTTP request 52 | #[derive(Debug)] 53 | pub struct ActivityData { 54 | headers: HeaderMap, 55 | method: Method, 56 | uri: Uri, 57 | body: Vec, 58 | } 59 | 60 | impl FromRequest for ActivityData 61 | where 62 | S: Send + Sync, 63 | { 64 | type Rejection = Response; 65 | 66 | async fn from_request(req: Request, _state: &S) -> Result { 67 | #[allow(unused_mut)] 68 | let (mut parts, body) = req.into_parts(); 69 | 70 | // take the full URI to handle nested routers 71 | // OriginalUri::from_request_parts has an Infallible error type 72 | #[cfg(feature = "axum-original-uri")] 73 | let uri = { 74 | use axum::extract::{FromRequestParts, OriginalUri}; 75 | OriginalUri::from_request_parts(&mut parts, _state) 76 | .await 77 | .expect("infallible") 78 | .0 79 | }; 80 | #[cfg(not(feature = "axum-original-uri"))] 81 | let uri = parts.uri; 82 | 83 | // this wont work if the body is an long running stream 84 | let bytes = axum::body::to_bytes(body, usize::MAX) 85 | .await 86 | .map_err(|err| (StatusCode::INTERNAL_SERVER_ERROR, err.to_string()).into_response())?; 87 | 88 | Ok(Self { 89 | headers: parts.headers, 90 | method: parts.method, 91 | uri, 92 | body: bytes.to_vec(), 93 | }) 94 | } 95 | } 96 | 97 | // TODO: copy tests from actix-web inbox and implement for axum as well 98 | -------------------------------------------------------------------------------- /examples/local_federation/instance.rs: -------------------------------------------------------------------------------- 1 | use crate::{ 2 | objects::{person::DbUser, post::DbPost}, 3 | Error, 4 | }; 5 | use activitypub_federation::config::{FederationConfig, UrlVerifier}; 6 | use anyhow::anyhow; 7 | use async_trait::async_trait; 8 | use std::{ 9 | str::FromStr, 10 | sync::{Arc, Mutex}, 11 | }; 12 | use url::Url; 13 | 14 | pub async fn new_instance( 15 | hostname: &str, 16 | name: String, 17 | ) -> Result, Error> { 18 | let mut system_user = DbUser::new(hostname, "system".into())?; 19 | system_user.ap_id = Url::parse(&format!("http://{}/", hostname))?.into(); 20 | 21 | let local_user = DbUser::new(hostname, name)?; 22 | let database = Arc::new(Database { 23 | system_user: system_user.clone(), 24 | users: Mutex::new(vec![local_user]), 25 | posts: Mutex::new(vec![]), 26 | }); 27 | let config = FederationConfig::builder() 28 | .domain(hostname) 29 | .signed_fetch_actor(&system_user) 30 | .app_data(database) 31 | .url_verifier(Box::new(MyUrlVerifier())) 32 | .debug(true) 33 | .build() 34 | .await?; 35 | Ok(config) 36 | } 37 | 38 | pub type DatabaseHandle = Arc; 39 | 40 | /// Our "database" which contains all known posts and users (local and federated) 41 | pub struct Database { 42 | pub system_user: DbUser, 43 | pub users: Mutex>, 44 | pub posts: Mutex>, 45 | } 46 | 47 | /// Use this to store your federation blocklist, or a database connection needed to retrieve it. 48 | #[derive(Clone)] 49 | struct MyUrlVerifier(); 50 | 51 | #[async_trait] 52 | impl UrlVerifier for MyUrlVerifier { 53 | async fn verify(&self, url: &Url) -> Result<(), activitypub_federation::error::Error> { 54 | if url.domain() == Some("malicious.com") { 55 | Err(activitypub_federation::error::Error::Other( 56 | "malicious domain".into(), 57 | )) 58 | } else { 59 | Ok(()) 60 | } 61 | } 62 | } 63 | 64 | pub enum Webserver { 65 | Axum, 66 | ActixWeb, 67 | } 68 | 69 | impl FromStr for Webserver { 70 | type Err = (); 71 | 72 | fn from_str(s: &str) -> Result { 73 | Ok(match s { 74 | "axum" => Webserver::Axum, 75 | "actix-web" => Webserver::ActixWeb, 76 | _ => panic!("Invalid webserver parameter, must be either `axum` or `actix-web`"), 77 | }) 78 | } 79 | } 80 | 81 | pub fn listen( 82 | config: &FederationConfig, 83 | webserver: &Webserver, 84 | ) -> Result<(), Error> { 85 | match webserver { 86 | Webserver::Axum => crate::axum::http::listen(config)?, 87 | Webserver::ActixWeb => crate::actix_web::http::listen(config)?, 88 | } 89 | Ok(()) 90 | } 91 | 92 | impl Database { 93 | pub fn local_user(&self) -> DbUser { 94 | let lock = self.users.lock().unwrap(); 95 | lock.first().unwrap().clone() 96 | } 97 | 98 | pub fn read_user(&self, name: &str) -> Result { 99 | let db_user = self.local_user(); 100 | if name == db_user.name { 101 | Ok(db_user) 102 | } else { 103 | Err(anyhow!("Invalid user {name}").into()) 104 | } 105 | } 106 | } 107 | -------------------------------------------------------------------------------- /src/fetch/collection_id.rs: -------------------------------------------------------------------------------- 1 | use crate::{config::Data, error::Error, fetch::fetch_object_http, traits::Collection}; 2 | use serde::{Deserialize, Serialize}; 3 | use std::{ 4 | fmt::{Debug, Display, Formatter}, 5 | marker::PhantomData, 6 | }; 7 | use url::Url; 8 | 9 | /// Typed wrapper for Activitypub Collection ID which helps with dereferencing. 10 | #[derive(Serialize, Deserialize)] 11 | #[serde(transparent)] 12 | pub struct CollectionId(Box, PhantomData) 13 | where 14 | Kind: Collection, 15 | for<'de2> ::Kind: Deserialize<'de2>; 16 | 17 | impl CollectionId 18 | where 19 | Kind: Collection, 20 | for<'de2> ::Kind: Deserialize<'de2>, 21 | { 22 | /// Construct a new CollectionId instance 23 | pub fn parse(url: &str) -> Result { 24 | Ok(Self(Box::new(Url::parse(url)?), PhantomData::)) 25 | } 26 | 27 | /// Fetches collection over HTTP 28 | /// 29 | /// Unlike [ObjectId::dereference](crate::fetch::object_id::ObjectId::dereference) this method doesn't do 30 | /// any caching. 31 | pub async fn dereference( 32 | &self, 33 | owner: &::Owner, 34 | data: &Data<::DataType>, 35 | ) -> Result::Error> 36 | where 37 | ::Error: From, 38 | { 39 | let res = fetch_object_http(&self.0, data).await?; 40 | let redirect_url = &res.url; 41 | Kind::verify(&res.object, redirect_url, data).await?; 42 | Kind::from_json(res.object, owner, data).await 43 | } 44 | } 45 | 46 | /// Need to implement clone manually, to avoid requiring Kind to be Clone 47 | impl Clone for CollectionId 48 | where 49 | Kind: Collection, 50 | for<'de2> ::Kind: serde::Deserialize<'de2>, 51 | { 52 | fn clone(&self) -> Self { 53 | CollectionId(self.0.clone(), self.1) 54 | } 55 | } 56 | 57 | impl Display for CollectionId 58 | where 59 | Kind: Collection, 60 | for<'de2> ::Kind: serde::Deserialize<'de2>, 61 | { 62 | fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result { 63 | write!(f, "{}", self.0.as_str()) 64 | } 65 | } 66 | 67 | impl Debug for CollectionId 68 | where 69 | Kind: Collection, 70 | for<'de2> ::Kind: serde::Deserialize<'de2>, 71 | { 72 | fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result { 73 | write!(f, "{}", self.0.as_str()) 74 | } 75 | } 76 | impl From> for Url 77 | where 78 | Kind: Collection, 79 | for<'de2> ::Kind: serde::Deserialize<'de2>, 80 | { 81 | fn from(id: CollectionId) -> Self { 82 | *id.0 83 | } 84 | } 85 | 86 | impl From for CollectionId 87 | where 88 | Kind: Collection + Send + 'static, 89 | for<'de2> ::Kind: serde::Deserialize<'de2>, 90 | { 91 | fn from(url: Url) -> Self { 92 | CollectionId(Box::new(url), PhantomData::) 93 | } 94 | } 95 | 96 | impl PartialEq for CollectionId 97 | where 98 | Kind: Collection, 99 | for<'de2> ::Kind: serde::Deserialize<'de2>, 100 | { 101 | fn eq(&self, other: &Self) -> bool { 102 | self.0.eq(&other.0) && self.1 == other.1 103 | } 104 | } 105 | -------------------------------------------------------------------------------- /src/reqwest_shim.rs: -------------------------------------------------------------------------------- 1 | use crate::error::Error; 2 | use bytes::{BufMut, Bytes, BytesMut}; 3 | use futures_core::{ready, stream::BoxStream, Stream}; 4 | use pin_project_lite::pin_project; 5 | use reqwest::Response; 6 | use std::{ 7 | future::Future, 8 | mem, 9 | pin::Pin, 10 | task::{Context, Poll}, 11 | }; 12 | 13 | /// 1 MB 14 | const MAX_BODY_SIZE: usize = 1024 * 1024; 15 | 16 | pin_project! { 17 | pub struct BytesFuture { 18 | #[pin] 19 | stream: BoxStream<'static, reqwest::Result>, 20 | limit: usize, 21 | aggregator: BytesMut, 22 | } 23 | } 24 | 25 | impl Future for BytesFuture { 26 | type Output = Result; 27 | 28 | fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { 29 | loop { 30 | let this = self.as_mut().project(); 31 | if let Some(chunk) = ready!(this.stream.poll_next(cx)).transpose()? { 32 | this.aggregator.put(chunk); 33 | if this.aggregator.len() > *this.limit { 34 | return Poll::Ready(Err(Error::ResponseBodyLimit)); 35 | } 36 | 37 | continue; 38 | } 39 | 40 | break; 41 | } 42 | 43 | Poll::Ready(Ok(mem::take(&mut self.aggregator).freeze())) 44 | } 45 | } 46 | 47 | pin_project! { 48 | pub struct TextFuture { 49 | #[pin] 50 | future: BytesFuture, 51 | } 52 | } 53 | 54 | impl Future for TextFuture { 55 | type Output = Result; 56 | 57 | fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { 58 | let this = self.project(); 59 | let bytes = ready!(this.future.poll(cx))?; 60 | Poll::Ready(String::from_utf8(bytes.to_vec()).map_err(Error::Utf8)) 61 | } 62 | } 63 | 64 | /// Response shim to work around [an issue in reqwest](https://github.com/seanmonstar/reqwest/issues/1234) (there is an [open pull request](https://github.com/seanmonstar/reqwest/pull/1532) fixing this). 65 | /// 66 | /// Reqwest doesn't limit the response body size by default nor does it offer an option to configure one. 67 | /// Since we have to fetch data from untrusted sources, not restricting the maximum size is a DoS hazard for us. 68 | /// 69 | /// This shim reimplements the `bytes`, `json`, and `text` functions and restricts the bodies length. 70 | /// 71 | /// TODO: Remove this shim as soon as reqwest gets support for size-limited bodies. 72 | pub trait ResponseExt { 73 | type BytesFuture; 74 | type TextFuture; 75 | 76 | /// Size limited version of `bytes` to work around a reqwest issue. Check [`ResponseExt`] docs for details. 77 | fn bytes_limited(self) -> Self::BytesFuture; 78 | /// Size limited version of `text` to work around a reqwest issue. Check [`ResponseExt`] docs for details. 79 | fn text_limited(self) -> Self::TextFuture; 80 | } 81 | 82 | impl ResponseExt for Response { 83 | type BytesFuture = BytesFuture; 84 | type TextFuture = TextFuture; 85 | 86 | fn bytes_limited(self) -> Self::BytesFuture { 87 | BytesFuture { 88 | stream: Box::pin(self.bytes_stream()), 89 | limit: MAX_BODY_SIZE, 90 | aggregator: BytesMut::new(), 91 | } 92 | } 93 | 94 | fn text_limited(self) -> Self::TextFuture { 95 | TextFuture { 96 | future: self.bytes_limited(), 97 | } 98 | } 99 | } 100 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Activitypub-Federation 2 | === 3 | [![Crates.io](https://img.shields.io/crates/v/activitypub-federation.svg)](https://crates.io/crates/activitypub-federation) 4 | [![Documentation](https://shields.io/docsrs/activitypub_federation)](https://docs.rs/activitypub-federation/) 5 | [![Build Status](https://woodpecker.join-lemmy.org/api/badges/LemmyNet/activitypub-federation-rust/status.svg)](https://drone.join-lemmy.org/LemmyNet/activitypub-federation-rust) 6 | 7 | 8 | 9 | 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. 10 | 11 | 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. 12 | 13 | Activitypub 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: 14 | 15 | - **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. 16 | - **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. 17 | - **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. 18 | - **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. 19 | - **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. 20 | 21 | [Visit the documentation](https://docs.rs/activitypub_federation) for a full guide that explains how to create a federated project from scratch. 22 | 23 | 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. 24 | 25 | ## License 26 | 27 | Licensed under [AGPLv3](/LICENSE). 28 | -------------------------------------------------------------------------------- /examples/local_federation/actix_web/http.rs: -------------------------------------------------------------------------------- 1 | use crate::{ 2 | error::Error, 3 | instance::DatabaseHandle, 4 | objects::person::{DbUser, PersonAcceptedActivities}, 5 | }; 6 | use activitypub_federation::{ 7 | actix_web::{inbox::receive_activity, signing_actor}, 8 | config::{Data, FederationConfig, FederationMiddleware}, 9 | fetch::webfinger::{build_webfinger_response, extract_webfinger_name}, 10 | protocol::context::WithContext, 11 | traits::Object, 12 | FEDERATION_CONTENT_TYPE, 13 | }; 14 | use actix_web::{web, web::Bytes, App, HttpRequest, HttpResponse, HttpServer}; 15 | use anyhow::anyhow; 16 | use serde::Deserialize; 17 | use tracing::info; 18 | 19 | pub fn listen(config: &FederationConfig) -> Result<(), Error> { 20 | let hostname = config.domain(); 21 | info!("Listening with actix-web on {hostname}"); 22 | let config = config.clone(); 23 | let server = HttpServer::new(move || { 24 | App::new() 25 | .wrap(FederationMiddleware::new(config.clone())) 26 | .route("/", web::get().to(http_get_system_user)) 27 | .route("/{user}", web::get().to(http_get_user)) 28 | .route("/{user}/inbox", web::post().to(http_post_user_inbox)) 29 | .route("/.well-known/webfinger", web::get().to(webfinger)) 30 | }) 31 | .bind(hostname)? 32 | .run(); 33 | tokio::spawn(server); 34 | Ok(()) 35 | } 36 | 37 | /// Handles requests to fetch system user json over HTTP 38 | pub async fn http_get_system_user(data: Data) -> Result { 39 | let json_user = data.system_user.clone().into_json(&data).await?; 40 | Ok(HttpResponse::Ok() 41 | .content_type(FEDERATION_CONTENT_TYPE) 42 | .json(WithContext::new_default(json_user))) 43 | } 44 | 45 | /// Handles requests to fetch user json over HTTP 46 | pub async fn http_get_user( 47 | request: HttpRequest, 48 | user_name: web::Path, 49 | data: Data, 50 | ) -> Result { 51 | let signed_by = signing_actor::(&request, None, &data).await?; 52 | // here, checks can be made on the actor or the domain to which 53 | // it belongs, to verify whether it is allowed to access this resource 54 | info!( 55 | "Fetch user request is signed by system account {}", 56 | signed_by.id() 57 | ); 58 | 59 | let db_user = data.local_user(); 60 | if user_name.into_inner() == db_user.name { 61 | let json_user = db_user.into_json(&data).await?; 62 | Ok(HttpResponse::Ok() 63 | .content_type(FEDERATION_CONTENT_TYPE) 64 | .json(WithContext::new_default(json_user))) 65 | } else { 66 | Err(anyhow!("Invalid user").into()) 67 | } 68 | } 69 | 70 | /// Handles messages received in user inbox 71 | pub async fn http_post_user_inbox( 72 | request: HttpRequest, 73 | body: Bytes, 74 | data: Data, 75 | ) -> Result { 76 | receive_activity::, DbUser, DatabaseHandle>( 77 | request, body, &data, 78 | ) 79 | .await 80 | } 81 | 82 | #[derive(Deserialize)] 83 | pub struct WebfingerQuery { 84 | resource: String, 85 | } 86 | 87 | pub async fn webfinger( 88 | query: web::Query, 89 | data: Data, 90 | ) -> Result { 91 | let name = extract_webfinger_name(&query.resource, &data)?; 92 | let db_user = data.read_user(name)?; 93 | Ok(HttpResponse::Ok().json(build_webfinger_response( 94 | query.resource.clone(), 95 | db_user.ap_id.into_inner(), 96 | ))) 97 | } 98 | -------------------------------------------------------------------------------- /Cargo.toml: -------------------------------------------------------------------------------- 1 | [package] 2 | name = "activitypub_federation" 3 | version = "0.7.0-beta.8" 4 | edition = "2021" 5 | description = "High-level Activitypub framework" 6 | keywords = ["activitypub", "activitystreams", "federation", "fediverse"] 7 | license = "AGPL-3.0" 8 | repository = "https://github.com/LemmyNet/activitypub-federation-rust" 9 | documentation = "https://docs.rs/activitypub_federation/" 10 | 11 | [features] 12 | default = ["actix-web", "axum"] 13 | actix-web = ["dep:actix-web", "dep:http02"] 14 | axum = ["dep:axum", "dep:tower"] 15 | axum-original-uri = ["dep:axum", "axum/original-uri"] 16 | 17 | [lints.rust] 18 | warnings = "deny" 19 | deprecated = "deny" 20 | 21 | [lints.clippy] 22 | perf = { level = "deny", priority = -1 } 23 | complexity = { level = "deny", priority = -1 } 24 | dbg_macro = "deny" 25 | inefficient_to_string = "deny" 26 | items-after-statements = "deny" 27 | implicit_clone = "deny" 28 | wildcard_imports = "deny" 29 | cast_lossless = "deny" 30 | manual_string_new = "deny" 31 | redundant_closure_for_method_calls = "deny" 32 | unwrap_used = "deny" 33 | 34 | [dependencies] 35 | chrono = { version = "0.4.41", features = ["clock"], default-features = false } 36 | serde = { version = "1.0.219", features = ["derive"] } 37 | async-trait = "0.1.88" 38 | url = { version = "2.5.4", features = ["serde"] } 39 | serde_json = { version = "1.0.140", features = ["preserve_order"] } 40 | reqwest = { version = "0.12.18", default-features = false, features = [ 41 | "json", 42 | "stream", 43 | "rustls-tls", 44 | ] } 45 | reqwest-middleware = "0.4.2" 46 | tracing = "0.1.41" 47 | base64 = "0.22.1" 48 | rand = "0.8.5" 49 | rsa = "0.9.8" 50 | http = "1.3.1" 51 | sha2 = { version = "0.10.9", features = ["oid"] } 52 | thiserror = "2.0.12" 53 | derive_builder = "0.20.2" 54 | itertools = "0.14.0" 55 | dyn-clone = "1.0.19" 56 | enum_delegate = "0.2.0" 57 | httpdate = "1.0.3" 58 | http-signature-normalization-reqwest = { version = "0.13.0", default-features = false, features = [ 59 | "sha-2", 60 | "middleware", 61 | "default-spawner", 62 | ] } 63 | http-signature-normalization = "0.7.0" 64 | bytes = "1.10.1" 65 | futures-core = { version = "0.3.31", default-features = false } 66 | pin-project-lite = "0.2.16" 67 | activitystreams-kinds = "0.3.0" 68 | regex = { version = "1.11.1", default-features = false, features = [ 69 | "std", 70 | "unicode", 71 | ] } 72 | tokio = { version = "1.45.0", features = [ 73 | "sync", 74 | "rt", 75 | "rt-multi-thread", 76 | "time", 77 | ] } 78 | futures = "0.3.31" 79 | moka = { version = "0.12.10", features = ["future"] } 80 | either = "1.15.0" 81 | 82 | # Actix-web 83 | actix-web = { version = "4.11.0", default-features = false, optional = true } 84 | http02 = { package = "http", version = "0.2.12", optional = true } 85 | 86 | # Axum 87 | axum = { version = "0.8.4", features = [ 88 | "json", 89 | ], default-features = false, optional = true } 90 | tower = { version = "0.5.2", optional = true } 91 | 92 | [dev-dependencies] 93 | anyhow = "1.0.98" 94 | axum = { version = "0.8.4", features = ["macros"] } 95 | axum-extra = { version = "0.10.1", features = ["typed-header"] } 96 | env_logger = "0.11.8" 97 | tokio = { version = "1.45.0", features = ["full"] } 98 | 99 | [profile.dev] 100 | strip = "symbols" 101 | debug = 0 102 | 103 | [[example]] 104 | name = "local_federation" 105 | path = "examples/local_federation/main.rs" 106 | 107 | [[example]] 108 | name = "live_federation" 109 | path = "examples/live_federation/main.rs" 110 | 111 | # Speedup RSA key generation 112 | # https://github.com/RustCrypto/RSA/blob/master/README.md#example 113 | [profile.dev.package.num-bigint-dig] 114 | opt-level = 3 115 | -------------------------------------------------------------------------------- /examples/live_federation/objects/post.rs: -------------------------------------------------------------------------------- 1 | use crate::{ 2 | activities::create_post::CreatePost, 3 | database::DatabaseHandle, 4 | error::Error, 5 | generate_object_id, 6 | objects::person::DbUser, 7 | }; 8 | use activitypub_federation::{ 9 | config::Data, 10 | fetch::object_id::ObjectId, 11 | kinds::{object::NoteType, public}, 12 | protocol::{helpers::deserialize_one_or_many, verification::verify_domains_match}, 13 | traits::{Actor, Object}, 14 | }; 15 | use activitystreams_kinds::link::MentionType; 16 | use serde::{Deserialize, Serialize}; 17 | use url::Url; 18 | 19 | #[derive(Clone, Debug)] 20 | pub struct DbPost { 21 | pub text: String, 22 | pub ap_id: ObjectId, 23 | pub creator: ObjectId, 24 | } 25 | 26 | #[derive(Deserialize, Serialize, Debug)] 27 | #[serde(rename_all = "camelCase")] 28 | pub struct Note { 29 | #[serde(rename = "type")] 30 | kind: NoteType, 31 | id: ObjectId, 32 | pub(crate) attributed_to: ObjectId, 33 | #[serde(deserialize_with = "deserialize_one_or_many")] 34 | pub(crate) to: Vec, 35 | content: String, 36 | in_reply_to: Option>, 37 | tag: Vec, 38 | } 39 | 40 | #[derive(Clone, Debug, Deserialize, Serialize)] 41 | pub struct Mention { 42 | pub href: Url, 43 | #[serde(rename = "type")] 44 | pub kind: MentionType, 45 | } 46 | 47 | #[async_trait::async_trait] 48 | impl Object for DbPost { 49 | type DataType = DatabaseHandle; 50 | type Kind = Note; 51 | type Error = Error; 52 | 53 | fn id(&self) -> &Url { 54 | self.ap_id.inner() 55 | } 56 | 57 | async fn read_from_id( 58 | _object_id: Url, 59 | _data: &Data, 60 | ) -> Result, Self::Error> { 61 | Ok(None) 62 | } 63 | 64 | async fn into_json(self, _data: &Data) -> Result { 65 | Ok(Note { 66 | kind: NoteType::Note, 67 | id: self.ap_id, 68 | content: self.text, 69 | attributed_to: self.creator, 70 | to: vec![public()], 71 | tag: vec![], 72 | in_reply_to: None, 73 | }) 74 | } 75 | 76 | async fn verify( 77 | json: &Self::Kind, 78 | expected_domain: &Url, 79 | _data: &Data, 80 | ) -> Result<(), Self::Error> { 81 | verify_domains_match(json.id.inner(), expected_domain)?; 82 | Ok(()) 83 | } 84 | 85 | async fn from_json(json: Self::Kind, data: &Data) -> Result { 86 | println!( 87 | "Received post with content {} and id {}", 88 | &json.content, &json.id 89 | ); 90 | let creator = json.attributed_to.dereference(data).await?; 91 | let post = DbPost { 92 | text: json.content, 93 | ap_id: json.id.clone(), 94 | creator: json.attributed_to.clone(), 95 | }; 96 | 97 | let mention = Mention { 98 | href: creator.ap_id.clone().into_inner(), 99 | kind: Default::default(), 100 | }; 101 | let note = Note { 102 | kind: Default::default(), 103 | id: generate_object_id(data.domain())?.into(), 104 | attributed_to: data.local_user().ap_id, 105 | to: vec![public()], 106 | content: format!("Hello {}", creator.name), 107 | in_reply_to: Some(json.id.clone()), 108 | tag: vec![mention], 109 | }; 110 | CreatePost::send(note, creator.shared_inbox_or_inbox(), data).await?; 111 | 112 | Ok(post) 113 | } 114 | } 115 | -------------------------------------------------------------------------------- /docs/09_sending_activities.md: -------------------------------------------------------------------------------- 1 | ## Sending activities 2 | 3 | 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. 4 | 5 | ``` 6 | # use activitypub_federation::config::FederationConfig; 7 | # use activitypub_federation::activity_queue::queue_activity; 8 | # use activitypub_federation::http_signatures::generate_actor_keypair; 9 | # use activitypub_federation::traits::Actor; 10 | # use activitypub_federation::fetch::object_id::ObjectId; 11 | # use activitypub_federation::traits::tests::{DB_USER, DbConnection, Follow}; 12 | # tokio::runtime::Runtime::new().unwrap().block_on(async { 13 | # let db_connection = DbConnection; 14 | # let config = FederationConfig::builder() 15 | # .domain("example.com") 16 | # .app_data(db_connection) 17 | # .build().await?; 18 | # let data = config.to_request_data(); 19 | # let sender = DB_USER.clone(); 20 | # let recipient = DB_USER.clone(); 21 | let activity = Follow { 22 | actor: ObjectId::parse("https://lemmy.ml/u/nutomic")?, 23 | object: recipient.federation_id.clone().into(), 24 | kind: Default::default(), 25 | id: "https://lemmy.ml/activities/321".try_into()? 26 | }; 27 | let inboxes = vec![recipient.shared_inbox_or_inbox()]; 28 | 29 | queue_activity(&activity, &sender, inboxes, &data).await?; 30 | # Ok::<(), anyhow::Error>(()) 31 | # }).unwrap() 32 | ``` 33 | 34 | 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. 35 | 36 | 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: 37 | 38 | - one minute, in case of service restart 39 | - one hour, in case of instance maintenance 40 | - 2.5 days, in case of major incident with rebuild from backup 41 | 42 | 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. 43 | 44 | In some cases you may want to bypass the builtin activity queue, and implement your own. For example to specify different retry intervals, or to persist retries across application restarts. You can do it with the following code: 45 | ```rust 46 | # use activitypub_federation::config::FederationConfig; 47 | # use activitypub_federation::activity_sending::SendActivityTask; 48 | # use activitypub_federation::http_signatures::generate_actor_keypair; 49 | # use activitypub_federation::traits::Actor; 50 | # use activitypub_federation::fetch::object_id::ObjectId; 51 | # use activitypub_federation::traits::tests::{DB_USER, DbConnection, Follow}; 52 | # tokio::runtime::Runtime::new().unwrap().block_on(async { 53 | # let db_connection = DbConnection; 54 | # let config = FederationConfig::builder() 55 | # .domain("example.com") 56 | # .app_data(db_connection) 57 | # .build().await?; 58 | # let data = config.to_request_data(); 59 | # let sender = DB_USER.clone(); 60 | # let recipient = DB_USER.clone(); 61 | let activity = Follow { 62 | actor: ObjectId::parse("https://lemmy.ml/u/nutomic")?, 63 | object: recipient.federation_id.clone().into(), 64 | kind: Default::default(), 65 | id: "https://lemmy.ml/activities/321".try_into()? 66 | }; 67 | let inboxes = vec![recipient.shared_inbox_or_inbox()]; 68 | 69 | let sends = SendActivityTask::prepare(&activity, &sender, inboxes, &data).await?; 70 | for send in sends { 71 | send.sign_and_send(&data).await?; 72 | } 73 | # Ok::<(), anyhow::Error>(()) 74 | # }).unwrap() 75 | ``` -------------------------------------------------------------------------------- /docs/08_receiving_activities.md: -------------------------------------------------------------------------------- 1 | ## Sending and receiving activities 2 | 3 | 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 [Activity](trait@crate::traits::Activity) trait. 4 | 5 | ``` 6 | # use serde::{Deserialize, Serialize}; 7 | # use url::Url; 8 | # use anyhow::Error; 9 | # use async_trait::async_trait; 10 | # use activitypub_federation::fetch::object_id::ObjectId; 11 | # use activitypub_federation::traits::tests::{DbConnection, DbUser}; 12 | # use activitystreams_kinds::activity::FollowType; 13 | # use activitypub_federation::traits::Activity; 14 | # use activitypub_federation::config::Data; 15 | # async fn send_accept() -> Result<(), Error> { Ok(()) } 16 | 17 | #[derive(Deserialize, Serialize, Clone, Debug)] 18 | #[serde(rename_all = "camelCase")] 19 | pub struct Follow { 20 | pub actor: ObjectId, 21 | pub object: ObjectId, 22 | #[serde(rename = "type")] 23 | pub kind: FollowType, 24 | pub id: Url, 25 | } 26 | 27 | #[async_trait] 28 | impl Activity for Follow { 29 | type DataType = DbConnection; 30 | type Error = Error; 31 | 32 | fn id(&self) -> &Url { 33 | &self.id 34 | } 35 | 36 | fn actor(&self) -> &Url { 37 | self.actor.inner() 38 | } 39 | 40 | async fn verify(&self, _data: &Data) -> Result<(), Self::Error> { 41 | Ok(()) 42 | } 43 | 44 | async fn receive(self, data: &Data) -> Result<(), Self::Error> { 45 | let actor = self.actor.dereference(data).await?; 46 | let followed = self.object.dereference(data).await?; 47 | data.add_follower(followed, actor).await?; 48 | Ok(()) 49 | } 50 | } 51 | ``` 52 | 53 | 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. 54 | 55 | 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. 56 | 57 | ``` 58 | # use axum::response::IntoResponse; 59 | # use activitypub_federation::axum::inbox::{ActivityData, receive_activity}; 60 | # use activitypub_federation::config::Data; 61 | # use activitypub_federation::protocol::context::WithContext; 62 | # use activitypub_federation::traits::Activity; 63 | # use activitypub_federation::traits::tests::{DbConnection, DbUser, Follow}; 64 | # use serde::{Deserialize, Serialize}; 65 | # use url::Url; 66 | 67 | #[derive(Deserialize, Serialize, Debug)] 68 | #[serde(untagged)] 69 | #[enum_delegate::implement(Activity)] 70 | pub enum PersonAcceptedActivities { 71 | Follow(Follow), 72 | } 73 | 74 | async fn http_post_user_inbox( 75 | data: Data, 76 | activity_data: ActivityData, 77 | ) -> impl IntoResponse { 78 | receive_activity::, DbUser, DbConnection>( 79 | activity_data, 80 | &data, 81 | ) 82 | .await.unwrap() 83 | } 84 | ``` 85 | 86 | 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. 87 | 88 | Activity enums can also be nested. 89 | -------------------------------------------------------------------------------- /src/error.rs: -------------------------------------------------------------------------------- 1 | //! Error messages returned by this library 2 | 3 | use crate::fetch::webfinger::WebFingerError; 4 | use http_signature_normalization_reqwest::SignError; 5 | use rsa::{ 6 | errors::Error as RsaError, 7 | pkcs8::{spki::Error as SpkiError, Error as Pkcs8Error}, 8 | }; 9 | use std::string::FromUtf8Error; 10 | use tokio::task::JoinError; 11 | use url::Url; 12 | 13 | /// Error messages returned by this library 14 | #[derive(thiserror::Error, Debug)] 15 | pub enum Error { 16 | /// Object was not found in local database 17 | #[error("Object was not found in local database")] 18 | NotFound, 19 | /// Request limit was reached during fetch 20 | #[error("Request limit was reached during fetch")] 21 | RequestLimit, 22 | /// Response body limit was reached during fetch 23 | #[error("Response body limit was reached during fetch")] 24 | ResponseBodyLimit, 25 | /// Object to be fetched was deleted 26 | #[error("Fetched remote object {0} which was deleted")] 27 | ObjectDeleted(Url), 28 | /// url verification error 29 | #[error("URL failed verification: {0}")] 30 | UrlVerificationError(&'static str), 31 | /// Incoming activity has invalid digest for body 32 | #[error("Incoming activity has invalid digest for body")] 33 | ActivityBodyDigestInvalid, 34 | /// Incoming activity has invalid signature 35 | #[error("Incoming activity has invalid signature")] 36 | ActivitySignatureInvalid, 37 | /// Failed to resolve actor via webfinger 38 | #[error("Failed to resolve actor via webfinger")] 39 | WebfingerResolveFailed(#[from] WebFingerError), 40 | /// Failed to serialize outgoing activity 41 | #[error("Failed to serialize outgoing activity {1}: {0}")] 42 | SerializeOutgoingActivity(serde_json::Error, String), 43 | /// Failed to parse an object fetched from url 44 | #[error("Failed to parse object {1} with content {2}: {0}")] 45 | ParseFetchedObject(serde_json::Error, Url, String), 46 | /// Failed to parse an activity received from another instance 47 | #[error("Failed to parse incoming activity {}: {0}", match .id { 48 | Some(t) => format!("with id {t}"), 49 | None => String::new(), 50 | })] 51 | ParseReceivedActivity { 52 | /// The parse error 53 | err: serde_json::Error, 54 | /// ID of the Activitypub object which caused this error 55 | id: Option, 56 | }, 57 | /// Reqwest Middleware Error 58 | #[error(transparent)] 59 | ReqwestMiddleware(#[from] reqwest_middleware::Error), 60 | /// Reqwest Error 61 | #[error(transparent)] 62 | Reqwest(#[from] reqwest::Error), 63 | /// UTF-8 error 64 | #[error(transparent)] 65 | Utf8(#[from] FromUtf8Error), 66 | /// Url Parse 67 | #[error(transparent)] 68 | UrlParse(#[from] url::ParseError), 69 | /// Signing errors 70 | #[error(transparent)] 71 | SignError(#[from] SignError), 72 | /// Failed to queue activity for sending 73 | #[error("Failed to queue activity {0} for sending")] 74 | ActivityQueueError(Url), 75 | /// Stop activity queue 76 | #[error(transparent)] 77 | StopActivityQueue(#[from] JoinError), 78 | /// Attempted to fetch object which doesn't have valid ActivityPub Content-Type 79 | #[error( 80 | "Attempted to fetch object from {0} which doesn't have valid ActivityPub Content-Type" 81 | )] 82 | FetchInvalidContentType(Url), 83 | /// Attempted to fetch object but the response's id field doesn't match 84 | #[error("Attempted to fetch object from {0} but the response's id field doesn't match")] 85 | FetchWrongId(Url), 86 | /// I/O error from OS 87 | #[error(transparent)] 88 | IoError(#[from] std::io::Error), 89 | /// Other generic errors 90 | #[error("{0}")] 91 | Other(String), 92 | } 93 | 94 | impl From for Error { 95 | fn from(value: RsaError) -> Self { 96 | Error::Other(value.to_string()) 97 | } 98 | } 99 | 100 | impl From for Error { 101 | fn from(value: Pkcs8Error) -> Self { 102 | Error::Other(value.to_string()) 103 | } 104 | } 105 | 106 | impl From for Error { 107 | fn from(value: SpkiError) -> Self { 108 | Error::Other(value.to_string()) 109 | } 110 | } 111 | 112 | impl PartialEq for Error { 113 | fn eq(&self, other: &Self) -> bool { 114 | std::mem::discriminant(self) == std::mem::discriminant(other) 115 | } 116 | } 117 | -------------------------------------------------------------------------------- /src/traits/either.rs: -------------------------------------------------------------------------------- 1 | use super::{Actor, Object}; 2 | use crate::{config::Data, error::Error}; 3 | use async_trait::async_trait; 4 | use chrono::{DateTime, Utc}; 5 | use either::Either; 6 | use serde::{Deserialize, Serialize}; 7 | use std::fmt::Debug; 8 | use url::Url; 9 | 10 | #[doc(hidden)] 11 | #[derive(Serialize, Deserialize)] 12 | #[serde(untagged)] 13 | pub enum UntaggedEither { 14 | Left(L), 15 | Right(R), 16 | } 17 | 18 | #[async_trait] 19 | impl Object for Either 20 | where 21 | T: Object + Object + Send + Sync, 22 | R: Object + Object + Send + Sync, 23 | ::Kind: Send + Sync, 24 | ::Kind: Send + Sync, 25 | D: Sync + Send + Clone, 26 | E: From + Debug, 27 | { 28 | type DataType = D; 29 | type Kind = UntaggedEither; 30 | type Error = E; 31 | 32 | /// `id` field of the object 33 | fn id(&self) -> &Url { 34 | match self { 35 | Either::Left(l) => l.id(), 36 | Either::Right(r) => r.id(), 37 | } 38 | } 39 | 40 | fn last_refreshed_at(&self) -> Option> { 41 | match self { 42 | Either::Left(l) => l.last_refreshed_at(), 43 | Either::Right(r) => r.last_refreshed_at(), 44 | } 45 | } 46 | 47 | async fn read_from_id( 48 | object_id: Url, 49 | data: &Data, 50 | ) -> Result, Self::Error> { 51 | let l = T::read_from_id(object_id.clone(), data).await?; 52 | if let Some(l) = l { 53 | return Ok(Some(Either::Left(l))); 54 | } 55 | let r = R::read_from_id(object_id.clone(), data).await?; 56 | if let Some(r) = r { 57 | return Ok(Some(Either::Right(r))); 58 | } 59 | Ok(None) 60 | } 61 | 62 | async fn delete(&self, data: &Data) -> Result<(), Self::Error> { 63 | match self { 64 | Either::Left(l) => l.delete(data).await, 65 | Either::Right(r) => r.delete(data).await, 66 | } 67 | } 68 | 69 | fn is_deleted(&self) -> bool { 70 | match self { 71 | Either::Left(l) => l.is_deleted(), 72 | Either::Right(r) => r.is_deleted(), 73 | } 74 | } 75 | 76 | async fn into_json(self, data: &Data) -> Result { 77 | Ok(match self { 78 | Either::Left(l) => UntaggedEither::Left(l.into_json(data).await?), 79 | Either::Right(r) => UntaggedEither::Right(r.into_json(data).await?), 80 | }) 81 | } 82 | 83 | async fn verify( 84 | json: &Self::Kind, 85 | expected_domain: &Url, 86 | data: &Data, 87 | ) -> Result<(), Self::Error> { 88 | match json { 89 | UntaggedEither::Left(l) => T::verify(l, expected_domain, data).await?, 90 | UntaggedEither::Right(r) => R::verify(r, expected_domain, data).await?, 91 | }; 92 | Ok(()) 93 | } 94 | 95 | async fn from_json(json: Self::Kind, data: &Data) -> Result { 96 | Ok(match json { 97 | UntaggedEither::Left(l) => Either::Left(T::from_json(l, data).await?), 98 | UntaggedEither::Right(r) => Either::Right(R::from_json(r, data).await?), 99 | }) 100 | } 101 | } 102 | 103 | #[async_trait] 104 | impl Actor for Either 105 | where 106 | T: Actor + Object + Object + Send + Sync + 'static, 107 | R: Actor + Object + Object + Send + Sync + 'static, 108 | ::Kind: Send + Sync, 109 | ::Kind: Send + Sync, 110 | D: Sync + Send + Clone, 111 | E: From + Debug, 112 | { 113 | fn public_key_pem(&self) -> &str { 114 | match self { 115 | Either::Left(l) => l.public_key_pem(), 116 | Either::Right(r) => r.public_key_pem(), 117 | } 118 | } 119 | 120 | fn private_key_pem(&self) -> Option { 121 | match self { 122 | Either::Left(l) => l.private_key_pem(), 123 | Either::Right(r) => r.private_key_pem(), 124 | } 125 | } 126 | 127 | fn inbox(&self) -> Url { 128 | match self { 129 | Either::Left(l) => l.inbox(), 130 | Either::Right(r) => r.inbox(), 131 | } 132 | } 133 | } 134 | -------------------------------------------------------------------------------- /examples/live_federation/objects/person.rs: -------------------------------------------------------------------------------- 1 | use crate::{activities::create_post::CreatePost, database::DatabaseHandle, error::Error}; 2 | use activitypub_federation::{ 3 | config::Data, 4 | fetch::object_id::ObjectId, 5 | http_signatures::generate_actor_keypair, 6 | kinds::actor::PersonType, 7 | protocol::{public_key::PublicKey, verification::verify_domains_match}, 8 | traits::{Activity, Actor, Object}, 9 | }; 10 | use chrono::{DateTime, Utc}; 11 | use serde::{Deserialize, Serialize}; 12 | use std::fmt::Debug; 13 | use url::Url; 14 | 15 | #[derive(Debug, Clone)] 16 | pub struct DbUser { 17 | pub name: String, 18 | pub ap_id: ObjectId, 19 | pub inbox: Url, 20 | // exists for all users (necessary to verify http signatures) 21 | pub public_key: String, 22 | // exists only for local users 23 | pub private_key: Option, 24 | last_refreshed_at: DateTime, 25 | pub followers: Vec, 26 | pub local: bool, 27 | } 28 | 29 | /// List of all activities which this actor can receive. 30 | #[derive(Deserialize, Serialize, Debug)] 31 | #[serde(untagged)] 32 | #[enum_delegate::implement(Activity)] 33 | pub enum PersonAcceptedActivities { 34 | CreateNote(CreatePost), 35 | } 36 | 37 | impl DbUser { 38 | pub fn new(hostname: &str, name: &str) -> Result { 39 | let ap_id = Url::parse(&format!("https://{}/{}", hostname, &name))?.into(); 40 | let inbox = Url::parse(&format!("https://{}/{}/inbox", hostname, &name))?; 41 | let keypair = generate_actor_keypair()?; 42 | Ok(DbUser { 43 | name: name.to_string(), 44 | ap_id, 45 | inbox, 46 | public_key: keypair.public_key, 47 | private_key: Some(keypair.private_key), 48 | last_refreshed_at: Utc::now(), 49 | followers: vec![], 50 | local: true, 51 | }) 52 | } 53 | } 54 | 55 | #[derive(Clone, Debug, Deserialize, Serialize)] 56 | #[serde(rename_all = "camelCase")] 57 | pub struct Person { 58 | #[serde(rename = "type")] 59 | kind: PersonType, 60 | preferred_username: String, 61 | id: ObjectId, 62 | inbox: Url, 63 | public_key: PublicKey, 64 | } 65 | 66 | #[async_trait::async_trait] 67 | impl Object for DbUser { 68 | type DataType = DatabaseHandle; 69 | type Kind = Person; 70 | type Error = Error; 71 | 72 | fn id(&self) -> &Url { 73 | self.ap_id.inner() 74 | } 75 | 76 | fn last_refreshed_at(&self) -> Option> { 77 | Some(self.last_refreshed_at) 78 | } 79 | 80 | async fn read_from_id( 81 | object_id: Url, 82 | data: &Data, 83 | ) -> Result, Self::Error> { 84 | let users = data.users.lock().unwrap(); 85 | let res = users 86 | .clone() 87 | .into_iter() 88 | .find(|u| u.ap_id.inner() == &object_id); 89 | Ok(res) 90 | } 91 | 92 | async fn into_json(self, _data: &Data) -> Result { 93 | Ok(Person { 94 | preferred_username: self.name.clone(), 95 | kind: Default::default(), 96 | id: self.ap_id.clone(), 97 | inbox: self.inbox.clone(), 98 | public_key: self.public_key(), 99 | }) 100 | } 101 | 102 | async fn verify( 103 | json: &Self::Kind, 104 | expected_domain: &Url, 105 | _data: &Data, 106 | ) -> Result<(), Self::Error> { 107 | verify_domains_match(json.id.inner(), expected_domain)?; 108 | Ok(()) 109 | } 110 | 111 | async fn from_json( 112 | json: Self::Kind, 113 | _data: &Data, 114 | ) -> Result { 115 | Ok(DbUser { 116 | name: json.preferred_username, 117 | ap_id: json.id, 118 | inbox: json.inbox, 119 | public_key: json.public_key.public_key_pem, 120 | private_key: None, 121 | last_refreshed_at: Utc::now(), 122 | followers: vec![], 123 | local: false, 124 | }) 125 | } 126 | } 127 | 128 | impl Actor for DbUser { 129 | fn public_key_pem(&self) -> &str { 130 | &self.public_key 131 | } 132 | 133 | fn private_key_pem(&self) -> Option { 134 | self.private_key.clone() 135 | } 136 | 137 | fn inbox(&self) -> Url { 138 | self.inbox.clone() 139 | } 140 | } 141 | -------------------------------------------------------------------------------- /docs/06_http_endpoints_axum.md: -------------------------------------------------------------------------------- 1 | ## HTTP endpoints 2 | 3 | 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. 4 | 5 | ```no_run 6 | # use std::net::SocketAddr; 7 | # use activitypub_federation::config::FederationConfig; 8 | # use activitypub_federation::protocol::context::WithContext; 9 | # use activitypub_federation::axum::json::FederationJson; 10 | # use anyhow::Error; 11 | # use activitypub_federation::traits::tests::Person; 12 | # use activitypub_federation::config::Data; 13 | # use activitypub_federation::traits::tests::DbConnection; 14 | # use axum::extract::Path; 15 | # use activitypub_federation::config::FederationMiddleware; 16 | # use axum::routing::get; 17 | # use crate::activitypub_federation::traits::Object; 18 | # use axum_extra::headers::ContentType; 19 | # use activitypub_federation::FEDERATION_CONTENT_TYPE; 20 | # use axum_extra::TypedHeader; 21 | # use axum::response::IntoResponse; 22 | # use http::HeaderMap; 23 | # async fn generate_user_html(_: String, _: Data) -> axum::response::Response { todo!() } 24 | 25 | #[tokio::main] 26 | async fn main() -> Result<(), Error> { 27 | let data = FederationConfig::builder() 28 | .domain("example.com") 29 | .app_data(DbConnection) 30 | .build().await?; 31 | 32 | let app = axum::Router::new() 33 | .route("/user/:name", get(http_get_user)) 34 | .layer(FederationMiddleware::new(data)); 35 | 36 | let addr = SocketAddr::from(([127, 0, 0, 1], 3000)); 37 | let listener = tokio::net::TcpListener::bind(addr).await?; 38 | tracing::debug!("listening on {}", addr); 39 | axum::serve(listener, app.into_make_service()).await?; 40 | Ok(()) 41 | } 42 | 43 | async fn http_get_user( 44 | header_map: HeaderMap, 45 | Path(name): Path, 46 | data: Data, 47 | ) -> impl IntoResponse { 48 | let accept = header_map.get("accept").map(|v| v.to_str().unwrap()); 49 | if accept == Some(FEDERATION_CONTENT_TYPE) { 50 | let db_user = data.read_local_user(&name).await.unwrap(); 51 | let json_user = db_user.into_json(&data).await.unwrap(); 52 | FederationJson(WithContext::new_default(json_user)).into_response() 53 | } 54 | else { 55 | generate_user_html(name, data).await 56 | } 57 | } 58 | ``` 59 | 60 | 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. 61 | 62 | 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 `FederationJson`. It can now be retrieved with the command `curl -H 'Accept: application/activity+json' ...` introduced earlier, or with `ObjectId`. 63 | 64 | If the `accept` header doesn't match, it renders the user profile as HTML for viewing in a web browser. 65 | 66 | 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`. 67 | 68 | To do this we can implement the following HTTP handler which must be bound to path `.well-known/webfinger`. 69 | 70 | ```rust 71 | # use serde::Deserialize; 72 | # use axum::{extract::Query, Json}; 73 | # use activitypub_federation::config::Data; 74 | # use activitypub_federation::fetch::webfinger::Webfinger; 75 | # use anyhow::Error; 76 | # use activitypub_federation::traits::tests::DbConnection; 77 | # use activitypub_federation::fetch::webfinger::extract_webfinger_name; 78 | # use activitypub_federation::fetch::webfinger::build_webfinger_response; 79 | 80 | #[derive(Deserialize)] 81 | struct WebfingerQuery { 82 | resource: String, 83 | } 84 | 85 | async fn webfinger( 86 | Query(query): Query, 87 | data: Data, 88 | ) -> Result, Error> { 89 | let name = extract_webfinger_name(&query.resource, &data)?; 90 | let db_user = data.read_local_user(name).await?; 91 | Ok(Json(build_webfinger_response(query.resource, db_user.federation_id))) 92 | } 93 | ``` 94 | -------------------------------------------------------------------------------- /src/protocol/helpers.rs: -------------------------------------------------------------------------------- 1 | //! Serde deserialization functions which help to receive differently shaped data 2 | 3 | use serde::{Deserialize, Deserializer}; 4 | 5 | /// Deserialize JSON single value or array into Vec. 6 | /// 7 | /// Useful if your application can handle multiple values for a field, but another federated 8 | /// platform only sends a single one. 9 | /// 10 | /// ``` 11 | /// # use activitypub_federation::protocol::helpers::deserialize_one_or_many; 12 | /// # use url::Url; 13 | /// #[derive(serde::Deserialize)] 14 | /// struct Note { 15 | /// #[serde(deserialize_with = "deserialize_one_or_many")] 16 | /// to: Vec 17 | /// } 18 | /// 19 | /// let single: Note = serde_json::from_str(r#"{"to": "https://example.com/u/alice" }"#)?; 20 | /// assert_eq!(single.to.len(), 1); 21 | /// 22 | /// let multiple: Note = serde_json::from_str( 23 | /// r#"{"to": [ 24 | /// "https://example.com/u/alice", 25 | /// "https://lemmy.ml/u/bob" 26 | /// ]}"#)?; 27 | /// assert_eq!(multiple.to.len(), 2); 28 | /// Ok::<(), anyhow::Error>(()) 29 | pub fn deserialize_one_or_many<'de, T, D>(deserializer: D) -> Result, D::Error> 30 | where 31 | T: Deserialize<'de>, 32 | D: Deserializer<'de>, 33 | { 34 | #[derive(Deserialize)] 35 | #[serde(untagged)] 36 | enum OneOrMany { 37 | One(T), 38 | Many(Vec), 39 | } 40 | 41 | let result: OneOrMany = Deserialize::deserialize(deserializer)?; 42 | Ok(match result { 43 | OneOrMany::Many(list) => list, 44 | OneOrMany::One(value) => vec![value], 45 | }) 46 | } 47 | 48 | /// Deserialize JSON single value or single element array into single value. 49 | /// 50 | /// Useful if your application can only handle a single value for a field, but another federated 51 | /// platform sends single value wrapped in array. Fails if array contains multiple items. 52 | /// 53 | /// ``` 54 | /// # use activitypub_federation::protocol::helpers::deserialize_one; 55 | /// # use url::Url; 56 | /// #[derive(serde::Deserialize)] 57 | /// struct Note { 58 | /// #[serde(deserialize_with = "deserialize_one")] 59 | /// to: [Url; 1] 60 | /// } 61 | /// 62 | /// let note = serde_json::from_str::(r#"{"to": ["https://example.com/u/alice"] }"#); 63 | /// assert!(note.is_ok()); 64 | pub fn deserialize_one<'de, T, D>(deserializer: D) -> Result<[T; 1], D::Error> 65 | where 66 | T: Deserialize<'de>, 67 | D: Deserializer<'de>, 68 | { 69 | #[derive(Deserialize)] 70 | #[serde(untagged)] 71 | enum MaybeArray { 72 | Simple(T), 73 | Array([T; 1]), 74 | } 75 | 76 | let result: MaybeArray = Deserialize::deserialize(deserializer)?; 77 | Ok(match result { 78 | MaybeArray::Simple(value) => [value], 79 | MaybeArray::Array([value]) => [value], 80 | }) 81 | } 82 | 83 | /// Attempts to deserialize item, in case of error falls back to the type's default value. 84 | /// 85 | /// Useful for optional fields which are sent with a different type from another platform, 86 | /// eg object instead of array. Should always be used together with `#[serde(default)]`, so 87 | /// that a mssing value doesn't cause an error. 88 | /// 89 | /// ``` 90 | /// # use activitypub_federation::protocol::helpers::deserialize_skip_error; 91 | /// # use url::Url; 92 | /// #[derive(serde::Deserialize)] 93 | /// struct Note { 94 | /// content: String, 95 | /// #[serde(deserialize_with = "deserialize_skip_error", default)] 96 | /// source: Option 97 | /// } 98 | /// 99 | /// let note = serde_json::from_str::( 100 | /// r#"{ 101 | /// "content": "How are you?", 102 | /// "source": { 103 | /// "content": "How are you?", 104 | /// "mediaType": "text/markdown" 105 | /// } 106 | /// }"#); 107 | /// assert_eq!(note.unwrap().source, None); 108 | /// # Ok::<(), anyhow::Error>(()) 109 | pub fn deserialize_skip_error<'de, T, D>(deserializer: D) -> Result 110 | where 111 | T: Deserialize<'de> + Default, 112 | D: Deserializer<'de>, 113 | { 114 | let value = serde_json::Value::deserialize(deserializer)?; 115 | let inner = T::deserialize(value).unwrap_or_default(); 116 | Ok(inner) 117 | } 118 | 119 | /// Deserialize either single value or last item from an array into an optional field. 120 | pub fn deserialize_last<'de, T, D>(deserializer: D) -> Result, D::Error> 121 | where 122 | T: Deserialize<'de>, 123 | D: Deserializer<'de>, 124 | { 125 | #[derive(Deserialize)] 126 | #[serde(untagged)] 127 | enum MaybeArray { 128 | Simple(T), 129 | Array(Vec), 130 | None, 131 | } 132 | 133 | let result = Deserialize::deserialize(deserializer)?; 134 | Ok(match result { 135 | MaybeArray::Simple(value) => Some(value), 136 | MaybeArray::Array(value) => value.into_iter().last(), 137 | MaybeArray::None => None, 138 | }) 139 | } 140 | 141 | #[cfg(test)] 142 | mod tests { 143 | #[test] 144 | fn deserialize_one_multiple_values() { 145 | use crate::protocol::helpers::deserialize_one; 146 | use url::Url; 147 | #[derive(serde::Deserialize)] 148 | struct Note { 149 | #[serde(deserialize_with = "deserialize_one")] 150 | _to: [Url; 1], 151 | } 152 | 153 | let note = serde_json::from_str::( 154 | r#"{"_to": ["https://example.com/u/alice", "https://example.com/u/bob"] }"#, 155 | ); 156 | assert!(note.is_err()); 157 | } 158 | } 159 | -------------------------------------------------------------------------------- /src/traits/tests.rs: -------------------------------------------------------------------------------- 1 | #![doc(hidden)] 2 | #![allow(clippy::unwrap_used)] 3 | //! Some impls of these traits for use in tests. Dont use this from external crates. 4 | //! 5 | //! TODO: Should be using `cfg[doctest]` but blocked by 6 | 7 | use super::{async_trait, Activity, Actor, Data, Debug, Object, PublicKey, Url}; 8 | use crate::{ 9 | error::Error, 10 | fetch::object_id::ObjectId, 11 | http_signatures::{generate_actor_keypair, Keypair}, 12 | protocol::verification::verify_domains_match, 13 | }; 14 | use activitystreams_kinds::{activity::FollowType, actor::PersonType}; 15 | use serde::{Deserialize, Serialize}; 16 | use std::sync::LazyLock; 17 | 18 | #[derive(Clone)] 19 | pub struct DbConnection; 20 | 21 | impl DbConnection { 22 | pub async fn read_post_from_json_id(&self, _: Url) -> Result, Error> { 23 | Ok(None) 24 | } 25 | pub async fn read_local_user(&self, _: &str) -> Result { 26 | todo!() 27 | } 28 | pub async fn upsert(&self, _: &T) -> Result<(), Error> { 29 | Ok(()) 30 | } 31 | pub async fn add_follower(&self, _: DbUser, _: DbUser) -> Result<(), Error> { 32 | Ok(()) 33 | } 34 | } 35 | 36 | #[derive(Clone, Debug, Deserialize, Serialize)] 37 | #[serde(rename_all = "camelCase")] 38 | pub struct Person { 39 | #[serde(rename = "type")] 40 | pub kind: PersonType, 41 | pub preferred_username: String, 42 | pub id: ObjectId, 43 | pub inbox: Url, 44 | pub public_key: PublicKey, 45 | } 46 | #[derive(Debug, Clone)] 47 | pub struct DbUser { 48 | pub name: String, 49 | pub federation_id: Url, 50 | pub inbox: Url, 51 | pub public_key: String, 52 | #[allow(dead_code)] 53 | private_key: Option, 54 | pub followers: Vec, 55 | pub local: bool, 56 | } 57 | 58 | pub static DB_USER_KEYPAIR: LazyLock = LazyLock::new(|| generate_actor_keypair().unwrap()); 59 | 60 | pub static DB_USER: LazyLock = LazyLock::new(|| DbUser { 61 | name: String::new(), 62 | federation_id: "https://localhost/123".parse().unwrap(), 63 | inbox: "https://localhost/123/inbox".parse().unwrap(), 64 | public_key: DB_USER_KEYPAIR.public_key.clone(), 65 | private_key: Some(DB_USER_KEYPAIR.private_key.clone()), 66 | followers: vec![], 67 | local: false, 68 | }); 69 | 70 | #[async_trait] 71 | impl Object for DbUser { 72 | type DataType = DbConnection; 73 | type Kind = Person; 74 | type Error = Error; 75 | 76 | fn id(&self) -> &Url { 77 | &self.federation_id 78 | } 79 | 80 | async fn read_from_id( 81 | _object_id: Url, 82 | _data: &Data, 83 | ) -> Result, Self::Error> { 84 | Ok(Some(DB_USER.clone())) 85 | } 86 | 87 | async fn into_json(self, _data: &Data) -> Result { 88 | Ok(Person { 89 | preferred_username: self.name.clone(), 90 | kind: Default::default(), 91 | id: self.federation_id.clone().into(), 92 | inbox: self.inbox.clone(), 93 | public_key: self.public_key(), 94 | }) 95 | } 96 | 97 | async fn verify( 98 | json: &Self::Kind, 99 | expected_domain: &Url, 100 | _data: &Data, 101 | ) -> Result<(), Self::Error> { 102 | verify_domains_match(json.id.inner(), expected_domain)?; 103 | Ok(()) 104 | } 105 | 106 | async fn from_json( 107 | json: Self::Kind, 108 | _data: &Data, 109 | ) -> Result { 110 | Ok(DbUser { 111 | name: json.preferred_username, 112 | federation_id: json.id.into(), 113 | inbox: json.inbox, 114 | public_key: json.public_key.public_key_pem, 115 | private_key: None, 116 | followers: vec![], 117 | local: false, 118 | }) 119 | } 120 | } 121 | 122 | impl Actor for DbUser { 123 | fn public_key_pem(&self) -> &str { 124 | &self.public_key 125 | } 126 | 127 | fn private_key_pem(&self) -> Option { 128 | self.private_key.clone() 129 | } 130 | 131 | fn inbox(&self) -> Url { 132 | self.inbox.clone() 133 | } 134 | } 135 | 136 | #[derive(Deserialize, Serialize, Clone, Debug)] 137 | #[serde(rename_all = "camelCase")] 138 | pub struct Follow { 139 | pub actor: ObjectId, 140 | pub object: ObjectId, 141 | #[serde(rename = "type")] 142 | pub kind: FollowType, 143 | pub id: Url, 144 | } 145 | 146 | #[async_trait] 147 | impl Activity for Follow { 148 | type DataType = DbConnection; 149 | type Error = Error; 150 | 151 | fn id(&self) -> &Url { 152 | &self.id 153 | } 154 | 155 | fn actor(&self) -> &Url { 156 | self.actor.inner() 157 | } 158 | 159 | async fn verify(&self, _: &Data) -> Result<(), Self::Error> { 160 | Ok(()) 161 | } 162 | 163 | async fn receive(self, _data: &Data) -> Result<(), Self::Error> { 164 | Ok(()) 165 | } 166 | } 167 | 168 | #[derive(Clone, Debug, Deserialize, Serialize)] 169 | #[serde(rename_all = "camelCase")] 170 | pub struct Note {} 171 | #[derive(Debug, Clone)] 172 | pub struct DbPost { 173 | pub federation_id: Url, 174 | } 175 | 176 | #[async_trait] 177 | impl Object for DbPost { 178 | type DataType = DbConnection; 179 | type Kind = Note; 180 | type Error = Error; 181 | 182 | fn id(&self) -> &Url { 183 | todo!() 184 | } 185 | 186 | async fn read_from_id(_: Url, _: &Data) -> Result, Self::Error> { 187 | todo!() 188 | } 189 | 190 | async fn into_json(self, _: &Data) -> Result { 191 | todo!() 192 | } 193 | 194 | async fn verify(_: &Self::Kind, _: &Url, _: &Data) -> Result<(), Self::Error> { 195 | todo!() 196 | } 197 | 198 | async fn from_json(_: Self::Kind, _: &Data) -> Result { 199 | todo!() 200 | } 201 | } 202 | -------------------------------------------------------------------------------- /docs/03_federating_users.md: -------------------------------------------------------------------------------- 1 | ## Federating users 2 | 3 | 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. 4 | 5 | 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. 6 | 7 | ```text 8 | $ curl -H 'Accept: application/activity+json' https://mastodon.social/@LemmyDev | jq 9 | { 10 | "id": "https://mastodon.social/users/LemmyDev", 11 | "type": "Person", 12 | "preferredUsername": "LemmyDev", 13 | "name": "Lemmy", 14 | "inbox": "https://mastodon.social/users/LemmyDev/inbox", 15 | "outbox": "https://mastodon.social/users/LemmyDev/outbox", 16 | "publicKey": { 17 | "id": "https://mastodon.social/users/LemmyDev#main-key", 18 | "owner": "https://mastodon.social/users/LemmyDev", 19 | "publicKeyPem": "..." 20 | }, 21 | ... 22 | } 23 | ``` 24 | 25 | The most important fields are: 26 | - `id`: Unique identifier for this object. At the same time it is the URL where we can fetch the object from 27 | - `type`: The type of this object 28 | - `preferredUsername`: Immutable username which was chosen at signup and is used in URLs as well as in mentions like `@LemmyDev@mastodon.social` 29 | - `name`: Displayname which can be freely changed at any time 30 | - `inbox`: URL where incoming activities are delivered to, treated in a later section 31 | see xx document for a definition of each field 32 | - `publicKey`: Key which is used for [HTTP Signatures](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures) 33 | 34 | 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. 35 | 36 | Based on this we can define the following minimal struct to (de)serialize a `Person` with serde. 37 | 38 | ```rust 39 | # use activitypub_federation::protocol::public_key::PublicKey; 40 | # use activitypub_federation::fetch::object_id::ObjectId; 41 | # use serde::{Deserialize, Serialize}; 42 | # use activitystreams_kinds::actor::PersonType; 43 | # use url::Url; 44 | # use activitypub_federation::traits::tests::DbUser; 45 | 46 | #[derive(Deserialize, Serialize)] 47 | #[serde(rename_all = "camelCase")] 48 | pub struct Person { 49 | id: ObjectId, 50 | #[serde(rename = "type")] 51 | kind: PersonType, 52 | preferred_username: String, 53 | name: String, 54 | inbox: Url, 55 | outbox: Url, 56 | public_key: PublicKey, 57 | } 58 | ``` 59 | 60 | `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. 61 | 62 | `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. 63 | 64 | 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. 65 | 66 | ```rust 67 | # use url::Url; 68 | # use chrono::{DateTime, Utc}; 69 | 70 | pub struct DbUser { 71 | pub id: i32, 72 | pub name: String, 73 | pub display_name: String, 74 | pub password_hash: Option, 75 | pub email: Option, 76 | pub federation_id: Url, 77 | pub inbox: Url, 78 | pub outbox: Url, 79 | pub local: bool, 80 | pub public_key: String, 81 | pub private_key: Option, 82 | pub last_refreshed_at: DateTime, 83 | } 84 | ``` 85 | 86 | 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 `federation_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. 87 | 88 | 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 (`federation_id`, `public_key` etc). 89 | 90 | Finally we need to implement the traits [Object](crate::traits::Object) and [Actor](crate::traits::Actor) for `DbUser`. These traits are used to convert between `Person` and `DbUser` types. [Object::from_json](crate::traits::Object::from_json) must store the received object in database, so that it can later be retrieved without network calls using [Object::read_from_id](crate::traits::Object::read_from_id). Refer to the documentation for more details. 91 | -------------------------------------------------------------------------------- /examples/local_federation/objects/person.rs: -------------------------------------------------------------------------------- 1 | use crate::{ 2 | activities::{accept::Accept, create_post::CreatePost, follow::Follow}, 3 | error::Error, 4 | instance::DatabaseHandle, 5 | objects::post::DbPost, 6 | utils::generate_object_id, 7 | }; 8 | use activitypub_federation::{ 9 | activity_queue::queue_activity, 10 | activity_sending::SendActivityTask, 11 | config::Data, 12 | fetch::{object_id::ObjectId, webfinger::webfinger_resolve_actor}, 13 | http_signatures::generate_actor_keypair, 14 | kinds::actor::PersonType, 15 | protocol::{context::WithContext, public_key::PublicKey, verification::verify_domains_match}, 16 | traits::{Activity, Actor, Object}, 17 | }; 18 | use chrono::{DateTime, Utc}; 19 | use serde::{Deserialize, Serialize}; 20 | use std::fmt::Debug; 21 | use url::Url; 22 | 23 | #[derive(Debug, Clone)] 24 | pub struct DbUser { 25 | pub name: String, 26 | pub ap_id: ObjectId, 27 | pub inbox: Url, 28 | // exists for all users (necessary to verify http signatures) 29 | public_key: String, 30 | // exists only for local users 31 | private_key: Option, 32 | last_refreshed_at: DateTime, 33 | pub followers: Vec, 34 | pub local: bool, 35 | } 36 | 37 | /// List of all activities which this actor can receive. 38 | #[derive(Deserialize, Serialize, Debug)] 39 | #[serde(untagged)] 40 | #[enum_delegate::implement(Activity)] 41 | pub enum PersonAcceptedActivities { 42 | Follow(Follow), 43 | Accept(Accept), 44 | CreateNote(CreatePost), 45 | } 46 | 47 | impl DbUser { 48 | pub fn new(hostname: &str, name: String) -> Result { 49 | let ap_id = Url::parse(&format!("http://{}/{}", hostname, &name))?.into(); 50 | let inbox = Url::parse(&format!("http://{}/{}/inbox", hostname, &name))?; 51 | let keypair = generate_actor_keypair()?; 52 | Ok(DbUser { 53 | name, 54 | ap_id, 55 | inbox, 56 | public_key: keypair.public_key, 57 | private_key: Some(keypair.private_key), 58 | last_refreshed_at: Utc::now(), 59 | followers: vec![], 60 | local: true, 61 | }) 62 | } 63 | } 64 | 65 | #[derive(Clone, Debug, Deserialize, Serialize)] 66 | #[serde(rename_all = "camelCase")] 67 | pub struct Person { 68 | #[serde(rename = "type")] 69 | kind: PersonType, 70 | preferred_username: String, 71 | id: ObjectId, 72 | inbox: Url, 73 | public_key: PublicKey, 74 | } 75 | 76 | impl DbUser { 77 | pub fn followers(&self) -> &Vec { 78 | &self.followers 79 | } 80 | 81 | pub fn followers_url(&self) -> Result { 82 | Ok(Url::parse(&format!("{}/followers", self.ap_id.inner()))?) 83 | } 84 | 85 | pub async fn follow(&self, other: &str, data: &Data) -> Result<(), Error> { 86 | let other: DbUser = webfinger_resolve_actor(other, data).await?; 87 | let id = generate_object_id(data.domain())?; 88 | let follow = Follow::new(self.ap_id.clone(), other.ap_id.clone(), id.clone()); 89 | self.send(follow, vec![other.shared_inbox_or_inbox()], false, data) 90 | .await?; 91 | Ok(()) 92 | } 93 | 94 | pub async fn post(&self, post: DbPost, data: &Data) -> Result<(), Error> { 95 | let id = generate_object_id(data.domain())?; 96 | let create = CreatePost::new(post.into_json(data).await?, id.clone()); 97 | let mut inboxes = vec![]; 98 | for f in self.followers.clone() { 99 | let user: DbUser = ObjectId::from(f).dereference(data).await?; 100 | inboxes.push(user.shared_inbox_or_inbox()); 101 | } 102 | self.send(create, inboxes, true, data).await?; 103 | Ok(()) 104 | } 105 | 106 | pub(crate) async fn send( 107 | &self, 108 | activity: A, 109 | recipients: Vec, 110 | use_queue: bool, 111 | data: &Data, 112 | ) -> Result<(), Error> 113 | where 114 | A: Activity + Serialize + Debug + Send + Sync, 115 | ::Error: From + From, 116 | { 117 | let activity = WithContext::new_default(activity); 118 | // Send through queue in some cases and bypass it in others to test both code paths 119 | if use_queue { 120 | queue_activity(&activity, self, recipients, data).await?; 121 | } else { 122 | let sends = SendActivityTask::prepare(&activity, self, recipients, data).await?; 123 | for send in sends { 124 | send.sign_and_send(data).await?; 125 | } 126 | } 127 | Ok(()) 128 | } 129 | } 130 | 131 | #[async_trait::async_trait] 132 | impl Object for DbUser { 133 | type DataType = DatabaseHandle; 134 | type Kind = Person; 135 | type Error = Error; 136 | 137 | fn id(&self) -> &Url { 138 | self.ap_id.inner() 139 | } 140 | 141 | fn last_refreshed_at(&self) -> Option> { 142 | Some(self.last_refreshed_at) 143 | } 144 | 145 | async fn read_from_id( 146 | object_id: Url, 147 | data: &Data, 148 | ) -> Result, Self::Error> { 149 | let users = data.users.lock().unwrap(); 150 | let res = users 151 | .clone() 152 | .into_iter() 153 | .find(|u| u.ap_id.inner() == &object_id); 154 | Ok(res) 155 | } 156 | 157 | async fn into_json(self, _data: &Data) -> Result { 158 | Ok(Person { 159 | preferred_username: self.name.clone(), 160 | kind: Default::default(), 161 | id: self.ap_id.clone(), 162 | inbox: self.inbox.clone(), 163 | public_key: self.public_key(), 164 | }) 165 | } 166 | 167 | async fn verify( 168 | json: &Self::Kind, 169 | expected_domain: &Url, 170 | _data: &Data, 171 | ) -> Result<(), Self::Error> { 172 | verify_domains_match(json.id.inner(), expected_domain)?; 173 | Ok(()) 174 | } 175 | 176 | async fn from_json(json: Self::Kind, data: &Data) -> Result { 177 | let user = DbUser { 178 | name: json.preferred_username, 179 | ap_id: json.id, 180 | inbox: json.inbox, 181 | public_key: json.public_key.public_key_pem, 182 | private_key: None, 183 | last_refreshed_at: Utc::now(), 184 | followers: vec![], 185 | local: false, 186 | }; 187 | let mut mutex = data.users.lock().unwrap(); 188 | mutex.push(user.clone()); 189 | Ok(user) 190 | } 191 | } 192 | 193 | impl Actor for DbUser { 194 | fn public_key_pem(&self) -> &str { 195 | &self.public_key 196 | } 197 | 198 | fn private_key_pem(&self) -> Option { 199 | self.private_key.clone() 200 | } 201 | 202 | fn inbox(&self) -> Url { 203 | self.inbox.clone() 204 | } 205 | } 206 | -------------------------------------------------------------------------------- /src/fetch/mod.rs: -------------------------------------------------------------------------------- 1 | //! Utilities for fetching data from other servers 2 | //! 3 | #![doc = include_str!("../../docs/07_fetching_data.md")] 4 | 5 | use crate::{ 6 | config::Data, 7 | error::{Error, Error::ParseFetchedObject}, 8 | extract_id, 9 | http_signatures::sign_request, 10 | reqwest_shim::ResponseExt, 11 | FEDERATION_CONTENT_TYPE, 12 | }; 13 | use bytes::Bytes; 14 | use http::{header::LOCATION, HeaderValue, StatusCode}; 15 | use serde::de::DeserializeOwned; 16 | use std::sync::atomic::Ordering; 17 | use tracing::info; 18 | use url::Url; 19 | 20 | /// Typed wrapper for collection IDs 21 | pub mod collection_id; 22 | /// Typed wrapper for Activitypub Object ID which helps with dereferencing and caching 23 | pub mod object_id; 24 | /// Resolves identifiers of the form `name@example.com` 25 | pub mod webfinger; 26 | 27 | /// Response from fetching a remote object 28 | pub struct FetchObjectResponse { 29 | /// The resolved object 30 | pub object: Kind, 31 | /// Contains the final URL (different from request URL in case of redirect) 32 | pub url: Url, 33 | content_type: Option, 34 | object_id: Option, 35 | } 36 | 37 | /// Fetch a remote object over HTTP and convert to `Kind`. 38 | /// 39 | /// [crate::fetch::object_id::ObjectId::dereference] wraps this function to add caching and 40 | /// conversion to database type. Only use this function directly in exceptional cases where that 41 | /// behaviour is undesired. 42 | /// 43 | /// Every time an object is fetched via HTTP, [RequestData.request_counter] is incremented by one. 44 | /// If the value exceeds [FederationSettings.http_fetch_limit], the request is aborted with 45 | /// [Error::RequestLimit]. This prevents denial of service attacks where an attack triggers 46 | /// infinite, recursive fetching of data. 47 | /// 48 | /// The `Accept` header will be set to the content of [`FEDERATION_CONTENT_TYPE`]. When parsing the 49 | /// response it ensures that it has a valid `Content-Type` header as defined by ActivityPub, to 50 | /// prevent security vulnerabilities like [this one](https://github.com/mastodon/mastodon/security/advisories/GHSA-jhrq-qvrm-qr36). 51 | /// Additionally it checks that the `id` field is identical to the fetch URL (after redirects). 52 | pub async fn fetch_object_http( 53 | url: &Url, 54 | data: &Data, 55 | ) -> Result, Error> { 56 | static FETCH_CONTENT_TYPE: HeaderValue = HeaderValue::from_static(FEDERATION_CONTENT_TYPE); 57 | const VALID_RESPONSE_CONTENT_TYPES: [&str; 3] = [ 58 | FEDERATION_CONTENT_TYPE, // lemmy 59 | r#"application/ld+json; profile="https://www.w3.org/ns/activitystreams""#, // activitypub standard 60 | r#"application/activity+json; charset=utf-8"#, // mastodon 61 | ]; 62 | let res = fetch_object_http_with_accept(url, data, &FETCH_CONTENT_TYPE, false).await?; 63 | 64 | // Ensure correct content-type to prevent vulnerabilities, with case insensitive comparison. 65 | let content_type = res 66 | .content_type 67 | .as_ref() 68 | .and_then(|c| Some(c.to_str().ok()?.to_lowercase())) 69 | .ok_or(Error::FetchInvalidContentType(res.url.clone()))?; 70 | if !VALID_RESPONSE_CONTENT_TYPES.contains(&content_type.as_str()) { 71 | return Err(Error::FetchInvalidContentType(res.url)); 72 | } 73 | 74 | // Ensure id field matches final url after redirect 75 | if res.object_id.as_ref() != Some(&res.url) { 76 | if let Some(res_object_id) = res.object_id { 77 | data.config.verify_url_valid(&res_object_id).await?; 78 | // If id is different but still on the same domain, attempt to request object 79 | // again from url in id field. 80 | if res_object_id.domain() == res.url.domain() { 81 | return Box::pin(fetch_object_http(&res_object_id, data)).await; 82 | } 83 | } 84 | // Failed to fetch the object from its specified id 85 | return Err(Error::FetchWrongId(res.url)); 86 | } 87 | 88 | // Dont allow fetching local object. Only check this after the request as a local url 89 | // may redirect to a remote object. 90 | if data.config.is_local_url(&res.url) { 91 | return Err(Error::NotFound); 92 | } 93 | 94 | Ok(res) 95 | } 96 | 97 | /// Fetch a remote object over HTTP and convert to `Kind`. This function works exactly as 98 | /// [`fetch_object_http`] except that the `Accept` header is specified in `content_type`. 99 | async fn fetch_object_http_with_accept( 100 | url: &Url, 101 | data: &Data, 102 | content_type: &HeaderValue, 103 | recursive: bool, 104 | ) -> Result, Error> { 105 | let config = &data.config; 106 | config.verify_url_valid(url).await?; 107 | info!("Fetching remote object {}", url.to_string()); 108 | 109 | let mut counter = data.request_counter.0.fetch_add(1, Ordering::SeqCst); 110 | // fetch_add returns old value so we need to increment manually here 111 | counter += 1; 112 | if counter > config.http_fetch_limit { 113 | return Err(Error::RequestLimit); 114 | } 115 | 116 | let req = config 117 | .client 118 | .get(url.as_str()) 119 | .header("Accept", content_type) 120 | .timeout(config.request_timeout); 121 | 122 | let res = if let Some((actor_id, private_key_pem)) = config.signed_fetch_actor.as_deref() { 123 | let req = sign_request( 124 | req, 125 | actor_id, 126 | Bytes::new(), 127 | private_key_pem.clone(), 128 | data.config.http_signature_compat, 129 | ) 130 | .await?; 131 | config.client.execute(req).await? 132 | } else { 133 | req.send().await? 134 | }; 135 | 136 | // Allow a single redirect using recursion. Further redirects are ignored. 137 | let location = res.headers().get(LOCATION).and_then(|l| l.to_str().ok()); 138 | if let (Some(location), false) = (location, recursive) { 139 | let location = location.parse()?; 140 | return Box::pin(fetch_object_http_with_accept( 141 | &location, 142 | data, 143 | content_type, 144 | true, 145 | )) 146 | .await; 147 | } 148 | 149 | if res.status() == StatusCode::GONE { 150 | return Err(Error::ObjectDeleted(url.clone())); 151 | } 152 | 153 | let url = res.url().clone(); 154 | let content_type = res.headers().get("Content-Type").cloned(); 155 | let text = res.bytes_limited().await?; 156 | let object_id = extract_id(&text).ok(); 157 | 158 | match serde_json::from_slice(&text) { 159 | Ok(object) => Ok(FetchObjectResponse { 160 | object, 161 | url, 162 | content_type, 163 | object_id, 164 | }), 165 | Err(e) => Err(ParseFetchedObject( 166 | e, 167 | url, 168 | String::from_utf8(Vec::from(text))?, 169 | )), 170 | } 171 | } 172 | 173 | #[cfg(test)] 174 | #[allow(clippy::unwrap_used)] 175 | mod tests { 176 | use super::*; 177 | use crate::{ 178 | config::FederationConfig, 179 | traits::tests::{DbConnection, Person}, 180 | }; 181 | 182 | #[tokio::test] 183 | async fn test_request_limit() -> Result<(), Error> { 184 | let config = FederationConfig::builder() 185 | .domain("example.com") 186 | .app_data(DbConnection) 187 | .http_fetch_limit(0) 188 | .build() 189 | .await 190 | .unwrap(); 191 | let data = config.to_request_data(); 192 | 193 | let fetch_url = "https://example.net/".to_string(); 194 | 195 | let res: Result, Error> = 196 | fetch_object_http(&Url::parse(&fetch_url).map_err(Error::UrlParse)?, &data).await; 197 | 198 | assert_eq!(res.err(), Some(Error::RequestLimit)); 199 | 200 | Ok(()) 201 | } 202 | } 203 | -------------------------------------------------------------------------------- /src/fetch/object_id.rs: -------------------------------------------------------------------------------- 1 | use crate::{config::Data, error::Error, fetch::fetch_object_http, traits::Object}; 2 | use chrono::{DateTime, Duration as ChronoDuration, Utc}; 3 | use serde::{Deserialize, Serialize}; 4 | use std::{ 5 | fmt::{Debug, Display, Formatter}, 6 | marker::PhantomData, 7 | str::FromStr, 8 | }; 9 | use url::Url; 10 | 11 | impl FromStr for ObjectId 12 | where 13 | T: Object + Send + Sync + Debug + 'static, 14 | for<'de2> ::Kind: Deserialize<'de2>, 15 | { 16 | type Err = url::ParseError; 17 | 18 | fn from_str(s: &str) -> Result { 19 | ObjectId::parse(s) 20 | } 21 | } 22 | /// Typed wrapper for Activitypub Object ID which helps with dereferencing and caching. 23 | /// 24 | /// It provides convenient methods for fetching the object from remote server or local database. 25 | /// Objects are automatically cached locally, so they don't have to be fetched every time. Much of 26 | /// the crate functionality relies on this wrapper. 27 | /// 28 | /// Every time an object is fetched via HTTP, [RequestData.request_counter] is incremented by one. 29 | /// If the value exceeds [FederationSettings.http_fetch_limit], the request is aborted with 30 | /// [Error::RequestLimit]. This prevents denial of service attacks where an attack triggers 31 | /// infinite, recursive fetching of data. 32 | /// 33 | /// ``` 34 | /// # use activitypub_federation::fetch::object_id::ObjectId; 35 | /// # use activitypub_federation::config::FederationConfig; 36 | /// # use activitypub_federation::error::Error::NotFound; 37 | /// # use activitypub_federation::traits::tests::{DbConnection, DbUser}; 38 | /// # tokio::runtime::Runtime::new().unwrap().block_on(async { 39 | /// # let db_connection = DbConnection; 40 | /// let config = FederationConfig::builder() 41 | /// .domain("example.com") 42 | /// .app_data(db_connection) 43 | /// .build().await?; 44 | /// let request_data = config.to_request_data(); 45 | /// let object_id = ObjectId::::parse("https://lemmy.ml/u/nutomic")?; 46 | /// // Attempt to fetch object from local database or fall back to remote server 47 | /// let user = object_id.dereference(&request_data).await; 48 | /// assert!(user.is_ok()); 49 | /// // Now you can also read the object from local database without network requests 50 | /// let user = object_id.dereference_local(&request_data).await; 51 | /// assert!(user.is_ok()); 52 | /// # Ok::<(), anyhow::Error>(()) 53 | /// # }).unwrap(); 54 | /// ``` 55 | #[derive(Serialize, Deserialize)] 56 | #[serde(transparent)] 57 | pub struct ObjectId(Box, PhantomData) 58 | where 59 | Kind: Object, 60 | for<'de2> ::Kind: Deserialize<'de2>; 61 | 62 | impl ObjectId 63 | where 64 | Kind: Object + Send + Sync + Debug + 'static, 65 | for<'de2> ::Kind: Deserialize<'de2>, 66 | { 67 | /// Construct a new objectid instance 68 | pub fn parse(url: &str) -> Result { 69 | Ok(Self(Box::new(Url::parse(url)?), PhantomData::)) 70 | } 71 | 72 | /// Returns a reference to the wrapped URL value 73 | pub fn inner(&self) -> &Url { 74 | &self.0 75 | } 76 | 77 | /// Returns the wrapped URL value 78 | pub fn into_inner(self) -> Url { 79 | *self.0 80 | } 81 | 82 | /// Fetches an activitypub object, either from local database (if possible), or over http. 83 | pub async fn dereference( 84 | &self, 85 | data: &Data<::DataType>, 86 | ) -> Result::Error> 87 | where 88 | ::Error: From, 89 | { 90 | let db_object = self.dereference_from_db(data).await?; 91 | 92 | // object found in database 93 | if let Some(object) = db_object { 94 | if let Some(last_refreshed_at) = object.last_refreshed_at() { 95 | let is_local = self.is_local(data); 96 | if !is_local && should_refetch_object(last_refreshed_at) { 97 | // object is outdated and should be refetched 98 | return self.dereference_from_http(data, Some(object)).await; 99 | } 100 | } 101 | Ok(object) 102 | } 103 | // object not found, need to fetch over http 104 | else { 105 | self.dereference_from_http(data, None).await 106 | } 107 | } 108 | 109 | /// If this is a remote object, fetch it from origin instance unconditionally to get the 110 | /// latest version, regardless of refresh interval. 111 | pub async fn dereference_forced( 112 | &self, 113 | data: &Data<::DataType>, 114 | ) -> Result::Error> 115 | where 116 | ::Error: From, 117 | { 118 | if data.config.is_local_url(&self.0) { 119 | self.dereference_from_db(data) 120 | .await 121 | .map(|o| o.ok_or(Error::NotFound.into()))? 122 | } else { 123 | // Don't pass in any db object, otherwise it would be returned in case http fetch fails 124 | self.dereference_from_http(data, None).await 125 | } 126 | } 127 | 128 | /// Fetch an object from the local db. Instead of falling back to http, this throws an error if 129 | /// the object is not found in the database. 130 | pub async fn dereference_local( 131 | &self, 132 | data: &Data<::DataType>, 133 | ) -> Result::Error> 134 | where 135 | ::Error: From, 136 | { 137 | let object = self.dereference_from_db(data).await?; 138 | object.ok_or_else(|| Error::NotFound.into()) 139 | } 140 | 141 | /// returning none means the object was not found in local db 142 | async fn dereference_from_db( 143 | &self, 144 | data: &Data<::DataType>, 145 | ) -> Result, ::Error> { 146 | let id = self.0.clone(); 147 | Object::read_from_id(*id, data).await 148 | } 149 | 150 | /// Fetch object from origin instance over HTTP, then verify and parse it. 151 | /// 152 | /// Uses Box::pin to wrap futures to reduce stack size and avoid stack overflow when 153 | /// when fetching objects recursively. 154 | async fn dereference_from_http( 155 | &self, 156 | data: &Data<::DataType>, 157 | db_object: Option, 158 | ) -> Result::Error> 159 | where 160 | ::Error: From, 161 | { 162 | let res = Box::pin(fetch_object_http(&self.0, data)).await; 163 | 164 | if let Err(Error::ObjectDeleted(url)) = res { 165 | if let Some(db_object) = db_object { 166 | db_object.delete(data).await?; 167 | return Ok(db_object); 168 | } 169 | return Err(Error::ObjectDeleted(url).into()); 170 | } 171 | 172 | // If fetch failed, return the existing object from local database 173 | if let (Err(_), Some(db_object)) = (&res, db_object) { 174 | return Ok(db_object); 175 | } 176 | let res = res?; 177 | let redirect_url = &res.url; 178 | 179 | // Prevent overwriting local object 180 | if data.config.is_local_url(redirect_url) { 181 | return self 182 | .dereference_from_db(data) 183 | .await? 184 | .ok_or(Error::NotFound.into()); 185 | } 186 | 187 | Box::pin(Kind::verify(&res.object, redirect_url, data)).await?; 188 | Box::pin(Kind::from_json(res.object, data)).await 189 | } 190 | 191 | /// Returns true if the object's domain matches the one defined in [[FederationConfig.domain]]. 192 | pub fn is_local(&self, data: &Data<::DataType>) -> bool { 193 | data.config.is_local_url(&self.0) 194 | } 195 | } 196 | 197 | /// Need to implement clone manually, to avoid requiring Kind to be Clone 198 | impl Clone for ObjectId 199 | where 200 | Kind: Object, 201 | for<'de2> ::Kind: Deserialize<'de2>, 202 | { 203 | fn clone(&self) -> Self { 204 | ObjectId(self.0.clone(), self.1) 205 | } 206 | } 207 | 208 | static ACTOR_REFETCH_INTERVAL_SECONDS: i64 = 24 * 60 * 60; 209 | static ACTOR_REFETCH_INTERVAL_SECONDS_DEBUG: i64 = 20; 210 | 211 | /// Determines when a remote actor should be refetched from its instance. In release builds, this is 212 | /// `ACTOR_REFETCH_INTERVAL_SECONDS` after the last refetch, in debug builds 213 | /// `ACTOR_REFETCH_INTERVAL_SECONDS_DEBUG`. 214 | fn should_refetch_object(last_refreshed: DateTime) -> bool { 215 | let update_interval = if cfg!(debug_assertions) { 216 | // avoid infinite loop when fetching community outbox 217 | ChronoDuration::try_seconds(ACTOR_REFETCH_INTERVAL_SECONDS_DEBUG).expect("valid duration") 218 | } else { 219 | ChronoDuration::try_seconds(ACTOR_REFETCH_INTERVAL_SECONDS).expect("valid duration") 220 | }; 221 | let refresh_limit = Utc::now() - update_interval; 222 | last_refreshed.lt(&refresh_limit) 223 | } 224 | 225 | impl Display for ObjectId 226 | where 227 | Kind: Object, 228 | for<'de2> ::Kind: Deserialize<'de2>, 229 | { 230 | fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result { 231 | write!(f, "{}", self.0.as_str()) 232 | } 233 | } 234 | 235 | impl Debug for ObjectId 236 | where 237 | Kind: Object, 238 | for<'de2> ::Kind: Deserialize<'de2>, 239 | { 240 | fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result { 241 | write!(f, "{}", self.0.as_str()) 242 | } 243 | } 244 | 245 | impl From> for Url 246 | where 247 | Kind: Object, 248 | for<'de2> ::Kind: Deserialize<'de2>, 249 | { 250 | fn from(id: ObjectId) -> Self { 251 | *id.0 252 | } 253 | } 254 | 255 | impl From for ObjectId 256 | where 257 | Kind: Object + Send + 'static, 258 | for<'de2> ::Kind: Deserialize<'de2>, 259 | { 260 | fn from(url: Url) -> Self { 261 | ObjectId(Box::new(url), PhantomData::) 262 | } 263 | } 264 | 265 | impl PartialEq for ObjectId 266 | where 267 | Kind: Object, 268 | for<'de2> ::Kind: Deserialize<'de2>, 269 | { 270 | fn eq(&self, other: &Self) -> bool { 271 | self.0.eq(&other.0) && self.1 == other.1 272 | } 273 | } 274 | 275 | /// Internal only 276 | #[cfg(test)] 277 | #[allow(clippy::unwrap_used)] 278 | pub mod tests { 279 | use super::*; 280 | use crate::traits::tests::DbUser; 281 | 282 | #[test] 283 | fn test_deserialize() { 284 | let id = ObjectId::::parse("http://test.com/").unwrap(); 285 | 286 | let string = serde_json::to_string(&id).unwrap(); 287 | assert_eq!("\"http://test.com/\"", string); 288 | 289 | let parsed: ObjectId = serde_json::from_str(&string).unwrap(); 290 | assert_eq!(parsed, id); 291 | } 292 | 293 | #[test] 294 | fn test_should_refetch_object() { 295 | let one_second_ago = Utc::now() - ChronoDuration::try_seconds(1).unwrap(); 296 | assert!(!should_refetch_object(one_second_ago)); 297 | 298 | let two_days_ago = Utc::now() - ChronoDuration::try_days(2).unwrap(); 299 | assert!(should_refetch_object(two_days_ago)); 300 | } 301 | } 302 | -------------------------------------------------------------------------------- /src/actix_web/inbox.rs: -------------------------------------------------------------------------------- 1 | //! Handles incoming activities, verifying HTTP signatures and other checks 2 | 3 | use super::http_compat; 4 | use crate::{ 5 | config::Data, 6 | error::Error, 7 | http_signatures::{verify_body_hash, verify_signature}, 8 | parse_received_activity, 9 | traits::{Activity, Actor, Object}, 10 | }; 11 | use actix_web::{web::Bytes, HttpRequest, HttpResponse}; 12 | use serde::de::DeserializeOwned; 13 | use tracing::debug; 14 | 15 | /// Handles incoming activities, verifying HTTP signatures and other checks 16 | /// 17 | /// After successful validation, activities are passed to respective [trait@Activity]. 18 | pub async fn receive_activity( 19 | request: HttpRequest, 20 | body: Bytes, 21 | data: &Data, 22 | ) -> Result::Error> 23 | where 24 | A: Activity + DeserializeOwned + Send + 'static, 25 | ActorT: Object + Actor + Send + Sync + 'static, 26 | for<'de2> ::Kind: serde::Deserialize<'de2>, 27 | ::Error: From + From<::Error>, 28 | ::Error: From, 29 | Datatype: Clone, 30 | { 31 | let (activity, _) = do_stuff::(request, body, data).await?; 32 | 33 | do_more_stuff(activity, data).await 34 | } 35 | 36 | /// Workaround required so we can use references for the hook, instead of cloning data. 37 | pub trait ReceiveActivityHook 38 | where 39 | A: Activity + DeserializeOwned + Send + Clone + 'static, 40 | ActorT: Object + Actor + Send + Clone + 'static, 41 | for<'de2> ::Kind: serde::Deserialize<'de2>, 42 | ::Error: From + From<::Error>, 43 | ::Error: From, 44 | Datatype: Clone, 45 | { 46 | /// Called when a new activity is recived 47 | fn hook( 48 | self, 49 | activity: &A, 50 | actor: &ActorT, 51 | data: &Data, 52 | ) -> impl std::future::Future::Error>>; 53 | } 54 | 55 | /// Same as [receive_activity], only that it calls the provided hook function before 56 | /// calling activity verify and receive functions. 57 | pub async fn receive_activity_with_hook( 58 | request: HttpRequest, 59 | body: Bytes, 60 | hook: impl ReceiveActivityHook, 61 | data: &Data, 62 | ) -> Result::Error> 63 | where 64 | A: Activity + DeserializeOwned + Send + Clone + 'static, 65 | ActorT: Object + Actor + Send + Sync + Clone + 'static, 66 | for<'de2> ::Kind: serde::Deserialize<'de2>, 67 | ::Error: From + From<::Error>, 68 | ::Error: From, 69 | Datatype: Clone, 70 | { 71 | let (activity, actor) = do_stuff::(request, body, data).await?; 72 | 73 | hook.hook(&activity, &actor, data).await?; 74 | 75 | do_more_stuff(activity, data).await 76 | } 77 | 78 | async fn do_stuff( 79 | request: HttpRequest, 80 | body: Bytes, 81 | data: &Data, 82 | ) -> Result<(A, ActorT), ::Error> 83 | where 84 | A: Activity + DeserializeOwned + Send + 'static, 85 | ActorT: Object + Actor + Send + Sync + 'static, 86 | for<'de2> ::Kind: serde::Deserialize<'de2>, 87 | ::Error: From + From<::Error>, 88 | ::Error: From, 89 | Datatype: Clone, 90 | { 91 | let digest_header = request 92 | .headers() 93 | .get("Digest") 94 | .map(http_compat::header_value); 95 | verify_body_hash(digest_header.as_ref(), &body)?; 96 | 97 | let (activity, actor) = parse_received_activity::(&body, data).await?; 98 | 99 | let headers = http_compat::header_map(request.headers()); 100 | let method = http_compat::method(request.method()); 101 | let uri = http_compat::uri(request.uri()); 102 | verify_signature(&headers, &method, &uri, actor.public_key_pem())?; 103 | 104 | Ok((activity, actor)) 105 | } 106 | 107 | async fn do_more_stuff( 108 | activity: A, 109 | data: &Data, 110 | ) -> Result::Error> 111 | where 112 | A: Activity + DeserializeOwned + Send + 'static, 113 | Datatype: Clone, 114 | { 115 | debug!("Receiving activity {}", activity.id().to_string()); 116 | activity.verify(data).await?; 117 | activity.receive(data).await?; 118 | Ok(HttpResponse::Ok().finish()) 119 | } 120 | 121 | #[cfg(test)] 122 | #[allow(clippy::unwrap_used)] 123 | mod test { 124 | use super::*; 125 | use crate::{ 126 | activity_sending::generate_request_headers, 127 | config::FederationConfig, 128 | fetch::object_id::ObjectId, 129 | http_signatures::sign_request, 130 | traits::tests::{DbConnection, DbUser, Follow, DB_USER_KEYPAIR}, 131 | }; 132 | use actix_web::test::TestRequest; 133 | use reqwest::Client; 134 | use reqwest_middleware::ClientWithMiddleware; 135 | use serde_json::json; 136 | use url::Url; 137 | 138 | /// Remove this conversion helper after actix-web upgrades to http 1.0 139 | fn header_pair( 140 | p: (&http::HeaderName, &http::HeaderValue), 141 | ) -> (http02::HeaderName, http02::HeaderValue) { 142 | ( 143 | http02::HeaderName::from_lowercase(p.0.as_str().as_bytes()).unwrap(), 144 | http02::HeaderValue::from_bytes(p.1.as_bytes()).unwrap(), 145 | ) 146 | } 147 | 148 | #[tokio::test] 149 | async fn test_receive_activity_hook() { 150 | let (body, incoming_request, config) = setup_receive_test().await; 151 | let res = receive_activity_with_hook::( 152 | incoming_request.to_http_request(), 153 | body, 154 | Dummy, 155 | &config.to_request_data(), 156 | ) 157 | .await; 158 | assert_eq!(res.err(), Some(Error::Other("test-error".to_string()))); 159 | } 160 | 161 | struct Dummy; 162 | 163 | impl ReceiveActivityHook for Dummy 164 | where 165 | A: Activity + DeserializeOwned + Send + Clone + 'static, 166 | ActorT: Object + Actor + Send + Clone + 'static, 167 | for<'de2> ::Kind: serde::Deserialize<'de2>, 168 | ::Error: From + From<::Error>, 169 | ::Error: From, 170 | Datatype: Clone, 171 | { 172 | async fn hook( 173 | self, 174 | _activity: &A, 175 | _actor: &ActorT, 176 | _data: &Data, 177 | ) -> Result<(), ::Error> { 178 | // ensure that hook gets called by returning this value 179 | Err(Error::Other("test-error".to_string()).into()) 180 | } 181 | } 182 | 183 | #[tokio::test] 184 | async fn test_receive_activity_invalid_body_signature() { 185 | let (_, incoming_request, config) = setup_receive_test().await; 186 | let err = receive_activity::( 187 | incoming_request.to_http_request(), 188 | "invalid".into(), 189 | &config.to_request_data(), 190 | ) 191 | .await 192 | .err() 193 | .unwrap(); 194 | 195 | assert_eq!(&err, &Error::ActivityBodyDigestInvalid) 196 | } 197 | 198 | #[tokio::test] 199 | async fn test_receive_activity_invalid_path() { 200 | let (body, incoming_request, config) = setup_receive_test().await; 201 | let incoming_request = incoming_request.uri("/wrong"); 202 | let err = receive_activity::( 203 | incoming_request.to_http_request(), 204 | body, 205 | &config.to_request_data(), 206 | ) 207 | .await 208 | .err() 209 | .unwrap(); 210 | 211 | assert_eq!(&err, &Error::ActivitySignatureInvalid) 212 | } 213 | 214 | #[tokio::test] 215 | async fn test_receive_unparseable_activity() { 216 | let (_, _, config) = setup_receive_test().await; 217 | 218 | let actor = Url::parse("http://ds9.lemmy.ml/u/lemmy_alpha").unwrap(); 219 | let activity_id = "http://localhost:123/1"; 220 | let activity = json!({ 221 | "actor": actor.as_str(), 222 | "to": ["https://www.w3.org/ns/activitystreams#Public"], 223 | "object": "http://ds9.lemmy.ml/post/1", 224 | "cc": ["http://enterprise.lemmy.ml/c/main"], 225 | "type": "Delete", 226 | "id": activity_id 227 | } 228 | ); 229 | let body: Bytes = serde_json::to_vec(&activity).unwrap().into(); 230 | let incoming_request = construct_request(&body, &actor).await; 231 | 232 | // intentionally cause a parse error by using wrong type for deser 233 | let res = receive_activity::( 234 | incoming_request.to_http_request(), 235 | body, 236 | &config.to_request_data(), 237 | ) 238 | .await; 239 | 240 | match res { 241 | Err(Error::ParseReceivedActivity { err: _, id }) => { 242 | assert_eq!(activity_id, id.expect("has url").as_str()); 243 | } 244 | _ => unreachable!(), 245 | } 246 | } 247 | 248 | async fn construct_request(body: &Bytes, actor: &Url) -> TestRequest { 249 | let inbox = "https://example.com/inbox"; 250 | let headers = generate_request_headers(&Url::parse(inbox).unwrap()); 251 | let request_builder = ClientWithMiddleware::from(Client::default()) 252 | .post(inbox) 253 | .headers(headers); 254 | let outgoing_request = sign_request( 255 | request_builder, 256 | actor, 257 | body.clone(), 258 | DB_USER_KEYPAIR.private_key().unwrap(), 259 | false, 260 | ) 261 | .await 262 | .unwrap(); 263 | let mut incoming_request = TestRequest::post().uri(outgoing_request.url().path()); 264 | for h in outgoing_request.headers() { 265 | incoming_request = incoming_request.append_header(header_pair(h)); 266 | } 267 | incoming_request 268 | } 269 | 270 | async fn setup_receive_test() -> (Bytes, TestRequest, FederationConfig) { 271 | let activity = Follow { 272 | actor: ObjectId::parse("http://localhost:123").unwrap(), 273 | object: ObjectId::parse("http://localhost:124").unwrap(), 274 | kind: Default::default(), 275 | id: "http://localhost:123/1".try_into().unwrap(), 276 | }; 277 | let body: Bytes = serde_json::to_vec(&activity).unwrap().into(); 278 | let incoming_request = construct_request(&body, activity.actor.inner()).await; 279 | 280 | let config = FederationConfig::builder() 281 | .domain("localhost:8002") 282 | .app_data(DbConnection) 283 | .debug(true) 284 | .build() 285 | .await 286 | .unwrap(); 287 | (body, incoming_request, config) 288 | } 289 | } 290 | -------------------------------------------------------------------------------- /src/fetch/webfinger.rs: -------------------------------------------------------------------------------- 1 | use crate::{ 2 | config::{domain_regex, Data}, 3 | error::Error, 4 | fetch::{fetch_object_http_with_accept, object_id::ObjectId}, 5 | traits::{Actor, Object}, 6 | FEDERATION_CONTENT_TYPE, 7 | }; 8 | use http::HeaderValue; 9 | use itertools::Itertools; 10 | use regex::Regex; 11 | use serde::{Deserialize, Serialize}; 12 | use std::{collections::HashMap, fmt::Display, sync::LazyLock}; 13 | use tracing::debug; 14 | use url::Url; 15 | 16 | /// Errors relative to webfinger handling 17 | #[derive(thiserror::Error, Debug)] 18 | pub enum WebFingerError { 19 | /// The webfinger identifier is invalid 20 | #[error("The webfinger identifier is invalid")] 21 | WrongFormat, 22 | /// The webfinger identifier doesn't match the expected instance domain name 23 | #[error("The webfinger identifier doesn't match the expected instance domain name")] 24 | WrongDomain, 25 | /// The wefinger object did not contain any link to an activitypub item 26 | #[error("The webfinger object did not contain any link to an activitypub item")] 27 | NoValidLink, 28 | } 29 | 30 | impl WebFingerError { 31 | fn into_crate_error(self) -> Error { 32 | self.into() 33 | } 34 | } 35 | 36 | /// The content-type for webfinger responses. 37 | pub static WEBFINGER_CONTENT_TYPE: HeaderValue = HeaderValue::from_static("application/jrd+json"); 38 | 39 | /// Takes an identifier of the form `name@example.com`, and returns an object of `Kind`. 40 | /// 41 | /// For this the identifier is first resolved via webfinger protocol to an Activitypub ID. This ID 42 | /// is then fetched using [ObjectId::dereference], and the result returned. 43 | pub async fn webfinger_resolve_actor( 44 | identifier: &str, 45 | data: &Data, 46 | ) -> Result::Error> 47 | where 48 | Kind: Object + Actor + Send + Sync + 'static + Object, 49 | for<'de2> ::Kind: serde::Deserialize<'de2>, 50 | ::Error: From + Send + Sync + Display, 51 | { 52 | let (_, domain) = identifier 53 | .splitn(2, '@') 54 | .collect_tuple() 55 | .ok_or(WebFingerError::WrongFormat.into_crate_error())?; 56 | 57 | // For production mode make sure that domain doesnt contain any port or path. 58 | if !data.config.debug && !domain_regex().is_match(domain) { 59 | return Err(Error::UrlVerificationError("Invalid characters in domain").into()); 60 | } 61 | 62 | let protocol = if data.config.debug { "http" } else { "https" }; 63 | let fetch_url = 64 | format!("{protocol}://{domain}/.well-known/webfinger?resource=acct:{identifier}"); 65 | debug!("Fetching webfinger url: {}", &fetch_url); 66 | 67 | let res = fetch_object_http_with_accept::<_, Webfinger>( 68 | &Url::parse(&fetch_url).map_err(Error::UrlParse)?, 69 | data, 70 | &WEBFINGER_CONTENT_TYPE, 71 | false, 72 | ) 73 | .await?; 74 | if res.url.as_str() != fetch_url { 75 | data.config.verify_url_valid(&res.url).await?; 76 | } 77 | 78 | debug_assert_eq!(res.object.subject, format!("acct:{identifier}")); 79 | let links: Vec = res 80 | .object 81 | .links 82 | .iter() 83 | .filter(|link| { 84 | if let Some(type_) = &link.kind { 85 | type_.starts_with("application/") 86 | } else { 87 | false 88 | } 89 | }) 90 | .filter_map(|l| l.href.clone()) 91 | .rev() 92 | .collect(); 93 | 94 | for l in links { 95 | let object = ObjectId::::from(l).dereference(data).await; 96 | match object { 97 | Ok(obj) => return Ok(obj), 98 | Err(error) => debug!(%error, "Failed to dereference link"), 99 | } 100 | } 101 | Err(WebFingerError::NoValidLink.into_crate_error().into()) 102 | } 103 | 104 | /// Extracts username from a webfinger resource parameter. 105 | /// 106 | /// Use this method for your HTTP handler at `.well-known/webfinger` to handle incoming webfinger 107 | /// request. For a parameter of the form `acct:gargron@mastodon.social` it returns `gargron`. 108 | /// 109 | /// Returns an error if query doesn't match local domain. 110 | /// 111 | ///``` 112 | /// # use activitypub_federation::config::FederationConfig; 113 | /// # use activitypub_federation::traits::tests::DbConnection; 114 | /// # use activitypub_federation::fetch::webfinger::extract_webfinger_name; 115 | /// # tokio::runtime::Runtime::new().unwrap().block_on(async { 116 | /// # let db_connection = DbConnection; 117 | /// let config = FederationConfig::builder() 118 | /// .domain("example.com") 119 | /// .app_data(db_connection) 120 | /// .build() 121 | /// .await 122 | /// .unwrap(); 123 | /// let data = config.to_request_data(); 124 | /// let res = extract_webfinger_name("acct:test_user@example.com", &data).unwrap(); 125 | /// assert_eq!(res, "test_user"); 126 | /// # Ok::<(), anyhow::Error>(()) 127 | /// }).unwrap(); 128 | ///``` 129 | pub fn extract_webfinger_name<'i, T>(query: &'i str, data: &Data) -> Result<&'i str, Error> 130 | where 131 | T: Clone, 132 | { 133 | static WEBFINGER_REGEX: LazyLock = 134 | LazyLock::new(|| Regex::new(r"^acct:([\p{L}0-9_\.\-]+)@(.*)$").expect("compile regex")); 135 | // Regex to extract usernames from webfinger query. Supports different alphabets using `\p{L}`. 136 | // TODO: This should use a URL parser 137 | let captures = WEBFINGER_REGEX 138 | .captures(query) 139 | .ok_or(WebFingerError::WrongFormat)?; 140 | 141 | let account_name = captures.get(1).ok_or(WebFingerError::WrongFormat)?; 142 | 143 | if captures.get(2).map(|m| m.as_str()) != Some(data.domain()) { 144 | return Err(WebFingerError::WrongDomain.into()); 145 | } 146 | Ok(account_name.as_str()) 147 | } 148 | 149 | /// Builds a basic webfinger response for the actor. 150 | /// 151 | /// It assumes that the given URL is valid both to the view the actor in a browser as HTML, and 152 | /// for fetching it over Activitypub with `activity+json`. This setup is commonly used for ease 153 | /// of discovery. 154 | /// 155 | /// ``` 156 | /// # use url::Url; 157 | /// # use activitypub_federation::fetch::webfinger::build_webfinger_response; 158 | /// let subject = "acct:nutomic@lemmy.ml".to_string(); 159 | /// let url = Url::parse("https://lemmy.ml/u/nutomic")?; 160 | /// build_webfinger_response(subject, url); 161 | /// # Ok::<(), anyhow::Error>(()) 162 | /// ``` 163 | pub fn build_webfinger_response(subject: String, url: Url) -> Webfinger { 164 | build_webfinger_response_with_type(subject, vec![(url, None)]) 165 | } 166 | 167 | /// Builds a webfinger response similar to `build_webfinger_response`. Use this when you want to 168 | /// return multiple actors who share the same namespace and to specify the type of the actor. 169 | /// 170 | /// `urls` takes a vector of tuples. The first item of the tuple is the URL while the second 171 | /// item is the type, such as `"Person"` or `"Group"`. If `None` is passed for the type, the field 172 | /// will be empty. 173 | /// 174 | /// ``` 175 | /// # use url::Url; 176 | /// # use activitypub_federation::fetch::webfinger::build_webfinger_response_with_type; 177 | /// let subject = "acct:nutomic@lemmy.ml".to_string(); 178 | /// let user = Url::parse("https://lemmy.ml/u/nutomic")?; 179 | /// let group = Url::parse("https://lemmy.ml/c/asklemmy")?; 180 | /// build_webfinger_response_with_type(subject, vec![ 181 | /// (user, Some("Person")), 182 | /// (group, Some("Group"))]); 183 | /// # Ok::<(), anyhow::Error>(()) 184 | /// ``` 185 | pub fn build_webfinger_response_with_type( 186 | subject: String, 187 | urls: Vec<(Url, Option<&str>)>, 188 | ) -> Webfinger { 189 | Webfinger { 190 | subject, 191 | links: urls.iter().fold(vec![], |mut acc, (url, kind)| { 192 | let properties: HashMap = kind 193 | .map(|kind| { 194 | HashMap::from([( 195 | "https://www.w3.org/ns/activitystreams#type" 196 | .parse() 197 | .expect("parse url"), 198 | kind.to_string(), 199 | )]) 200 | }) 201 | .unwrap_or_default(); 202 | let mut links = vec![ 203 | WebfingerLink { 204 | rel: Some("http://webfinger.net/rel/profile-page".to_string()), 205 | kind: Some("text/html".to_string()), 206 | href: Some(url.clone()), 207 | ..Default::default() 208 | }, 209 | WebfingerLink { 210 | rel: Some("self".to_string()), 211 | kind: Some(FEDERATION_CONTENT_TYPE.to_string()), 212 | href: Some(url.clone()), 213 | properties, 214 | ..Default::default() 215 | }, 216 | ]; 217 | acc.append(&mut links); 218 | acc 219 | }), 220 | aliases: vec![], 221 | properties: Default::default(), 222 | } 223 | } 224 | 225 | /// A webfinger response with information about a `Person` or other type of actor. 226 | #[derive(Serialize, Deserialize, Debug, Default, PartialEq)] 227 | pub struct Webfinger { 228 | /// The actor which is described here, for example `acct:LemmyDev@mastodon.social` 229 | pub subject: String, 230 | /// Links where further data about `subject` can be retrieved 231 | pub links: Vec, 232 | /// Other Urls which identify the same actor as the `subject` 233 | #[serde(default, skip_serializing_if = "Vec::is_empty")] 234 | pub aliases: Vec, 235 | /// Additional data about the subject 236 | #[serde(default, skip_serializing_if = "HashMap::is_empty")] 237 | pub properties: HashMap, 238 | } 239 | 240 | /// A single link included as part of a [Webfinger] response. 241 | #[derive(Serialize, Deserialize, Debug, Default, PartialEq)] 242 | pub struct WebfingerLink { 243 | /// Relationship of the link, such as `self` or `http://webfinger.net/rel/profile-page` 244 | pub rel: Option, 245 | /// Media type of the target resource 246 | #[serde(rename = "type")] 247 | pub kind: Option, 248 | /// Url pointing to the target resource 249 | pub href: Option, 250 | /// Used for remote follow external interaction url 251 | pub template: Option, 252 | /// Additional data about the link 253 | #[serde(default, skip_serializing_if = "HashMap::is_empty")] 254 | pub properties: HashMap, 255 | } 256 | 257 | #[cfg(test)] 258 | #[allow(clippy::unwrap_used)] 259 | mod tests { 260 | use super::*; 261 | use crate::{ 262 | config::FederationConfig, 263 | traits::tests::{DbConnection, DbUser}, 264 | }; 265 | 266 | #[tokio::test] 267 | async fn test_webfinger() -> Result<(), Error> { 268 | let config = FederationConfig::builder() 269 | .domain("example.com") 270 | .app_data(DbConnection) 271 | .build() 272 | .await 273 | .unwrap(); 274 | let data = config.to_request_data(); 275 | 276 | webfinger_resolve_actor::("LemmyDev@mastodon.social", &data).await?; 277 | Ok(()) 278 | } 279 | 280 | #[tokio::test] 281 | async fn test_webfinger_extract_name() -> Result<(), Error> { 282 | use crate::traits::tests::DbConnection; 283 | let data = Data { 284 | config: FederationConfig::builder() 285 | .domain("example.com") 286 | .app_data(DbConnection) 287 | .build() 288 | .await 289 | .unwrap(), 290 | request_counter: Default::default(), 291 | }; 292 | assert_eq!( 293 | Ok("test123"), 294 | extract_webfinger_name("acct:test123@example.com", &data) 295 | ); 296 | assert_eq!( 297 | Ok("Владимир"), 298 | extract_webfinger_name("acct:Владимир@example.com", &data) 299 | ); 300 | assert_eq!( 301 | Ok("example.com"), 302 | extract_webfinger_name("acct:example.com@example.com", &data) 303 | ); 304 | assert_eq!( 305 | Ok("da-sh"), 306 | extract_webfinger_name("acct:da-sh@example.com", &data) 307 | ); 308 | assert_eq!( 309 | Ok("تجريب"), 310 | extract_webfinger_name("acct:تجريب@example.com", &data) 311 | ); 312 | Ok(()) 313 | } 314 | } 315 | -------------------------------------------------------------------------------- /src/activity_sending.rs: -------------------------------------------------------------------------------- 1 | //! Queue for signing and sending outgoing activities with retry 2 | //! 3 | #![doc = include_str!("../docs/09_sending_activities.md")] 4 | 5 | use crate::{ 6 | config::Data, 7 | error::Error, 8 | http_signatures::sign_request, 9 | reqwest_shim::ResponseExt, 10 | traits::{Activity, Actor}, 11 | FEDERATION_CONTENT_TYPE, 12 | }; 13 | use bytes::Bytes; 14 | use futures::StreamExt; 15 | use http::StatusCode; 16 | use httpdate::fmt_http_date; 17 | use itertools::Itertools; 18 | use reqwest::{ 19 | header::{HeaderMap, HeaderName, HeaderValue}, 20 | Response, 21 | }; 22 | use reqwest_middleware::ClientWithMiddleware; 23 | use rsa::{pkcs8::DecodePrivateKey, RsaPrivateKey}; 24 | use serde::Serialize; 25 | use std::{ 26 | fmt::{Debug, Display}, 27 | time::{Duration, Instant, SystemTime}, 28 | }; 29 | use tracing::{debug, warn}; 30 | use url::Url; 31 | 32 | #[derive(Clone, Debug)] 33 | /// All info needed to sign and send one activity to one inbox. You should generally use 34 | /// [[crate::activity_queue::queue_activity]] unless you want implement your own queue. 35 | pub struct SendActivityTask { 36 | pub(crate) actor_id: Url, 37 | pub(crate) activity_id: Url, 38 | pub(crate) activity: Bytes, 39 | pub(crate) inbox: Url, 40 | pub(crate) private_key: RsaPrivateKey, 41 | pub(crate) http_signature_compat: bool, 42 | } 43 | 44 | impl Display for SendActivityTask { 45 | fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 46 | write!(f, "{} to {}", self.activity_id, self.inbox) 47 | } 48 | } 49 | 50 | impl SendActivityTask { 51 | /// Prepare an activity for sending 52 | /// 53 | /// - `activity`: The activity to be sent, gets converted to json 54 | /// - `inboxes`: List of remote actor inboxes that should receive the activity. Ignores local actor 55 | /// inboxes. Should be built by calling [crate::traits::Actor::shared_inbox_or_inbox] 56 | /// for each target actor. 57 | pub async fn prepare( 58 | activity: &A, 59 | actor: &ActorType, 60 | inboxes: Vec, 61 | data: &Data, 62 | ) -> Result, Error> 63 | where 64 | A: Activity + Serialize + Debug, 65 | Datatype: Clone, 66 | ActorType: Actor, 67 | { 68 | build_tasks(activity, actor, inboxes, data).await 69 | } 70 | 71 | /// convert a sendactivitydata to a request, signing and sending it 72 | pub async fn sign_and_send(&self, data: &Data) -> Result<(), Error> { 73 | self.sign_and_send_internal(&data.config.client, data.config.request_timeout) 74 | .await 75 | } 76 | 77 | pub(crate) async fn sign_and_send_internal( 78 | &self, 79 | client: &ClientWithMiddleware, 80 | timeout: Duration, 81 | ) -> Result<(), Error> { 82 | debug!("Sending {} to {}", self.activity_id, self.inbox,); 83 | let request_builder = client 84 | .post(self.inbox.to_string()) 85 | .timeout(timeout) 86 | .headers(generate_request_headers(&self.inbox)); 87 | let request = sign_request( 88 | request_builder, 89 | &self.actor_id, 90 | self.activity.clone(), 91 | self.private_key.clone(), 92 | self.http_signature_compat, 93 | ) 94 | .await?; 95 | 96 | // Send the activity, and log a warning if its too slow. 97 | let now = Instant::now(); 98 | let response = client.execute(request).await?; 99 | let elapsed = now.elapsed().as_secs(); 100 | if elapsed > 10 { 101 | warn!( 102 | "Sending activity {} to {} took {}s", 103 | self.activity_id, self.inbox, elapsed 104 | ); 105 | } 106 | self.handle_response(response).await 107 | } 108 | 109 | /// Based on the HTTP status code determines if an activity was delivered successfully. In that case 110 | /// Ok is returned. Otherwise it returns Err and the activity send should be retried later. 111 | /// 112 | /// Equivalent code in mastodon: https://github.com/mastodon/mastodon/blob/v4.2.8/app/helpers/jsonld_helper.rb#L215-L217 113 | async fn handle_response(&self, response: Response) -> Result<(), Error> { 114 | match response.status() { 115 | status if status.is_success() => { 116 | debug!("Activity {self} delivered successfully"); 117 | Ok(()) 118 | } 119 | status 120 | if status.is_client_error() 121 | && status != StatusCode::REQUEST_TIMEOUT 122 | && status != StatusCode::TOO_MANY_REQUESTS => 123 | { 124 | let text = response.text_limited().await?; 125 | debug!("Activity {self} was rejected, aborting: {text}"); 126 | Ok(()) 127 | } 128 | status => { 129 | let text = response.text_limited().await?; 130 | 131 | Err(Error::Other(format!( 132 | "Activity {self} failure with status {status}: {text}", 133 | ))) 134 | } 135 | } 136 | } 137 | } 138 | 139 | pub(crate) async fn build_tasks( 140 | activity: &A, 141 | actor: &ActorType, 142 | inboxes: Vec, 143 | data: &Data, 144 | ) -> Result, Error> 145 | where 146 | A: Activity + Serialize + Debug, 147 | Datatype: Clone, 148 | ActorType: Actor, 149 | { 150 | let config = &data.config; 151 | let actor_id = activity.actor(); 152 | let activity_id = activity.id(); 153 | let activity_serialized: Bytes = serde_json::to_vec(activity) 154 | .map_err(|e| Error::SerializeOutgoingActivity(e, format!("{:?}", activity)))? 155 | .into(); 156 | let private_key = get_pkey_cached(data, actor).await?; 157 | 158 | Ok(futures::stream::iter( 159 | inboxes 160 | .into_iter() 161 | .unique() 162 | .filter(|i| !config.is_local_url(i)), 163 | ) 164 | .filter_map(|inbox| async { 165 | if let Err(err) = config.verify_url_valid(&inbox).await { 166 | debug!("inbox url invalid, skipping: {inbox}: {err}"); 167 | return None; 168 | }; 169 | Some(SendActivityTask { 170 | actor_id: actor_id.clone(), 171 | activity_id: activity_id.clone(), 172 | inbox, 173 | activity: activity_serialized.clone(), 174 | private_key: private_key.clone(), 175 | http_signature_compat: config.http_signature_compat, 176 | }) 177 | }) 178 | .collect() 179 | .await) 180 | } 181 | 182 | pub(crate) async fn get_pkey_cached( 183 | data: &Data, 184 | actor: &ActorType, 185 | ) -> Result 186 | where 187 | ActorType: Actor, 188 | { 189 | let actor_id = actor.id(); 190 | // PKey is internally like an Arc<>, so cloning is ok 191 | data.config 192 | .actor_pkey_cache 193 | .try_get_with_by_ref(actor_id, async { 194 | let private_key_pem = actor.private_key_pem().ok_or_else(|| { 195 | Error::Other(format!( 196 | "Actor {actor_id} does not contain a private key for signing" 197 | )) 198 | })?; 199 | 200 | // This is a mostly expensive blocking call, we don't want to tie up other tasks while this is happening 201 | let pkey = tokio::task::spawn_blocking(move || { 202 | RsaPrivateKey::from_pkcs8_pem(&private_key_pem).map_err(|err| { 203 | Error::Other(format!("Could not create private key from PEM data:{err}")) 204 | }) 205 | }) 206 | .await 207 | .map_err(|err| Error::Other(format!("Error joining: {err}")))??; 208 | std::result::Result::::Ok(pkey) 209 | }) 210 | .await 211 | .map_err(|e| Error::Other(format!("cloned error: {e}"))) 212 | } 213 | 214 | pub(crate) fn generate_request_headers(inbox_url: &Url) -> HeaderMap { 215 | let mut host = inbox_url.domain().expect("read inbox domain").to_string(); 216 | if let Some(port) = inbox_url.port() { 217 | host = format!("{}:{}", host, port); 218 | } 219 | 220 | let mut headers = HeaderMap::new(); 221 | headers.insert( 222 | HeaderName::from_static("content-type"), 223 | HeaderValue::from_static(FEDERATION_CONTENT_TYPE), 224 | ); 225 | headers.insert( 226 | HeaderName::from_static("host"), 227 | HeaderValue::from_str(&host).expect("Hostname is valid"), 228 | ); 229 | headers.insert( 230 | "date", 231 | HeaderValue::from_str(&fmt_http_date(SystemTime::now())).expect("Date is valid"), 232 | ); 233 | headers 234 | } 235 | 236 | #[cfg(test)] 237 | #[allow(clippy::unwrap_used)] 238 | mod tests { 239 | use super::*; 240 | use crate::{config::FederationConfig, http_signatures::generate_actor_keypair}; 241 | use std::{ 242 | sync::{atomic::AtomicUsize, Arc}, 243 | time::Instant, 244 | }; 245 | use tracing::info; 246 | 247 | // This will periodically send back internal errors to test the retry 248 | async fn dodgy_handler(headers: HeaderMap, body: Bytes) -> Result<(), StatusCode> { 249 | debug!("Headers:{:?}", headers); 250 | debug!("Body len:{}", body.len()); 251 | Ok(()) 252 | } 253 | 254 | async fn test_server() { 255 | use axum::{routing::post, Router}; 256 | 257 | // We should break every now and then ;) 258 | let state = Arc::new(AtomicUsize::new(0)); 259 | 260 | let app = Router::new() 261 | .route("/", post(dodgy_handler)) 262 | .with_state(state); 263 | 264 | let listener = tokio::net::TcpListener::bind("0.0.0.0:8001").await.unwrap(); 265 | axum::serve(listener, app.into_make_service()) 266 | .await 267 | .unwrap(); 268 | } 269 | 270 | #[tokio::test(flavor = "multi_thread")] 271 | // Sends 100 messages 272 | async fn test_activity_sending() -> anyhow::Result<()> { 273 | let num_messages: usize = 100; 274 | 275 | tokio::spawn(test_server()); 276 | 277 | /* 278 | // uncomment for debug logs & stats 279 | use tracing::log::LevelFilter; 280 | 281 | env_logger::builder() 282 | .filter_level(LevelFilter::Warn) 283 | .filter_module("activitypub_federation", LevelFilter::Info) 284 | .format_timestamp(None) 285 | .init(); 286 | 287 | */ 288 | let keypair = generate_actor_keypair().unwrap(); 289 | 290 | let message = SendActivityTask { 291 | actor_id: "http://localhost:8001".parse().unwrap(), 292 | activity_id: "http://localhost:8001/activity".parse().unwrap(), 293 | activity: "{}".into(), 294 | inbox: "http://localhost:8001".parse().unwrap(), 295 | private_key: keypair.private_key().unwrap(), 296 | http_signature_compat: true, 297 | }; 298 | let data = FederationConfig::builder() 299 | .app_data(()) 300 | .domain("localhost") 301 | .build() 302 | .await? 303 | .to_request_data(); 304 | 305 | let start = Instant::now(); 306 | 307 | for _ in 0..num_messages { 308 | message.clone().sign_and_send(&data).await?; 309 | } 310 | 311 | info!("Queue Sent: {:?}", start.elapsed()); 312 | Ok(()) 313 | } 314 | 315 | #[tokio::test] 316 | async fn test_handle_response() { 317 | let keypair = generate_actor_keypair().unwrap(); 318 | let message = SendActivityTask { 319 | actor_id: "http://localhost:8001".parse().unwrap(), 320 | activity_id: "http://localhost:8001/activity".parse().unwrap(), 321 | activity: "{}".into(), 322 | inbox: "http://localhost:8001".parse().unwrap(), 323 | private_key: keypair.private_key().unwrap(), 324 | http_signature_compat: true, 325 | }; 326 | 327 | let res = |status| { 328 | http::Response::builder() 329 | .status(status) 330 | .body(vec![]) 331 | .unwrap() 332 | .into() 333 | }; 334 | 335 | assert!(message.handle_response(res(StatusCode::OK)).await.is_ok()); 336 | assert!(message 337 | .handle_response(res(StatusCode::BAD_REQUEST)) 338 | .await 339 | .is_ok()); 340 | 341 | assert!(message 342 | .handle_response(res(StatusCode::MOVED_PERMANENTLY)) 343 | .await 344 | .is_err()); 345 | assert!(message 346 | .handle_response(res(StatusCode::REQUEST_TIMEOUT)) 347 | .await 348 | .is_err()); 349 | assert!(message 350 | .handle_response(res(StatusCode::TOO_MANY_REQUESTS)) 351 | .await 352 | .is_err()); 353 | assert!(message 354 | .handle_response(res(StatusCode::INTERNAL_SERVER_ERROR)) 355 | .await 356 | .is_err()); 357 | } 358 | } 359 | -------------------------------------------------------------------------------- /src/traits/mod.rs: -------------------------------------------------------------------------------- 1 | //! Traits which need to be implemented for federated data types 2 | 3 | use crate::{config::Data, protocol::public_key::PublicKey}; 4 | use async_trait::async_trait; 5 | use chrono::{DateTime, Utc}; 6 | use serde::Deserialize; 7 | use std::{fmt::Debug, ops::Deref}; 8 | use url::Url; 9 | 10 | /// `Either` implementations for traits 11 | pub mod either; 12 | pub mod tests; 13 | 14 | /// Helper for converting between database structs and federated protocol structs. 15 | /// 16 | /// ``` 17 | /// # use activitystreams_kinds::{object::NoteType, public}; 18 | /// # use chrono::{Local, DateTime, Utc}; 19 | /// # use serde::{Deserialize, Serialize}; 20 | /// # use url::Url; 21 | /// # use activitypub_federation::protocol::{public_key::PublicKey, helpers::deserialize_one_or_many}; 22 | /// # use activitypub_federation::config::Data; 23 | /// # use activitypub_federation::fetch::object_id::ObjectId; 24 | /// # use activitypub_federation::protocol::verification::verify_domains_match; 25 | /// # use activitypub_federation::traits::{Actor, Object}; 26 | /// # use activitypub_federation::traits::tests::{DbConnection, DbUser}; 27 | /// # 28 | /// /// How the post is read/written in the local database 29 | /// #[derive(Debug)] 30 | /// pub struct DbPost { 31 | /// pub text: String, 32 | /// pub ap_id: ObjectId, 33 | /// pub creator: ObjectId, 34 | /// pub local: bool, 35 | /// } 36 | /// 37 | /// /// How the post is serialized and represented as Activitypub JSON 38 | /// #[derive(Deserialize, Serialize, Debug)] 39 | /// #[serde(rename_all = "camelCase")] 40 | /// pub struct Note { 41 | /// #[serde(rename = "type")] 42 | /// kind: NoteType, 43 | /// id: ObjectId, 44 | /// pub(crate) attributed_to: ObjectId, 45 | /// #[serde(deserialize_with = "deserialize_one_or_many")] 46 | /// pub(crate) to: Vec, 47 | /// content: String, 48 | /// } 49 | /// 50 | /// #[async_trait::async_trait] 51 | /// impl Object for DbPost { 52 | /// type DataType = DbConnection; 53 | /// type Kind = Note; 54 | /// type Error = anyhow::Error; 55 | /// 56 | /// fn id(&self) -> &Url { self.ap_id.inner() } 57 | /// 58 | /// async fn read_from_id(object_id: Url, data: &Data) -> Result, Self::Error> { 59 | /// // Attempt to read object from local database. Return Ok(None) if not found. 60 | /// let post: Option = data.read_post_from_json_id(object_id).await?; 61 | /// Ok(post) 62 | /// } 63 | /// 64 | /// async fn into_json(self, data: &Data) -> Result { 65 | /// // Called when a local object gets sent out over Activitypub. Simply convert it to the 66 | /// // protocol struct 67 | /// Ok(Note { 68 | /// kind: Default::default(), 69 | /// id: self.ap_id.clone().into(), 70 | /// attributed_to: self.creator, 71 | /// to: vec![public()], 72 | /// content: self.text, 73 | /// }) 74 | /// } 75 | /// 76 | /// async fn verify(json: &Self::Kind, expected_domain: &Url, data: &Data,) -> Result<(), Self::Error> { 77 | /// verify_domains_match(json.id.inner(), expected_domain)?; 78 | /// // additional application specific checks 79 | /// Ok(()) 80 | /// } 81 | /// 82 | /// async fn from_json(json: Self::Kind, data: &Data) -> Result { 83 | /// // Called when a remote object gets received over Activitypub. Validate and insert it 84 | /// // into the database. 85 | /// 86 | /// let post = DbPost { 87 | /// text: json.content, 88 | /// ap_id: json.id, 89 | /// creator: json.attributed_to, 90 | /// local: false, 91 | /// }; 92 | /// 93 | /// // Here we need to persist the object in the local database. Note that Activitypub 94 | /// // doesnt distinguish between creating and updating an object. Thats why we need to 95 | /// // use upsert functionality. 96 | /// data.upsert(&post).await?; 97 | /// 98 | /// Ok(post) 99 | /// } 100 | /// 101 | /// } 102 | #[async_trait] 103 | pub trait Object: Sized + Debug { 104 | /// App data type passed to handlers. Must be identical to 105 | /// [crate::config::FederationConfigBuilder::app_data] type. 106 | type DataType: Clone + Send + Sync; 107 | /// The type of protocol struct which gets sent over network to federate this database struct. 108 | type Kind; 109 | /// Error type returned by handler methods 110 | type Error; 111 | 112 | /// `id` field of the object 113 | fn id(&self) -> &Url; 114 | 115 | /// Returns the last time this object was updated. 116 | /// 117 | /// If this returns `Some` and the value is too long ago, the object is refetched from the 118 | /// original instance. This should always be implemented for actors, because there is no active 119 | /// update mechanism prescribed. It is possible to send `Update/Person` activities for profile 120 | /// changes, but not all implementations do this, so `last_refreshed_at` is still necessary. 121 | /// 122 | /// The object is refetched if `last_refreshed_at` value is more than 24 hours ago. In debug 123 | /// mode this is reduced to 20 seconds. 124 | fn last_refreshed_at(&self) -> Option> { 125 | None 126 | } 127 | 128 | /// Try to read the object with given `id` from local database. 129 | /// 130 | /// Should return `Ok(None)` if not found. 131 | async fn read_from_id( 132 | object_id: Url, 133 | data: &Data, 134 | ) -> Result, Self::Error>; 135 | 136 | /// Mark remote object as deleted in local database. 137 | /// 138 | /// Called when a `Delete` activity is received, or if fetch returns a `Tombstone` object. 139 | async fn delete(&self, _data: &Data) -> Result<(), Self::Error> { 140 | Ok(()) 141 | } 142 | 143 | /// Returns true if the object was deleted 144 | fn is_deleted(&self) -> bool { 145 | false 146 | } 147 | 148 | /// Convert database type to Activitypub type. 149 | /// 150 | /// Called when a local object gets fetched by another instance over HTTP, or when an object 151 | /// gets sent in an activity. 152 | async fn into_json(self, data: &Data) -> Result; 153 | 154 | /// Verifies that the received object is valid. 155 | /// 156 | /// You should check here that the domain of id matches `expected_domain`. Additionally you 157 | /// should perform any application specific checks. 158 | /// 159 | /// It is necessary to use a separate method for this, because it might be used for activities 160 | /// like `Delete/Note`, which shouldn't perform any database write for the inner `Note`. 161 | async fn verify( 162 | json: &Self::Kind, 163 | expected_domain: &Url, 164 | data: &Data, 165 | ) -> Result<(), Self::Error>; 166 | 167 | /// Convert object from ActivityPub type to database type. 168 | /// 169 | /// Called when an object is received from HTTP fetch or as part of an activity. This method 170 | /// should write the received object to database. Note that there is no distinction between 171 | /// create and update, so an `upsert` operation should be used. 172 | async fn from_json(json: Self::Kind, data: &Data) -> Result; 173 | 174 | /// Generates HTTP response to serve the object for fetching from other instances. 175 | /// 176 | /// - If the object has a remote domain, sends a redirect to the original instance. 177 | /// - If [Object.is_deleted] returns true, returns a [crate::protocol::tombstone::Tombstone] instead. 178 | /// - Otherwise serves the object JSON using [Object.into_json] and pretty-print 179 | /// 180 | /// `federation_context` is the value of `@context`. 181 | #[cfg(feature = "actix-web")] 182 | async fn http_response( 183 | self, 184 | federation_context: &serde_json::Value, 185 | data: &Data, 186 | ) -> Result 187 | where 188 | Self::Error: From, 189 | Self::Kind: serde::Serialize + Send, 190 | { 191 | use crate::actix_web::response::{ 192 | create_http_response, 193 | create_tombstone_response, 194 | redirect_remote_object, 195 | }; 196 | let id = self.id(); 197 | let res = if !data.config.is_local_url(id) { 198 | redirect_remote_object(id) 199 | } else if !self.is_deleted() { 200 | let json = self.into_json(data).await?; 201 | create_http_response(json, federation_context)? 202 | } else { 203 | create_tombstone_response(id.clone(), federation_context)? 204 | }; 205 | Ok(res) 206 | } 207 | } 208 | 209 | /// Handler for receiving incoming activities. 210 | /// 211 | /// ``` 212 | /// # use activitystreams_kinds::activity::FollowType; 213 | /// # use url::Url; 214 | /// # use activitypub_federation::fetch::object_id::ObjectId; 215 | /// # use activitypub_federation::config::Data; 216 | /// # use activitypub_federation::traits::Activity; 217 | /// # use activitypub_federation::traits::tests::{DbConnection, DbUser}; 218 | /// #[derive(serde::Deserialize)] 219 | /// struct Follow { 220 | /// actor: ObjectId, 221 | /// object: ObjectId, 222 | /// #[serde(rename = "type")] 223 | /// kind: FollowType, 224 | /// id: Url, 225 | /// } 226 | /// 227 | /// #[async_trait::async_trait] 228 | /// impl Activity for Follow { 229 | /// type DataType = DbConnection; 230 | /// type Error = anyhow::Error; 231 | /// 232 | /// fn id(&self) -> &Url { 233 | /// &self.id 234 | /// } 235 | /// 236 | /// fn actor(&self) -> &Url { 237 | /// self.actor.inner() 238 | /// } 239 | /// 240 | /// async fn verify(&self, data: &Data) -> Result<(), Self::Error> { 241 | /// Ok(()) 242 | /// } 243 | /// 244 | /// async fn receive(self, data: &Data) -> Result<(), Self::Error> { 245 | /// let local_user = self.object.dereference(data).await?; 246 | /// let follower = self.actor.dereference(data).await?; 247 | /// data.add_follower(local_user, follower).await?; 248 | /// Ok(()) 249 | /// } 250 | /// } 251 | /// ``` 252 | #[async_trait] 253 | #[enum_delegate::register] 254 | pub trait Activity { 255 | /// App data type passed to handlers. Must be identical to 256 | /// [crate::config::FederationConfigBuilder::app_data] type. 257 | type DataType: Clone + Send + Sync; 258 | /// Error type returned by handler methods 259 | type Error; 260 | 261 | /// `id` field of the activity 262 | fn id(&self) -> &Url; 263 | 264 | /// `actor` field of activity 265 | fn actor(&self) -> &Url; 266 | 267 | /// Verifies that the received activity is valid. 268 | /// 269 | /// This needs to be a separate method, because it might be used for activities 270 | /// like `Undo/Follow`, which shouldn't perform any database write for the inner `Follow`. 271 | async fn verify(&self, data: &Data) -> Result<(), Self::Error>; 272 | 273 | /// Called when an activity is received. 274 | /// 275 | /// Should perform validation and possibly write action to the database. In case the activity 276 | /// has a nested `object` field, must call `object.from_json` handler. 277 | async fn receive(self, data: &Data) -> Result<(), Self::Error>; 278 | } 279 | 280 | /// Trait to allow retrieving common Actor data. 281 | pub trait Actor: Object + Send + 'static { 282 | /// The actor's public key for verifying signatures of incoming activities. 283 | /// 284 | /// Use [generate_actor_keypair](crate::http_signatures::generate_actor_keypair) to create the 285 | /// actor keypair. 286 | fn public_key_pem(&self) -> &str; 287 | 288 | /// The actor's private key for signing outgoing activities. 289 | /// 290 | /// Use [generate_actor_keypair](crate::http_signatures::generate_actor_keypair) to create the 291 | /// actor keypair. 292 | fn private_key_pem(&self) -> Option; 293 | 294 | /// The inbox where activities for this user should be sent to 295 | fn inbox(&self) -> Url; 296 | 297 | /// Generates a public key struct for use in the actor json representation 298 | fn public_key(&self) -> PublicKey { 299 | PublicKey::new(self.id().clone(), self.public_key_pem().to_string()) 300 | } 301 | 302 | /// The actor's shared inbox, if any 303 | fn shared_inbox(&self) -> Option { 304 | None 305 | } 306 | 307 | /// Returns shared inbox if it exists, normal inbox otherwise. 308 | fn shared_inbox_or_inbox(&self) -> Url { 309 | self.shared_inbox().unwrap_or_else(|| self.inbox()) 310 | } 311 | } 312 | 313 | /// Allow for boxing of enum variants 314 | #[async_trait] 315 | impl Activity for Box 316 | where 317 | T: Activity + Send + Sync, 318 | { 319 | type DataType = T::DataType; 320 | type Error = T::Error; 321 | 322 | fn id(&self) -> &Url { 323 | self.deref().id() 324 | } 325 | 326 | fn actor(&self) -> &Url { 327 | self.deref().actor() 328 | } 329 | 330 | async fn verify(&self, data: &Data) -> Result<(), Self::Error> { 331 | self.deref().verify(data).await 332 | } 333 | 334 | async fn receive(self, data: &Data) -> Result<(), Self::Error> { 335 | (*self).receive(data).await 336 | } 337 | } 338 | 339 | /// Trait for federating collections 340 | #[async_trait] 341 | pub trait Collection: Sized { 342 | /// Actor or object that this collection belongs to 343 | type Owner; 344 | /// App data type passed to handlers. Must be identical to 345 | /// [crate::config::FederationConfigBuilder::app_data] type. 346 | type DataType: Clone + Send + Sync; 347 | /// The type of protocol struct which gets sent over network to federate this database struct. 348 | type Kind: for<'de2> Deserialize<'de2>; 349 | /// Error type returned by handler methods 350 | type Error; 351 | 352 | /// Reads local collection from database and returns it as Activitypub JSON. 353 | async fn read_local( 354 | owner: &Self::Owner, 355 | data: &Data, 356 | ) -> Result; 357 | 358 | /// Verifies that the received object is valid. 359 | /// 360 | /// You should check here that the domain of id matches `expected_domain`. Additionally you 361 | /// should perform any application specific checks. 362 | async fn verify( 363 | json: &Self::Kind, 364 | expected_domain: &Url, 365 | data: &Data, 366 | ) -> Result<(), Self::Error>; 367 | 368 | /// Convert object from ActivityPub type to database type. 369 | /// 370 | /// Called when an object is received from HTTP fetch or as part of an activity. This method 371 | /// should also write the received object to database. Note that there is no distinction 372 | /// between create and update, so an `upsert` operation should be used. 373 | async fn from_json( 374 | json: Self::Kind, 375 | owner: &Self::Owner, 376 | data: &Data, 377 | ) -> Result; 378 | } 379 | --------------------------------------------------------------------------------