@spfn/core 0.2.0-beta.4 → 0.2.0-beta.42

package/docs/server.md

@@ -0,0 +1,429 @@
+# Server
+
+HTTP server configuration with three-level progressive customization.
+
+## Quick Start
+
+```typescript
+// src/server/index.ts
+import { startServer } from '@spfn/core/server';
+
+await startServer();
+```
+
+---
+
+## Configuration Levels
+
+### Level 1: Zero Config
+
+No configuration needed. Uses sensible defaults:
+
+```typescript
+import { startServer } from '@spfn/core/server';
+
+await startServer();
+// Port: 4000 (or process.env.PORT)
+// Host: localhost (or process.env.HOST)
+// Middleware: Logger + CORS + ErrorHandler
+// Infrastructure: Auto-init from env vars
+```
+
+### Level 2: Partial Customization
+
+Create `src/server/server.config.ts`:
+
+```typescript
+import { defineServerConfig, defineRouter } from '@spfn/core/server';
+import * as userRoutes from './routes/users';
+import * as postRoutes from './routes/posts';
+import { authMiddleware, rateLimiter } from './middlewares';
+
+const appRouter = defineRouter({
+    ...userRoutes,
+    ...postRoutes
+});
+
+export default defineServerConfig()
+    .port(8790)
+    .host('0.0.0.0')
+    .routes(appRouter)
+    .middlewares([authMiddleware, rateLimiter])
+    .build();
+
+export type AppRouter = typeof appRouter;
+```
+
+### Level 3: Full Control
+
+Create `src/server/app.ts` for custom Hono setup:
+
+```typescript
+import { Hono } from 'hono';
+import { timing } from 'hono/timing';
+import { compress } from 'hono/compress';
+import type { AppFactory } from '@spfn/core/server';
+
+export default (async () => {
+    const app = new Hono();
+
+    // Custom middleware
+    app.use('*', timing());
+    app.use('*', compress());
+
+    // Custom routes
+    app.get('/custom', (c) => c.json({ custom: true }));
+
+    return app;
+}) satisfies AppFactory;
+```
+
+Then in `server.config.ts`:
+
+```typescript
+export default defineServerConfig()
+    .routes(appRouter)  // Routes registered to your custom app
+    .build();
+```
+
+---
+
+## Configuration Builder
+
+### Basic Options
+
+```typescript
+defineServerConfig()
+    .port(8790)                    // Server port
+    .host('0.0.0.0')               // Server host
+    .routes(appRouter)             // Router
+    .middlewares([...])            // Global middlewares
+    .build();
+```
+
+### Infrastructure Options
+
+```typescript
+defineServerConfig()
+    .database(true)                // Enable database (default: auto from env)
+    .redis(true)                   // Enable Redis (default: auto from env)
+    .build();
+```
+
+### CORS Options
+
+```typescript
+defineServerConfig()
+    .cors({
+        origin: ['https://example.com'],
+        methods: ['GET', 'POST', 'PUT', 'DELETE'],
+        credentials: true
+    })
+    .build();
+```
+
+### Lifecycle Hooks
+
+```typescript
+defineServerConfig()
+    .beforeStart(async () => {
+        // Before server starts
+        console.log('Initializing...');
+    })
+    .afterStart(async (server) => {
+        // After server is running
+        console.log(`Server running on port ${server.port}`);
+    })
+    .beforeShutdown(async () => {
+        // Before graceful shutdown
+        console.log('Shutting down...');
+    })
+    .build();
+```
+
+---
+
+## Router
+
+### Define Router
+
+```typescript
+import { defineRouter } from '@spfn/core/route';
+
+export const appRouter = defineRouter({
+    getUser,
+    createUser,
+    updateUser,
+    deleteUser
+});
+```
+
+### Nested Routers
+
+```typescript
+export const appRouter = defineRouter({
+    users: defineRouter({
+        get: getUser,
+        create: createUser,
+        list: getUsers
+    }),
+    posts: defineRouter({
+        get: getPost,
+        create: createPost
+    })
+});
+```
+
+### Type Export
+
+```typescript
+// server.config.ts
+export type AppRouter = typeof appRouter;
+
+// Use in Next.js client
+import type { AppRouter } from '@/server/server.config';
+import { createApi } from '@spfn/core/nextjs';
+
+const api = createApi<AppRouter>();
+```
+
+---
+
+## Graceful Shutdown
+
+Automatic graceful shutdown with drain behavior (AWS drain style):
+
+```
+SIGTERM
+  │
+  ├─ Phase 1: server.close()              ← 새 연결 거부, 진행 중 요청 대기
+  ├─ Phase 2: stopBoss()                   ← pg-boss 작업 정리
+  ├─ Phase 3: ShutdownManager.execute()
+  │     ├─ drain: tracked operations 완료 대기
+  │     └─ hooks: 등록된 훅 순서대로 실행
+  ├─ Phase 4: beforeShutdown lifecycle     ← 기존 lifecycle 호환
+  ├─ Phase 5: closeDatabase / closeCache
+  └─ process.exit(0)
+```
+
+**Signals handled:** `SIGTERM`, `SIGINT`
+
+### ShutdownManager
+
+모듈별 독립적인 shutdown 훅 등록과 장기 작업 추적:
+
+```typescript
+import { getShutdownManager } from '@spfn/core/server';
+
+const shutdown = getShutdownManager();
+
+// 1. Shutdown 훅 등록 — 모듈별 독립 cleanup
+shutdown.onShutdown('ai-client', async () =>
+{
+    await openaiClient.close();
+}, { timeout: 5000, order: 10 });
+
+shutdown.onShutdown('search-index', async () =>
+{
+    await elasticClient.close();
+}, { order: 20 });
+
+// 2. 장기 작업 추적 — shutdown 시 완료까지 대기
+const result = await shutdown.trackOperation(
+    'ai-generate',
+    aiService.generate(prompt)
+);
+// shutdown 중이면 자동으로 throw → 503
+
+// 3. Shutdown 상태 확인
+if (shutdown.isShuttingDown())
+{
+    return c.json({ error: 'Server is shutting down' }, 503);
+}
+```
+
+### Timeout Configuration
+
+```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,    // 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
+# apps/values.yaml
+gracefulShutdown:
+  terminationGracePeriodSeconds: 660  # 11분
+```
+
+```bash
+SHUTDOWN_TIMEOUT=640000  # 660 - 5 - 15 = 640s
+```
+
+---
+
+## Health Check
+
+Built-in health endpoint at `/health`:
+
+```bash
+# Normal
+curl http://localhost:8790/health
+# { "status": "ok", "timestamp": "2024-..." }
+
+# During shutdown → 503
+# { "status": "shutting_down", "timestamp": "2024-..." }
+```
+
+---
+
+## Environment Variables
+
+```bash
+# Server
+PORT=8790
+HOST=localhost
+NODE_ENV=development
+
+# Database
+DATABASE_URL=postgresql://localhost:5432/mydb
+DATABASE_WRITE_URL=postgresql://primary:5432/mydb
+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         # 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
+```
+
+---
+
+## File Structure
+
+```
+src/server/
+├── server.config.ts    # Configuration (Level 2)
+├── app.ts              # Custom Hono app (Level 3, optional)
+├── index.ts            # Entry point
+├── entities/           # Database schema
+├── repositories/       # Data access
+├── routes/             # API routes
+└── middlewares/        # Custom middleware
+```
+
+---
+
+## Startup Banner
+
+On startup, server displays:
+
+```
+╭──────────────────────────────────────╮
+│                                      │
+│     SPFN Server v1.0.0               │
+│                                      │
+│     http://localhost:8790            │
+│                                      │
+│     Press Ctrl+C to stop             │
+│                                      │
+╰──────────────────────────────────────╯
+
+  ✓ Database connected
+  ✓ Redis connected
+  ✓ 12 routes registered
+```
+
+---
+
+## Best Practices
+
+### Do
+
+```typescript
+// 1. Export router type for client usage
+export type AppRouter = typeof appRouter;
+
+// 2. Use lifecycle hooks for initialization
+.beforeStart(async () => {
+    await warmupCache();
+})
+
+// 3. Register global middlewares
+.middlewares([authMiddleware, rateLimiter])
+
+// 4. Use Level 2 for most projects
+defineServerConfig()
+    .port(8790)
+    .routes(appRouter)
+    .build();
+```
+
+### Don't
+
+```typescript
+// 1. Don't hardcode port in production
+.port(8790)  // Use process.env.PORT instead
+
+// 2. Don't skip database auto-init unless needed
+.database(false)  // Usually let it auto-detect
+
+// 3. Don't use Level 3 unless necessary
+// Level 2 covers most use cases
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spfn/core",
-  "version": "0.2.0-beta.4",
+  "version": "0.2.0-beta.42",
   "description": "SPFN Framework Core - File-based routing, transactions, repository pattern",
   "type": "module",
   "exports": {
@@ -146,12 +146,13 @@
     "dotenv": "^17.2.3",
     "drizzle-orm": "^0.45.0",
     "drizzle-typebox": "^0.1.0",
-    "hono": "^4.10.6",
+    "hono": "^4.12.4",
     "jiti": "^2.6.1",
     "micromatch": "^4.0.8",
     "pg-boss": "^11.1.2",
     "postgres": "^3.4.0",
     "typescript": "^5.3.3",
+    "undici": "^7.24.0",
     "zod": "^4.1.11"
   },
   "optionalDependencies": {

package/dist/types-B-e_f2dQ.d.ts

@@ -1,121 +0,0 @@
-import { E as EventRouterDef, I as InferEventNames, b as InferEventPayload } from './router-Di7ENoah.js';
-
-/**
- * SSE Types
- *
- * Type definitions for Server-Sent Events
- */
-
-/**
- * SSE message sent from server
- */
-interface SSEMessage<TEvent extends string = string, TPayload = unknown> {
-    /** Event name */
-    event: TEvent;
-    /** Event payload */
-    data: TPayload;
-    /** Optional message ID for reconnection */
-    id?: string;
-}
-/**
- * SSE Handler configuration
- */
-interface SSEHandlerConfig {
-    /**
-     * Keep-alive ping interval in milliseconds
-     * @default 30000
-     */
-    pingInterval?: number;
-    /**
-     * Custom headers for SSE response
-     */
-    headers?: Record<string, string>;
-}
-/**
- * SSE Client configuration
- */
-interface SSEClientConfig {
-    /**
-     * Backend API host URL
-     * @default NEXT_PUBLIC_SPFN_API_URL || 'http://localhost:8790'
-     * @example 'http://localhost:8790'
-     * @example 'https://api.example.com'
-     */
-    host?: string;
-    /**
-     * SSE endpoint pathname
-     * @default '/events/stream'
-     */
-    pathname?: string;
-    /**
-     * Full URL (overrides host + pathname)
-     * @deprecated Use host and pathname instead
-     * @example 'http://localhost:8790/events/stream'
-     */
-    url?: string;
-    /**
-     * Auto reconnect on disconnect
-     * @default true
-     */
-    reconnect?: boolean;
-    /**
-     * Reconnect delay in milliseconds
-     * @default 3000
-     */
-    reconnectDelay?: number;
-    /**
-     * Maximum reconnect attempts (0 = infinite)
-     * @default 0
-     */
-    maxReconnectAttempts?: number;
-    /**
-     * Include credentials (cookies) in request
-     * @default false
-     */
-    withCredentials?: boolean;
-}
-/**
- * Event handler function
- */
-type SSEEventHandler<TPayload> = (payload: TPayload) => void;
-/**
- * Event handlers map for EventRouter
- */
-type SSEEventHandlers<TRouter extends EventRouterDef<any>> = {
-    [K in InferEventNames<TRouter>]?: SSEEventHandler<InferEventPayload<TRouter, K>>;
-};
-/**
- * Subscription options
- */
-interface SSESubscribeOptions<TRouter extends EventRouterDef<any>> {
-    /**
-     * Events to subscribe
-     */
-    events: InferEventNames<TRouter>[];
-    /**
-     * Event handlers
-     */
-    handlers: SSEEventHandlers<TRouter>;
-    /**
-     * Called when connection opens
-     */
-    onOpen?: () => void;
-    /**
-     * Called on connection error
-     */
-    onError?: (error: Event) => void;
-    /**
-     * Called when reconnecting
-     */
-    onReconnect?: (attempt: number) => void;
-}
-/**
- * SSE connection state
- */
-type SSEConnectionState = 'connecting' | 'open' | 'closed' | 'error';
-/**
- * Unsubscribe function
- */
-type SSEUnsubscribe = () => void;
-
-export type { SSEHandlerConfig as S, SSEMessage as a, SSEClientConfig as b, SSEEventHandler as c, SSEEventHandlers as d, SSESubscribeOptions as e, SSEConnectionState as f, SSEUnsubscribe as g };