convex-effect-workflows 0.1.0

package/src/client/ConvexTracer.ts

@@ -0,0 +1,75 @@
+import * as Context from "effect/Context";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Tracer from "effect/Tracer";
+import type { GenericDataModel, GenericMutationCtx } from "convex/server";
+import type { ComponentApi } from "../component/_generated/component.js";
+
+type MutationRunCtx = Pick<GenericMutationCtx<GenericDataModel>, "runMutation">;
+
+export function makeConvexTracer(
+  component: ComponentApi,
+  ctx: MutationRunCtx,
+  executionId: string,
+  traceId: string,
+): Tracer.Tracer {
+  return Tracer.make({
+    span: (name, parent, _context, _links, _startTime, kind, options) => {
+      const parentSpanId = Option.match(parent, {
+        onNone: () => undefined,
+        onSome: (span) => span.spanId,
+      });
+      const spanId = crypto.randomUUID().replaceAll("-", "").slice(0, 16);
+
+      void ctx
+        .runMutation(component.spans.createSpan, {
+          executionId,
+          traceId,
+          spanId,
+          parentSpanId,
+          name,
+          kind: "system",
+          input: undefined,
+          attributes: options?.attributes,
+        })
+        .catch(() => {});
+
+      const attributes = new Map<string, unknown>(
+        options?.attributes ? Object.entries(options.attributes) : [],
+      );
+
+      const span: Tracer.Span = {
+        _tag: "Span",
+        name,
+        spanId,
+        traceId,
+        parent,
+        context: Context.empty(),
+        status: { _tag: "Started", startTime: 0n },
+        attributes,
+        links: [],
+        sampled: true,
+        kind,
+        end: (_endTime, exit) => {
+          void ctx
+            .runMutation(component.spans.endSpan, {
+              executionId,
+              spanId,
+              output: Exit.isSuccess(exit) ? exit.value : undefined,
+              error: Exit.isFailure(exit) ? String(exit.cause) : undefined,
+              attributes: Object.fromEntries(attributes.entries()),
+            })
+            .catch(() => {});
+        },
+        attribute: (key, value) => {
+          attributes.set(key, value);
+        },
+        event: () => {},
+        addLinks: () => {},
+      };
+
+      return span;
+    },
+    context: (f) => f(),
+  });
+}

