@gaonjs/async 0.1.3 → 0.2.1

package/dist/lease.js

@@ -0,0 +1,86 @@
+// @gaonjs/async · 리스 기반 리더 선출 (§7 · 질문 19)
+//
+// 허브의 HA(active-standby)와 스케줄러 틱(§7 잡, M7)이 같은 메커니즘을
+// 쓴다: NATS KV 버킷에 TTL 을 걸고, 리더 후보가 리더 키를 **원자적으로
+// 생성**(create — 이미 있으면 실패)해 상호배제를 얻는다. 리더는 TTL 의
+// 절반 주기로 키를 갱신(revision CAS)해 리스를 연장하고, 리더가 죽으면
+// 갱신이 끊겨 TTL 만료 후 대기 인스턴스가 승격한다. (2026-07-22 실 NATS
+// 실측: create 상호배제·TTL 만료 승격 확인.)
+const DEFAULT_TTL_MS = 5000;
+/**
+ * 리더 선출을 시작한다. 반환 핸들의 isLeader 로 상태를 읽고 stop() 으로
+ * 사임한다. 콜백(onElected/onRevoked)으로 리더십 전이를 통지한다.
+ */
+export async function leaseLeader(opts) {
+    const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+    const refreshMs = opts.refreshMs ?? Math.max(500, Math.floor(ttlMs / 2));
+    const bucket = opts.bucket ?? 'gaon_lease';
+    // TTL 은 버킷 단위(MaxAge) — 갱신이 끊긴 리더 키가 만료돼 승계가 열린다.
+    const kv = await opts.nats.kv(bucket, { ttl: ttlMs });
+    let leader = false;
+    let revision = 0;
+    let stopped = false;
+    let timer;
+    const setLeader = (next) => {
+        if (next === leader)
+            return;
+        leader = next;
+        if (next)
+            opts.onElected?.();
+        else
+            opts.onRevoked?.();
+    };
+    const tick = async () => {
+        try {
+            if (!leader) {
+                // 후보: 리더 키를 원자적으로 생성 시도. 성공 = 승격.
+                try {
+                    revision = await kv.create(opts.key, opts.id);
+                    setLeader(true);
+                }
+                catch {
+                    // 키가 이미 있음(다른 리더 보유) — 대기 유지.
+                }
+            }
+            else {
+                // 리더: revision CAS 로 갱신해 리스 연장. 실패 = 리스 상실.
+                try {
+                    revision = await kv.update(opts.key, opts.id, revision);
+                }
+                catch {
+                    setLeader(false);
+                    revision = 0;
+                }
+            }
+        }
+        catch (err) {
+            opts.onError?.(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            if (!stopped)
+                timer = setTimeout(() => void tick(), refreshMs);
+        }
+    };
+    // 첫 시도는 즉시 — 부팅 직후 리더가 정해지도록.
+    await tick();
+    return {
+        get isLeader() {
+            return leader;
+        },
+        async stop() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            if (leader) {
+                // 사임: 내 revision 에서만 삭제(내가 여전히 리더일 때만) — 즉시 승계.
+                try {
+                    await kv.delete(opts.key);
+                }
+                catch {
+                    // 이미 만료·교체됐으면 무시.
+                }
+                setLeader(false);
+            }
+        },
+    };
+}

package/dist/listeners.d.ts

@@ -0,0 +1,37 @@
+import type { GaonNats } from './nats.js';
+import { type StreamTuning } from './streams.js';
+export type ListenerEvent = {
+    readonly kind: 'handled';
+    readonly listener: string;
+    readonly event: string;
+} | {
+    readonly kind: 'retrying';
+    readonly listener: string;
+    readonly event: string;
+    readonly attempt: number;
+} | {
+    readonly kind: 'dropped';
+    readonly listener: string;
+    readonly event: string;
+    readonly error: string;
+} | {
+    readonly kind: 'error';
+    readonly error: string;
+};
+export interface ListenersOptions {
+    readonly nats: GaonNats;
+    /** ack 대기(ms). 기본 30000. */
+    readonly ackWaitMs?: number;
+    /** 리스너 최대 재전달(크래시·실패 합산). 기본 6. */
+    readonly maxDeliver?: number;
+    /** graceful drain 상한(ms). 기본 30000. */
+    readonly drainTimeoutMs?: number;
+    readonly tuning?: StreamTuning;
+    onEvent?(e: ListenerEvent): void;
+}
+export interface ListenersHandle {
+    stop(): Promise<void>;
+    readonly inflight: number;
+}
+/** 등록된 리스너들을 이벤트 스트림에 붙여 소비를 시작한다. */
+export declare function runListeners(opts: ListenersOptions): Promise<ListenersHandle>;

