@bhooai/nexus-core 0.1.0

package/src/http/Router.ts

@@ -0,0 +1,149 @@
+import type { Handler, Middleware, Params, RequestContext } from './context.js';
+
+interface RouteNode {
+  static: Map<string, RouteNode>; // exact segment -> child
+  param?: { name: string; node: RouteNode };
+  wildcard?: { node: RouteNode };
+  handlers: Map<string, Handler>; // method -> handler
+  middleware: Middleware[];
+}
+
+function createNode(): RouteNode {
+  return { static: new Map(), handlers: new Map(), middleware: [] };
+}
+
+interface MatchResult {
+  handler: Handler;
+  params: Params;
+  middleware: Middleware[];
+  pattern: string;
+}
+
+/**
+ * Trie router supporting static segments, `:param` segments, and `*` wildcards.
+ * Per-route middleware runs before the handler; router-level middleware (via
+ * `use`) runs for all matched routes under its mount path.
+ */
+export class Router {
+  private root = createNode();
+  private globalMiddleware: Middleware[] = [];
+  private routeCount = 0;
+
+  /** Register router-level middleware. */
+  use(mw: Middleware): this;
+  use(path: string, mw: Middleware): this;
+  use(pathOrMw: string | Middleware, maybeMw?: Middleware): this {
+    if (typeof pathOrMw === 'function') {
+      this.globalMiddleware.push(pathOrMw);
+    } else if (maybeMw) {
+      // path-scoped middleware: attach to a node matched by prefix
+      const node = this.findOrCreateNode(pathOrMw);
+      node.middleware.push(maybeMw);
+    }
+    return this;
+  }
+
+  get(path: string, handler: Handler, mw: Middleware[] = []): this { return this.add('GET', path, handler, mw); }
+  post(path: string, handler: Handler, mw: Middleware[] = []): this { return this.add('POST', path, handler, mw); }
+  put(path: string, handler: Handler, mw: Middleware[] = []): this { return this.add('PUT', path, handler, mw); }
+  patch(path: string, handler: Handler, mw: Middleware[] = []): this { return this.add('PATCH', path, handler, mw); }
+  delete(path: string, handler: Handler, mw: Middleware[] = []): this { return this.add('DELETE', path, handler, mw); }
+  head(path: string, handler: Handler, mw: Middleware[] = []): this { return this.add('HEAD', path, handler, mw); }
+  options(path: string, handler: Handler, mw: Middleware[] = []): this { return this.add('OPTIONS', path, handler, mw); }
+
+  add(method: string, path: string, handler: Handler, mw: Middleware[] = []): this {
+    const node = this.findOrCreateNode(path);
+    node.handlers.set(method.toUpperCase(), handler);
+    for (const m of mw) node.middleware.push(m);
+    this.routeCount++;
+    return this;
+  }
+
+  /** Resolve a request to a route match, or null if none. */
+  match(method: string, path: string): MatchResult | null {
+    const segments = splitPath(path);
+    const params: Params = {};
+    const collectedMw: Middleware[] = [...this.globalMiddleware];
+
+    let node: RouteNode = this.root;
+    for (let i = 0; i < segments.length; i++) {
+      const seg = segments[i]!;
+      if (node.static.has(seg)) {
+        node = node.static.get(seg)!;
+      } else if (node.param) {
+        params[node.param.name] = decodeURIComponent(seg);
+        node = node.param.node;
+      } else if (node.wildcard) {
+        // Wildcard is terminal: consume the rest of the path.
+        node = node.wildcard.node;
+        if (node.middleware.length) collectedMw.push(...node.middleware);
+        break;
+      } else {
+        return null;
+      }
+      if (node.middleware.length) collectedMw.push(...node.middleware);
+    }
+
+    const handler = node.handlers.get(method);
+    if (!handler) {
+      // Method not allowed on this path — surface 405 if any method matches.
+      if (node.handlers.size > 0) {
+        return { handler: methodNotAllowedHandler(node.handlers), params, middleware: collectedMw, pattern: path };
+      }
+      return null;
+    }
+    return { handler, params, middleware: collectedMw, pattern: joinPattern(path) };
+  }
+
+  get size(): number {
+    return this.routeCount;
+  }
+
+  /** Enumerate registered (method, path) pairs — for OPTIONS/CORS introspection. */
+  routes(): Array<{ method: string; path: string }> {
+    const out: Array<{ method: string; path: string }> = [];
+    const walk = (node: RouteNode, prefix: string) => {
+      for (const [method] of node.handlers) out.push({ method, path: prefix || '/' });
+      for (const [seg, child] of node.static) walk(child, `${prefix}/${seg}`);
+      if (node.param) walk(node.param.node, `${prefix}/:${node.param.name}`);
+      if (node.wildcard) walk(node.wildcard.node, `${prefix}/*`);
+    };
+    walk(this.root, '');
+    return out;
+  }
+
+  private findOrCreateNode(path: string): RouteNode {
+    const segments = splitPath(path);
+    let node = this.root;
+    for (const seg of segments) {
+      if (seg === '*') {
+        if (!node.wildcard) node.wildcard = { node: createNode() };
+        node = node.wildcard.node;
+      } else if (seg.startsWith(':')) {
+        const name = seg.slice(1);
+        if (!node.param) node.param = { name, node: createNode() };
+        node.param.name = name;
+        node = node.param.node;
+      } else {
+        if (!node.static.has(seg)) node.static.set(seg, createNode());
+        node = node.static.get(seg)!;
+      }
+    }
+    return node;
+  }
+}
+
+function splitPath(path: string): string[] {
+  return path.split('/').filter((s) => s.length > 0);
+}
+
+function joinPattern(path: string): string {
+  return path.startsWith('/') ? path : `/${path}`;
+}
+
+function methodNotAllowedHandler(handlers: Map<string, Handler>): Handler {
+  return (ctx) => {
+    ctx.setHeader('allow', [...handlers.keys()].join(', '));
+    ctx.status(405);
+  };
+}

