@gaonjs/async 0.1.2 → 0.2.0

package/dist/__fixtures__/testnats.d.ts

@@ -0,0 +1,7 @@
+import { type GaonNats } from '../nats.js';
+export declare const TEST_NATS_URL: string;
+export declare function createTestNats(name?: string): Promise<GaonNats>;
+/** 충돌 없는 버킷/키 프리픽스. */
+export declare function uniqueName(prefix: string): string;
+/** KV 버킷(스트림 KV_<bucket>)을 삭제해 테스트 잔여물을 정리한다. */
+export declare function dropBucket(nats: GaonNats, bucket: string): Promise<void>;

package/dist/__fixtures__/testnats.js

@@ -0,0 +1,21 @@
+// 실 NATS 테스트 인프라 (CLAUDE.md §9 — 목업·인메모리 금지).
+// compose.yaml 의 nats(4223, JetStream)에 붙는다. mega-nats(4222) 회피용
+// 전용 포트라 GAON_TEST_NATS_URL 로 재지정한다.
+//
+// 격리: NATS KV 는 트랜잭션이 없으므로, 테스트마다 고유 버킷/subject
+// 프리픽스를 쓰고 끝나면 스트림을 삭제해 정리한다.
+import { connectNats } from '../nats.js';
+import { jetstreamManager } from '@nats-io/jetstream';
+export const TEST_NATS_URL = process.env.GAON_TEST_NATS_URL ?? 'nats://127.0.0.1:4223';
+export async function createTestNats(name) {
+    return connectNats({ servers: TEST_NATS_URL, name: name ?? 'gaon-test' });
+}
+/** 충돌 없는 버킷/키 프리픽스. */
+export function uniqueName(prefix) {
+    return `${prefix}_${Date.now().toString(36)}_${Math.floor(Math.random() * 1e6).toString(36)}`;
+}
+/** KV 버킷(스트림 KV_<bucket>)을 삭제해 테스트 잔여물을 정리한다. */
+export async function dropBucket(nats, bucket) {
+    const jsm = await jetstreamManager(nats.nc);
+    await jsm.streams.delete(`KV_${bucket}`).catch(() => { });
+}

package/dist/channel.d.ts

@@ -0,0 +1,52 @@
+/** 연결 인가/프레즌스 메타 계산 시점의 컨텍스트(소켓 attach 전). */
+export interface ChannelAuthContext<User = unknown> {
+    /** 채널 이름(파일명 관례). */
+    readonly channel: string;
+    /** 세션 인증 사용자(M5). 비로그인 연결이면 null. */
+    readonly user: User | null;
+    /** 연결이 보낸 쿼리 파라미터(예: ?room=42). */
+    readonly query: Readonly<Record<string, string>>;
+}
+/** 접속자 목록에 실리는 한 멤버. */
+export interface PresenceMember {
+    /** 안정적 멤버 식별자(로그인=user:<id>, 익명=conn:<uuid>). */
+    readonly id: string;
+    /** presenceInfo 로 노출한 공개 메타(이름 등). */
+    readonly info: Record<string, unknown>;
+}
+/** 연결된 소켓 하나의 런타임 컨텍스트(onJoin/onMessage/onLeave). */
+export interface ChannelContext<User = unknown> extends ChannelAuthContext<User> {
+    /** 이 연결의 멤버 식별자. */
+    readonly member: string;
+    /** 이 연결에만 전송. */
+    send(data: unknown): void;
+    /** 채널 전체(모든 서버의 모든 연결)로 브로드캐스트. */
+    broadcast(data: unknown): void;
+    /** 현재 채널 접속자 목록(허브 권위 · 전 서버 동기화). */
+    presence(): Promise<PresenceMember[]>;
+}
+/** 채널 정의 — 전 훅 선택. */
+export interface ChannelDef<User = unknown> {
+    /**
+     * 연결 인가. false 를 반환하면 연결을 거부한다(4401 close).
+     * 생략 시 모두 허용(공개 채널).
+     */
+    authorize?(ctx: ChannelAuthContext<User>): boolean | Promise<boolean>;
+    /**
+     * 접속자 목록에 노출할 공개 메타를 만든다(민감 정보 제외 — §4.2 경계).
+     * 생략 시 빈 객체.
+     */
+    presenceInfo?(ctx: ChannelAuthContext<User>): Record<string, unknown>;
+    /** 참여(연결 수립·프레즌스 등록 후). */
+    onJoin?(ctx: ChannelContext<User>): void | Promise<void>;
+    /** 클라이언트 메시지 수신. */
+    onMessage?(ctx: ChannelContext<User>, data: unknown): void | Promise<void>;
+    /** 이탈(연결 종료·프레즌스 해제 후). */
+    onLeave?(ctx: ChannelContext<User>): void | Promise<void>;
+}
+/**
+ * 채널을 정의한다. 런타임 동작은 없고 정의 객체를 그대로 돌려주는
+ * 타입 앵커다(model()/controller() 와 같은 헬퍼 패턴). 파일의 default
+ * export 로 두면 websocket 런타임이 파일명을 채널 이름으로 등록한다.
+ */
+export declare function channel<User = unknown>(def: ChannelDef<User>): ChannelDef<User>;

