@gaonjs/async 0.1.3 → 0.2.1

package/dist/work.js

@@ -0,0 +1,88 @@
+// @gaonjs/async · 워커 프로세스 런타임 (§7 M7 · line 863~885)
+//
+// `gaon work` 가 띄우는 운영 런타임. 도메인의 잡·리스너·스케줄·아웃박스를
+// 한 프로세스에 조립한다:
+//  - 잡 워커(runWorker)     — 큐 소비·재시도·DLQ
+//  - 리스너(runListeners)    — 이벤트 소비
+//  - 스케줄러(runScheduler)  — 리더 선출 단일 발행(선택)
+//  - 아웃박스 릴레이(runOutboxRelay) — DB→NATS 발행(DB 있을 때만)
+//
+// Graceful drain: stop() 이 전 구성요소를 순서대로 내린다 — 스케줄러(신규
+// 틱 중단·리더 반납) → 릴레이 → 리스너 → 워커(진행 잡 완료 대기). 워커·
+// 리스너가 진행 중 작업을 상한까지 기다리므로, 종료가 진행 잡을 자르지 않는다.
+import { configureJobs } from './jobs.js';
+import { configureEvents } from './events.js';
+import { runWorker } from './worker.js';
+import { runListeners } from './listeners.js';
+import { runScheduler } from './schedule.js';
+import { runOutboxRelay, ensureOutboxTable } from './outbox.js';
+import { registeredListeners } from './events.js';
+import { registeredJobs } from './jobs.js';
+/**
+ * 워커 런타임을 조립·기동한다. 호출 전에 도메인 파일(잡·리스너·스케줄)을
+ * import 해 레지스트리를 채워 두어야 한다(파일=등록).
+ */
+export async function runWork(opts) {
+    const emit = (e) => opts.onEvent?.(e);
+    // enqueue·emit 전송 배선(재시도 재적재·잡→잡·즉시 발행 경로).
+    configureJobs(opts.nats, opts.tuning);
+    configureEvents(opts.nats, opts.tuning);
+    const worker = await runWorker({
+        nats: opts.nats,
+        concurrency: opts.concurrency,
+        ackWaitMs: opts.ackWaitMs,
+        drainTimeoutMs: opts.drainTimeoutMs,
+        tuning: opts.tuning,
+        onEvent: (event) => emit({ kind: 'worker', event }),
+    });
+    const listeners = registeredListeners().length
+        ? await runListeners({
+            nats: opts.nats,
+            ackWaitMs: opts.ackWaitMs,
+            drainTimeoutMs: opts.drainTimeoutMs,
+            tuning: opts.tuning,
+            onEvent: (event) => emit({ kind: 'listener', event }),
+        })
+        : undefined;
+    let relay;
+    if (opts.db) {
+        await ensureOutboxTable(opts.db);
+        relay = runOutboxRelay(opts.db, {
+            pollMs: opts.relayPollMs,
+            onRelayed: (count) => emit({ kind: 'relay', count }),
+        });
+    }
+    let scheduler;
+    if (opts.schedule && opts.schedule.entries.length > 0) {
+        scheduler = await runScheduler({
+            nats: opts.nats,
+            def: opts.schedule,
+            id: opts.id,
+            onEvent: (event) => emit({ kind: 'scheduler', event }),
+        });
+    }
+    emit({
+        kind: 'ready',
+        jobs: registeredJobs().length,
+        listeners: registeredListeners().length,
+        scheduled: opts.schedule?.entries.length ?? 0,
+    });
+    let stopped = false;
+    return {
+        worker,
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            // 스케줄러 먼저 — 신규 틱 중단·리더 반납(다른 인스턴스가 즉시 승계).
+            if (scheduler)
+                await scheduler.stop();
+            if (relay)
+                await relay.stop();
+            // 리스너·워커는 진행 중 작업을 상한까지 기다린 뒤 내려간다.
+            if (listeners)
+                await listeners.stop();
+            await worker.stop();
+        },
+    };
+}

