@spfn/core 0.2.0-beta.20 → 0.2.0-beta.22

package/dist/{types-B-lVqv6b.d.ts → types-DAVwA-_7.d.ts}

@@ -22,6 +22,15 @@ import { E as EventRouterDef, I as InferEventNames, b as InferEventPayload } fro
  * manager.destroy();
  * ```
  */
+/**
+ * Minimal cache client interface (compatible with ioredis Redis | Cluster)
+ */
+type CacheClient = {
+    set(key: string, value: string, ...args: any[]): Promise<any>;
+    getdel?(key: string): Promise<string | null>;
+    get(key: string): Promise<string | null>;
+    del(key: string | string[]): Promise<number>;
+};
 /**
  * Stored SSE token data
  */
@@ -62,6 +71,31 @@ interface SSETokenManagerConfig {
      */
     cleanupInterval?: number;
 }
+/**
+ * Redis/Valkey-backed token store for multi-instance deployments.
+ *
+ * Uses SET EX for automatic TTL expiry and GETDEL for atomic one-time consumption.
+ * No cleanup needed — Redis handles expiration automatically.
+ *
+ * @example
+ * ```typescript
+ * import { getCache } from '@spfn/core/cache';
+ *
+ * const cache = getCache();
+ * if (cache) {
+ *     const store = new CacheTokenStore(cache);
+ *     const manager = new SSETokenManager({ store });
+ * }
+ * ```
+ */
+declare class CacheTokenStore implements SSETokenStore {
+    private cache;
+    private prefix;
+    constructor(cache: CacheClient);
+    set(token: string, data: SSEToken): Promise<void>;
+    consume(token: string): Promise<SSEToken | null>;
+    cleanup(): Promise<void>;
+}
 declare class SSETokenManager {
     private store;
     private ttl;
@@ -237,10 +271,17 @@ interface SSEClientConfig {
      * Called on every (re)connect. The returned token is appended
      * to the SSE URL as `?token=...`.
      *
+     * For automatic token acquisition via RPC proxy, use `createAuthSSEClient` instead.
+     *
      * @example
      * ```typescript