package/src/client/ConvexWorkflowEngine.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, test } from "vitest";
+import { ConvexWorkflowEngine } from "./ConvexWorkflowEngine.js";
+
+describe("ConvexWorkflowEngine runner dispatch", () => {
+  test("start schedules component runner fan-in when execution is newly created", async () => {
+    const createExecutionRef = Symbol("createExecution");
+    const runnerRunRef = Symbol("runner.run");
+
+    const scheduled: Array<{ delay: number; fn: unknown; args: unknown }> = [];
+
+    const engine = new ConvexWorkflowEngine({
+      executions: { createExecution: createExecutionRef },
+      runner: { run: runnerRunRef },
+    } as any);
+
+    const ctx = {
+      runMutation: async (fn: unknown) => {
+        if (fn === createExecutionRef) {
+          return { created: true };
+        }
+        throw new Error("unexpected mutation");
+      },
+      runQuery: async () => null,
+      scheduler: {
+        runAfter: async (delay: number, fn: unknown, args: unknown) => {
+          scheduled.push({ delay, fn, args });
+          return "scheduled" as any;
+        },
+      },
+    } as any;
+
+    const executionId = await engine.start(ctx, {
+      workflowName: "orderWorkflow",
+      executionId: "exec-1",
+      payload: { id: 1 },
+      runner: "function://runner" as any,
+    });
+
+    expect(executionId).toBe("exec-1");
+    expect(scheduled).toHaveLength(1);
+    expect(scheduled[0]).toEqual({
+      delay: 0,
+      fn: runnerRunRef,
+      args: { executionId: "exec-1", generation: 0 },
+    });
+  });
+
+  test("start does not schedule runner when execution already exists", async () => {
+    const createExecutionRef = Symbol("createExecution");
+    const runnerRunRef = Symbol("runner.run");
+
+    const scheduled: Array<unknown> = [];
+
+    const engine = new ConvexWorkflowEngine({
+      executions: { createExecution: createExecutionRef },
+      runner: { run: runnerRunRef },
+    } as any);
+
+    const ctx = {
+      runMutation: async () => ({ created: false }),
+      runQuery: async () => null,
+      scheduler: {
+        runAfter: async (_delay: number, _fn: unknown, _args: unknown) => {
+          scheduled.push(true);
+          return "scheduled" as any;
+        },
+      },
+    } as any;
+
+    await engine.start(ctx, {
+      workflowName: "orderWorkflow",
+      executionId: "exec-2",
+      payload: { id: 2 },
+      runner: "function://runner" as any,
+    });
+
+    expect(scheduled).toHaveLength(0);
+  });
+
+  test("resume schedules runner fan-in for active execution and skips terminal", async () => {
+    const getExecutionRef = Symbol("getExecution");
+    const runnerRunRef = Symbol("runner.run");
+
+    const scheduled: Array<{ fn: unknown; args: unknown }> = [];
+
+    const engine = new ConvexWorkflowEngine({
+      executions: { getExecution: getExecutionRef },
+      runner: { run: runnerRunRef },
+    } as any);
+
+    const ctx = {
+      runMutation: async () => null,
+      runQuery: async (_fn: unknown, args: any) => {
+        if (args.executionId === "exec-active") {
+          return { status: "running", generation: 7 };
+        }
+        if (args.executionId === "exec-terminal") {
+          return { status: "completed", generation: 9 };
+        }
+        return null;
+      },
+      scheduler: {
+        runAfter: async (_delay: number, fn: unknown, args: unknown) => {
+          scheduled.push({ fn, args });
+          return "scheduled" as any;
+        },
+      },
+    } as any;
+
+    await engine.resume(ctx, {
+      executionId: "exec-active",
+    });
+
+    await engine.resume(ctx, {
+      executionId: "exec-terminal",
+    });
+
+    expect(scheduled).toHaveLength(1);
+    expect(scheduled[0]).toEqual({
+      fn: runnerRunRef,
+      args: { executionId: "exec-active", generation: 7 },
+    });
+  });
+});

package/src/client/ConvexWorkflowEngine.ts

