@gencow/core 0.1.22 → 0.1.23

package/src/__tests__/scheduler-durable-v2.test.ts

@@ -0,0 +1,270 @@
+/**
+ * packages/core/src/__tests__/scheduler-durable-v2.test.ts
+ *
+ * Scheduler Durable v2 테스트 — Platform DB 중앙화 구현 검증.
+ *
+ * DB/HTTP 의존 없이 검증 가능한 핵심 로직:
+ * - persistJob에 올바른 필드가 전달되는지
+ * - args가 persistJob 콜백까지 정확히 전달되는지
+ * - 다수의 job 동시 등록 시 id 충돌 없음
+ * - removeJob 실패 시 graceful 처리
+ * - runAfter(0) 즉시 실행 케이스
+ * - 대형 args 직렬화 안정성
+ *
+ * Run: bun test packages/core/src/__tests__/scheduler-durable-v2.test.ts
+ */
+
+import { describe, it, expect } from "bun:test";
+import { createScheduler } from "../scheduler";
+import type { ScheduledJobRecord } from "../scheduler";
+
+describe("Scheduler Durable v2 — Platform DB 중앙화", () => {
+    // ── args 전달 정확성 ──
+
+    it("persistJob에 args가 정확히 전달된다 (중첩 객체)", async () => {
+        const persisted: ScheduledJobRecord[] = [];
+
+        const scheduler = createScheduler({
+            persistJob: async (job) => { persisted.push(job); },
+            removeJob: async () => true,
+        });
+
+        scheduler.registerAction("deep.args", async () => {});
+
+        const complexArgs = {
+            nested: { deeply: { value: 42 } },
+            array: [1, 2, { x: "y" }],
+            unicode: "한글테스트 🎯",
+            nullValue: null,
+            boolValue: false,
+            zero: 0,
+            emptyString: "",
+        };
+
+        scheduler.runAfter(1000, "deep.args", complexArgs);
+        await new Promise((r) => setTimeout(r, 50));
+
+        expect(persisted.length).toBe(1);
+        expect(persisted[0].args).toEqual(complexArgs);
+    });
+
+    it("persistJob에 args 미전달 시 undefined로 전달", async () => {
+        const persisted: ScheduledJobRecord[] = [];
+
+        const scheduler = createScheduler({
+            persistJob: async (job) => { persisted.push(job); },
+            removeJob: async () => true,
+        });
+
+        scheduler.registerAction("no.args", async () => {});
+        scheduler.runAfter(1000, "no.args"); // args 생략
+
+        await new Promise((r) => setTimeout(r, 50));
+
+        expect(persisted.length).toBe(1);
+        // args는 undefined 또는 빈 값이어야 함 (Platform에서 {} default 처리)
+        expect(persisted[0].args === undefined || persisted[0].args === null || JSON.stringify(persisted[0].args) === "{}").toBe(true);
+    });
+
+    // ── 동시 등록 id 고유성 ──
+
+    it("10개 job 동시 등록 시 모든 id가 고유하다", async () => {
+        const persisted: ScheduledJobRecord[] = [];
+
+        const scheduler = createScheduler({
+            persistJob: async (job) => { persisted.push(job); },
+            removeJob: async () => true,
+        });
+
+        for (let i = 0; i < 10; i++) {
+            scheduler.registerAction(`batch.${i}`, async () => {});
+        }
+
+        const ids: string[] = [];
+        for (let i = 0; i < 10; i++) {
+            ids.push(scheduler.runAfter(1000, `batch.${i}`, { idx: i }));
+        }
+
+        await new Promise((r) => setTimeout(r, 100));
+
+        // 모든 id 고유
+        const uniqueIds = new Set(ids);
+        expect(uniqueIds.size).toBe(10);
+
+        // 모든 persistJob 호출됨
+        expect(persisted.length).toBe(10);
+    });
+
+    // ── runAfter(0) — 즉시 실행 ──
+
+    it("runAfter(0) — durable mode에서도 즉시 persistJob 호출", async () => {
+        const persisted: ScheduledJobRecord[] = [];
+
+        const scheduler = createScheduler({
+            persistJob: async (job) => { persisted.push(job); },
+            removeJob: async () => true,
+        });
+
+        scheduler.registerAction("instant", async () => {});
+
+        const beforeTime = Date.now();
+        scheduler.runAfter(0, "instant", { immediate: true });
+
+        await new Promise((r) => setTimeout(r, 50));
+
+        expect(persisted.length).toBe(1);
+        expect(persisted[0].args).toEqual({ immediate: true });
+        // runAt은 현재 시간과 거의 동일해야 함 (±2초 오차 허용)
+        expect(Math.abs(persisted[0].runAt.getTime() - beforeTime)).toBeLessThan(2000);
+    });
+
+    // ── removeJob 실패 시 graceful 처리 ──
+
+    it("removeJob 실패 시 cancel()이 false 반환 (throw 안 함)", async () => {
+        const scheduler = createScheduler({
+            persistJob: async () => {},
+            removeJob: async () => {
+                throw new Error("DB connection lost");
+            },
+        });
+
+        scheduler.registerAction("fail.cancel", async () => {});
+        const id = scheduler.runAfter(10000, "fail.cancel");
+
+        await new Promise((r) => setTimeout(r, 50));
+
+        // suppress expected error
+        const orig = console.error;
+        console.error = () => {};
+        const result = scheduler.cancel(id);
+        console.error = orig;
+
+        // removeJob 실패 시 return false, throw 안 함
+        expect(typeof result).toBe("boolean");
+    });
+
+    // ── 대형 args 안정성 ──
+
+    it("대형 args (10KB) 직렬화 안정성", async () => {
+        const persisted: ScheduledJobRecord[] = [];
+
+        const scheduler = createScheduler({
+            persistJob: async (job) => { persisted.push(job); },
+            removeJob: async () => true,
+        });
+
+        scheduler.registerAction("large.payload", async () => {});
+
+        // ~10KB args
+        const largeArgs = {
+            data: "x".repeat(10_000),
+            items: Array.from({ length: 100 }, (_, i) => ({ id: i, name: `item-${i}` })),
+        };
+
+        scheduler.runAfter(1000, "large.payload", largeArgs);
+        await new Promise((r) => setTimeout(r, 50));
+
+        expect(persisted.length).toBe(1);
+        expect((persisted[0].args as any).data.length).toBe(10_000);
+        expect((persisted[0].args as any).items.length).toBe(100);
+    });
+
+    // ── onError + args 조합 ──
+
+    it("onError와 args가 함께 persistJob에 전달된다", async () => {
+        const persisted: ScheduledJobRecord[] = [];
+
+        const scheduler = createScheduler({
+            persistJob: async (job) => { persisted.push(job); },
+            removeJob: async () => true,
+        });
+
+        scheduler.registerAction("pipeline.step1", async () => {});
+        scheduler.registerAction("pipeline.onError", async () => {});
+
+        scheduler.runAfter(5000, "pipeline.step1", { step: 1, data: "test" }, { onError: "pipeline.onError" });
+
+        await new Promise((r) => setTimeout(r, 50));
+
+        expect(persisted.length).toBe(1);
+        expect(persisted[0].action).toBe("pipeline.step1");
+        expect(persisted[0].args).toEqual({ step: 1, data: "test" });
+        expect(persisted[0].onErrorAction).toBe("pipeline.onError");
+    });
+
+    // ── runAt + durable 조합 ──
+
+    it("runAt(과거 시점) — durable mode에서도 persistJob 호출 (즉시 실행 대상)", async () => {
+        const persisted: ScheduledJobRecord[] = [];
+
+        const scheduler = createScheduler({
+            persistJob: async (job) => { persisted.push(job); },
+            removeJob: async () => true,
+        });
+
+        scheduler.registerAction("past.task", async () => {});
+
+        const pastTime = new Date(Date.now() - 60_000); // 1분 전
+        scheduler.runAt(pastTime, "past.task", { expired: true });
+
+        await new Promise((r) => setTimeout(r, 50));
+
+        expect(persisted.length).toBe(1);
+        expect(persisted[0].args).toEqual({ expired: true });
+        // runAt이 과거여도 persistJob은 호출되어야 함 (폴러가 즉시 픽업)
+    });
+
+    // ── 다중 cancel ──
+
+    it("같은 job을 2번 cancel — 첫 번째만 removeJob 성공", async () => {
+        let removeCount = 0;
+
+        const scheduler = createScheduler({
+            persistJob: async () => {},
+            removeJob: async () => {
+                removeCount++;
+                return removeCount === 1; // 첫 번째만 true
+            },
+        });
+
+        scheduler.registerAction("double.cancel", async () => {});
+        const id = scheduler.runAfter(10000, "double.cancel");
+
+        await new Promise((r) => setTimeout(r, 50));
+
+        const r1 = scheduler.cancel(id);
+        await new Promise((r) => setTimeout(r, 20));
+        const r2 = scheduler.cancel(id);
+
+        // 첫 번째 cancel은 성공 (pendingJobs에서 제거)
+        expect(r1).toBe(true);
+        // 두 번째 cancel은 이미 제거되었으므로 false
+        expect(r2).toBe(false);
+    });
+
+    // ── persistJob 순서 보장 ──
+
+    it("연속 runAfter 호출 시 persistJob 순서 보장", async () => {
+        const order: string[] = [];
+
+        const scheduler = createScheduler({
+            persistJob: async (job) => {
+                order.push(job.action);
+            },
+            removeJob: async () => true,
+        });
+
+        scheduler.registerAction("a", async () => {});
+        scheduler.registerAction("b", async () => {});
+        scheduler.registerAction("c", async () => {});
+
+        scheduler.runAfter(1000, "a");
+        scheduler.runAfter(2000, "b");
+        scheduler.runAfter(3000, "c");
+
+        await new Promise((r) => setTimeout(r, 100));
+
+        // persistJob은 호출 순서대로 실행되어야 함
+        expect(order).toEqual(["a", "b", "c"]);
+    });
+});

