Reifying a request as a command object enables queueing, scheduling, retrying and logging. What properties must those command objects have to be safely queued and replayed?

## What changes when the command leaves the stack An in-process command executes microseconds after creation, in the same address space, with the same clock, the same logged-in user, the same open transaction. A queued or logged command may execute: - minutes or days later, - on a different machine, - after a process restart, - **more than once**, - possibly out of order relative to its siblings, - against code that has since been deployed and changed. Every property below follows from that list. ## 1. Self-containment (capture the context at creation) Anything ambient must be materialized into fields: - **Identity**: who requested it (`requestedBy`), and what they were authorized to do. Do not re-derive it at execution — there is no session then. Authorization decisions are usually made at *enqueue* time and recorded; re-checking at execution is a second, deliberate policy choice. - **Time**: `requestedAt` as data. A command that calls "now()" inside execute produces a different result on replay. - **Randomness / generated identifiers**: generate the new entity's ID at creation and store it, so a retry writes the *same* ID instead of creating a duplicate row. This single trick converts many non-idempotent creates into idempotent ones. - **Snapshot vs reference for inputs**: decide deliberately. Storing `productId` means the command executes against the *current* price; storing `priceAtOrderTime` means it executes against the price the user saw. Both are valid; silently picking one is the bug. ## 2. Serializability The command becomes a message: named primitive fields + a type discriminator, encoded as JSON/protobuf/Avro or a table row. Consequences: - **No live dependencies inside the command.** Repositories, HTTP clients, connections, and closures cannot be serialized. This forces the *request-as-data + handler* split: the command carries only data; the handler (resolved by command type) owns the collaborators. This is exactly how command buses, job frameworks, and actor systems work. - **Keep payloads small.** Store references to large blobs, not the blobs. ## 3. Idempotency — the hardest one Durable messaging is **at-least-once** by default: exactly-once end-to-end delivery is not achievable in general, because the acknowledgement can be lost after the effect was applied. So plan for duplicates: - **Idempotency key**: a stable identifier generated once at command creation (not at retry). The handler records processed keys in the same transaction as the effect and skips duplicates. Storing the key with the effect atomically is what makes this correct; a separate "seen" cache updated after the effect leaves a crash window. - **Naturally idempotent effects**: prefer absolute over relative operations — `setStatus(SHIPPED)` replays safely, `incrementBalance(10)` does not. Conditional writes ("update where version = 7", compare-and-set) achieve the same effect. - **Effects outside your database** — sending mail, calling a payment provider — need the provider's own idempotency key, or an outbox pattern where the intent is committed transactionally and dispatched afterwards with dedup. ## 4. Versioning and schema evolution A persisted command is a long-lived contract with your future self. Rules: add fields with defaults, never repurpose or remove a field's meaning, carry an explicit `version`/schema id, and keep upcasting logic that can read old payloads. For replayable logs (undo history that survives restarts, event-sourced streams, crash-recovery journals), old commands may be re-read years later. Deleting a command class without a migration path bricks the log. ## 5. Ordering Stacking commands in a queue does not preserve order once you add concurrency and retries. Decide explicitly: - **Global ordering**: single consumer, no parallelism — simple, slow. - **Per-key ordering**: partition by aggregate/entity id so all commands for one entity run in order while different entities run in parallel. This is the usual answer. - **No ordering**: only acceptable if commands are commutative. Also beware retries reordering: a failed command retried after a later one already succeeded will apply stale intent. Optimistic-concurrency version checks ("apply only if the target is still at version N") reject such stale commands. ## 6. Lifecycle, failure, and observability - **Status separated from submission**: pending / in-flight / succeeded / failed, plus attempt count. "Accepted" is not "done" — the API contract usually becomes 202 + a job id the caller polls. - **Retry policy**: exponential backoff with jitter; distinguish *transient* failures (retry) from *permanent* ones (invalid data — never retryable, don't burn attempts). - **Dead-letter store**: after N attempts, park the command with its error for inspection rather than looping forever or dropping it silently. - **Poison messages and stuck jobs**: a visibility timeout / lease with automatic reclaim, so a worker that dies mid-command doesn't strand it forever. - **Correlation**: carry a trace/correlation id so the deferred execution can be tied back to the originating request in logs. ## 7. Authorization Because the command is now data on a queue, whoever can write to the queue can request the effect. Validate and authorize **before** enqueueing, record the decision in the command, and treat the queue itself as a trust boundary (a worker should not blindly trust a payload from an untrusted producer). ## The takeaway Queueing is not a free consequence of "the request is an object". It is a consequence of the request being **self-contained, serializable, replay-safe, and versioned data**. Command gives you the shape; those four properties give you the correctness.