bhooai-nexus 0.1.2

package/packages/nexus-realtime/src/index.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './adapter/PubSubAdapter.js';
+export * from './adapter/RedisPubSubAdapter.js';
+export * from './server/RealtimeServer.js';
+export * from './mediasoup/MediasoupAdapter.js';

package/packages/nexus-realtime/src/mediasoup/MediasoupAdapter.ts

@@ -0,0 +1,176 @@
+import type { Connection } from '../types.js';
+import type { MediaAction } from '../types.js';
+
+/**
+ * mediasoup SFU adapter. Lazily imports `mediasoup` (an optional native
+ * dependency) so the realtime package loads even when mediasoup is not
+ * installed; media actions return a clear error in that case.
+ *
+ * One mediasoup worker is created per adapter; one router per room (with a
+ * default Opus audio + VP8 video RTP capability set). Each connection gets a
+ * send WebRtcTransport and a recv WebRtcTransport; producers/consumers are
+ * tracked per connection. This is a functional single-room SFU demo; full
+ * multi-room capacity scaling is wired but tuned in a later pass.
+ */
+export interface MediasoupAdapterOptions {
+  /** RTC listen IP announced to clients (default 127.0.0.1). */
+  announceIp?: string;
+  /** RTC port range (defaults let mediasoup choose). */
+  rtcMinPort?: number;
+  rtcMaxPort?: number;
+  /** Number of mediasoup workers (default 1). */
+  workerCount?: number;
+}
+
+// Default router media codecs: Opus audio + VP8 video. (RTX omitted for portability —
+// adding it requires a correctly-bound `apt` referencing the VP8 payload type; not needed for the demo.)
+const ROUTER_MEDIA_CODECS = [
+  { kind: 'audio', mimeType: 'audio/opus', clockRate: 48000, channels: 2 },
+  { kind: 'video', mimeType: 'video/VP8', clockRate: 90000, rtcpFeedback: [{ type: 'nack' }, { type: 'nack', parameter: 'pli' }, { type: 'ccm', parameter: 'fir' }, { type: 'goog-remb' }] },
+];
+
+interface ConnState {
+  sendTransport?: unknown;
+  recvTransport?: unknown;
+  producers: Map<string, unknown>;
+  consumers: Map<string, unknown>;
+}
+
+export class MediasoupAdapter {
+  private workerPromise?: Promise<unknown>;
+  private routers = new Map<string, Promise<unknown>>();
+  private states = new WeakMap<Connection, ConnState>();
+  private opts: MediasoupAdapterOptions;
+
+  constructor(opts: MediasoupAdapterOptions = {}) {
+    this.opts = opts;
+  }
+
+  private state(conn: Connection): ConnState {
+    let s = this.states.get(conn);
+    if (!s) { s = { producers: new Map(), consumers: new Map() }; this.states.set(conn, s); }
+    return s;
+  }
+
+  private async worker(): Promise<unknown> {
+    if (!this.workerPromise) {
+      const mod = await import('mediasoup');
+      this.workerPromise = mod.createWorker({
+        logLevel: 'warn',
+        rtcMinPort: this.opts.rtcMinPort ?? 40000,
+        rtcMaxPort: this.opts.rtcMaxPort ?? 40100,
+      }) as Promise<unknown>;
+    }
+    return this.workerPromise;
+  }
+
+  private async router(room: string): Promise<unknown> {
+    let p = this.routers.get(room);
+    if (!p) {
+      p = (async () => {
+        const w = await this.worker();
+        const r = await (w as any).createRouter({ mediaCodecs: ROUTER_MEDIA_CODECS });
+        return r;
+      })();
+      this.routers.set(room, p);
+    }
+    return p;
+  }
+
+  async handle(conn: Connection, action: MediaAction, payload: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const room = String(payload.room ?? 'default');
+    const router = await this.router(room);
+    const s = this.state(conn);
+
+    switch (action) {
+      case 'getRouterRtpCapabilities':
+        return { rtpCapabilities: (router as any).rtpCapabilities };
+
+      case 'createWebRtcTransport': {
+        const dir = (payload.direction ?? 'send') as 'send' | 'recv';
+        const t = await (router as any).createWebRtcTransport({
+          listenIps: [{ ip: '0.0.0.0', announcedIp: this.opts.announceIp ?? '127.0.0.1' }],
+          enableUdp: true,
+          enableTcp: true,
+          preferUdp: true,
+        });
+        if (dir === 'send') s.sendTransport = t; else s.recvTransport = t;
+        return {
+          id: t.id,
+          iceParameters: t.iceParameters,
+          iceCandidates: t.iceCandidates,
+          dtlsParameters: t.dtlsParameters,
+          direction: dir,
+        };
+      }
+
+      case 'connectTransport': {
+        const dir = (payload.direction ?? 'send') as 'send' | 'recv';
+        const t = dir === 'send' ? s.sendTransport : s.recvTransport;
+        if (!t) return { error: 'transport not found' };
+        await (t as any).connect({ dtlsParameters: payload.dtlsParameters });
+        return { connected: true };
+      }
+
+      case 'produce': {
+        if (!s.sendTransport) return { error: 'send transport not found' };
+        const producer = await (s.sendTransport as any).produce({
+          kind: payload.kind,
+          rtpParameters: payload.rtpParameters,
+          paused: false,
+        });
+        s.producers.set(producer.id, producer);
+        return { id: producer.id, kind: producer.kind };
+      }
+
+      case 'consume': {
+        if (!s.recvTransport) return { error: 'recv transport not found' };
+        const canConsume = (router as any).canConsume({ producerId: payload.producerId, rtpCapabilities: payload.rtpCapabilities });
+        if (!canConsume) return { error: 'cannot consume' };
+        const consumer = await (s.recvTransport as any).consume({
+          producerId: payload.producerId,
+          rtpCapabilities: payload.rtpCapabilities,
+          paused: true,
+        });
+        s.consumers.set(consumer.id, consumer);
+        return {
+          id: consumer.id,
+          producerId: consumer.producerId,
+          kind: consumer.kind,
+          rtpParameters: consumer.rtpParameters,
+        };
+      }
+
+      case 'closeProducer': {
+        const p = s.producers.get(String(payload.producerId));
+        if (p) { (p as any).close(); s.producers.delete(String(payload.producerId)); }
+        return { closed: true };
+      }
+
+      case 'closeConsumer': {
+        const c = s.consumers.get(String(payload.consumerId));
+        if (c) { (c as any).close(); s.consumers.delete(String(payload.consumerId)); }
+        return { closed: true };
+      }
+
+      default:
+        return { error: `unknown media action` };
+    }
+  }
+
+  /** Clean up a connection's transports/producers/consumers on disconnect. */
+  cleanup(conn: Connection): void {
+    const s = this.states.get(conn);
+    if (!s) return;
+    for (const p of s.producers.values()) try { (p as any).close(); } catch { /* ignore */ }
+    for (const c of s.consumers.values()) try { (c as any).close(); } catch { /* ignore */ }
+    try { (s.sendTransport as any)?.close(); } catch { /* ignore */ }
+    try { (s.recvTransport as any)?.close(); } catch { /* ignore */ }
+    this.states.delete(conn);
+  }
+
+  /** Whether mediasoup is importable on this process (for capability checks). */
+  static async isAvailable(): Promise<boolean> {
+    try { await import('mediasoup'); return true; } catch { return false; }
+  }
+}

