fix(webapp): make request idempotency work with scoped keys

Request idempotency was doing nothing. The key a client sends is hashed
together with its environment and task scope before it is looked up, but
the idempotency cache still required the raw UUID format and rejected
the hashed value, so every trigger, batch trigger and create-batch
request skipped deduplication. A request the server had already
accepted, whose response the client never received, would therefore
create a second run or batch when the SDK retried it.

The cache now accepts the derived key, so a retried request returns the
original run or batch. The client-supplied
`x-trigger-request-idempotency-key` header is still validated as a v4
UUID, now at the point where it is read; a header of any other shape is
ignored as before, so the request itself still succeeds. Keys stay
scoped to a single environment, task set and request type.

Mono-RevId: 85b6e31f5bdb722d99db28f66a2d5b533a0f3ce4

Author: claude[bot]

.server-changes/fix-request-idempotency-retries.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: fix
+---
+
+Retried trigger and batch trigger requests are deduplicated again: when the SDK automatically retries a request that the server had in fact already accepted, you get the original run or batch back instead of a duplicate one.

apps/webapp/app/routes/api.v1.tasks.$taskId.trigger.ts

@@ -20,7 +20,7 @@ import {
   handleRequestIdempotency,
   saveRequestIdempotency,
 } from "~/utils/requestIdempotency.server";
-import { scopeRequestIdempotencyKey } from "~/utils/requestIdempotencyKey";
+import { scopeRequestIdempotencyHeader } from "~/utils/requestIdempotencyKey";
 import { canWriteParentRun } from "~/utils/parentRunAuthorization.server";
 import { sanitizeTriggerSource } from "~/utils/triggerSource";
 import { runStore } from "~/v3/runStore.server";
@@ -89,7 +89,7 @@ const { action, loader } = createActionApiRoute(
       return json({ error: "Unauthorized" }, { status: 403 });
     }
 
