@spfn/core 0.2.0-beta.3 → 0.2.0-beta.31

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.3",
+  "version": "0.2.0-beta.31",
   "description": "SPFN Framework Core - File-based routing, transactions, repository pattern",
   "type": "module",
   "exports": {
@@ -64,6 +64,11 @@
       "import": "./dist/env/index.js",
       "require": "./dist/env/index.js"
     },
+    "./env/loader": {
+      "types": "./dist/env/loader.d.ts",
+      "import": "./dist/env/loader.js",
+      "require": "./dist/env/loader.js"
+    },
     "./logger": {
       "types": "./dist/logger/index.d.ts",
       "import": "./dist/logger/index.js",
@@ -83,6 +88,16 @@
       "types": "./dist/event/index.d.ts",
       "import": "./dist/event/index.js",
       "require": "./dist/event/index.js"
+    },
+    "./event/sse": {
+      "types": "./dist/event/sse/index.d.ts",
+      "import": "./dist/event/sse/index.js",
+      "require": "./dist/event/sse/index.js"
+    },
+    "./event/sse/client": {
+      "types": "./dist/event/sse/client.d.ts",
+      "import": "./dist/event/sse/client.js",
+      "require": "./dist/event/sse/client.js"
     }
   },
   "keywords": [
@@ -137,6 +152,7 @@
     "pg-boss": "^11.1.2",
     "postgres": "^3.4.0",
     "typescript": "^5.3.3",
+    "undici": "^7.22.0",
     "zod": "^4.1.11"
   },
   "optionalDependencies": {
@@ -148,7 +164,7 @@
     "@vitest/coverage-v8": "^4.0.6",
     "drizzle-kit": "^0.31.6",
     "madge": "^8.0.0",
-    "next": "16.0.7",
+    "next": "^16.0.0",
     "tsup": "^8.5.0",
     "vitest": "^4.0.6"
   },