@mandujs/core 0.10.0 → 0.11.0

package/src/plugins/types.ts

@@ -0,0 +1,363 @@
+/**
+ * DNA-001: Plugin Adapter Pattern - Core Types
+ *
+ * 플러그인 시스템의 핵심 인터페이스 정의
+ * - 타입 안전한 플러그인 등록
+ * - 설정 스키마 검증
+ * - 라이프사이클 훅
+ */
+
+import type { z, ZodSchema } from "zod";
+
+/**
+ * 플러그인 카테고리
+ */
+export type PluginCategory =
+  | "guard-preset"    // Guard 아키텍처 프리셋
+  | "build"           // 빌드 플러그인 (analyzer, minifier)
+  | "logger"          // 로깅 전송
+  | "mcp-tool"        // MCP 도구 확장
+  | "middleware"      // 글로벌 미들웨어
+  | "custom";         // 사용자 정의
+
+/**
+ * 플러그인 메타데이터
+ */
+export interface PluginMeta {
+  /** 고유 ID (예: "guard-preset-fsd", "build-analyzer") */
+  id: string;
+
+  /** 표시 이름 */
+  name: string;
+
+  /** 설명 */
+  description?: string;
+
+  /** 버전 (semver) */
+  version: string;
+
+  /** 카테고리 */
+  category: PluginCategory;
+
+  /** 작성자 */
+  author?: string;
+
+  /** 저장소 URL */
+  repository?: string;
+
+  /** 태그 (검색용) */
+  tags?: string[];
+}
+
+/**
+ * 플러그인 API - 플러그인이 프레임워크와 상호작용하는 인터페이스
+ */
+export interface PluginApi {
+  /**
+   * Guard 프리셋 등록
+   */
+  registerGuardPreset: (preset: GuardPresetPlugin) => void;
+
+  /**
+   * 빌드 플러그인 등록
+   */
+  registerBuildPlugin: (plugin: BuildPlugin) => void;
+
+  /**
+   * 로거 전송 등록
+   */
+  registerLoggerTransport: (transport: LoggerTransportPlugin) => void;
+
+  /**
+   * MCP 도구 등록
+   */
+  registerMcpTool: (tool: McpToolPlugin) => void;
+
+  /**
+   * 미들웨어 등록
+   */
+  registerMiddleware: (middleware: MiddlewarePlugin) => void;
+
+  /**
+   * 설정 가져오기
+   */
+  getConfig: <T>(key: string) => T | undefined;
+
+  /**
+   * 로거
+   */
+  logger: {
+    debug: (msg: string, data?: unknown) => void;
+    info: (msg: string, data?: unknown) => void;
+    warn: (msg: string, data?: unknown) => void;
+    error: (msg: string, data?: unknown) => void;
+  };
+}
+
+/**
+ * 플러그인 라이프사이클 훅
+ */
+export interface PluginHooks {
+  /**
+   * 플러그인 로드 시 (설정 검증 후)
+   */
+  onLoad?: () => void | Promise<void>;
+
+  /**
+   * 플러그인 언로드 시
+   */
+  onUnload?: () => void | Promise<void>;
+
+  /**
+   * 서버 시작 시
+   */
+  onServerStart?: () => void | Promise<void>;
+
+  /**
+   * 서버 종료 시
+   */
+  onServerStop?: () => void | Promise<void>;
+}
+
+/**
+ * 기본 플러그인 인터페이스
+ */
+export interface Plugin<TConfig = unknown> extends PluginHooks {
+  /** 플러그인 메타데이터 */
+  meta: PluginMeta;
+
+  /** 설정 스키마 (Zod) */
+  configSchema?: ZodSchema<TConfig>;
+
+  /**
+   * 플러그인 등록 함수
+   * @param api - 플러그인 API
+   * @param config - 검증된 설정
+   */
+  register: (api: PluginApi, config: TConfig) => void | Promise<void>;
+}
+
+// ============================================================================
+// 카테고리별 플러그인 타입
+// ============================================================================
+
+/**
+ * Guard 프리셋 플러그인
+ */
+export interface GuardPresetPlugin {
+  /** 프리셋 ID (예: "fsd", "clean", "hexagonal") */
+  id: string;
+
+  /** 표시 이름 */
+  name: string;
+
+  /** 설명 */
+  description?: string;
+
+  /**
+   * 프리셋 규칙 정의
+   * @returns 규칙 배열
+   */
+  getRules: () => GuardRule[];
+
+  /**
+   * 레이어 정의 (있는 경우)
+   */
+  getLayers?: () => LayerDefinition[];
+}
+
+/**
+ * Guard 규칙
+ */
+export interface GuardRule {
+  id: string;
+  name: string;
+  description?: string;
+  severity: "error" | "warn" | "off";
+  check: (context: GuardRuleContext) => GuardViolation[];
+}
+
+/**
+ * Guard 규칙 실행 컨텍스트
+ */
+export interface GuardRuleContext {
+  filePath: string;
+  sourceCode: string;
+  imports: ImportInfo[];
+  exports: ExportInfo[];
+  projectRoot: string;
+}
+
+/**
+ * Import 정보
+ */
+export interface ImportInfo {
+  source: string;
+  specifiers: string[];
+  isTypeOnly: boolean;
+  line: number;
+}
+
+/**
+ * Export 정보
+ */
+export interface ExportInfo {
+  name: string;
+  isDefault: boolean;
+  isTypeOnly: boolean;
+  line: number;
+}
+
+/**
+ * Guard 위반
+ */
+export interface GuardViolation {
+  ruleId: string;
+  message: string;
+  severity: "error" | "warn";
+  filePath: string;
+  line?: number;
+  column?: number;
+  fix?: {
+    description: string;
+    replacement?: string;
+  };
+}
+
+/**
+ * 레이어 정의
+ */
+export interface LayerDefinition {
+  name: string;
+  pattern: string | RegExp;
+  allowedDependencies: string[];
+}
+
+/**
+ * 빌드 플러그인
+ */
+export interface BuildPlugin {
+  /** 플러그인 ID */
+  id: string;
+
+  /** 표시 이름 */
+  name: string;
+
+  /**
+   * 빌드 전 훅
+   */
+  onBuildStart?: (context: BuildContext) => void | Promise<void>;
+
+  /**
+   * 번들 처리
+   */
+  transform?: (code: string, id: string) => string | null | Promise<string | null>;
+
+  /**
+   * 빌드 후 훅
+   */
+  onBuildEnd?: (context: BuildContext, result: BuildResult) => void | Promise<void>;
+}
+
+/**
+ * 빌드 컨텍스트
+ */
+export interface BuildContext {
+  outDir: string;
+  minify: boolean;
+  sourcemap: boolean;
+  mode: "development" | "production";
+}
+
+/**
+ * 빌드 결과
+ */
+export interface BuildResult {
+  success: boolean;
+  outputFiles: string[];
+  errors?: string[];
+  stats?: {
+    duration: number;
+    totalSize: number;
+  };
+}
+
+/**
+ * 로거 전송 플러그인
+ */
+export interface LoggerTransportPlugin {
+  /** 전송 ID */
+  id: string;
+
+  /** 표시 이름 */
+  name: string;
+
+  /**
+   * 로그 전송
+   */
+  send: (entry: LogEntry) => void | Promise<void>;
+
+  /**
+   * 배치 전송 (옵션)
+   */
+  sendBatch?: (entries: LogEntry[]) => void | Promise<void>;
+
+  /**
+   * 종료 시 플러시
+   */
+  flush?: () => void | Promise<void>;
+}
+
+/**
+ * 로그 항목
+ */
+export interface LogEntry {
+  level: "debug" | "info" | "warn" | "error";
+  message: string;
+  timestamp: Date;
+  data?: unknown;
+  context?: Record<string, unknown>;
+}
+
+/**
+ * MCP 도구 플러그인
+ */
+export interface McpToolPlugin {
+  /** 도구 이름 */
+  name: string;
+
+  /** 설명 */
+  description: string;
+
+  /**
+   * 입력 스키마 (JSON Schema)
+   */
+  inputSchema: Record<string, unknown>;
+
+  /**
+   * 도구 실행
+   */
+  execute: (input: unknown) => unknown | Promise<unknown>;
+}
+
+/**
+ * 미들웨어 플러그인
+ */
+export interface MiddlewarePlugin {
+  /** 미들웨어 ID */
+  id: string;
+
+  /** 표시 이름 */
+  name: string;
+
+  /** 실행 순서 (낮을수록 먼저) */
+  order?: number;
+
+  /**
+   * 미들웨어 함수
+   */
+  handler: (
+    request: Request,
+    next: () => Promise<Response>
+  ) => Response | Promise<Response>;
+}

