feat(PAB-21): Idempotency-Key on chat completions + request_dedup table

[pablopunk]

Summary

This PR implements idempotency support for the chat completions API endpoint, allowing clients to safely retry requests without risk of duplicate processing or billing.

Key Changes

Idempotency-Key Header Support:

• The /api/v1/chat/completions endpoint now reads an Idempotency-Key header from incoming requests and passes it through to the proxy pipeline.

Request Deduplication Table:

• A new request_dedup table stores deduplication state per user and idempotency key, with a unique index on (user_id, idempotency_key). It tracks request status (in_flight, completed, failed), cached response data, headers, and timestamps.

Deduplication Logic (handleDedup):

• First request with a key: Inserts a new in_flight row and proceeds normally with the upstream call.
• Duplicate while in-flight (non-stale): Returns a 409 Conflict with idempotency_conflict error, indicating the request is already being processed.
• Stale in-flight row (>5 minutes old): Reclaims the row (resets to in_flight) and proceeds with the request.
• Completed non-streaming response: Replays the cached response (status, body, headers) with the same deterministic request ID, so the client receives an identical result.
• Completed streaming response: Returns 409 since streaming responses cannot be replayed.
• Failed previous attempt: Reclaims the row and retries the request.

Deterministic Request IDs:

• When dedup is enabled, the request ID is derived from a SHA-256 hash of user_id:idempotency_key, ensuring replayed responses carry the same x-request-id.

Post-Response Persistence:

• After a non-streaming upstream response completes, the dedup row is updated to completed with the response JSON, headers, and upstream status.
• For streaming responses, the row is marked completed but no response body is stored (replay not supported).

Kill Switch:

• The entire dedup feature can be disabled via the idempotency_dedup backend kill switch.

Testing:

• Unit tests cover all dedup states (new, in-flight, stale, completed non-streaming, completed streaming, failed).
• A smoke test script (smoke-idempotency.sh) sends two identical requests with the same Idempotency-Key and asserts both return 200 with the same x-request-id.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nvm	Ready	Preview, Comment	Jul 12, 2026 12:39pm

[kody-ai]

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

• Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	❌
Security	✅
Business Logic	❌

Access your configuration settings here.

​

[kody-ai]

Race condition in backend/src/lib/proxy.ts:212-223 allows two stale retries to reclaim the same requestDedup row because the UPDATE only filters on id, so both requests can pass Date.now() - createdAt > DEDUP_STALE_MS, call the upstream, and recordUsage. Guard the reclaim with status = 'in_flight' and fail the second winner with a 409 idempotency_conflict to preserve the dedup guarantee.

if (Date.now() - createdAt > DEDUP_STALE_MS) {
  const [reclaimed] = await db.update(requestDedup).set({
    status: 'in_flight',
    requestId,
    createdAt: new Date(),
    requestHash: null, responseJson: null, responseHeaders: null, upstreamStatus: null, completedAt: null,
  }).where(and(
    eq(requestDedup.id, existing.id),
    eq(requestDedup.status, 'in_flight'),
  )).returning({ id: requestDedup.id });
  if (!reclaimed) return withRequestId(Response.json({ error: { type: 'idempotency_conflict', message: 'Request already in progress' } }, { status: 409 }), requestId);
  return undefined;
}

Prompt for LLM

File backend/src/lib/proxy.ts:

Line 210 to 224:

Race condition in backend/src/lib/proxy.ts:212-223 allows two stale retries to reclaim the same `requestDedup` row because the `UPDATE` only filters on `id`, so both requests can pass `Date.now() - createdAt > DEDUP_STALE_MS`, call the upstream, and recordUsage. Guard the reclaim with `status = 'in_flight'` and fail the second winner with a 409 `idempotency_conflict` to preserve the dedup guarantee.

Suggested Code:

    if (Date.now() - createdAt > DEDUP_STALE_MS) {
      const [reclaimed] = await db.update(requestDedup).set({
        status: 'in_flight',
        requestId,
        createdAt: new Date(),
        requestHash: null, responseJson: null, responseHeaders: null, upstreamStatus: null, completedAt: null,
      }).where(and(
        eq(requestDedup.id, existing.id),
        eq(requestDedup.status, 'in_flight'),
      )).returning({ id: requestDedup.id });
      if (!reclaimed) return withRequestId(Response.json({ error: { type: 'idempotency_conflict', message: 'Request already in progress' } }, { status: 409 }), requestId);
      return undefined;
    }

_{Talk to Kody by mentioning @kody}

_{Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.}

​

​