package/packages/nexus-realtime/src/server/RealtimeServer.ts

@@ -0,0 +1,252 @@
+import { WebSocketServer, WebSocket } from 'ws';
+import type { IncomingMessage, Server as HttpServer } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { randomBytes } from 'node:crypto';
+import type { AuthService, CsrfOptions } from '@bhooai/nexus-auth';
+import { checkWsUpgrade } from '@bhooai/nexus-auth';
+import { AuthenticationError } from '@bhooai/nexus-core';
+import type { ClientMessage, ServerMessage, Connection } from '../types.js';
+import type { PubSubAdapter } from '../adapter/PubSubAdapter.js';
+import { MemoryPubSubAdapter } from '../adapter/PubSubAdapter.js';
+import type { MediasoupAdapter } from '../mediasoup/MediasoupAdapter.js';
+
+export interface RealtimeServerOptions {
+  /** The HTTP server to attach the WebSocket upgrade handler to. */
+  httpServer: HttpServer;
+  /** WS path (default '/ws'). */
+  path?: string;
+  /** Auth service for access-token verification on upgrade (optional → anonymous). */
+  authService?: AuthService;
+  /** CSRF options for the WS upgrade origin + double-submit check (optional). */
+  csrfOptions?: CsrfOptions;
+  /** Pub/sub adapter for cross-instance fanout (default in-memory). */
+  adapter?: PubSubAdapter;
+  /** mediasoup SFU adapter for media routing (optional). */
+  mediasoup?: MediasoupAdapter;
+  /** Require authentication on upgrade (default true when authService provided). */
+  requireAuth?: boolean;
+}
+
+const CONN_CHANNEL = (id: string) => `conn:${id}`;
+const ROOM_CHANNEL = (room: string) => `room:${room}`;
+
+/**
+ * WebSocket realtime server. Attaches to an HTTP server's 'upgrade' event,
+ * authenticates the upgrade (access token via `?token=` query, optional CSRF
+ * origin/double-submit check), and dispatches client messages: room join/leave,
+ * WebRTC offer/answer/ICE-candidate relay, and app broadcasts.
+ *
+ * Cross-instance fanout uses the pub/sub adapter: direct peer messages are
+ * published to `conn:<id>` (delivered by whichever instance hosts the peer);
+ * room events are published to `room:<room>` (delivered to every instance with
+ * local members).
+ */
+export class RealtimeServer {
+  private wss: WebSocketServer;
+  private adapter: PubSubAdapter;
+  private connections = new Map<string, Connection>();
+  /** Local members per room (connIds on THIS instance). */
+  private roomMembers = new Map<string, Set<string>>();
+  private subscribedRooms = new Set<string>();
+  private opts: RealtimeServerOptions;
+
+  constructor(opts: RealtimeServerOptions) {
+    this.opts = opts;
+    this.adapter = opts.adapter ?? new MemoryPubSubAdapter();
+    this.wss = new WebSocketServer({ noServer: true });
+    this.opts.httpServer.on('upgrade', (req, socket, head) => this.handleUpgrade(req, socket, head));
+  }
+
+  private async handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): Promise<void> {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    // Only handle our WS path; let other upgrade listeners handle the rest.
+    if (url.pathname !== (this.opts.path ?? '/ws')) return;
+
+    try {
+      // 1. CSRF + origin check (WS has no CORS preflight).
+      if (this.opts.csrfOptions) checkWsUpgrade(req.headers as Record<string, string | string[] | undefined>, this.opts.csrfOptions);
+
+      // 2. Authenticate via ?token=<accessToken> (or subprotocol).
+      const token = (url.searchParams.get('token') ?? req.headers['sec-websocket-protocol']?.split(',').map((s) => s.trim())[0]) ?? '';
+      let userId: string | undefined;
+      let roles: string[] = [];
+      if (this.opts.authService && token) {
+        const payload = await this.opts.authService.verifyAccessToken(token);
+        userId = payload.sub;
+        roles = payload.roles ?? [];
+      } else if (this.opts.requireAuth ?? !!this.opts.authService) {
+        throw new AuthenticationError('Missing access token');
+      }
+
+      this.wss.handleUpgrade(req, socket, head, (ws) => {
+        const id = userId ?? randomBytes(9).toString('base64url');
+        this.register(ws, id, userId, roles);
+      });
+    } catch (err) {
+      socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+      socket.destroy();
+    }
+  }
+
+  private register(ws: WebSocket, id: string, userId: string | undefined, roles: string[]): void {
+    const conn: Connection = {
+      id,
+      userId,
+      roles,
+      rooms: new Set(),
+      get isOpen() { return ws.readyState === ws.OPEN; },
+      send: (message) => { if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(message)); },
+      close: (code, reason) => ws.close(code, reason),
+    };
+    this.connections.set(id, conn);
+
+    // Subscribe to this connection's direct channel (cross-instance delivery).
+    const direct = (raw: Buffer | string) => {
+      const msg = JSON.parse(raw.toString()) as ServerMessage;
+      conn.send(msg);
+    };
+    this.adapter.subscribe(CONN_CHANNEL(id), direct);
+    (conn as Connection & { _direct?: unknown })._direct = direct;
+
+    ws.on('message', (data) => this.onMessage(conn, data.toString('utf8')));
+    ws.on('close', () => this.onClose(conn, direct));
+    ws.on('error', () => this.onClose(conn, direct));
+  }
+
+  private async onMessage(conn: Connection, raw: string): Promise<void> {
+    let msg: ClientMessage;
+    try {
+      msg = JSON.parse(raw) as ClientMessage;
+    } catch {
+      conn.send({ type: 'error', message: 'Invalid JSON' });
+      return;
+    }
+    switch (msg.type) {
+      case 'ping':
+        conn.send({ type: 'pong' });
+        return;
+      case 'join':
+        await this.joinRoom(conn, msg.room);
+        return;
+      case 'leave':
+        await this.leaveRoom(conn, msg.room);
+        return;
+      case 'offer':
+      case 'answer':
+      case 'candidate': {
+        const to = this.connections.get(msg.to);
+        if (to) {
+          // Same instance: send directly.
+          to.send(this.relayFrom(conn, msg));
+        } else {
+          // Cross-instance: publish to the peer's direct channel (best-effort).
+          this.adapter.publish(CONN_CHANNEL(msg.to), JSON.stringify(this.relayFrom(conn, msg)));
+        }
+        return;
+      }
+      case 'broadcast':
+        this.broadcastRoom(msg.room, { type: 'broadcast', room: msg.room, from: conn.id, event: msg.event, data: msg.data });
+        return;
+      case 'media':
+        await this.handleMedia(conn, msg);
+        return;
+      default:
+        conn.send({ type: 'error', message: `Unknown message type` });
+    }
+  }
+
+  private relayFrom(conn: Connection, msg: ClientMessage): ServerMessage {
+    if (msg.type === 'offer') return { type: 'offer', from: conn.id, sdp: msg.sdp };
+    if (msg.type === 'answer') return { type: 'answer', from: conn.id, sdp: msg.sdp };
+    if (msg.type === 'candidate') return { type: 'candidate', from: conn.id, candidate: msg.candidate };
+    throw new Error('Cannot relay a non-peer message');
+  }
+
+  private async joinRoom(conn: Connection, room: string): Promise<void> {
+    if (conn.rooms.has(room)) return;
+    let set = this.roomMembers.get(room);
+    const wasEmpty = !set || set.size === 0;
+    if (!set) { set = new Set(); this.roomMembers.set(room, set); }
+    set.add(conn.id);
+    conn.rooms.add(room);
+
+    if (wasEmpty && !this.subscribedRooms.has(room)) {
+      this.adapter.subscribe(ROOM_CHANNEL(room), this.deliverRoom);
+      this.subscribedRooms.add(room);
+    }
+    // Notify everyone (including cross-instance) that a peer joined.
+    this.adapter.publish(ROOM_CHANNEL(room), JSON.stringify({ type: 'peer-joined', room, peer: conn.id }));
+    // Tell the joiner who's already here (local members).
+    const peers = [...set].filter((id) => id !== conn.id);
+    conn.send({ type: 'joined', room, peers });
+  }
+
+  private async leaveRoom(conn: Connection, room: string): Promise<void> {
+    conn.rooms.delete(room);
+    const set = this.roomMembers.get(room);
+    if (!set) return;
+    set.delete(conn.id);
+    this.adapter.publish(ROOM_CHANNEL(room), JSON.stringify({ type: 'peer-left', room, peer: conn.id }));
+    conn.send({ type: 'left', room });
+    if (set.size === 0) {
+      this.roomMembers.delete(room);
+      this.subscribedRooms.delete(room);
+      this.adapter.unsubscribe(ROOM_CHANNEL(room), this.deliverRoom);
+    }
+  }
+
+  /** Deliver a room-channel message to all local members of that room, skipping the originator. */
+  private deliverRoom = (raw: Buffer | string): void => {
+    const msg = JSON.parse(raw.toString()) as ServerMessage & { room?: string };
+    const room = msg.room;
+    if (!room) return;
+    const set = this.roomMembers.get(room);
+    if (!set) return;
+    // The originator must not receive its own join/leave/broadcast echo.
+    const origin =
+      msg.type === 'peer-joined' || msg.type === 'peer-left' ? (msg as { peer: string }).peer
+      : msg.type === 'broadcast' ? (msg as { from: string }).from
+      : undefined;
+    for (const id of set) {
+      if (id === origin) continue;
+      this.connections.get(id)?.send(msg);
+    }
+  };
+
+  private broadcastRoom(room: string, msg: ServerMessage): void {
+    this.adapter.publish(ROOM_CHANNEL(room), JSON.stringify(msg));
+  }
+
+  /** Publish an application event to every authenticated connection in a room. */
+  broadcast(room: string, event: string, data?: unknown): void {
+    this.broadcastRoom(room, { type: 'broadcast', room, from: 'server', event, data });
+  }
+
+  private async handleMedia(conn: Connection, msg: ClientMessage & { type: 'media' }): Promise<void> {
+    if (!this.opts.mediasoup) {
+      conn.send({ type: 'error', message: 'mediasoup SFU not enabled', code: 'NO_SFU' });
+      return;
+    }
+    const reply = await this.opts.mediasoup.handle(conn, msg.action, msg.payload);
+    conn.send({ type: 'media', action: msg.action, payload: reply });
+  }
+
+  private async onClose(conn: Connection, direct: (raw: Buffer | string) => void): Promise<void> {
+    this.connections.delete(conn.id);
+    this.adapter.unsubscribe(CONN_CHANNEL(conn.id), direct);
+    for (const room of [...conn.rooms]) await this.leaveRoom(conn, room);
+    this.opts.mediasoup?.cleanup(conn);
+  }
+
+  /** Number of live connections (test/monitoring helper). */
+  get connectionCount(): number {
+    return this.connections.size;
+  }
+
+  /** Close the WS server and all connections. */
+  close(): Promise<void> {
+    for (const conn of this.connections.values()) conn.close(1001, 'server shutting down');
+    this.wss.close();
+    return Promise.resolve();
+  }
+}

