disallow empty filter

Author: carderne

apps/webapp/test/bulk-actions-api.e2e.full.test.ts

@@ -159,22 +159,41 @@ describe("Bulk actions API", () => {
     const response = await server.webapp.fetch("/api/v1/bulk-actions", {
       method: "POST",
       headers: authHeaders(apiKey),
-      body: JSON.stringify({ action: "cancel", filter: {}, runIds: ["run_123"] }),
+      body: JSON.stringify({ action: "cancel", filter: { status: "FAILED" }, runIds: ["run_123"] }),
     });
 
     expect(response.status).toBe(400);
     const body = await response.json();
     expect(body.error).toContain("Exactly one of filter or runIds must be provided");
   });
 
+  it("rejects create requests with an empty filter", async () => {
+    const server = getTestServer();
+    const { apiKey } = await seedTestEnvironment(server.prisma);
+
+    const response = await server.webapp.fetch("/api/v1/bulk-actions", {
+      method: "POST",
+      headers: authHeaders(apiKey),
+      body: JSON.stringify({ action: "cancel", filter: {} }),
+    });
+
+    expect(response.status).toBe(400);
+    const body = await response.json();
+    expect(body.error).toContain("At least one filter must be provided");
+  });
+
   it("returns a generic error for unexpected create failures", async () => {
     const server = getTestServer();
     const { apiKey } = await seedTestEnvironment(server.prisma);
 
     const response = await server.webapp.fetch("/api/v1/bulk-actions", {
       method: "POST",
       headers: authHeaders(apiKey),
-      body: JSON.stringify({ action: "cancel", filter: {}, name: "No ClickHouse in this suite" }),
+      body: JSON.stringify({
+        action: "cancel",
+        filter: { status: "FAILED" },
+        name: "No ClickHouse in this suite",
+      }),
     });
 
     expect(response.status).toBe(500);

docs/management/runs/bulk-actions.mdx

@@ -28,7 +28,7 @@ const completed = await runs.bulk.poll(action.id);
 console.log(completed.status, completed.counts);
 ```
 
-`filter` accepts the same filters as [`runs.list()`](/management/runs/list), excluding pagination fields. Relative time filters such as `period` are resolved when the bulk action is created, so later batches process the same fixed time range.
+`filter` accepts the same filters as [`runs.list()`](/management/runs/list), excluding pagination fields. Provide at least one filter field; use `runIds` when you want to target specific runs. Relative time filters such as `period` are resolved when the bulk action is created, so later batches process the same fixed time range.
 
 <ParamField body="filter" type="BulkActionFilter">
   Selects runs using the same filter shape as `runs.list()`, excluding `limit`, `after`, and `before`.

packages/core/src/v3/apiClient/types.ts

@@ -70,8 +70,13 @@ export interface ListProjectRunsQueryParams extends CursorPageParams, ListRunsQu
   env?: Array<"dev" | "staging" | "prod"> | "dev" | "staging" | "prod";
 }
 
+type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = T &
+  {
+    [K in Keys]-?: Required<Pick<T, K>>;
+  }[Keys];
+
 /** Same filters as runs.list(), excluding pagination. */
-export type BulkActionFilter = Omit<ListRunsQueryParams, keyof CursorPageParams>;
+export type BulkActionFilter = RequireAtLeastOne<Omit<ListRunsQueryParams, keyof CursorPageParams>>;
 
 export type BulkActionSelection =
   | { filter: BulkActionFilter; runIds?: never }

packages/core/src/v3/schemas/api.ts

@@ -1229,22 +1229,43 @@ const MachineOrMachineArray = z.union([MachinePresetName, z.array(MachinePresetN
 const QueueOrQueueArray = z.union([QueueTypeName, z.array(QueueTypeName)]);
 const DateOrNumber = z.union([z.coerce.date(), z.number()]);
 
-const BulkActionFilterRequestBody = z.object({
-  status: z.union([RunStatus, z.array(RunStatus)]).optional(),
-  taskIdentifier: StringOrStringArray.optional(),
-  version: StringOrStringArray.optional(),
-  from: DateOrNumber.optional(),
-  to: DateOrNumber.optional(),
-  period: z.string().optional(),
-  bulkAction: z.string().optional(),
-  tag: StringOrStringArray.optional(),
-  schedule: z.string().optional(),
-  isTest: z.boolean().optional(),
-  batch: z.string().optional(),
-  queue: QueueOrQueueArray.optional(),
-  machine: MachineOrMachineArray.optional(),
-  region: StringOrStringArray.optional(),
-});
+const BulkActionFilterRequestBody = z
+  .object({
+    status: z.union([RunStatus, z.array(RunStatus)]).optional(),
+    taskIdentifier: StringOrStringArray.optional(),
+    version: StringOrStringArray.optional(),
+    from: DateOrNumber.optional(),
+    to: DateOrNumber.optional(),
+    period: z.string().optional(),
+    bulkAction: z.string().optional(),
+    tag: StringOrStringArray.optional(),
+    schedule: z.string().optional(),
+    isTest: z.boolean().optional(),
+    batch: z.string().optional(),
+    queue: QueueOrQueueArray.optional(),
+    machine: MachineOrMachineArray.optional(),
+    region: StringOrStringArray.optional(),
+  })
+  .refine((filter) => Object.values(filter).some(isNonEmptyBulkActionFilterValue), {
+    message: "At least one filter must be provided",
+  });
+
+/** Recursively checks for at least one non-undefined, non-empty value. */
+function isNonEmptyBulkActionFilterValue(value: unknown): boolean {
+  if (value === undefined) {
+    return false;
+  }
+
+  if (Array.isArray(value)) {
+    return value.some(isNonEmptyBulkActionFilterValue);
+  }
+
+  if (typeof value === "string") {
+    return value.trim().length > 0;
+  }
+
+  return true;
+}
 
 const BulkActionSelectionRequestBody = {
   filter: BulkActionFilterRequestBody.optional(),