Overview

This PR adds idempotency support for HTTP routes and command bus commands. It prevents duplicate side effects by storing the result of the first execution and replaying it for subsequent requests with the same idempotency key.

Payment processing, order creation, resource provisioning and any operation where retrying the same request should not produce duplicate side effects. Timeouts, retries by clients, and accidental double clicks all cause the same problem: the server can't distinguish a retry from a new request.

Routes

Add #[Idempotent] to a controller method. Clients send an Idempotency-Key header. The first request executes normally and caches the response. Subsequent requests with the same key replay the cached response.

Example:

use Tempest\Idempotency\Attributes\Idempotent;
final readonly class OrderController
{
 #[Post('/orders')]
 #[Idempotent]
 public function create(CreateOrderRequest $request): Response
 {
 // Only executes once per idempotency key.
 // Retries replay the original response.
 $order = $this->orderService->create($request);
 return new GenericResponse(
 status: Status::CREATED,
 body: ['id' => $order->id],
 );
 }
}

Commands

Mark a command with #[IdempotentCommand]. Duplicate dispatches with the same payload are silently skipped.

Example:

use Tempest\Idempotency\Attributes\IdempotentCommand;
#[IdempotentCommand]
final readonly class ImportInvoicesCommand
{
 public function __construct(
 public string $vendorId,
 public string $month,
 ) {}
}

Commands can also provide explicit keys via HasIdempotencyKey.

Example:

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;
 }
}

Known limitations at the opening of PR

• (削除) No differentiation between in-progress/same key, different payload cases (削除ここまで)
• (削除) Scoping is weak, we need an additional component (user-provided resolver) (削除ここまで)
• (削除) Heartbeat renewal is not implemented yet (削除ここまで)
• (削除) We need to target only POST and PATCH methods, disallow others (削除ここまで)
• Possibly other things I didn't think of

Wonftixes (design decision)

• Stored responses must be JsonSerializable (more of a design decision than an issue)
• Windows incompatibility due to posix and pcntl usage