idempotency

type FingerprintMismatchError ¶

type FingerprintMismatchError struct {
	// Stored is the canonical fingerprint blob (see computeFingerprint) recorded
	// for the original Claim. Opaque to the Store; parsed only by the middleware.
	Stored string
}

FingerprintMismatchError wraps ErrFingerprintMismatch and carries the stored canonical fingerprint blob recorded for the original request, so the middleware can compute a per-field diff naming the top-level fields that changed. Stored holds ONLY per-field hashes (hex sha256), never raw request values — echoing a stored request value is structurally impossible because raw values are never persisted.

func (e *FingerprintMismatchError) Error() string

func (e *FingerprintMismatchError) Unwrap() error

type IdempotencyKey ¶

type IdempotencyKey struct {
	// contains filtered or unexported fields
}

IdempotencyKey is the sealed (namespace, key) pair that scopes one idempotency record. Its fields are unexported, so a populated IdempotencyKey{...} literal cannot be constructed outside this package — the only producers are the sanctioned constructors DeriveKey (HTTP records) and DeriveCommandKey (commands). Stores read it through Namespace()/Key().

Why sealed (the node-agnostic invariant, #1449/#1610) ¶

The framework HTTP idempotency replay store is assembly-wide: every pod in an assembly sharing one Redis deduplicates the same logical request. That rests on the (ns,key) carrying NO per-pod / per-listener / per-cell dimension — it is derived ONLY from request + principal data. Sealing the type makes that structural, on two axes (AI-robust grading, frozen by archtest HTTP-IDEMPOTENCY-KEY-NODE-AGNOSTIC-01; governance真值源 = ADR docs/architecture/202606051000-1449-adr-http-idempotency-assembly-scope-namespace.md):

• node-agnostic / ban-external-source — Hard, both directions: upstream-external Hard (unexported fields ⇒ no other package can mint a key and splice in node-local state — "sealed construction") + downstream Hard (Store.Claim takes IdempotencyKey, so a raw (ns,key) string pair is inexpressible at the store boundary). NOTE: upstream is Hard only against OTHER packages; an in-package populated literal or a second in-package producer is NOT a compile error — the archtest sole-producer freeze is the Medium backstop there (same split as metrics.CellLabel / holder-seal #893).
• require-isolation-tuple (each sanctioned constructor's body must FLOW all its dimensions into the key) — Medium, genuine Go ceiling: Go cannot express "a body consumes all its inputs", and the same-type string params could be transposed at the (single, reviewed) callsite. The β archtest's AST taint walk (with a flat-composition guard that rejects value laundering) is the Medium backstop. Won't-do ceiling tracked at gh #1650 (same family as #851/#893/#1282/#1552).

Two sanctioned constructors (HTTP record + cross-cell command, #1669) ¶

DeriveKey mints the HTTP record key. DeriveCommandKey (#1669) mints the command dedup key from (tenant, subject, command_id) — the bridge primitive the cross-cell same-slot half of #1610 consumes (routing one logical command to a single dedup slot across cells). Both produce this SAME sealed IdempotencyKey and flow through the SAME Store.Claim sink — the sealed type + funnel are the durable infra and need no change. The archtest sole-producer allowlist + the per-constructor signature/taint gate are single-sourced from one table (idempotencyKeyConstructors), so both constructors are locked identically and a third producer cannot be added to one gate while skipping the other.

func DeriveCommandKey(tenantID, subject, commandID string) IdempotencyKey

ns  = tenantID, or noTenantSentinel when empty.
key = subject + "\x00" + commandID

func DeriveKey(tenantID, subject, method, path, idemKey string) IdempotencyKey

ns  = tenantID, or noTenantSentinel when empty.
key = subject + "\x00" + method + "\x00" + path + "\x00" + idemKey

func (k IdempotencyKey) Key() string

func (k IdempotencyKey) Namespace() string

type MemStore ¶

type MemStore struct {
	// contains filtered or unexported fields
}

MemStore is an in-process Store implementation backed by a mutex-guarded map. It is safe for use in unit tests and single-pod demo deployments; it does NOT coordinate idempotency across replicas.

Use a Redis-backed Store for multi-replica deployments.

func NewMemStore(clk clock.Clock) *MemStore

func (ms *MemStore) Claim(ctx context.Context, k IdempotencyKey, fingerprint string, leaseTTL time.Duration) (idempotency.ClaimState, *RecordedResponse, Receipt, error)

type MetricsObserver ¶

type MetricsObserver interface {
	ObserveRequest(ctx context.Context, state RequestState)
}

MetricsObserver is the best-effort sink for per-request idempotency metrics. The HTTP idempotency Middleware calls ObserveRequest once per idempotency state event with the corresponding RequestState. Most requests emit a single event; an acquired request whose response is oversize emits two — StateAcquired at claim time, then StateOversize when the body overflows (see RequestState for the acquired ⊇ oversize relationship). The other five states are mutually exclusive and emit once each. The interface lives in this producer package (not in runtime/observability/metrics) so the middleware never imports the metrics package — mirroring the executor.Observer placement that lets runtime/observability/metrics.SagaCollector import the producer without an import cycle.

Implementations MUST be non-blocking and tolerate canceled contexts: they run on the request hot path and must never affect idempotency correctness. The canonical production implementation is runtime/observability/metrics.IdempotencyCollector, which records idempotency_requests_total{cell,state} and derives the {cell} label from the request context. ObserveRequest deliberately takes no cellID argument: the owner cell is read from ctx by the collector (kernel/ctxkeys.CellID, set by the router root CellAttribution middleware) so the {cell} sentinel single source stays in the metrics package and the middleware stays metrics-agnostic.

type Option ¶

type Option func(*middlewareConfig)

Option is a functional option for Middleware.

func WithDoneTTL(d time.Duration) Option

func WithExemptMatcher(fn func(*http.Request) bool) Option

func WithLeaseTTL(d time.Duration) Option

func WithMaxBodyBytes(n int) Option

func WithMetrics(obs MetricsObserver) Option

type Receipt ¶

type Receipt interface {
	// Record persists resp as the canonical response for this idempotency key
	// and commits the lease, making the key's state ClaimDone for doneTTL.
	// doneTTL controls how long future requests replay the stored response
	// (typically kernel/idempotency.DefaultTTL = 24h).
	Record(ctx context.Context, resp *RecordedResponse, doneTTL time.Duration) error

	// Release abandons the in-progress lease without recording a response,
	// allowing the key to be re-claimed by a subsequent request.
	Release(ctx context.Context) error
}

Receipt is the HTTP-specific lifecycle handle for a single acquired idempotency lease. It mirrors kernel/idempotency.Receipt but Commit carries the response blob — the HTTP layer must persist the response for future replay before committing.

Usage for ClaimAcquired:

1. Run the HTTP handler to produce a response.
2. Call Record(ctx, resp, doneTTL) to persist the response and commit the lease.
3. On handler error (before or after partial writes), call Release(ctx) so the lease expires and another request may retry.

Record and Release are idempotent with respect to the lease state: calling them on a non-acquired claim state returns kernel/idempotency.ErrNoClaimLease.

Store implementors: both Record and Release are typically called from a defer after the request context may already be canceled (timeout/client disconnect). Use context.WithoutCancel(ctx) when issuing the underlying store operations so the commit/release reaches the backend even when the request context is canceled. See runtime/http/idempotency.Middleware for the reference implementation.

type RecordedResponse ¶

type RecordedResponse struct {
	// contains filtered or unexported fields
}

RecordedResponse is the sealed blob stored by the idempotency middleware for future replay on ClaimDone. All fields are unexported; consumers read state through the value-receiver getters below.

Sealed construction: the only ways to obtain a RecordedResponse are newRecordedResponse (package-internal producer constructor used by the HTTP middleware after handler execution) and UnmarshalRecordedResponse (the wire-decode funnel used by Store implementations when loading a stored blob). Composite literals RecordedResponse{...} outside this package are a compile error (all fields unexported).

func UnmarshalRecordedResponse(raw []byte) (RecordedResponse, error)

func (r RecordedResponse) Body() []byte

func (r RecordedResponse) Header() http.Header

func (r RecordedResponse) RecordedAt() time.Time

func (r RecordedResponse) Status() int

type RequestState ¶

type RequestState string

RequestState is the typed, wire-stable label value identifying the outcome of a single idempotency decision. Its value set is frozen as the metric label values of idempotency_requests_total{state} and is enforced by archtest IDEMPOTENCY-REQUESTS-STATE-LABEL-VALUES-FROZEN-01 (A1 freezes the value set; A2 forbids inline literals / RequestState("x") conversions from reaching the label, requiring every value to flow from one of the declared constants below). The same string-typed-enum funnel is used by the saga executor (executor.TickResult / DriveResult / …) and reconcile (resultLabel).

Cardinality: the value set is a closed, registration-time enumeration (6 values); combined with the bounded {cell} dimension the worst-case series count is tiny. There is no per-request / per-key dimension — keys are SHA-256 hashed for logs only and never become metric labels.

const (
	// StateAcquired is recorded once per fresh claim (ClaimAcquired): the lease
	// was acquired and the business handler runs. It is the denominator of
	// processed mutating requests. It is emitted at claim time, BEFORE the
	// handler completes, so it counts every fresh claim regardless of the
	// handler's terminal outcome (successful record, 4xx/5xx, oversize, or
	// panic) — acquired is not the sum of the other states. StateOversize is a
	// sub-event of an acquired request (an acquired request whose response was
	// too large to record increments both acquired and oversize), so
	// oversize/acquired is the uncacheable-response rate.
	StateAcquired RequestState = "acquired"

	// StateReplayed is recorded when a stored response is replayed (ClaimDone):
	// the idempotency key hit and the cached response was served without
	// re-invoking the handler.
	StateReplayed RequestState = "replayed"

	// StateBusy is recorded when an in-flight lease exists for the key
	// (ClaimBusy → 409 with Retry-After). A sustained busy rate signals a
	// retry storm or a stuck in-flight request.
	StateBusy RequestState = "busy"

	// StateStoreError is recorded when Store.Claim returns a non-fingerprint
	// error (→ 500). It is the Claim-path store failure rate. Record/Release
	// failures (after the response is already served) are intentionally not a
	// state — they are logged at slog.Error and are out of this counter's scope.
	StateStoreError RequestState = "store_error"

	// StateOversize is recorded when an acquired request's response body exceeds
	// the buffer limit and is therefore not recorded for future replay
	// (the response is still served to the client normally). See StateAcquired
	// for the acquired ⊇ oversize relationship.
	StateOversize RequestState = "oversize"

	// StateKeyReused is recorded when the same Idempotency-Key is presented with
	// a different request body (fingerprint mismatch → 422 ErrIdempotencyKeyReused).
	// It is security-relevant: a sustained rate can indicate a client bug or a
	// replay attempt.
	StateKeyReused RequestState = "key_reused"
)

type Store ¶

type Store interface {
	Claim(ctx context.Context, k IdempotencyKey, fingerprint string, leaseTTL time.Duration) (idempotency.ClaimState, *RecordedResponse, Receipt, error) //nolint:lll // full Claim contract signature cannot be wrapped in an interface decl
}

Store is the HTTP-layer idempotency backend. Implementations live in adapters/ (e.g., adapters/redis).

Claim semantics — discriminate on the returned ClaimState:

switch state {
case idempotency.ClaimAcquired:
    // rec is nil; receipt is the acquired lease.
    // Run the handler, call receipt.Record on success, receipt.Release on error.
case idempotency.ClaimDone:
    // rec is non-nil; replay it. MUST NOT run the handler again.
case idempotency.ClaimBusy:
    // rec is nil; another request is in-flight. Return 409.
}

On error (err != nil), fail closed: do not run the handler. If err wraps ErrFingerprintMismatch (errors.Is), the same key was previously claimed with a different fingerprint — the middleware returns 422 (KindUnprocessable) with ErrIdempotencyKeyReused. Do NOT add a 4th ClaimState for this case; use the sentinel error path instead. Implementations MUST return a *FingerprintMismatchError (which wraps the sentinel) so the middleware can recover the stored fingerprint blob for the per-field diff.

k is the sealed (namespace, key) pair produced by a sanctioned constructor (DeriveKey from the HTTP request + principal isolation tuple, or DeriveCommandKey from the command isolation tuple); the Store reads it via k.Namespace() (the tenant scope, or "_notenant" when absent) and k.Key() (the per-request key — see those constructors for the byte layout). A raw (ns,key) string pair cannot reach Claim — that typed boundary is the downstream Hard gate of the node-agnostic invariant (#1449/#1610). fingerprint is the opaque canonical blob produced by computeFingerprint (JSON whose Body field is hex(sha256(rawBody)) and whose Fields field maps top-level field names to per-field hashes for the diff); the Store treats it as an opaque string and only compares / round-trips it.