+     * // Recommended: use createAuthSSEClient for automatic token handling
+     * import { createAuthSSEClient } from '@spfn/core/event/sse/client';
+     * const client = createAuthSSEClient<EventRouter>();
+     *
+     * // Manual: provide acquireToken directly
      * acquireToken: async () => {
-     *     const res = await fetch('/api/events/token', {
+     *     const res = await fetch('/api/rpc/eventsToken', {
      *         method: 'POST',
      *         credentials: 'include',
      *     });
@@ -295,4 +336,4 @@ type SSEConnectionState = 'connecting' | 'open' | 'closed' | 'error';
  */
 type SSEUnsubscribe = () => void;
 
-export { type SSEHandlerConfig as S, type SSEAuthConfig as a, SSETokenManager as b, type SSEToken as c, type SSETokenStore as d, type SSETokenManagerConfig as e, type SSEMessage as f, type SSEHandlerAuthConfig as g, type SSEClientConfig as h, type SSEEventHandler as i, type SSEEventHandlers as j, type SSESubscribeOptions as k, type SSEConnectionState as l, type SSEUnsubscribe as m };
+export { CacheTokenStore as C, type SSEHandlerConfig as S, type SSEAuthConfig as a, SSETokenManager as b, type SSEToken as c, type SSETokenStore as d, type SSETokenManagerConfig as e, type SSEMessage as f, type SSEHandlerAuthConfig as g, type SSEClientConfig as h, type SSEEventHandler as i, type SSEEventHandlers as j, type SSESubscribeOptions as k, type SSEConnectionState as l, type SSEUnsubscribe as m };

package/docs/event.md

@@ -195,21 +195,30 @@ unsubscribe();
 
 ### With Authentication
 
+Use `createAuthSSEClient` which handles token acquisition automatically via the RPC proxy:
+
 ```typescript
-const client = createSSEClient<EventRouter>({
-    acquireToken: async () =>
-    {
-        const res = await fetch('/api/events/token', {
-            method: 'POST',
-            credentials: 'include',
-        });
-        const data = await res.json();
-        return data.token;
-    },
+import { createAuthSSEClient } from '@spfn/core/event/sse/client';
+import type { EventRouter } from '@/server/events/router';
+
+const client = createAuthSSEClient<EventRouter>();
+```
+
+This requires `eventRouteMap` to be merged into your RPC proxy (one-time setup):
+
+```typescript
+// app/api/rpc/[routeName]/route.ts
+import '@spfn/auth/nextjs/api';
+import { createRpcProxy } from '@spfn/core/nextjs/server';
+import { eventRouteMap } from '@spfn/core/event';
+import { routeMap } from '@/generated/route-map';
+
+export const { GET, POST } = createRpcProxy({
+    routeMap: { ...routeMap, ...eventRouteMap },
 });
 ```
 
-`acquireToken` is called on every (re)connect — one-time tokens are handled automatically.
+Tokens are acquired on every (re)connect — one-time tokens are handled automatically.
 
 ## Simple Subscribe Helper
 
@@ -298,6 +307,17 @@ if (cache)
 await userCreated.emit({ userId: '123' });
 ```
 
+### SSE Token Store
+
+SSE 토큰 저장소도 멀티 인스턴스에서 공유되어야 합니다.
+캐시가 연결되면 `CacheTokenStore`가 **자동 사용**됩니다.
+
+| 환경 | 토큰 저장소 | 설정 |
+|------|------------|------|
+| `CACHE_URL` 없음 | `InMemoryTokenStore` | 자동 |
+| `CACHE_URL` 설정됨 | `CacheTokenStore` | 자동 감지 |
+| 커스텀 | `SSETokenStore` 구현 | `auth.store` 옵션 |
+
 ## API Reference
 
 ### defineEvent(name)

package/docs/nextjs.md

@@ -8,12 +8,14 @@ RPC proxy and type-safe API client for Next.js.
 
 ```typescript
 // app/api/rpc/[routeName]/route.ts
-import { appRouter } from '@/server/server.config';
+import '@spfn/auth/nextjs/api';
 import { createRpcProxy } from '@spfn/core/nextjs/server';
+import { authRouteMap } from '@spfn/auth';
+import { eventRouteMap } from '@spfn/core/event';
+import { routeMap } from '@/generated/route-map';
 
-export const { GET, POST, PUT, PATCH, DELETE } = createRpcProxy({
-    router: appRouter,
-    apiUrl: process.env.SPFN_API_URL || 'http://localhost:8790'
+export const { GET, POST } = createRpcProxy({
+    routeMap: { ...routeMap, ...authRouteMap, ...eventRouteMap },
 });
 ```
 
@@ -135,7 +137,7 @@ const updated = await api.updateUser.call({
 
 ```typescript
 export const { GET, POST } = createRpcProxy({
-    router: appRouter,
+    routeMap: { ...routeMap, ...authRouteMap },
     apiUrl: process.env.SPFN_API_URL,
     interceptors: {
         request: async (request, context) => {
@@ -208,6 +210,10 @@ SPFN_API_URL=http://localhost:8790
 
 # For production
 SPFN_API_URL=https://api.example.com
+
+# RPC proxy timeout (AbortController, default: 120s)
+# Should be shorter than FETCH_HEADERS_TIMEOUT for meaningful 504 responses
+RPC_PROXY_TIMEOUT=120000
 ```
 
 ## Best Practices

package/docs/server.md

@@ -246,12 +246,30 @@ if (shutdown.isShuttingDown())
 
 ```typescript
 defineServerConfig()
+    .timeout({
+        request: 120000,    // SERVER_TIMEOUT (default: 120s)
+        keepAlive: 65000,   // SERVER_KEEPALIVE_TIMEOUT (default: 65s)
+        headers: 60000,     // SERVER_HEADERS_TIMEOUT (default: 60s)
+    })
+    .fetchTimeout({
+        connect: 10000,     // FETCH_CONNECT_TIMEOUT (default: 10s)
+        headers: 300000,    // FETCH_HEADERS_TIMEOUT (default: 300s)
+        body: 300000,       // FETCH_BODY_TIMEOUT (default: 300s)
+    })
     .shutdown({
-        timeout: 280000,  // 280s (default: k8s 300s - 5s preStop - 15s margin)
+        timeout: 280000,    // SHUTDOWN_TIMEOUT (default: 280s)
     })
     .build();
 ```
 
+For long-running AI workloads, increase fetch timeouts:
+
+```bash
+FETCH_HEADERS_TIMEOUT=600000   # 10 minutes
+FETCH_BODY_TIMEOUT=600000      # 10 minutes
+RPC_PROXY_TIMEOUT=580000       # Must be < FETCH_HEADERS_TIMEOUT
+```
+
 AI 파이프라인 등 장기 작업이 있는 앱은 Helm chart과 함께 조정:
 
 ```yaml
@@ -297,8 +315,42 @@ DATABASE_READ_URL=postgresql://replica:5432/mydb
 # Redis
 REDIS_URL=redis://localhost:6379
 
+# Server Timeout (inbound HTTP server)
+SERVER_TIMEOUT=120000           # Request timeout (default: 120s)
+SERVER_KEEPALIVE_TIMEOUT=65000  # Keep-alive timeout (default: 65s)
+SERVER_HEADERS_TIMEOUT=60000    # Headers timeout, Slowloris defense (default: 60s)
+
+# Fetch Timeout (outbound HTTP via undici global dispatcher)
+FETCH_CONNECT_TIMEOUT=10000     # TCP connection timeout (default: 10s)
+FETCH_HEADERS_TIMEOUT=300000    # Response headers timeout (default: 300s)
+FETCH_BODY_TIMEOUT=300000       # Body chunk interval timeout (default: 300s)
+
+# RPC Proxy Timeout (Next.js → Backend)
+RPC_PROXY_TIMEOUT=120000        # AbortController timeout (default: 120s)
+
 # Shutdown
-SHUTDOWN_TIMEOUT=280000  # Milliseconds (default: 280s)
+SHUTDOWN_TIMEOUT=280000         # Graceful shutdown timeout (default: 280s)
+```
+
+### Timeout Architecture
+
+```
+Request flow:
+Client → Next.js API Route → fetch() → SPFN Backend
+
+Timeout layers:
+┌──────────────────────────────────────────────────────┐
+│ RPC_PROXY_TIMEOUT (AbortController)     default 120s │ ← shortest, returns 504
+│ FETCH_HEADERS_TIMEOUT (undici)          default 300s │ ← fetch socket level
+│ FETCH_BODY_TIMEOUT (undici)             default 300s │ ← body chunk interval
+│ FETCH_CONNECT_TIMEOUT (undici)          default  10s │ ← TCP connection
+├──────────────────────────────────────────────────────┤
+│ SERVER_TIMEOUT (backend server.timeout) default 120s │ ← backend HTTP server
+│ SERVER_HEADERS_TIMEOUT                  default  60s │ ← Slowloris defense
+│ SERVER_KEEPALIVE_TIMEOUT                default  65s │ ← idle connection
+└──────────────────────────────────────────────────────┘
+
+Rule: RPC_PROXY_TIMEOUT < FETCH_HEADERS_TIMEOUT
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spfn/core",
-  "version": "0.2.0-beta.20",
+  "version": "0.2.0-beta.22",
   "description": "SPFN Framework Core - File-based routing, transactions, repository pattern",
   "type": "module",
   "exports": {