Command Message Handler¶
Message-handling method — instantiates Message-Mediated State Coordination
Receives a directed, imperative command message, decides whether it may and should be honoured, and either applies it as a state change or rejects it with a reason.
A Command Message Handler is the code that receives a command — a message naming an action it wants performed on one specific recipient ("cancel this reservation," "charge this card") — and is the single authority that decides whether to carry it out. The idea that makes it this mechanism, and not an event reactor: a command is imperative, directed, and refusable. Unlike an event — a fact that already happened, broadcast to whoever cares, which is Event Choreography's domain — a command is a request aimed at one owner who validates it against current state and authority, then either enacts the change or rejects it. The handler is the gate where "someone asked for X" becomes "X happened" or "X was denied."
Example¶
A hotel reservation service receives a CancelReservation command carrying a reservation ID, the caller's identity, and a reason. The service's command handler is the sole authority on the reservation's fate. It authenticates that the caller owns this reservation or is authorized staff; it checks the reservation exists and is in a cancellable state (not already checked in, still inside the free-cancellation window); and it validates the command's own fields. If everything holds, it applies the change — marks the reservation cancelled, releases the room back to inventory — and emits a ReservationCancelled event for billing and housekeeping to react to. If a precondition fails ("past the cancellation deadline"), it does not silently drop the message: it returns a typed rejection the caller can show the guest. And it honours only the fields the command legitimately needs — a waiveFee: true flag smuggled into the payload is ignored unless the caller's authority actually permits waivers. The outcome: every change to a reservation flows through one auditable decision point that can say no.
How it works¶
- Classify the intent. Recognize the message as a command (do-this), distinct from an event (this-happened) or a query (tell-me) — commands are the class that may mutate state and may be rejected.
- Authorize before acting. Check that the sender is permitted to issue this command against this target before touching any state.
- Validate against invariants. Test the command's fields and the recipient's current state; a command is honoured only if it leaves the recipient in a valid state.
- Apply or reject, definitively. Enact the change or return a typed rejection — never a silent drop — so the caller always learns the outcome.
Tuning parameters¶
- Validation strictness — how much the handler checks before acting. Stricter protects invariants but rejects more edge cases and couples the handler to more state.
- Rejection surface — silent drop versus typed error versus compensating reply. Rich rejections help callers recover but expand the contract and can leak internal reasons.
- Authority model — where permission is decided: in the handler, at an upstream gateway, or carried in the message as a capability token. Moving it upstream simplifies the handler but trusts the edge.
- Minimization stance — whether the handler reads only declared fields and rejects unknown ones, or tolerantly ignores extras. Strict minimization limits blast radius and privilege creep; tolerance eases evolution.
When it helps, and when it misleads¶
Its strength is concentrating every state-changing decision for a recipient into one authority that enforces invariants, authorization, and validation in a single auditable place — the backbone of the command side of CQRS.[n1] Because a command is directed and answerable, the caller learns whether it succeeded, unlike a fire-and-forget event.
Its failure modes are the price of that centralization. The handler is a natural bottleneck and a single point of failure for its target — everything that changes the recipient waits on it. Treating commands like events (or the reverse) is the classic modelling error: broadcasting a command to many handlers means several parties each "do it," while awaiting a reply to an event couples things that should stay decoupled. And because a command can be redelivered on retry, a handler that isn't idempotent will apply the same change twice — charge twice, cancel-then-reinstate — so deduplication is essential, but it belongs to Retry with Idempotency Key, not here. The discipline is to keep commands directed (one recipient, one authority), always return a definite accept or reject, and never let a handler mutate anyone's state but its own recipient's.
How it implements the components¶
message_intent_taxonomy— it defines and enforces the command category: which messages are imperative, directed, and refusable, as opposed to broadcast events or read-only queries.receiver_handler_rule— it is the rule mapping a received command to a validated state transition or a typed rejection.message_authorization_and_minimization_rule— at handling time it enforces the sender's authority to issue this command and honours only the fields the command legitimately needs.
It enforces authority but does not define the field-level allow-list or the message contract it checks against (message_contract, schema_version_negotiation — see Message Schema Registry); it handles directed commands, so the event facet of message_intent_taxonomy and receiver_handler_rule is Event Choreography's; and it neither dedupes a redelivered command (idempotency_and_correlation_marker — see Retry with Idempotency Key) nor guarantees the command reached it (channel_delivery_semantics — see Durable Queue with Acknowledgement).
Related¶
- Instantiates: Message-Mediated State Coordination — it is the single decision authority through which a directed command becomes a state change.
- Sibling mechanisms: Event Choreography · Actor Mailbox Loop · Message Schema Registry · Retry with Idempotency Key · Request-Reply Correlation · Durable Queue with Acknowledgement
Editorial Notes¶
Form Classification¶
Form family: Control, Automation & Runtime
Rationale: Receives a directed, imperative command message, decides whether it may and should be honoured, and either applies it as a state change or rejects it with a reason, making its operative form a live operational control that automatically routes, enforces, adapts, or responds during execution.
Independent corroboration: The frozen evidence defines Command Message Handler as 'Receives a directed, imperative command message, decides whether it may and should be honoured, and either applies it as a state change or rejects it with a reason', so its operative form is Control, Automation & Runtime.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Single lineage
Present-day reach: Multi-domain
Rationale: Message-oriented and actor-system design established directed, refusable command handlers that validate authority and current state before mutation.
Review resolution: Both reviewers agree on computer_science as primary. Reading the source mechanism confirms that its defining operation belongs to that lineage; the final record retains no alternate lineage only where it materially formed the mechanism and keeps present-day application breadth separate from provenance.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
In an actor system the command handler is often the actor's receive behaviour itself: Actor Mailbox Loop supplies the serialized, one-at-a-time execution context, and this supplies the per-command decision of whether and how to apply the change. Keeping them distinct is useful — the same command-handling rule can run inside an actor loop, behind a durable queue, or straight off an HTTP endpoint, because the authority-and-validation logic is independent of how the command was delivered.
[n1] CQRS (Command Query Responsibility Segregation) — separating the model that changes state (commands) from the one that reads it (queries). The command message handler is the write side's entry point; keeping commands and queries distinct is what lets each be validated, scaled, and reasoned about on its own terms. ↩