feat(idempotency): add idempotency package

[xHeaven]

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

[github-actions]

Benchmark Results

Comparison of idempotency against 3.x (092791b48782454545faf396cb9433b8afb22c8e).

Open to see the benchmark results

Benchmark	Set	Mem. Peak	Time	Variability
ViewRenderBench(benchExpressions)	-	23.903mb +0.00%	519.755μs +5.06%	±1.25% -56.92%

_{Generated by phpbench against commit 2caea11}

[aidan-casey]

Pretty slick, man!

[xHeaven]

Should be fine for review, can't seem to add/change much.

[brendt]

Don't forget about adding the docs :) My suggestion would be to have a section both in the routing and command bus docs

Also: would there be any impact if we worked on FrankenPHP worker mode? Somethings we already need to account for?

[xHeaven]

@brendt

Don't forget about adding the docs :) My suggestion would be to have a section both in the routing and command bus docs

Definitely, just wanted to gather some feedback first and iterate with things, to make sure there is no stale documentation anywhere when things get into their final form.

Also: would there be any impact if we worked on FrankenPHP worker mode? Somethings we already need to account for?

Yes, we'd potentially have to revisit HeartbeatRenewer due to pcntl_signal and pcntl_alarm usage. Not sure how I'd handle this in worker mode just yet.