package/dist/listeners.js

@@ -0,0 +1,89 @@
+// @gaonjs/async · 리스너 소비 (§7 M7 · line 798~826)
+//
+// 워커(`gaon work`)가 등록된 리스너마다 이벤트 스트림에 durable 컨슈머를
+// 붙여 소비한다. 리스너 id 가 durable 이름의 근간이라, 재시작해도 같은
+// 지점부터 이어 받는다(중복 배달 가능 — 리스너는 멱등 권장).
+//
+// 이벤트는 알림성이라 잡보다 단순하게 다룬다: 성공→ack, 실패→백오프 후
+// 재전달(nak), max_deliver 소진→폐기(term, 로깅). 잡 같은 DLQ 는 두지 않되
+// 재시도는 준다.
+import { jetstreamManager } from '@nats-io/jetstream';
+import { EVENTS_STREAM, eventSubject, listenerConsumerName, toNanos, ensureEventsStream, } from './streams.js';
+import { decodePayloadBytes } from './codec.js';
+import { backoffDelayMs } from './backoff.js';
+import { registeredListeners } from './events.js';
+const DEFAULT_ACK_WAIT_MS = 30000;
+const DEFAULT_MAX_DELIVER = 6;
+const DEFAULT_DRAIN_MS = 30000;
+/** 등록된 리스너들을 이벤트 스트림에 붙여 소비를 시작한다. */
+export async function runListeners(opts) {
+    const ackWaitMs = opts.ackWaitMs ?? DEFAULT_ACK_WAIT_MS;
+    const maxDeliver = opts.maxDeliver ?? DEFAULT_MAX_DELIVER;
+    const drainTimeoutMs = opts.drainTimeoutMs ?? DEFAULT_DRAIN_MS;
+    const emit = (e) => opts.onEvent?.(e);
+    await ensureEventsStream(opts.nats, opts.tuning);
+    const jsm = await jetstreamManager(opts.nats.nc);
+    const listeners = registeredListeners();
+    const closers = [];
+    const inflightAll = new Set();
+    for (const listener of listeners) {
+        const durable = listenerConsumerName(listener.id);
+        await jsm.consumers.add(EVENTS_STREAM, {
+            durable_name: durable,
+            filter_subject: eventSubject(listener.eventName),
+            ack_policy: 'explicit',
+            ack_wait: toNanos(ackWaitMs),
+            max_deliver: maxDeliver,
+        });
+        const handle = async (m) => {
+            const attempt = m.info.deliveryCount;
+            try {
+                const payload = decodePayloadBytes(m.data);
+                await listener.handler(payload);
+                m.ack();
+                emit({ kind: 'handled', listener: listener.id, event: listener.eventName });
+            }
+            catch (err) {
+                const error = err instanceof Error ? err.message : String(err);
+                if (attempt < maxDeliver) {
+                    m.nak(backoffDelayMs(attempt, { jitter: 0.2 }));
+                    emit({ kind: 'retrying', listener: listener.id, event: listener.eventName, attempt });
+                }
+                else {
+                    m.term();
+                    emit({ kind: 'dropped', listener: listener.id, event: listener.eventName, error });
+                }
+            }
+        };
+        const consumer = await opts.nats.js.consumers.get(EVENTS_STREAM, durable);
+        const messages = await consumer.consume({ max_messages: 1 });
+        const loop = (async () => {
+            for await (const m of messages) {
+                const p = handle(m).finally(() => inflightAll.delete(p));
+                inflightAll.add(p);
+                await Promise.race(inflightAll);
+            }
+        })();
+        closers.push(async () => {
+            messages.stop();
+            await loop.catch(() => { });
+        });
+    }
+    let stopped = false;
+    return {
+        get inflight() {
+            return inflightAll.size;
+        },
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            for (const close of closers)
+                await close();
+            const deadline = Date.now() + drainTimeoutMs;
+            while (inflightAll.size > 0 && Date.now() < deadline) {
+                await Promise.race([...inflightAll, new Promise((r) => setTimeout(r, 200))]);
+            }
+        },
+    };
+}

