@gencow/core 0.1.22 → 0.1.24

package/src/__tests__/workflow.test.ts

@@ -0,0 +1,583 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { PGlite } from "@electric-sql/pglite";
+import { drizzle } from "drizzle-orm/pglite";
+import { sql } from "drizzle-orm";
+import { getWorkflowResumeActionName, workflow } from "../workflow.js";
+import { getQueryDef, getRegisteredMutations } from "../reactive.js";
+import { v } from "../v.js";
+import { registerWorkflowsApi } from "../workflows-api.js";
+
+const WORKFLOW_TABLE_SETUP = [
+    `CREATE TABLE IF NOT EXISTS _gencow_workflows (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        args JSONB NOT NULL DEFAULT '{}'::jsonb,
+        status TEXT NOT NULL DEFAULT 'pending',
+        current_step TEXT,
+        result JSONB,
+        error TEXT,
+        realtime_token TEXT NOT NULL DEFAULT '',
+        retry_count INTEGER NOT NULL DEFAULT 0,
+        max_retries INTEGER NOT NULL DEFAULT 3,
+        max_duration_ms BIGINT NOT NULL DEFAULT 1800000,
+        started_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        completed_at TIMESTAMPTZ,
+        user_id TEXT
+    )`,
+    `CREATE TABLE IF NOT EXISTS _gencow_workflow_steps (
+        id SERIAL PRIMARY KEY,
+        workflow_id TEXT NOT NULL REFERENCES _gencow_workflows(id) ON DELETE CASCADE,
+        step_name TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'pending',
+        output JSONB,
+        error TEXT,
+        started_at TIMESTAMPTZ,
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        completed_at TIMESTAMPTZ,
+        UNIQUE(workflow_id, step_name)
+    )`,
+    `CREATE TABLE IF NOT EXISTS _gencow_workflow_events (
+        id TEXT PRIMARY KEY,
+        workflow_id TEXT NOT NULL REFERENCES _gencow_workflows(id) ON DELETE CASCADE,
+        event_name TEXT NOT NULL,
+        payload JSONB,
+        received_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        consumed_at TIMESTAMPTZ
+    )`,
+] as const;
+
+describe("workflow()", () => {
+    let client: PGlite;
+    let db: ReturnType<typeof drizzle>;
+
+    function buildCtx(userId: string | null) {
+        return {
+            db,
+            unsafeDb: db,
+            auth: {
+                getUserIdentity: () => (
+                    userId
+                        ? { id: userId, email: `${userId}@workflow.test` }
+                        : null
+                ),
+                requireAuth: () => {
+                    if (!userId) throw new Error("Authentication required");
+                    return { id: userId, email: `${userId}@workflow.test` };
+                },
+            },
+            storage: {} as any,
+            scheduler: {
+                runAfter: () => "unused",
+                runAt: () => "unused",
+                cancel: () => false,
+                cron: () => {},
+                registerAction: () => {},
+                executeAction: async () => {},
+            },
+            realtime: { emit: () => {}, refresh: () => {} },
+            retry: async (fn: () => Promise<unknown>) => fn(),
+        };
+    }
+
+    beforeAll(async () => {
+        client = new PGlite();
+        db = drizzle(client);
+        for (const stmt of WORKFLOW_TABLE_SETUP) {
+            await client.exec(stmt);
+        }
+        registerWorkflowsApi();
+    });
+
+    afterAll(async () => {
+        await client.close();
+    });
+
+    it("start mutation inserts workflow row and schedules resume action", async () => {
+        const name = `agents.workflowStart${Date.now()}`;
+        const start = workflow(name, {
+            args: { topic: v.string() },
+            handler: async () => ({ ok: true }),
+        });
+
+        const scheduled: Array<{ delayMs: number; action: string; args: unknown }> = [];
+        const result = await start.handler({
+            db,
+            unsafeDb: db,
+            auth: {
+                getUserIdentity: () => ({ id: "user_workflow_start", email: "owner@test.dev" }),
+                requireAuth: () => ({ id: "user_workflow_start", email: "owner@test.dev" }),
+            },
+            storage: {} as any,
+            scheduler: {
+                runAfter: (delayMs, action, args) => {
+                    scheduled.push({ delayMs, action, args });
+                    return "job-start-1";
+                },
+                runAt: () => "unused",
+                cancel: () => false,
+                cron: () => {},
+                registerAction: () => {},
+                executeAction: async () => {},
+            },
+            realtime: { emit: () => {}, refresh: () => {} },
+            retry: async (fn) => fn(),
+        }, { topic: "durable execution" });
+
+        expect(result.status).toBe("pending");
+        expect(result.name).toBe(name);
+        expect(result.scheduledJobId).toBe("job-start-1");
+        expect(scheduled).toEqual([
+            {
+                delayMs: 0,
+                action: getWorkflowResumeActionName(name),
+                args: { workflowId: result.id },
+            },
+        ]);
+
+        const rowResult = await db.execute(sql`
+            SELECT id, name, status, max_retries, user_id, args, realtime_token
+            FROM _gencow_workflows
+            WHERE id = ${result.id}
+        `);
+        const row = (rowResult as { rows: Array<{ id: string; name: string; status: string; max_retries: number; user_id: string | null; args: unknown; realtime_token: string }> }).rows[0];
+
+        expect(row.id).toBe(result.id);
+        expect(row.name).toBe(name);
+        expect(row.status).toBe("pending");
+        expect(row.max_retries).toBe(3);
+        expect(row.user_id).toBe("user_workflow_start");
+        expect(row.args).toEqual({ value: { topic: "durable execution" } });
+        expect(row.realtime_token.length).toBeGreaterThan(10);
+    });
+
+    it("scheduler enqueue failure rolls back the workflow row", async () => {
+        const name = `agents.workflowRollback${Date.now()}`;
+        const start = workflow(name, {
+            args: { topic: v.string() },
+            handler: async () => ({ ok: true }),
+        });
+
+        await expect(start.handler({
+            db,
+            unsafeDb: db,
+            auth: {
+                getUserIdentity: () => null,
+                requireAuth: () => {
+                    throw new Error("not used");
+                },
+            },
+            storage: {} as any,
+            scheduler: {
+                runAfter: () => {
+                    throw new Error("scheduler unavailable");
+                },
+                runAt: () => "unused",
+                cancel: () => false,
+                cron: () => {},
+                registerAction: () => {},
+                executeAction: async () => {},
+            },
+            realtime: { emit: () => {}, refresh: () => {} },
+            retry: async (fn) => fn(),
+        }, { topic: "should rollback" })).rejects.toThrow("scheduler unavailable");
+
+        const countResult = await db.execute(sql`
+            SELECT count(*)::int AS c
+            FROM _gencow_workflows
+            WHERE name = ${name}
+        `);
+        const count = (countResult as { rows: Array<{ c: number }> }).rows[0]?.c ?? 0;
+        expect(count).toBe(0);
+    });
+
+    it("workflows.get returns full snapshot for the owner and hides private workflows from others", async () => {
+        const getWorkflow = getQueryDef("workflows.get");
+        expect(getWorkflow).toBeDefined();
+
+        const workflowId = `wf_owned_${Date.now()}`;
+        await db.execute(sql`
+            INSERT INTO _gencow_workflows (
+                id,
+                name,
+                args,
+                status,
+                current_step,
+                result,
+                error,
+                retry_count,
+                max_retries,
+                max_duration_ms,
+                started_at,
+                updated_at,
+                completed_at,
+                user_id
+            )
+            VALUES (
+                ${workflowId},
+                'agents.report',
+                '{"value":{"topic":"market map"}}'::jsonb,
+                'running',
+                'analyze',
+                NULL,
+                NULL,
+                1,
+                3,
+                1800000,
+                NOW() - INTERVAL '2 minutes',
+                NOW() - INTERVAL '5 seconds',
+                NULL,
+                'owner_workflow'
+            )
+        `);
+        await db.execute(sql`
+            INSERT INTO _gencow_workflow_steps (
+                workflow_id,
+                step_name,
+                status,
+                output,
+                error,
+                started_at,
+                updated_at,
+                completed_at
+            )
+            VALUES
+                (
+                    ${workflowId},
+                    'search',
+                    'completed',
+                    '{"value":{"hits":2}}'::jsonb,
+                    NULL,
+                    NOW() - INTERVAL '90 seconds',
+                    NOW() - INTERVAL '80 seconds',
+                    NOW() - INTERVAL '80 seconds'
+                ),
+                (
+                    ${workflowId},
+                    'analyze',
+                    'running',
+                    NULL,
+                    NULL,
+                    NOW() - INTERVAL '10 seconds',
+                    NOW() - INTERVAL '5 seconds',
+                    NULL
+                )
+        `);
+
+        const ownerSnapshot = await getWorkflow!.handler(buildCtx("owner_workflow") as any, { id: workflowId });
+        expect(ownerSnapshot).toMatchObject({
+            id: workflowId,
+            name: "agents.report",
+            status: "running",
+            derivedStatus: "running",
+            currentStep: "analyze",
+            args: { topic: "market map" },
+            result: null,
+            retryCount: 1,
+            maxRetries: 3,
+        });
+        expect(ownerSnapshot?.realtimeKey).toMatch(new RegExp(`^__gencow\\.workflow\\.state\\.${workflowId}\\.`));
+        expect(ownerSnapshot?.steps).toHaveLength(2);
+        expect(ownerSnapshot?.steps[0]).toMatchObject({
+            name: "search",
+            status: "completed",
+            output: { hits: 2 },
+        });
+        expect(ownerSnapshot?.steps[1]).toMatchObject({
+            name: "analyze",
+            status: "running",
+            output: null,
+        });
+
+        const strangerSnapshot = await getWorkflow!.handler(buildCtx("stranger_workflow") as any, { id: workflowId });
+        expect(strangerSnapshot).toBeNull();
+    });
+
+    it("workflows.get allows ownerless public workflows to be polled without auth", async () => {
+        const getWorkflow = getQueryDef("workflows.get");
+        expect(getWorkflow).toBeDefined();
+
+        const workflowId = `wf_public_${Date.now()}`;
+        await db.execute(sql`
+            INSERT INTO _gencow_workflows (
+                id,
+                name,
+                args,
+                status,
+                current_step,
+                result,
+                error,
+                retry_count,
+                max_retries,
+                max_duration_ms,
+                started_at,
+                updated_at,
+                completed_at,
+                user_id
+            )
+            VALUES (
+                ${workflowId},
+                'agents.public',
+                '{"value":{"topic":"public"}}'::jsonb,
+                'completed',
+                NULL,
+                '{"value":{"report":"done"}}'::jsonb,
+                NULL,
+                0,
+                3,
+                1800000,
+                NOW() - INTERVAL '1 minute',
+                NOW() - INTERVAL '5 seconds',
+                NOW() - INTERVAL '5 seconds',
+                NULL
+            )
+        `);
+
+        const snapshot = await getWorkflow!.handler(buildCtx(null) as any, { id: workflowId });
+        expect(snapshot).toMatchObject({
+            id: workflowId,
+            status: "completed",
+            derivedStatus: "completed",
+            result: { report: "done" },
+            steps: [],
+        });
+        expect(snapshot?.realtimeKey).toMatch(new RegExp(`^__gencow\\.workflow\\.state\\.${workflowId}\\.`));
+    });
+
+    it("workflows.signal persists an event and wakes waiting workflows for the owner only", async () => {
+        const signalWorkflow = getRegisteredMutations().find((item) => item.name === "workflows.signal");
+        expect(signalWorkflow).toBeDefined();
+
+        const workflowId = `wf_signal_${Date.now()}`;
+        await db.execute(sql`
+            INSERT INTO _gencow_workflows (
+                id,
+                name,
+                args,
+                status,
+                current_step,
+                result,
+                error,
+                retry_count,
+                max_retries,
+                max_duration_ms,
+                started_at,
+                updated_at,
+                completed_at,
+                user_id
+            )
+            VALUES (
+                ${workflowId},
+                'agents.waiting',
+                '{}'::jsonb,
+                'pending',
+                'wait:approval#1',
+                NULL,
+                NULL,
+                0,
+                3,
+                1800000,
+                NOW() - INTERVAL '20 seconds',
+                NOW() - INTERVAL '5 seconds',
+                NULL,
+                'signal_owner'
+            )
+        `);
+
+        const scheduled: Array<{ delayMs: number; action: string; args: unknown }> = [];
+        const accepted = await signalWorkflow!.handler({
+            ...buildCtx("signal_owner"),
+            scheduler: {
+                runAfter: (delayMs, action, args) => {
+                    scheduled.push({ delayMs, action, args });
+                    return "job-signal-1";
+                },
+                runAt: () => "unused",
+                cancel: () => false,
+                cron: () => {},
+                registerAction: () => {},
+                executeAction: async () => {},
+            },
+        } as any, {
+            id: workflowId,
+            event: "approval",
+            payload: { approved: true },
+        });
+
+        expect(accepted).toEqual({
+            ok: true,
+            workflowId,
+            event: "approval",
+            scheduledJobId: "job-signal-1",
+        });
+        expect(scheduled).toEqual([
+            {
+                delayMs: 0,
+                action: getWorkflowResumeActionName("agents.waiting"),
+                args: { workflowId },
+            },
+        ]);
+
+        const eventResult = await db.execute(sql`
+            SELECT workflow_id, event_name, payload, consumed_at IS NULL AS is_unconsumed
+            FROM _gencow_workflow_events
+            WHERE workflow_id = ${workflowId}
+        `);
+        const eventRow = (eventResult as {
+            rows: Array<{
+                workflow_id: string;
+                event_name: string;
+                payload: unknown;
+                is_unconsumed: boolean;
+            }>;
+        }).rows[0];
+        expect(eventRow).toEqual({
+            workflow_id: workflowId,
+            event_name: "approval",
+            payload: { value: { approved: true } },
+            is_unconsumed: true,
+        });
+
+        const denied = await signalWorkflow!.handler(buildCtx("someone_else") as any, {
+            id: workflowId,
+            event: "approval",
+            payload: { approved: false },
+        });
+        expect(denied).toEqual({
+            ok: false,
+            workflowId,
+            event: "approval",
+            scheduledJobId: null,
+        });
+    });
+
+    it("workflows.list requires auth and filters to the current owner", async () => {
+        const listWorkflows = getQueryDef("workflows.list");
+        expect(listWorkflows).toBeDefined();
+
+        const userACompleted = `wf_user_a_completed_${Date.now()}`;
+        const userAWaiting = `wf_user_a_waiting_${Date.now()}`;
+        const userASleeping = `wf_user_a_sleeping_${Date.now()}`;
+        const userBRunning = `wf_user_b_running_${Date.now()}`;
+
+        await db.execute(sql`
+            INSERT INTO _gencow_workflows (
+                id,
+                name,
+                args,
+                status,
+                current_step,
+                result,
+                error,
+                retry_count,
+                max_retries,
+                max_duration_ms,
+                started_at,
+                updated_at,
+                completed_at,
+                user_id
+            )
+            VALUES
+                (
+                    ${userACompleted},
+                    'agents.sync',
+                    '{}'::jsonb,
+                    'completed',
+                    NULL,
+                    NULL,
+                    NULL,
+                    0,
+                    3,
+                    1800000,
+                    NOW() - INTERVAL '30 seconds',
+                    NOW() - INTERVAL '20 seconds',
+                    NOW() - INTERVAL '20 seconds',
+                    'workflow_user_a'
+                ),
+                (
+                    ${userAWaiting},
+                    'agents.sync',
+                    '{}'::jsonb,
+                    'pending',
+                    'wait:approval#1',
+                    NULL,
+                    NULL,
+                    0,
+                    3,
+                    1800000,
+                    NOW() - INTERVAL '10 seconds',
+                    NOW() - INTERVAL '10 seconds',
+                    NULL,
+                    'workflow_user_a'
+                ),
+                (
+                    ${userASleeping},
+                    'agents.sync',
+                    '{}'::jsonb,
+                    'pending',
+                    'sleep#1',
+                    NULL,
+                    NULL,
+                    0,
+                    3,
+                    1800000,
+                    NOW() - INTERVAL '15 seconds',
+                    NOW() - INTERVAL '12 seconds',
+                    NULL,
+                    'workflow_user_a'
+                ),
+                (
+                    ${userBRunning},
+                    'agents.sync',
+                    '{}'::jsonb,
+                    'running',
+                    'analyze',
+                    NULL,
+                    NULL,
+                    0,
+                    3,
+                    1800000,
+                    NOW() - INTERVAL '5 seconds',
+                    NOW() - INTERVAL '5 seconds',
+                    NULL,
+                    'workflow_user_b'
+                )
+        `);
+
+        const ownWorkflows = await listWorkflows!.handler(buildCtx("workflow_user_a") as any, { limit: 10 });
+        expect(ownWorkflows.map((item: any) => item.id)).toEqual([userAWaiting, userASleeping, userACompleted]);
+        expect(ownWorkflows.every((item: any) => item.name === "agents.sync")).toBe(true);
+        expect(ownWorkflows.some((item: any) => item.id === userBRunning)).toBe(false);
+        expect(ownWorkflows.find((item: any) => item.id === userAWaiting)?.derivedStatus).toBe("waiting");
+        expect(ownWorkflows.find((item: any) => item.id === userASleeping)?.derivedStatus).toBe("sleeping");
+
+        const completedOnly = await listWorkflows!.handler(
+            buildCtx("workflow_user_a") as any,
+            { limit: 10, status: "completed" }
+        );
+        expect(completedOnly).toHaveLength(1);
+        expect(completedOnly[0]?.id).toBe(userACompleted);
+
+        const waitingOnly = await listWorkflows!.handler(
+            buildCtx("workflow_user_a") as any,
+            { limit: 10, status: "waiting" }
+        );
+        expect(waitingOnly).toHaveLength(1);
+        expect(waitingOnly[0]?.id).toBe(userAWaiting);
+
+        const sleepingOnly = await listWorkflows!.handler(
+            buildCtx("workflow_user_a") as any,
+            { limit: 10, status: "sleeping" }
+        );
+        expect(sleepingOnly).toHaveLength(1);
+        expect(sleepingOnly[0]?.id).toBe(userASleeping);
+
+        await expect(
+            listWorkflows!.handler(buildCtx(null) as any, { limit: 10 })
+        ).rejects.toThrow("Authentication required");
+
+        await expect(
+            listWorkflows!.handler(buildCtx("workflow_user_a") as any, { limit: 10, status: "mystery" })
+        ).rejects.toThrow('Argument "status": expected one of pending, running, completed, failed');
+    });
+});

