3 unstable releases

0.2.0 Dec 5, 2021
0.1.1 Nov 30, 2021
0.1.0 Nov 30, 2021

#25 in #federation

AGPL-3.0

98KB
2.5K SLoC

Apub: utilities for building activitypub servers

Delivery

The Deliver trait defines how to deliver objects to remote servers. There are three implementations of Deliver provided by this crate: one backed by Reqwest, one backed by Awc, and one backed by Background Jobs, with the HTTP portion backed by another Deliver implementation.

For more information, see the clients module

Fetching

The Repo trait defines how to fetch an Object from somewhere. This is generic enough to be used for fetching from a Database as well as fetching from a remote server. There are no database implementations provided by default, implementing Repo is simple enough with the help of async_trait. There are two HTTP implementations of Repo provided by apub, one backed by Reqwest and one backed by Apub.

For more information, see the clients module

Accepting

The Ingest trait is the main point for accepting activities into your system. Ingest is generic over the type it ingests. This allows for a single type to accept multiple kinds of activities with different implementations. It may be worthwile to implement Ingest<DeleteActivity> differently from Ingest<UndoActivity>. Further, implementations can implement Ingest<A> where A: SomeTrait. Creating generic Ingest implementations can enable better code re-use between kinds of activities.

See the ingest module for more types and traits to help with accepting activities

Request Utilities

When you're building an application that frequently makes HTTP Requests, you may want to preemptively stop a request from continuing. For this behavior, apub provides the Session trait. When a request is made via Awc or Reqwest's Repo or Deliver implementations, a check to the current Session is made to see if the given request should procede, and when the request finishes, the current session is notified of whether the request completed succesfully or failed. Two Session types are provided by default: BreakerSession and RequestCountSession. BreakerSession is designed to be shared between all requests the application makes, and will stop requests to domains with too many consecutive failures for a configured duration. RequestCountSession will keep track of how many requests a client makes in total, and prevents future requests if a configured limit is exceeded. A new RequestCountSession should be instantiated for each Ingest

Request Validation

Much like transportation, apub provides two implementations for cryptography, one backed by OpenSSL and one backed by the Rustcrypto libraries. When using the provided HTTP Repo implementations, HTTP SIgnatures and HTTP Digests will automatically be applied to all requests.

For dealing with Public and Private keys, two additional traits are provided: PublicKeyRepo and PrivateKeyRepo. These traits define an API for storing and retrieving keys that server ingegrations can rely on for signing and validating requests.

For more information, see the cryptography and activitypub::keys modules.

ActivityPub Impelementation

Apub provides basic traits for dealing with a few kinds of activitypub Objects. These traits are far from a perfect representation of the activitypub spec, and are instead meant to ease dealing with common types.

In addition, apub provides simple concrete implementations for an Object, and Actor, an Activity, and a Public Key. These implementations may be too basic to be of much help, but are included to aide in prototyping. The SimplePublicKey type is used in the PublicKeyRepo api.

For more information, see the activitypub module.

Feature Flags

Feature Description default
full Enable every feature false
with-actix-web Enable apub's actix-web integration false
with-awc Enable apub's awc Repo and Deliver false
with-background-jobs Enable apub's background_jobs delivery integration false
with-openssl Enable HTTP Signatures with OpenSSL false
with-reqwest Enable apub's reqwest Repo and Deliver false
with-rustcrypto Enable HTTP Signatures with rustcrypto false
utils Enable helper types and traits not strictly required true

Examples

See the examples directory for concrete implementations.

Ready-made Implementations of Repo and Deliver Utilities for ingesting activities Pre-defined validators for Ingest implementations apub integration with http servers actix-web integration Types and traits for building activitypub servers Extensions of the activitypub traits, with dereferencing via FullRepo Basic concrete types implementing activitypub traits Helpers for dealing with public and private keys More types and traits for dealing with public keys Implementations and extra traits for Sessions Cryptography implementations for HTTP Signatures More traits for dealing with digests More openssl types for signing and verification More rustcrypto types for signing and verification More traits for signing and verification

Dependencies

~2–16MB
~223K SLoC