convex-effect-workflows 0.1.0

package/src/client/runner.ts

@@ -0,0 +1,165 @@
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Workflow from "@effect/workflow/Workflow";
+import {
+  makeUnsafe as makeUnsafeWorkflowEngine,
+  WorkflowEngine,
+  type WorkflowInstance,
+} from "@effect/workflow/WorkflowEngine";
+import {
+  createFunctionHandle,
+  internalMutationGeneric,
+  makeFunctionReference,
+  type FunctionReference,
+} from "convex/server";
+import { v } from "convex/values";
+import type { WorkpoolOptions } from "@convex-dev/workpool";
+import type { ComponentApi } from "../component/_generated/component.js";
+import { provideConvexCtx } from "./runtime.js";
+import type { ConvexWorkflowCtx } from "./ConvexCtx.js";
+import {
+  makeConvexEncoded,
+  type ActivityEnqueueArgs,
+  type RunnerEnqueueArgs,
+} from "./encoded.js";
+import { registerWorkflow } from "./registry.js";
+import type { RunnerArgs, RunnerHandle } from "./ConvexWorkflowEngine.js";
+import {
+  enqueueActivity,
+  scheduleRunnerFanIn,
+} from "./boundaries.js";
+
+export type RunnerMutationArgs = RunnerArgs;
+
+type MutationReference =
+  | FunctionReference<"mutation", "public">
+  | FunctionReference<"mutation", "internal">;
+
+type ActionReference =
+  | FunctionReference<"action", "public">
+  | FunctionReference<"action", "internal">;
+
+export type RunnerReference = MutationReference | string;
+
+function asMutationReference(reference: unknown): MutationReference {
+  return reference as MutationReference;
+}
+
+function asRunnerMutationReference(reference: RunnerReference): MutationReference {
+  if (typeof reference === "string") {
+    return makeFunctionReference<"mutation", RunnerMutationArgs, void>(reference);
+  }
+  return reference;
+}
+
+export type ActivityWorkerTarget = ActionReference | string;
+
+async function activityWorkerHandle(
+  reference: ActivityWorkerTarget,
+): Promise<string> {
+  if (typeof reference === "string") {
+    const fnRef = makeFunctionReference<"action">(reference);
+    return await createFunctionHandle(fnRef);
+  }
+  return await createFunctionHandle(reference);
+}
+
+export type RunnerOptions = {
+  // Prefer a module path string like "orderWorkflow:activityWorker".
+  // Registered function objects from internalActionGeneric are not valid
+  // FunctionReferences for createFunctionHandle at runtime.
+  activityWorker: ActivityWorkerTarget;
+  workpoolOptions?: WorkpoolOptions;
+};
+
+/**
+ * Define a workflow runner mutation for one workflow.
+ *
+ * The runner executes one deterministic tick by calling the encoded engine
+ * directly (not `WorkflowEngine.execute`), avoiding in-mutation suspended loops.
+ * Suspension/resume is handled via component.onComplete.
+ */
+export function defineWorkflowRunner(
+  component: ComponentApi,
+  workflow: Workflow.Any,
+  execute: (
+    payload: object,
+    executionId: string,
+  ) => Effect.Effect<unknown, unknown, WorkflowInstance | WorkflowEngine>,
+  options: RunnerOptions,
+) {
+  registerWorkflow(workflow, execute);
+
+  return internalMutationGeneric({
+    args: {
+      executionId: v.string(),
+      generation: v.number(),
+    },
+    handler: async (ctx, args: RunnerMutationArgs) => {
+      const workerHandle = await activityWorkerHandle(options.activityWorker);
+
+      const hooks = {
+        enqueueRunner: async (
+          convexCtx: ConvexWorkflowCtx,
+          hookArgs: RunnerEnqueueArgs,
+        ) => {
+          await scheduleRunnerFanIn(convexCtx.scheduler, component, {
+            executionId: hookArgs.executionId,
+            generation: hookArgs.generation,
+          });
+        },
+        enqueueActivity: async (
+          convexCtx: ConvexWorkflowCtx,
+          hookArgs: ActivityEnqueueArgs,
+        ) => {
+          return await enqueueActivity(convexCtx.runMutation, component, {
+            executionId: hookArgs.executionId,
+            generation: hookArgs.generation,
+            workflowName: workflow.name,
+            activityName: hookArgs.activity.name,
+            attempt: hookArgs.attempt,
+            stepNumber: hookArgs.stepNumber,
+            spanId: hookArgs.spanId,
+            activityWorkerHandle: workerHandle,
+            workpoolOptions: options.workpoolOptions,
+          });
+        },
+      };
+
+      const encoded = makeConvexEncoded(component, hooks);
+      const engine = makeUnsafeWorkflowEngine(encoded);
+
+      const program = Effect.gen(function*() {
+        yield* encoded.register(workflow, execute);
+        return yield* encoded.execute(workflow, {
+          executionId: args.executionId,
+          payload: {},
+          discard: false,
+          parent: undefined,
+        });
+      });
+
+      const exit = await Effect.runPromiseExit(
+        provideConvexCtx(
+          Effect.provideService(program, WorkflowEngine, engine),
+          ctx,
+        ) as Effect.Effect<unknown, never, never>,
+      );
+
+      if (Exit.isFailure(exit)) {
+        await ctx.runMutation(asMutationReference(component.executions.completeExecution), {
+          executionId: args.executionId,
+          generation: args.generation,
+          kind: "failure",
+          error: `Runner failure: ${String(exit.cause)}`,
+        });
+      }
+    },
+  });
+}
+
+export async function functionHandleForRunner(
+  runner: RunnerReference,
+): Promise<RunnerHandle> {
+  return (await createFunctionHandle(asRunnerMutationReference(runner))) as RunnerHandle;
+}