package/dist/nats.d.ts

@@ -0,0 +1,28 @@
+import { type NatsConnection } from '@nats-io/transport-node';
+import { type JetStreamClient } from '@nats-io/jetstream';
+import { Kvm } from '@nats-io/kv';
+import type { KV, KvOptions } from '@nats-io/kv';
+export interface NatsOptions {
+    /** 접속지. 생략 시 env GAON_NATS_URL, 그다음 nats://127.0.0.1:4222. */
+    readonly servers?: string | readonly string[];
+    /** 연결 이름(모니터링 식별). serve/work/hub 프로세스가 각자 붙인다. */
+    readonly name?: string;
+}
+/** 연결 + JetStream + KV 를 한데 묶은 Gaon NATS 핸들. */
+export interface GaonNats {
+    readonly nc: NatsConnection;
+    readonly js: JetStreamClient;
+    readonly kvm: Kvm;
+    /** 이름있는 KV 버킷을 열거나(없으면) 만든다. */
+    kv(bucket: string, opts?: Partial<KvOptions>): Promise<KV>;
+    /** 이름으로 JetStream 스트림을 삭제한다(없으면 무시). 운영 리셋·테스트 정리용. */
+    deleteStream(name: string): Promise<void>;
+    /** 처리 중 메시지를 흘려보내고 연결을 닫는다(graceful). */
+    close(): Promise<void>;
+}
+/**
+ * NATS 에 연결하고 JetStream·KV 핸들을 준비한다. 연결 실패는 수리
+ * 안내를 포함한 에러로 즉시 던진다(§7.5.3 — 에러가 곧 수리 안내서).
+ */
+export declare function connectNats(opts?: NatsOptions): Promise<GaonNats>;
+export type { NatsConnection, JetStreamClient, KV };

package/dist/nats.js

@@ -0,0 +1,61 @@
+// @gaonjs/async · NATS 연결 (§7 실시간 · 백본)
+//
+// NATS 는 실시간(채널 브로드캐스트·프레즌스 전송)과 비동기(잡·이벤트,
+// M7)의 공통 백본이다. 여기서는 연결 + JetStream + KV 핸들을 하나로
+// 묶어 노출한다. 목업은 없다(§9) — 개발·테스트·운영 모두 실 NATS 로 돈다.
+//
+// 기본 접속지는 표준 포트(4222) — 사용자 프로젝트의 `gaon dev` compose 가
+// 띄우는 NATS 다. 이 저장소의 테스트 인프라는 mega-nats(4222) 회피용으로
+// 4223 을 쓰므로 `GAON_NATS_URL` 로 재지정한다(§9 테스트 픽스처).
+import { connect } from '@nats-io/transport-node';
+import { jetstream, jetstreamManager } from '@nats-io/jetstream';
+import { Kvm } from '@nats-io/kv';
+function resolveServers(opts) {
+    if (opts.servers)
+        return Array.isArray(opts.servers) ? [...opts.servers] : opts.servers;
+    return process.env.GAON_NATS_URL ?? 'nats://127.0.0.1:4222';
+}
+/**
+ * NATS 에 연결하고 JetStream·KV 핸들을 준비한다. 연결 실패는 수리
+ * 안내를 포함한 에러로 즉시 던진다(§7.5.3 — 에러가 곧 수리 안내서).
+ */
+export async function connectNats(opts = {}) {
+    const servers = resolveServers(opts);
+    let nc;
+    try {
+        nc = await connect({ servers, name: opts.name });
+    }
+    catch (err) {
+        const where = Array.isArray(servers) ? servers.join(', ') : servers;
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`[@gaonjs/async] NATS 연결 실패 (${where}): ${msg}\n` +
+            `→ 개발 인프라를 기동하세요: gaon dev (또는 docker compose up -d nats)\n` +
+            `→ 접속지를 바꾸려면 GAON_NATS_URL 환경변수를 설정하세요.`);
+    }
+    const js = jetstream(nc);
+    const kvm = new Kvm(js);
+    return {
+        nc,
+        js,
+        kvm,
+        async kv(bucket, kvOpts) {
+            // create 는 있으면 열고 없으면 만든다(멱등). 버킷 설정(ttl 등)은
+            // 최초 생성 시에만 적용된다.
+            return kvm.create(bucket, kvOpts);
+        },
+        async deleteStream(name) {
+            const jsm = await jetstreamManager(nc);
+            await jsm.streams.delete(name).catch(() => { });
+        },
+        async close() {
+            // drain 은 처리 중 메시지를 흘려보내고 닫는다. 이미 닫히는 중이거나
+            // in-flight 요청이 끊겨 throw 하면 강제 close 로 마무리한다.
+            try {
+                await nc.drain();
+            }
+            catch {
+                await nc.close().catch(() => { });
+            }
+        },
+    };
+}

