mega-framework 0.1.10 → 0.1.13

package/types/core/lock/index.d.ts

@@ -0,0 +1,96 @@
+/** 활성 락 manager 설정(boot lock 스테이지). null 로 해제(셧다운/테스트). @param {LockManager | null} manager @returns {void} */
+export function setLockManager(manager: LockManager | null): void;
+/** 현재 활성 락 manager(없으면 null — `ctx.lock.with` 미부착). @returns {LockManager | null} */
+export function getLockManager(): LockManager | null;
+/**
+ * 분산 락 manager 를 만든다 — driver 자동 폴백 포함. boot 가 1회 호출해 `ctx.lock` 에 부착한다.
+ *
+ * @param {{ driver?: string, ttl?: number, waitMs?: number, fifo?: boolean, cache?: string }} [lockConfig] -
+ *   config 의 `lock` 섹션. `cache` 는 redis driver 가 빌릴 cache 어댑터 alias(redis/auto 일 때 의미).
+ * @param {{ logger?: any, redisClient?: any, isClusterWorker?: boolean }} [deps] -
+ *   - `redisClient` boot 가 cache 어댑터에서 빌려 넘긴 ioredis 클라이언트(없으면 null).
+ *   - `isClusterWorker` 현재 프로세스가 cluster 워커인지(`cluster.isWorker`).
+ * @returns {LockManager}
+ */
+export function createLockManager(lockConfig?: {
+    driver?: string;
+    ttl?: number;
+    waitMs?: number;
+    fifo?: boolean;
+    cache?: string;
+}, deps?: {
+    logger?: any;
+    redisClient?: any;
+    isClusterWorker?: boolean;
+}): LockManager;
+/**
+ * `ctx.lock` 콜러블에 사용자 API 메서드를 얹는다 — `ctx.lock(alias)`(기존)와 `ctx.lock.with(...)`(신규) 공존.
+ * boot 가 manager 생성 후 각 앱의 lock accessor 에 1회 호출한다.
+ *
+ * @param {Function & Record<string, any>} lockAccessor - `(alias) => MegaLockAdapter` 콜러블(ctx-builder 산출).
+ * @param {LockManager} manager
+ * @returns {Function & Record<string, any>} 같은 accessor(체이닝용).
+ */
+export function attachLockApi(lockAccessor: Function & Record<string, any>, manager: LockManager): Function & Record<string, any>;
+/**
+ * 사용자 분산 락 API. driver 한 개를 감싸 `with/acquire/tryAcquire/forceRelease/stats` 를 제공한다.
+ */
+export class LockManager {
+    /**
+     * @param {import('./contract.js').LockDriver} driver - 선택된 저수준 driver.
+     * @param {{ defaults: { ttl: number, waitMs: number, fifo: boolean }, logger?: any }} opts
+     */
+    constructor(driver: import("./contract.js").LockDriver, { defaults, logger }: {
+        defaults: {
+            ttl: number;
+            waitMs: number;
+            fifo: boolean;
+        };
+        logger?: any;
+    });
+    /** @returns {string} 활성 driver 이름('redis'|'cluster'|'memory'). */
+    get driverName(): string;
+    /**
+     * 락 획득(대기 후 실패 시 throw) — `try/finally` 로 직접 release 하는 용도.
+     * @param {string} key - 자원 키(비어있지 않은 공백 없는 문자열).
+     * @param {import('./contract.js').LockOpts} [opts] - ttl/waitMs/fifo/fence/extendable.
+     * @returns {Promise<import('./contract.js').LockHandle>}
+     * @throws {MegaConflictError} `lock.not_acquired` - waitMs 안에 못 잡음(자원이 잠겨있음 — 409).
+     * @throws {MegaValidationError} key/opts 부적합.
+     */
+    acquire(key: string, opts?: import("./contract.js").LockOpts): Promise<import("./contract.js").LockHandle>;
+    /**
+     * 락을 즉시 1회만 시도(대기 없음) — 못 잡으면 null(throw 아님).
+     * @param {string} key @param {import('./contract.js').LockOpts} [opts]
+     * @returns {Promise<import('./contract.js').LockHandle | null>}
+     */
+    tryAcquire(key: string, opts?: import("./contract.js").LockOpts): Promise<import("./contract.js").LockHandle | null>;
+    /**
+     * 락 보호 임계구역 실행 — 획득 → fn 실행 → **반드시 해제**(성공/예외 무관). 가장 권장되는 사용법.
+     * @template T
+     * @param {string} key
+     * @param {import('./contract.js').LockOpts | ((lock: import('./contract.js').LockHandle) => Promise<T> | T)} optsOrFn -
+     *   옵션, 또는 옵션을 생략하고 바로 fn(2-인자 형태 `with(key, fn)`).
+     * @param {(lock: import('./contract.js').LockHandle) => Promise<T> | T} [maybeFn] - 3-인자 형태의 fn.
+     * @returns {Promise<T>} fn 의 반환값.
+     */
+    with<T>(key: string, optsOrFn: import("./contract.js").LockOpts | ((lock: import("./contract.js").LockHandle) => Promise<T> | T), maybeFn?: (lock: import("./contract.js").LockHandle) => Promise<T> | T): Promise<T>;
+    /**
+     * 관리용 강제 해제(토큰 무관) — 운영 개입(고아 락 정리)용. 주의: 정상 보유자의 임계구역을 깰 수 있다.
+     * @param {string} key @returns {Promise<void>}
+     */
+    forceRelease(key: string): Promise<void>;
+    /** @returns {Promise<{ driver: string, active: number, waiting: number }>} 현재 보유/대기 수. */
+    stats(): Promise<{
+        driver: string;
+        active: number;
+        waiting: number;
+    }>;
+    /** 정리 — driver 자원(타이머·구독·IPC) 해제. graceful shutdown 에서 호출. @returns {Promise<void>} */
+    close(): Promise<void>;
+    #private;
+}
+import { MemoryLockDriver } from './memory-lock.js';
+import { ClusterLockDriver } from './cluster-lock.js';
+import { RedisLockDriver } from './redis-lock.js';
+export { MemoryLockDriver, ClusterLockDriver, RedisLockDriver };