package/dist/channel.js

@@ -0,0 +1,17 @@
+// @gaonjs/async · 채널 정의 API (§7 실시간 · 질문 19)
+//
+// 채널은 `apps/<app>/channels/<이름>.ts` 파일 하나로 정의한다 —
+// 파일 존재 = 등록(다른 배터리와 동일 관례). 정의는 `channel(def)`
+// 헬퍼 + 설정 객체 스타일이다(클래스·데코레이터 금지 — CLAUDE.md §1).
+//
+// 브로드캐스트는 NATS pub/sub 을 타므로 다중 인스턴스에서 별도 어댑터가
+// 필요 없다(§7 line 891). 프레즌스(접속자 동기화)는 presence.ts 가
+// 이 컨텍스트에 얹는다.
+/**
+ * 채널을 정의한다. 런타임 동작은 없고 정의 객체를 그대로 돌려주는
+ * 타입 앵커다(model()/controller() 와 같은 헬퍼 패턴). 파일의 default
+ * export 로 두면 websocket 런타임이 파일명을 채널 이름으로 등록한다.
+ */
+export function channel(def) {
+    return def;
+}

package/dist/hub.d.ts

@@ -0,0 +1,25 @@
+import type { GaonNats } from './nats.js';
+export interface HubOptions {
+    readonly nats: GaonNats;
+    /** 인스턴스 식별자(리스 값). */
+    readonly id: string;
+    /** 리스 TTL(ms). 기본 5000. */
+    readonly ttlMs?: number;
+    /** 멤버 만료 임계(ms) — 이 시간 넘게 하트비트 없으면 leave 처리. 기본 30000. */
+    readonly memberTimeoutMs?: number;
+    /** 만료 스윕 주기(ms). 기본 5000. */
+    readonly sweepMs?: number;
+    /** 리더십·상태 통지(옵션). */
+    onState?(state: {
+        leader: boolean;
+    }): void;
+}
+export interface HubHandle {
+    readonly isLeader: boolean;
+    stop(): Promise<void>;
+}
+/**
+ * 허브를 시작한다. 리더가 되기 전에는 대기하고, 리더가 되면 프레즌스
+ * 명령 구독·KV 권위 갱신·델타 중계·만료 스윕을 켠다.
+ */
+export declare function runHub(opts: HubOptions): Promise<HubHandle>;

package/dist/hub.js

