@gaonjs/web 0.2.0 → 0.2.2

package/dist/app.d.ts

@@ -1,9 +1,11 @@
 import { type FastifyInstance, type FastifyServerOptions } from 'fastify';
 import { type FastifyCorsOptions } from '@fastify/cors';
+import { type GaonNats } from '@gaonjs/async';
 import type { RouteDef } from './routes.js';
 import { type DispatchOptions } from './dispatch.js';
 import { type AppSessionOptions } from './session.js';
 import { type AuthOptions, type JwtAuthOptions } from './auth.js';
+import { type ChannelMap } from './websocket.js';
 /** 한 앱 정의 — 프리픽스(생략 시 관례)·라우트·컨트롤러 맵. */
 export interface AppSpec {
     readonly name: string;
@@ -20,6 +22,11 @@ export interface AppSpec {
     readonly auth?: AuthOptions | JwtAuthOptions;
     /** 요청별 컨텍스트 확장(추가 훅). */
     readonly dispatch?: DispatchOptions;
+    /**
+     * 실시간 채널(§7 · M6). apps/<app>/channels/<이름>.ts 의 default export 를
+     * 이름별로 모은 맵. realtime(NATS)이 설정된 경우에만 활성.
+     */
+    readonly channels?: ChannelMap;
 }
 export interface SecurityOptions {
     /** CORS 설정. 기본은 same-origin 만 허용(origin:false). false 로 완전 비활성. */
@@ -38,6 +45,19 @@ export interface CreateAppOptions {
     readonly cookieSecret?: string;
     readonly security?: SecurityOptions;
     readonly fastify?: FastifyServerOptions;
+    /**
+     * 실시간 백본(§7 · M6). 설정하면 채널(ws)이 활성화된다. nats 커넥션은
+     * 호출자가 소유·종료한다(여기선 채널 런타임만 onClose 로 정리). server 는
+     * 프레즌스 식별자(생략 시 hostname#pid). heartbeatMs 는 프레즌스 하트비트
+     * 주기(생략 시 런타임 기본 10000) — 허브 만료 임계의 1/3 이하로 둔다.
+     */
+    readonly realtime?: {
+        readonly nats: GaonNats;
+        readonly server?: string;
+        /** 허브 TCP 주소 'host:port'(errata E-2). 생략 시 NATS KV 공지 발견. */
+        readonly hubAddr?: string;
+        readonly heartbeatMs?: number;
+    };
 }
 /**
  * 앱 스펙들로 Fastify 인스턴스를 만든다. 쿠키·CORS·rate limit(보안 기본값)을

package/dist/app.js

@@ -10,9 +10,14 @@ import Fastify from 'fastify';
 import cookie from '@fastify/cookie';
 import cors from '@fastify/cors';
 import rateLimit from '@fastify/rate-limit';
+import { hostname } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { createChannelRuntime } from '@gaonjs/async';
 import { prefixFor, registerApp } from './dispatch.js';
 import { registerSession } from './session.js';
 import { jwtAuthAugment, sessionAuthAugment } from './auth.js';
+import { registerChannels, registerWebSocketSupport, } from './websocket.js';
+import { verifyToken } from './jwt.js';
 /**
  * 앱 스펙들로 Fastify 인스턴스를 만든다. 쿠키·CORS·rate limit(보안 기본값)을
  * 켜고, 각 앱의 라우트를 프리픽스 아래 등록한다. listen 은 호출자가 한다.
@@ -20,6 +25,22 @@ import { jwtAuthAugment, sessionAuthAugment } from './auth.js';
 export async function createApp(opts) {
     const app = Fastify(opts.fastify);
     const security = opts.security ?? {};
+    // 실시간 채널 런타임 — 프로세스당 하나(전 앱 공유, NATS 는 호출자 소유).
+    let runtime;
+    if (opts.realtime) {
+        const server = opts.realtime.server ?? `${hostname()}#${process.pid}`;
+        runtime = await createChannelRuntime({
+            nats: opts.realtime.nats,
+            server,
+            hubAddr: opts.realtime.hubAddr,
+            heartbeatMs: opts.realtime.heartbeatMs,
+        });
+        // 전역 upgrade 훅은 루트에서 한 번만 — 채널 라우트는 앱 스코프에서 정의.
+        await registerWebSocketSupport(app);
+        app.addHook('onClose', async () => {
+            await runtime?.close();
+        });
+    }
     // 쿠키 — 세션·CSRF·서명 쿠키의 토대. secret 은 서명 쿠키에만 필요.
     await app.register(cookie, { secret: opts.cookieSecret ?? process.env.GAON_COOKIE_SECRET });
     // CORS — 기본 same-origin(origin:false). 크로스 오리진은 명시 설정으로만.
@@ -39,6 +60,14 @@ export async function createApp(opts) {
             if (spec.session)
                 await registerSession(scope, spec.name, prefix, spec.session);
             registerApp(scope, { name: spec.name, routes: spec.routes, controllers: spec.controllers }, dispatchOptionsFor(spec, opts.version));
+            // 채널(ws)은 세션과 같은 스코프에 등록 — 연결이 앱 세션으로 인증된다.
+            if (runtime && spec.channels && Object.keys(spec.channels).length > 0) {
+                registerChannels(scope, {
+                    runtime,
+                    channels: spec.channels,
+                    resolveMember: memberResolverFor(spec),
+                });
+            }
         }, { prefix });
     }
     return app;
@@ -61,3 +90,35 @@ function dispatchOptionsFor(spec, version) {
         : undefined;
     return { version, loginRedirect, ...spec.dispatch, augment };
 }
+/**
+ * 채널 연결의 멤버/사용자를 앱 인증 방식에 맞춰 해석한다. 세션 앱은
+ * session.userId 로, JWT 앱은 쿼리(access_token)로 인증한다(웹소켓은
+ * 커스텀 헤더를 못 실으므로 API 앱은 쿼리 토큰이 관례다). 비로그인은
+ * 익명 연결(공개 채널 허용).
+ */
+function memberResolverFor(spec) {
+    const auth = spec.auth;
+    if (!auth)
+        return undefined;
+    if ('strategy' in auth && auth.strategy === 'jwt') {
+        return async (request) => {
+            const token = request.query?.access_token;
+            if (typeof token === 'string') {
+                const payload = await verifyToken(auth.secret, token);
+                if (payload && payload.typ === 'access' && typeof payload.sub === 'string') {
+                    const user = (await auth.loadUser(payload.sub)) ?? null;
+                    return { member: `user:${payload.sub}`, user };
+                }
+            }
+            return { member: `conn:${randomUUID()}`, user: null };
+        };
+    }
+    const sessionAuth = auth;
+    return async (request) => {
+        const uid = request.session?.userId;
+        if (uid == null)
+            return { member: `conn:${randomUUID()}`, user: null };
+        const user = (await sessionAuth.loadUser(uid)) ?? null;
+        return { member: `user:${String(uid)}`, user };
+    };
+}

package/dist/index.d.ts

@@ -11,3 +11,4 @@ export { signToken, verifyToken, type TokenType } from "./jwt.js";
 export { hashPassword, verifyPassword } from "./password.js";
 export { renderInertia, inertiaRedirect, type InertiaPage, type InertiaOptions, } from "./inertia.js";
 export { serializeProps } from "./serialize.js";
+export { registerChannels, registerWebSocketSupport, type ChannelMap, type MemberIdentity, type MemberResolver, type RegisterChannelsOptions, } from "./websocket.js";

package/dist/index.js

@@ -30,3 +30,5 @@ export { hashPassword, verifyPassword } from "./password.js";
 export { renderInertia, inertiaRedirect, } from "./inertia.js";
 // 응답 경계 직렬화 (hidden 제외 §4.2)
 export { serializeProps } from "./serialize.js";
+// 실시간 채널 전송 (WebSocket · §7 M6)
+export { registerChannels, registerWebSocketSupport, } from "./websocket.js";

package/dist/websocket.d.ts

@@ -0,0 +1,28 @@
+import type { FastifyInstance, FastifyRequest } from 'fastify';
+import type { ChannelDef, ChannelRuntime } from '@gaonjs/async';
+/**
+ * @fastify/websocket 을 등록한다. 전역 upgrade 훅을 걸므로 서버당 **한 번만**
+ * (루트에서) 호출해야 한다. 라우트(registerChannels)는 이후 어느 스코프에서든
+ * 정의할 수 있다.
+ */
+export declare function registerWebSocketSupport(app: FastifyInstance): Promise<void>;
+export type ChannelMap = Record<string, ChannelDef<unknown>>;
+/** 연결 주체(멤버 식별자 + 인증 사용자). */
+export interface MemberIdentity {
+    readonly member: string;
+    readonly user: unknown;
+}
+export type MemberResolver = (request: FastifyRequest) => Promise<MemberIdentity> | MemberIdentity;
+export interface RegisterChannelsOptions {
+    readonly runtime: ChannelRuntime;
+    readonly channels: ChannelMap;
+    /** 연결 주체 해석(세션·JWT). 생략 시 세션 userId 또는 익명. */
+    readonly resolveMember?: MemberResolver;
+    /** ws 라우트 경로(스코프 프리픽스 이후). 기본 '/gaon/ws/:channel'. */
+    readonly path?: string;
+}
+/**
+ * 앱 스코프에 채널 ws 라우트를 등록한다. 연결마다 멤버를 해석하고 런타임에
+ * join 을 위임하며, 소켓 메시지를 채널 정의의 onMessage 로 흘린다.
+ */
+export declare function registerChannels(scope: FastifyInstance, opts: RegisterChannelsOptions): void;

package/dist/websocket.js

@@ -0,0 +1,103 @@
+// @gaonjs/web · WebSocket 전송 계층 (§7 실시간 · M6)
+//
+// 채널의 전송을 @fastify/websocket 으로 붙인다. 채널 정의(@gaonjs/async 의
+// channel())는 전송을 모르고, 여기서 raw WebSocket 을 SocketAdapter 로 감싸
+// ChannelRuntime 에 넘긴다. 라우트는 앱 캡슐화 스코프 안에 등록되므로
+// 세션(M5)이 그대로 살아 있어 연결을 인증할 수 있다.
+//
+// 경로 관례: `<앱 프리픽스>/gaon/ws/:channel`. 채널명은 apps/*/channels/
+// 파일명이다(파일=등록). 알 수 없는 채널은 4404 로 닫는다.
+import websocketPlugin from '@fastify/websocket';
+import { randomUUID } from 'node:crypto';
+/**
+ * @fastify/websocket 을 등록한다. 전역 upgrade 훅을 걸므로 서버당 **한 번만**
+ * (루트에서) 호출해야 한다. 라우트(registerChannels)는 이후 어느 스코프에서든
+ * 정의할 수 있다.
+ */
+export async function registerWebSocketSupport(app) {
+    await app.register(websocketPlugin);
+}
+/** 세션 userId 로 멤버를 정한다. 비로그인은 익명 연결 id. */
+async function defaultResolveMember(request) {
+    const sess = request.session;
+    const uid = sess?.userId;
+    if (uid != null)
+        return { member: `user:${String(uid)}`, user: { id: uid } };
+    return { member: `conn:${randomUUID()}`, user: null };
+}
+function queryOf(request) {
+    const q = request.query;
+    const out = {};
+    if (q)
+        for (const [k, v] of Object.entries(q))
+            if (typeof v === 'string')
+                out[k] = v;
+    return out;
+}
+/**
+ * 앱 스코프에 채널 ws 라우트를 등록한다. 연결마다 멤버를 해석하고 런타임에
+ * join 을 위임하며, 소켓 메시지를 채널 정의의 onMessage 로 흘린다.
+ */
+export function registerChannels(scope, opts) {
+    // @fastify/websocket 은 registerWebSocketSupport 로 루트에서 이미 등록됐다고
+    // 가정한다(전역 upgrade 훅 중복 방지). 여기서는 채널 라우트만 정의한다.
+    const resolve = opts.resolveMember ?? defaultResolveMember;
+    const routePath = opts.path ?? '/gaon/ws/:channel';
+    scope.get(routePath, { websocket: true }, (socket, request) => {
+        const name = request.params.channel ?? '';
+        const def = opts.channels[name];
+        if (!def) {
+            socket.close(4404, 'unknown channel');
+            return;
+        }
+        const adapter = {
+            send: (text) => {
+                if (socket.readyState === socket.OPEN)
+                    socket.send(text);
+            },
+            close: (code, reason) => socket.close(code, reason),
+        };
+        // join 은 비동기(허브 왕복). 그 사이 도착한 메시지는 버퍼링했다가 재생한다.
+        const pending = [];
+        let conn = null;
+        let ready = false;
+        let closed = false;
+        socket.on('message', (raw) => {
+            const text = typeof raw === 'string' ? raw : String(raw);
+            if (ready && conn)
+                void conn.receive(text);
+            else
+                pending.push(text);
+        });
+        socket.on('close', () => {
+            closed = true;
+            if (conn)
+                void conn.leave();
+        });
+        void (async () => {
+            const { member, user } = await resolve(request);
+            const c = await opts.runtime.join({
+                channel: name,
+                def,
+                member,
+                user,
+                query: queryOf(request),
+                socket: adapter,
+            });
+            if (!c)
+                return; // 인가 거부 — 런타임이 소켓을 닫았다.
+            conn = c;
+            if (closed) {
+                void c.leave(); // join 도중 이미 끊겼으면 즉시 정리.
+                return;
+            }
+            ready = true;
+            for (const t of pending)
+                void c.receive(t);
+            pending.length = 0;
+        })().catch((err) => {
+            adapter.send(JSON.stringify({ t: 'error', message: err instanceof Error ? err.message : String(err) }));
+            socket.close(1011, 'join failed');
+        });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/web",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Gaon 웹 레이어: Fastify 통합·파일 기반 라우팅·보안 기본값 (구현 예정)",
   "type": "module",
   "license": "MIT",
@@ -29,10 +29,12 @@
     "@fastify/csrf-protection": "^8.0.0",
     "@fastify/rate-limit": "^11.1.0",
     "@fastify/session": "^11.1.2",
+    "@fastify/websocket": "^11.0.2",
     "bcryptjs": "^3.0.3",
     "fastify": "^5.10.0",
     "ioredis": "^5.11.1",
     "jose": "^6.2.4",
+    "@gaonjs/async": "0.2.1",
     "@gaonjs/core": "0.1.3"
   },
   "scripts": {