package/packages/nexus-realtime/src/types.ts

@@ -0,0 +1,52 @@
+/** Messages a client may send over the WebSocket. */
+export type ClientMessage =
+  | { type: 'join'; room: string }
+  | { type: 'leave'; room: string }
+  | { type: 'offer'; to: string; sdp: string; room?: string }
+  | { type: 'answer'; to: string; sdp: string; room?: string }
+  | { type: 'candidate'; to: string; candidate: unknown; room?: string }
+  | { type: 'broadcast'; room: string; event: string; data?: unknown }
+  | { type: 'ping' }
+  | { type: 'media'; action: MediaAction; payload: Record<string, unknown> };
+
+/** Messages the server sends to a client. */
+export type ServerMessage =
+  | { type: 'joined'; room: string; peers: string[] }
+  | { type: 'left'; room: string }
+  | { type: 'peer-joined'; room: string; peer: string }
+  | { type: 'peer-left'; room: string; peer: string }
+  | { type: 'offer'; from: string; sdp: string }
+  | { type: 'answer'; from: string; sdp: string }
+  | { type: 'candidate'; from: string; candidate: unknown }
+  | { type: 'broadcast'; room: string; from: string; event: string; data?: unknown }
+  | { type: 'pong' }
+  | { type: 'media'; action: MediaAction; payload: Record<string, unknown> }
+  | { type: 'error'; message: string; code?: string };
+
+/** mediasoup signaling actions relayed over WS. */
+export type MediaAction =
+  | 'getRouterRtpCapabilities'
+  | 'createWebRtcTransport'
+  | 'connectTransport'
+  | 'produce'
+  | 'consume'
+  | 'closeProducer'
+  | 'closeConsumer';
+
+/** A connected client's server-side record. */
+export interface Connection {
+  /** Stable id for this connection (the user id when authenticated, else random). */
+  id: string;
+  /** Authenticated user id (undefined for anonymous connections). */
+  userId?: string;
+  /** Roles from the access token. */
+  roles: string[];
+  /** Rooms this connection has joined (on this instance). */
+  rooms: Set<string>;
+  /** Send a JSON message to the client. */
+  send(message: ServerMessage): void;
+  /** Close the connection. */
+  close(code?: number, reason?: string): void;
+  /** Whether the underlying socket is still open. */
+  readonly isOpen: boolean;
+}