package/dist/outbox.d.ts

@@ -0,0 +1,34 @@
+import type { Kysely, Transaction } from 'kysely';
+export declare const OUTBOX_TABLE = "_gaon_outbox";
+/**
+ * `_gaon_outbox` 테이블을 보장한다(CREATE TABLE IF NOT EXISTS). id 는 클라이언트
+ * 생성 UUID 라 dialect 별 auto-increment 차이를 피한다. created_at 은 코드에서
+ * 넣어 dialect default 함수 의존을 없앤다.
+ */
+export declare function ensureOutboxTable(db: Kysely<any>): Promise<void>;
+/**
+ * 서비스 트랜잭션을 연다. 이 안에서의 emit 은 같은 트랜잭션으로 아웃박스에
+ * 적재된다(트랜잭션 밖 emit 은 즉시 발행). fn 이 throw 하면 롤백 —
+ * 비즈니스 쓰기와 아웃박스 적재가 함께 취소돼 정합이 유지된다.
+ */
+export declare function runInTransaction<T>(db: Kysely<any>, fn: (trx: Transaction<any>) => Promise<T>): Promise<T>;
+export interface RelayOptions {
+    /** 한 번에 처리할 최대 행 수. 기본 100. */
+    readonly batchSize?: number;
+    /** 폴링 주기(ms). 기본 1000. */
+    readonly pollMs?: number;
+    /** 진행 통지(로깅·테스트). */
+    onError?(err: Error): void;
+    onRelayed?(count: number): void;
+}
+export interface RelayHandle {
+    stop(): Promise<void>;
+    /** 한 번 즉시 폴링(테스트·부팅 직후 소진용). 발행 건수를 돌려준다. */
+    drainOnce(): Promise<number>;
+}
+/**
+ * 아웃박스 릴레이를 시작한다. 미발행 행을 폴링해 NATS 로 발행하고 표시한다.
+ * SKIP LOCKED 로 잠긴 행을 건너뛰어 여러 릴레이가 같은 행을 두 번 잡지
+ * 않는다(중복은 at-least-once 로 허용되지만 낭비를 줄인다).
+ */
+export declare function runOutboxRelay(db: Kysely<any>, opts?: RelayOptions): RelayHandle;

package/dist/outbox.js

