Design
The Fediversity API lets API clients manage deployments of Fediverse applications (Mastodon, PeerTube and Pixelfed) through hosting providers. It wraps the stateless deployment programs of core, and adds queued execution, progress reports and authorization.
This document gives the design and its reasons. The normative requirements are in the feature specifications under specs/:
| Topic | Specification |
|---|---|
| Deployments, builds, delete, actions, update policy, audit events | 001-deployments-and-builds |
| Schema, renames, migration, trusted sources, the self-pin | 002-schema-and-sources |
| The component catalog and its artwork | 003-application-catalog |
| The authorization callback, the service token, CORS, the reconcile callback | 004-authorization |
| Jobs, isolation of deployments, progress events | 005-job-execution |
| The NixOS module, the development shell, the published contract | 006-service-deployment |
Actors
- API clients (front-ends such as the panel): submit configurations, follow progress, manage deployments.
- API service (HTTP RPC and Centrifugo pub/sub): accepts requests, manages the build queue, brokers events.
- Builders: run the Nix builds and the deployments. They can be dedicated builder nodes (#366).
- TF backend: keeps the state of each deployment, one address per deployment.
Design rationale
A deployment is a long-running operation with state. A request-response model alone is a bad fit for progress reports: clients must poll, and HTTP connections can time out. Thus the wire surface has two parts: stateless RPC over HTTP for submit, query, cancel and list, and WebSocket pub/sub through Centrifugo for build progress and changes of deployment state.
Each part has a standard document, made from the models in the code:
| Layer | Format |
|---|---|
| HTTP RPC (submit, query, cancel, delete, schema, builds, logs) | OpenAPI 3.1 |
| Pub/sub events (build progress, deployment state changes) | AsyncAPI 3.0 |
Pages
- Transport -- HTTP RPC and Centrifugo pub/sub.
- Deployments -- deployment identifiers, the two-store model and deletion, what a configuration serves, the SBOM and the secrets of the operator.
- Authorization and access -- the authorization callback, audit events and the front-end access model.
- Schema and migration sources -- the schema endpoints, migration semantics and the default-source baseline freeze.
- The component catalog -- the listing and its artwork.
- Deployment actions -- suspend and resume, operations of an application and the objects left behind.
- Migrations -- export, the follow of a deSEC zone, transfer sources, the dry eval and the restore of a migration import.
- Domains -- claims, registration, transfer-in, terms, renewal, take-out, change, contact, owner and the own zone token.
- Update policy -- who starts the deploy of a new self-pin.
- Usage -- the usage periods and the domain events that a hosting provider bills.
- Build Queue -- queue semantics, the backend selection criteria and the queue backends.
- Future Considerations -- open design questions.