package/src/client/runtime.ts

@@ -0,0 +1,30 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import {
+  makeUnsafe as makeUnsafeWorkflowEngine,
+  WorkflowEngine,
+} from "@effect/workflow/WorkflowEngine";
+import type { ComponentApi } from "../component/_generated/component.js";
+import { ConvexCtx, type ConvexWorkflowCtx } from "./ConvexCtx.js";
+import { makeConvexEncoded, type ConvexEncodedHooks } from "./encoded.js";
+
+export function makeWorkflowEngine(
+  component: ComponentApi,
+  hooks: ConvexEncodedHooks,
+): WorkflowEngine["Type"] {
+  return makeUnsafeWorkflowEngine(makeConvexEncoded(component, hooks));
+}
+
+export function provideConvexCtx<A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  ctx: ConvexWorkflowCtx,
+) {
+  return Effect.provideService(effect, ConvexCtx, ctx);
+}
+
+export function layerConvexWorkflowEngine(
+  component: ComponentApi,
+  hooks: ConvexEncodedHooks,
+): Layer.Layer<WorkflowEngine> {
+  return Layer.succeed(WorkflowEngine, makeWorkflowEngine(component, hooks));
+}

package/src/component/_generated/api.ts

@@ -0,0 +1,179 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as activityCompletions from "../activityCompletions.js";
+import type * as boundaries from "../boundaries.js";
+import type * as cleanup from "../cleanup.js";
+import type * as clocks from "../clocks.js";
+import type * as config from "../config.js";
+import type * as dashboard from "../dashboard.js";
+import type * as deferreds from "../deferreds.js";
+import type * as executions from "../executions.js";
+import type * as journalSteps from "../journalSteps.js";
+import type * as logs from "../logs.js";
+import type * as onComplete from "../onComplete.js";
+import type * as payloads from "../payloads.js";
+import type * as queries from "../queries.js";
+import type * as runner from "../runner.js";
+import type * as spans from "../spans.js";
+import type * as utils from "../utils.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  activityCompletions: typeof activityCompletions;
+  boundaries: typeof boundaries;
+  cleanup: typeof cleanup;
+  clocks: typeof clocks;
+  config: typeof config;
+  dashboard: typeof dashboard;
+  deferreds: typeof deferreds;
+  executions: typeof executions;
+  journalSteps: typeof journalSteps;
+  logs: typeof logs;
+  onComplete: typeof onComplete;
+  payloads: typeof payloads;
+  queries: typeof queries;
+  runner: typeof runner;
+  spans: typeof spans;
+  utils: typeof utils;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {
+  workpool: {
+    config: {
+      update: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          logLevel?: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
+          maxParallelism?: number;
+        },
+        any
+      >;
+    };
+    lib: {
+      cancel: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          id: string;
+          logLevel?: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
+        },
+        any
+      >;
+      cancelAll: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          before?: number;
+          limit?: number;
+          logLevel?: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
+        },
+        any
+      >;
+      enqueue: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          config: {
+            logLevel?: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
+            maxParallelism?: number;
+          };
+          fnArgs: any;
+          fnHandle: string;
+          fnName: string;
+          fnType: "action" | "mutation" | "query";
+          onComplete?: { context?: any; fnHandle: string };
+          retryBehavior?: {
+            base: number;
+            initialBackoffMs: number;
+            maxAttempts: number;
+          };
+          runAt: number;
+        },
+        string
+      >;
+      enqueueBatch: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          config: {
+            logLevel?: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
+            maxParallelism?: number;
+          };
+          items: Array<{
+            fnArgs: any;
+            fnHandle: string;
+            fnName: string;
+            fnType: "action" | "mutation" | "query";
+            onComplete?: { context?: any; fnHandle: string };
+            retryBehavior?: {
+              base: number;
+              initialBackoffMs: number;
+              maxAttempts: number;
+            };
+            runAt: number;
+          }>;
+        },
+        Array<string>
+      >;
+      status: FunctionReference<
+        "query",
+        "internal",
+        { id: string },
+        | { previousAttempts: number; state: "pending" }
+        | { previousAttempts: number; state: "running" }
+        | { state: "finished" }
+      >;
+      statusBatch: FunctionReference<
+        "query",
+        "internal",
+        { ids: Array<string> },
+        Array<
+          | { previousAttempts: number; state: "pending" }
+          | { previousAttempts: number; state: "running" }
+          | { state: "finished" }
+        >
+      >;
+    };
+  };
+};