package/src/http/Server.ts

@@ -0,0 +1,145 @@
+import { createServer, IncomingMessage, Server as HttpServer, ServerResponse } from 'node:http';
+import { createServer as createHttpsServer } from 'node:https';
+import { readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import type { Middleware, RequestContext } from './context.js';
+import { createContext } from './context.js';
+import type { Router } from './Router.js';
+import { NexusError, toNexusError } from '../errors.js';
+
+/** Generate a request id (overridable for tests/injection). */
+export function newRequestId(): string {
+  return randomUUID();
+}
+
+export interface ServerOptions {
+  router: Router;
+  /** Global middleware run before routing. */
+  middleware?: Middleware[];
+  /** Trust X-Forwarded-* headers (boolean or hop count). */
+  trustProxy?: boolean | number;
+  /** Maximum request body size in bytes. */
+  bodyLimit?: number;
+  /** HTTPS cert/key paths (enables TLS when both present). */
+  certFile?: string;
+  keyFile?: string;
+  /** Called for each error to produce a JSON error body. */
+  onError?: (err: NexusError, ctx: RequestContext) => unknown;
+}
+
+/**
+ * Inbuilt HTTP server built on node:http (no express). Runs a middleware
+ * pipeline, dispatches to the router, propagates request/trace ids, and
+ * supports graceful shutdown.
+ */
+export class NexusServer {
+  private server: HttpServer;
+  private middleware: Middleware[];
+  private opts: ServerOptions;
+
+  constructor(opts: ServerOptions) {
+    this.opts = { trustProxy: false, bodyLimit: 1024 * 1024, ...opts };
+    this.middleware = opts.middleware ?? [];
+    const handler = (req: IncomingMessage, res: ServerResponse) => this.handle(req, res);
+    if (opts.certFile && opts.keyFile) {
+      this.server = createHttpsServer(
+        { cert: readFileSync(opts.certFile), key: readFileSync(opts.keyFile) },
+        handler,
+      );
+    } else {
+      this.server = createServer(handler);
+    }
+  }
+
+  use(mw: Middleware): this {
+    this.middleware.push(mw);
+    return this;
+  }
+
+  listen(port: number, host: string = '0.0.0.0'): Promise<void> {
+    return new Promise((resolve) => {
+      this.server.listen(port, host, () => resolve());
+    });
+  }
+
+  get address() {
+    return this.server.address();
+  }
+
+  /** The underlying node:http(s) server (for attaching WebSocket upgrades, etc.). */
+  get httpServer(): HttpServer {
+    return this.server;
+  }
+
+  close(): Promise<void> {
+    return new Promise((resolve) => this.server.close(() => resolve()));
+  }
+
+  private async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const requestId = (req.headers['x-request-id'] as string) ?? newRequestId();
+    res.setHeader('x-request-id', requestId);
+    const ctx = createContext(req, res, requestId);
+
+    try {
+      await this.runPipeline(ctx);
+    } catch (err) {
+      this.handleError(err, ctx);
+    }
+  }
+
+  private async runPipeline(ctx: RequestContext): Promise<void> {
+    const stack = [...this.middleware, this.dispatchMiddleware()];
+    let i = 0;
+    const next = async () => {
+      const mw = stack[i++];
+      if (mw) await mw(ctx, next);
+    };
+    await next();
+
+    if (!ctx.res.writableEnded) {
+      ctx.status(404);
+    }
+  }
+
+  private dispatchMiddleware(): Middleware {
+    return async (ctx, next) => {
+      const match = this.opts.router.match(ctx.method, ctx.path);
+      if (!match) {
+        await next();
+        return;
+      }
+      ctx.params = match.params;
+      ctx.routePattern = match.pattern;
+      // Run route middleware then the handler.
+      let i = 0;
+      const routeStack = [...match.middleware, match.handler];
+      const routeNext = async () => {
+        const fn = routeStack[i++];
+        if (fn) await fn(ctx, routeNext);
+      };
+      await routeNext();
+      await next();
+    };
+  }
+
+  private handleError(err: unknown, ctx: RequestContext): void {
+    if (ctx.res.writableEnded) return;
+    const ne = toNexusError(err);
+    const body = this.opts.onError ? this.opts.onError(ne, ctx) : defaultErrorBody(ne);
+    if (!ctx.res.headersSent) {
+      ctx.res.statusCode = ne.statusCode;
+      ctx.res.setHeader('content-type', 'application/json; charset=utf-8');
+    }
+    ctx.res.end(JSON.stringify(body));
+  }
+}
+
+function defaultErrorBody(err: NexusError): unknown {
+  return {
+    error: {
+      code: err.code,
+      message: err.message,
+      ...(err.details ? { details: err.details } : {}),
+    },
+  };
+}

