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)
| Crate | Owns | Starts here |
|---|---|---|
spindle-core | Matrix event values, the monotonic linear log, state snapshots and the bounded federation-DAG overlay | crates/spindle-core/src/lib.rs, then log.rs, state.rs, pdu.rs and state_table.rs |
spindle-store | Durable ordered-key persistence, record codecs, backups and migrations; it uses Fjall and depends on spindle-core | crates/spindle-store/src/lib.rs, then codec.rs, backup.rs and migrate.rs |
spindle-server | The client-server and server-server HTTP surface, authentication, rooms, federation, media, administration and the spindle executable | crates/spindle-server/src/main.rs, lib.rs and routes.rs |
spindle-operator | A separate control plane for durable operations, deployment drivers, audit evidence, operator authentication and its browser console | crates/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:
crates/spindle-server/src/main.rsloads configuration, opens thespindle-storebackend and builds the application state.crates/spindle-server/src/routes.rsmounts the Axum route table. TheMOUNTEDtable is also used by the surface checks; it must not drift from the router.- 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. - Room services use
spindle-coretypes such asRoomLog,StateSnapshot,PduandLinearIndex. Core keeps Matrix ancestry (prev_events) and Spindle's linear storage order as separate concepts. spindle-storeencodes 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 keepMOUNTEDaccurate.auth.rs: useAuthenticatedor 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.mdanddocs/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.rsturns 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.rsconverts 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.rsownsRoomLog,LinearIndex, append order, forward extremities and the bounded federation-DAG overlay.crates/spindle-core/src/state.rsowns state roots, snapshots, trie rehydration and state-resolution inputs.crates/spindle-core/src/pdu.rsparses events and validates their values.crates/spindle-core/src/state_table.rsowns 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.rsdefines the on-disk record representation and versioned record format.backup.rsdefines store backup and restore behavior.migrate.rsdefines storage migrations.- The key names and content-addressed state layout come from
spindle-core::keysand 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.rsandfederation/handle signed requests between servers, keys and federation-wide behavior.inbound.rsandinbound/handle inbound events, gaps, backfill and recovery.rooms/owns room reads, writes, extremities, policy and room-local services.state_res.rsandauthorize.rsconnect 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.rsowns checkpointed operations, leases, approvals, cancellation and compensation over the journal.driver.rsis the deployment-specific driver interface.api.rsdefines the/_spindle/operator/v1API used by the console and CLI.auth.rsowns OIDC-backed sessions, CSRF and roles.homeserver.rsreads homeserver people, rooms and reports through an admin connection; the browser does not hold that credential.console.rsserves the browser console, whilesecret.rshandles 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
- Read the relevant section above and the linked ADR or contract page.
- 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.
- If a route, Matrix surface claim or generated page changed, run the regeneration and drift checks described in maintenance.md.
- 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.