Skip to main content

developer guide

This page maps the Rust workspace to the concerns a contributor is likely to change. It is a guide to code, not a replacement for the specification, the operator guide, or the maintenance guide.

Workspace at a glance​

The workspace has four crates. The server path and the operator path are separate processes:

spindle-server (the `spindle` homeserver binary)
├── spindle-core
└── spindle-store
└── spindle-core

spindle-operator (standalone deployment control plane)
CrateOwnsStarts here
spindle-coreMatrix event values, the monotonic linear log, state snapshots and the bounded federation-DAG overlaycrates/spindle-core/src/lib.rs, then log.rs, state.rs, pdu.rs and state_table.rs
spindle-storeDurable ordered-key persistence, record codecs, backups and migrations; it uses Fjall and depends on spindle-corecrates/spindle-store/src/lib.rs, then codec.rs, backup.rs and migrate.rs
spindle-serverThe client-server and server-server HTTP surface, authentication, rooms, federation, media, administration and the spindle executablecrates/spindle-server/src/main.rs, lib.rs and routes.rs
spindle-operatorA separate control plane for durable operations, deployment drivers, audit evidence, operator authentication and its browser consolecrates/spindle-operator/src/lib.rs, then engine.rs, driver.rs, api.rs and auth.rs

spindle-operator intentionally has no path dependency on the homeserver crates. It stays available while operators stop a homeserver for migration, cutover or recovery. Do not add operator process logic to spindle-server because both projects expose APIs over HTTP.

Request and storage path​

A normal client or federation request follows this shape:

  1. crates/spindle-server/src/main.rs loads configuration, opens the spindle-store backend and builds the application state.
  2. crates/spindle-server/src/routes.rs mounts the Axum route table. The MOUNTED table is also used by the surface checks; it must not drift from the router.
  3. A handler in crates/spindle-server/src/ authenticates the caller, applies the route's access checks and delegates room/event work to the server services.
  4. Room services use spindle-core types such as RoomLog, StateSnapshot, Pdu and LinearIndex. Core keeps Matrix ancestry (prev_events) and Spindle's linear storage order as separate concepts.
  5. spindle-store encodes records and reads or writes the durable keyspaces. The server owns the request lifecycle; details about persistence belong to the store.

State resolution is not a server-only algorithm. The core log asks for a StateResolver when parent states differ. spindle-server supplies the room-version-specific implementation in state_res.rs and state_res_v1.rs. That boundary keeps the storage model reusable and leaves Matrix rules at the protocol edge.

Where to make common changes​

Add or change an HTTP endpoint​

Start in crates/spindle-server/src/routes.rs and the handler module that owns the API family. Then check all of these boundaries:

  • routes.rs: mount the route and keep MOUNTED accurate.
  • auth.rs: use Authenticated or another explicit extractor when the route needs an identity. A handler that should authenticate must not parse a bearer token in an ad hoc way.
  • surface.rs: update the advertised Matrix surface only after the code makes the route available and tests cover it.
  • crates/spindle-server/tests/ or the owning module tests: prove the route's response and authorization behavior.
  • docs/dashboard.md and docs/spec-gaps.md: run the generated-page workflow described in maintenance.md when the route changes the served surface.

A feature flag can change whether a route exists. Keep the route table, /versions claims and tests aligned for each feature combination.

Fix an authentication or authorization bug​

Separate caller identity from event authorization:

  • crates/spindle-server/src/auth.rs turns a bearer token into an identity and handles local sessions, appservice tokens and delegated authentication.
  • Route and room handlers apply resource-level checks. Follow the handler into rooms/ or the service that owns it; authentication does not grant access to a room.
  • crates/spindle-server/src/authorize.rs converts stored events and the materialized state into the input for Matrix's authorization predicate. It must not invent a second authorization algorithm.

For state-dependent event rules, compare behavior with ruma and read ADR 0005 before you change the send or federation path. divergence.md records which rules Matrix supplies and which behaviors are Spindle-specific.

Change event order, state or fork handling​

Use spindle-core first:

  • crates/spindle-core/src/log.rs owns RoomLog, LinearIndex, append order, forward extremities and the bounded federation-DAG overlay.
  • crates/spindle-core/src/state.rs owns state roots, snapshots, trie rehydration and state-resolution inputs.
  • crates/spindle-core/src/pdu.rs parses events and validates their values.
  • crates/spindle-core/src/state_table.rs owns the state-key table used by the in-memory state representation.

The server adapters in state_res.rs and state_res_v1.rs provide the room-version rules. The durable implementation in spindle-store should persist and restore the core model; it should not decide Matrix semantics. Read ADR 0001 for the linear-order/federation-DAG decision and ADR 0005 for the current resolver boundary.

Change a storage read, write or recovery path​

Start in crates/spindle-store/src/lib.rs:

  • codec.rs defines the on-disk record representation and versioned record format.
  • backup.rs defines store backup and restore behavior.
  • migrate.rs defines storage migrations.
  • The key names and content-addressed state layout come from spindle-core::keys and the core state types.

Keep storage operations narrow: the store provides ordered key-value reads, scans and writes; query or protocol policy belongs in the server. Check restore, migration and corruption behavior for each record or keyspace change. The lifecycle contract is in lifecycle.md.

Change federation or room behavior​

The protocol-facing code lives in crates/spindle-server/src/:

  • federation.rs and federation/ handle signed requests between servers, keys and federation-wide behavior.
  • inbound.rs and inbound/ handle inbound events, gaps, backfill and recovery.
  • rooms/ owns room reads, writes, extremities, policy and room-local services.
  • state_res.rs and authorize.rs connect those paths to the core state model and Matrix authorization rules.

Use the Complement and federation tests before you change a boundary. The conformance guide and divergence.md document the interoperability and divergence expectations.

Change operator workflows​

The standalone operator service is under crates/spindle-operator/src/:

  • engine.rs owns checkpointed operations, leases, approvals, cancellation and compensation over the journal.
  • driver.rs is the deployment-specific driver interface.
  • api.rs defines the /_spindle/operator/v1 API used by the console and CLI.
  • auth.rs owns OIDC-backed sessions, CSRF and roles.
  • homeserver.rs reads homeserver people, rooms and reports through an admin connection; the browser does not hold that credential.
  • console.rs serves the browser console, while secret.rs handles secret references and redaction.

Operator state has its own disk and journal. Changes to a deployment driver should not need changes to the homeserver request path.

Before opening a pull request​

  1. Read the relevant section above and the linked ADR or contract page.
  2. Add a behavior test at the boundary that would have failed before the change. Follow the test and generated-page requirements in the contribution guide.
  3. If a route, Matrix surface claim or generated page changed, run the regeneration and drift checks described in maintenance.md.
  4. Run the smallest relevant checks in the workspace, then run the pull-request gates from the contribution guide.

When the code and this guide disagree, update the guide only after you confirm that the code and its tests express the intended boundary. The specification and accepted ADRs are the decision record for architectural changes.