@gencow/core 0.1.22 → 0.1.24

package/src/workflow.ts

@@ -0,0 +1,205 @@
+import { sql } from "drizzle-orm";
+import { mutation } from "./reactive.js";
+import type { MutationDef } from "./reactive.js";
+import type {
+    WorkflowDef,
+    WorkflowDuration,
+    WorkflowOptions,
+    WorkflowStartResult,
+} from "./workflow-types.js";
+import { registerWorkflowsApi } from "./workflows-api.js";
+
+declare global {
+    // eslint-disable-next-line no-var
+    var __gencow_workflowRegistry: Map<string, WorkflowDef<any, any>>;
+}
+
+const workflowRegistry =
+    globalThis.__gencow_workflowRegistry ??= new Map<string, WorkflowDef<any, any>>();
+
+export const DEFAULT_WORKFLOW_MAX_DURATION_MS = 30 * 60 * 1000;
+export const DEFAULT_WORKFLOW_MAX_RETRIES = 3;
+export const WORKFLOW_RESUME_ACTION_PREFIX = "__gencow.workflow.resume";
+export const WORKFLOW_REALTIME_KEY_PREFIX = "__gencow.workflow.state";
+
+type SerializedWorkflowValue =
+    | { __gencowUndefined: true }
+    | { value: unknown };
+
+function isSerializedWorkflowValue(value: unknown): value is SerializedWorkflowValue {
+    return !!value && typeof value === "object" && (
+        "__gencowUndefined" in value ||
+        "value" in value
+    );
+}
+
+export function serializeWorkflowValue(value: unknown): SerializedWorkflowValue {
+    const payload = value === undefined
+        ? { __gencowUndefined: true as const }
+        : { value };
+
+    try {
+        return JSON.parse(JSON.stringify(payload)) as SerializedWorkflowValue;
+    } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(
+            `workflow() only persists JSON-serializable values. Failed to serialize workflow payload: ${reason}`
+        );
+    }
+}
+
+export function deserializeWorkflowValue(value: unknown): unknown {
+    if (!isSerializedWorkflowValue(value)) return value;
+    if ("__gencowUndefined" in value) return undefined;
+    return value.value;
+}
+
+function clampRetries(retries: number | undefined): number {
+    if (retries == null) return DEFAULT_WORKFLOW_MAX_RETRIES;
+    if (!Number.isFinite(retries) || retries < 0) {
+        throw new Error(`workflow() retries must be a non-negative finite number, got "${retries}"`);
+    }
+    return Math.floor(retries);
+}
+
+function parseDurationString(raw: string, label: string): number {
+    const normalized = raw.trim().toLowerCase();
+    const match = normalized.match(/^(\d+)(ms|s|m|h|d)$/);
+    if (!match) {
+        throw new Error(
+            `${label} must be a number of ms or a string like "30m", "90s", "1h" — got "${raw}"`
+        );
+    }
+    const value = Number(match[1]);
+    const unit = match[2];
+    const unitMs =
+        unit === "ms" ? 1 :
+            unit === "s" ? 1_000 :
+                unit === "m" ? 60_000 :
+                    unit === "h" ? 3_600_000 :
+                        86_400_000;
+    return value * unitMs;
+}
+
+export function parseWorkflowDurationMs(
+    raw: WorkflowDuration,
+    label = "workflow duration"
+): number {
+    if (typeof raw === "number") {
+        if (!Number.isFinite(raw) || raw <= 0) {
+            throw new Error(`${label} must be a positive finite number, got "${raw}"`);
+        }
+        return Math.floor(raw);
+    }
+    if (typeof raw !== "string") {
+        throw new Error(
+            `${label} must be a positive finite number or a string like "30m", "90s", "1h" — got "${String(raw)}"`
+        );
+    }
+    return parseDurationString(raw, label);
+}
+
+function normalizeMaxDurationMs(maxDuration: WorkflowDuration | undefined): number {
+    if (maxDuration == null) return DEFAULT_WORKFLOW_MAX_DURATION_MS;
+    return parseWorkflowDurationMs(maxDuration, "workflow() maxDuration");
+}
+
+export function getWorkflowResumeActionName(name: string): string {
+    return `${WORKFLOW_RESUME_ACTION_PREFIX}.${name}`;
+}
+
+export function createWorkflowRealtimeToken(): string {
+    return crypto.randomUUID().replace(/-/g, "");
+}
+
+export function getWorkflowRealtimeKey(workflowId: string, realtimeToken: string): string {
+    return `${WORKFLOW_REALTIME_KEY_PREFIX}.${workflowId}.${realtimeToken}`;
+}
+
+export function getWorkflowDef(name: string): WorkflowDef | undefined {
+    return workflowRegistry.get(name);
+}
+
+export function getRegisteredWorkflows(): WorkflowDef[] {
+    return Array.from(workflowRegistry.values());
+}
+
+/**
+ * workflow() — durable multi-step execution with step memoization.
+ *
+ * The returned value is still a mutation definition, so existing API codegen and
+ * frontend hooks keep working without extra workflow-specific tooling.
+ */
+export function workflow<TSchema = any, TReturn = any>(
+    name: string,
+    options: WorkflowOptions<TSchema, TReturn>
+): MutationDef<TSchema, WorkflowStartResult> {
+    registerWorkflowsApi();
+
+    const maxDurationMs = normalizeMaxDurationMs(options.maxDuration);
+    const maxRetries = clampRetries(options.retries);
+
+    const def: WorkflowDef<TSchema, TReturn> = {
+        name,
+        argsSchema: options.args,
+        isPublic: options.public === true,
+        maxDurationMs,
+        maxRetries,
+        handler: options.handler,
+    };
+
+    workflowRegistry.set(name, def);
+
+    return mutation<TSchema, WorkflowStartResult>(name, {
+        args: options.args,
+        public: options.public,
+        handler: async (ctx, args) => {
+            const workflowId = crypto.randomUUID();
+            const resumeAction = getWorkflowResumeActionName(name);
+            const ownerId = ctx.auth.getUserIdentity()?.id ?? null;
+            const persistedArgs = serializeWorkflowValue(args ?? {});
+            const realtimeToken = createWorkflowRealtimeToken();
+
+            await ctx.unsafeDb.execute(sql`
+                INSERT INTO _gencow_workflows (
+                    id,
+                    name,
+                    args,
+                    realtime_token,
+                    status,
+                    retry_count,
+                    max_retries,
+                    max_duration_ms,
+                    user_id
+                )
+                VALUES (
+                    ${workflowId},
+                    ${name},
+                    ${JSON.stringify(persistedArgs)}::jsonb,
+                    ${realtimeToken},
+                    'pending',
+                    0,
+                    ${maxRetries},
+                    ${maxDurationMs},
+                    ${ownerId}
+                )
+            `);
+
+            try {
+                const scheduledJobId = ctx.scheduler.runAfter(0, resumeAction, { workflowId });
+                return {
+                    id: workflowId,
+                    name,
+                    status: "pending",
+                    scheduledJobId,
+                };
+            } catch (error) {
+                await ctx.unsafeDb.execute(sql`
+                    DELETE FROM _gencow_workflows
+                    WHERE id = ${workflowId}
+                `);
+                throw error;
+            }
+        },
+    });
+}

