fluxion-ts 0.0.4

package/tests/core/server-options.test.ts

@@ -0,0 +1,204 @@
+import { once } from 'node:events';
+import http from 'node:http';
+import path from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { fluxion } from '@/core/server.js';
+import type { FluxionDatabaseInput } from '@/core/server.js';
+import type { LogEntry, LoggerOption } from '@/common/logger.js';
+
+import { closeServer, createTempDirectory, removeDirectory, writeFile } from '../helpers/test-utils.js';
+
+interface StartServerOptions {
+  maxRequestBytes?: number;
+  logger?: LoggerOption;
+  databases?: FluxionDatabaseInput[];
+  dbConfigPath?: string;
+}
+
+async function startServer(
+  dynamicDirectory: string,
+  options: StartServerOptions = {},
+): Promise<{ server: http.Server; baseUrl: string }> {
+  const server = fluxion({
+    dir: dynamicDirectory,
+    host: '127.0.0.1',
+    port: 0,
+    maxRequestBytes: options.maxRequestBytes,
+    logger: options.logger,
+    databases: options.databases,
+    dbConfigPath: options.dbConfigPath,
+  });
+
+  if (!server.listening) {
+    await once(server, 'listening');
+  }
+
+  const address = server.address();
+  if (address === null || typeof address === 'string') {
+    throw new Error('Failed to resolve server address');
+  }
+
+  return {
+    server,
+    baseUrl: `http://127.0.0.1:${address.port}`,
+  };
+}
+
+describe('server options', () => {
+  const tempDirectories: string[] = [];
+  const servers: http.Server[] = [];
+  let consoleLogSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(async () => {
+    for (const server of servers.splice(0)) {
+      await closeServer(server);
+    }
+
+    for (const tempDirectory of tempDirectories.splice(0)) {
+      await removeDirectory(tempDirectory);
+    }
+
+    vi.restoreAllMocks();
+  });
+
+  it('enforces maxRequestBytes and returns 413 for oversized body', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-server-max-body-');
+    tempDirectories.push(dynamicDirectory);
+
+    await writeFile(
+      path.join(dynamicDirectory, 'echo.mjs'),
+      [
+        'export default function handler(req, res) {',
+        '  const chunks = [];',
+        "  req.on('data', (chunk) => chunks.push(Buffer.from(chunk)));",
+        "  req.on('end', () => res.end(String(Buffer.concat(chunks).byteLength)));",
+        '}',
+      ].join('\n'),
+    );
+
+    const { server, baseUrl } = await startServer(dynamicDirectory, { maxRequestBytes: 8 });
+    servers.push(server);
+
+    const oversizedResponse = await fetch(`${baseUrl}/echo`, {
+      method: 'POST',
+      body: '123456789',
+      headers: {
+        'content-type': 'text/plain',
+      },
+    });
+
+    expect(oversizedResponse.status).toBe(413);
+
+    const oversizedPayload = (await oversizedResponse.json()) as { message?: string };
+    expect(oversizedPayload.message).toContain('request body too large');
+
+    const okResponse = await fetch(`${baseUrl}/echo`, {
+      method: 'POST',
+      body: '12345',
+      headers: {
+        'content-type': 'text/plain',
+      },
+    });
+
+    expect(okResponse.status).toBe(200);
+    expect(await okResponse.text()).toBe('5');
+  });
+
+  it('rejects invalid maxRequestBytes at startup', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-server-max-body-invalid-');
+    tempDirectories.push(dynamicDirectory);
+
+    expect(() =>
+      fluxion({
+        dir: dynamicDirectory,
+        host: '127.0.0.1',
+        port: 0,
+        maxRequestBytes: 0,
+      }),
+    ).toThrow('Invalid maxRequestBytes');
+  });
+
+  it('loads db config from private file path', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-server-db-config-');
+    tempDirectories.push(dynamicDirectory);
+
+    await writeFile(
+      path.join(dynamicDirectory, 'ctx.mjs'),
+      [
+        'export default {',
+        '  handler(_req, res, context) {',
+        "    const ready = typeof context.worker?.id === 'string';",
+        "    res.end(ready ? 'worker-ready' : 'worker-missing');",
+        '  },',
+        '};',
+      ].join('\n'),
+    );
+
+    const privateConfigPath = path.join(dynamicDirectory, '.fluxion-private', 'db.config.cjs');
+    await writeFile(
+      privateConfigPath,
+      [
+        'module.exports = {',
+        "  main: {",
+        "    driver: 'pg',",
+        '    options: {},',
+        '  },',
+        '};',
+      ].join('\n'),
+    );
+
+    const { server, baseUrl } = await startServer(dynamicDirectory, {
+      dbConfigPath: privateConfigPath,
+    });
+    servers.push(server);
+
+    const response = await fetch(`${baseUrl}/ctx`);
+    expect(response.status).toBe(200);
+    expect(await response.text()).toBe('worker-ready');
+  });
+
+  it('supports json-line logger mode', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-server-logger-json-');
+    tempDirectories.push(dynamicDirectory);
+
+    const { server, baseUrl } = await startServer(dynamicDirectory, { logger: 'json-line' });
+    servers.push(server);
+
+    await fetch(`${baseUrl}/missing`);
+
+    const lines = consoleLogSpy.mock.calls
+      .map((call: unknown[]) => call[0])
+      .filter((value: unknown): value is string => typeof value === 'string');
+    expect(lines.length).toBeGreaterThan(0);
+
+    const entries = lines.map((line: string) => JSON.parse(line) as Record<string, unknown>);
+    expect(entries.some((entry: Record<string, unknown>) => entry.event === 'ServerStarted')).toBe(true);
+    expect(entries.some((entry: Record<string, unknown>) => entry.event === 'RequestCompleted')).toBe(true);
+  });
+
+  it('supports custom logger function', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-server-logger-custom-');
+    tempDirectories.push(dynamicDirectory);
+
+    const entries: LogEntry[] = [];
+
+    const { server, baseUrl } = await startServer(dynamicDirectory, {
+      logger(entry) {
+        entries.push(entry);
+      },
+    });
+    servers.push(server);
+
+    await fetch(`${baseUrl}/missing`);
+
+    expect(entries.some((entry) => entry.event === 'ServerStarted')).toBe(true);
+    expect(entries.some((entry) => entry.event === 'RequestCompleted')).toBe(true);
+    expect(consoleLogSpy).not.toHaveBeenCalled();
+  });
+});

