feat(idempotency): add idempotency package

.github/CODEOWNERS

@@ -34,6 +34,7 @@
 /packages/http/                                      @brendt @aidan-casey
 /packages/http-client/                               @aidan-casey
 /packages/icon/                                      @innocenzi
+/packages/idempotency/                               @xHeaven
 /packages/kv-store/                                  @innocenzi
 /packages/log/                                       @brendt
 /packages/mail/                                      @innocenzi

composer.json

@@ -110,6 +110,7 @@
         "tempest/http": "self.version",
         "tempest/http-client": "self.version",
         "tempest/icon": "self.version",
+        "tempest/idempotency": "self.version",
         "tempest/intl": "self.version",
         "tempest/kv-store": "self.version",
         "tempest/log": "self.version",
@@ -151,6 +152,7 @@
             "Tempest\\HttpClient\\": "packages/http-client/src",
             "Tempest\\Http\\": "packages/http/src",
             "Tempest\\Icon\\": "packages/icon/src",
+            "Tempest\\Idempotency\\": "packages/idempotency/src",
             "Tempest\\Intl\\": "packages/intl/src",
             "Tempest\\KeyValue\\": "packages/kv-store/src",
             "Tempest\\Log\\": "packages/log/src",
@@ -220,6 +222,7 @@
             "Tempest\\HttpClient\\Tests\\": "packages/http-client/tests",
             "Tempest\\Http\\Tests\\": "packages/http/tests",
             "Tempest\\Icon\\Tests\\": "packages/icon/tests",
+            "Tempest\\Idempotency\\Tests\\": "packages/idempotency/tests",
             "Tempest\\Intl\\Tests\\": "packages/intl/tests",
             "Tempest\\KeyValue\\Tests\\": "packages/kv-store/tests",
             "Tempest\\Log\\Tests\\": "packages/log/tests",

docs/1-essentials/01-routing.md

@@ -678,6 +678,39 @@ final readonly class Auth implements RouteDecorator
 }
 ```
 
+## Idempotent routes
+
+For operations like payment processing or order creation, retrying the same request should not produce duplicate side effects. Tempest provides the {b`Tempest\Idempotency\Attributes\Idempotent`} route decorator to handle this. Clients send an `Idempotency-Key` header; the first request executes normally and caches the response, while subsequent requests with the same key replay the cached response.
+
+```php app/OrderController.php
+use Tempest\Router\Post;
+use Tempest\Http\Response;
+use Tempest\Http\GenericResponse;
+use Tempest\Http\Status;
+use Tempest\Idempotency\Attributes\Idempotent;
+
+final readonly class OrderController
+{
+    #[Post('/orders')]
+    #[Idempotent]
+    public function create(CreateOrderRequest $request): Response
+    {
+        $order = $this->orderService->create($request);
+
+        return new GenericResponse(
+            status: Status::CREATED,
+            body: ['id' => $order->id],
+        );
+    }
+}
+```
+
+Idempotency is only supported for `POST` and `PATCH` routes. The attribute can be applied at the class level to make all routes in a controller idempotent, and accepts optional parameters for per-route TTL and key requirement overrides.
+
+:::info
+Read the full [idempotency documentation](../2-features/19-idempotency.md) for details on scope resolvers, configuration, response behavior, and command bus idempotency.
+:::
+
 ## Responses
 
 All requests to a controller action expect a response to be returned to the client. This is done by returning a {b`Tempest\View\View`} or a {b`Tempest\Http\Response`} object.

docs/2-features/10-command-bus.md

@@ -115,6 +115,54 @@ In order to _run_ an asynchronous command, you'll have to run the `tempest comma
 
 Note that async command handling is still an early feature, and will receive many improvements over time.
 