package/src/http/bodyParser.ts

@@ -0,0 +1,129 @@
+import type { Middleware } from './context.js';
+import { NexusError } from '../errors.js';
+
+/** Read the full request body into a Buffer, capped at `limit` bytes. */
+export function readBody(req: import('node:http').IncomingMessage, limit: number): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    req.on('data', (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > limit) {
+        req.destroy();
+        reject(new NexusError('Request body too large', { code: 'BODY_TOO_LARGE', statusCode: 413 }));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Body parser middleware: parses JSON, urlencoded, and multipart/form-data
+ * (urlencoded + multipart use Node's querystring / a simple parser). For
+ * multipart file uploads, populates `ctx.state.files` with { field, filename,
+ * contentType, data } entries.
+ */
+export function bodyParser(limit = 1024 * 1024): Middleware {
+  return async (ctx, next) => {
+    const type = (ctx.headers['content-type'] ?? '').toString().split(';')[0]?.trim() ?? '';
+    if (ctx.method === 'GET' || ctx.method === 'HEAD' || !type) {
+      await next();
+      return;
+    }
+    const buf = await readBody(ctx.req, limit);
+    // Preserve the raw body for webhook signature verification (the parsed form
+    // loses exact byte order/encoding that the gateway's signature was computed over).
+    ctx.state.__rawBody = buf;
+    try {
+      if (type === 'application/json') {
+        ctx.body = buf.length ? JSON.parse(buf.toString('utf8')) : undefined;
+      } else if (type === 'application/x-www-form-urlencoded') {
+        ctx.body = parseUrlEncoded(buf.toString('utf8'));
+      } else if (type === 'text/plain') {
+        ctx.body = buf.toString('utf8');
+      } else if (type === 'multipart/form-data') {
+        const { fields, files } = parseMultipart(buf, getBoundary(ctx.headers['content-type']?.toString() ?? ''));
+        ctx.body = fields;
+        ctx.state.files = files;
+      } else {
+        ctx.body = buf;
+      }
+    } catch {
+      throw new NexusError('Invalid request body', { code: 'INVALID_BODY', statusCode: 400 });
+    }
+    await next();
+  };
+}
+
+function getBoundary(contentType: string): string | undefined {
+  const match = /boundary=("?)([^";]+)\1/.exec(contentType);
+  return match?.[2];
+}
+
+export function parseUrlEncoded(input: string): Record<string, string | string[]> {
+  const out: Record<string, string | string[]> = {};
+  for (const pair of input.split('&')) {
+    if (!pair) continue;
+    const eq = pair.indexOf('=');
+    const key = decodeURIComponent(eq === -1 ? pair : pair.slice(0, eq)).replace(/\+/g, ' ');
+    const val = decodeURIComponent(eq === -1 ? '' : pair.slice(eq + 1)).replace(/\+/g, ' ');
+    const existing = out[key];
+    if (existing === undefined) out[key] = val;
+    else if (Array.isArray(existing)) existing.push(val);
+    else out[key] = [existing, val];
+  }
+  return out;
+}
+
+export interface UploadedFile {
+  field: string;
+  filename: string;
+  contentType: string;
+  data: Buffer;
+}
+
+/** Minimal multipart/form-data parser sufficient for file uploads. */
+export function parseMultipart(buf: Buffer, boundary?: string): {
+  fields: Record<string, string>;
+  files: UploadedFile[];
+} {
+  const fields: Record<string, string> = {};
+  const files: UploadedFile[] = [];
+  if (!boundary) return { fields, files };
+  const delim = Buffer.from(`--${boundary}`);
+  const parts = splitBuffer(buf, delim).slice(1); // drop preamble
+  for (const part of parts) {
+    if (part.length === 0 || part.toString('utf8').trim() === '--') continue;
+    const headerEnd = part.indexOf('\r\n\r\n');
+    if (headerEnd === -1) continue;
+    const headerStr = part.subarray(0, headerEnd).toString('utf8');
+    const bodyBuf = part.subarray(headerEnd + 4, part.length - 2); // strip trailing \r\n
+    const disposition = /Content-Disposition: form-data;[^\r\n]*/i.exec(headerStr)?.[0] ?? '';
+    const name = /name="([^"]+)"/.exec(disposition)?.[1];
+    const filename = /filename="([^"]*)"/.exec(disposition)?.[1];
+    const contentType = /Content-Type: ([^\r\n]+)/i.exec(headerStr)?.[1]?.trim() ?? 'text/plain';
+    if (!name) continue;
+    if (filename !== undefined) {
+      files.push({ field: name, filename, contentType, data: bodyBuf });
+    } else {
+      fields[name] = bodyBuf.toString('utf8');
+    }
+  }
+  return { fields, files };
+}
+
+function splitBuffer(buf: Buffer, delim: Buffer): Buffer[] {
+  const out: Buffer[] = [];
+  let start = 0;
+  let idx = buf.indexOf(delim, start);
+  while (idx !== -1) {
+    out.push(buf.subarray(start, idx));
+    start = idx + delim.length;
+    idx = buf.indexOf(delim, start);
+  }
+  out.push(buf.subarray(start));
+  return out;
+}