package/tests/e2e/fluxion-server.e2e-spec.ts

@@ -0,0 +1,225 @@
+import { once } from 'node:events';
+import fs from 'node:fs/promises';
+import http from 'node:http';
+import path from 'node:path';
+
+import axios, { type AxiosInstance } from 'axios';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { fluxion } from '@/core/server.js';
+
+import { closeServer, createTempDirectory, removeDirectory, sleep, waitFor, writeFile } from '../helpers/test-utils.js';
+
+async function startFluxion(dynamicDirectory: string): Promise<{ server: http.Server; client: AxiosInstance }> {
+  const server = fluxion({
+    dir: dynamicDirectory,
+    host: '127.0.0.1',
+    port: 0,
+  });
+
+  if (!server.listening) {
+    await once(server, 'listening');
+  }
+
+  const address = server.address();
+  if (address === null || typeof address === 'string') {
+    throw new Error('Failed to resolve server address');
+  }
+
+  const baseURL = `http://127.0.0.1:${address.port}`;
+
+  const client = axios.create({
+    baseURL,
+    timeout: 2500,
+    validateStatus: () => true,
+    proxy: false,
+  });
+
+  return { server, client };
+}
+
+describe('fluxion e2e', () => {
+  const tempDirectories: string[] = [];
+  const servers: http.Server[] = [];
+
+  beforeEach(() => {
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(async () => {
+    for (const server of servers.splice(0)) {
+      await closeServer(server);
+    }
+
+    for (const tempDirectory of tempDirectories.splice(0)) {
+      await removeDirectory(tempDirectory);
+    }
+
+    vi.restoreAllMocks();
+  });
+
+  it('loads startup routes, serves static files, and exposes meta apis', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-e2e-startup-');
+    tempDirectories.push(dynamicDirectory);
+
+    await writeFile(
+      path.join(dynamicDirectory, 'aaa', 'bb', 'cc', 'index.mjs'),
+      "export default function handler(_req, res) { res.end('startup-ok'); }",
+    );
+    await writeFile(path.join(dynamicDirectory, 'aaa', 'public', 'app.js'), "console.log('startup');");
+
+    const { server, client } = await startFluxion(dynamicDirectory);
+    servers.push(server);
+
+    const nestedResponse = await client.get('/aaa/bb/cc');
+    expect(nestedResponse.status).toBe(200);
+    expect(nestedResponse.data).toBe('startup-ok');
+
+    const staticResponse = await client.get('/aaa/public/app.js');
+    expect(staticResponse.status).toBe(200);
+    expect(staticResponse.data).toContain("console.log('startup')");
+
+    const routesResponse = await client.get('/_fluxion/routes');
+    expect(routesResponse.status).toBe(200);
+    expect(routesResponse.data).toMatchObject({
+      routes: {
+        handlers: [
+          {
+            route: '/aaa/bb/cc',
+            file: 'aaa/bb/cc/index.mjs',
+          },
+        ],
+      },
+    });
+    expect(
+      routesResponse.data.routes.staticFiles.some(
+        (item: { route: string; file: string }) =>
+          item.route === '/aaa/public/app.js' && item.file === 'aaa/public/app.js',
+      ),
+    ).toBe(true);
+
+    const healthzResponse = await client.get('/_fluxion/healthz');
+    expect(healthzResponse.status).toBe(200);
+    expect(healthzResponse.data?.ok).toBe(true);
+
+    const workersResponse = await client.get('/_fluxion/workers');
+    expect(workersResponse.status).toBe(200);
+    expect(workersResponse.data).toMatchObject({
+      workers: {
+        dir: dynamicDirectory,
+      },
+    });
+    expect(Array.isArray(workersResponse.data.workers?.workers)).toBe(true);
+    expect(workersResponse.data.workers?.workers.length).toBeGreaterThanOrEqual(1);
+
+    const missingRouteResponse = await client.get('/missing/path');
+    expect(missingRouteResponse.status).toBe(404);
+    expect(missingRouteResponse.data).toMatchObject({
+      message: 'Route not found',
+    });
+  });
+
+  it('reflects route add and remove by file changes', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-e2e-add-remove-');
+    tempDirectories.push(dynamicDirectory);
+
+    const { server, client } = await startFluxion(dynamicDirectory);
+    servers.push(server);
+
+    await writeFile(
+      path.join(dynamicDirectory, 'bbb', 'hello.mjs'),
+      "export default function handler(_req, res) { res.end('watch-mounted'); }",
+    );
+
+    await waitFor(async () => {
+      const response = await client.get('/bbb/hello');
+      return response.status === 200 && response.data === 'watch-mounted';
+    });
+
+    const routesAfterAdd = await client.get('/_fluxion/routes');
+    expect(
+      routesAfterAdd.data.routes.handlers.some(
+        (item: { route: string; file: string }) => item.route === '/bbb/hello' && item.file === 'bbb/hello.mjs',
+      ),
+    ).toBe(true);
+
+    await fs.rm(path.join(dynamicDirectory, 'bbb', 'hello.mjs'), { force: true });
+
+    await waitFor(async () => {
+      const response = await client.get('/bbb/hello');
+      return response.status === 404 && response.data?.message === 'Route not found';
+    });
+
+    const routesAfterRemove = await client.get('/_fluxion/routes');
+    expect(routesAfterRemove.data.routes.handlers.some((item: { route: string }) => item.route === '/bbb/hello')).toBe(
+      false,
+    );
+  });
+
+  it('hot reloads mjs handler by mtime+size and returns 500 for invalid default export', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-e2e-reload-');
+    tempDirectories.push(dynamicDirectory);
+
+    const handlerFile = path.join(dynamicDirectory, 'ccc', 'task.mjs');
+
+    await writeFile(handlerFile, "export default function handler(_req, res) { res.end('v1'); }");
+
+    const { server, client } = await startFluxion(dynamicDirectory);
+    servers.push(server);
+
+    const firstResponse = await client.get('/ccc/task');
+    expect(firstResponse.status).toBe(200);
+    expect(firstResponse.data).toBe('v1');
+
+    await sleep(20);
+    await writeFile(handlerFile, "export default function handler(_req, res) { res.end('v2-hot'); }");
+
+    await waitFor(async () => {
+      const response = await client.get('/ccc/task');
+      return response.status === 200 && response.data === 'v2-hot';
+    });
+
+    await sleep(20);
+    await writeFile(handlerFile, 'export default { broken: true };');
+
+    await waitFor(async () => {
+      const response = await client.get('/ccc/task');
+      return response.status === 500 && response.data?.message === 'Internal Server Error';
+    });
+  });
+
+  it('blocks routing for underscore-prefixed directories', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-e2e-underscore-');
+    tempDirectories.push(dynamicDirectory);
+
+    await writeFile(
+      path.join(dynamicDirectory, '_lib', 'secret.mjs'),
+      "export default function handler(_req, res) { res.end('hidden'); }",
+    );
+    await writeFile(path.join(dynamicDirectory, '_lib', 'tool.js'), "console.log('hidden-tool');");
+    await writeFile(
+      path.join(dynamicDirectory, 'public', 'ping.mjs'),
+      "export default function handler(_req, res) { res.end('public-ok'); }",
+    );
+
+    const { server, client } = await startFluxion(dynamicDirectory);
+    servers.push(server);
+
+    const publicResponse = await client.get('/public/ping');
+    expect(publicResponse.status).toBe(200);
+    expect(publicResponse.data).toBe('public-ok');
+
+    const hiddenHandlerResponse = await client.get('/_lib/secret');
+    expect(hiddenHandlerResponse.status).toBe(404);
+
+    const hiddenStaticResponse = await client.get('/_lib/tool.js');
+    expect(hiddenStaticResponse.status).toBe(404);
+
+    const routesResponse = await client.get('/_fluxion/routes');
+    const hasHiddenRoute =
+      routesResponse.data.routes.handlers.some((item: { file: string }) => item.file.startsWith('_lib/')) ||
+      routesResponse.data.routes.staticFiles.some((item: { file: string }) => item.file.startsWith('_lib/'));
+
+    expect(hasHiddenRoute).toBe(false);
+  });
+});

