fluxion-ts 0.0.4

package/src/workers/options.ts

@@ -0,0 +1,77 @@
+/**
+ * Worker runtime tuning options.
+ */
+export interface ExecutorOptions {
+  /**
+   * Request timeout in milliseconds.
+   */
+  requestTimeoutMs: number;
+  /**
+   * Maximum concurrent requests allowed in the pool.
+   */
+  maxInflight: number;
+  /**
+   * Soft heap threshold in MB. Idle worker may restart after crossing it.
+   */
+  memorySoftLimitMb: number;
+  /**
+   * ! Hard heap threshold in MB. Worker is restarted once reached.
+   */
+  memoryHardLimitMb: number;
+  /**
+   * Memory telemetry interval in milliseconds.
+   */
+  memorySampleIntervalMs: number;
+  /**
+   * ! V8 old-generation limit per worker in MB.
+   */
+  maxOldGenerationSizeMb: number;
+  /**
+   * ! V8 young-generation limit per worker in MB.
+   */
+  maxYoungGenerationSizeMb: number;
+  /**
+   * Worker stack size in MB.
+   */
+  stackSizeMb: number;
+  /**
+   * ! Maximum response payload bytes allowed from worker to main thread.
+   */
+  maxResponseBytes: number;
+}
+
+/**
+ * Custom worker item used by `workerStrategy`.
+ */
+export interface WorkerStrategyCustomItem extends Partial<ExecutorOptions> {
+  /**
+   * Stable worker id.
+   */
+  id: string;
+  /**
+   * Database names this worker can access.
+   */
+  db: string[];
+}
+
+/**
+ * Worker strategy selector.
+ */
+export type WorkerStrategy = 'all' | WorkerStrategyCustomItem[];
+
+/**
+ * Resolves runtime options with framework defaults.
+ */
+export function resolveExecutorOptions(overrides: Partial<ExecutorOptions> = {}): ExecutorOptions {
+  return {
+    requestTimeoutMs: overrides.requestTimeoutMs ?? 3000,
+    maxInflight: overrides.maxInflight ?? 64,
+    memorySoftLimitMb: overrides.memorySoftLimitMb ?? 96,
+    memoryHardLimitMb: overrides.memoryHardLimitMb ?? 128,
+    memorySampleIntervalMs: overrides.memorySampleIntervalMs ?? 5000,
+    maxOldGenerationSizeMb: overrides.maxOldGenerationSizeMb ?? 128,
+    maxYoungGenerationSizeMb: overrides.maxYoungGenerationSizeMb ?? 32,
+    stackSizeMb: overrides.stackSizeMb ?? 4,
+    maxResponseBytes: overrides.maxResponseBytes ?? 2 * 1024 * 1024,
+  };
+}

package/src/workers/protocol.d.ts