package/dist/worker.d.ts

@@ -0,0 +1,71 @@
+import type { GaonNats } from './nats.js';
+import { type StreamTuning } from './streams.js';
+/** DLQ 레코드(사람이 확인·재적재). */
+export interface DlqRecord {
+    readonly id: string;
+    readonly name: string;
+    readonly queue: string;
+    readonly args: readonly unknown[];
+    readonly attempts: number;
+    readonly error: string;
+    readonly failedAt: number;
+    readonly enqueuedAt: number;
+}
+export type WorkerEvent = {
+    readonly kind: 'processing';
+    readonly job: string;
+    readonly id: string;
+    readonly attempt: number;
+} | {
+    readonly kind: 'succeeded';
+    readonly job: string;
+    readonly id: string;
+} | {
+    readonly kind: 'retrying';
+    readonly job: string;
+    readonly id: string;
+    readonly attempt: number;
+    readonly delayMs: number;
+} | {
+    readonly kind: 'deferred';
+    readonly job: string;
+    readonly id: string;
+    readonly delayMs: number;
+} | {
+    readonly kind: 'dead';
+    readonly job: string;
+    readonly id: string;
+    readonly attempts: number;
+    readonly error: string;
+} | {
+    readonly kind: 'skipped';
+    readonly name: string;
+    readonly id: string;
+} | {
+    readonly kind: 'error';
+    readonly error: string;
+};
+export interface WorkerOptions {
+    readonly nats: GaonNats;
+    /** 큐별 기본 동시성. 잡 옵션의 concurrency 가 우선. 기본 1. */
+    readonly concurrency?: number;
+    /** ack 대기(ms) — 이 시간 안에 ack/nak 없으면 크래시로 보고 재전달. 기본 30000. */
+    readonly ackWaitMs?: number;
+    /** graceful drain 상한(ms). 기본 30000. */
+    readonly drainTimeoutMs?: number;
+    /** 스트림 튜닝(중복 창 등). */
+    readonly tuning?: StreamTuning;
+    /** 진행 이벤트 통지(로깅·테스트). */
+    onEvent?(e: WorkerEvent): void;
+}
+export interface WorkerHandle {
+    /** graceful drain: 신규 pull 중단 → 진행 잡 완료 대기 → 종료. */
+    stop(): Promise<void>;
+    /** 현재 처리 중(in-flight) 잡 수. */
+    readonly inflight: number;
+}
+/**
+ * 워커를 시작한다. registeredQueues() 의 각 큐에 컨슈머를 붙인다 —
+ * 호출 전에 잡 파일을 import 해 레지스트리를 채워 두어야 한다.
+ */
+export declare function runWorker(opts: WorkerOptions): Promise<WorkerHandle>;

package/dist/worker.js

