Chronos Billing Engine: building a usage-based billing API that never double-charges

final class EventController
{
    public function __construct(
        private readonly MessageBusInterface $messageBus,
        private readonly RateLimiterFactory $eventIngestionLimiter,
        private readonly LoggerInterface $logger,
    ) {
    }

    #[Route('/api/v1/events', name: 'events_ingest', methods: ['POST'])]
    public function __invoke(Request $request): JsonResponse
    {
        $limiter = $this->eventIngestionLimiter->create($request->getClientIp() ?? 'unknown');
        if (!$limiter->consume(1)->isAccepted()) {
            return new JsonResponse(['error' => 'Too many requests.'], 429);
        }

        $payload = json_decode($request->getContent(), true, 512, JSON_THROW_ON_ERROR);
        $clientId = (string) ($payload['client_id'] ?? '');
        $endpoint = (string) ($payload['endpoint'] ?? '');

        $idempotencyKey = $request->headers->has('Idempotency-Key')
            ? $request->headers->get('Idempotency-Key')
            : IdempotencyKey::fromPayload($clientId, $endpoint, $request->getContent())->value();

        $this->messageBus->dispatch(new LogEventMessage($clientId, $endpoint, (string) $idempotencyKey));

        return new JsonResponse(status: 202); // Accepted : traité de façon asynchrone
    }
}

final readonly class IdempotencyKey
{
    private string $value;

    public function __construct(string $value)
    {
        $trimmed = trim($value);

        if ($trimmed === '' || strlen($trimmed) > 128) {
            throw new \InvalidArgumentException('Idempotency key must be between 1 and 128 characters.');
        }

        $this->value = $trimmed;
    }

    public static function fromPayload(string $clientId, string $endpoint, string $rawBody): self
    {
        return new self(hash('sha256', $clientId . '|' . $endpoint . '|' . $rawBody));
    }

    public function value(): string
    {
        return $this->value;
    }
}

final readonly class LogClientEventUseCase
{
    public function __construct(
        private EventRepositoryInterface $eventRepository,
        private IdempotencyGuardInterface $idempotencyGuard,
        private ?LoggerInterface $logger = null,
    ) {
    }

    public function execute(LogEventCommand $command): void
    {
        $idempotencyKey = new IdempotencyKey($command->idempotencyKey);

        if ($this->idempotencyGuard->hasBeenProcessed($idempotencyKey)) {
            throw new DuplicateEventException(
                sprintf('Event with idempotency key "%s" was already processed.', $idempotencyKey->value())
            );
        }

        $event = new Event(/* ... */);

        $this->eventRepository->save($event);
        $this->idempotencyGuard->markAsProcessed($idempotencyKey);
    }
}

final class ApiKeyAuthenticator extends AbstractAuthenticator
{
    public function __construct(
        private readonly string $expectedApiKeyHash,
    ) {
    }

    public function authenticate(Request $request): Passport
    {
        $providedKey = (string) $request->headers->get('X-Api-Key', '');

        if ($providedKey === '' || !hash_equals($this->expectedApiKeyHash, hash('sha256', $providedKey))) {
            throw new AuthenticationException('Invalid or missing API key.');
        }

        return new SelfValidatingPassport(
            new UserBadge('api-client', fn () => new InMemoryUser('api-client', null, ['ROLE_API_CLIENT']))
        );
    }
}

framework:
    rate_limiter:
        event_ingestion:
            policy: 'sliding_window'
            limit: 200
            interval: '60 seconds'

final class BillingCalculatorTest extends TestCase
{
    private BillingCalculator $calculator;

    protected function setUp(): void
    {
        $this->calculator = new BillingCalculator();
    }

    public function test_it_returns_zero_price_below_free_tier_threshold(): void
    {
        $invoice = $this->buildInvoiceWithEvents(500);

        $price = $this->calculator->calculate($invoice);

        self::assertSame(0, $price->amountInCents());
    }

    public function test_it_bills_only_events_exceeding_free_tier(): void
    {
        $invoice = $this->buildInvoiceWithEvents(1200);

        $price = $this->calculator->calculate($invoice);

        self::assertSame(200 * 2, $price->amountInCents()); // 200 événements facturables x 2 centimes
    }
}

// (extrait résumé) LogClientEventUseCaseTest
public function test_it_rejects_a_duplicate_event_without_persisting_it_twice(): void
{
    $guard = $this->createMock(IdempotencyGuardInterface::class);
    $guard->method('hasBeenProcessed')->willReturn(true);

    $repository = $this->createMock(EventRepositoryInterface::class);
    $repository->expects(self::never())->method('save');

    $this->expectException(DuplicateEventException::class);

    // ... exécution du use case avec une clé déjà traitée
}

final class BillingCalculator
{
    private const PRICE_PER_EVENT_CENTS = 2; // 0,02 € par événement ingéré
    private const FREE_TIER_THRESHOLD = 1000;

    public function calculate(Invoice $invoice): Price
    {
        $billableEvents = max(0, $invoice->totalEvents() - self::FREE_TIER_THRESHOLD);

        return Price::fromCents($billableEvents * self::PRICE_PER_EVENT_CENTS);
    }
}