package/types/core/lock/memory-lock.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @typedef {Object} HeldLock - 보유 중 락 레코드.
+ * @property {string} token @property {number} expiresAt @property {ReturnType<typeof setTimeout>} timer @property {number} [fence]
+ */
+/**
+ * @typedef {Object} Waiter - 대기 큐 항목.
+ * @property {number} ttl @property {boolean} fence @property {(lock: import('./contract.js').DriverLock | null) => void} resolve
+ * @property {ReturnType<typeof setTimeout> | null} timer
+ */
+export class MemoryLockDriver {
+    /** @type {'memory'} */
+    get name(): "memory";
+    /**
+     * 락 획득 — 즉시 가능하면 grant, 아니면 waitMs 안에서 FIFO 큐 대기.
+     * @param {string} key @param {import('./contract.js').NormalizedLockOpts} opts
+     * @returns {Promise<import('./contract.js').DriverLock | null>}
+     */
+    acquire(key: string, { ttl, waitMs, fence }: import("./contract.js").NormalizedLockOpts): Promise<import("./contract.js").DriverLock | null>;
+    /**
+     * 락 해제 — 토큰이 현재 보유자일 때만. 해제 후 다음 대기자 승계.
+     * @param {string} key @param {string} token @returns {Promise<boolean>}
+     */
+    release(key: string, token: string): Promise<boolean>;
+    /**
+     * TTL 연장 — 토큰이 보유자일 때만 만료 타이머 재설정.
+     * @param {string} key @param {string} token @param {number} ttl @returns {Promise<boolean>}
+     */
+    extend(key: string, token: string, ttl: number): Promise<boolean>;
+    /** 강제 해제(관리용, 토큰 무관) — 보유 비우고 다음 대기자 승계. @param {string} key @returns {Promise<void>} */
+    forceRelease(key: string): Promise<void>;
+    /** @returns {Promise<{ driver: string, active: number, waiting: number }>} 보유/대기 수. */
+    stats(): Promise<{
+        driver: string;
+        active: number;
+        waiting: number;
+    }>;
+    /** 정리 — 모든 만료 타이머 해제 + 대기자에 null 응답(graceful shutdown). @returns {Promise<void>} */
+    close(): Promise<void>;
+    #private;
+}
+/**
+ * - 보유 중 락 레코드.
+ */
+export type HeldLock = {
+    token: string;
+    expiresAt: number;
+    timer: ReturnType<typeof setTimeout>;
+    fence?: number;
+};
+/**
+ * - 대기 큐 항목.
+ */
+export type Waiter = {
+    ttl: number;
+    fence: boolean;
+    resolve: (lock: import("./contract.js").DriverLock | null) => void;
+    timer: ReturnType<typeof setTimeout> | null;
+};

