@bhooai/nexus-core 0.1.0

package/src/http/uploads.ts

@@ -0,0 +1,85 @@
+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);
+
+  router.post(path, async (ctx) => {
+    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);
+  }, options.middleware ?? []);
+}
+
+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/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/tests/config.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { mergeConfig, configFromEnv, deepMerge } from '../src/index.js';
+
+describe('deepMerge', () => {
+  it('merges nested objects with later sources winning', () => {
+    const out = deepMerge({ a: { b: 1, c: 2 } }, { a: { b: 9 } });
+    expect(out).toEqual({ a: { b: 9, c: 2 } });
+  });
+
+  it('replaces arrays rather than concatenating', () => {
+    const out = deepMerge({ list: [1, 2] }, { list: [3] });
+    expect(out).toEqual({ list: [3] });
+  });
+});
+
+describe('configFromEnv', () => {
+  it('maps NEXUS_SERVER_PORT to { server: { port } } with coercion', () => {
+    const cfg = configFromEnv({ NEXUS_SERVER_PORT: '5000', NEXUS_SERVER_HTTPS: 'true' });
+    expect(cfg.server?.port).toBe(5000);
+    expect(cfg.server?.https).toBe(true);
+  });
+});
+
+describe('mergeConfig', () => {
+  it('applies user overrides over defaults and validates', () => {
+    const cfg = mergeConfig({ server: { port: 5000 }, auth: { jwt: { secret: 'supersecret' } } });
+    expect(cfg.server.port).toBe(5000);
+    expect(cfg.server.host).toBe('0.0.0.0'); // default retained
+    expect(cfg.auth.jwt.secret).toBe('supersecret');
+  });
+
+  it('rejects an invalid jwt secret length', () => {
+    expect(() => mergeConfig({ auth: { jwt: { secret: 'short' } } })).toThrow();
+  });
+
+  it('rejects an out-of-range port', () => {
+    expect(() => mergeConfig({ server: { port: 99999 } })).toThrow();
+  });
+
+  it('returns a frozen object', () => {
+    const cfg = mergeConfig({});
+    expect(Object.isFrozen(cfg)).toBe(true);
+  });
+});

package/tests/di.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { Container, ResolutionError } from '../src/index.js';
+
+describe('Container', () => {
+  it('resolves singletons once', () => {
+    const c = new Container();
+    let calls = 0;
+    c.register('counter', () => ++calls, { lifetime: 'singleton' });
+    expect(c.resolve('counter')).toBe(1);
+    expect(c.resolve('counter')).toBe(1);
+  });
+
+  it('resolves transients each time', () => {
+    const c = new Container();
+    let calls = 0;
+    c.register('counter', () => ++calls, { lifetime: 'transient' });
+    expect(c.resolve('counter')).toBe(1);
+    expect(c.resolve('counter')).toBe(2);
+  });
+
+  it('injects declared dependencies', () => {
+    const c = new Container();
+    c.register('base', () => 41);
+    c.register('derived', (container, base: number) => base + 1, { deps: ['base'] });
+    expect(c.resolve('derived')).toBe(42);
+  });
+
+  it('detects circular dependencies', () => {
+    const c = new Container();
+    c.register('a', (container) => container.resolve('b'), { deps: ['b'] });
+    c.register('b', (container) => container.resolve('a'), { deps: ['a'] });
+    expect(() => c.resolve('a')).toThrow(ResolutionError);
+  });
+
+  it('throws for unregistered services', () => {
+    const c = new Container();
+    expect(() => c.resolve('missing')).toThrow(ResolutionError);
+  });
+});

