Part of Stem. This page defines the handler and fixes what it takes in and what it puts out.
The handler is the single routine through which every blob enters a peer's index: it decodes and verifies the blob, finds the kind definition it belongs to, validates it against that kind, evaluates authority, and emits facts, links, node-to-blob mappings and the set of resources whose state must be re-evaluated.
There is one handler, not one per blob type. The six signed blob types are few enough that decoding is a small switch, and everything after decoding is driven by data: the Kind descriptor says which state representation to expect, which schema to validate against, where the targeted node is, which fields produce which links, and what to retain. A new kind of resource is a new kind descriptor and a new schema, both published as resources, and the handler needs no change.
Inputs
A blob, its CID, and the context of its arrival: the peer it came from (if any), the account that peer authenticated as, and the scope the sender claimed, which for a local publish is the daemon's own.
Steps
Decode and verify. DAG-CBOR decode; read type; verify the signature as in Signed blobs. A blob that fails is rejected and the whole transfer batch it arrived in is refused, exactly as today.
Migrate if HM24. A Ref, Capability, Comment, Profile or Contact is passed through the migration box described in Migration, which yields the Stem records the blob stands for. The original bytes are kept; the derived records are indexed as if they had arrived.
Resolve the kind. For a Node blob, fetch or look up the kind definition it names and check it against the node's creating blob. For a Change or Snapshot, the kind comes from the node whose head reaches it; a state blob not yet reached by any node is stored and stashed as pending. For a Grant, Revocation or Group there is no kind; they go to the authority graph.
Validate. Check the blob's structural rules (the "Rules" section of its schema page) and, for Snapshots, the value against the kind's schema. Validation of Snapshots of the core kinds is strict. Validation of document attributes stays advisory, as it is today.
Authorize. Ask the authority graph whether the signer holds the level the blob needs. If the needed grants are not present, fetch the blob's proof chain from the sender before giving up; if still not present, stash the blob with reason unauthorized and the signer as the retry key. For a transfer, also check the blob belongs to the claimed scope by the scope set derivation; a blob outside the claimed scope is rejected, not stashed.
Emit. Record the blob's row; emit links by walking the kind's link rules and the blob's structural fields (deps, prev, heads, parent, proof, schema); emit facts marked signed for values read from the blob; map the blob to the nodes whose state it belongs to; and compute the set of affected resources: the node a Node blob declares, the nodes whose heads reach a Change or Snapshot, every node whose readers may change because of a Grant or Revocation.
Re-evaluate. Fold the affected resources (Resources and nodes), recompute their readers, update the blob access relation, recompute derived facts (child counts, comment counts, first image), update the materialised scope sets, and retry every stashed blob keyed on anything that just changed.
Everything from step 3 on runs inside one transaction per batch, so a reader of the index never sees a half-applied blob.
Outputs
the blob row and its node mappings
links, each typed by link kind
facts, each marked signed or derived
the updated authority graph and readers
the set of affected resources, folded
stash rows for what could not be applied, with the key that will retry them
a transfer record with the per-blob verdict, when the blob came from a peer
Today (HM24)
The daemon has seven indexers, one per blob type, each writing its own rows and each knowing the visibility rules for its type, and sync and permissions know the types by name. The runtime model page explains why collapsing them into one data-driven routine is the point of Stem.
See also
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime