@trigger.dev/convex 0.0.1 → 4.8.2

package/dist/component/worker.js

@@ -0,0 +1,105 @@
+import { v } from "convex/values";
+import { internal } from "./api.js";
+import { internalAction, internalMutation } from "./server.js";
+import { pause } from "./runs.js";
+import { ApiError, inlineValue, request } from "./apiClient.js";
+import { IDEMPOTENCY_TTL, MAX_SYNC_FAILURES, REQUEST_TIMEOUT_MS, SUBMISSION_WINDOW_MS, WATCHDOG_MARGIN_MS, pollDelay, } from "./shared.js";
+const jobArgs = { id: v.id("runs"), generation: v.number() };
+export const tick = internalMutation({
+    args: jobArgs,
+    returns: v.null(),
+    handler: async (ctx, { id, generation }) => {
+        const run = await ctx.db.get("runs", id);
+        if (!run ||
+            run.generation !== generation ||
+            run.syncStatus === "complete" ||
+            run.syncStatus === "paused")
+            return null;
+        if (!run.runId && Date.now() - run._creationTime >= SUBMISSION_WINDOW_MS) {
+            await pause(ctx, run, "Submission retry window expired; check Trigger before triggering again");
+            return null;
+        }
+        const nextGeneration = generation + 1;
+        await ctx.db.patch("runs", id, { generation: nextGeneration, checks: run.checks + 1 });
+        // Schedule the watchdog transactionally before starting an action that can be interrupted.
+        await ctx.scheduler.runAfter(Math.max(pollDelay(run.checks), REQUEST_TIMEOUT_MS + WATCHDOG_MARGIN_MS), internal.worker.tick, { id, generation: nextGeneration });
+        await ctx.scheduler.runAfter(0, internal.worker.step, { id, generation: nextGeneration });
+        return null;
+    },
+});
+export const step = internalAction({
+    args: jobArgs,
+    returns: v.null(),
+    handler: async (ctx, { id, generation }) => {
+        const loaded = await ctx.runQuery(internal.runs.load, { id });
+        if (!loaded ||
+            loaded.run.generation !== generation ||
+            loaded.run.syncStatus === "complete" ||
+            loaded.run.syncStatus === "paused")
+            return null;
+        const { run, request: saved } = loaded;
+        try {
+            if (!run.runId) {
+                const result = await request(saved.config, `/api/v1/tasks/${encodeURIComponent(run.taskId)}/trigger`, {
+                    payload: saved.payload,
+                    options: {
+                        ...saved.options,
+                        idempotencyKey: `convex:${id}`,
+                        idempotencyKeyTTL: IDEMPOTENCY_TTL,
+                    },
+                });
+                if (typeof result.id !== "string")
+                    throw new ApiError("Missing run ID in Trigger.dev response", true);
+                await ctx.runMutation(internal.runs.recordSubmission, { id, generation, runId: result.id });
+            }
+            else {
+                const result = await request(saved.config, `/api/v3/runs/${encodeURIComponent(run.runId)}`);
+                if (typeof result.status !== "string" || typeof result.isCompleted !== "boolean") {
+                    throw new ApiError("Missing run status in Trigger.dev response", true);
+                }
+                const output = inlineValue(result.output);
+                await ctx.runMutation(internal.runs.recordStatus, {
+                    id,
+                    generation,
+                    status: result.status,
+                    completed: result.isCompleted || result.status === "EXPIRED" || result.status === "TIMED_OUT",
+                    output: output.value,
+                    outputOmitted: output.omitted,
+                    outputPresignedUrl: typeof result.outputPresignedUrl === "string" ? result.outputPresignedUrl : undefined,
+                    error: inlineValue(result.error).value,
+                    metadata: inlineValue(result.metadata).value,
+                });
+            }
+        }
+        catch (error) {
+            await ctx.runMutation(internal.worker.recordError, {
+                id,
+                generation,
+                message: error instanceof ApiError
+                    ? error.message
+                    : "Run synchronization failed; inspect Convex function logs",
+                permanent: error instanceof ApiError && !error.retryable,
+            });
+            // Preserve diagnostic detail in server logs without including the request config.
+            console.error("Trigger.dev synchronization failed", {
+                id,
+                error: error instanceof Error ? error.name : "UnknownError",
+            });
+        }
+        return null;
+    },
+});
+export const recordError = internalMutation({
+    args: { ...jobArgs, message: v.string(), permanent: v.boolean() },
+    returns: v.null(),
+    handler: async (ctx, { id, generation, message, permanent }) => {
+        const run = await ctx.db.get("runs", id);
+        if (!run || run.generation !== generation || run.syncStatus === "complete")
+            return null;
+        const failures = run.failures + 1;
+        await ctx.db.patch("runs", id, { failures, syncError: message, updatedAt: Date.now() });
+        if (permanent || failures >= MAX_SYNC_FAILURES)
+            await pause(ctx, run, message);
+        return null;
+    },
+});

