@trigger.dev/convex 0.0.1 → 4.8.2

package/src/component/runs.ts

@@ -0,0 +1,227 @@
+import {
+  paginationOptsValidator,
+  type FunctionHandle,
+  type GenericMutationCtx,
+} from "convex/server";
+import { v } from "convex/values";
+import { internal } from "./api.js";
+import { internalMutation, internalQuery, mutation, query, type DataModel } from "./server.js";
+import {
+  MAX_INLINE_BYTES,
+  MAX_PAGE_BYTES,
+  SUBMISSION_WINDOW_MS,
+  vConfig,
+  vRun,
+  vTriggerOptions,
+  type Run,
+} from "./shared.js";
+
+type RunDoc = DataModel["runs"]["document"];
+
+export function toRun(run: RunDoc): Run {
+  const { _id, _creationTime, generation, checks, failures, callback, ...fields } = run;
+  return { id: _id, createdAt: _creationTime, ...fields };
+}
+
+export const trigger = mutation({
+  args: {
+    taskId: v.string(),
+    payload: v.optional(v.any()),
+    options: vTriggerOptions,
+    config: vConfig,
+    idempotencyKey: v.optional(v.string()),
+    callback: v.optional(v.string()),
+  },
+  returns: v.string(),
+  handler: async (ctx, args): Promise<string> => {
+    if (!args.taskId.trim()) throw new Error("taskId is required");
+    if (
+      new TextEncoder().encode(JSON.stringify({ payload: args.payload, options: args.options }))
+        .byteLength > MAX_INLINE_BYTES
+    ) {
+      throw new Error(
+        "Payload and options must fit within 256 KiB; pass a storage reference for larger inputs"
+      );
+    }
+    if (args.idempotencyKey !== undefined) {
+      const existing = await ctx.db
+        .query("runs")
+        .withIndex("by_key", (q) => q.eq("idempotencyKey", args.idempotencyKey))
+        .unique();
+      if (existing) return existing._id;
+    }
+    const id = await ctx.db.insert("runs", {
+      taskId: args.taskId,
+      idempotencyKey: args.idempotencyKey,
+      status: "PENDING",
+      syncStatus: "pending",
+      updatedAt: Date.now(),
+      generation: 0,
+      checks: 0,
+      failures: 0,
+      callback: args.callback,
+    });
+    await ctx.db.insert("requests", {
+      run: id,
+      payload: args.payload,
+      options: args.options,
+      config: args.config,
+    });
+    await ctx.scheduler.runAfter(0, internal.worker.tick, { id, generation: 0 });
+    return id;
+  },
+});
+
+export const get = query({
+  args: { id: v.string() },
+  returns: v.union(vRun, v.null()),
+  handler: async (ctx, { id }): Promise<Run | null> => {
+    const runId = ctx.db.normalizeId("runs", id);
+    const run = runId ? await ctx.db.get("runs", runId) : null;
+    return run ? toRun(run) : null;
+  },
+});
+
+export const list = query({
+  args: { paginationOpts: paginationOptsValidator },
+  returns: v.object({ page: v.array(vRun), isDone: v.boolean(), continueCursor: v.string() }),
+  handler: async (
+    ctx,
+    { paginationOpts }
+  ): Promise<{ page: Run[]; isDone: boolean; continueCursor: string }> => {
+    if (paginationOpts.numItems < 1 || paginationOpts.numItems > 100) {
+      throw new Error("Request between 1 and 100 runs per page");
+    }
+    const result = await ctx.db
+      .query("runs")
+      .order("desc")
+      .paginate({
+        ...paginationOpts,
+        maximumBytesRead: Math.min(
+          paginationOpts.maximumBytesRead ?? MAX_PAGE_BYTES,
+          MAX_PAGE_BYTES
+        ),
+      });
+    return {
+      page: result.page.map(toRun),
+      isDone: result.isDone,
+      continueCursor: result.continueCursor,
+    };
+  },
+});
+
+export const resume = mutation({
+  args: { id: v.string(), config: vConfig },
+  returns: v.null(),
+  handler: async (ctx, { id, config }): Promise<null> => {
+    const runId = ctx.db.normalizeId("runs", id);
+    const run = runId ? await ctx.db.get("runs", runId) : null;
+    if (!run) throw new Error("Run not found");
+    if (run.syncStatus !== "paused") return null;
+    if (!run.runId && Date.now() - run._creationTime >= SUBMISSION_WINDOW_MS) {
+      throw new Error(
+        "Submission retry window expired; reconcile the run in Trigger before triggering again"
+      );
+    }
+    const request = await ctx.db
+      .query("requests")
+      .withIndex("by_run", (q) => q.eq("run", run._id))
+      .unique();
+    if (!request) throw new Error("Run request not found");
+    await ctx.db.patch("requests", request._id, { config });
+    const generation = run.generation + 1;
+    await ctx.db.patch("runs", run._id, {
+      syncStatus: run.runId ? "active" : "pending",
+      syncError: undefined,
+      failures: 0,
+      checks: 0,
+      generation,
+      updatedAt: Date.now(),
+    });
+    await ctx.scheduler.runAfter(0, internal.worker.tick, { id: run._id, generation });
+    return null;
+  },
+});
+
+export const load = internalQuery({
+  args: { id: v.id("runs") },
+  handler: async (ctx, { id }) => {
+    const run = await ctx.db.get("runs", id);
+    const request = await ctx.db
+      .query("requests")
+      .withIndex("by_run", (q) => q.eq("run", id))
+      .unique();
+    return run && request ? { run, request } : null;
+  },
+});
+
+export const recordSubmission = internalMutation({
+  args: { id: v.id("runs"), generation: v.number(), runId: v.string() },
+  returns: v.null(),
+  handler: async (ctx, args): Promise<null> => {
+    const run = await ctx.db.get("runs", args.id);
+    if (!run || run.generation !== args.generation || run.syncStatus === "complete") return null;
+    await ctx.db.patch("runs", args.id, {
+      runId: args.runId,
+      status: "QUEUED",
+      syncStatus: "active",
+      syncError: undefined,
+      failures: 0,
+      checks: 0,
+      updatedAt: Date.now(),
+    });
+    return null;
+  },
+});
+
+export const recordStatus = internalMutation({
+  args: {
+    id: v.id("runs"),
+    generation: v.number(),
+    status: v.string(),
+    completed: v.boolean(),
+    output: v.optional(v.any()),
+    outputPresignedUrl: v.optional(v.string()),
+    outputOmitted: v.optional(v.boolean()),
+    error: v.optional(v.any()),
+    metadata: v.optional(v.any()),
+  },
+  returns: v.null(),
+  handler: async (ctx, { id, generation, completed, ...result }): Promise<null> => {
+    const run = await ctx.db.get("runs", id);
+    if (!run || run.generation !== generation || run.syncStatus === "complete") return null;
+    const updates = {
+      ...result,
+      syncStatus: completed ? ("complete" as const) : ("active" as const),
+      syncError: undefined,
+      failures: 0,
+      updatedAt: Date.now(),
+    };
+    await ctx.db.patch("runs", id, updates);
+    if (completed) {
+      if (run.callback) {
+        await ctx.runMutation(run.callback as FunctionHandle<"mutation", { run: Run }>, {
+          run: toRun({ ...run, ...updates }),
+        });
+      }
+      const request = await ctx.db
+        .query("requests")
+        .withIndex("by_run", (q) => q.eq("run", id))
+        .unique();
+      if (request) await ctx.db.delete("requests", request._id);
+    }
+    return null;
+  },
+});
+
+export async function pause(
+  ctx: GenericMutationCtx<DataModel>,
+  run: RunDoc,
+  message: string
+): Promise<void> {
+  await ctx.db.patch("runs", run._id, {
+    syncStatus: "paused",
+    syncError: message,
+    updatedAt: Date.now(),
+  });
+}