@@ -0,0 +1,186 @@
+/**
+ * IPC protocol between main thread and runtime worker.
+ */
+export namespace protocol {
+  /**
+   * Supported runtime db drivers.
+   */
+  export type DbDriver = 'pg' | 'mysql2';
+
+  /**
+   * Normalized db connection config pushed from main thread to workers.
+   */
+  export interface WorkerDbConnectionConfig {
+    /**
+     * Driver used to initialize the connection pool.
+     */
+    driver: DbDriver;
+    /**
+     * Optional target context key for db module injection.
+     */
+    contextKey?: string;
+    /**
+     * Driver-specific pool options.
+     */
+    options: Record<string, unknown>;
+  }
+
+  /**
+   * Worker db config map keyed by database name.
+   */
+  export type WorkerDbConfigMap = Record<string, WorkerDbConnectionConfig>;
+
+  /**
+   * HTTP header value.
+   */
+  export type HeaderValue = string | string[];
+
+  /**
+   * HTTP header map.
+   */
+  export type Headers = Record<string, HeaderValue>;
+
+  /**
+   * Execute payload sent to worker.
+   */
+  export interface Payload {
+    /**
+     * Absolute path of the handler file.
+     */
+    filePath: string;
+    /**
+     * Version token generated from file metadata.
+     */
+    version: string;
+    /**
+     * HTTP method.
+     */
+    method: string;
+    /**
+     * Raw request target (pathname + query).
+     */
+    url: string;
+    /**
+     * Request headers.
+     */
+    headers: Headers;
+    /**
+     * Request body as binary payload.
+     */
+    body?: Uint8Array;
+    /**
+     * Client ip captured in main thread.
+     */
+    ip: string;
+  }
+
+  /**
+   * Main -> worker execute command.
+   */
+  export interface ExecuteMessage {
+    type: 'execute';
+    /**
+     * Correlation id for this request.
+     */
+    id: string;
+    payload: Payload;
+  }
+
+  /**
+   * Worker response payload to be applied on ServerResponse.
+   */
+  export interface SerializedResponse {
+    /**
+     * HTTP status code.
+     */
+    statusCode: number;
+    /**
+     * Serialized response headers.
+     */
+    headers: Record<string, string>;
+    /**
+     * Optional response body bytes.
+     */
+    body?: Uint8Array;
+  }
+
+  /**
+   * Serialized runtime error.
+   */
+  export interface SerializedError {
+    /**
+     * Error class name.
+     */
+    name: string;
+    /**
+     * Error message.
+     */
+    message: string;
+    /**
+     * Optional stack trace.
+     */
+    stack?: string;
+    /**
+     * Optional error code.
+     */
+    code?: string;
+  }
+
+  /**
+   * Worker -> main result event.
+   */
+  export interface ResultMessage {
+    type: 'result';
+    /**
+     * Correlation id matching ExecuteMessage.id.
+     */
+    id: string;
+    /**
+     * Whether execution succeeded.
+     */
+    ok: boolean;
+    /**
+     * Handler execution time in milliseconds.
+     */
+    elapsedMs: number;
+    /**
+     * Heap used when result is produced.
+     */
+    heapUsed: number;
+    response?: SerializedResponse;
+    error?: SerializedError;
+  }
+
+  /**
+   * Worker -> main periodic memory report.
+   */
+  export interface MemoryMessage {
+    type: 'memory';
+    /**
+     * V8 heap used bytes.
+     */
+    heapUsed: number;
+    /**
+     * Resident set size bytes.
+     */
+    rss: number;
+    /**
+     * External memory bytes.
+     */
+    external: number;
+    /**
+     * ArrayBuffer memory bytes.
+     */
+    arrayBuffers: number;
+  }
+
+  /**
+   * Union of commands accepted by worker.
+   */
+  export type InboundMessage = ExecuteMessage;
+
+  /**
+   * Union of events emitted by worker.
+   */
+  export type OutboundMessage = ResultMessage | MemoryMessage;
+}

package/tests/core/dynamic-directory.test.ts