@@ -0,0 +1,209 @@
+import type {
+  FunctionHandle,
+  GenericDataModel,
+  GenericMutationCtx,
+  GenericQueryCtx,
+} from "convex/server";
+import type { ComponentApi } from "../component/_generated/component.js";
+import type {
+  ExecutionStatus,
+  LogLevel,
+  LogSource,
+  SortOrder,
+  SpanKind,
+  SpanStatus,
+  StepState,
+} from "../shared/validators.js";
+import {
+  scheduleRunnerFanIn,
+  serializeRunnerHandle,
+} from "./boundaries.js";
+
+export type MutationRunCtx = Pick<
+  GenericMutationCtx<GenericDataModel>,
+  "runMutation" | "runQuery" | "scheduler"
+>;
+
+export type QueryRunCtx = Pick<GenericQueryCtx<GenericDataModel>, "runQuery">;
+
+export type RunnerArgs = {
+  executionId: string;
+  generation: number;
+};
+
+export type RunnerHandle = FunctionHandle<"mutation", RunnerArgs, void>;
+
+export type StartWorkflowArgs = {
+  workflowName: string;
+  executionId: string;
+  payload: unknown;
+  runner: RunnerHandle;
+  tenantId?: string;
+  parentExecutionId?: string;
+  traceId?: string;
+};
+
+export type ResumeWorkflowArgs = {
+  executionId: string;
+};
+
+export class ConvexWorkflowEngine {
+  constructor(public component: ComponentApi) {}
+
+  async start(ctx: MutationRunCtx, args: StartWorkflowArgs) {
+    const { created } = await ctx.runMutation(this.component.executions.createExecution, {
+      workflowName: args.workflowName,
+      executionId: args.executionId,
+      payload: args.payload,
+      tenantId: args.tenantId,
+      parentExecutionId: args.parentExecutionId,
+      traceId: args.traceId,
+      runnerHandle: serializeRunnerHandle(args.runner),
+    });
+
+    if (created) {
+      await scheduleRunnerFanIn(ctx.scheduler, this.component, {
+        executionId: args.executionId,
+        generation: 0,
+      });
+    }
+
+    return args.executionId;
+  }
+
+  async poll(ctx: QueryRunCtx, executionId: string) {
+    return await ctx.runQuery(this.component.executions.getExecution, {
+      executionId,
+    });
+  }
+
+  async interrupt(ctx: MutationRunCtx, executionId: string, reason?: string) {
+    return await ctx.runMutation(this.component.executions.interruptExecution, {
+      executionId,
+      reason,
+    });
+  }
+
+  async resume(ctx: MutationRunCtx, args: ResumeWorkflowArgs) {
+    const execution = await ctx.runQuery(this.component.executions.getExecution, {
+      executionId: args.executionId,
+    });
+
+    if (
+      !execution ||
+      execution.status === "completed" ||
+      execution.status === "failed" ||
+      execution.status === "interrupted"
+    ) {
+      return;
+    }
+
+    await scheduleRunnerFanIn(ctx.scheduler, this.component, {
+      executionId: args.executionId,
+      generation: execution.generation,
+    });
+  }
+
+  async listExecutions(
+    ctx: QueryRunCtx,
+    args?: {
+      workflowName?: string;
+      status?: ExecutionStatus;
+      tenantId?: string;
+      startedAfter?: number;
+      startedBefore?: number;
+      limit?: number;
+      cursorStartedAt?: number;
+      cursorExecutionId?: string;
+      order?: SortOrder;
+    },
+  ) {
+    return await ctx.runQuery(this.component.dashboard.listExecutions, {
+      workflowName: args?.workflowName,
+      status: args?.status,
+      tenantId: args?.tenantId,
+      startedAfter: args?.startedAfter,
+      startedBefore: args?.startedBefore,
+      limit: args?.limit,
+      cursorStartedAt: args?.cursorStartedAt,
+      cursorExecutionId: args?.cursorExecutionId,
+      order: args?.order,
+    });
+  }
+
+  async getExecution(ctx: QueryRunCtx, executionId: string) {
+    return await ctx.runQuery(this.component.dashboard.getExecution, {
+      executionId,
+    });
+  }
+
+  async listExecutionSteps(
+    ctx: QueryRunCtx,
+    args: {
+      executionId: string;
+      state?: StepState;
+      limit?: number;
+      afterStepNumber?: number;
+    },
+  ) {
+    return await ctx.runQuery(this.component.dashboard.listExecutionSteps, args);
+  }
+
+  async listExecutionSpans(
+    ctx: QueryRunCtx,
+    args: {
+      executionId: string;
+      kind?: SpanKind;
+      status?: SpanStatus;
+      limit?: number;
+      afterStartTime?: number;
+    },
+  ) {
+    return await ctx.runQuery(this.component.dashboard.listExecutionSpans, args);
+  }
+
+  async listExecutionLogs(
+    ctx: QueryRunCtx,
+    args: {
+      executionId: string;
+      level?: LogLevel;
+      source?: LogSource;
+      spanId?: string;
+      limit?: number;
+      afterTimestamp?: number;
+      order?: SortOrder;
+    },
+  ) {
+    return await ctx.runQuery(this.component.dashboard.listExecutionLogs, args);
+  }
+
+  async getConfig(ctx: QueryRunCtx) {
+    return await ctx.runQuery(this.component.config.getConfig, {});
+  }
+
+  async setConfig(
+    ctx: MutationRunCtx,
+    args: {
+      maxInlineBytes?: number;
+      maxLogDataBytes?: number;
+      maxSpanAttrBytes?: number;
+      retentionDays?: number;
+      defaultLogLevel?: LogLevel;
+    },
+  ) {
+    return await ctx.runMutation(this.component.config.setConfig, args);
+  }
+
+  async cleanup(
+    ctx: MutationRunCtx,
+    args?: {
+      retentionDays?: number;
+      limit?: number;
+    },
+  ) {
+    return await ctx.runMutation(
+      this.component.cleanup.cleanupOldExecutions,
+      args ?? {},
+    );
+  }
+}

