convex-effect-workflows 0.1.0

package/src/component/cleanup.ts

@@ -0,0 +1,218 @@
+import { v } from "convex/values";
+import { mutation, type MutationCtx } from "./_generated/server.js";
+import type { Doc, Id } from "./_generated/dataModel.js";
+import { DEFAULT_RETENTION_DAYS } from "../shared/constants.js";
+import { scheduleCleanupOldExecutions } from "./boundaries.js";
+
+const TERMINAL_STATUSES = ["completed", "failed", "interrupted"] as const;
+
+function clamp(value: number, min: number, max: number) {
+  return Math.max(min, Math.min(value, max));
+}
+
+function assertPositiveInteger(value: number | undefined, field: string) {
+  if (value === undefined) {
+    return;
+  }
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${field} must be a positive integer`);
+  }
+}
+
+async function resolveRetentionDays(
+  ctx: MutationCtx,
+  requestedRetentionDays: number | undefined,
+): Promise<number> {
+  if (requestedRetentionDays !== undefined) {
+    return requestedRetentionDays;
+  }
+
+  const config = await ctx.db
+    .query("config")
+    .withIndex("by_key", (q) => q.eq("key", "default"))
+    .unique();
+
+  return config?.retentionDays ?? DEFAULT_RETENTION_DAYS;
+}
+
+async function collectOldTerminalExecutions(
+  ctx: MutationCtx,
+  cutoffTimestamp: number,
+  fetchLimit: number,
+): Promise<Array<Doc<"executions">>> {
+  const collected: Array<Doc<"executions">> = [];
+
+  for (const status of TERMINAL_STATUSES) {
+    if (collected.length >= fetchLimit) {
+      break;
+    }
+
+    const remaining = fetchLimit - collected.length;
+    const rows = await ctx.db
+      .query("executions")
+      .withIndex("by_status_started", (q) =>
+        q.eq("status", status).lt("startedAt", cutoffTimestamp),
+      )
+      .take(remaining);
+
+    collected.push(...rows);
+  }
+
+  collected.sort((a, b) => a.startedAt - b.startedAt);
+  return collected;
+}
+
+function collectExecutionPayloadRefs(
+  execution: Doc<"executions">,
+  payloadIds: Set<Id<"payloads">>,
+) {
+  if (execution.payloadRef) {
+    payloadIds.add(execution.payloadRef);
+  }
+  if (execution.resultRef) {
+    payloadIds.add(execution.resultRef);
+  }
+}
+
+function collectJournalPayloadRefs(
+  step: Doc<"journalSteps">,
+  payloadIds: Set<Id<"payloads">>,
+) {
+  if (step.inputRef) {
+    payloadIds.add(step.inputRef);
+  }
+  if (step.runResult && step.runResult.kind !== "canceled" && step.runResult.valueRef) {
+    payloadIds.add(step.runResult.valueRef);
+  }
+}
+
+function collectSpanPayloadRefs(
+  span: Doc<"spans">,
+  payloadIds: Set<Id<"payloads">>,
+) {
+  if (span.inputRef) {
+    payloadIds.add(span.inputRef);
+  }
+  if (span.outputRef) {
+    payloadIds.add(span.outputRef);
+  }
+}
+
+function collectDeferredPayloadRefs(
+  deferred: Doc<"deferreds">,
+  payloadIds: Set<Id<"payloads">>,
+) {
+  if (deferred.exitRef) {
+    payloadIds.add(deferred.exitRef);
+  }
+}
+
+async function deleteExecutionArtifacts(ctx: MutationCtx, execution: Doc<"executions">) {
+  const payloadIds = new Set<Id<"payloads">>();
+  const workIds = new Set<string>();
+
+  collectExecutionPayloadRefs(execution, payloadIds);
+
+  const journalSteps = await ctx.db
+    .query("journalSteps")
+    .withIndex("by_execution_step", (q) => q.eq("executionId", execution.executionId))
+    .collect();
+
+  for (const step of journalSteps) {
+    collectJournalPayloadRefs(step, payloadIds);
+    if (step.workId) {
+      workIds.add(step.workId);
+    }
+    await ctx.db.delete(step._id);
+  }
+
+  for (const workId of workIds) {
+    const completion = await ctx.db
+      .query("activityCompletions")
+      .withIndex("by_work_id", (q) => q.eq("workId", workId))
+      .unique();
+    if (completion) {
+      await ctx.db.delete(completion._id);
+    }
+  }
+
+  const spans = await ctx.db
+    .query("spans")
+    .withIndex("by_execution_start", (q) => q.eq("executionId", execution.executionId))
+    .collect();
+
+  for (const span of spans) {
+    collectSpanPayloadRefs(span, payloadIds);
+    await ctx.db.delete(span._id);
+  }
+
+  const logs = await ctx.db
+    .query("logs")
+    .withIndex("by_execution_time", (q) => q.eq("executionId", execution.executionId))
+    .collect();
+
+  for (const log of logs) {
+    await ctx.db.delete(log._id);
+  }
+
+  const deferreds = await ctx.db
+    .query("deferreds")
+    .withIndex("by_execution_name", (q) => q.eq("executionId", execution.executionId))
+    .collect();
+
+  for (const deferred of deferreds) {
+    collectDeferredPayloadRefs(deferred, payloadIds);
+    await ctx.db.delete(deferred._id);
+  }
+
+  for (const payloadId of payloadIds) {
+    const payload = await ctx.db.get(payloadId);
+    if (payload) {
+      await ctx.db.delete(payload._id);
+    }
+  }
+
+  await ctx.db.delete(execution._id);
+}
+
+/**
+ * Delete old terminal executions and all associated observability/state records.
+ */
+export const cleanupOldExecutions = mutation({
+  args: {
+    retentionDays: v.optional(v.number()),
+    limit: v.optional(v.number()),
+  },
+  returns: v.object({
+    deletedCount: v.number(),
+    hasMore: v.boolean(),
+  }),
+  handler: async (ctx, args) => {
+    assertPositiveInteger(args.retentionDays, "retentionDays");
+    assertPositiveInteger(args.limit, "limit");
+
+    const retentionDays = await resolveRetentionDays(ctx, args.retentionDays);
+    const limit = clamp(args.limit ?? 50, 1, 200);
+    const cutoffTimestamp = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+
+    const fetched = await collectOldTerminalExecutions(ctx, cutoffTimestamp, limit + 1);
+    const targets = fetched.slice(0, limit);
+    const hasMore = fetched.length > limit;
+
+    for (const execution of targets) {
+      await deleteExecutionArtifacts(ctx, execution);
+    }
+
+    if (hasMore) {
+      await scheduleCleanupOldExecutions(ctx.scheduler, {
+        retentionDays,
+        limit,
+      });
+    }
+
+    return {
+      deletedCount: targets.length,
+      hasMore,
+    };
+  },
+});

package/src/component/clocks.ts

@@ -0,0 +1,26 @@
+import { v } from "convex/values";
+import { mutation } from "./_generated/server.js";
+import { scheduleDeferredDone } from "./boundaries.js";
+
+/**
+ * Schedule a durable deferred completion wake-up.
+ *
+ * This models clock scheduling for workflow sleeps.
+ */
+export const scheduleDeferredWake = mutation({
+  args: {
+    executionId: v.string(),
+    deferredName: v.string(),
+    delayMs: v.number(),
+    exit: v.optional(v.any()),
+  },
+  returns: v.id("_scheduled_functions"),
+  handler: async (ctx, args) => {
+    const delayMs = Math.max(0, args.delayMs);
+    return await scheduleDeferredDone(ctx.scheduler, delayMs, {
+      executionId: args.executionId,
+      deferredName: args.deferredName,
+      exit: args.exit ?? null,
+    });
+  },
+});

package/src/component/config.test.ts

@@ -0,0 +1,159 @@
+/// <reference types="vite/client" />
+
+import { describe, expect, test } from "vitest";
+import { api } from "./_generated/api.js";
+import { initConvexTest } from "./setup.test.js";
+import {
+  MAX_INLINE_PAYLOAD_BYTES,
+  MAX_LOG_DATA_BYTES,
+  MAX_SPAN_ATTR_BYTES,
+  DEFAULT_RETENTION_DAYS,
+} from "../shared/constants.js";
+
+describe("config API", () => {
+  test("getConfig returns defaults when unset", async () => {
+    const t = initConvexTest();
+
+    const config = await t.query(api.config.getConfig, {});
+
+    expect(config).toEqual({
+      maxInlineBytes: MAX_INLINE_PAYLOAD_BYTES,
+      maxLogDataBytes: MAX_LOG_DATA_BYTES,
+      maxSpanAttrBytes: MAX_SPAN_ATTR_BYTES,
+      retentionDays: DEFAULT_RETENTION_DAYS,
+      defaultLogLevel: "info",
+    });
+  });
+
+  test("setConfig performs partial updates and merges with defaults", async () => {
+    const t = initConvexTest();
+
+    // Set partial config
+    const result1 = await t.mutation(api.config.setConfig, {
+      retentionDays: 60,
+      defaultLogLevel: "debug",
+    });
+
+    expect(result1).toEqual({
+      maxInlineBytes: MAX_INLINE_PAYLOAD_BYTES,
+      maxLogDataBytes: MAX_LOG_DATA_BYTES,
+      maxSpanAttrBytes: MAX_SPAN_ATTR_BYTES,
+      retentionDays: 60,
+      defaultLogLevel: "debug",
+    });
+
+    // Verify with getConfig
+    const fetched = await t.query(api.config.getConfig, {});
+    expect(fetched).toEqual(result1);
+
+    // Update more fields (should merge, not replace)
+    const result2 = await t.mutation(api.config.setConfig, {
+      maxInlineBytes: 128_000,
+    });
+
+    expect(result2).toEqual({
+      maxInlineBytes: 128_000,
+      maxLogDataBytes: MAX_LOG_DATA_BYTES,
+      maxSpanAttrBytes: MAX_SPAN_ATTR_BYTES,
+      retentionDays: 60,
+      defaultLogLevel: "debug",
+    });
+  });
+
+  test("setConfig rejects invalid numeric values", async () => {
+    const t = initConvexTest();
+
+    // Zero should be rejected
+    await expect(
+      t.mutation(api.config.setConfig, { maxInlineBytes: 0 }),
+    ).rejects.toThrow("maxInlineBytes must be a positive integer");
+
+    // Negative should be rejected
+    await expect(
+      t.mutation(api.config.setConfig, { retentionDays: -5 }),
+    ).rejects.toThrow("retentionDays must be a positive integer");
+
+    // Non-integer should be rejected
+    await expect(
+      t.mutation(api.config.setConfig, { maxLogDataBytes: 12.5 }),
+    ).rejects.toThrow("maxLogDataBytes must be a positive integer");
+
+    // NaN should be rejected
+    await expect(
+      t.mutation(api.config.setConfig, { maxSpanAttrBytes: NaN }),
+    ).rejects.toThrow("maxSpanAttrBytes must be a positive integer");
+  });
+
+  test("setConfig validates all numeric fields independently", async () => {
+    const t = initConvexTest();
+
+    // Multiple invalid fields - should fail on first validation error
+    await expect(
+      t.mutation(api.config.setConfig, {
+        maxInlineBytes: -1,
+        retentionDays: 0,
+      }),
+    ).rejects.toThrow("maxInlineBytes must be a positive integer");
+
+    // After fixing first error, second should be caught
+    await expect(
+      t.mutation(api.config.setConfig, {
+        maxInlineBytes: 1000,
+        retentionDays: 0,
+      }),
+    ).rejects.toThrow("retentionDays must be a positive integer");
+  });
+
+  test("setConfig with valid positive integers succeeds", async () => {
+    const t = initConvexTest();
+
+    const result = await t.mutation(api.config.setConfig, {
+      maxInlineBytes: 1,
+      maxLogDataBytes: 1,
+      maxSpanAttrBytes: 1,
+      retentionDays: 1,
+    });
+
+    expect(result).toEqual({
+      maxInlineBytes: 1,
+      maxLogDataBytes: 1,
+      maxSpanAttrBytes: 1,
+      retentionDays: 1,
+      defaultLogLevel: "info",
+    });
+  });
+
+  test("defaultLogLevel accepts all valid values", async () => {
+    const t = initConvexTest();
+
+    const validLevels: Array<"debug" | "info" | "warn" | "error"> = [
+      "debug",
+      "info",
+      "warn",
+      "error",
+    ];
+
+    for (const level of validLevels) {
+      const result = await t.mutation(api.config.setConfig, {
+        defaultLogLevel: level,
+      });
+      expect(result.defaultLogLevel).toBe(level);
+    }
+  });
+
+  test("setConfig returns resolved config after update", async () => {
+    const t = initConvexTest();
+
+    const initial = await t.mutation(api.config.setConfig, {
+      maxInlineBytes: 500_000,
+      retentionDays: 90,
+    });
+
+    // Verify the returned config includes all fields with correct values
+    expect(initial.maxInlineBytes).toBe(500_000);
+    expect(initial.retentionDays).toBe(90);
+    expect(initial.defaultLogLevel).toBe("info"); // default
+    expect(initial.maxLogDataBytes).toBe(MAX_LOG_DATA_BYTES); // preserved default
+    expect(initial.maxSpanAttrBytes).toBe(MAX_SPAN_ATTR_BYTES); // preserved default
+  });
+});

package/src/component/config.ts

@@ -0,0 +1,145 @@
+import { v } from "convex/values";
+import {
+  mutation,
+  query,
+  type MutationCtx,
+  type QueryCtx,
+} from "./_generated/server.js";
+import {
+  MAX_INLINE_PAYLOAD_BYTES,
+  MAX_LOG_DATA_BYTES,
+  MAX_SPAN_ATTR_BYTES,
+  DEFAULT_RETENTION_DAYS,
+} from "../shared/constants.js";
+import { vLogLevel } from "../shared/validators.js";
+import type { LogLevel } from "../shared/validators.js";
+import type { Doc } from "./_generated/dataModel.js";
+
+type ConfigDoc = Doc<"config">;
+
+type ResolvedConfig = {
+  maxInlineBytes: number;
+  maxLogDataBytes: number;
+  maxSpanAttrBytes: number;
+  retentionDays: number;
+  defaultLogLevel: LogLevel;
+};
+
+const DEFAULT_CONFIG: ResolvedConfig = {
+  maxInlineBytes: MAX_INLINE_PAYLOAD_BYTES,
+  maxLogDataBytes: MAX_LOG_DATA_BYTES,
+  maxSpanAttrBytes: MAX_SPAN_ATTR_BYTES,
+  retentionDays: DEFAULT_RETENTION_DAYS,
+  defaultLogLevel: "info",
+};
+
+function validatePositiveInteger(
+  value: number | undefined | null,
+  fieldName: string,
+): void {
+  if (value !== undefined && value !== null) {
+    if (!Number.isInteger(value) || value <= 0) {
+      throw new Error(`${fieldName} must be a positive integer`);
+    }
+  }
+}
+
+type DbReaderCtx = Pick<QueryCtx, "db"> | Pick<MutationCtx, "db">;
+
+async function getConfigDoc(ctx: DbReaderCtx): Promise<ConfigDoc | null> {
+  return await ctx.db
+    .query("config")
+    .withIndex("by_key", (q) => q.eq("key", "default"))
+    .unique();
+}
+
+function resolveConfig(doc: ConfigDoc | null): ResolvedConfig {
+  if (!doc) {
+    return { ...DEFAULT_CONFIG };
+  }
+  return {
+    maxInlineBytes: doc.maxInlineBytes ?? DEFAULT_CONFIG.maxInlineBytes,
+    maxLogDataBytes: doc.maxLogDataBytes ?? DEFAULT_CONFIG.maxLogDataBytes,
+    maxSpanAttrBytes: doc.maxSpanAttrBytes ?? DEFAULT_CONFIG.maxSpanAttrBytes,
+    retentionDays: doc.retentionDays ?? DEFAULT_CONFIG.retentionDays,
+    defaultLogLevel: doc.defaultLogLevel ?? DEFAULT_CONFIG.defaultLogLevel,
+  };
+}
+
+/**
+ * Get the resolved configuration with defaults applied.
+ */
+export const getConfig = query({
+  args: {},
+  returns: v.object({
+    maxInlineBytes: v.number(),
+    maxLogDataBytes: v.number(),
+    maxSpanAttrBytes: v.number(),
+    retentionDays: v.number(),
+    defaultLogLevel: vLogLevel,
+  }),
+  handler: async (ctx) => {
+    const doc = await getConfigDoc(ctx);
+    return resolveConfig(doc);
+  },
+});
+
+/**
+ * Set configuration via partial update merge/upsert.
+ * All numeric values must be positive integers if provided.
+ */
+export const setConfig = mutation({
+  args: {
+    maxInlineBytes: v.optional(v.number()),
+    maxLogDataBytes: v.optional(v.number()),
+    maxSpanAttrBytes: v.optional(v.number()),
+    retentionDays: v.optional(v.number()),
+    defaultLogLevel: v.optional(vLogLevel),
+  },
+  returns: v.object({
+    maxInlineBytes: v.number(),
+    maxLogDataBytes: v.number(),
+    maxSpanAttrBytes: v.number(),
+    retentionDays: v.number(),
+    defaultLogLevel: vLogLevel,
+  }),
+  handler: async (ctx, args) => {
+    validatePositiveInteger(args.maxInlineBytes, "maxInlineBytes");
+    validatePositiveInteger(args.maxLogDataBytes, "maxLogDataBytes");
+    validatePositiveInteger(args.maxSpanAttrBytes, "maxSpanAttrBytes");
+    validatePositiveInteger(args.retentionDays, "retentionDays");
+
+    const existing = await getConfigDoc(ctx);
+
+    const patch: Partial<ConfigDoc> = {};
+    if (args.maxInlineBytes !== undefined) {
+      patch.maxInlineBytes = args.maxInlineBytes;
+    }
+    if (args.maxLogDataBytes !== undefined) {
+      patch.maxLogDataBytes = args.maxLogDataBytes;
+    }
+    if (args.maxSpanAttrBytes !== undefined) {
+      patch.maxSpanAttrBytes = args.maxSpanAttrBytes;
+    }
+    if (args.retentionDays !== undefined) {
+      patch.retentionDays = args.retentionDays;
+    }
+    if (args.defaultLogLevel !== undefined) {
+      patch.defaultLogLevel = args.defaultLogLevel;
+    }
+
+    if (existing) {
+      if (Object.keys(patch).length > 0) {
+        await ctx.db.patch(existing._id, patch);
+      }
+    } else {
+      await ctx.db.insert("config", {
+        key: "default",
+        ...patch,
+      });
+    }
+
+    const updated = await getConfigDoc(ctx);
+    return resolveConfig(updated);
+  },
+});

package/src/component/convex.config.ts

@@ -0,0 +1,7 @@
+import { defineComponent } from "convex/server";
+import workpool from "@convex-dev/workpool/convex.config";
+
+const component = defineComponent("effectWorkflows");
+component.use(workpool);
+
+export default component;