03 · API
Make retries safe
Treat caller identity, request replay, and invalid transitions as part of the contract.
Trace an authorized mutation through validation, atomic state change, and idempotent replay.
The engineering problem
A delivery may be accepted while the browser loses its response. Retrying must return the existing result instead of receiving the same pallets again.
STEP 1
Derive the actor on the server
The reference resolves authenticated membership from the session and checks ownership on every resource. A supplied customer ID cannot grant access. The public companion binds a private workspace to an opaque HttpOnly cookie and offers three explicitly synthetic roles inside it.
STEP 2
Bind a key to intent
Confirmation, receiving, and release accept an idempotency key. The reference records actor, operation, payload fingerprint, and result in the same transaction. A repeated key with a changed payload is a conflict.
STEP 3
Design useful failures
Expired holds, incompatible pallets, excess receipts, stale revisions, and forbidden role actions return explicit errors. A release request records intent; only an operator's release changes physical custody.
YOUR TURN
Make the behavior visible.
- Receive pallets once, then use Replay last action.
- Verify that pallet count and charges remain unchanged.
- Switch from Cedar to Juniper and verify Cedar's bookings, inventory, and invoice are absent.
Acceptance evidence
Replaying a successful request creates zero additional pallets, movements, or charges. A different customer's identifier never grants access.
Read the working source.
These files belong to the downloadable PostgreSQL reference. The hosted companion has its own bounded state machine and persistence adapter.
Design review
What must the API retain when a request times out after the database commits?
Review the tradeoff
Retain the key, original payload, and the recorded result. Retry the same intent with the same key; a new key can create a second business operation.