Download the PHP package rasuvaeff/yii3-idempotency without Composer

rasuvaeff/yii3-idempotency

Русская версия

Idempotency key middleware for Yii3 APIs. Prevents duplicate processing of POST/PUT/PATCH requests.

Using an AI coding assistant? llms.txt contains a compact API reference you can feed to the LLM. Projects using the llm/skills Composer plugin also get this package's agent skill synced into .agents/skills/ automatically on install.

Requirements

• PHP 8.3+
• psr/clock ^1.0
• psr/http-message ^2.0
• psr/http-server-middleware ^1.0

Installation

Usage

Basic setup

How it works

Failure classification

By default every throwable released the claim, so a deterministic business outcome (PaymentDeclined, InsufficientFunds) was re-executed on retry. Give the middleware a DomainFailureRenderer and domain failures become part of the cached outcome instead:

DefaultFailureClassifier decides, in order:

FailureKind::Bug is never inferred — declare it via an override. Both Bug and Infrastructure release the claim and rethrow; the distinction is for your own reporting.

The middleware caches exactly what the renderer returns, so the first attempt and every replay are byte-identical. A renderer that returns null declines the failure: the claim is released and the original throwable is rethrown. Without a renderer nothing changes — every throwable stays retryable.

Only the throwing path is classified. A handler that returns a 4xx response still releases the claim.

Caller scoping

scopeResolver has no default, on purpose. A keyspace shared by every caller lets one client replay another client's cached response — and the replay path returns the stored response without ever entering the handler, so it never reaches the handler's authorization checks either. The same gap lets a client occupy someone else's key and lock them out for the whole TTL.

A request with no principal resolves to the anonymous namespace, which every anonymous caller shares — there is no identity to separate them by. Do not put caller-private data behind an idempotent endpoint reachable anonymously. The namespace is tagged by caller state (caller:identity:<id> against caller:anonymous:<name>), so an authenticated caller whose identifier happens to read anonymous never lands in it.

Opt-out. SharedKeyspaceScopeResolver puts every caller in one keyspace, which is the pre-2.0 behaviour. It is safe only when a single principal can reach the middleware — a single-tenant deployment, an internal service with one trusted client, or an endpoint whose responses hold nothing caller-private.

Endpoint scoping

A key also identifies the request but not the endpoint, so the same key sent to two endpoints would collide on one record. CompositeScopeResolver stacks the endpoint namespace on top of the caller:

The storage key becomes sha256(scope . "\0" . key) — a fixed 64 characters, so a long-but-valid client key can never be pushed past the 255-character limit. Stored keys are therefore opaque: scoping trades greppable keys for collision freedom. A scope name that would itself exceed 1024 characters (a long path, a long principal identifier, several dimensions joined) is collapsed to its hash rather than rejected, so request data cannot turn a request into a 500 by its length alone. Other resolution failures — an attribute holding a value the resolver cannot stringify, for example — still surface as errors: they are deployment mistakes, not client input.

Each dimension is length-prefixed before the parts are joined (21:caller:identity:alice | 16:POST /api/orders), so the separator appearing inside a name cannot make two different compositions resolve to one scope.

ScopedIdempotencyKeyExtractor still applies a scope at the extractor level and is kept for compatibility, but scoping the middleware is the supported way: it is the one place that cannot be left out.

Keys from the payload

For queue handlers and command-bus consumers the key lives inside the payload rather than in a header:

The path is read from the parsed body with dot notation. Segments are matched literally, so a payload key containing a dot is not addressable. A value that resolves to nothing (missing, null, or not a string/int) throws MissingKeyException; pass required: false to resolve to null instead and let the middleware policy decide.

Configuration

DomainFailureRenderer has no default binding — it is an application concern, and wiring one in your own config/common/di/*.php is what turns domain-failure caching on. FailureClassifier needs wiring only to override DefaultFailureClassifier, which the middleware falls back to on its own.

Public API

Security

• Keys are namespaced by the caller: scopeResolver is a required constructor argument, so a keyspace shared across clients is a deliberate, documented choice (SharedKeyspaceScopeResolver) and never an accident. Without it one client can replay another client's cached response, and the replay path never enters the handler — never reaching its authorization checks
• Set-Cookie, Date and hop-by-hop response headers are never captured, so an identifier carried by one of those headers — a session cookie above all — does not end up in a storage row for the whole TTL and a stale cookie is never replayed. Identifiers in the response body or in your own headers are stored and replayed as-is: name them in additionalExcludedResponseHeaders, which extends the built-in list and cannot switch it off
• A malformed key from an untrusted request answers 400, not 500 — a client cannot generate unhandled exceptions with one header
• Fingerprint includes method, path, query string, and body — prevents payload substitution
• Request body stream is rewound after fingerprinting — handlers can re-read it
• Only 2xx responses returned by the handler are cached; non-2xx (incl. retryable 409/423/429 and any 5xx) release the claim, so a transient failure cannot be replayed for the whole TTL. A rendered domain failure is the one deliberate exception and is cached at whatever status the renderer chose
• Thrown failures are cached only when you configure a DomainFailureRenderer and the classifier calls them Domain. \Error, anything marked RetryableFailure, and anything you override as Bug always release the claim — a transient failure still cannot be pinned for the whole TTL. Classify conservatively: a failure cached as Domain is replayed until the record expires
• Scoping hashes the client key together with the scope, so a scope name is never echoed back and a long key cannot be pushed past the length limit
• Idempotency applies only to the configured methods (default POST/PUT/PATCH) — safe methods pass through
• Atomic claim prevents race conditions (in persistent storage adapters)
• TTL prevents indefinite storage

Examples

See examples/ for runnable scripts.

Development

make test-coverage and make mutation bootstrap pcov inside the composer:2 container because the base image has no coverage driver.

License

BSD-3-Clause. See LICENSE.md.