Module spool 

The durable spool: a delivery is on disk and fsync’d before console acknowledges GitHub.

Why: both existing webhook handlers return 202 and then do the work, so any failure after the ack loses the delivery permanently — GitHub does not retry an acknowledged delivery (ADR-0034 Context, “The fail-open shape, already shipped on this exact path”). Ordering the durable write before the ack is what makes a lost delivery either recoverable from GitHub (never acked) or visible in a health signal (acked and spooled). That ordering only holds if the write is genuinely durable, hence the fsync of both the file and its directory.

What: one JSON file per delivery under resolve_data_dir("trusty-console")/webhook-spool/. Spool::persist_new writes a temp file, fsyncs it, links it into place — refusing to clobber an entry already there — then fsyncs the directory so the new name survives a crash. Spool::persist_update is the same sequence committing with rename, for Spool::record_attempt’s deliberate overwrite. Spool::remove_acked is the only deletion path and is reachable only from an explicit target acknowledgement.

🔴 Spool::list_pending answers a missing directory with an error, not an empty listing, for any spool that was successfully opened. An unreadable spool reported as “nothing pending” makes the health scan green while every delivery 500s.

🔴 Every fallible step here returns an error to the caller. Nothing in this module logs-and-continues, because a swallowed spool failure is exactly the defect the spool exists to remove.

Test: webhook/tests.rs — spool_* cases cover the durable round trip, attempt bumping, ack-only deletion, and both write-failure arms.

Structs

EntryMeta

One entry as described by its filename alone — no file was opened.

PendingEntry

A pending entry paired with the path it lives at.

PendingListing

Result of one Spool::list_pending sweep.

Provenance

What console proves to the target about a relayed body (ADR-0034 §3).

Spool

The on-disk spool rooted at one directory.

SpoolEntry

One spooled delivery.

SpoolMetadata

Result of one Spool::scan_metadata pass.

Enums

SpoolError

Failures of the durable-write path. Every variant means the delivery is not safely recorded, so every one of them must reach the HTTP caller as a 5xx rather than a log line.

Constants

EXHAUSTED_DIR_NAME

Subdirectory holding deliveries console has stopped trying to relay.

SPOOL_DIR_NAME

Directory name under the console’s data dir.

SPOOL_SCHEMA_VERSION

Bumped whenever SpoolEntry’s shape changes, so a future reader can tell an entry it cannot interpret from one it can.