package/types/core/lock/redis-lock.d.ts

@@ -0,0 +1,43 @@
+export class RedisLockDriver {
+    /**
+     * @param {{ client: any, createSubscriber?: () => any }} opts
+     *   - `client` ioredis 호환 클라이언트(`set`/`eval`/`incr`/`zadd`… 보유). cache 어댑터의 `.native`.
+     *   - `createSubscriber` Pub/Sub 구독 연결 생성자(기본 `client.duplicate()`). 테스트 주입용.
+     */
+    constructor({ client, createSubscriber }: {
+        client: any;
+        createSubscriber?: () => any;
+    });
+    /** @type {'redis'} */
+    get name(): "redis";
+    /**
+     * 락 획득 — fifo 면 대기열 head 일 때만, 아니면 즉시 SET 후 경합 시 Pub/Sub 대기.
+     * @param {string} key @param {import('./contract.js').NormalizedLockOpts} opts
+     * @returns {Promise<import('./contract.js').DriverLock | null>}
+     */
+    acquire(key: string, { ttl, waitMs, fifo, fence }: import("./contract.js").NormalizedLockOpts): Promise<import("./contract.js").DriverLock | null>;
+    /**
+     * 해제 — 소유 토큰일 때만 DEL + 해제 알림(Lua 원자).
+     * @param {string} key @param {string} token @returns {Promise<boolean>}
+     */
+    release(key: string, token: string): Promise<boolean>;
+    /**
+     * 연장 — 소유 토큰일 때만 PEXPIRE(Lua 원자).
+     * @param {string} key @param {string} token @param {number} ttl @returns {Promise<boolean>}
+     */
+    extend(key: string, token: string, ttl: number): Promise<boolean>;
+    /** 강제 해제(관리용, 토큰 무관) — DEL + 해제 알림(대기자 깨움). @param {string} key @returns {Promise<void>} */
+    forceRelease(key: string): Promise<void>;
+    /**
+     * 통계(best-effort) — `…:v:*`/`…:w:*` 키를 SCAN 으로 센다. O(키 수) 라 운영 관측용(고빈도 호출 비권장).
+     * @returns {Promise<{ driver: string, active: number, waiting: number }>}
+     */
+    stats(): Promise<{
+        driver: string;
+        active: number;
+        waiting: number;
+    }>;
+    /** 정리 — 구독 연결만 quit(명령 클라이언트는 cache 소유라 건드리지 않음). @returns {Promise<void>} */
+    close(): Promise<void>;
+    #private;
+}

package/types/core/mega-app.d.ts