@@ -0,0 +1,48 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createTempDirectory, ensureDir, removeDirectory } from '../helpers/test-utils.js';
+
+describe('dynamic-directory', () => {
+  const tempDirectories: string[] = [];
+
+  beforeEach(() => {
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(async () => {
+    for (const tempDirectory of tempDirectories.splice(0)) {
+      await removeDirectory(tempDirectory);
+    }
+
+    vi.restoreAllMocks();
+  });
+
+  it('creates missing dynamic directory', async () => {
+    const root = await createTempDirectory('fluxion-dynamic-directory-');
+    tempDirectories.push(root);
+
+    const dynamicDirectory = path.join(root, 'dynamic');
+    const existsBefore = await fs
+      .stat(dynamicDirectory)
+      .then(() => true)
+      .catch(() => false);
+
+    expect(existsBefore).toBe(false);
+
+    ensureDir(dynamicDirectory);
+
+    const stat = await fs.stat(dynamicDirectory);
+    expect(stat.isDirectory()).toBe(true);
+  });
+
+  it('does nothing when dynamic directory already exists', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-dynamic-existing-');
+    tempDirectories.push(dynamicDirectory);
+
+    ensureDir(dynamicDirectory);
+
+    const stat = await fs.stat(dynamicDirectory);
+    expect(stat.isDirectory()).toBe(true);
+  });
+});

package/tests/core/file-runtime.test.ts

@@ -0,0 +1,347 @@
+import http from 'node:http';
+import path from 'node:path';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  closeServer,
+  createTempDirectory,
+  listenEphemeral,
+  removeDirectory,
+  sleep,
+  writeFile,
+} from '../helpers/test-utils.js';
+import { createFileRuntime } from '@/workers/file-runtime.js';
+import type { FileRuntime, FileRuntimeOptions } from '@/workers/file-runtime.js';
+import { HandlerResult } from '@/common/consts.js';
+
+async function startRuntimeServer(
+  dynamicDirectory: string,
+  options?: FileRuntimeOptions,
+): Promise<{ server: http.Server; baseUrl: string; runtime: FileRuntime }> {
+  const runtime = createFileRuntime(dynamicDirectory, options);
+
+  const server = http.createServer((req, res) => {
+    void runtime
+      .handleRequest(req, res)
+      .then((result) => {
+        if (result === HandlerResult.NotFound) {
+          res.statusCode = 404;
+          res.end('not_found');
+        }
+      })
+      .catch((error: unknown) => {
+        res.statusCode = 500;
+        res.end(String(error));
+      });
+  });
+
+  server.once('close', () => {
+    void runtime.close();
+  });
+
+  const { baseUrl } = await listenEphemeral(server);
+  return { server, baseUrl, runtime };
+}
+
+describe('file-runtime', () => {
+  const tempDirectories: string[] = [];
+  const servers: http.Server[] = [];
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+
+    for (const server of servers.splice(0)) {
+      await closeServer(server);
+    }
+
+    for (const tempDirectory of tempDirectories.splice(0)) {
+      await removeDirectory(tempDirectory);
+    }
+  });
+
+  it('prefers index.mjs over sibling .mjs handler', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-runtime-priority-');
+    tempDirectories.push(dynamicDirectory);
+
+    await writeFile(
+      path.join(dynamicDirectory, 'aaa', 'bb', 'cc', 'index.mjs'),
+      "export default function handler(_req, res) { res.end('from-index'); }",
+    );
+    await writeFile(
+      path.join(dynamicDirectory, 'aaa', 'bb', 'cc.mjs'),
+      "export default function handler(_req, res) { res.end('from-file'); }",
+    );
+
+    const { server, baseUrl } = await startRuntimeServer(dynamicDirectory);
+    servers.push(server);
+
+    const response = await fetch(`${baseUrl}/aaa/bb/cc`);
+    expect(response.status).toBe(200);
+    expect(await response.text()).toBe('from-index');
+  });
+
+  it('reloads handler when file mtime and size change', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-runtime-reload-');
+    tempDirectories.push(dynamicDirectory);
+
+    const handlerFile = path.join(dynamicDirectory, 'aaa', 'bb', 'cc.mjs');
+
+    await writeFile(handlerFile, "export default function handler(_req, res) { res.end('v1'); }");
+
+    const { server, baseUrl } = await startRuntimeServer(dynamicDirectory);
+    servers.push(server);
+
+    const firstResponse = await fetch(`${baseUrl}/aaa/bb/cc`);
+    expect(await firstResponse.text()).toBe('v1');
+
+    await sleep(20);
+    await writeFile(handlerFile, "export default function handler(_req, res) { res.end('v2-reloaded'); }");
+
+    const secondResponse = await fetch(`${baseUrl}/aaa/bb/cc`);
+    expect(secondResponse.status).toBe(200);
+    expect(await secondResponse.text()).toBe('v2-reloaded');
+  });
+
+  it('waits for callback-style async handlers to end the response', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-runtime-callback-');
+    tempDirectories.push(dynamicDirectory);
+
+    await writeFile(
+      path.join(dynamicDirectory, 'delayed.mjs'),
+      "export default function handler(_req, res) { setTimeout(() => res.end('delayed-ok'), 20); }",
+    );
+
+    const { server, baseUrl } = await startRuntimeServer(dynamicDirectory);
+    servers.push(server);
+
+    const response = await fetch(`${baseUrl}/delayed`);
+    expect(response.status).toBe(200);
+    expect(await response.text()).toBe('delayed-ok');
+  });
+
+  it('serializes handler return value as json response', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-runtime-return-json-');
+    tempDirectories.push(dynamicDirectory);
+
+    await writeFile(
+      path.join(dynamicDirectory, 'return-json.mjs'),
+      [
+        'export default async function handler() {',
+        '  return { ok: true, count: 1 };',
+        '}',
+      ].join('\n'),
+    );
+
+    const { server, baseUrl } = await startRuntimeServer(dynamicDirectory);
+    servers.push(server);
+
+    const response = await fetch(`${baseUrl}/return-json`);
+    expect(response.status).toBe(200);
+    expect(response.headers.get('content-type')).toContain('application/json');
+    expect((await response.json()) as Record<string, unknown>).toEqual({ ok: true, count: 1 });
+  });
+
+  it('serves static .js files and blocks underscore directories', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-runtime-static-');
+    tempDirectories.push(dynamicDirectory);
+
+    await writeFile(path.join(dynamicDirectory, 'assets', 'app.js'), "console.log('app');");
+    await writeFile(
+      path.join(dynamicDirectory, '_lib', 'ping.mjs'),
+      "export default function handler(_req, res) { res.end('hidden'); }",
+    );
+
+    const { server, baseUrl } = await startRuntimeServer(dynamicDirectory);
+    servers.push(server);
+
+    const staticResponse = await fetch(`${baseUrl}/assets/app.js`);
+    expect(staticResponse.status).toBe(200);
+    expect(await staticResponse.text()).toContain("console.log('app')");
+    expect(staticResponse.headers.get('content-type')).toContain('text/javascript');
+
+    const hiddenHandlerResponse = await fetch(`${baseUrl}/_lib/ping`);
+    expect(hiddenHandlerResponse.status).toBe(404);
+    expect(await hiddenHandlerResponse.text()).toBe('not_found');
+
+    const hiddenStaticResponse = await fetch(`${baseUrl}/_lib/ping.mjs`);
+    expect(hiddenStaticResponse.status).toBe(404);
+    expect(await hiddenStaticResponse.text()).toBe('not_found');
+  });
+
+  it('creates route snapshot from .mjs handlers and static files', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-runtime-snapshot-');
+    tempDirectories.push(dynamicDirectory);
+
+    await writeFile(
+      path.join(dynamicDirectory, 'aaa', 'bb', 'cc', 'index.mjs'),
+      "export default function handler(_req, res) { res.end('from-index'); }",
+    );
+    await writeFile(
+      path.join(dynamicDirectory, 'aaa', 'bb', 'cc.mjs'),
+      "export default function handler(_req, res) { res.end('from-file'); }",
+    );
+    await writeFile(path.join(dynamicDirectory, 'public', 'app.js'), "console.log('app');");
+    await writeFile(path.join(dynamicDirectory, '_lib', 'internal.mjs'), 'export default () => {};');
+
+    const runtime = createFileRuntime(dynamicDirectory);
+    const snapshot = await runtime.getRouteSnapshot();
+
+    expect(snapshot.handlers).toEqual([
+      {
+        route: '/aaa/bb/cc',
+        file: 'aaa/bb/cc/index.mjs',
+        version: expect.stringContaining(':'),
+      },
+    ]);
+
+    expect(snapshot.staticFiles).toContainEqual({
+      route: '/public/app.js',
+      file: 'public/app.js',
+      version: expect.stringContaining(':'),
+    });
+
+    expect(snapshot.handlers.some((item) => item.file.includes('_lib'))).toBe(false);
+    expect(snapshot.staticFiles.some((item) => item.file.includes('_lib'))).toBe(false);
+  });
+
+  it('supports object-style default export and passes handler context', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-runtime-context-');
+    tempDirectories.push(dynamicDirectory);
+
+    await writeFile(
+      path.join(dynamicDirectory, 'ctx.mjs'),
+      [
+        'export default {',
+        '  handler(_req, res, context) {',
+        "    res.setHeader('x-worker-id', context.worker.id);",
+        "    res.end(typeof context.worker?.id === 'string' ? 'context-ok' : 'context-missing');",
+        '  },',
+        '};',
+      ].join('\n'),
+    );
+
+    const { server, baseUrl } = await startRuntimeServer(dynamicDirectory);
+    servers.push(server);
+
+    const response = await fetch(`${baseUrl}/ctx`);
+    expect(response.status).toBe(200);
+    expect(await response.text()).toBe('context-ok');
+    expect(response.headers.get('x-worker-id')).toContain('fluxion-worker-all');
+  });
+
+  it('injects module instances into context via modules declarations', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-runtime-db-config-');
+    tempDirectories.push(dynamicDirectory);
+
+    await writeFile(
+      path.join(dynamicDirectory, 'dbctx.mjs'),
+      [
+        'export default {',
+        '  modules: [',
+        '    {',
+        "      module: 'node:crypto',",
+        "      injectKey: 'mydb',",
+        '      factory: (cryptoModule) => {',
+        '        return {',
+        '          query(sql) {',
+        "            return cryptoModule.createHash('sha1').update(String(sql)).digest('hex');",
+        '          },',
+        '        };',
+        '      },',
+        '    },',
+        '  ],',
+        '  handler(_req, res, context) {',
+        "    const ready = typeof context.mydb?.query === 'function';",
+        "    const sample = ready ? context.mydb.query('select 1') : '';",
+        "    res.setHeader('x-ready', String(ready));",
+        '    res.end(ready && sample.length > 0 ? "module-connected" : "module-missing");',
+        '  },',
+        '};',
+      ].join('\n'),
+    );
+
+    const { server, baseUrl } = await startRuntimeServer(dynamicDirectory);
+    servers.push(server);
+
+    const response = await fetch(`${baseUrl}/dbctx`);
+    expect(response.status).toBe(200);
+    expect(await response.text()).toBe('module-connected');
+    expect(response.headers.get('x-ready')).toBe('true');
+  });
+
+  it('rejects legacy handler-level db declaration', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-runtime-db-shape-');
+    tempDirectories.push(dynamicDirectory);
+
+    await writeFile(
+      path.join(dynamicDirectory, 'invalid-db-shape.mjs'),
+      [
+        'export default {',
+        "  db: ['main'],",
+        '  handler(_req, res) {',
+        "    res.end('never');",
+        '  },',
+        '};',
+      ].join('\n'),
+    );
+
+    const { server, baseUrl } = await startRuntimeServer(dynamicDirectory);
+    servers.push(server);
+
+    const response = await fetch(`${baseUrl}/invalid-db-shape`);
+    expect(response.status).toBe(500);
+    expect(await response.text()).toContain('Legacy db declaration is no longer supported');
+  });
+
+  it('rejects modules declaration when injectKey is reserved', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-runtime-module-reserved-');
+    tempDirectories.push(dynamicDirectory);
+
+    await writeFile(
+      path.join(dynamicDirectory, 'invalid-inject-key.mjs'),
+      [
+        'export default {',
+        '  modules: [',
+        '    {',
+        "      module: 'node:crypto',",
+        "      injectKey: 'worker',",
+        '      factory: () => ({})',
+        '    },',
+        '  ],',
+        '  handler(_req, res) {',
+        "    res.end('never');",
+        '  },',
+        '};',
+      ].join('\n'),
+    );
+
+    const { server, baseUrl } = await startRuntimeServer(dynamicDirectory);
+    servers.push(server);
+
+    const response = await fetch(`${baseUrl}/invalid-inject-key`);
+    expect(response.status).toBe(500);
+    expect(await response.text()).toContain('injectKey "worker" is reserved');
+  });
+
+  it('fails request when worker response exceeds maxResponseBytes', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-runtime-res-size-');
+    tempDirectories.push(dynamicDirectory);
+
+    await writeFile(
+      path.join(dynamicDirectory, 'large.mjs'),
+      "export default function handler(_req, res) { res.end('0123456789'.repeat(40)); }",
+    );
+
+    const { server, baseUrl } = await startRuntimeServer(dynamicDirectory, {
+      workerOptions: {
+        maxResponseBytes: 128,
+      },
+    });
+    servers.push(server);
+
+    const response = await fetch(`${baseUrl}/large`);
+    expect(response.status).toBe(500);
+    expect(await response.text()).toContain('worker response too large');
+  });
+});