3 unstable releases
0.2.0 | Dec 5, 2021 |
---|---|
0.1.1 | Nov 30, 2021 |
0.1.0 | Nov 30, 2021 |
#25 in #federation
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