@@ -0,0 +1,130 @@
+// @gaonjs/async · 아웃박스 패턴 (§7 M7 · line 828~836 · v1 코어 내장)
+//
+// 이중 쓰기(dual-write) 문제 해결: 서비스 트랜잭션이 커밋됐는데 이벤트 발행이
+// 유실되는 일을 막는다. 트랜잭션 안 emit 은 같은 트랜잭션으로 `_gaon_outbox`
+// 에 적재되고(runInTransaction + outboxContext), 백그라운드 릴레이(단순 폴링)가
+// 미발행 행을 NATS 로 발행한 뒤 발행 표시한다. **at-least-once** — 발행 후
+// 표시 사이에 죽으면 다음 폴링이 재발행하고, msgID 중복 제거가 흡수한다.
+//
+// DB 결합을 피하려 Kysely 핸들을 주입받는다(async→data 의존 없음). 테이블은
+// 프레임웍 내부용이라 사용자 스키마 diff 밖에서 ensureOutboxTable 로 보장한다.
+import { randomUUID } from 'node:crypto';
+import { runWithOutbox } from './outboxContext.js';
+import { encodePayload, decodePayload } from './codec.js';
+import { publishToSubject } from './events.js';
+export const OUTBOX_TABLE = '_gaon_outbox';
+/**
+ * `_gaon_outbox` 테이블을 보장한다(CREATE TABLE IF NOT EXISTS). id 는 클라이언트
+ * 생성 UUID 라 dialect 별 auto-increment 차이를 피한다. created_at 은 코드에서
+ * 넣어 dialect default 함수 의존을 없앤다.
+ */
+export async function ensureOutboxTable(db) {
+    await db.schema
+        .createTable(OUTBOX_TABLE)
+        .ifNotExists()
+        .addColumn('id', 'varchar(36)', (c) => c.primaryKey())
+        .addColumn('subject', 'varchar(255)', (c) => c.notNull())
+        .addColumn('payload', 'text', (c) => c.notNull())
+        .addColumn('created_at', 'timestamp', (c) => c.notNull())
+        .addColumn('published_at', 'timestamp')
+        .execute();
+    // 미발행 행 조회를 빠르게(published_at IS NULL 스캔).
+    await db.schema
+        .createIndex(`${OUTBOX_TABLE}_unpublished`)
+        .ifNotExists()
+        .on(OUTBOX_TABLE)
+        .column('published_at')
+        .execute()
+        .catch(() => { });
+}
+/** 트랜잭션에 묶인 stager — 같은 트랜잭션으로 outbox 행을 insert 한다. */
+function makeStager(trx) {
+    return {
+        async stage(subject, payload) {
+            await trx
+                .insertInto(OUTBOX_TABLE)
+                .values({
+                id: randomUUID(),
+                subject,
+                payload: encodePayload(payload),
+                created_at: new Date(),
+                published_at: null,
+            })
+                .execute();
+        },
+    };
+}
+/**
+ * 서비스 트랜잭션을 연다. 이 안에서의 emit 은 같은 트랜잭션으로 아웃박스에
+ * 적재된다(트랜잭션 밖 emit 은 즉시 발행). fn 이 throw 하면 롤백 —
+ * 비즈니스 쓰기와 아웃박스 적재가 함께 취소돼 정합이 유지된다.
+ */
+export function runInTransaction(db, fn) {
+    return db.transaction().execute((trx) => runWithOutbox(makeStager(trx), () => fn(trx)));
+}
+const DEFAULT_BATCH = 100;
+const DEFAULT_POLL_MS = 1000;
+/**
+ * 아웃박스 릴레이를 시작한다. 미발행 행을 폴링해 NATS 로 발행하고 표시한다.
+ * SKIP LOCKED 로 잠긴 행을 건너뛰어 여러 릴레이가 같은 행을 두 번 잡지
+ * 않는다(중복은 at-least-once 로 허용되지만 낭비를 줄인다).
+ */
+export function runOutboxRelay(db, opts = {}) {
+    const batchSize = opts.batchSize ?? DEFAULT_BATCH;
+    const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+    let stopped = false;
+    let timer;
+    const relayBatch = async () => {
+        // 미발행 행을 트랜잭션 안에서 잠그고(SKIP LOCKED) 발행 후 표시한다.
+        // 발행(NATS)은 트랜잭션 밖 부수효과라, 표시 커밋 전에 죽으면 재발행된다
+        // (at-least-once). msgID=행 id 로 이벤트 스트림에서 중복 제거된다.
+        const rows = await db.transaction().execute(async (trx) => {
+            const locked = (await trx
+                .selectFrom(OUTBOX_TABLE)
+                .selectAll()
+                .where('published_at', 'is', null)
+                .orderBy('created_at')
+                .limit(batchSize)
+                .forUpdate()
+                .skipLocked()
+                .execute());
+            for (const row of locked) {
+                await publishToSubject(row.subject, decodePayload(row.payload), row.id);
+                await trx
+                    .updateTable(OUTBOX_TABLE)
+                    .set({ published_at: new Date() })
+                    .where('id', '=', row.id)
+                    .execute();
+            }
+            return locked;
+        });
+        if (rows.length > 0)
+            opts.onRelayed?.(rows.length);
+        return rows.length;
+    };
+    const tick = async () => {
+        try {
+            // 밀린 행이 있으면 배치를 연달아 비운다(폴링 지연 없이 소진).
+            let n = 0;
+            do {
+                n = await relayBatch();
+            } while (n >= batchSize && !stopped);
+        }
+        catch (err) {
+            opts.onError?.(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            if (!stopped)
+                timer = setTimeout(() => void tick(), pollMs);
+        }
+    };
+    void tick();
+    return {
+        async stop() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+        },
+        drainOnce: relayBatch,
+    };
+}