package/tests/http.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { Router, NexusServer, bodyParser, parseUrlEncoded, parseMultipart, registerUploadRoutes, serveStatic } from '../src/index.js';
+import { request } from 'node:http';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+function getJson(url: string, opts: { method?: string; headers?: Record<string, string>; body?: string } = {}): Promise<{ status: number; body: string; headers: Record<string, string | string[] | undefined> }> {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const req = request(
+      { hostname: u.hostname, port: u.port, path: u.pathname + u.search, method: opts.method ?? 'GET', headers: opts.headers },
+      (res) => {
+        let body = '';
+        res.on('data', (c) => (body += c));
+        res.on('end', () => resolve({ status: res.statusCode ?? 0, body, headers: res.headers }));
+      },
+    );
+    req.on('error', reject);
+    if (opts.body) req.write(opts.body);
+    req.end();
+  });
+}
+
+describe('Router', () => {
+  it('matches static routes and extracts params', () => {
+    const r = new Router();
+    r.get('/users/:id', (ctx) => ctx.json({ id: ctx.params.id }));
+    const m = r.match('GET', '/users/42');
+    expect(m).not.toBeNull();
+    expect(m!.params.id).toBe('42');
+  });
+
+  it('matches wildcards', () => {
+    const r = new Router();
+    r.get('/assets/*', (ctx) => ctx.text('ok'));
+    expect(r.match('GET', '/assets/a/b.css')).not.toBeNull();
+    expect(r.match('GET', '/other/x')).toBeNull();
+  });
+
+  it('returns 405 handler when method mismatches but path matches', () => {
+    const r = new Router();
+    r.post('/items', () => undefined);
+    const m = r.match('GET', '/items');
+    expect(m).not.toBeNull();
+  });
+
+  it('decodes URI-encoded params', () => {
+    const r = new Router();
+    r.get('/q/:term', () => undefined);
+    expect(r.match('GET', '/q/hello%20world')!.params.term).toBe('hello world');
+  });
+});
+
+describe('bodyParser', () => {
+  it('parses urlencoded', () => {
+    expect(parseUrlEncoded('a=1&b=hi%20there&b=2')).toEqual({ a: '1', b: ['hi there', '2'] });
+  });
+
+  it('parses multipart fields and files', () => {
+    const boundary = '----testboundary';
+    const body = Buffer.from(
+      `--${boundary}\r\n` +
+        'Content-Disposition: form-data; name="title"\r\n\r\n' +
+        'Hello\r\n' +
+        `--${boundary}\r\n` +
+        'Content-Disposition: form-data; name="upload"; filename="f.txt"\r\n' +
+        'Content-Type: text/plain\r\n\r\n' +
+        'file contents\r\n' +
+        `--${boundary}--\r\n`,
+    );
+    const { fields, files } = parseMultipart(body, boundary);
+    expect(fields.title).toBe('Hello');
+    expect(files[0]?.filename).toBe('f.txt');
+    expect(files[0]?.data.toString('utf8')).toBe('file contents');
+  });
+});
+
+describe('NexusServer end-to-end', () => {
+  let server: NexusServer;
+  let port: number;
+
+  afterEach(async () => {
+    if (server) await server.close();
+  });
+
+  it('routes a request and returns JSON', async () => {
+    const router = new Router();
+    router.get('/health', (ctx) => ctx.json({ ok: true }));
+    server = new NexusServer({ router, middleware: [bodyParser()] });
+    await server.listen(0, '127.0.0.1');
+    port = (server.address as import('node:net').AddressInfo).port;
+    const res = await getJson(`http://127.0.0.1:${port}/health`);
+    expect(res.status).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ ok: true });
+    expect(res.headers['x-request-id']).toBeDefined();
+  });
+
+  it('parses a JSON POST body', async () => {
+    const router = new Router();
+    router.post('/echo', (ctx) => ctx.json({ received: ctx.body }));
+    server = new NexusServer({ router, middleware: [bodyParser()] });
+    await server.listen(0, '127.0.0.1');
+    port = (server.address as import('node:net').AddressInfo).port;
+    const res = await getJson(`http://127.0.0.1:${port}/echo`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ msg: 'hi' }),
+    });
+    expect(res.status).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ received: { msg: 'hi' } });
+  });
+
+  it('returns 404 for unknown routes and 405 for wrong method', async () => {
+    const router = new Router();
+    router.post('/only', () => undefined);
+    server = new NexusServer({ router });
+    await server.listen(0, '127.0.0.1');
+    port = (server.address as import('node:net').AddressInfo).port;
+    const notFound = await getJson(`http://127.0.0.1:${port}/nope`);
+    expect(notFound.status).toBe(404);
+    const wrong = await getJson(`http://127.0.0.1:${port}/only`);
+    expect(wrong.status).toBe(405);
+    expect(wrong.headers['allow']).toBe('POST');
+  });
+
+  it('stores multipart uploads and serves them below a URL prefix', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'nexus-uploads-'));
+    const boundary = '----nexus-upload-test';
+    const body =
+      `--${boundary}\r\n` +
+      'Content-Disposition: form-data; name="file"; filename="hello.txt"\r\n' +
+      'Content-Type: text/plain\r\n\r\n' +
+      'hello nexus\r\n' +
+      `--${boundary}--\r\n`;
+    try {
+      const router = new Router();
+      registerUploadRoutes(router, { directory });
+      server = new NexusServer({
+        router,
+        middleware: [serveStatic(directory, { prefix: '/uploads' }), bodyParser()],
+      });
+      await server.listen(0, '127.0.0.1');
+      port = (server.address as import('node:net').AddressInfo).port;
+
+      const uploaded = await getJson(`http://127.0.0.1:${port}/uploads`, {
+        method: 'POST',
+        headers: { 'content-type': `multipart/form-data; boundary=${boundary}` },
+        body,
+      });
+      expect(uploaded.status).toBe(201);
+      const saved = JSON.parse(uploaded.body).files[0] as { url: string; filename: string };
+      expect(saved.url).toBe(`/uploads/${saved.filename}`);
+
+      const downloaded = await getJson(`http://127.0.0.1:${port}${saved.url}`);
+      expect(downloaded.status).toBe(200);
+      expect(downloaded.body).toBe('hello nexus');
+      expect((await readFile(join(directory, saved.filename))).toString()).toBe('hello nexus');
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineProject } from 'vitest/config';
+
+export default defineProject({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    globals: false,
+  },
+});