@@ -0,0 +1,143 @@
+// @gaonjs/async · 허브 서버 (§7 실시간 · 질문 19)
+//
+// 허브는 접속자 목록의 **단일 권위이자 중계**다. 웹서버들이 보내는
+// 프레즌스 명령(join/leave/heartbeat)을 받아 **NATS KV 에 영속**하고(허브만
+// KV 를 쓴다), 변경 델타를 전 웹서버로 브로드캐스트한다. HA 는 스케줄러와
+// 동일한 **리스 기반 리더 선출**(active-standby) — 리더만 명령을 처리한다.
+//
+// - 재시작 복원: 리더가 되면 KV 의 기존 로스터로 생존 추적을 재구축한다.
+//   접속자 목록 자체는 KV 에 남아 있으므로 허브가 죽어도 유실되지 않는다
+//   (웹서버의 list() 는 KV 를 직접 읽는다).
+// - 생존 추적: 웹서버가 죽어 하트비트가 끊긴 멤버는 임계 시간 후 만료시켜
+//   leave 로 처리한다(§7 line 898).
+import { leaseLeader } from './lease.js';
+import { PRESENCE_BUCKET } from './presence.js';
+import { presenceKey, parsePresenceKey } from './keys.js';
+import { HUB_PRESENCE_SUBJECT, presenceEventSubject, encodeJson, decodeJson, } from './protocol.js';
+/** now 주입 없이 테스트 결정성을 위해 Date.now 를 감싼다. */
+const now = () => Date.now();
+/**
+ * 허브를 시작한다. 리더가 되기 전에는 대기하고, 리더가 되면 프레즌스
+ * 명령 구독·KV 권위 갱신·델타 중계·만료 스윕을 켠다.
+ */
+export async function runHub(opts) {
+    const memberTimeoutMs = opts.memberTimeoutMs ?? 30000;
+    const sweepMs = opts.sweepMs ?? 5000;
+    const kv = await opts.nats.kv(PRESENCE_BUCKET);
+    // 리더일 때만 살아 있는 자원.
+    let sub;
+    let sweepTimer;
+    // 멤버별 마지막 생존 시각(KV 키 → ts). 리더 승격 시 KV 에서 복원.
+    const lastSeen = new Map();
+    const broadcast = (channel, ev) => {
+        opts.nats.nc.publish(presenceEventSubject(channel), encodeJson(ev));
+    };
+    const applyJoin = async (channel, member, info, server) => {
+        const key = presenceKey(channel, member);
+        const rec = { info, server, ts: now() };
+        await kv.put(key, encodeJson(rec));
+        lastSeen.set(key, rec.ts);
+        broadcast(channel, { type: 'join', channel, member: { id: member, info } });
+    };
+    const applyLeave = async (channel, member) => {
+        const key = presenceKey(channel, member);
+        await kv.delete(key).catch(() => { });
+        lastSeen.delete(key);
+        broadcast(channel, { type: 'leave', channel, member });
+    };
+    const applyHeartbeat = async (channel, member) => {
+        const key = presenceKey(channel, member);
+        const entry = await kv.get(key);
+        if (!entry)
+            return; // join 을 놓친 하트비트는 무시(다음 join 에서 정합).
+        const rec = decodeJson(entry.value);
+        if (!rec)
+            return;
+        const bumped = { ...rec, ts: now() };
+        await kv.put(key, encodeJson(bumped));
+        lastSeen.set(key, bumped.ts);
+    };
+    const handleCommand = async (cmd) => {
+        if (cmd.op === 'join')
+            await applyJoin(cmd.channel, cmd.member, cmd.info, cmd.server);
+        else if (cmd.op === 'leave')
+            await applyLeave(cmd.channel, cmd.member);
+        else
+            await applyHeartbeat(cmd.channel, cmd.member);
+    };
+    const sweep = async () => {
+        const cutoff = now() - memberTimeoutMs;
+        for (const [key, ts] of [...lastSeen.entries()]) {
+            if (ts < cutoff) {
+                const { channel, member } = parsePresenceKey(key);
+                await applyLeave(channel, member);
+            }
+        }
+    };
+    // 리더 승격: KV 로스터로 생존 추적 재구축(재시작 복원).
+    const restoreFromKv = async () => {
+        lastSeen.clear();
+        const iter = await kv.keys();
+        for await (const key of iter) {
+            const entry = await kv.get(key);
+            if (!entry)
+                continue;
+            const rec = decodeJson(entry.value);
+            if (rec)
+                lastSeen.set(key, rec.ts);
+        }
+    };
+    const startLeading = async () => {
+        // 구독을 먼저 켜서 승격 직후 도착하는 명령을 놓치지 않는다(복원은 그 뒤).
+        // 리더만 구독한다 — 대기 인스턴스는 명령을 처리하지 않는다. 큐 그룹으로
+        // 리더 교대 순간의 중복 처리를 막는다.
+        const subscription = opts.nats.nc.subscribe(HUB_PRESENCE_SUBJECT, { queue: 'gaon-hub' });
+        sub = subscription;
+        (async () => {
+            for await (const m of subscription) {
+                const cmd = decodeJson(m.data);
+                if (!cmd)
+                    continue;
+                try {
+                    await handleCommand(cmd);
+                }
+                finally {
+                    // join/leave 는 request/reply — 반영 후 ack. heartbeat 는 reply 없음.
+                    if (m.reply)
+                        m.respond(encodeJson({ ok: true }));
+                }
+            }
+        })();
+        sweepTimer = setInterval(() => void sweep(), sweepMs);
+        // KV 로스터로 생존 추적 재구축(재시작 복원). 명령 처리와 병행돼도
+        // 안전하다(둘 다 lastSeen 을 덮어쓸 뿐).
+        await restoreFromKv();
+        opts.onState?.({ leader: true });
+    };
+    const stopLeading = () => {
+        sub?.unsubscribe();
+        sub = undefined;
+        if (sweepTimer)
+            clearInterval(sweepTimer);
+        sweepTimer = undefined;
+        lastSeen.clear();
+        opts.onState?.({ leader: false });
+    };
+    const lease = await leaseLeader({
+        nats: opts.nats,
+        key: 'hub.leader',
+        id: opts.id,
+        ttlMs: opts.ttlMs,
+        onElected: () => void startLeading(),
+        onRevoked: () => stopLeading(),
+    });
+    return {
+        get isLeader() {
+            return lease.isLeader;
+        },
+        async stop() {
+            stopLeading();
+            await lease.stop();
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,2 +1,9 @@
 export declare const version: string;
-export declare const status: "planned";
+export { connectNats, type NatsOptions, type GaonNats, type NatsConnection, type JetStreamClient, type KV, } from './nats.js';
+export { leaseLeader, type LeaseOptions, type LeaseHandle } from './lease.js';
+export { encodeSegment, decodeSegment, presenceKey, presenceChannelFilter, parsePresenceKey, channelSubject, } from './keys.js';
+export { channel, type ChannelDef, type ChannelContext, type ChannelAuthContext, type PresenceMember, } from './channel.js';
+export { createPresenceClient, PRESENCE_BUCKET, type PresenceClient, type PresenceClientOptions, } from './presence.js';
+export { createChannelRuntime, type ChannelRuntime, type ChannelRuntimeOptions, type SocketAdapter, type JoinRequest, type Connection, } from './runtime.js';
+export { runHub, type HubOptions, type HubHandle } from './hub.js';
+export { HUB_PRESENCE_SUBJECT, presenceEventSubject, encodeJson, decodeJson, type ClientMessage, type ServerFrame, type PresenceCommand, type PresenceEvent, type BroadcastEnvelope, } from './protocol.js';

package/dist/index.js

@@ -1,8 +1,24 @@
 /**
- * @gaonjs/async — Gaon NATS 통합 (잡·이벤트·스케줄러·채널·허브 프레즌스).
+ * @gaonjs/async — Gaon NATS 통합 (실시간: 채널·프레즌스·허브 / 비동기: 잡·이벤트).
  *
- * 실시간 세로 조각은 로드맵 M6. 현재는 개발 상태만 노출하는 스텁이다.
+ * 실시간 세로 조각(M6): 채널 브로드캐스트·프레즌스·허브가 NATS 를
+ * 백본으로 동작한다(§7). 잡·이벤트·스케줄러(M7)는 후속.
  */
-import { VERSION } from "@gaonjs/core";
+import { VERSION } from '@gaonjs/core';
 export const version = VERSION;
-export const status = "planned";
+// NATS 연결 (연결 + JetStream + KV)
+export { connectNats, } from './nats.js';
+// 리스 기반 리더 선출 (허브 HA · 스케줄러 공용)
+export { leaseLeader } from './lease.js';
+// subject/KV 키 인코딩
+export { encodeSegment, decodeSegment, presenceKey, presenceChannelFilter, parsePresenceKey, channelSubject, } from './keys.js';
+// 채널 정의 API (§7 · 파일=등록 관례)
+export { channel, } from './channel.js';
+// 프레즌스 클라이언트 (웹서버 측 · 허브 동기화)
+export { createPresenceClient, PRESENCE_BUCKET, } from './presence.js';
+// 채널 런타임 (웹서버 측 · 브로드캐스트 + 프레즌스 + 소켓 어댑터)
+export { createChannelRuntime, } from './runtime.js';
+// 허브 서버 (프레즌스 권위·중계 · 리더 선출 HA)
+export { runHub } from './hub.js';
+// 와이어 프로토콜 (프레임·subject·직렬화)
+export { HUB_PRESENCE_SUBJECT, presenceEventSubject, encodeJson, decodeJson, } from './protocol.js';

package/dist/keys.d.ts

@@ -0,0 +1,15 @@
+/** 임의 문자열을 subject/KV 세그먼트로 안전하게 인코딩(base64url). */
+export declare function encodeSegment(value: string): string;
+/** encodeSegment 의 역함수. */
+export declare function decodeSegment(token: string): string;
+/** 프레즌스 멤버의 KV 키: `presence.<채널>.<멤버>`. */
+export declare function presenceKey(channel: string, member: string): string;
+/** 한 채널의 모든 멤버를 훑는 KV 키 필터(와일드카드). */
+export declare function presenceChannelFilter(channel: string): string;
+/** presenceKey 를 되돌려 { channel, member } 를 얻는다. */
+export declare function parsePresenceKey(key: string): {
+    channel: string;
+    member: string;
+};
+/** 채널 브로드캐스트 subject: `gaon.chan.<채널>`. */
+export declare function channelSubject(channel: string): string;

package/dist/keys.js

@@ -0,0 +1,43 @@
+// @gaonjs/async · NATS subject/KV 키 인코딩 (§7 실시간)
+//
+// NATS 의 subject 토큰과 KV 키는 문자 집합이 제한된다: `.` 는 토큰
+// 구분자로 예약이고, 공백·`:`·`*`·`>` 등은 쓸 수 없다(실측 2026-07-22 —
+// `chan:room:user:42` 는 "invalid key" 로 거부됐다). 채널명은 파일명
+// 관례라 대개 안전하지만 멤버 ID(유저 키)는 임의 문자열일 수 있으므로,
+// 세그먼트를 base64url 로 인코딩해 항상 유효한 키를 만든다. base64url 의
+// 문자 집합(A–Z a–z 0–9 - _)은 전부 KV 키에 허용되고 `.` 를 만들지
+// 않으므로 구분자와 충돌하지 않는다.
+/** 임의 문자열을 subject/KV 세그먼트로 안전하게 인코딩(base64url). */
+export function encodeSegment(value) {
+    // 빈 문자열은 base64 가 ''(빈 세그먼트 → 유효하지 않은 키)이 되므로
+    // 단일 토큰 '_' 로 표기한다(디코드에서 되돌린다).
+    if (value === '')
+        return '_';
+    return Buffer.from(value, 'utf8').toString('base64url');
+}
+/** encodeSegment 의 역함수. */
+export function decodeSegment(token) {
+    if (token === '_')
+        return '';
+    return Buffer.from(token, 'base64url').toString('utf8');
+}
+/** 프레즌스 멤버의 KV 키: `presence.<채널>.<멤버>`. */
+export function presenceKey(channel, member) {
+    return `presence.${encodeSegment(channel)}.${encodeSegment(member)}`;
+}
+/** 한 채널의 모든 멤버를 훑는 KV 키 필터(와일드카드). */
+export function presenceChannelFilter(channel) {
+    return `presence.${encodeSegment(channel)}.*`;
+}
+/** presenceKey 를 되돌려 { channel, member } 를 얻는다. */
+export function parsePresenceKey(key) {
+    const parts = key.split('.');
+    if (parts.length !== 3 || parts[0] !== 'presence') {
+        throw new Error(`[@gaonjs/async] presence 키 형식이 아닙니다: ${key}`);
+    }
+    return { channel: decodeSegment(parts[1]), member: decodeSegment(parts[2]) };
+}
+/** 채널 브로드캐스트 subject: `gaon.chan.<채널>`. */
+export function channelSubject(channel) {
+    return `gaon.chan.${encodeSegment(channel)}`;
+}

package/dist/lease.d.ts

@@ -0,0 +1,31 @@
+import type { GaonNats } from './nats.js';
+export interface LeaseOptions {
+    readonly nats: GaonNats;
+    /** 리스 전용 KV 버킷. 생략 시 'gaon_lease'. */
+    readonly bucket?: string;
+    /** 리더 키. 역할마다 다르게(예: 'hub.leader', 'scheduler.leader'). */
+    readonly key: string;
+    /** 이 인스턴스 식별자(리더가 누구인지 값으로 저장). */
+    readonly id: string;
+    /** 리스 TTL(ms). 기본 5000. 리더가 죽고 이 시간 안에 승격이 일어난다. */
+    readonly ttlMs?: number;
+    /** 갱신 주기(ms). 기본 ttlMs/2 — 네트워크 지연 여유. */
+    readonly refreshMs?: number;
+    /** 리더가 됐을 때. */
+    onElected?(): void;
+    /** 리더에서 내려왔을 때(리스 상실). */
+    onRevoked?(): void;
+    /** 배경 루프 에러(연결 순단 등). 생략 시 무시하고 다음 틱 재시도. */
+    onError?(err: Error): void;
+}
+export interface LeaseHandle {
+    /** 현재 이 인스턴스가 리더인가. */
+    readonly isLeader: boolean;
+    /** 리더면 키를 비우고(즉시 승계 유도) 루프를 멈춘다. */
+    stop(): Promise<void>;
+}
+/**
+ * 리더 선출을 시작한다. 반환 핸들의 isLeader 로 상태를 읽고 stop() 으로
+ * 사임한다. 콜백(onElected/onRevoked)으로 리더십 전이를 통지한다.
+ */
+export declare function leaseLeader(opts: LeaseOptions): Promise<LeaseHandle>;

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/nats.d.ts

@@ -0,0 +1,26 @@
+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>;
+    /** 처리 중 메시지를 흘려보내고 연결을 닫는다(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,57 @@
+// @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 } 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 close() {
+            // drain 은 처리 중 메시지를 흘려보내고 닫는다. 이미 닫히는 중이거나
+            // in-flight 요청이 끊겨 throw 하면 강제 close 로 마무리한다.
+            try {
+                await nc.drain();
+            }
+            catch {
+                await nc.close().catch(() => { });
+            }
+        },
+    };
+}

package/dist/presence.d.ts

@@ -0,0 +1,23 @@
+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;
+    /** 하트비트 주기(ms). 기본 10000. 허브 만료 임계의 1/3 이하 권장. */
+    readonly heartbeatMs?: number;
+    /** 허브 응답 대기(ms). 기본 2000. 리더 부재(failover) 시 타임아웃. */
+    readonly requestTimeoutMs?: 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[]>;
+    /** 채널 프레즌스 델타 구독. 반환 함수로 해지. */
+    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,65 @@
+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 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;
+/** JSON 을 NATS 페이로드(Uint8Array)로. */
+export declare function encodeJson(value: unknown): Uint8Array;
+/** NATS 페이로드(Uint8Array)를 JSON 으로. 실패 시 undefined. */
+export declare function decodeJson<T>(bytes: Uint8Array): T | undefined;

package/dist/protocol.js

@@ -0,0 +1,28 @@
+// @gaonjs/async · 실시간 와이어 프로토콜 (§7 · 질문 19 — 프로토콜은 구현 단계)
+//
+// 세 경로의 메시지 형식을 한곳에 모은다:
+//  1) 클라이언트 ↔ 웹서버 (WebSocket JSON 프레임)
+//  2) 웹서버 → 허브 (프레즌스 등록/해제/하트비트 · NATS)
+//  3) 허브 → 전 웹서버 (프레즌스 델타 브로드캐스트 · NATS)
+// 그리고 채널 브로드캐스트(웹서버 ↔ 웹서버, NATS)까지.
+import { encodeSegment } from './keys.js';
+// ─── NATS subject 상수 ──────────────────────────────────────────────────
+/** 웹서버 → 허브 프레즌스 명령(허브가 큐 구독). */
+export const HUB_PRESENCE_SUBJECT = 'gaon.hub.presence';
+/** 허브 → 전 서버 프레즌스 델타(채널별). 채널명은 내부에서 인코딩한다. */
+export function presenceEventSubject(channel) {
+    return `gaon.presence.${encodeSegment(channel)}`;
+}
+/** JSON 을 NATS 페이로드(Uint8Array)로. */
+export function encodeJson(value) {
+    return new TextEncoder().encode(JSON.stringify(value));
+}
+/** NATS 페이로드(Uint8Array)를 JSON 으로. 실패 시 undefined. */
+export function decodeJson(bytes) {
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,36 @@
+import type { GaonNats } from './nats.js';
+import type { ChannelDef } from './channel.js';
+import { type PresenceClient } from './presence.js';
+/** 전송 계층이 구현하는 소켓 인터페이스. */
+export interface SocketAdapter {
+    send(text: string): void;
+    close(code?: number, reason?: string): void;
+}
+export interface ChannelRuntimeOptions {
+    readonly nats: GaonNats;
+    /** 이 웹서버 식별자. */
+    readonly server: string;
+    /** 프레즌스 클라이언트(주입). 생략 시 내부 생성. */
+    readonly presence?: PresenceClient;
+    readonly heartbeatMs?: number;
+}
+export interface JoinRequest<User = unknown> {
+    readonly channel: string;
+    readonly def: ChannelDef<User>;
+    readonly member: string;
+    readonly user: User | null;
+    readonly query: Readonly<Record<string, string>>;
+    readonly socket: SocketAdapter;
+}
+export interface Connection {
+    /** 클라이언트가 보낸 원시 텍스트 프레임을 처리한다. */
+    receive(raw: string): Promise<void>;
+    /** 연결 종료 — 프레즌스 해제·onLeave·구독 정리. */
+    leave(): Promise<void>;
+}
+export interface ChannelRuntime {
+    /** 인가 실패 시 소켓을 닫고 null 을 반환한다. */
+    join<User>(req: JoinRequest<User>): Promise<Connection | null>;
+    close(): Promise<void>;
+}
+export declare function createChannelRuntime(opts: ChannelRuntimeOptions): Promise<ChannelRuntime>;

package/dist/runtime.js

@@ -0,0 +1,124 @@
+// @gaonjs/async · 채널 런타임 (웹서버 측 · §7)
+//
+// 웹서버(serve 프로세스)마다 하나. 채널 정의(channel())의 훅을 구동하고,
+// 브로드캐스트는 NATS pub/sub 으로 전 인스턴스에 팬아웃하며(별도 어댑터
+// 불필요 §7 line 891), 프레즌스는 허브와 동기화한다. 소켓 전송은 어댑터로
+// 주입받아 전송 계층(@fastify/websocket)과 분리한다 — 런타임 자체는 실
+// NATS 로 소켓 없이도 테스트할 수 있다.
+import { channelSubject } from './keys.js';
+import { encodeJson, decodeJson } from './protocol.js';
+import { createPresenceClient } from './presence.js';
+export async function createChannelRuntime(opts) {
+    const nats = opts.nats;
+    const presence = opts.presence ??
+        (await createPresenceClient({ nats, server: opts.server, heartbeatMs: opts.heartbeatMs }));
+    const ownPresence = !opts.presence;
+    const channels = new Map();
+    const sendFrame = (socket, frame) => {
+        socket.send(JSON.stringify(frame));
+    };
+    const deliverToChannel = (channel, frame) => {
+        const state = channels.get(channel);
+        if (!state)
+            return;
+        for (const c of state.conns)
+            sendFrame(c.socket, frame);
+    };
+    /** 채널 인프라(브로드캐스트·프레즌스 구독)를 필요 시 최초 1회 만든다. */
+    const ensureChannel = (channel) => {
+        const existing = channels.get(channel);
+        if (existing)
+            return existing;
+        // 브로드캐스트: 모든 서버가 같은 subject 를 구독 → 발행 1건이 전
+        // 인스턴스의 로컬 소켓으로 팬아웃(발행자 자신 포함, 중복 없음).
+        const broadcastSub = nats.nc.subscribe(channelSubject(channel));
+        (async () => {
+            for await (const m of broadcastSub) {
+                const env = decodeJson(m.data);
+                if (env)
+                    deliverToChannel(channel, { t: 'msg', data: env.data });
+            }
+        })();
+        // 프레즌스 델타: 허브 방송을 로컬 소켓으로 전달.
+        const unsubPresence = presence.subscribe(channel, (ev) => {
+            if (ev.type === 'join')
+                deliverToChannel(channel, { t: 'presence:join', member: ev.member });
+            else
+                deliverToChannel(channel, { t: 'presence:leave', member: ev.member });
+        });
+        const state = { conns: new Set(), broadcastSub, unsubPresence };
+        channels.set(channel, state);
+        return state;
+    };
+    const teardownIfEmpty = (channel) => {
+        const state = channels.get(channel);
+        if (!state || state.conns.size > 0)
+            return;
+        state.broadcastSub.unsubscribe();
+        state.unsubPresence();
+        channels.delete(channel);
+    };
+    return {
+        async join(req) {
+            // 런타임은 채널을 타입 소거해 다룬다(전송 계층이 User 를 알 필요 없음).
+            const def = req.def;
+            const authCtx = { channel: req.channel, user: req.user, query: req.query };
+            if (def.authorize) {
+                const ok = await def.authorize(authCtx);
+                if (!ok) {
+                    sendFrame(req.socket, { t: 'error', message: '채널 인가 거부' });
+                    req.socket.close(4401, 'unauthorized');
+                    return null;
+                }
+            }
+            const info = def.presenceInfo ? def.presenceInfo(authCtx) : {};
+            const ctx = {
+                channel: req.channel,
+                member: req.member,
+                user: req.user,
+                query: req.query,
+                send: (data) => sendFrame(req.socket, { t: 'msg', data }),
+                broadcast: (data) => {
+                    const env = { data };
+                    nats.nc.publish(channelSubject(req.channel), encodeJson(env));
+                },
+                presence: () => presence.list(req.channel),
+            };
+            const state = ensureChannel(req.channel);
+            const conn = { member: req.member, socket: req.socket, ctx, def };
+            state.conns.add(conn);
+            // 허브에 등록(KV 반영까지 대기) → 초기 스냅샷을 KV 권위에서 읽어 전송.
+            await presence.join(req.channel, req.member, info);
+            const members = await presence.list(req.channel);
+            sendFrame(req.socket, { t: 'joined', channel: req.channel, member: req.member });
+            sendFrame(req.socket, { t: 'presence', members });
+            await def.onJoin?.(ctx);
+            let left = false;
+            return {
+                async receive(raw) {
+                    const msg = decodeJson(new TextEncoder().encode(raw));
+                    if (msg?.t === 'msg')
+                        await def.onMessage?.(ctx, msg.data);
+                },
+                async leave() {
+                    if (left)
+                        return;
+                    left = true;
+                    await presence.leave(req.channel, req.member);
+                    await def.onLeave?.(ctx);
+                    state.conns.delete(conn);
+                    teardownIfEmpty(req.channel);
+                },
+            };
+        },
+        async close() {
+            for (const [, state] of channels) {
+                state.broadcastSub.unsubscribe();
+                state.unsubPresence();
+            }
+            channels.clear();
+            if (ownPresence)
+                await presence.close();
+        },
+    };
+}

package/package.json

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