package/src/runtime/session-key.ts

@@ -0,0 +1,328 @@
+/**
+ * DNA-004: Session Key Utilities
+ *
+ * 세션 키 기반 격리 시스템
+ * - SSR 상태 격리 (팀별, 사용자별)
+ * - 캐시 키 생성 (route + params + user)
+ * - WebSocket 채널 격리 (향후)
+ */
+
+/**
+ * 세션 스코프
+ */
+export type SessionScope =
+  | "global"   // 전역 (모든 사용자 공유)
+  | "team"     // 팀별 격리
+  | "user"     // 사용자별 격리
+  | "request"; // 요청별 격리 (캐시 없음)
+
+/**
+ * 세션 키 빌더 옵션
+ */
+export interface SessionKeyOptions {
+  /** 라우트 ID 또는 경로 */
+  route: string;
+
+  /** 팀 ID (team/user 스코프에서 사용) */
+  teamId?: string;
+
+  /** 사용자 ID (user 스코프에서 사용) */
+  userId?: string;
+
+  /** 세션 스코프 */
+  scope: SessionScope;
+
+  /** 추가 파라미터 (쿼리 파라미터 등) */
+  params?: Record<string, string>;
+
+  /** 네임스페이스 (기본: "session") */
+  namespace?: string;
+}
+
+/**
+ * 캐시 키 빌더 옵션
+ */
+export interface CacheKeyOptions {
+  /** 캐시 타입 (예: "ssr", "api", "data") */
+  type: string;
+
+  /** 리소스 식별자 */
+  resource: string;
+
+  /** 버전 또는 태그 */
+  version?: string;
+
+  /** 추가 파라미터 */
+  params?: Record<string, string | number | boolean>;
+
+  /** 사용자 ID (사용자별 캐시 시) */
+  userId?: string;
+}
+
+/**
+ * 문자열 정규화 (소문자, 특수문자 제거)
+ */
+function normalize(str: string): string {
+  return str
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+/**
+ * 파라미터를 정렬된 문자열로 변환
+ */
+function serializeParams(params: Record<string, string | number | boolean>): string {
+  const entries = Object.entries(params)
+    .filter(([_, v]) => v !== undefined && v !== null && v !== "")
+    .sort(([a], [b]) => a.localeCompare(b));
+
+  if (entries.length === 0) return "";
+
+  return entries
+    .map(([k, v]) => `${normalize(k)}=${normalize(String(v))}`)
+    .join("&");
+}
+
+/**
+ * 세션 키 생성
+ *
+ * @example
+ * ```ts
+ * // 전역 세션
+ * buildSessionKey({ route: "/dashboard", scope: "global" })
+ * // → "session:/dashboard"
+ *
+ * // 팀별 세션
+ * buildSessionKey({ route: "/projects", scope: "team", teamId: "team-123" })
+ * // → "session:/projects:team:team-123"
+ *
+ * // 사용자별 세션
+ * buildSessionKey({ route: "/profile", scope: "user", userId: "user-456" })
+ * // → "session:/profile:user:user-456"
+ *
+ * // 파라미터 포함
+ * buildSessionKey({
+ *   route: "/search",
+ *   scope: "user",
+ *   userId: "user-456",
+ *   params: { q: "mandu", page: "1" }
+ * })
+ * // → "session:/search:user:user-456:page=1&q=mandu"
+ * ```
+ */
+export function buildSessionKey(options: SessionKeyOptions): string {
+  const { route, teamId, userId, scope, params, namespace = "session" } = options;
+  const parts: string[] = [namespace, normalize(route)];
+
+  switch (scope) {
+    case "team":
+      if (teamId) {
+        parts.push(`team:${normalize(teamId)}`);
+      }
+      break;
+
+    case "user":
+      if (userId) {
+        parts.push(`user:${normalize(userId)}`);
+      } else if (teamId) {
+        // user 스코프에서 teamId만 있으면 팀 레벨로 폴백
+        parts.push(`team:${normalize(teamId)}`);
+      }
+      break;
+
+    case "request":
+      // 요청별 고유 키 (타임스탬프 + 랜덤)
+      parts.push(`req:${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+      break;
+
+    case "global":
+    default:
+      // 추가 스코프 없음
+      break;
+  }
+
+  // 파라미터 추가
+  if (params && Object.keys(params).length > 0) {
+    const serialized = serializeParams(params);
+    if (serialized) {
+      parts.push(serialized);
+    }
+  }
+
+  return parts.join(":");
+}
+
+/**
+ * 캐시 키 생성
+ *
+ * @example
+ * ```ts
+ * // SSR 캐시
+ * buildCacheKey({ type: "ssr", resource: "/blog/123" })
+ * // → "cache:ssr:/blog/123"
+ *
+ * // 버전 포함
+ * buildCacheKey({ type: "api", resource: "users", version: "v2" })
+ * // → "cache:api:users:v2"
+ *
+ * // 파라미터 포함
+ * buildCacheKey({
+ *   type: "data",
+ *   resource: "products",
+ *   params: { category: "food", limit: 10 }
+ * })
+ * // → "cache:data:products:category=food&limit=10"
+ *
+ * // 사용자별 캐시
+ * buildCacheKey({
+ *   type: "ssr",
+ *   resource: "/dashboard",
+ *   userId: "user-123"
+ * })
+ * // → "cache:ssr:/dashboard:user:user-123"
+ * ```
+ */
+export function buildCacheKey(options: CacheKeyOptions): string {
+  const { type, resource, version, params, userId } = options;
+  const parts: string[] = ["cache", normalize(type), normalize(resource)];
+
+  if (version) {
+    parts.push(normalize(version));
+  }
+
+  if (userId) {
+    parts.push(`user:${normalize(userId)}`);
+  }
+
+  if (params && Object.keys(params).length > 0) {
+    const serialized = serializeParams(params);
+    if (serialized) {
+      parts.push(serialized);
+    }
+  }
+
+  return parts.join(":");
+}
+
+/**
+ * WebSocket 채널 키 생성
+ *
+ * @example
+ * ```ts
+ * buildChannelKey({ channel: "notifications", userId: "user-123" })
+ * // → "ws:notifications:user:user-123"
+ *
+ * buildChannelKey({ channel: "team-chat", teamId: "team-456" })
+ * // → "ws:team-chat:team:team-456"
+ * ```
+ */
+export function buildChannelKey(options: {
+  channel: string;
+  userId?: string;
+  teamId?: string;
+}): string {
+  const { channel, userId, teamId } = options;
+  const parts: string[] = ["ws", normalize(channel)];
+
+  if (userId) {
+    parts.push(`user:${normalize(userId)}`);
+  } else if (teamId) {
+    parts.push(`team:${normalize(teamId)}`);
+  }
+
+  return parts.join(":");
+}
+
+/**
+ * 세션 키 파싱
+ *
+ * @example
+ * ```ts
+ * parseSessionKey("session:/dashboard:team:team-123")
+ * // → { namespace: "session", route: "/dashboard", scope: "team", teamId: "team-123" }
+ * ```
+ */
+export function parseSessionKey(key: string): {
+  namespace: string;
+  route: string;
+  scope: SessionScope;
+  teamId?: string;
+  userId?: string;
+  params?: string;
+} | null {
+  const parts = key.split(":");
+
+  if (parts.length < 2) return null;
+
+  const [namespace, route, ...rest] = parts;
+  let scope: SessionScope = "global";
+  let teamId: string | undefined;
+  let userId: string | undefined;
+  let params: string | undefined;
+
+  for (let i = 0; i < rest.length; i++) {
+    const part = rest[i];
+
+    if (part === "team" && rest[i + 1]) {
+      scope = "team";
+      teamId = rest[++i];
+    } else if (part === "user" && rest[i + 1]) {
+      scope = "user";
+      userId = rest[++i];
+    } else if (part.startsWith("req:")) {
+      scope = "request";
+    } else if (part.includes("=")) {
+      params = part;
+    }
+  }
+
+  return { namespace, route, scope, teamId, userId, params };
+}
+
+/**
+ * 키 패턴 매칭 (와일드카드 지원)
+ *
+ * @example
+ * ```ts
+ * matchKeyPattern("session:/dashboard:*", "session:/dashboard:team:team-123")
+ * // → true
+ *
+ * matchKeyPattern("cache:ssr:*", "cache:api:users")
+ * // → false
+ * ```
+ */
+export function matchKeyPattern(pattern: string, key: string): boolean {
+  const patternParts = pattern.split(":");
+  const keyParts = key.split(":");
+
+  for (let i = 0; i < patternParts.length; i++) {
+    const p = patternParts[i];
+
+    if (p === "*") {
+      // 와일드카드는 나머지 모두 매칭
+      return true;
+    }
+
+    if (p === "**") {
+      // 더블 와일드카드는 0개 이상 매칭
+      if (i === patternParts.length - 1) return true;
+
+      // 나머지 패턴과 매칭되는 위치 찾기
+      const remaining = patternParts.slice(i + 1);
+      for (let j = i; j <= keyParts.length - remaining.length; j++) {
+        if (matchKeyPattern(remaining.join(":"), keyParts.slice(j).join(":"))) {
+          return true;
+        }
+      }
+      return false;
+    }
+
+    if (keyParts[i] !== p) {
+      return false;
+    }
+  }
+
+  return patternParts.length === keyParts.length;
+}