+## Idempotent commands
+
+Commands that should not be processed more than once—such as payment processing or invoice imports—can be marked with {b`Tempest\Idempotency\Attributes\IdempotentCommand`}. Duplicate dispatches with the same payload are silently skipped.
+
+```php
+// app/ImportInvoicesCommand.php
+
+use Tempest\Idempotency\Attributes\IdempotentCommand;
+
+#[IdempotentCommand]
+final readonly class ImportInvoicesCommand
+{
+    public function __construct(
+        public string $vendorId,
+        public string $month,
+    ) {}
+}
+```
+
+By default, the deduplication key is derived from the command's properties. Two commands with identical property values are considered duplicates. For explicit control over the key, implement the {b`Tempest\Idempotency\Contracts\HasIdempotencyKey`} interface:
+
+```php
+// app/ProcessPaymentCommand.php
+
+use Tempest\Idempotency\Attributes\IdempotentCommand;
+use Tempest\Idempotency\Contracts\HasIdempotencyKey;
+
+#[IdempotentCommand]
+final readonly class ProcessPaymentCommand implements HasIdempotencyKey
+{
+    public function __construct(
+        public string $paymentId,
+        public int $amount,
+    ) {}
+
+    public function getIdempotencyKey(): string
+    {
+        return $this->paymentId;
+    }
+}
+```
+
+When using explicit keys, the payload fingerprint is still verified. Dispatching the same key with a different payload throws {b`Tempest\Idempotency\Exceptions\IdempotencyKeyWasAlreadyUsed`}.
+
+:::info
+Read the full [idempotency documentation](./19-idempotency.md) for details on configuration, TTL overrides, custom stores, and HTTP route idempotency.
+:::
+
 ## Command bus middleware
 
 Whenever commands are dispatched, they are passed to the command bus, which will pass the command along to each of its handlers. Similar to web requests and console commands, this command bus supports middleware. Command bus middleware can be used to, for example, do logging for specific commands, add metadata to commands, or anything else. Command bus middleware are classes that implement the `CommandBusMiddleware` interface, and look like this:

docs/2-features/19-idempotency.md