package/src/client/activityWorker.ts

@@ -0,0 +1,62 @@
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { internalActionGeneric } from "convex/server";
+import { v } from "convex/values";
+import { WorkflowInstance } from "@effect/workflow/WorkflowEngine";
+import * as Activity from "@effect/workflow/Activity";
+import { getActivity, getWorkflow } from "./registry.js";
+
+export const activityWorkerArgs = {
+  workflowName: v.string(),
+  activityName: v.string(),
+  executionId: v.string(),
+  attempt: v.number(),
+};
+
+export async function runRegisteredActivity(args: {
+  workflowName: string;
+  activityName: string;
+  executionId: string;
+  attempt: number;
+}) {
+  const workflowEntry = getWorkflow(args.workflowName);
+  if (!workflowEntry) {
+    throw new Error(`Workflow not registered: ${args.workflowName}`);
+  }
+  const activity = getActivity(args.activityName);
+  if (!activity) {
+    throw new Error(`Activity not registered: ${args.activityName}`);
+  }
+
+  const instance = WorkflowInstance.initial(
+    workflowEntry.workflow,
+    args.executionId,
+  );
+
+  const exit = await Effect.runPromiseExit(
+    activity.executeEncoded.pipe(
+      Effect.provideService(WorkflowInstance, instance),
+      Effect.provideService(Activity.CurrentAttempt as never, args.attempt),
+    ),
+  );
+
+  if (Exit.isSuccess(exit)) {
+    return exit.value;
+  }
+
+  throw new Error(String(exit.cause));
+}
+
+/**
+ * Create an app-local internal action worker that can execute registered activities.
+ */
+export function defineActivityWorker() {
+  return internalActionGeneric({
+    args: activityWorkerArgs,
+    handler: async (_ctx, args) => {
+      return await runRegisteredActivity(args);
+    },
+  });
+}
+
+export type ActivityWorkerReference = ReturnType<typeof defineActivityWorker>;