package/src/workflows-api.ts

@@ -0,0 +1,425 @@
+import { sql } from "drizzle-orm";
+import { mutation, query } from "./reactive.js";
+import {
+    createWorkflowRealtimeToken,
+    deserializeWorkflowValue,
+    getWorkflowResumeActionName,
+    getWorkflowRealtimeKey,
+    serializeWorkflowValue,
+} from "./workflow.js";
+import { GencowValidationError, v } from "./v.js";
+import type {
+    WorkflowDerivedStatus,
+    WorkflowSnapshot,
+    WorkflowSignalResult,
+    WorkflowStatus,
+    WorkflowStepSnapshot,
+    WorkflowSummary,
+} from "./workflow-types.js";
+import { deriveWorkflowStatus } from "./workflow-types.js";
+
+declare global {
+    // eslint-disable-next-line no-var
+    var __gencow_workflowsApiRegistered: boolean | undefined;
+}
+
+type WorkflowRow = {
+    id: string;
+    name: string;
+    args: unknown;
+    status: WorkflowStatus;
+    current_step: string | null;
+    result: unknown;
+    error: string | null;
+    retry_count: number;
+    max_retries: number;
+    max_duration_ms: number;
+    started_at: string | Date;
+    updated_at: string | Date;
+    completed_at: string | Date | null;
+    realtime_token: string | null;
+    user_id: string | null;
+};
+
+type WorkflowStepRow = {
+    step_name: string;
+    status: WorkflowStatus;
+    output: unknown;
+    error: string | null;
+    started_at: string | Date | null;
+    updated_at: string | Date;
+    completed_at: string | Date | null;
+};
+
+type WorkflowSignalTargetRow = {
+    id: string;
+    name: string;
+    status: WorkflowStatus;
+    current_step: string | null;
+    user_id: string | null;
+};
+
+const WORKFLOW_STATUSES = new Set<WorkflowStatus>([
+    "pending",
+    "running",
+    "completed",
+    "failed",
+]);
+const WORKFLOW_DERIVED_PENDING_STATUSES = new Set<WorkflowDerivedStatus>([
+    "queued",
+    "waiting",
+    "sleeping",
+]);
+
+type WorkflowDbLike = {
+    execute: (query: unknown) => Promise<unknown>;
+};
+
+function rowsFromResult<T>(result: unknown): T[] {
+    if (Array.isArray(result)) return result as T[];
+    if (result && typeof result === "object" && Array.isArray((result as { rows?: unknown[] }).rows)) {
+        return (result as { rows: T[] }).rows;
+    }
+    return [];
+}
+
+function parseJsonField(value: unknown): unknown {
+    if (typeof value !== "string") return value;
+    try {
+        return JSON.parse(value);
+    } catch {
+        return value;
+    }
+}
+
+function toIsoString(value: string | Date): string {
+    if (value instanceof Date) return value.toISOString();
+    const parsed = new Date(value);
+    return Number.isFinite(parsed.getTime()) ? parsed.toISOString() : String(value);
+}
+
+function toOptionalIsoString(value: string | Date | null): string | null {
+    return value ? toIsoString(value) : null;
+}
+
+function mapWorkflowSummary(row: WorkflowRow): WorkflowSummary {
+    return {
+        id: row.id,
+        name: row.name,
+        status: row.status,
+        derivedStatus: deriveWorkflowStatus(row.status, row.current_step),
+        currentStep: row.current_step,
+        error: row.error,
+        retryCount: row.retry_count,
+        maxRetries: row.max_retries,
+        maxDurationMs: Number(row.max_duration_ms),
+        startedAt: toIsoString(row.started_at),
+        updatedAt: toIsoString(row.updated_at),
+        completedAt: toOptionalIsoString(row.completed_at),
+    };
+}
+
+function mapWorkflowStep(row: WorkflowStepRow): WorkflowStepSnapshot {
+    return {
+        name: row.step_name,
+        status: row.status,
+        output: deserializeWorkflowValue(parseJsonField(row.output)),
+        error: row.error,
+        startedAt: toOptionalIsoString(row.started_at),
+        updatedAt: toIsoString(row.updated_at),
+        completedAt: toOptionalIsoString(row.completed_at),
+    };
+}
+
+function normalizeListLimit(limit: number | undefined): number {
+    if (limit == null) return 20;
+    if (!Number.isFinite(limit)) {
+        throw new GencowValidationError(`Argument "limit": expected a finite number, got ${limit}`);
+    }
+    return Math.max(1, Math.min(100, Math.floor(limit)));
+}
+
+function normalizeStatus(status: string | undefined): WorkflowStatus | undefined {
+    if (status == null) return undefined;
+    if (!WORKFLOW_STATUSES.has(status as WorkflowStatus)) {
+        throw new GencowValidationError(
+            `Argument "status": expected one of pending, running, completed, failed`
+        );
+    }
+    return status as WorkflowStatus;
+}
+
+function normalizeDerivedStatus(status: string | undefined): WorkflowDerivedStatus | undefined {
+    if (status == null) return undefined;
+    if (WORKFLOW_DERIVED_PENDING_STATUSES.has(status as WorkflowDerivedStatus)) {
+        return status as WorkflowDerivedStatus;
+    }
+    return normalizeStatus(status) as WorkflowDerivedStatus;
+}
+
+function toWorkflowStatusFilter(status: WorkflowDerivedStatus | undefined): WorkflowStatus | undefined {
+    if (status == null) return undefined;
+    if (WORKFLOW_DERIVED_PENDING_STATUSES.has(status)) {
+        return "pending";
+    }
+    return status as WorkflowStatus;
+}
+
+async function ensureWorkflowRealtimeToken(
+    db: WorkflowDbLike,
+    workflowId: string,
+    currentToken: string | null
+): Promise<string | null> {
+    if (currentToken && currentToken.trim() !== "") return currentToken;
+
+    const nextToken = createWorkflowRealtimeToken();
+    const updateResult = await db.execute(sql`
+        UPDATE _gencow_workflows
+        SET realtime_token = ${nextToken}
+        WHERE id = ${workflowId}
+          AND (realtime_token IS NULL OR realtime_token = '')
+        RETURNING realtime_token
+    `);
+    const updatedToken = rowsFromResult<{ realtime_token: string | null }>(updateResult)[0]?.realtime_token ?? null;
+    if (updatedToken && updatedToken.trim() !== "") return updatedToken;
+
+    const rereadResult = await db.execute(sql`
+        SELECT realtime_token
+        FROM _gencow_workflows
+        WHERE id = ${workflowId}
+        LIMIT 1
+    `);
+    const rereadToken = rowsFromResult<{ realtime_token: string | null }>(rereadResult)[0]?.realtime_token ?? null;
+    return rereadToken && rereadToken.trim() !== "" ? rereadToken : null;
+}
+
+async function loadWorkflowSignalTarget(
+    db: WorkflowDbLike,
+    workflowId: string
+): Promise<WorkflowSignalTargetRow | null> {
+    const result = await db.execute(sql`
+        SELECT
+            id,
+            name,
+            status,
+            current_step,
+            user_id
+        FROM _gencow_workflows
+        WHERE id = ${workflowId}
+        LIMIT 1
+    `);
+    return rowsFromResult<WorkflowSignalTargetRow>(result)[0] ?? null;
+}
+
+export async function loadWorkflowSnapshot(
+    db: WorkflowDbLike,
+    workflowId: string,
+    options?: {
+        viewerUserId?: string | null;
+        requireViewerMatch?: boolean;
+    }
+): Promise<WorkflowSnapshot | null> {
+    const workflowResult = await db.execute(sql`
+        SELECT
+            id,
+            name,
+            args,
+            status,
+            current_step,
+            result,
+            error,
+            retry_count,
+            max_retries,
+            max_duration_ms,
+            started_at,
+            updated_at,
+            completed_at,
+            realtime_token,
+            user_id
+        FROM _gencow_workflows
+        WHERE id = ${workflowId}
+        LIMIT 1
+    `);
+    const row = rowsFromResult<WorkflowRow>(workflowResult)[0] ?? null;
+    if (!row) return null;
+
+    const viewerUserId = options?.viewerUserId ?? null;
+    if (options?.requireViewerMatch && row.user_id && row.user_id !== viewerUserId) {
+        return null;
+    }
+
+    const realtimeToken = await ensureWorkflowRealtimeToken(db, workflowId, row.realtime_token);
+    if (!realtimeToken) return null;
+
+    const stepsResult = await db.execute(sql`
+        SELECT
+            step_name,
+            status,
+            output,
+            error,
+            started_at,
+            updated_at,
+            completed_at
+        FROM _gencow_workflow_steps
+        WHERE workflow_id = ${workflowId}
+        ORDER BY COALESCE(started_at, updated_at) ASC, step_name ASC
+    `);
+
+    return {
+        ...mapWorkflowSummary(row),
+        args: deserializeWorkflowValue(parseJsonField(row.args)),
+        result: deserializeWorkflowValue(parseJsonField(row.result)),
+        steps: rowsFromResult<WorkflowStepRow>(stepsResult).map(mapWorkflowStep),
+        realtimeKey: getWorkflowRealtimeKey(row.id, realtimeToken),
+    };
+}
+
+export function registerWorkflowsApi(): void {
+    if (globalThis.__gencow_workflowsApiRegistered) return;
+    globalThis.__gencow_workflowsApiRegistered = true;
+
+    query("workflows.get", {
+        args: { id: v.string() },
+        public: true,
+        handler: async (ctx, args): Promise<WorkflowSnapshot | null> => {
+            return loadWorkflowSnapshot(ctx.unsafeDb, args.id, {
+                viewerUserId: ctx.auth.getUserIdentity()?.id ?? null,
+                requireViewerMatch: true,
+            });
+        },
+    });
+
+    mutation("workflows.signal", {
+        args: {
+            id: v.string(),
+            event: v.string(),
+            payload: v.optional(v.any()),
+        },
+        public: true,
+        handler: async (ctx, args): Promise<WorkflowSignalResult> => {
+            const normalizedEvent = args.event.trim();
+            if (!normalizedEvent) {
+                throw new GencowValidationError(`Argument "event": expected a non-empty string`);
+            }
+
+            const workflow = await loadWorkflowSignalTarget(ctx.unsafeDb, args.id);
+            const viewerUserId = ctx.auth.getUserIdentity()?.id ?? null;
+
+            if (!workflow || (workflow.user_id && workflow.user_id !== viewerUserId)) {
+                return {
+                    ok: false,
+                    workflowId: args.id,
+                    event: normalizedEvent,
+                    scheduledJobId: null,
+                };
+            }
+
+            if (workflow.status === "completed" || workflow.status === "failed") {
+                return {
+                    ok: false,
+                    workflowId: workflow.id,
+                    event: normalizedEvent,
+                    scheduledJobId: null,
+                };
+            }
+
+            const persistedPayload = serializeWorkflowValue(args.payload);
+            await ctx.unsafeDb.execute(sql`
+                INSERT INTO _gencow_workflow_events (
+                    id,
+                    workflow_id,
+                    event_name,
+                    payload
+                )
+                VALUES (
+                    ${crypto.randomUUID()},
+                    ${workflow.id},
+                    ${normalizedEvent},
+                    ${JSON.stringify(persistedPayload)}::jsonb
+                )
+            `);
+
+            let scheduledJobId: string | null = null;
+            if (workflow.status === "pending" && workflow.current_step?.startsWith("wait:")) {
+                try {
+                    scheduledJobId = ctx.scheduler.runAfter(
+                        0,
+                        getWorkflowResumeActionName(workflow.name),
+                        { workflowId: workflow.id }
+                    );
+                } catch {
+                    scheduledJobId = null;
+                }
+            }
+
+            return {
+                ok: true,
+                workflowId: workflow.id,
+                event: normalizedEvent,
+                scheduledJobId,
+            };
+        },
+    });
+
+    query("workflows.list", {
+        args: {
+            limit: v.optional(v.number()),
+            status: v.optional(v.string()),
+        },
+        handler: async (ctx, args): Promise<WorkflowSummary[]> => {
+            const userId = ctx.auth.requireAuth().id;
+            const limit = normalizeListLimit(args.limit);
+            const requestedStatus = normalizeDerivedStatus(args.status);
+            const status = toWorkflowStatusFilter(requestedStatus);
+
+            const result = status == null
+                ? await ctx.unsafeDb.execute(sql`
+                    SELECT
+                        id,
+                        name,
+                        args,
+                        status,
+                        current_step,
+                        result,
+                        error,
+                        retry_count,
+                        max_retries,
+                        max_duration_ms,
+                        started_at,
+                        updated_at,
+                        completed_at,
+                        user_id
+                    FROM _gencow_workflows
+                    WHERE user_id = ${userId}
+                    ORDER BY started_at DESC
+                    LIMIT ${limit}
+                `)
+                : await ctx.unsafeDb.execute(sql`
+                    SELECT
+                        id,
+                        name,
+                        args,
+                        status,
+                        current_step,
+                        result,
+                        error,
+                        retry_count,
+                        max_retries,
+                        max_duration_ms,
+                        started_at,
+                        updated_at,
+                        completed_at,
+                        user_id
+                    FROM _gencow_workflows
+                    WHERE user_id = ${userId}
+                      AND status = ${status}
+                    ORDER BY started_at DESC
+                    LIMIT ${limit}
+                `);
+
+            return rowsFromResult<WorkflowRow>(result)
+                .map(mapWorkflowSummary)
+                .filter((row) => requestedStatus == null || row.derivedStatus === requestedStatus);
+        },
+    });
+}