package/src/http/context.ts

@@ -0,0 +1,112 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Socket } from 'node:net';
+
+/** Route path parameters extracted from the URL. */
+export type Params = Record<string, string>;
+
+/** Per-request mutable state shared across middleware. */
+export type State = Record<string, unknown>;
+
+export interface RequestContext {
+  /** The raw Node request. */
+  req: IncomingMessage;
+  /** The raw Node response. */
+  res: ServerResponse;
+  /** HTTP method, uppercased. */
+  method: string;
+  /** URL pathname (no query). */
+  path: string;
+  /** Parsed query string. */
+  query: Record<string, string | string[]>;
+  /** Route params. */
+  params: Params;
+  /** Headers (lowercased keys). */
+  headers: Record<string, string | string[] | undefined>;
+  /** Parsed request body (set by body parser middleware). */
+  body: unknown;
+  /** Per-request state. */
+  state: State;
+  /** Request id (also in headers as x-request-id). */
+  requestId: string;
+  /** The matched route pattern, e.g. "/users/:id". */
+  routePattern?: string;
+  /** Send a JSON response. */
+  json(data: unknown, status?: number): void;
+  /** Send a text response. */
+  text(data: string, status?: number): void;
+  /** Send an HTML response. */
+  html(data: string, status?: number): void;
+  /** Send an empty/status-only response. */
+  status(status: number): void;
+  /** Redirect to a location. */
+  redirect(location: string, status?: number): void;
+  /** Set a response header. */
+  setHeader(name: string, value: string | string[]): void;
+}
+
+export type Next = () => Promise<void> | void;
+
+export type Middleware = (ctx: RequestContext, next: Next) => Promise<void> | void;
+
+export type Handler = (ctx: RequestContext) => void | Promise<void>;
+
+/** Build a RequestContext from raw Node objects. */
+export function createContext(
+  req: IncomingMessage,
+  res: ServerResponse,
+  requestId: string,
+): RequestContext {
+  const url = new URL(req.url ?? '/', 'http://localhost');
+  const query: Record<string, string | string[]> = {};
+  for (const [k, v] of url.searchParams.entries()) {
+    const existing = query[k];
+    if (existing === undefined) query[k] = v;
+    else if (Array.isArray(existing)) existing.push(v);
+    else query[k] = [existing, v];
+  }
+  const ctx: RequestContext = {
+    req,
+    res,
+    method: (req.method ?? 'GET').toUpperCase(),
+    path: url.pathname,
+    query,
+    params: {},
+    headers: req.headers as Record<string, string | string[] | undefined>,
+    body: undefined,
+    state: {},
+    requestId,
+    json(data, status = 200) {
+      send(res, JSON.stringify(data), status, 'application/json; charset=utf-8');
+    },
+    text(data, status = 200) {
+      send(res, data, status, 'text/plain; charset=utf-8');
+    },
+    html(data, status = 200) {
+      send(res, data, status, 'text/html; charset=utf-8');
+    },
+    status(s) {
+      res.statusCode = s;
+      res.end();
+    },
+    redirect(location, status = 302) {
+      res.statusCode = status;
+      res.setHeader('location', location);
+      res.end();
+    },
+    setHeader(name, value) {
+      res.setHeader(name, value);
+    },
+  };
+  return ctx;
+}
+
+function send(res: ServerResponse, body: string, status: number, type: string): void {
+  res.statusCode = status;
+  res.setHeader('content-type', type);
+  res.end(body);
+}
+
+/** True if the socket is still writable (not closed). */
+export function isAlive(socket: Socket | undefined): boolean {
+  return !!socket && !socket.destroyed && socket.writable;
+}