@@ -0,0 +1,176 @@
+// @gaonjs/async · 잡 워커 (§7 M7 · line 858~886)
+//
+// `gaon work` 프로세스의 심장. 등록된 잡의 큐마다 JetStream pull 컨슈머를
+// 만들어 메시지를 당겨 처리한다. 처리 규칙:
+//  - notBefore 미도래(지연·백오프 대기) → nak(남은 시간)로 정확히 그 시각에
+//    재전달되게 미룬다(§7 line 792 "NAK 지연 기반").
+//  - 성공 → ack(워크큐 보존이라 삭제된다).
+//  - 실패 & 재시도 여분 있음 → attempt+1·notBefore=now+백오프 로 재적재 후 ack.
+//  - 실패 & 재시도 소진 → DLQ 로 옮기고 term(더 재전달 안 함).
+//  - 파싱 불가(포이즌) → 즉시 term.
+//
+// JetStream 의 네이티브 재전달(ack_wait·max_deliver)은 정상 재시도가 아니라
+// **크래시 복구**용이다: 워커가 잡을 붙든 채 죽으면 ack_wait 만료로 스트림에
+// 되돌아가 다른 워커가 다시 처리한다(at-least-once — 잡은 멱등 권장).
+//
+// Graceful drain(§7 line 885): 종료 시그널 → 신규 pull 중단 → 진행 잡 완료
+// 대기(timeout) → 종료. 미완료 잡은 ack 타임아웃으로 스트림에 남는다.
+import { jetstreamManager } from '@nats-io/jetstream';
+import { JOBS_STREAM, DLQ_SUBJECT, jobConsumerName, jobSubject, toNanos, ensureJobsStream, ensureDlqStream, } from './streams.js';
+import { encodePayloadBytes, decodePayloadBytes } from './codec.js';
+import { backoffDelayMs } from './backoff.js';
+import { configureJobs, getJob, registeredQueues, registeredJobs, enqueueRaw, DEFAULT_QUEUE, } from './jobs.js';
+const DEFAULT_ACK_WAIT_MS = 30000;
+const DEFAULT_DRAIN_MS = 30000;
+/**
+ * 워커를 시작한다. registeredQueues() 의 각 큐에 컨슈머를 붙인다 —
+ * 호출 전에 잡 파일을 import 해 레지스트리를 채워 두어야 한다.
+ */
+export async function runWorker(opts) {
+    const ackWaitMs = opts.ackWaitMs ?? DEFAULT_ACK_WAIT_MS;
+    const drainTimeoutMs = opts.drainTimeoutMs ?? DEFAULT_DRAIN_MS;
+    const emit = (e) => opts.onEvent?.(e);
+    // enqueue 전송도 워커에서 필요하다(재시도 재적재·잡→잡 큐잉).
+    configureJobs(opts.nats, opts.tuning);
+    await ensureJobsStream(opts.nats, opts.tuning);
+    await ensureDlqStream(opts.nats, opts.tuning);
+    const jsm = await jetstreamManager(opts.nats.nc);
+    const toDlq = async (rec) => {
+        await opts.nats.js.publish(DLQ_SUBJECT, encodePayloadBytes(rec), { msgID: `${rec.id}#dead` });
+    };
+    // 한 메시지 처리: notBefore·성공·재시도·DLQ 규칙을 적용한다.
+    const handleMessage = async (m) => {
+        let msg;
+        try {
+            msg = decodePayloadBytes(m.data);
+        }
+        catch {
+            // 포이즌(파싱 불가) — 무한 재전달을 막으려 즉시 폐기한다.
+            emit({ kind: 'skipped', name: '(unparseable)', id: '?' });
+            m.term();
+            return;
+        }
+        const now = Date.now();
+        if (now < msg.notBefore) {
+            // 아직 실행 시각 전 — 남은 시간만큼 정확히 미룬다(지연·백오프).
+            const delayMs = msg.notBefore - now;
+            emit({ kind: 'deferred', job: msg.name, id: msg.id, delayMs });
+            m.nak(delayMs);
+            return;
+        }
+        const def = getJob(msg.name);
+        if (!def) {
+            // 이 워커에 해당 잡이 등록돼 있지 않다 — 다른 워커 몫일 수 있으니
+            // 잠시 뒤 재전달되게 미룬다(포이즌 취급하지 않는다).
+            emit({ kind: 'skipped', name: msg.name, id: msg.id });
+            m.nak(1000);
+            return;
+        }
+        const attempt = msg.attempt + 1;
+        const maxAttempts = 1 + (def.options.retries ?? 3);
+        emit({ kind: 'processing', job: msg.name, id: msg.id, attempt });
+        // 긴 잡이 ack_wait 를 넘겨 조기 재전달되지 않게 주기적으로 working() 을
+        // 보내 리스를 연장한다.
+        const heartbeat = setInterval(() => {
+            try {
+                m.working();
+            }
+            catch {
+                // 이미 ack/term 된 뒤면 무시.
+            }
+        }, Math.max(1000, Math.floor(ackWaitMs / 2)));
+        try {
+            const run = def.handler;
+            await run(...msg.args);
+            clearInterval(heartbeat);
+            m.ack();
+            emit({ kind: 'succeeded', job: msg.name, id: msg.id });
+        }
+        catch (err) {
+            clearInterval(heartbeat);
+            const error = err instanceof Error ? err.message : String(err);
+            if (attempt < maxAttempts) {
+                const delayMs = backoffDelayMs(attempt, def.options);
+                // attempt·notBefore 를 올려 재적재하고 현재 메시지는 ack 로 치운다.
+                await enqueueRaw({ ...msg, attempt, notBefore: Date.now() + delayMs });
+                m.ack();
+                emit({ kind: 'retrying', job: msg.name, id: msg.id, attempt, delayMs });
+            }
+            else {
+                await toDlq({
+                    id: msg.id,
+                    name: msg.name,
+                    queue: msg.queue,
+                    args: msg.args,
+                    attempts: attempt,
+                    error,
+                    failedAt: Date.now(),
+                    enqueuedAt: msg.enqueuedAt,
+                });
+                m.term();
+                emit({ kind: 'dead', job: msg.name, id: msg.id, attempts: attempt, error });
+            }
+        }
+    };
+    // 큐마다 컨슈머를 붙이고 동시성 제한 소비 루프를 돈다.
+    const queues = registeredQueues();
+    if (queues.length === 0)
+        queues.push(DEFAULT_QUEUE);
+    const closers = [];
+    const inflightAll = new Set();
+    for (const queue of queues) {
+        const durable = jobConsumerName(queue);
+        // 큐 동시성: 이 큐에 속한 잡 중 최댓값(없으면 워커 기본).
+        const declared = registeredJobs()
+            .filter((d) => d.queue === queue)
+            .map((d) => d.options.concurrency ?? 0);
+        const perQueueConc = Math.max(0, ...declared) || (opts.concurrency ?? 1);
+        await jsm.consumers.add(JOBS_STREAM, {
+            durable_name: durable,
+            filter_subject: jobSubject(queue),
+            ack_policy: 'explicit',
+            ack_wait: toNanos(ackWaitMs),
+            // 정상 재시도는 우리가 재적재로 처리한다. 네이티브 재전달은 크래시
+            // 복구용이라 상한만 둔다(포이즌 크래시 루프 방지).
+            max_deliver: 25,
+            max_ack_pending: 1000,
+        });
+        const consumer = await opts.nats.js.consumers.get(JOBS_STREAM, durable);
+        const messages = await consumer.consume({ max_messages: perQueueConc });
+        const loop = (async () => {
+            for await (const m of messages) {
+                const p = handleMessage(m).finally(() => inflightAll.delete(p));
+                inflightAll.add(p);
+                if (inflightAll.size >= perQueueConc)
+                    await Promise.race(inflightAll);
+            }
+        })();
+        closers.push(async () => {
+            // 신규 pull 중단(진행 중인 in-flight 는 아래에서 대기).
+            messages.stop();
+            await loop.catch(() => { });
+        });
+    }
+    let stopped = false;
+    return {
+        get inflight() {
+            return inflightAll.size;
+        },
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            // 1) 신규 pull 중단.
+            for (const close of closers)
+                await close();
+            // 2) 진행 잡 완료 대기(상한). 남으면 ack_wait 로 스트림에 되돌아간다.
+            const deadline = Date.now() + drainTimeoutMs;
+            while (inflightAll.size > 0 && Date.now() < deadline) {
+                await Promise.race([...inflightAll, delay(200)]);
+            }
+        },
+    };
+}
+function delay(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/async",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Gaon NATS 통합: 잡·이벤트·스케줄러·채널(ws)·허브(프레즌스) (구현 예정)",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,10 @@
     "README.md"
   ],
   "dependencies": {
+    "@nats-io/transport-node": "^3.1.0",
+    "@nats-io/jetstream": "^3.1.0",
+    "@nats-io/kv": "^3.1.0",
+    "kysely": "^0.29.4",
     "@gaonjs/core": "0.1.3"
   },
   "scripts": {