package/packages/nexus-telemetry/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@bhooai/nexus-telemetry",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/packages/nexus-telemetry/src/index.ts

@@ -0,0 +1,3 @@
+export * from './logger/Logger.js';
+export * from './metrics/Metrics.js';
+export * from './trace.js';

package/packages/nexus-telemetry/src/logger/Logger.ts

@@ -0,0 +1,178 @@
+import { createWriteStream, existsSync, mkdirSync, renameSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { EOL } from 'node:os';
+
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+export const LEVEL_ORDER: Record<LogLevel, number> = {
+  trace: 10,
+  debug: 20,
+  info: 30,
+  warn: 40,
+  error: 50,
+  fatal: 60,
+};
+
+export interface LogRecord {
+  level: LogLevel;
+  time: number;
+  msg: string;
+  [key: string]: unknown;
+}
+
+export interface LoggerOptions {
+  level?: LogLevel;
+  format?: 'json' | 'pretty';
+  console?: boolean;
+  /** File transport settings. */
+  file?: { dir: string; maxFileSize: number; maxFiles: number };
+  /** Field names to redact (replaced with [REDACTED]). */
+  redact?: string[];
+  /** Default bindings applied to every record. */
+  bindings?: Record<string, unknown>;
+}
+
+const COLORS: Record<LogLevel, string> = {
+  trace: '\x1b[90m',
+  debug: '\x1b[36m',
+  info: '\x1b[32m',
+  warn: '\x1b[33m',
+  error: '\x1b[31m',
+  fatal: '\x1b[35m',
+};
+const RESET = '\x1b[0m';
+
+/** Inbuilt structured logger with JSON/pretty formatting, redaction, and rotating file transport. */
+export class Logger {
+  private opts: Required<Pick<LoggerOptions, 'level' | 'format' | 'console' | 'redact'>> & {
+    file?: NonNullable<LoggerOptions['file']>;
+    bindings: Record<string, unknown>;
+  };
+  private stream: NodeJS.WritableStream | null = null;
+  private currentSize = 0;
+
+  constructor(opts: LoggerOptions = {}) {
+    this.opts = {
+      level: opts.level ?? 'info',
+      format: opts.format ?? 'pretty',
+      console: opts.console ?? true,
+      redact: opts.redact ?? [],
+      file: opts.file,
+      bindings: opts.bindings ?? {},
+    };
+    if (this.opts.file) this.openStream(this.opts.file);
+  }
+
+  private openStream(file: NonNullable<LoggerOptions['file']>): void {
+    if (!existsSync(file.dir)) mkdirSync(file.dir, { recursive: true });
+    const target = join(file.dir, 'nexus.log');
+    try {
+      this.currentSize = existsSync(target) ? statSync(target).size : 0;
+    } catch {
+      this.currentSize = 0;
+    }
+    this.stream = createWriteStream(target, { flags: 'a' });
+    this.stream.on('error', () => {
+      this.stream = null;
+    });
+  }
+
+  child(bindings: Record<string, unknown>): Logger {
+    return new Logger({
+      level: this.opts.level,
+      format: this.opts.format,
+      console: this.opts.console,
+      file: this.opts.file,
+      redact: this.opts.redact,
+      bindings: { ...this.opts.bindings, ...bindings },
+    });
+  }
+
+  setLevel(level: LogLevel): void {
+    this.opts.level = level;
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    return LEVEL_ORDER[level] >= LEVEL_ORDER[this.opts.level];
+  }
+
+  log(level: LogLevel, msg: string, data?: Record<string, unknown>): void {
+    if (!this.shouldLog(level)) return;
+    const record: LogRecord = {
+      level,
+      time: Date.now(),
+      msg,
+      ...this.opts.bindings,
+      ...(data ?? {}),
+    };
+    const safe = this.redactFields(record);
+    const line = this.opts.format === 'json' ? JSON.stringify(safe) : this.pretty(safe);
+    this.write(line + EOL, level);
+  }
+
+  private redactFields(record: LogRecord): LogRecord {
+    if (this.opts.redact.length === 0) return record;
+    const out: LogRecord = { ...record };
+    for (const key of this.opts.redact) {
+      if (key in out) out[key] = '[REDACTED]';
+    }
+    return out;
+  }
+
+  private pretty(rec: LogRecord): string {
+    const time = new Date(rec.time).toISOString();
+    const levelTag = `${COLORS[rec.level]}${rec.level.toUpperCase().padEnd(5)}${RESET}`;
+    const base = Object.fromEntries(
+      Object.entries(rec).filter(([k]) => k !== 'level' && k !== 'time' && k !== 'msg'),
+    );
+    const payload = Object.keys(base).length ? ` ${JSON.stringify(base)}` : '';
+    return `${time} ${levelTag} ${rec.msg}${payload}`;
+  }
+
+  private write(line: string, level: LogLevel): void {
+    if (this.opts.console) {
+      if (level === 'error' || level === 'fatal') process.stderr.write(line);
+      else process.stdout.write(line);
+    }
+    if (this.stream && this.opts.file) {
+      this.currentSize += Buffer.byteLength(line);
+      this.stream.write(line);
+      if (this.currentSize >= this.opts.file.maxFileSize) this.rotate();
+    }
+  }
+
+  private rotate(): void {
+    const file = this.opts.file!;
+    const target = join(file.dir, 'nexus.log');
+    if (!existsSync(target)) return;
+    this.stream?.end();
+    for (let i = file.maxFiles - 1; i > 0; i--) {
+      const from = join(file.dir, `nexus.${i - 1}.log`);
+      const to = join(file.dir, `nexus.${i}.log`);
+      if (existsSync(from)) renameSync(from, to);
+    }
+    renameSync(target, join(file.dir, 'nexus.0.log'));
+    this.currentSize = 0;
+    this.stream = createWriteStream(target, { flags: 'a' });
+  }
+
+  // Convenience level methods
+  trace(msg: string, data?: Record<string, unknown>): void { this.log('trace', msg, data); }
+  debug(msg: string, data?: Record<string, unknown>): void { this.log('debug', msg, data); }
+  info(msg: string, data?: Record<string, unknown>): void { this.log('info', msg, data); }
+  warn(msg: string, data?: Record<string, unknown>): void { this.log('warn', msg, data); }
+  error(msg: string, data?: Record<string, unknown>): void { this.log('error', msg, data); }
+  fatal(msg: string, data?: Record<string, unknown>): void { this.log('fatal', msg, data); }
+
+  /** Flush file transport. */
+  close(): Promise<void> {
+    return new Promise((resolve) => {
+      if (this.stream) this.stream.end(() => resolve());
+      else resolve();
+    });
+  }
+}
+
+/** A no-op file-less logger for tests / library contexts. */
+export function createLogger(opts?: LoggerOptions): Logger {
+  return new Logger({ console: false, ...opts });
+}