package/src/http/index.ts

@@ -0,0 +1,6 @@
+export * from './context.js';
+export * from './Router.js';
+export * from './Server.js';
+export * from './bodyParser.js';
+export * from './static.js';
+export * from './uploads.js';

package/src/http/static.ts

@@ -0,0 +1,85 @@
+import { createReadStream, existsSync, statSync } from 'node:fs';
+import { extname, join, normalize, sep } from 'node:path';
+import type { Middleware } from './context.js';
+import { NotFoundError } from '../errors.js';
+
+const MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.map': 'application/json',
+  '.txt': 'text/plain; charset=utf-8',
+  '.webp': 'image/webp',
+  '.wasm': 'application/wasm',
+};
+
+/** Serve static files from `root`. Safe against path traversal. */
+export function serveStatic(root: string, options: { index?: string; prefix?: string } = {}): Middleware {
+  const index = options.index ?? 'index.html';
+  const prefix = normalizePrefix(options.prefix);
+  return async (ctx, next) => {
+    if (ctx.method !== 'GET' && ctx.method !== 'HEAD') {
+      await next();
+      return;
+    }
+    if (prefix && ctx.path !== prefix && !ctx.path.startsWith(`${prefix}/`)) {
+      await next();
+      return;
+    }
+    const requestPath = prefix ? ctx.path.slice(prefix.length) || '/' : ctx.path;
+    const safe = normalize(requestPath).replace(/^(\.\.[/\\])+/, '');
+    let filePath = join(root, safe);
+    if (isOutside(root, filePath)) {
+      throw new NotFoundError();
+    }
+    if (!existsSync(filePath)) {
+      await next();
+      return;
+    }
+    const initialStat = statSync(filePath);
+    if (initialStat.isDirectory()) {
+      filePath = join(filePath, index);
+      if (!existsSync(filePath)) {
+        await next();
+        return;
+      }
+    }
+    const stat = statSync(filePath);
+    const ext = extname(filePath).toLowerCase();
+    ctx.setHeader('content-type', MIME[ext] ?? 'application/octet-stream');
+    ctx.setHeader('content-length', String(stat.size));
+    ctx.setHeader('etag', `"${stat.size.toString(16)}-${stat.mtimeMs.toString(16)}"`);
+    if (ctx.method === 'HEAD') {
+      ctx.status(200);
+      return;
+    }
+    await new Promise<void>((resolveStream, rejectStream) => {
+      const stream = createReadStream(filePath);
+      stream.on('error', rejectStream);
+      stream.on('end', resolveStream);
+      stream.pipe(ctx.res);
+    });
+  };
+}
+
+function normalizePrefix(prefix: string | undefined): string {
+  if (!prefix || prefix === '/') return '';
+  return `/${prefix.replace(/^\/+|\/+$/g, '')}`;
+}
+
+function isOutside(root: string, target: string): boolean {
+  const rel = normalize(target).split(sep);
+  const base = normalize(root).split(sep);
+  return !normalize(target).startsWith(normalize(root) + sep) && normalize(target) !== normalize(root);
+}