convex-effect-workflows 0.1.0

package/src/client/encoded.ts

@@ -0,0 +1,484 @@
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Workflow from "@effect/workflow/Workflow";
+import type * as Activity from "@effect/workflow/Activity";
+import type * as DurableDeferred from "@effect/workflow/DurableDeferred";
+import {
+  type Encoded,
+  WorkflowEngine,
+  WorkflowInstance,
+} from "@effect/workflow/WorkflowEngine";
+import type { ComponentApi } from "../component/_generated/component.js";
+import type { Doc } from "../component/_generated/dataModel.js";
+import { ConvexCtx, type ConvexWorkflowCtx } from "./ConvexCtx.js";
+import { scheduleDeferredCompletion } from "./boundaries.js";
+
+type ExecutionDoc = Doc<"executions">;
+type JournalStepDoc = Doc<"journalSteps">;
+type PayloadDoc = Doc<"payloads">;
+
+type ReplayStep = Pick<
+  JournalStepDoc,
+  "stepNumber" | "state" | "signature" | "runResult"
+>;
+
+type ReplayState = {
+  steps: Array<ReplayStep>;
+  cursor: number;
+};
+
+const ReplayStateTag = Context.GenericTag<ReplayState>(
+  "convex-effect-workflows/ReplayState",
+);
+
+export type RunnerEnqueueArgs = {
+  workflow: Workflow.Any;
+  executionId: string;
+  generation: number;
+};
+
+export type ActivityEnqueueArgs = RunnerEnqueueArgs & {
+  activity: Activity.Any;
+  stepNumber: number;
+  spanId: string;
+  attempt: number;
+};
+
+export type ConvexEncodedHooks = {
+  enqueueRunner: (ctx: ConvexWorkflowCtx, args: RunnerEnqueueArgs) => Promise<void>;
+  enqueueActivity: (
+    ctx: ConvexWorkflowCtx,
+    args: ActivityEnqueueArgs,
+  ) => Promise<string>;
+};
+
+type EncodedExecuteOptions = {
+  executionId: string;
+  payload: unknown;
+  discard: boolean;
+  parent?: {
+    executionId: string;
+  };
+};
+
+type EncodedDeferredDoneOptions = {
+  executionId: string;
+  deferredName: string;
+  exit: unknown;
+};
+
+type EncodedScheduleClockOptions = {
+  executionId: string;
+  clock: {
+    duration: Duration.DurationInput;
+    deferred: {
+      name: string;
+    };
+  };
+};
+
+function signaturesMatch(a: unknown, b: unknown) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function asExecuteOptions(options: unknown): EncodedExecuteOptions {
+  return options as EncodedExecuteOptions;
+}
+
+function asDeferredDoneOptions(options: unknown): EncodedDeferredDoneOptions {
+  return options as EncodedDeferredDoneOptions;
+}
+
+function asScheduleClockOptions(options: unknown): EncodedScheduleClockOptions {
+  return options as EncodedScheduleClockOptions;
+}
+
+function toStepResult(step: ReplayStep): Workflow.Result<unknown, unknown> {
+  const runResult = step?.runResult;
+  if (!runResult) {
+    return new Workflow.Suspended({});
+  }
+  if (runResult.kind === "success") {
+    return new Workflow.Complete({ exit: Exit.succeed(runResult.valuePreview) });
+  }
+  if (runResult.kind === "failed") {
+    return new Workflow.Complete({ exit: Exit.fail(runResult.error) });
+  }
+  return new Workflow.Complete({ exit: Exit.fail("canceled") });
+}
+
+function toExecutionTerminal(
+  execution: ExecutionDoc | null | undefined,
+): Workflow.Result<unknown, unknown> | undefined {
+  if (!execution) return undefined;
+  if (execution.status === "completed") {
+    return new Workflow.Complete({ exit: Exit.succeed(execution.resultPreview) });
+  }
+  if (execution.status === "failed" || execution.status === "interrupted") {
+    return new Workflow.Complete({
+      exit: Exit.fail(execution.error ?? "Workflow failed"),
+    });
+  }
+  return undefined;
+}
+
+function readExecution(
+  ctx: ConvexWorkflowCtx,
+  component: ComponentApi,
+  executionId: string,
+): Promise<ExecutionDoc | null> {
+  return ctx.runQuery(component.executions.getExecution, { executionId }) as Promise<
+    ExecutionDoc | null
+  >;
+}
+
+function readJournalSteps(
+  ctx: ConvexWorkflowCtx,
+  component: ComponentApi,
+  executionId: string,
+): Promise<Array<ReplayStep>> {
+  return ctx.runQuery(component.journalSteps.loadJournalForExecution, {
+    executionId,
+  }) as Promise<Array<ReplayStep>>;
+}
+
+function readPayload(
+  ctx: ConvexWorkflowCtx,
+  component: ComponentApi,
+  payloadId: PayloadDoc["_id"],
+): Promise<PayloadDoc | null> {
+  const runQueryPayload = ctx.runQuery as (
+    reference: unknown,
+    args: { payloadId: PayloadDoc["_id"] },
+  ) => Promise<PayloadDoc | null>;
+
+  return runQueryPayload(component.payloads.getPayload, { payloadId });
+}
+
+export function makeConvexEncoded(
+  component: ComponentApi,
+  hooks: ConvexEncodedHooks,
+): Encoded {
+  const workflows = new Map<
+    string,
+    {
+      workflow: Workflow.Any;
+      execute: (
+        payload: object,
+        executionId: string,
+      ) => Effect.Effect<unknown, unknown, WorkflowInstance | WorkflowEngine>;
+    }
+  >();
+
+  const encoded = {
+    register: Effect.fnUntraced(function*(workflow: Workflow.Any, execute: unknown) {
+      workflows.set(workflow.name, {
+        workflow,
+        execute: execute as (
+          payload: object,
+          executionId: string,
+        ) => Effect.Effect<unknown, unknown, WorkflowInstance | WorkflowEngine>,
+      });
+    }),
+
+    execute: Effect.fnUntraced(function*(workflow: Workflow.Any, options: unknown) {
+      const convex = yield* ConvexCtx;
+      const executeOptions = asExecuteOptions(options);
+
+      const created = yield* Effect.promise(() =>
+        convex.runMutation(component.executions.createExecution, {
+          workflowName: workflow.name,
+          executionId: executeOptions.executionId,
+          payload: executeOptions.payload,
+          parentExecutionId: executeOptions.parent?.executionId,
+        }),
+      );
+
+      if (executeOptions.discard) {
+        if (created.created) {
+          yield* Effect.promise(() =>
+            hooks.enqueueRunner(convex, {
+              workflow,
+              executionId: executeOptions.executionId,
+              generation: 0,
+            }),
+          );
+        }
+        return;
+      }
+
+      const execution = yield* Effect.promise(() =>
+        readExecution(convex, component, executeOptions.executionId),
+      );
+      if (!execution) {
+        return new Workflow.Complete({
+          exit: Exit.fail(`Execution not found: ${executeOptions.executionId}`),
+        });
+      }
+
+      const terminal = toExecutionTerminal(execution);
+      if (terminal) {
+        return terminal;
+      }
+
+      yield* Effect.promise(() =>
+        convex.runMutation(component.executions.setExecutionRunning, {
+          executionId: executeOptions.executionId,
+          generation: execution.generation,
+        }),
+      );
+
+      const replaySteps = yield* Effect.promise(() =>
+        readJournalSteps(convex, component, executeOptions.executionId),
+      );
+
+      const registered = workflows.get(workflow.name);
+      if (!registered) {
+        yield* Effect.promise(() =>
+          convex.runMutation(component.executions.completeExecution, {
+            executionId: executeOptions.executionId,
+            generation: execution.generation,
+            kind: "failure",
+            error: `Workflow not registered: ${workflow.name}`,
+          }),
+        );
+        return new Workflow.Complete({
+          exit: Exit.fail(`Workflow not registered: ${workflow.name}`),
+        });
+      }
+
+      const engine = yield* WorkflowEngine;
+      const instance = WorkflowInstance.initial(workflow, executeOptions.executionId);
+
+      let payload = execution.payloadPreview;
+      const payloadRef = execution.payloadRef;
+      if (payloadRef) {
+        const payloadDoc = yield* Effect.promise(() =>
+          readPayload(convex, component, payloadRef),
+        );
+        payload = payloadDoc?.data ?? execution.payloadPreview;
+      }
+
+      const replayState: ReplayState = { steps: replaySteps, cursor: 0 };
+      const result = yield* registered.execute(payload, executeOptions.executionId).pipe(
+        Workflow.intoResult,
+        Effect.provideService(ReplayStateTag, replayState),
+        Effect.provideService(WorkflowInstance, instance),
+        Effect.provideService(WorkflowEngine, engine),
+      );
+
+      if (result._tag === "Complete") {
+        yield* Exit.match(result.exit, {
+          onSuccess: (value) =>
+            Effect.promise(() =>
+              convex.runMutation(component.executions.completeExecution, {
+                executionId: executeOptions.executionId,
+                generation: execution.generation,
+                kind: "success",
+                result: value,
+              }),
+            ),
+          onFailure: (cause) =>
+            Effect.promise(() =>
+              convex.runMutation(component.executions.completeExecution, {
+                executionId: executeOptions.executionId,
+                generation: execution.generation,
+                kind: "failure",
+                error: String(cause),
+              }),
+            ),
+        });
+      } else {
+        yield* Effect.promise(() =>
+          convex.runMutation(component.executions.setExecutionSuspended, {
+            executionId: executeOptions.executionId,
+            generation: execution.generation,
+          }),
+        );
+      }
+
+      return result;
+    }),
+
+    poll: Effect.fnUntraced(function*(_workflow: Workflow.Any, executionId: string) {
+      const convex = yield* ConvexCtx;
+      const execution = yield* Effect.promise(() =>
+        readExecution(convex, component, executionId),
+      );
+      return toExecutionTerminal(execution);
+    }),
+
+    interrupt: Effect.fnUntraced(function*(_workflow: Workflow.Any, executionId: string) {
+      const convex = yield* ConvexCtx;
+      yield* Effect.promise(() =>
+        convex.runMutation(component.executions.interruptExecution, {
+          executionId,
+          reason: "Interrupted",
+        }),
+      );
+    }),
+
+    resume: Effect.fnUntraced(function*(workflow: Workflow.Any, executionId: string) {
+      const convex = yield* ConvexCtx;
+      const execution = yield* Effect.promise(() =>
+        readExecution(convex, component, executionId),
+      );
+      if (!execution || execution.status === "interrupted") {
+        return;
+      }
+      yield* Effect.promise(() =>
+        hooks.enqueueRunner(convex, {
+          workflow,
+          executionId,
+          generation: execution.generation,
+        }),
+      );
+    }),
+
+    activityExecute: Effect.fnUntraced(function*(activity: Activity.Any, attempt: number) {
+      const convex = yield* ConvexCtx;
+      const instance = yield* WorkflowInstance;
+      const replay = yield* ReplayStateTag;
+
+      const signature = {
+        kind: "activity" as const,
+        opName: activity.name,
+      };
+
+      const replayed = replay.steps[replay.cursor];
+      if (replayed) {
+        replay.cursor += 1;
+        if (!signaturesMatch(replayed.signature, signature)) {
+          throw new Error(
+            `Determinism mismatch at ${instance.executionId}/${replayed.stepNumber}`,
+          );
+        }
+        if (
+          replayed.state === "completed" ||
+          replayed.state === "failed" ||
+          replayed.state === "canceled"
+        ) {
+          return toStepResult(replayed);
+        }
+        return new Workflow.Suspended({});
+      }
+
+      const execution = yield* Effect.promise(() =>
+        readExecution(convex, component, instance.executionId),
+      );
+      if (!execution) {
+        return new Workflow.Complete({
+          exit: Exit.fail(`Execution not found: ${instance.executionId}`),
+        });
+      }
+
+      const stepNumber = replay.steps.length;
+      const span = yield* Effect.promise(() =>
+        convex.runMutation(component.spans.createSpan, {
+          executionId: instance.executionId,
+          traceId: execution.traceId,
+          name: activity.name,
+          kind: "activity",
+          stepNumber,
+          attempt,
+        }),
+      );
+
+      yield* Effect.promise(() =>
+        convex.runMutation(component.journalSteps.appendJournalStep, {
+          executionId: instance.executionId,
+          stepNumber,
+          kind: "activity",
+          name: activity.name,
+          signature,
+          attempt,
+          spanId: span.spanId,
+          input: null,
+        }),
+      );
+
+      const workId = yield* Effect.promise(() =>
+        hooks.enqueueActivity(convex, {
+          workflow: instance.workflow,
+          executionId: instance.executionId,
+          generation: execution.generation,
+          activity,
+          stepNumber,
+          spanId: span.spanId,
+          attempt,
+        }),
+      );
+
+      yield* Effect.promise(() =>
+        convex.runMutation(component.journalSteps.suspendJournalStep, {
+          executionId: instance.executionId,
+          stepNumber,
+          workId,
+        }),
+      );
+
+      replay.steps.push({
+        stepNumber,
+        state: "suspended",
+        signature,
+      });
+      replay.cursor += 1;
+
+      return new Workflow.Suspended({});
+    }),
+
+    deferredResult: Effect.fnUntraced(function*(deferred: DurableDeferred.Any) {
+      const convex = yield* ConvexCtx;
+      const instance = yield* WorkflowInstance;
+      return yield* Effect.promise(() =>
+        convex.runQuery(component.deferreds.deferredResult, {
+          executionId: instance.executionId,
+          deferredName: deferred.name,
+        }),
+      );
+    }),
+
+    deferredDone: Effect.fnUntraced(function*(options: unknown) {
+      const convex = yield* ConvexCtx;
+      const doneOptions = asDeferredDoneOptions(options);
+
+      yield* Effect.promise(() =>
+        convex.runMutation(component.deferreds.deferredDone, {
+          executionId: doneOptions.executionId,
+          deferredName: doneOptions.deferredName,
+          exit: doneOptions.exit,
+        }),
+      );
+    }),
+
+    scheduleClock: Effect.fnUntraced(function*(
+      _workflow: Workflow.Any,
+      options: unknown,
+    ) {
+      const convex = yield* ConvexCtx;
+      const clockOptions = asScheduleClockOptions(options);
+
+      const execution = yield* Effect.promise(() =>
+        readExecution(convex, component, clockOptions.executionId),
+      );
+      if (!execution) {
+        return;
+      }
+
+      const ms = Duration.toMillis(clockOptions.clock.duration);
+      const runAfter = Math.max(0, Math.ceil(ms));
+
+      yield* Effect.promise(() =>
+        scheduleDeferredCompletion(convex.scheduler, component, runAfter, {
+          executionId: clockOptions.executionId,
+          deferredName: clockOptions.clock.deferred.name,
+          exit: Exit.void,
+        }),
+      );
+    }),
+  };
+
+  return encoded as unknown as Encoded;
+}