package/dist/outboxContext.d.ts

@@ -0,0 +1,8 @@
+/** 트랜잭션에 묶인 아웃박스 적재기. 같은 트랜잭션으로 outbox 행을 쓴다. */
+export interface OutboxStager {
+    stage(subject: string, payload: unknown): Promise<void>;
+}
+/** 현재 활성 아웃박스 stager(트랜잭션 안일 때만). 없으면 undefined. */
+export declare function currentOutbox(): OutboxStager | undefined;
+/** stager 를 문맥에 세우고 fn 을 실행한다(트랜잭션 런타임이 호출). */
+export declare function runWithOutbox<T>(stager: OutboxStager, fn: () => Promise<T>): Promise<T>;

package/dist/outboxContext.js

@@ -0,0 +1,16 @@
+// @gaonjs/async · 아웃박스 트랜잭션 컨텍스트 (§7 M7 · line 828~836)
+//
+// emit() 이 "지금 트랜잭션 안인가"를 알아야 아웃박스로 적재할지 즉시 발행할지
+// 정한다. 스택을 타고 내려가는 이 문맥을 AsyncLocalStorage 로 전달한다 —
+// 서비스 트랜잭션이 열리면 트랜잭션에 묶인 stager 를 세우고, 그 안에서의
+// emit 은 같은 트랜잭션으로 _gaon_outbox 에 적재된다. 개발자에겐 보이지 않는다.
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+/** 현재 활성 아웃박스 stager(트랜잭션 안일 때만). 없으면 undefined. */
+export function currentOutbox() {
+    return storage.getStore();
+}
+/** stager 를 문맥에 세우고 fn 을 실행한다(트랜잭션 런타임이 호출). */
+export function runWithOutbox(stager, fn) {
+    return storage.run(stager, fn);
+}

package/dist/presence.d.ts

@@ -0,0 +1,26 @@
+import type { GaonNats } from './nats.js';
+import type { PresenceMember } from './channel.js';
+import { type PresenceEvent } from './protocol.js';
+export declare const PRESENCE_BUCKET = "gaon_presence";
+export interface PresenceClientOptions {
+    readonly nats: GaonNats;
+    /** 이 웹서버 식별자(허브가 서버→멤버 매핑에 사용). */
+    readonly server: string;
+    /** 허브 TCP 주소 'host:port'. 생략 시 NATS KV 에 공지된 리더 엔드포인트를 발견. */
+    readonly hubAddr?: string;
+    /** ping 주기(ms). 반열림 감지 백스톱. 기본 3000(허브 pingTimeout 의 1/3 이하). */
+    readonly heartbeatMs?: number;
+    /** 재접속 백오프 최소·최대(ms). 기본 250·2000. */
+    readonly reconnectMinMs?: number;
+    readonly reconnectMaxMs?: number;
+}
+export interface PresenceClient {
+    join(channel: string, member: string, info: Record<string, unknown>): Promise<void>;
+    leave(channel: string, member: string): Promise<void>;
+    /** 채널의 현재 접속자 목록(허브 KV 권위 ∪ 로컬 멤버). */
+    list(channel: string): Promise<PresenceMember[]>;
+    /** 채널 프레즌스 델타 구독(허브가 NATS 로 broadcast). 반환 함수로 해지. */
+    subscribe(channel: string, onEvent: (e: PresenceEvent) => void): () => void;
+    close(): Promise<void>;
+}
+export declare function createPresenceClient(opts: PresenceClientOptions): Promise<PresenceClient>;