package/src/__tests__/scheduler-durable.test.ts

@@ -0,0 +1,173 @@
+/**
+ * packages/core/src/__tests__/scheduler-durable.test.ts
+ *
+ * Scheduler Durable Mode 테스트 — createScheduler({ persistJob, removeJob })
+ * DB 콜백이 제공되면 runAfter()가 setTimeout 대신 persistJob을 호출하고,
+ * cancel()이 removeJob을 호출하는지 검증.
+ *
+ * Run: bun test packages/core/src/__tests__/scheduler-durable.test.ts
+ */
+
+import { describe, it, expect } from "bun:test";
+import { createScheduler } from "../scheduler";
+import type { ScheduledJobRecord } from "../scheduler";
+
+describe("Scheduler Durable Mode — persistJob/removeJob", () => {
+    it("durable mode에서 runAfter → persistJob 콜백 호출", async () => {
+        const persisted: ScheduledJobRecord[] = [];
+
+        const scheduler = createScheduler({
+            persistJob: async (job) => {
+                persisted.push(job);
+            },
+            removeJob: async () => true,
+        });
+
+        scheduler.registerAction("test.durable", async () => {});
+        const id = scheduler.runAfter(5000, "test.durable", { key: "value" });
+
+        // persistJob은 비동기이므로 약간 대기
+        await new Promise((r) => setTimeout(r, 50));
+
+        expect(persisted.length).toBe(1);
+        expect(persisted[0].id).toBe(id);
+        expect(persisted[0].action).toBe("test.durable");
+        expect(persisted[0].args).toEqual({ key: "value" });
+        expect(persisted[0].runAt).toBeInstanceOf(Date);
+        expect(persisted[0].runAt.getTime()).toBeGreaterThan(Date.now() + 4000); // ~5초 후
+    });
+
+    it("durable mode에서 runAfter → setTimeout 실행 안 함 (외부 폴러에 위임)", async () => {
+        let actionExecuted = false;
+
+        const scheduler = createScheduler({
+            persistJob: async () => {},
+            removeJob: async () => true,
+        });
+
+        scheduler.registerAction("no.exec", async () => {
+            actionExecuted = true;
+        });
+
+        scheduler.runAfter(50, "no.exec");
+
+        // 100ms 대기 — durable mode에서는 action이 실행되지 않아야 함
+        await new Promise((r) => setTimeout(r, 150));
+
+        expect(actionExecuted).toBe(false);
+    });
+
+    it("durable mode에서 cancel → removeJob 콜백 호출", async () => {
+        const removed: string[] = [];
+
+        const scheduler = createScheduler({
+            persistJob: async () => {},
+            removeJob: async (jobId) => {
+                removed.push(jobId);
+                return true;
+            },
+        });
+
+        scheduler.registerAction("noop", async () => {});
+        const id = scheduler.runAfter(10000, "noop");
+
+        // persistJob 완료 대기
+        await new Promise((r) => setTimeout(r, 50));
+
+        scheduler.cancel(id);
+
+        // removeJob은 비동기이므로 대기
+        await new Promise((r) => setTimeout(r, 50));
+
+        expect(removed.length).toBeGreaterThanOrEqual(1);
+        expect(removed).toContain(id);
+    });
+
+    it("durable mode에서 onError action 이름이 persistJob에 전달", async () => {
+        const persisted: ScheduledJobRecord[] = [];
+
+        const scheduler = createScheduler({
+            persistJob: async (job) => {
+                persisted.push(job);
+            },
+            removeJob: async () => true,
+        });
+
+        scheduler.registerAction("step1", async () => {});
+        scheduler.registerAction("onFail", async () => {});
+
+        scheduler.runAfter(1000, "step1", {}, { onError: "onFail" });
+
+        await new Promise((r) => setTimeout(r, 50));
+
+        expect(persisted.length).toBe(1);
+        expect(persisted[0].onErrorAction).toBe("onFail");
+    });
+
+    it("persistJob 실패 시 인메모리 fallback으로 실행", async () => {
+        let actionExecuted = false;
+
+        const scheduler = createScheduler({
+            persistJob: async () => {
+                throw new Error("DB connection failed");
+            },
+            removeJob: async () => true,
+        });
+
+        scheduler.registerAction("fallback.test", async () => {
+            actionExecuted = true;
+        });
+
+        // suppress expected error log
+        const origError = console.error;
+        console.error = () => {};
+
+        scheduler.runAfter(50, "fallback.test");
+
+        // persistJob 실패 → fallback → setTimeout(50ms) → 실행
+        await new Promise((r) => setTimeout(r, 300));
+
+        console.error = origError;
+
+        expect(actionExecuted).toBe(true);
+    });
+
+    it("콜백 미설정 시 기존 인메모리 mode 유지", async () => {
+        let executed = false;
+
+        const scheduler = createScheduler(); // no options
+
+        scheduler.registerAction("mem.test", async () => {
+            executed = true;
+        });
+
+        scheduler.runAfter(50, "mem.test");
+
+        await new Promise((r) => setTimeout(r, 150));
+
+        expect(executed).toBe(true);
+    });
+
+    it("runAt도 durable mode에서 persistJob 호출", async () => {
+        const persisted: ScheduledJobRecord[] = [];
+
+        const scheduler = createScheduler({
+            persistJob: async (job) => {
+                persisted.push(job);
+            },
+            removeJob: async () => true,
+        });
+
+        scheduler.registerAction("future.task", async () => {});
+
+        const futureTime = new Date(Date.now() + 60_000); // 1분 후
+        scheduler.runAt(futureTime, "future.task", { x: 1 });
+
+        await new Promise((r) => setTimeout(r, 50));
+
+        expect(persisted.length).toBe(1);
+        expect(persisted[0].action).toBe("future.task");
+        // runAt → runAfter 변환이므로 runAt 시간과 근사해야 함
+        expect(Math.abs(persisted[0].runAt.getTime() - futureTime.getTime())).toBeLessThan(1000);
+    });
+});

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,7 @@ 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 { v, parseArgs, GencowValidationError } from "./v.js";
 export type { Validator, Infer, InferArgs } from "./v.js";
 export { withRetry } from "./retry.js";
@@ -23,6 +23,7 @@ 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 — 하위호환용, 향후 메이저 버전에서 제거 예정

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, {});