package/src/crud.ts

@@ -412,7 +412,7 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
     }
 
     // ── 내부 헬퍼: list+count 데이터 가져오기 (realtime push용 재사용) ──
-    // Runs inside db.transaction so createRlsDb() can SET LOCAL app.current_user_id for RLS.
+    // Runs inside db.transaction so createRlsDb() RLS session vars apply for RLS.
     // ⚠️ limit/offset 없이 전체 SELECT — 대량 데이터 시 성능 저하 주의
     // TODO(P2): realtime emit 시 invalidation 메시지만 전송하고 클라이언트가 re-fetch하는 패턴 검토
     async function fetchListWithTotal(db: any, whereClause?: SQL, userId?: string) {

package/src/index.ts

@@ -9,7 +9,11 @@ export type { GencowCtx, AuthCtx, UserIdentity, QueryDef, MutationDef, RealtimeC
 export { query, mutation, httpAction, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations, getRegisteredHttpActions } from "./reactive.js";
 export type { Storage } from "./storage.js";
 export { createScheduler, getSchedulerInfo } from "./scheduler.js";
-export type { Scheduler, ScheduleOptions, FailedJob } from "./scheduler.js";
+export type { Scheduler, ScheduleOptions, FailedJob, CreateSchedulerOptions, ScheduledJobRecord } from "./scheduler.js";
+export { workflow, getWorkflowDef, getRegisteredWorkflows, getWorkflowResumeActionName, getWorkflowRealtimeKey, createWorkflowRealtimeToken, serializeWorkflowValue, deserializeWorkflowValue, parseWorkflowDurationMs, DEFAULT_WORKFLOW_MAX_DURATION_MS, DEFAULT_WORKFLOW_MAX_RETRIES, WORKFLOW_RESUME_ACTION_PREFIX, WORKFLOW_REALTIME_KEY_PREFIX } from "./workflow.js";
+export { deriveWorkflowStatus } from "./workflow-types.js";
+export type { WorkflowCtx, WorkflowHandler, WorkflowOptions, WorkflowDef, WorkflowResumePayload, WorkflowStartResult, WorkflowSignalResult, WorkflowStatus, WorkflowDerivedStatus, WorkflowSummary, WorkflowSnapshot, WorkflowStepSnapshot, WorkflowListArgs, WorkflowDuration } from "./workflow-types.js";
+export { loadWorkflowSnapshot } from "./workflows-api.js";
 export { v, parseArgs, GencowValidationError } from "./v.js";
 export type { Validator, Infer, InferArgs } from "./v.js";
 export { withRetry } from "./retry.js";
@@ -23,10 +27,8 @@ export type { GencowAuthConfig, AuthEmailVerification } from "./auth-config.js";
 export { ownerRls, getOwnerRlsMeta, registerOwnerRls } from "./rls.js";
 export type { OwnerRlsMeta } from "./rls.js";
 export { createRlsDb } from "./rls-db.js";
+export type { RlsSessionContext } from "./rls-db.js";
 export { crud, parseFilterNode, applyFilterOp, getOwnerRlsTables } from "./crud.js";
 
 // Deprecated alias — 하위호환용, 향후 메이저 버전에서 제거 예정
 export { crud as gencowCrud } from "./crud.js";
-
-
-

package/src/reactive.ts

@@ -477,6 +477,14 @@ export function buildRealtimeCtx(options?: {
                 }
                 try {
                     // refresh용 ctx 생성 (mutation ctx와 동일한 DB/auth 스코프)
+                    if (!options?.buildCtxForRefresh) {
+                        console.warn(
+                            `[gencow] ⚠️  refresh("${key}"): buildCtxForRefresh not provided. ` +
+                            `Query handler will receive an empty ctx — ctx.db will be undefined. ` +
+                            `This is a framework configuration error. ` +
+                            `💡 Ensure buildRealtimeCtx() receives a buildCtxForRefresh callback.`
+                        );
+                    }
                     const refreshCtx = options?.buildCtxForRefresh?.() ?? ({} as GencowCtx);
                     const result = await queryDef.handler(refreshCtx, {});