package/src/client/boundaries.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test, vi } from "vitest";
+import {
+  enqueueActivity,
+  scheduleDeferredCompletion,
+  scheduleRunnerFanIn,
+} from "./boundaries.js";
+
+describe("client boundaries", () => {
+  test("enqueueActivity delegates to component.runner.enqueueActivity", async () => {
+    const runMutation = vi.fn(async () => "work-123");
+    const runnerEnqueueRef = { _ref: "runner:enqueueActivity" };
+
+    const result = await enqueueActivity(
+      runMutation as any,
+      {
+        runner: {
+          enqueueActivity: runnerEnqueueRef,
+        },
+      } as any,
+      {
+        executionId: "exec-1",
+        generation: 0,
+        workflowName: "wf",
+        activityName: "validateOrder",
+        attempt: 1,
+        stepNumber: 0,
+        spanId: "span-1",
+        activityWorkerHandle: "function://worker",
+      },
+    );
+
+    expect(result).toBe("work-123");
+    expect(runMutation).toHaveBeenCalledTimes(1);
+    expect(runMutation).toHaveBeenCalledWith(runnerEnqueueRef, {
+      executionId: "exec-1",
+      generation: 0,
+      workflowName: "wf",
+      activityName: "validateOrder",
+      attempt: 1,
+      stepNumber: 0,
+      spanId: "span-1",
+      activityWorkerHandle: "function://worker",
+    });
+  });
+
+  test("scheduleRunnerFanIn uses component runner mutation reference", async () => {
+    const runAfter = vi.fn(async () => "scheduled");
+    const runnerRef = { _ref: "runner:run" };
+
+    await scheduleRunnerFanIn(
+      { runAfter } as any,
+      { runner: { run: runnerRef } } as any,
+      { executionId: "exec-2", generation: 3 },
+    );
+
+    expect(runAfter).toHaveBeenCalledWith(0, runnerRef, {
+      executionId: "exec-2",
+      generation: 3,
+    });
+  });
+
+  test("scheduleDeferredCompletion uses component deferred mutation reference", async () => {
+    const runAfter = vi.fn(async () => "scheduled");
+    const deferredRef = { _ref: "deferreds:deferredDone" };
+
+    await scheduleDeferredCompletion(
+      { runAfter } as any,
+      { deferreds: { deferredDone: deferredRef } } as any,
+      500,
+      {
+        executionId: "exec-3",
+        deferredName: "clock/wake",
+        exit: { ok: true },
+      },
+    );
+
+    expect(runAfter).toHaveBeenCalledWith(500, deferredRef, {
+      executionId: "exec-3",
+      deferredName: "clock/wake",
+      exit: { ok: true },
+    });
+  });
+});

package/src/client/boundaries.ts

@@ -0,0 +1,79 @@
+import type {
+  FunctionReference,
+  GenericDataModel,
+  GenericMutationCtx,
+} from "convex/server";
+import type { WorkpoolOptions } from "@convex-dev/workpool";
+import type { ComponentApi } from "../component/_generated/component.js";
+import type { RunnerArgs, RunnerHandle } from "./ConvexWorkflowEngine.js";
+
+type Scheduler = Pick<GenericMutationCtx<GenericDataModel>, "scheduler">["scheduler"];
+
+type MutationRef =
+  | FunctionReference<"mutation", "public">
+  | FunctionReference<"mutation", "internal">;
+
+function asMutationRef(reference: unknown): MutationRef {
+  return reference as MutationRef;
+}
+
+type MutationRun = Pick<
+  GenericMutationCtx<GenericDataModel>,
+  "runMutation"
+>["runMutation"];
+
+type ComponentWithActivityEnqueue = ComponentApi & {
+  runner: {
+    enqueueActivity: MutationRef;
+  };
+};
+
+export type EnqueueActivityArgs = {
+  executionId: string;
+  generation: number;
+  workflowName: string;
+  activityName: string;
+  attempt: number;
+  stepNumber: number;
+  spanId?: string;
+  activityWorkerHandle: string;
+  workpoolOptions?: WorkpoolOptions;
+};
+
+export function serializeRunnerHandle(handle: RunnerHandle): string {
+  return handle as unknown as string;
+}
+
+export function enqueueActivity(
+  runMutation: MutationRun,
+  component: ComponentApi,
+  args: EnqueueActivityArgs,
+) {
+  const reference = (component as ComponentWithActivityEnqueue).runner.enqueueActivity;
+  return runMutation(asMutationRef(reference), args);
+}
+
+export function scheduleRunnerFanIn(
+  scheduler: Scheduler,
+  component: ComponentApi,
+  args: RunnerArgs,
+) {
+  return scheduler.runAfter(0, asMutationRef(component.runner.run), args);
+}
+
+export function scheduleDeferredCompletion(
+  scheduler: Scheduler,
+  component: ComponentApi,
+  runAfterMs: number,
+  args: {
+    executionId: string;
+    deferredName: string;
+    exit: unknown;
+  },
+) {
+  return scheduler.runAfter(
+    runAfterMs,
+    asMutationRef(component.deferreds.deferredDone),
+    args,
+  );
+}