package/package.json

@@ -1,16 +1,49 @@
 {
   "name": "@trigger.dev/convex",
-  "version": "0.0.1",
+  "version": "4.8.2",
   "description": "Run Trigger.dev tasks from Convex mutations and query their results reactively",
   "license": "Apache-2.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/triggerdotdev/trigger.dev",
     "directory": "packages/convex"
   },
-  "homepage": "https://trigger.dev",
-  "publishConfig": {
-    "access": "public"
+  "files": [
+    "dist",
+    "src/component",
+    "!src/component/**/*.test.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./convex.config.js": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "convex": "^1.48.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "convex": "^1.48.0",
+    "convex-test": "^0.0.65",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
   },
-  "files": ["README.md"]
-}
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/component/_generated/component.ts

@@ -0,0 +1,18 @@
+import type { ApiFromModules, FilterApi, FunctionReference } from "convex/server";
+import type * as runs from "../runs.js";
+
+type PublicApi = FilterApi<ApiFromModules<{ runs: typeof runs }>, FunctionReference<any, "public">>;
+
+// Derive the component boundary from its functions, so it cannot drift from their validators.
+export type ComponentApi<Name extends string | undefined = string | undefined> = {
+  runs: {
+    [Key in keyof PublicApi["runs"]]: PublicApi["runs"][Key] extends FunctionReference<
+      infer Type,
+      any,
+      infer Args,
+      infer Result
+    >
+      ? FunctionReference<Type, "internal", Args, Result, Name>
+      : never;
+  };
+};

package/src/component/api.ts

@@ -0,0 +1,6 @@
+import { anyApi, type ApiFromModules, type FilterApi, type FunctionReference } from "convex/server";
+import type * as runs from "./runs.js";
+import type * as worker from "./worker.js";
+
+type Api = ApiFromModules<{ runs: typeof runs; worker: typeof worker }>;
+export const internal = anyApi as unknown as FilterApi<Api, FunctionReference<any, "internal">>;

package/src/component/apiClient.ts

@@ -0,0 +1,57 @@
+import { MAX_INLINE_BYTES, REQUEST_TIMEOUT_MS, type Config } from "./shared.js";
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public retryable: boolean
+  ) {
+    super(message);
+  }
+}
+
+export async function request(
+  config: Config,
+  path: string,
+  body?: unknown
+): Promise<Record<string, unknown>> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const response = await fetch(config.baseUrl + path, {
+      method: body === undefined ? "GET" : "POST",
+      headers: { Authorization: `Bearer ${config.secretKey}`, "Content-Type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: controller.signal,
+      redirect: "error",
+    });
+    if (!response.ok) {
+      await response.body?.cancel();
+      const retryHeader = response.headers.get("x-should-retry");
+      // Never persist response bodies, which could contain credentials or payloads.
+      throw new ApiError(
+        `Trigger.dev API returned HTTP ${response.status}`,
+        retryHeader === "true" ||
+          (retryHeader !== "false" &&
+            (response.status === 408 ||
+              response.status === 409 ||
+              response.status === 429 ||
+              response.status >= 500))
+      );
+    }
+    const data: unknown = await response.json();
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+      throw new ApiError("Invalid Trigger.dev response", true);
+    }
+    return data as Record<string, unknown>;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function inlineValue(value: unknown): { value?: any; omitted: boolean } {
+  if (value === undefined) return { omitted: false };
+  if (new TextEncoder().encode(JSON.stringify(value)).byteLength > MAX_INLINE_BYTES) {
+    return { omitted: true };
+  }
+  return { value, omitted: false };
+}

