@enderworld/onlyapi 1.5.1

package/src/shared/cli.ts

@@ -0,0 +1,294 @@
+import { cpus } from "node:os";
+import type { AppConfig } from "../infrastructure/config/config.js";
+
+// ── ANSI escape sequences (zero dependencies) ──────────────────────────
+
+const esc = (code: string) => `\x1b[${code}m`;
+const reset = esc("0");
+
+const bold = (s: string) => `${esc("1")}${s}${reset}`;
+const dim = (s: string) => `${esc("2")}${s}${reset}`;
+
+const cyan = (s: string) => `${esc("36")}${s}${reset}`;
+const green = (s: string) => `${esc("32")}${s}${reset}`;
+const yellow = (s: string) => `${esc("33")}${s}${reset}`;
+const magenta = (s: string) => `${esc("35")}${s}${reset}`;
+const blue = (s: string) => `${esc("34")}${s}${reset}`;
+const red = (s: string) => `${esc("31")}${s}${reset}`;
+const gray = (s: string) => `${esc("90")}${s}${reset}`;
+const white = (s: string) => `${esc("97")}${s}${reset}`;
+
+const bgCyan = (s: string) => `${esc("46")}${esc("30")} ${s} ${reset}`;
+const bgGreen = (s: string) => `${esc("42")}${esc("30")} ${s} ${reset}`;
+const bgYellow = (s: string) => `${esc("43")}${esc("30")} ${s} ${reset}`;
+const bgMagenta = (s: string) => `${esc("45")}${esc("97")} ${s} ${reset}`;
+
+// ── Helpers ─────────────────────────────────────────────────────────────
+
+const pad = (s: string, len: number): string => s.padEnd(len);
+
+const formatUptime = (ms: number): string => {
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  return `${(ms / 1000).toFixed(2)}s`;
+};
+
+const envBadge = (env: string): string => {
+  switch (env) {
+    case "production":
+      return bgGreen("PRODUCTION");
+    case "development":
+      return bgCyan("DEVELOPMENT");
+    case "test":
+      return bgYellow("TEST");
+    default:
+      return bgMagenta(env.toUpperCase());
+  }
+};
+
+const methodColor = (method: string): string => {
+  switch (method) {
+    case "GET":
+      return green(bold(pad(method, 7)));
+    case "POST":
+      return cyan(bold(pad(method, 7)));
+    case "PATCH":
+      return yellow(bold(pad(method, 7)));
+    case "PUT":
+      return yellow(bold(pad(method, 7)));
+    case "DELETE":
+      return red(bold(pad(method, 7)));
+    default:
+      return white(bold(pad(method, 7)));
+  }
+};
+
+// ── Route table ─────────────────────────────────────────────────────────
+
+interface RouteInfo {
+  readonly method: string;
+  readonly path: string;
+  readonly auth: boolean;
+  readonly description: string;
+}
+
+const routes: readonly RouteInfo[] = [
+  { method: "GET", path: "/health", auth: false, description: "Shallow health check" },
+  { method: "GET", path: "/readiness", auth: false, description: "Deep readiness check" },
+  { method: "GET", path: "/docs", auth: false, description: "OpenAPI 3.1 spec (JSON)" },
+  { method: "GET", path: "/docs/html", auth: false, description: "Swagger UI" },
+  { method: "POST", path: "/api/v1/auth/register", auth: false, description: "Register user" },
+  { method: "POST", path: "/api/v1/auth/login", auth: false, description: "Login" },
+  { method: "POST", path: "/api/v1/auth/refresh", auth: false, description: "Refresh token" },
+  { method: "POST", path: "/api/v1/auth/logout", auth: true, description: "Logout" },
+  { method: "GET", path: "/api/v1/users/me", auth: true, description: "Get profile" },
+  { method: "PATCH", path: "/api/v1/users/me", auth: true, description: "Update profile" },
+  { method: "DELETE", path: "/api/v1/users/me", auth: true, description: "Delete account" },
+  { method: "GET", path: "/api/v1/admin/users", auth: true, description: "List users (admin)" },
+  { method: "GET", path: "/api/v1/admin/users/:id", auth: true, description: "Get user (admin)" },
+  {
+    method: "PATCH",
+    path: "/api/v1/admin/users/:id/role",
+    auth: true,
+    description: "Change role (admin)",
+  },
+  {
+    method: "POST",
+    path: "/api/v1/admin/users/:id/ban",
+    auth: true,
+    description: "Ban user (admin)",
+  },
+  {
+    method: "POST",
+    path: "/api/v1/admin/users/:id/unban",
+    auth: true,
+    description: "Unban user (admin)",
+  },
+  {
+    method: "GET",
+    path: "/metrics",
+    auth: false,
+    description: "Prometheus metrics",
+  },
+];
+
+// ── ASCII Logo ──────────────────────────────────────────────────────────
+
+const logo = (): string => {
+  const lines = [
+    `${bold(cyan("  ┌─────────────────────────────────────────┐"))}`,
+    `${bold(cyan("  │"))}                                           ${bold(cyan("│"))}`,
+    `${bold(cyan("  │"))}   ${bold(white("⚡ onlyApi"))}  ${dim(gray("v1.3.0"))}                      ${bold(cyan("│"))}`,
+    `${bold(cyan("  │"))}   ${dim(gray("Zero-dep enterprise REST API on Bun"))}    ${bold(cyan("│"))}`,
+    `${bold(cyan("  │"))}                                           ${bold(cyan("│"))}`,
+    `${bold(cyan("  └─────────────────────────────────────────┘"))}`,
+  ];
+  return lines.join("\n");
+};
+
+// ── Public API ──────────────────────────────────────────────────────────
+
+interface StartupInfo {
+  readonly config: AppConfig;
+  readonly bootTimeMs: number;
+  readonly isCluster?: boolean;
+  readonly workerId?: string;
+  readonly workerCount?: number;
+}
+
+/**
+ * Prints a beautiful startup banner to stdout.
+ * Called once after the server is fully initialized.
+ */
+export const printStartupBanner = (info: StartupInfo): void => {
+  const { config, bootTimeMs } = info;
+  const isCluster = info.isCluster ?? false;
+  const workerId = info.workerId;
+
+  const localUrl = `http://localhost:${config.port}`;
+  const networkUrl = `http://${config.host === "0.0.0.0" ? getLocalIp() : config.host}:${config.port}`;
+
+  const lines: string[] = [];
+
+  lines.push("");
+  lines.push(logo());
+  lines.push("");
+
+  // ── Server info ──
+  lines.push(
+    `  ${envBadge(config.env)}  ${dim("booted in")} ${bold(green(formatUptime(bootTimeMs)))}`,
+  );
+  lines.push("");
+
+  // ── URLs ──
+  lines.push(`  ${bold(white("→"))} ${dim("Local:")}    ${bold(cyan(localUrl))}`);
+  if (config.host === "0.0.0.0") {
+    lines.push(`  ${bold(white("→"))} ${dim("Network:")}  ${bold(cyan(networkUrl))}`);
+  }
+  lines.push("");
+
+  // ── Process info ──
+  lines.push(`  ${gray("├─")} ${dim("PID")}           ${white(String(process.pid))}`);
+  lines.push(`  ${gray("├─")} ${dim("Runtime")}       ${magenta(`Bun ${Bun.version}`)}`);
+  lines.push(`  ${gray("├─")} ${dim("TypeScript")}    ${blue("strict")} ${dim("(22+ flags)")}`);
+
+  if (isCluster) {
+    const count = info.workerCount ?? cpus().length;
+    lines.push(`  ${gray("├─")} ${dim("Mode")}          ${yellow(`cluster × ${count} workers`)}`);
+    if (workerId !== undefined) {
+      lines.push(`  ${gray("├─")} ${dim("Worker")}        ${yellow(`#${workerId}`)}`);
+    }
+  } else {
+    lines.push(`  ${gray("├─")} ${dim("Mode")}          ${green("single process")}`);
+  }
+
+  lines.push(
+    `  ${gray("├─")} ${dim("Rate limit")}    ${white(`${config.rateLimit.maxRequests} req/${config.rateLimit.windowMs / 1000}s`)}`,
+  );
+  lines.push(`  ${gray("├─")} ${dim("Log level")}     ${white(config.log.level)}`);
+  lines.push(`  ${gray("└─")} ${dim("Log format")}    ${white(config.log.format)}`);
+  lines.push("");
+
+  // ── Routes ──
+  lines.push(`  ${bold(white("Routes"))} ${dim(`(${routes.length})`)}`);
+  lines.push(`  ${gray("─".repeat(60))}`);
+
+  for (const route of routes) {
+    const lock = route.auth ? yellow("🔒") : green("  ");
+    const desc = dim(gray(route.description));
+    lines.push(`  ${lock} ${methodColor(route.method)} ${pad(route.path, 30)} ${desc}`);
+  }
+
+  lines.push(`  ${gray("─".repeat(60))}`);
+  lines.push("");
+
+  // ── Help ──
+  lines.push(`  ${dim("press")} ${bold(white("Ctrl+C"))} ${dim("to stop")}`);
+  lines.push("");
+
+  process.stdout.write(`${lines.join("\n")}\n`);
+};
+
+/**
+ * Prints a compact cluster master banner (no routes, just overview).
+ */
+export const printClusterBanner = (workerCount: number, cpuCount: number): void => {
+  const lines: string[] = [];
+
+  lines.push("");
+  lines.push(logo());
+  lines.push("");
+  lines.push(
+    `  ${bgMagenta("CLUSTER")}  ${dim("spawning")} ${bold(yellow(String(workerCount)))} ${dim("workers on")} ${bold(white(String(cpuCount)))} ${dim("CPU cores")}`,
+  );
+  lines.push("");
+  lines.push(`  ${gray("├─")} ${dim("Master PID")}    ${white(String(process.pid))}`);
+  lines.push(`  ${gray("├─")} ${dim("Runtime")}       ${magenta(`Bun ${Bun.version}`)}`);
+  lines.push(
+    `  ${gray("└─")} ${dim("SO_REUSEPORT")}  ${green("enabled")} ${dim("(kernel load balancing)")}`,
+  );
+  lines.push("");
+  lines.push(`  ${dim("press")} ${bold(white("Ctrl+C"))} ${dim("to stop all workers")}`);
+  lines.push("");
+
+  process.stdout.write(`${lines.join("\n")}\n`);
+};
+
+/**
+ * Prints a compact worker ready line (one line per worker).
+ */
+export const printWorkerReady = (workerId: number, pid: number, port: number): void => {
+  process.stdout.write(
+    `  ${green("✓")} ${dim("Worker")} ${bold(white(`#${workerId}`))} ${dim("ready")} ${gray(`(PID ${pid}, port ${port})`)}\n`,
+  );
+};
+
+/**
+ * Prints a clean shutdown message.
+ */
+export const printShutdown = (signal: string): void => {
+  process.stdout.write(
+    `\n  ${yellow("⏻")} ${dim("Received")} ${bold(white(signal))}${dim(", shutting down gracefully…")}\n\n`,
+  );
+};
+
+/**
+ * Prints a beautiful config validation error with hints.
+ */
+export const printConfigError = (errors: Record<string, string[]>): void => {
+  const lines: string[] = [];
+
+  lines.push("");
+  lines.push(`  ${bgMagenta("CONFIG ERROR")}  ${dim("Invalid configuration detected")}`);
+  lines.push("");
+
+  for (const [field, messages] of Object.entries(errors)) {
+    for (const msg of messages) {
+      lines.push(`  ${red("✗")} ${bold(white(field))} ${dim("→")} ${red(msg)}`);
+    }
+  }
+
+  lines.push("");
+  lines.push(`  ${dim("Hint: Copy .env.example to .env and set the required values:")}`);
+  lines.push(`  ${cyan("$ cp .env.example .env")}`);
+  lines.push("");
+
+  process.stderr.write(`${lines.join("\n")}\n`);
+};
+
+// ── Utilities ───────────────────────────────────────────────────────────
+
+const getLocalIp = (): string => {
+  try {
+    const nets = require("node:os").networkInterfaces();
+    for (const name of Object.keys(nets)) {
+      for (const net of nets[name] ?? []) {
+        if (net.family === "IPv4" && !net.internal) {
+          return net.address as string;
+        }
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return "0.0.0.0";
+};

package/src/shared/container.ts

@@ -0,0 +1,65 @@
+/**
+ * Minimal compile-time–safe DI container.
+ * No decorators, no reflect-metadata, no runtime magic.
+ * Register singletons by token; resolve by token.
+ */
+
+const registry = new Map<symbol, unknown>();
+
+export const Container = {
+  register<T>(token: symbol, instance: T): void {
+    if (registry.has(token)) {
+      throw new Error(`[Container] Token already registered: ${token.toString()}`);
+    }
+    registry.set(token, instance);
+  },
+
+  resolve<T>(token: symbol): T {
+    const instance = registry.get(token);
+    if (instance === undefined) {
+      throw new Error(`[Container] Token not registered: ${token.toString()}`);
+    }
+    return instance as T;
+  },
+
+  /** Only for tests — clears the entire registry */
+  reset(): void {
+    registry.clear();
+  },
+} as const;
+
+/** Well-known DI tokens */
+export const Tokens = {
+  Logger: Symbol.for("Logger"),
+  Config: Symbol.for("Config"),
+  UserRepository: Symbol.for("UserRepository"),
+  PasswordHasher: Symbol.for("PasswordHasher"),
+  TokenService: Symbol.for("TokenService"),
+  TokenBlacklist: Symbol.for("TokenBlacklist"),
+  AccountLockout: Symbol.for("AccountLockout"),
+  AuthService: Symbol.for("AuthService"),
+  UserService: Symbol.for("UserService"),
+  HealthService: Symbol.for("HealthService"),
+  AdminService: Symbol.for("AdminService"),
+  AuditLog: Symbol.for("AuditLog"),
+  Database: Symbol.for("Database"),
+  MetricsCollector: Symbol.for("MetricsCollector"),
+  AlertSink: Symbol.for("AlertSink"),
+  VerificationTokenRepository: Symbol.for("VerificationTokenRepository"),
+  RefreshTokenStore: Symbol.for("RefreshTokenStore"),
+  ApiKeyRepository: Symbol.for("ApiKeyRepository"),
+  PasswordHistory: Symbol.for("PasswordHistory"),
+  PasswordPolicy: Symbol.for("PasswordPolicy"),
+  TotpService: Symbol.for("TotpService"),
+  OAuthProviders: Symbol.for("OAuthProviders"),
+  OAuthAccountRepository: Symbol.for("OAuthAccountRepository"),
+  ApiKeyService: Symbol.for("ApiKeyService"),
+  EventBus: Symbol.for("EventBus"),
+  EventFactory: Symbol.for("EventFactory"),
+  WebhookRegistry: Symbol.for("WebhookRegistry"),
+  WebhookDispatcher: Symbol.for("WebhookDispatcher"),
+  JobQueue: Symbol.for("JobQueue"),
+  WebSocketManager: Symbol.for("WebSocketManager"),
+  SseHandler: Symbol.for("SseHandler"),
+  Cache: Symbol.for("Cache"),
+} as const;

package/src/shared/index.ts

@@ -0,0 +1,2 @@
+export { Container, Tokens } from "./container.js";
+export * from "./utils/index.js";

package/src/shared/log-format.ts

@@ -0,0 +1,148 @@
+import type { LogLevel } from "../core/ports/logger.js";
+
+// ── ANSI escape sequences ──────────────────────────────────────────────
+
+const esc = (code: string) => `\x1b[${code}m`;
+const reset = esc("0");
+
+const bold = (s: string) => `${esc("1")}${s}${reset}`;
+const dim = (s: string) => `${esc("2")}${s}${reset}`;
+
+const cyan = (s: string) => `${esc("36")}${s}${reset}`;
+const green = (s: string) => `${esc("32")}${s}${reset}`;
+const yellow = (s: string) => `${esc("33")}${s}${reset}`;
+const red = (s: string) => `${esc("31")}${s}${reset}`;
+const gray = (s: string) => `${esc("90")}${s}${reset}`;
+const white = (s: string) => `${esc("97")}${s}${reset}`;
+
+const bgGreen = (s: string) => `${esc("42")}${esc("30")} ${s} ${reset}`;
+const bgCyan = (s: string) => `${esc("46")}${esc("30")} ${s} ${reset}`;
+const bgYellow = (s: string) => `${esc("43")}${esc("30")} ${s} ${reset}`;
+const bgRed = (s: string) => `${esc("41")}${esc("97")} ${s} ${reset}`;
+
+// ── Helpers ─────────────────────────────────────────────────────────────
+
+const timestamp = (): string => {
+  const d = new Date();
+  const h = String(d.getHours()).padStart(2, "0");
+  const m = String(d.getMinutes()).padStart(2, "0");
+  const s = String(d.getSeconds()).padStart(2, "0");
+  const ms = String(d.getMilliseconds()).padStart(3, "0");
+  return `${h}:${m}:${s}.${ms}`;
+};
+
+const levelBadge = (level: LogLevel): string => {
+  switch (level) {
+    case "debug":
+      return gray("DBG");
+    case "info":
+      return green("INF");
+    case "warn":
+      return yellow("WRN");
+    case "error":
+      return red("ERR");
+    case "fatal":
+      return bgRed("FTL");
+  }
+};
+
+const methodBadge = (method: string): string => {
+  switch (method) {
+    case "GET":
+      return bgGreen("GET");
+    case "POST":
+      return bgCyan("POST");
+    case "PATCH":
+      return bgYellow("PATCH");
+    case "PUT":
+      return bgYellow("PUT");
+    case "DELETE":
+      return bgRed("DEL");
+    case "OPTIONS":
+      return gray("OPT");
+    default:
+      return white(method);
+  }
+};
+
+const statusColor = (status: number): string => {
+  if (status < 300) return bold(green(String(status)));
+  if (status < 400) return bold(cyan(String(status)));
+  if (status < 500) return bold(yellow(String(status)));
+  return bold(red(String(status)));
+};
+
+const durationColor = (ms: number): string => {
+  if (ms < 1) return green(`${ms}ms`);
+  if (ms < 50) return green(`${ms}ms`);
+  if (ms < 200) return yellow(`${ms}ms`);
+  return red(`${ms}ms`);
+};
+
+const formatMeta = (meta: Record<string, unknown>): string => {
+  const entries = Object.entries(meta);
+  if (entries.length === 0) return "";
+  const parts = entries.map(([k, v]) => `${dim(k)}${dim("=")}${white(String(v))}`);
+  return ` ${parts.join(" ")}`;
+};
+
+// ── Public formatters ───────────────────────────────────────────────────
+
+/**
+ * Format a structured log entry (used by the Logger port).
+ *
+ *   INF 12:34:56.789 Registering user  service=auth email=foo@bar.com
+ */
+export const formatLogEntry = (
+  level: LogLevel,
+  msg: string,
+  meta: Record<string, unknown>,
+): string => {
+  const ts = dim(gray(timestamp()));
+  const badge = levelBadge(level);
+  const metaStr = formatMeta(meta);
+  return `  ${badge} ${ts} ${white(msg)}${metaStr}\n`;
+};
+
+/**
+ * Format an HTTP access log line (used by batched server logger).
+ *
+ *   ← GET 200 /health 0.34ms  ip=127.0.0.1 rid=abc123
+ */
+export const formatAccessLog = (
+  method: string,
+  path: string,
+  status: number,
+  durationMs: number,
+  ip: string,
+  requestId: string,
+): string => {
+  const ts = dim(gray(timestamp()));
+  const arrow = dim("←");
+  const mBadge = methodBadge(method);
+  const st = statusColor(status);
+  const dur = durationColor(durationMs);
+  const p = white(path);
+  const meta = dim(gray(`ip=${ip} rid=${requestId.slice(0, 8)}`));
+  return `  ${arrow} ${ts} ${mBadge} ${st} ${p} ${dur}  ${meta}\n`;
+};
+
+/**
+ * Format a rate-limit warning line.
+ *
+ *   ⚠ 12:34:56.789 Rate limited  ip=1.2.3.4 hits=152
+ */
+export const formatRateLimitLog = (ip: string, count: number): string => {
+  const ts = dim(gray(timestamp()));
+  return `  ${yellow("⚠")} ${ts} ${bold(yellow("Rate limited"))}  ${dim("ip=")}${white(ip)} ${dim("hits=")}${white(String(count))}\n`;
+};
+
+/**
+ * Format a CORS rejection line.
+ *
+ *   ✗ 12:34:56.789 CORS rejected  origin=evil.com
+ */
+export const formatCorsRejectLog = (origin: string): string => {
+  const ts = dim(gray(timestamp()));
+  return `  ${red("✗")} ${ts} ${bold(red("CORS rejected"))}  ${dim("origin=")}${white(origin)}\n`;
+};

package/src/shared/utils/id.ts

@@ -0,0 +1,5 @@
+/**
+ * Generate a cryptographically random request identifier (UUIDv4).
+ * Uses Bun's built-in crypto — zero deps.
+ */
+export const generateId = (): string => crypto.randomUUID();

package/src/shared/utils/index.ts

@@ -0,0 +1,2 @@
+export { timingSafeEqual } from "./timing-safe.js";
+export { generateId } from "./id.js";

package/src/shared/utils/timing-safe.ts

@@ -0,0 +1,20 @@
+/**
+ * Tiny constant-time string comparison to prevent timing attacks on tokens / secrets.
+ */
+export const timingSafeEqual = (a: string, b: string): boolean => {
+  const enc = new TextEncoder();
+  const bufA = enc.encode(a);
+  const bufB = enc.encode(b);
+  if (bufA.byteLength !== bufB.byteLength) return false;
+
+  return crypto.subtle
+    ? // Bun exposes crypto.subtle – use it
+      (() => {
+        let mismatch = 0;
+        for (let i = 0; i < bufA.byteLength; i++) {
+          mismatch |= (bufA[i] ?? 0) ^ (bufB[i] ?? 0);
+        }
+        return mismatch === 0;
+      })()
+    : false;
+};