package/src/client/index.ts

@@ -0,0 +1,47 @@
+export { ConvexWorkflowEngine } from "./ConvexWorkflowEngine.js";
+export type {
+  MutationRunCtx,
+  QueryRunCtx,
+  RunnerArgs,
+  RunnerHandle,
+  StartWorkflowArgs,
+  ResumeWorkflowArgs,
+} from "./ConvexWorkflowEngine.js";
+
+export { ConvexCtx, ConvexActionCtx } from "./ConvexCtx.js";
+export type { ConvexWorkflowCtx, ConvexWorkflowActionCtx } from "./ConvexCtx.js";
+
+export { makeConvexLogger } from "./ConvexLogger.js";
+export { makeConvexTracer } from "./ConvexTracer.js";
+
+export {
+  makeConvexEncoded,
+  type ConvexEncodedHooks,
+  type RunnerEnqueueArgs,
+  type ActivityEnqueueArgs,
+} from "./encoded.js";
+
+export {
+  makeWorkflowEngine,
+  provideConvexCtx,
+  layerConvexWorkflowEngine,
+} from "./runtime.js";
+
+export {
+  serializeRunnerHandle,
+  scheduleRunnerFanIn,
+  scheduleDeferredCompletion,
+} from "./boundaries.js";
+
+export { registerActivity, registerWorkflow, getActivity, getWorkflow } from "./registry.js";
+export {
+  defineActivityWorker,
+  runRegisteredActivity,
+  activityWorkerArgs,
+} from "./activityWorker.js";
+export {
+  defineWorkflowRunner,
+  functionHandleForRunner,
+  type RunnerMutationArgs,
+  type RunnerOptions,
+} from "./runner.js";

package/src/client/registry.ts

@@ -0,0 +1,35 @@
+import type * as Activity from "@effect/workflow/Activity";
+import type * as Workflow from "@effect/workflow/Workflow";
+import type * as Effect from "effect/Effect";
+import type { WorkflowEngine, WorkflowInstance } from "@effect/workflow/WorkflowEngine";
+
+export type WorkflowExecute = (
+  payload: object,
+  executionId: string,
+) => Effect.Effect<unknown, unknown, WorkflowInstance | WorkflowEngine>;
+
+const workflows = new Map<string, { workflow: Workflow.Any; execute: WorkflowExecute }>();
+const activities = new Map<string, Activity.Any>();
+
+export function registerWorkflow(workflow: Workflow.Any, execute: WorkflowExecute) {
+  workflows.set(workflow.name, { workflow, execute });
+}
+
+export function getWorkflow(name: string) {
+  return workflows.get(name);
+}
+
+export function registerActivity(activity: Activity.Any) {
+  activities.set(activity.name, activity);
+}
+
+export function getActivity(name: string) {
+  return activities.get(name);
+}
+
+export function listRegistered() {
+  return {
+    workflows: [...workflows.keys()],
+    activities: [...activities.keys()],
+  };
+}