bhooai-nexus 0.1.2

package/packages/nexus-core/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.json({ error: { code: 'NOT_FOUND', message: `No route for ${ctx.method} ${ctx.path}` } }, 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/packages/nexus-core/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/packages/nexus-core/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/packages/nexus-core/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/packages/nexus-core/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);
+}

package/packages/nexus-core/src/http/uploads.ts

@@ -0,0 +1,94 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { extname, basename, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import type { Router } from './Router.js';
+import type { Middleware, RequestContext } from './context.js';
+import type { UploadedFile } from './bodyParser.js';
+import { ValidationError } from '../errors.js';
+
+export interface UploadRouteOptions {
+  /** Directory where uploaded files are persisted. */
+  directory: string;
+  /** POST endpoint that accepts multipart/form-data. */
+  path?: string;
+  /** Public URL prefix returned for saved files. */
+  publicPath?: string;
+  /** Maximum size of an individual file. */
+  maxFileSize?: number;
+  /** Maximum number of files accepted in one request. */
+  maxFiles?: number;
+  /** Empty means all MIME types are accepted. */
+  allowedTypes?: string[];
+  /** Optional route middleware, such as authentication. */
+  middleware?: Middleware[];
+}
+
+export interface SavedUpload {
+  field: string;
+  originalName: string;
+  filename: string;
+  contentType: string;
+  size: number;
+  url: string;
+}
+
+/** Register a safe multipart upload endpoint backed by a local directory. */
+export function registerUploadRoutes(router: Router, options: UploadRouteOptions): void {
+  const path = options.path ?? '/uploads';
+  const publicPath = (options.publicPath ?? path).replace(/\/$/, '');
+  const maxFileSize = options.maxFileSize ?? 10 * 1024 * 1024;
+  const maxFiles = options.maxFiles ?? 20;
+  const allowedTypes = new Set(options.allowedTypes ?? []);
+  const directory = resolve(options.directory);
+
+  // The upload handler accepts both the configured path (`/uploads`) and any
+  // sub-path (`/uploads/images`, `/uploads/files`, ...) so the cluster's
+  // upload-path allocation can route different prefixes to different file nodes
+  // while every node still serves the same multipart endpoint.
+  const handler = async (ctx: import('./index.js').RequestContext) => {
+    const files = (ctx.state.files as UploadedFile[] | undefined) ?? [];
+    if (files.length === 0) throw new ValidationError('At least one file is required');
+    if (files.length > maxFiles) throw new ValidationError(`A maximum of ${maxFiles} files may be uploaded`);
+
+    for (const file of files) {
+      if (file.data.length > maxFileSize) {
+        throw new ValidationError(`File "${file.filename}" exceeds the ${maxFileSize}-byte limit`);
+      }
+      if (allowedTypes.size > 0 && !allowedTypes.has(file.contentType)) {
+        throw new ValidationError(`File type "${file.contentType}" is not allowed`);
+      }
+    }
+
+    await mkdir(directory, { recursive: true });
+    const saved: SavedUpload[] = [];
+    for (const file of files) {
+      const extension = safeExtension(file.filename);
+      const filename = `${randomUUID()}${extension}`;
+      await writeFile(join(directory, filename), file.data, { flag: 'wx' });
+      saved.push({
+        field: file.field,
+        originalName: basename(file.filename),
+        filename,
+        contentType: file.contentType,
+        size: file.data.length,
+        url: `${publicPath}/${filename}`,
+      });
+    }
+    ctx.json({ files: saved }, 201);
+  };
+  const mw = options.middleware ?? [];
+  router.post(path, handler, mw);
+  // Also accept sub-paths (/uploads/images, /uploads/files, ...) so upload-path
+  // allocation in the cluster LB can target specific file nodes by prefix.
+  router.post(`${path}/*`, handler, mw);
+}
+
+function safeExtension(filename: string): string {
+  const extension = extname(basename(filename)).toLowerCase();
+  return /^\.[a-z0-9]{1,10}$/.test(extension) ? extension : '';
+}
+
+/** Type guard useful to route handlers that consume parsed multipart state. */
+export function uploadedFiles(ctx: RequestContext): UploadedFile[] {
+  return (ctx.state.files as UploadedFile[] | undefined) ?? [];
+}

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

@@ -0,0 +1,4 @@
+export * from './config/index.js';
+export * from './di/index.js';
+export * from './errors.js';
+export * from './http/index.js';

package/packages/nexus-crypto/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@bhooai/nexus-crypto",
+  "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": {},
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}