package/dist/protocol.d.ts

@@ -0,0 +1,96 @@
+import type { PresenceMember } from './channel.js';
+/** 클라이언트가 채널로 보내는 메시지. data 는 onMessage 로 전달된다. */
+export interface ClientMessage {
+    readonly t: 'msg';
+    readonly data: unknown;
+}
+export type ServerFrame = {
+    readonly t: 'joined';
+    readonly channel: string;
+    readonly member: string;
+} | {
+    readonly t: 'msg';
+    readonly data: unknown;
+} | {
+    readonly t: 'presence';
+    readonly members: readonly PresenceMember[];
+} | {
+    readonly t: 'presence:join';
+    readonly member: PresenceMember;
+} | {
+    readonly t: 'presence:leave';
+    readonly member: string;
+} | {
+    readonly t: 'error';
+    readonly message: string;
+};
+/** 프레즌스 상태 변경을 허브에 알리는 이벤트. 허브가 KV 권위를 갱신한다. */
+export type PresenceCommand = {
+    readonly op: 'join';
+    readonly channel: string;
+    readonly member: string;
+    readonly info: Record<string, unknown>;
+    readonly server: string;
+} | {
+    readonly op: 'leave';
+    readonly channel: string;
+    readonly member: string;
+    readonly server: string;
+} | {
+    readonly op: 'heartbeat';
+    readonly channel: string;
+    readonly member: string;
+    readonly server: string;
+};
+export type HubCommand = {
+    readonly op: 'register';
+    readonly server: string;
+} | {
+    readonly op: 'join';
+    readonly channel: string;
+    readonly member: string;
+    readonly info: Record<string, unknown>;
+} | {
+    readonly op: 'leave';
+    readonly channel: string;
+    readonly member: string;
+} | {
+    readonly op: 'synced';
+} | {
+    readonly op: 'unregister';
+    readonly server: string;
+} | {
+    readonly op: 'ping';
+};
+export type PresenceEvent = {
+    readonly type: 'join';
+    readonly channel: string;
+    readonly member: PresenceMember;
+} | {
+    readonly type: 'leave';
+    readonly channel: string;
+    readonly member: string;
+};
+/** channelSubject(name) 로 오가는 브로드캐스트 봉투. */
+export interface BroadcastEnvelope {
+    readonly data: unknown;
+}
+/** 웹서버 → 허브 프레즌스 명령(허브가 큐 구독). */
+export declare const HUB_PRESENCE_SUBJECT = "gaon.hub.presence";
+/** 허브 → 전 서버 프레즌스 델타(채널별). 채널명은 내부에서 인코딩한다. */
+export declare function presenceEventSubject(channel: string): string;
+/** 리더 허브가 자신의 TCP 엔드포인트를 공지하는 KV 버킷·키(멀티호스트 발견). */
+export declare const HUB_ENDPOINT_BUCKET = "gaon_hub";
+export declare const HUB_ENDPOINT_KEY = "endpoint";
+/** 값을 개행 종결 JSON 한 줄로 인코딩(TCP 전송 단위). */
+export declare function encodeLine(value: unknown): string;
+/**
+ * TCP 청크를 누적해 완결된 라인(JSON)만 파싱해 내는 디코더를 만든다.
+ * 소켓은 메시지 경계를 보장하지 않으므로(청크 분할·병합) 개행으로 잘라
+ * 완성된 줄만 넘긴다. 파싱 불가한 줄은 건너뛴다.
+ */
+export declare function createLineDecoder<T>(): (chunk: string) => T[];
+/** JSON 을 NATS 페이로드(Uint8Array)로. */
+export declare function encodeJson(value: unknown): Uint8Array;
+/** NATS 페이로드(Uint8Array)를 JSON 으로. 실패 시 undefined. */
+export declare function decodeJson<T>(bytes: Uint8Array): T | undefined;