@@ -0,0 +1,272 @@
+---
+title: Idempotency
+description: "Prevent duplicate side effects for HTTP routes and command bus commands by storing and replaying the result of the first execution."
+---
+
+## Overview
+
+Payment processing, order creation, resource provisioning - any operation where retrying the same request should not produce duplicate side effects. Timeouts, client retries, and accidental double clicks all cause the same problem: the server cannot distinguish a retry from a new request.
+
+The `tempest/idempotency` package solves this by storing the result of the first execution and replaying it for subsequent requests with the same idempotency key. It supports both [HTTP routes](#idempotent-routes) and [command bus commands](#idempotent-commands).
+
+## Idempotent routes
+
+Add the {b`Tempest\Idempotency\Attributes\Idempotent`} attribute to a controller method. Clients send an `Idempotency-Key` header with a unique value (typically a UUID). The first request executes normally and caches the response. Subsequent requests with the same key replay the cached response without re-executing the handler.
+
+```php app/OrderController.php
+use Tempest\Router\Post;
+use Tempest\Http\Response;
+use Tempest\Http\GenericResponse;
+use Tempest\Http\Status;
+use Tempest\Idempotency\Attributes\Idempotent;
+
+final readonly class OrderController
+{
+    #[Post('/orders')]
+    #[Idempotent]
+    public function create(CreateOrderRequest $request): Response
+    {
+        $order = $this->orderService->create($request);
+
+        return new GenericResponse(
+            status: Status::CREATED,
+            body: ['id' => $order->id],
+        );
+    }
+}
+```
+
+The client must include the idempotency key as a header:
+
+```
+POST /orders HTTP/1.1
+Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
+Content-Type: application/json
+
+{"product": "widget", "quantity": 3}
+```
+
+When a cached response is replayed, the response includes an `idempotency-replayed: true` header so the client can distinguish replays from original executions.
+
+### Supported methods
+
+Idempotency is only supported for `POST` and `PATCH` routes. Applying `#[Idempotent]` to a `GET`, `PUT`, `DELETE`, or other method will throw an {b`Tempest\Idempotency\Exceptions\IdempotencyMethodWasNotSupported`} exception. `GET` is inherently idempotent, `PUT` and `DELETE` are idempotent by definition in HTTP semantics, and only `POST` and `PATCH` produce non-idempotent side effects.
+
+### Scope resolver
+
+Idempotency keys must be scoped per user or client to prevent key collisions across different actors. This is done by implementing the {b`Tempest\Idempotency\Contracts\IdempotencyScopeResolver`} interface and registering it in the container.
+
+The `resolve()` method receives the current request and must return a string that uniquely identifies the caller - such as a user ID, session ID, or API key:
+
+```php app/UserIdempotencyScopeResolver.php
+use Tempest\Http\Request;
+use Tempest\Idempotency\Contracts\IdempotencyScopeResolver;
+
+final readonly class UserIdempotencyScopeResolver implements IdempotencyScopeResolver
+{
+    public function __construct(
+        private AuthManager $auth,
+    ) {}
+
+    public function resolve(Request $request): string
+    {
+        return (string) $this->auth->currentUser()->id;
+    }
+}
+```
+
+:::warning
+A scope resolver is required. If no implementation of {b`Tempest\Idempotency\Contracts\IdempotencyScopeResolver`} is registered in the container, the middleware will fail at construction time.
+:::
+
+### Per-route overrides
+
+The `#[Idempotent]` attribute accepts optional parameters to override the global configuration on a per-route basis:
+
+```php app/PaymentController.php
+use Tempest\Router\Post;
+use Tempest\Http\Response;
+use Tempest\Idempotency\Attributes\Idempotent;
+
+final readonly class PaymentController
+{
+    #[Post('/payments')]
+    #[Idempotent(ttlInSeconds: 172_800, requireKey: true)]
+    public function charge(ChargeRequest $request): Response
+    {
+        // Cached response persists for 48 hours instead of the default 24
+    }
+}
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `ttlInSeconds` | `?int` | How long a completed response is cached. Defaults to the config value (86400 / 24 hours). |
+| `pendingTtlInSeconds` | `?int` | How long a pending (in-progress) record is considered active. Defaults to the config value (60 seconds). |
+| `requireKey` | `?bool` | Whether requests without the idempotency key header should be rejected with a 400 response. Defaults to `true`. |
+| `header` | `?string` | The header name to read the idempotency key from. Defaults to `Idempotency-Key`. |
+
+When `requireKey` is set to `false`, requests without the header bypass idempotency protection entirely and execute normally.
+
+### Class-level application
+
+The `#[Idempotent]` attribute can be applied at the class level to make all routes in a controller idempotent:
+
+```php app/ApiOrderController.php
+use Tempest\Router\Post;
+use Tempest\Router\Patch;
+use Tempest\Http\Response;
+use Tempest\Idempotency\Attributes\Idempotent;
+
+#[Idempotent]
+final readonly class ApiOrderController
+{
+    #[Post('/api/orders')]
+    public function create(CreateOrderRequest $request): Response { /* … */ }
+
+    #[Patch('/api/orders/{id}')]
+    public function update(int $id, UpdateOrderRequest $request): Response { /* … */ }
+}
+```
+
+### Response behavior
+
+The middleware produces different responses depending on the state of the idempotency key:
+
+| Scenario | Status | Description |
+|---|---|---|
+| No existing record |  -  | The request executes normally and the response is cached. |
+| Completed record, same payload | Original status | The cached response is replayed with an `idempotency-replayed: true` header. |
+| Completed record, different payload | 422 | The key was already used with a different request body. |
+| Pending record (in progress) | 409 | Another request with the same key is currently being processed. A `retry-after: 1` header is included. |
+| Missing key (when required) | 400 | The `Idempotency-Key` header was not provided. |
+
+### How it works
+
+The `#[Idempotent]` attribute is a [route decorator](../1-essentials/01-routing.md#route-decorators) that adds {b`Tempest\Idempotency\Middleware\IdempotencyMiddleware`} to the route's middleware stack. The middleware:
+
+1. Reads the idempotency key from the request header.
+2. Computes a fingerprint of the request (method, URI, body, and query parameters).
+3. Acquires a cache lock to prevent concurrent processing of the same key.
+4. Checks for an existing record in the idempotency store.
+5. If no record exists, saves a pending record, executes the handler, and stores the completed response.
+6. If the handler throws an exception, the pending record is deleted so the request can be retried.
+
+A heartbeat mechanism keeps pending records alive during long-running requests, preventing other processes from incorrectly taking over an operation that is still in progress.
+
+## Idempotent commands
+
+Mark a command class with {b`Tempest\Idempotency\Attributes\IdempotentCommand`} to prevent duplicate dispatches. When the same command is dispatched more than once, the duplicate is silently skipped.
+
+```php app/ImportInvoicesCommand.php
+use Tempest\Idempotency\Attributes\IdempotentCommand;
+
+#[IdempotentCommand]
+final readonly class ImportInvoicesCommand
+{
+    public function __construct(
+        public string $vendorId,
+        public string $month,
+    ) {}
+}
+```
+
+The handler is defined as usual with `#[CommandHandler]`:
+
+```php app/ImportInvoicesHandler.php
+use Tempest\CommandBus\CommandHandler;
+
+final class ImportInvoicesHandler
+{
+    #[CommandHandler]
+    public function handleImportInvoices(ImportInvoicesCommand $command): void
+    {
+        // Only executes once per unique command payload.
+        // Duplicate dispatches are silently skipped.
+    }
+}
+```
+
+By default, the idempotency key is derived from a fingerprint of the command's properties. Two commands with identical property values produce the same fingerprint and are considered duplicates.
+
+### Explicit idempotency keys
+
+Commands can provide an explicit key by implementing the {b`Tempest\Idempotency\Contracts\HasIdempotencyKey`} interface. This is useful when the deduplication key should be a specific business identifier rather than the full payload:
+
+```php app/ProcessPaymentCommand.php
+use Tempest\Idempotency\Attributes\IdempotentCommand;
+use Tempest\Idempotency\Contracts\HasIdempotencyKey;
+
+#[IdempotentCommand]
+final readonly class ProcessPaymentCommand implements HasIdempotencyKey
+{
+    public function __construct(
+        public string $paymentId,
+        public int $amount,
+    ) {}
+
+    public function getIdempotencyKey(): string
+    {
+        return $this->paymentId;
+    }
+}
+```
+
+When using explicit keys, the fingerprint of the command payload is still verified. If the same key is dispatched with a different payload, an {b`Tempest\Idempotency\Exceptions\IdempotencyKeyWasAlreadyUsed`} exception is thrown.
+
+### Per-command TTL overrides
+
+The `#[IdempotentCommand]` attribute accepts optional TTL parameters:
+
+```php
+#[IdempotentCommand(ttlInSeconds: 3600, pendingTtlInSeconds: 30)]
+final readonly class ProcessPaymentCommand { /* … */ }
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `ttlInSeconds` | `?int` | How long the completed record is cached. Defaults to the config value (86400 / 24 hours). |
+| `pendingTtlInSeconds` | `?int` | How long a pending record is considered active. Defaults to the config value (60 seconds). |
+
+## Configuration
+
+The idempotency package is configured by creating an `idempotency.config.php` file. All settings have sensible defaults:
+
+```php app/idempotency.config.php
+use Tempest\Idempotency\Config\IdempotencyConfig;
+
+return new IdempotencyConfig(
+    header: 'Idempotency-Key',
+    requireKey: true,
+    ttlInSeconds: 86_400,
+    pendingTtlInSeconds: 60,
+    cachePrefix: 'idempotency',
+);
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `header` | `Idempotency-Key` | The HTTP header name to read the idempotency key from. |
+| `requireKey` | `true` | Whether to reject requests that do not include the idempotency key header. |
+| `ttlInSeconds` | `86400` (24h) | How long a completed response is cached. |
+| `pendingTtlInSeconds` | `60` | How long a pending record is considered active before it can be taken over. |
+| `cachePrefix` | `idempotency` | Prefix for cache keys in the idempotency store. |
+| `storeClass` | `CacheIdempotencyStore` | The {b`Tempest\Idempotency\Store\IdempotencyStore`} implementation to use. |
+
+### Custom stores
+
+The default store uses Tempest's [cache](./06-cache.md) component. A custom store can be created by implementing the {b`Tempest\Idempotency\Store\IdempotencyStore`} interface and setting the `storeClass` in the configuration:
+
+```php app/idempotency.config.php
+use Tempest\Idempotency\Config\IdempotencyConfig;
+use App\RedisIdempotencyStore;
+
+return new IdempotencyConfig(
+    storeClass: RedisIdempotencyStore::class,
+);
+```
+
+## Limitations
+
+- **Windows is not supported.** The heartbeat mechanism relies on `pcntl_alarm` and `pcntl_signal`, which are not available on Windows. Attempting to use idempotency on Windows will throw an {b`Tempest\Idempotency\Exceptions\IdempotencyPlatformWasNotSupported`} exception.
+- **Stored responses must be serializable.** Response bodies are stored using PHP serialization or JSON encoding. Non-serializable bodies (such as generators or views) are stored as type name strings and will not reproduce the original output on replay.