package/tests/helpers/test-utils.ts

@@ -0,0 +1,81 @@
+import { once } from 'node:events';
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+
+export async function createTempDirectory(prefix: string): Promise<string> {
+  return fs.promises.mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+export async function removeDirectory(targetPath: string): Promise<void> {
+  await fs.promises.rm(targetPath, { recursive: true, force: true });
+}
+
+export async function writeFile(targetPath: string, content: string): Promise<void> {
+  await fs.promises.mkdir(path.dirname(targetPath), { recursive: true });
+  await fs.promises.writeFile(targetPath, content, 'utf8');
+}
+
+export async function waitFor(predicate: () => Promise<boolean>, timeoutMs = 5000, stepMs = 50): Promise<void> {
+  const startAt = Date.now();
+
+  while (Date.now() - startAt <= timeoutMs) {
+    if (await predicate()) {
+      return;
+    }
+
+    await sleep(stepMs);
+  }
+
+  throw new Error(`Condition not met within ${timeoutMs}ms`);
+}
+
+export async function sleep(ms: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function listenEphemeral(
+  server: http.Server,
+  host = '127.0.0.1',
+): Promise<{ host: string; port: number; baseUrl: string }> {
+  server.listen(0, host);
+
+  if (!server.listening) {
+    await once(server, 'listening');
+  }
+
+  const address = server.address();
+
+  if (address === null || typeof address === 'string') {
+    throw new Error('Failed to resolve server address');
+  }
+
+  return {
+    host,
+    port: address.port,
+    baseUrl: `http://${host}:${address.port}`,
+  };
+}
+
+export async function closeServer(server: http.Server): Promise<void> {
+  if (!server.listening) {
+    return;
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    server.close((error) => {
+      if (error !== undefined) {
+        reject(error);
+        return;
+      }
+
+      resolve();
+    });
+  });
+}
+export function ensureDir(dir: string): void {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "esModuleInterop": true,
+    "strict": true,
+
+    "jsx": "react-jsx",
+    "jsxImportSource": "kt.js",
+    "plugins": [{ "name": "@ktjs/ts-plugin" }],
+
+    "declaration": false,
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["./src/**/*.ts", "*.config.ts", "./tests/**/*.ts", "./document/**/*.ts", "./document/**/*.tsx"],
+  "exclude": ["**/dist/**/*.js", "**/dist/**/*.d.ts", "**/example/**/code/**"]
+}

package/vitest.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from 'vitest/config';
+import path from 'node:path';
+
+export default defineConfig(() => {
+  const packageDir = import.meta.dirname;
+  return {
+    test: {
+      include: [path.join(packageDir, '**', '*.{test,spec,e2e-spec}.?(c|m)[jt]s?(x)')],
+      exclude: [
+        path.join(packageDir, '**', 'node_modules', '**'),
+        path.join(packageDir, '**', 'dist', '**'),
+        path.join(packageDir, '**', 'build', '**'),
+        path.join(packageDir, '**', 'coverage', '**'),
+      ],
+      silent: false,
+    },
+    define: {},
+    resolve: {
+      alias: {
+        '@': path.join(packageDir, 'src'),
+      },
+    },
+  };
+});