@@ -309,6 +309,16 @@ export class MegaApp {
      * @returns {import('./ctx-builder.js').AdapterAccessors}
      */
     get adapterAccessors(): import("./ctx-builder.js").AdapterAccessors;
+    /** 분산 락 사용자 API(ADR-226) — `ctx.lock` 과 같은 process manager(콜러블 + .with/.acquire/...). @returns {any} */
+    get lock(): any;
+    /** 메시지 버스 사용자 API(ADR-227) — `ctx.bus` 와 같은 process manager(콜러블 + .emit/.on/.request/...). @returns {any} */
+    get bus(): any;
+    /** 앱 별명 → 공유 DB 어댑터(ADR-102). 미선언 별명은 throw. @param {string} alias @returns {import('../adapters/mega-adapter.js').MegaAdapter} */
+    db(alias: string): import("../adapters/mega-adapter.js").MegaAdapter;
+    /** 앱 별명 → 공유 캐시 어댑터(ADR-102). 미선언 별명은 throw. @param {string} alias @returns {import('../adapters/mega-adapter.js').MegaAdapter} */
+    cache(alias: string): import("../adapters/mega-adapter.js").MegaAdapter;
+    /** 앱 로거(pino, ADR-141) — `ctx.log` 의 요청 바인딩 없는 베이스 로거. @returns {any} */
+    get log(): any;
     /**
      * 이 앱의 서비스 레지스트리(name → 클래스, ADR-148). 요청 ctx 빌더가 `ctx.services.<name>` lazy DI 의
      * 클래스 lookup 출처로 읽는다. 부팅 orchestrator 가 `setServiceRegistry` 로 채운다.

package/types/core/scope-registry.d.ts

@@ -10,5 +10,11 @@ export const GLOBAL_ONLY_KEYS: readonly string[];
 export const APP_ONLY_KEYS: readonly string[];
 /** Shared-Reference 키 — 전역 services 의 키만 참조 가능 */
 export const SHARED_REFERENCE_KEYS: readonly string[];
+/**
+ * Dual-scope 키 — 글로벌(mega.config.js)과 앱(app.config.js) **양쪽**에 정의 가능 (ADR-229).
+ * 글로벌은 fallback, 앱별 정의가 있으면 그 앱은 자기 manager 를 쓴다(앱별 lock/bus backend 분리). GLOBAL_ONLY_KEYS
+ * 에도 그대로 남겨(글로벌 정의 허용) 두고, validateAppConfig 가 이 목록을 wrong_scope 예외로 둔다.
+ */
+export const DUAL_SCOPE_KEYS: readonly string[];
 export const ALL_GLOBAL_KEYS: readonly string[];
 export const ALL_APP_KEYS: readonly string[];

package/types/index.d.ts

@@ -18,7 +18,7 @@ export { registerAspPlugin } from "./lib/asp/plugin.js";
 export { MegaAspTerminator } from "./lib/asp/ws-terminator.js";
 export { normalizeAspConfig } from "./lib/asp/config.js";
 export { MegaHubLink } from "./core/hub-link.js";
-export { MegaApp, MegaServer, Router, loadAndValidateConfig, loadRoutes, bootApp, buildBootContext, MegaService, MegaCluster, wrapEnvelope, errorEnvelope, buildErrorHandler, ajvErrorToValidationError, MegaWebSocketController, createWsMessage, validateWsMessage, parseWsMessage, generateMessageId, WS_MESSAGE_SCHEMA, WS_PROTOCOL_VERSION, WS_TYPE_PATTERN, buildHttpCtx, buildAdapterAccessors, registerSession, generateSid, readSession, createSessionStore, SESSION_STORE_DRIVERS, createSessionCleanupSchedule } from "./core/index.js";
+export { MegaApp, MegaServer, Router, loadAndValidateConfig, loadRoutes, bootApp, buildBootContext, getApp, hasApp, MegaService, MegaCluster, wrapEnvelope, errorEnvelope, buildErrorHandler, ajvErrorToValidationError, MegaWebSocketController, createWsMessage, validateWsMessage, parseWsMessage, generateMessageId, WS_MESSAGE_SCHEMA, WS_PROTOCOL_VERSION, WS_TYPE_PATTERN, buildHttpCtx, buildAdapterAccessors, registerSession, generateSid, readSession, createSessionStore, SESSION_STORE_DRIVERS, createSessionCleanupSchedule } from "./core/index.js";
 export { runCli, parseArgs, runWorkerHost, runSchedulerHost, dispatchPluginCommand, USAGE } from "./cli/index.js";
 export { MegaHttpError, MegaValidationError, MegaAuthError, MegaForbiddenError, MegaNotFoundError, MegaConflictError, MegaInternalError } from "./errors/http-errors.js";
 export { buildLogger, buildLoggerOptions, buildTargets } from "./lib/mega-logger.js";

package/types/lib/mega-job-queue.d.ts

@@ -7,7 +7,7 @@ export const DEFAULT_DLQ_MAX_AGE_MS: number;
 export const DEFAULT_RUN_TIMEOUT_MS: number;
 /**
  * @typedef {Object} MegaJobQueueOptions
- * @property {import('nats').NatsConnection} nc - **연결된** NatsConnection(`ctx.bus(alias).native`).
+ * @property {import('@nats-io/nats-core').NatsConnection} nc - **연결된** NatsConnection(`ctx.bus(alias).native`).
  * @property {number} [ackWaitMs=30000] - consumer ack 대기(ms). 초과 시 JetStream 재전달. `working()`
  *   하트비트가 이 값의 절반마다 lease 를 갱신한다.
  * @property {number} [maxDeliver=5] - JetStream 최대 전달 횟수(워커 크래시 재전달 backstop).
@@ -31,6 +31,17 @@ export const DEFAULT_RUN_TIMEOUT_MS: number;
  * @property {any} [result] - run 반환값(성공 시).
  * @property {Error} [error] - 실패 사유(실패 시).
  */
+/**
+ * ensureReady 가 lazy import 로 채우는 v3 nats 심볼 묶음(ADR-225). enum·nanos·not-found 에러 클래스만
+ * 추려 보관해 잡 미사용 앱에 nats 전체 로드를 강제하지 않는다.
+ * @typedef {Object} MegaJobQueueNatsBundle
+ * @property {typeof import('@nats-io/jetstream').RetentionPolicy} RetentionPolicy
+ * @property {typeof import('@nats-io/jetstream').AckPolicy} AckPolicy
+ * @property {typeof import('@nats-io/jetstream').StorageType} StorageType
+ * @property {typeof import('@nats-io/nats-core').nanos} nanos
+ * @property {typeof import('@nats-io/jetstream').JetStreamApiError} JetStreamApiError
+ * @property {typeof import('@nats-io/jetstream').JetStreamApiCodes} JetStreamApiCodes
+ */
 /**
  * JetStream 잡 큐 런타임. {@link MegaJob} 클래스를 받아 enqueue/consume·재시도·DLQ 를 처리한다.
  *
@@ -115,19 +126,19 @@ export class MegaJobQueue extends EventEmitter<any> {
      * in-flight Promise 가 reject 되지 않게 — MegaScheduler #fire 와 동일 불변식). 내부/테스트용 seam 이라
      * `_` 접두사(어댑터 `_connect` 컨벤션).
      *
-     * @param {MegaJob} instance @param {Record<string, any>} ctx @param {import('nats').JsMsg} msg
+     * @param {MegaJob} instance @param {Record<string, any>} ctx @param {import('@nats-io/jetstream').JsMsg} msg
      * @param {ReturnType<typeof resolveJobRetryConfig>} retryConfig @param {string} subject
      * @param {number} [runTimeoutMs] - run 전체(재시도 포함) 상한(ms). 미지정 시 큐 디폴트, 0 = 무제한.
      * @returns {Promise<MegaJobHandleResult>}
      */
-    _handleMessage(instance: MegaJob, ctx: Record<string, any>, msg: import("nats").JsMsg, retryConfig: ReturnType<typeof resolveJobRetryConfig>, subject: string, runTimeoutMs?: number): Promise<MegaJobHandleResult>;
+    _handleMessage(instance: MegaJob, ctx: Record<string, any>, msg: import("@nats-io/jetstream").JsMsg, retryConfig: ReturnType<typeof resolveJobRetryConfig>, subject: string, runTimeoutMs?: number): Promise<MegaJobHandleResult>;
     #private;
 }
 export type MegaJobQueueOptions = {
     /**
      * - **연결된** NatsConnection(`ctx.bus(alias).native`).
      */
-    nc: import("nats").NatsConnection;
+    nc: import("@nats-io/nats-core").NatsConnection;
     /**
      * - consumer ack 대기(ms). 초과 시 JetStream 재전달. `working()`
      * 하트비트가 이 값의 절반마다 lease 를 갱신한다.
@@ -183,6 +194,18 @@ export type MegaJobHandleResult = {
      */
     error?: Error;
 };
+/**
+ * ensureReady 가 lazy import 로 채우는 v3 nats 심볼 묶음(ADR-225). enum·nanos·not-found 에러 클래스만
+ * 추려 보관해 잡 미사용 앱에 nats 전체 로드를 강제하지 않는다.
+ */
+export type MegaJobQueueNatsBundle = {
+    RetentionPolicy: typeof import("@nats-io/jetstream").RetentionPolicy;
+    AckPolicy: typeof import("@nats-io/jetstream").AckPolicy;
+    StorageType: typeof import("@nats-io/jetstream").StorageType;
+    nanos: typeof import("@nats-io/nats-core").nanos;
+    JetStreamApiError: typeof import("@nats-io/jetstream").JetStreamApiError;
+    JetStreamApiCodes: typeof import("@nats-io/jetstream").JetStreamApiCodes;
+};
 import { EventEmitter } from 'node:events';
 import { MegaJob } from './mega-job.js';
 import { resolveJobRetryConfig } from './mega-job.js';

package/sample/simple/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -1 +0,0 @@
-{"version":"4.1.8","results":[[":test/apps/main/index.test.js",{"duration":1.6905000000000001,"failed":false}]]}