package/src/component/schema.ts

@@ -0,0 +1,19 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+import { runFields, vConfig, vTriggerOptions } from "./shared.js";
+
+export default defineSchema({
+  runs: defineTable({
+    ...runFields,
+    generation: v.number(),
+    checks: v.number(),
+    failures: v.number(),
+    callback: v.optional(v.string()),
+  }).index("by_key", ["idempotencyKey"]),
+  requests: defineTable({
+    run: v.id("runs"),
+    payload: v.optional(v.any()),
+    options: vTriggerOptions,
+    config: vConfig,
+  }).index("by_run", ["run"]),
+});

package/src/component/server.ts

@@ -0,0 +1,19 @@
+import {
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+  mutationGeneric,
+  queryGeneric,
+  type ActionBuilder,
+  type MutationBuilder,
+  type QueryBuilder,
+  type DataModelFromSchemaDefinition,
+} from "convex/server";
+import type schema from "./schema.js";
+
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
+export const internalMutation: MutationBuilder<DataModel, "internal"> = internalMutationGeneric;
+export const internalQuery: QueryBuilder<DataModel, "internal"> = internalQueryGeneric;
+export const internalAction: ActionBuilder<DataModel, "internal"> = internalActionGeneric;

package/src/component/shared.ts

@@ -0,0 +1,61 @@
+import { v, type Infer } from "convex/values";
+
+export const vTriggerOptions = v.object({
+  tags: v.optional(v.array(v.string())),
+  delay: v.optional(v.string()),
+  queue: v.optional(v.object({ name: v.string() })),
+  concurrencyKey: v.optional(v.string()),
+  machine: v.optional(v.string()),
+  metadata: v.optional(v.any()),
+  maxAttempts: v.optional(v.number()),
+  maxDuration: v.optional(v.number()),
+  ttl: v.optional(v.string()),
+});
+
+export const vConfig = v.object({
+  secretKey: v.string(),
+  baseUrl: v.string(),
+});
+
+export const runFields = {
+  taskId: v.string(),
+  runId: v.optional(v.string()),
+  idempotencyKey: v.optional(v.string()),
+  status: v.string(),
+  syncStatus: v.union(
+    v.literal("pending"),
+    v.literal("active"),
+    v.literal("paused"),
+    v.literal("complete")
+  ),
+  output: v.optional(v.any()),
+  outputPresignedUrl: v.optional(v.string()),
+  outputOmitted: v.optional(v.boolean()),
+  error: v.optional(v.any()),
+  metadata: v.optional(v.any()),
+  syncError: v.optional(v.string()),
+  updatedAt: v.number(),
+};
+export const vRun = v.object({
+  id: v.string(),
+  createdAt: v.number(),
+  ...runFields,
+});
+
+export type Run = Infer<typeof vRun>;
+export type TriggerOptions = Infer<typeof vTriggerOptions>;
+export type Config = Infer<typeof vConfig>;
+
+const FIRST_POLL_MS = 15_000;
+const MAX_POLL_MS = 60_000;
+export const REQUEST_TIMEOUT_MS = 10_000;
+export const WATCHDOG_MARGIN_MS = 5_000;
+export const MAX_SYNC_FAILURES = 8;
+export const SUBMISSION_WINDOW_MS = 60 * 60 * 1_000;
+export const IDEMPOTENCY_TTL = "24h";
+export const MAX_INLINE_BYTES = 256 * 1_024;
+export const MAX_PAGE_BYTES = 4 * 1_024 * 1_024;
+
+export function pollDelay(checks: number): number {
+  return Math.min(FIRST_POLL_MS * 2 ** Math.min(checks, 4), MAX_POLL_MS);
+}

package/src/component/worker.ts

@@ -0,0 +1,131 @@
+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 }): Promise<null> => {
+    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 }): Promise<null> => {
+    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 }): Promise<null> => {
+    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;
+  },
+});