-    const scopedIdempotencyKey = scopeRequestIdempotencyKey(requestIdempotencyKey, [
+    const scopedIdempotencyKey = scopeRequestIdempotencyHeader(requestIdempotencyKey, [
       authentication.environment.id,
       params.taskId,
     ]);

apps/webapp/app/routes/api.v2.tasks.batch.ts

@@ -12,7 +12,7 @@ import {
   handleRequestIdempotency,
   saveRequestIdempotency,
 } from "~/utils/requestIdempotency.server";
-import { scopeRequestIdempotencyKey } from "~/utils/requestIdempotencyKey";
+import { scopeRequestIdempotencyHeader } from "~/utils/requestIdempotencyKey";
 import { canWriteParentRun } from "~/utils/parentRunAuthorization.server";
 import { ServiceValidationError } from "~/v3/services/baseService.server";
 import { BatchProcessingStrategy } from "~/v3/services/batchTriggerV3.server";
@@ -100,7 +100,7 @@ const { action, loader } = createActionApiRoute(
       requestIdempotencyKey,
     });
 
-    const scopedIdempotencyKey = scopeRequestIdempotencyKey(requestIdempotencyKey, [
+    const scopedIdempotencyKey = scopeRequestIdempotencyHeader(requestIdempotencyKey, [
       authentication.environment.id,
       ...Array.from(new Set(body.items.map((item) => item.task))).sort(),
     ]);

apps/webapp/app/services/requestIdempotency.server.ts

@@ -5,19 +5,20 @@ import { createCache, DefaultStatefulContext, Namespace } from "@unkey/cache";
 import { createLRUMemoryStore } from "@internal/cache";
 import { RedisCacheStore } from "./unkey/redisCacheStore.server";
 import type { RedisWithClusterOptions } from "~/redis.server";
-import { validate as uuidValidate, version as uuidVersion } from "uuid";
 import { startActiveSpan } from "~/v3/tracer.server";
 
 export type RequestIdempotencyServiceOptions<TTypes extends string> = {
   types: TTypes[];
-  redis: RedisWithClusterOptions;
+  redis?: RedisWithClusterOptions;
   logger?: Logger;
   logLevel?: LogLevel;
   ttlInMs?: number;
 };
 
 const DEFAULT_TTL_IN_MS = 60_000 * 60 * 24;
 
+const SCOPED_REQUEST_ID_REGEX = /^[0-9a-f]{64}$/;
+
 type RequestIdempotencyCacheEntry = {
   id: string;
 };
@@ -30,24 +31,24 @@ export class RequestIdempotencyService<TTypes extends string> {
     this.logger =
       options.logger ?? new Logger("RequestIdempotencyService", options.logLevel ?? "info");
 
-    const keyPrefix = options.redis.keyPrefix
-      ? `request-idempotency:${options.redis.keyPrefix}`
-      : "request-idempotency:";
-
     const ctx = new DefaultStatefulContext();
     const memory = createLRUMemoryStore(1000);
-    const redisCacheStore = new RedisCacheStore({
-      name: "request-idempotency",
-      connection: {
-        keyPrefix: keyPrefix,
-        ...options.redis,
-      },
-    });
+    const redisCacheStore = options.redis
+      ? new RedisCacheStore({
+          name: "request-idempotency",
+          connection: {
+            keyPrefix: options.redis.keyPrefix
+              ? `request-idempotency:${options.redis.keyPrefix}`
+              : "request-idempotency:",
+            ...options.redis,
+          },
+        })
+      : undefined;
 
     // This cache holds the rate limit configuration for each org, so we don't have to fetch it every request
     const cache = createCache({
       requests: new Namespace<RequestIdempotencyCacheEntry>(ctx, {
-        stores: [memory, redisCacheStore],
+        stores: redisCacheStore ? [memory, redisCacheStore] : [memory],
         fresh: options.ttlInMs ?? DEFAULT_TTL_IN_MS,
         stale: options.ttlInMs ?? DEFAULT_TTL_IN_MS,
       }),
@@ -115,12 +116,8 @@ export class RequestIdempotencyService<TTypes extends string> {
     return result;
   }
 
-  // The requestIdempotencyKey should be a valid UUID
+  // Keys are server-derived by `scopeRequestIdempotencyKey()`, so only the shape needs checking.
   #validateRequestId(requestIdempotencyKey: string): boolean {
-    return isValidV4UUID(requestIdempotencyKey);
+    return SCOPED_REQUEST_ID_REGEX.test(requestIdempotencyKey);
   }
 }
-
-function isValidV4UUID(uuid: string): boolean {
-  return uuidValidate(uuid) && uuidVersion(uuid) === 4;
-}

apps/webapp/app/utils/requestIdempotency.test.ts

@@ -1,5 +1,6 @@
+import { randomUUID } from "node:crypto";
 import { describe, expect, it } from "vitest";
-import { scopeRequestIdempotencyKey } from "./requestIdempotencyKey";
+import { scopeRequestIdempotencyHeader, scopeRequestIdempotencyKey } from "./requestIdempotencyKey";
 
 describe("scopeRequestIdempotencyKey", () => {
   it("keeps retries stable within the same environment and task scope", () => {
@@ -15,8 +16,37 @@ describe("scopeRequestIdempotencyKey", () => {
     expect(scopeRequestIdempotencyKey("request-1", ["env-2", "task-a"])).not.toBe(original);
   });
 
-  it("preserves missing request keys", () => {
+  it("skips missing request keys", () => {
     expect(scopeRequestIdempotencyKey(undefined, ["env-1", "task-a"])).toBeUndefined();
-    expect(scopeRequestIdempotencyKey(null, ["env-1", "task-a"])).toBeNull();
+    expect(scopeRequestIdempotencyKey(null, ["env-1", "task-a"])).toBeUndefined();
+  });
+});
+
+describe("scopeRequestIdempotencyHeader", () => {
+  it("scopes a v4 UUID header", () => {
+    const requestIdempotencyKey = randomUUID();
+
+    expect(scopeRequestIdempotencyHeader(requestIdempotencyKey, ["env-1", "task-a"])).toBe(
+      scopeRequestIdempotencyKey(requestIdempotencyKey, ["env-1", "task-a"])
+    );
+  });
+
+  it("ignores a header that is not a v4 UUID, instead of failing the request", () => {
+    for (const requestIdempotencyKey of [
+      "not-a-uuid",
+      "",
+      "00000000-0000-0000-0000-000000000000",
+      "1b4e28ba-2fa1-11d2-883f-0016d3cca427", // v1
+      `${randomUUID()} `,
+    ]) {
+      expect(
+        scopeRequestIdempotencyHeader(requestIdempotencyKey, ["env-1", "task-a"])
+      ).toBeUndefined();
+    }
+  });
+
+  it("skips missing headers", () => {
+    expect(scopeRequestIdempotencyHeader(undefined, ["env-1", "task-a"])).toBeUndefined();
+    expect(scopeRequestIdempotencyHeader(null, ["env-1", "task-a"])).toBeUndefined();
   });
 });

apps/webapp/app/utils/requestIdempotencyKey.ts

@@ -1,12 +1,26 @@
 import { createHash } from "node:crypto";
+import { validate as uuidValidate, version as uuidVersion } from "uuid";
 
 export function scopeRequestIdempotencyKey(
   requestIdempotencyKey: string | null | undefined,
   scope: readonly string[]
-): string | null | undefined {
-  if (!requestIdempotencyKey) return requestIdempotencyKey;
+): string | undefined {
+  if (!requestIdempotencyKey) return undefined;
 
   return createHash("sha256")
     .update(JSON.stringify([requestIdempotencyKey, ...scope]))
     .digest("hex");
 }
+
+export function scopeRequestIdempotencyHeader(
+  requestIdempotencyKey: string | null | undefined,
+  scope: readonly string[]
+): string | undefined {
+  if (!requestIdempotencyKey || !isValidV4UUID(requestIdempotencyKey)) return undefined;
+
+  return scopeRequestIdempotencyKey(requestIdempotencyKey, scope);
+}
+
+function isValidV4UUID(uuid: string): boolean {
+  return uuidValidate(uuid) && uuidVersion(uuid) === 4;
+}

apps/webapp/test/requestIdempotency.server.test.ts

@@ -0,0 +1,63 @@
+import { randomUUID } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { RequestIdempotencyService } from "~/services/requestIdempotency.server";
+import {
+  scopeRequestIdempotencyHeader,
+  scopeRequestIdempotencyKey,
+} from "~/utils/requestIdempotencyKey";
+
+function createService() {
+  return new RequestIdempotencyService({ types: ["trigger", "batch-trigger"] });
+}
+
+describe("RequestIdempotencyService", () => {
+  it("returns the saved entry for a scoped key", async () => {
+    const service = createService();
+    const scopedKey = scopeRequestIdempotencyHeader(randomUUID(), ["env-1", "task-a"]);
+
+    expect(scopedKey).toBeDefined();
+
+    await service.saveRequest("trigger", scopedKey!, { id: "run_1234" });
+
+    await expect(service.checkRequest("trigger", scopedKey!)).resolves.toEqual({ id: "run_1234" });
+  });
+
+  it("keeps entries isolated by environment, task and request type", async () => {
+    const service = createService();
+    const requestIdempotencyKey = randomUUID();
+    const scopedKey = scopeRequestIdempotencyHeader(requestIdempotencyKey, ["env-1", "task-a"]);
+
+    await service.saveRequest("trigger", scopedKey!, { id: "run_1234" });
+
+    const otherEnvironment = scopeRequestIdempotencyHeader(requestIdempotencyKey, [
+      "env-2",
+      "task-a",
+    ]);
+    const otherTask = scopeRequestIdempotencyHeader(requestIdempotencyKey, ["env-1", "task-b"]);
+
+    await expect(service.checkRequest("trigger", otherEnvironment!)).resolves.toBeUndefined();
+    await expect(service.checkRequest("trigger", otherTask!)).resolves.toBeUndefined();
+    await expect(service.checkRequest("batch-trigger", scopedKey!)).resolves.toBeUndefined();
+  });
+
+  it("accepts a scoped body key, not just a scoped header", async () => {
+    const service = createService();
+    const scopedKey = scopeRequestIdempotencyKey("my-batch-key", ["env-1", "task-a"]);
+
+    await service.saveRequest("batch-trigger", scopedKey!, { id: "batch_1234" });
+
+    await expect(service.checkRequest("batch-trigger", scopedKey!)).resolves.toEqual({
+      id: "batch_1234",
+    });
+  });
+
+  it("ignores a key that was not scoped, instead of throwing", async () => {
+    const service = createService();
+    const unscopedKey = randomUUID();
+
+    await expect(
+      service.saveRequest("trigger", unscopedKey, { id: "run_1234" })
+    ).resolves.toBeUndefined();
+    await expect(service.checkRequest("trigger", unscopedKey)).resolves.toBeUndefined();
+  });
+});

apps/webapp/test/routesBatchGetReplicaLag.guard.test.ts

@@ -114,6 +114,8 @@ import { action as actionCreateBatch } from "~/routes/api.v3.batches";
 // A cuid (25 chars after the `batch_` prefix) classifies LEGACY, so the batch is owned by the legacy
 // (control-plane) store; the client-less reads then land on the LEGACY leg.
 const CUID_25 = "c".repeat(25);
+// Must be a v4 UUID or the route ignores the header.
+const REQUEST_IDEMPOTENCY_KEY = "b3f1e9c2-5d7a-4a1b-9c8e-2f6d4a7b1c30";
 
 let seq = 0;
 
@@ -339,7 +341,7 @@ describe("routes-batch-get callers under a lagging replica", () => {
             "content-type": "application/json",
             "content-length": String(Buffer.byteLength(body)),
             authorization: `Bearer ${seed.environment.apiKey}`,
-            "x-trigger-request-idempotency-key": "req_idem_tb",
+            "x-trigger-request-idempotency-key": REQUEST_IDEMPOTENCY_KEY,
           },
           body,
         }),