package/src/component/convex.config.ts

@@ -0,0 +1,3 @@
+import { defineComponent } from "convex/server";
+
+export default defineComponent("trigger");

package/src/component/runs.test.ts

@@ -0,0 +1,354 @@
+import { createServer, type Server } from "node:http";
+import { once } from "node:events";
+import { afterAll, afterEach, beforeAll, beforeEach, expect, test, vi } from "vitest";
+import { defineTestApp, type ComponentRegistration } from "convex-test";
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+import { Trigger, vRun, type ComponentApi } from "../client/index.js";
+import schema from "./schema.js";
+import { MAX_INLINE_BYTES } from "./shared.js";
+
+const modules = {
+  "./_generated/component.ts": () => import("./_generated/component.js"),
+  "./runs.ts": () => import("./runs.js"),
+  "./worker.ts": () => import("./worker.js"),
+};
+const app = defineTestApp({
+  schema: defineSchema({
+    completions: defineTable({ run: vRun }),
+    controls: defineTable({ failCallback: v.boolean() }),
+  }),
+  components: {
+    trigger: {
+      register: ((t, name) =>
+        t.registerComponent(name, schema, modules)) as ComponentRegistration<ComponentApi>,
+    },
+  },
+});
+let baseUrl: string;
+const { createTest, api, internal } = app.defineModules({
+  callbacks: {
+    complete: app.internalMutation({
+      args: { run: vRun },
+      handler: async (ctx, args) => {
+        if ((await ctx.db.query("controls").first())?.failCallback)
+          throw new Error("Callback unavailable");
+        await ctx.db.insert("completions", args);
+      },
+    }),
+  },
+  jobs: {
+    request: app.mutation({
+      args: {
+        rollback: v.optional(v.boolean()),
+        key: v.optional(v.string()),
+        payload: v.optional(v.any()),
+      },
+      handler: async (ctx, args): Promise<string> => {
+        const trigger = new Trigger(app.components.trigger, {
+          secretKey: "test-only-key",
+          baseUrl,
+          onComplete: internal.callbacks.complete,
+        });
+        const id = await trigger.trigger(
+          ctx,
+          "render-video",
+          args.payload ?? { videoId: "video-1" },
+          {
+            idempotencyKey: args.key,
+            tags: ["video:1"],
+          }
+        );
+        if (args.rollback) throw new Error("Roll back the application transaction");
+        return id;
+      },
+    }),
+  },
+});
+
+async function drain(t: ReturnType<typeof createTest>): Promise<void> {
+  for (let i = 0; i < 100; i++) {
+    vi.advanceTimersToNextTimer();
+    await t.finishInProgressScheduledFunctions();
+    const { page } = await t.query(app.components.trigger.runs.list, {
+      paginationOpts: { numItems: 10, cursor: null },
+    });
+    if (page.every((run) => run.syncStatus === "complete" || run.syncStatus === "paused")) return;
+  }
+  throw new Error("Runs did not settle");
+}
+
+let server: Server;
+let submissions: number;
+let polls: number;
+let remoteRuns: Map<string, string>;
+let loseFirstResponse: boolean;
+let triggerStatus: number;
+let pollFailures: number;
+let pollFailureStatus: number;
+let pollRetryHeader: string | undefined;
+let activePolls: number;
+let remoteStatus: string;
+let remoteIsCompleted: boolean;
+let largeOutput: boolean;
+let submittedOptions: Record<string, unknown>;
+
+beforeAll(async () => {
+  server = createServer(async (req, res) => {
+    res.setHeader("Content-Type", "application/json");
+    if (req.headers.authorization !== "Bearer test-only-key") {
+      res.writeHead(401).end("{}");
+      return;
+    }
+    if (req.method === "POST") {
+      submissions++;
+      let body = "";
+      for await (const chunk of req) body += chunk;
+      const data = JSON.parse(body);
+      submittedOptions = data.options;
+      if (triggerStatus !== 200) {
+        res.writeHead(triggerStatus).end("{}");
+        return;
+      }
+      const key: string = data.options.idempotencyKey;
+      if (!remoteRuns.has(key)) remoteRuns.set(key, `run_${remoteRuns.size + 1}`);
+      if (loseFirstResponse && submissions === 1) {
+        res.destroy();
+        return;
+      }
+      res.end(JSON.stringify({ id: remoteRuns.get(key) }));
+    } else {
+      polls++;
+      if (pollFailures-- > 0) {
+        if (pollRetryHeader !== undefined) res.setHeader("x-should-retry", pollRetryHeader);
+        res.writeHead(pollFailureStatus).end("{}");
+        return;
+      }
+      const completed = activePolls-- <= 0;
+      res.end(
+        JSON.stringify({
+          id: "run_1",
+          status: completed ? remoteStatus : "EXECUTING",
+          isCompleted: completed && remoteIsCompleted,
+          output: completed
+            ? largeOutput
+              ? "x".repeat(MAX_INLINE_BYTES + 1)
+              : { url: "https://example.com/video.mp4" }
+            : undefined,
+          metadata: { progress: completed ? 100 : 50 },
+        })
+      );
+    }
+  });
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Expected TCP server");
+  baseUrl = `http://127.0.0.1:${address.port}`;
+});
+
+beforeEach(() => {
+  vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "Date"] });
+  submissions = 0;
+  polls = 0;
+  remoteRuns = new Map();
+  loseFirstResponse = false;
+  triggerStatus = 200;
+  pollFailures = 0;
+  pollFailureStatus = 503;
+  pollRetryHeader = undefined;
+  activePolls = 0;
+  remoteStatus = "COMPLETED";
+  remoteIsCompleted = true;
+  largeOutput = false;
+  submittedOptions = {};
+});
+afterEach(() => vi.useRealTimers());
+afterAll(
+  () =>
+    new Promise<void>((resolve, reject) => {
+      server.close((error) => (error ? reject(error) : resolve()));
+      server.closeAllConnections();
+    })
+);
+
+test("rolling back the application mutation never submits work", async () => {
+  const t = createTest();
+  await expect(t.mutation(api.jobs.request, { rollback: true })).rejects.toThrow("Roll back");
+  await drain(t);
+  expect(submissions).toBe(0);
+  expect(
+    await t.query(app.components.trigger.runs.list, {
+      paginationOpts: { numItems: 10, cursor: null },
+    })
+  ).toMatchObject({ page: [] });
+});
+
+test("deduplicates requests, stores reactive results, and calls the app once without exposing credentials", async () => {
+  const t = createTest();
+  const id = await t.mutation(api.jobs.request, { key: "render:1" });
+  expect(await t.mutation(api.jobs.request, { key: "render:1" })).toBe(id);
+  await drain(t);
+  await drain(t);
+  const run = await t.query(app.components.trigger.runs.get, { id });
+  expect(run).toMatchObject({
+    runId: "run_1",
+    status: "COMPLETED",
+    syncStatus: "complete",
+    output: { url: "https://example.com/video.mp4" },
+    metadata: { progress: 100 },
+  });
+  expect(JSON.stringify(run)).not.toContain("test-only-key");
+  expect(
+    JSON.stringify(
+      await t.query(app.components.trigger.runs.list, {
+        paginationOpts: { numItems: 10, cursor: null },
+      })
+    )
+  ).not.toContain("test-only-key");
+  expect(submissions).toBe(1);
+  expect(submittedOptions).toMatchObject({ tags: ["video:1"], idempotencyKeyTTL: "24h" });
+  expect(await t.run((ctx) => ctx.db.query("completions").collect())).toHaveLength(1);
+});
+
+test("retries an ambiguous submission using the same remote idempotency key", async () => {
+  loseFirstResponse = true;
+  const t = createTest();
+  const id = await t.mutation(api.jobs.request, {});
+  await drain(t);
+  expect(submissions).toBe(2);
+  expect(remoteRuns.size).toBe(1);
+  expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+    syncStatus: "complete",
+  });
+});
+
+test("recovers from temporary polling failures and observes cancellation without task hooks", async () => {
+  pollFailures = 2;
+  remoteStatus = "CANCELED";
+  const t = createTest();
+  const id = await t.mutation(api.jobs.request, {});
+  await drain(t);
+  expect(polls).toBe(3);
+  expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+    status: "CANCELED",
+    syncStatus: "complete",
+  });
+});
+
+test.each(["EXPIRED", "TIMED_OUT"])(
+  "finishes %s runs even when isCompleted is false",
+  async (status) => {
+    remoteStatus = status;
+    remoteIsCompleted = false;
+    const t = createTest();
+    const id = await t.mutation(api.jobs.request, {});
+    await drain(t);
+    await drain(t);
+    expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+      status,
+      syncStatus: "complete",
+    });
+    expect(polls).toBe(1);
+    const completions = await t.run((ctx) => ctx.db.query("completions").collect());
+    expect(completions).toHaveLength(1);
+    expect(completions[0]?.run.status).toBe(status);
+  }
+);
+
+test.each([
+  { status: 404, header: "true", syncStatus: "complete", expectedPolls: 2 },
+  { status: 404, header: undefined, syncStatus: "paused", expectedPolls: 1 },
+  { status: 503, header: "false", syncStatus: "paused", expectedPolls: 1 },
+])(
+  "honors retry policy for HTTP $status with x-should-retry=$header",
+  async ({ status, header, syncStatus, expectedPolls }) => {
+    pollFailures = 1;
+    pollFailureStatus = status;
+    pollRetryHeader = header;
+    const t = createTest();
+    const id = await t.mutation(api.jobs.request, {});
+    await drain(t);
+    expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({ syncStatus });
+    expect(polls).toBe(expectedPolls);
+  }
+);
+
+test("pauses a rejected submission and can resume it inside the retry window", async () => {
+  triggerStatus = 401;
+  const t = createTest();
+  const id = await t.mutation(api.jobs.request, {});
+  await drain(t);
+  expect(submissions).toBe(1);
+  expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+    syncStatus: "paused",
+  });
+  triggerStatus = 200;
+  await t.mutation(app.components.trigger.runs.resume, {
+    id,
+    config: { baseUrl, secretKey: "test-only-key" },
+  });
+  await drain(t);
+  expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+    syncStatus: "complete",
+  });
+});
+
+test("keeps completion usable when the remote output exceeds the document budget", async () => {
+  largeOutput = true;
+  const t = createTest();
+  const id = await t.mutation(api.jobs.request, {});
+  await drain(t);
+  expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+    syncStatus: "complete",
+    outputOmitted: true,
+  });
+});
+
+test("tracks active work without invoking completion early", async () => {
+  activePolls = 1;
+  const t = createTest();
+  const id = await t.mutation(api.jobs.request, {});
+  for (let i = 0; i < 20 && polls === 0; i++) {
+    vi.advanceTimersToNextTimer();
+    await t.finishInProgressScheduledFunctions();
+  }
+  expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+    status: "EXECUTING",
+    syncStatus: "active",
+    metadata: { progress: 50 },
+  });
+  expect(await t.run((ctx) => ctx.db.query("completions").collect())).toHaveLength(0);
+  await drain(t);
+  expect(await t.run((ctx) => ctx.db.query("completions").collect())).toHaveLength(1);
+});
+
+test("a failing callback rolls back completion and can be retried without duplicate application writes", async () => {
+  const t = createTest();
+  const controlId = await t.run((ctx) => ctx.db.insert("controls", { failCallback: true }));
+  const id = await t.mutation(api.jobs.request, {});
+  await drain(t);
+  expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+    syncStatus: "paused",
+  });
+  expect(await t.run((ctx) => ctx.db.query("completions").collect())).toHaveLength(0);
+  await t.run((ctx) => ctx.db.patch(controlId, { failCallback: false }));
+  await t.mutation(app.components.trigger.runs.resume, {
+    id,
+    config: { secretKey: "test-only-key", baseUrl },
+  });
+  await drain(t);
+  expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+    syncStatus: "complete",
+  });
+  expect(await t.run((ctx) => ctx.db.query("completions").collect())).toHaveLength(1);
+});
+
+test("rejects large inputs before scheduling remote work", async () => {
+  const t = createTest();
+  await expect(
+    t.mutation(api.jobs.request, { payload: "x".repeat(MAX_INLINE_BYTES + 1) })
+  ).rejects.toThrow("256 KiB");
+  await drain(t);
+  expect(submissions).toBe(0);
+});