@zintrust/core 0.1.26 → 0.1.28

package/src/runtime/adapters/NodeServerAdapter.ts

@@ -0,0 +1,289 @@
+import { Env } from '@config/env';
+import Logger from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import type { IncomingMessage, Server, ServerResponse } from '@node-singletons/http';
+import { createServer } from '@node-singletons/http';
+import type {
+  AdapterConfig,
+  PlatformRequest,
+  PlatformResponse,
+  RuntimeAdapter,
+} from '@runtime/RuntimeAdapter';
+
+/**
+ * Node.js HTTP Server adapter for standard containers and traditional servers
+ * Uses Node.js built-in HTTP server for maximum compatibility
+ * Sealed namespace for immutability
+ */
+export const NodeServerAdapter = Object.freeze({
+  /**
+   * Create a new Node.js server adapter instance
+   */
+  create(config: AdapterConfig): RuntimeAdapter & {
+    startServer(port?: number, host?: string): Promise<void>;
+    stop(): Promise<void>;
+  } {
+    const logger = config.logger ?? createDefaultLogger();
+    const state: { server?: Server } = {};
+
+    return {
+      platform: 'nodejs',
+
+      // eslint-disable-next-line @typescript-eslint/require-await
+      async handle(_event: unknown, _context?: unknown): Promise<PlatformResponse> {
+        throw ErrorFactory.createConfigError(
+          'Node.js adapter requires startServer() method. Use RuntimeDetector for automatic initialization.'
+        );
+      },
+
+      /**
+       * Start HTTP server for Node.js environments
+       */
+      async startServer(port: number = 3000, host: string = 'localhost'): Promise<void> {
+        return startNodeServer(state, config, logger, port, host);
+      },
+
+      /**
+       * Stop the HTTP server gracefully
+       */
+      async stop(): Promise<void> {
+        return stopNodeServer(state, logger);
+      },
+
+      parseRequest(_event: unknown): PlatformRequest {
+        throw ErrorFactory.createConfigError('Node.js adapter uses native Node.js HTTP');
+      },
+
+      formatResponse(_response: PlatformResponse): unknown {
+        throw ErrorFactory.createConfigError('Node.js adapter uses native Node.js HTTP');
+      },
+
+      getLogger(): {
+        debug(msg: string, data?: unknown): void;
+        info(msg: string, data?: unknown): void;
+        warn(msg: string, data?: unknown): void;
+        error(msg: string, err?: Error): void;
+      } {
+        return (
+          logger ?? {
+            debug: (msg: string) => Logger.debug(`[Node.js] ${msg}`),
+            info: (msg: string) => Logger.info(`[Node.js] ${msg}`),
+            warn: (msg: string) => Logger.warn(`[Node.js] ${msg}`),
+            error: (msg: string, err?: Error) => Logger.error(`[Node.js] ${msg}`, err?.message),
+          }
+        );
+      },
+
+      supportsPersistentConnections(): boolean {
+        return true;
+      },
+
+      getEnvironment(): {
+        nodeEnv: NodeJS.ProcessEnv['NODE_ENV'];
+        runtime: string;
+        dbConnection: string;
+        dbHost?: string;
+        dbPort?: number;
+        [key: string]: unknown;
+      } {
+        return getNodeEnvironment();
+      },
+    };
+  },
+});
+
+/**
+ * Start Node.js HTTP server
+ */
+async function startNodeServer(
+  state: { server?: Server },
+  config: AdapterConfig,
+  logger: AdapterConfig['logger'],
+  port: number,
+  host: string
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    state.server = createServer((req: IncomingMessage, res: ServerResponse) => {
+      handleRequest(req, res, config, logger);
+    });
+
+    state.server.listen(port, host, () => {
+      logger?.info(`Node.js server listening on http://${host}:${port}`);
+      resolve();
+    });
+
+    state.server.on('error', (error: Error) => {
+      logger?.error('Server error', error);
+      reject(error);
+    });
+
+    state.server.on('clientError', (error: Error, socket) => {
+      if ((error as NodeJS.ErrnoException).code === 'ECONNRESET' || !socket.writable) {
+        return;
+      }
+      logger?.warn(`Client error: ${error.message}`);
+    });
+  });
+}
+
+/**
+ * Stop Node.js HTTP server
+ */
+async function stopNodeServer(
+  state: { server?: Server },
+  logger: AdapterConfig['logger']
+): Promise<void> {
+  return new Promise((resolve) => {
+    if (state.server) {
+      state.server.close(() => {
+        logger?.info('Node.js server stopped');
+        resolve();
+      });
+    } else {
+      resolve();
+    }
+  });
+}
+
+/**
+ * Get Node.js environment
+ */
+function getNodeEnvironment(): {
+  nodeEnv: NodeJS.ProcessEnv['NODE_ENV'];
+  runtime: string;
+  dbConnection: string;
+  dbHost?: string;
+  dbPort?: number;
+  [key: string]: unknown;
+} {
+  return {
+    nodeEnv: Env.NODE_ENV,
+    runtime: 'nodejs',
+    dbConnection: Env.DB_CONNECTION,
+    dbHost: Env.DB_HOST,
+    dbPort: Env.DB_PORT,
+  };
+}
+
+/**
+ * Handle request processing
+ */
+function handleRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  config: AdapterConfig,
+  logger?: AdapterConfig['logger']
+): void {
+  const chunks: Buffer[] = [];
+  let body: Buffer | null = null;
+
+  // Collect request body
+  req.on('data', (chunk: Buffer) => {
+    const maxSize = config.maxBodySize ?? 10 * 1024 * 1024;
+    if (chunks.length * chunk.length > maxSize) {
+      res.writeHead(413, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Payload Too Large' }));
+      req.socket.destroy();
+      return;
+    }
+    chunks.push(chunk);
+  });
+
+  req.on('end', async (): Promise<void> => {
+    try {
+      body = chunks.length > 0 ? Buffer.concat(chunks) : null;
+
+      // Set request timeout
+      const timeout = config.timeout ?? 30000;
+      const timeoutHandle = setTimeout(() => {
+        if (!res.headersSent) {
+          res.writeHead(504, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Gateway Timeout' }));
+        }
+      }, timeout);
+
+      try {
+        // Call ZinTrust handler
+        await config.handler(req, res, body);
+      } finally {
+        clearTimeout(timeoutHandle);
+      }
+
+      logger?.debug('Request processed', {
+        method: req.method,
+        url: req.url,
+        statusCode: res.statusCode,
+        remoteAddr: req.socket.remoteAddress,
+      });
+    } catch (error) {
+      const err = error as Error;
+      logger?.error('Request processing error', err);
+      Logger.error('Request processing error', err.message);
+      handleError(res, err, logger);
+    }
+  });
+
+  req.on('error', (error: Error) => {
+    Logger.error('Request stream error', error.message);
+    handleRequestError(res, error, logger);
+  });
+}
+
+/**
+ * Handle request handler errors
+ */
+function handleError(res: ServerResponse, error: Error, logger?: AdapterConfig['logger']): void {
+  logger?.error('Request handler error', error);
+  Logger.error('Request handler error', error.message);
+
+  if (!res.headersSent) {
+    res.writeHead(500, { 'Content-Type': 'application/json' });
+    res.end(
+      JSON.stringify({
+        error: 'Internal Server Error',
+        statusCode: 500,
+        timestamp: new Date().toISOString(),
+        ...(Env.get('NODE_ENV') === 'development' && {
+          message: error.message,
+        }),
+      })
+    );
+  }
+}
+
+/**
+ * Handle request stream errors
+ */
+function handleRequestError(
+  res: ServerResponse,
+  error: Error,
+  logger?: AdapterConfig['logger']
+): void {
+  logger?.error('Request error', error);
+  Logger.error('Request error', error.message);
+  if (!res.headersSent) {
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Bad Request' }));
+  }
+}
+
+function createDefaultLogger(): AdapterConfig['logger'] {
+  return {
+    debug: (msg: string, data?: unknown) =>
+      Logger.debug(
+        `[Node.js] ${msg}`,
+        data !== undefined && data !== null ? JSON.stringify(data) : ''
+      ),
+    info: (msg: string, data?: unknown) =>
+      Logger.info(
+        `[Node.js] ${msg}`,
+        data !== undefined && data !== null ? JSON.stringify(data) : ''
+      ),
+    warn: (msg: string, data?: unknown) =>
+      Logger.warn(
+        `[Node.js] ${msg}`,
+        data !== undefined && data !== null ? JSON.stringify(data) : ''
+      ),
+    error: (msg: string, err?: Error) => Logger.error(`[Node.js] ${msg}`, err?.message),
+  };
+}

package/src/runtime/getKernel.ts

@@ -0,0 +1,34 @@
+import { Application } from '@boot/Application';
+import type { IKernel } from '@http/Kernel';
+import { Kernel } from '@http/Kernel';
+
+let kernelPromise: Promise<IKernel> | null = null;
+
+export async function getKernel(): Promise<IKernel> {
+  if (kernelPromise !== null) {
+    return kernelPromise;
+  }
+
+  const initialize = async (): Promise<IKernel> => {
+    const app = Application.create();
+    await app.boot();
+    return Kernel.create(app.getRouter(), app.getContainer());
+  };
+
+  kernelPromise = initialize().catch((error) => {
+    // Allow retry on subsequent calls if initialization fails.
+    kernelPromise = null;
+    throw error;
+  });
+
+  return kernelPromise;
+}
+
+/**
+ * Test-only helper.
+ *
+ * Allows unit tests to reset the singleton between cases without leaking state.
+ */
+export function __resetKernelForTests(): void {
+  kernelPromise = null;
+}

package/src/runtime/useFileLoader.ts

@@ -0,0 +1,234 @@
+/**
+ * Project file loader
+ *
+ * Loads project-owned files (typically config modules) from the project root.
+ *
+ * Usage:
+ *  - useFileLoader('config/mail.ts').get<TypeMail>()
+ *  - useFileLoader('config', 'mail.ts').get<TypeMail>()
+ */
+
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { existsSync } from '@node-singletons/fs';
+import pathModule, { extname, join, resolve, sep } from '@node-singletons/path';
+import processModule from '@node-singletons/process';
+import { pathToFileURL } from '@node-singletons/url';
+
+type UnknownModule = Record<string, unknown> & { default?: unknown };
+
+export type FileLoader = Readonly<{
+  /** Absolute filesystem candidates (in resolution order). */
+  candidates: () => readonly string[];
+  /** Returns the first existing candidate path (or the first candidate if none exist). */
+  path: () => string;
+  /** Whether any candidate exists on disk. */
+  exists: () => boolean;
+  /**
+   * Loads the file via ESM dynamic import and returns:
+   * - `default` export when present
+   * - otherwise the full module namespace object
+   */
+  get: <T = unknown>() => Promise<T>;
+}>;
+
+const resolveProjectRoot = (): string => {
+  const isTestRuntime = (): boolean => {
+    const nodeEnv = processModule.env?.['NODE_ENV'];
+    const isVitest =
+      processModule.env?.['VITEST'] !== undefined ||
+      processModule.env?.['VITEST_WORKER_ID'] !== undefined ||
+      processModule.env?.['VITEST_POOL_ID'] !== undefined;
+
+    return nodeEnv === 'testing' || isVitest;
+  };
+
+  const isCoreRepo = (cwdPath: string): boolean => {
+    const fromNpm = processModule.env?.['npm_package_name'];
+    if (fromNpm === '@zintrust/core') return true;
+
+    // Vitest suites (notably CoverageBoost) may mock `@node-singletons/fs` to return
+    // `existsSync() === true` for everything and `readFileSync() === '{}'`, which makes
+    // any package.json-based detection unreliable. Instead, detect a core repo checkout
+    // by checking whether this module is being executed from within the current cwd.
+    // - core repo tests: import.meta.url points into `<cwd>/src/...`
+    // - consumer apps: import.meta.url points into `node_modules/@zintrust/core/...`
+    try {
+      const cwdAbs = resolve(cwdPath);
+      const selfUrl = new URL(import.meta.url);
+      const selfPath = decodeURIComponent(selfUrl.pathname);
+      const selfAbs = resolve(selfPath);
+      return selfAbs === cwdAbs || selfAbs.startsWith(cwdAbs + sep);
+    } catch {
+      return false;
+    }
+  };
+
+  const fromEnv = processModule.env?.['ZINTRUST_PROJECT_ROOT'];
+  if (typeof fromEnv === 'string' && fromEnv.trim().length > 0) return fromEnv.trim();
+
+  const cwd = processModule.cwd();
+
+  // In the ZinTrust core repo, `config/*.ts` are templates (not consumer app config).
+  // During core test runs, we avoid auto-loading them to prevent unexpected overrides.
+  // In normal runs, keep the historical behavior (projectRoot = cwd).
+  if (isCoreRepo(cwd) && isTestRuntime()) {
+    return resolve(cwd, '.zintrust-internal-project-root');
+  }
+
+  return cwd;
+};
+
+const isInternalProjectRoot = (projectRoot: string): boolean =>
+  pathModule.basename(projectRoot) === '.zintrust-internal-project-root';
+
+const normalizeProjectRelativePath = (raw: string): string => {
+  const value = String(raw ?? '').trim();
+  if (value.length === 0) {
+    throw ErrorFactory.createConfigError('useFileLoader() requires a non-empty path');
+  }
+
+  if (value.includes('\u0000')) {
+    throw ErrorFactory.createSecurityError('Invalid file path (null byte)');
+  }
+
+  const normalized = value.replaceAll('\\', '/').replace(/^\.\/+/, '');
+
+  if (pathModule.isAbsolute(normalized)) {
+    throw ErrorFactory.createSecurityError('Absolute paths are not allowed', { requested: value });
+  }
+
+  return normalized;
+};
+
+const resolveWithinProjectRoot = (projectRoot: string, relativePath: string): string => {
+  const rootAbs = resolve(projectRoot);
+  const candidateAbs = resolve(projectRoot, relativePath);
+
+  if (candidateAbs === rootAbs) return candidateAbs;
+
+  if (!candidateAbs.startsWith(rootAbs + sep)) {
+    throw ErrorFactory.createSecurityError('Invalid file path (path traversal detected)', {
+      projectRoot: rootAbs,
+      requested: relativePath,
+      resolved: candidateAbs,
+    });
+  }
+
+  return candidateAbs;
+};
+
+const replaceExtension = (filePath: string, nextExt: string): string => {
+  const current = extname(filePath);
+  if (current.length === 0) return `${filePath}${nextExt}`;
+  return filePath.slice(0, -current.length) + nextExt;
+};
+
+const unique = (items: string[]): string[] => {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const item of items) {
+    if (seen.has(item)) continue;
+    seen.add(item);
+    out.push(item);
+  }
+  return out;
+};
+
+const buildCandidateAbsolutePaths = (projectRoot: string, relativePath: string): string[] => {
+  const ext = extname(relativePath);
+
+  const baseRelCandidates = unique([
+    relativePath,
+    ...(ext.length === 0
+      ? [`${relativePath}.ts`, `${relativePath}.js`, `${relativePath}.mjs`]
+      : []),
+    ...(ext === '.ts'
+      ? [replaceExtension(relativePath, '.js'), replaceExtension(relativePath, '.mjs')]
+      : []),
+    ...(ext === '.js'
+      ? [replaceExtension(relativePath, '.mjs'), replaceExtension(relativePath, '.ts')]
+      : []),
+    ...(ext === '.mjs'
+      ? [replaceExtension(relativePath, '.js'), replaceExtension(relativePath, '.ts')]
+      : []),
+  ]);
+
+  const absCandidates = baseRelCandidates.flatMap((rel) => [
+    resolveWithinProjectRoot(projectRoot, rel),
+    resolveWithinProjectRoot(projectRoot, join('dist', rel)),
+  ]);
+
+  return unique(absCandidates);
+};
+
+const importModule = async (filePath: string): Promise<UnknownModule> => {
+  const url = pathToFileURL(filePath).href;
+  return (await import(url)) as UnknownModule;
+};
+
+export const useFileLoader = (...args: [string] | [string, ...string[]]): FileLoader => {
+  const relativePath =
+    args.length === 1
+      ? normalizeProjectRelativePath(args[0])
+      : normalizeProjectRelativePath(args.join('/'));
+
+  const projectRoot = resolveProjectRoot();
+  const isInternalRoot = isInternalProjectRoot(projectRoot);
+  const candidates = buildCandidateAbsolutePaths(projectRoot, relativePath);
+
+  // The core repo uses `.zintrust-internal-project-root` as a sentinel during core test runs.
+  // In this mode, we must *never* import project config templates.
+  // This also avoids test suites that mock `existsSync()` globally (e.g. CoverageBoost).
+  const exists = (): boolean => (isInternalRoot ? false : candidates.some((c) => existsSync(c)));
+
+  const resolveFirstExistingPath = (): string => {
+    if (isInternalRoot) return candidates[0] ?? resolveWithinProjectRoot(projectRoot, relativePath);
+    for (const candidate of candidates) {
+      if (existsSync(candidate)) return candidate;
+    }
+    return candidates[0] ?? resolveWithinProjectRoot(projectRoot, relativePath);
+  };
+
+  const get = async <T = unknown>(): Promise<T> => {
+    if (isInternalRoot) {
+      throw ErrorFactory.createNotFoundError('Project file not found', {
+        projectRoot,
+        relativePath,
+        candidates,
+      });
+    }
+
+    const candidate = candidates.find((c) => existsSync(c));
+    if (candidate === undefined) {
+      throw ErrorFactory.createNotFoundError('Project file not found', {
+        projectRoot,
+        relativePath,
+        candidates,
+      });
+    }
+
+    try {
+      const mod = await importModule(candidate);
+      if (Object.hasOwn(mod, 'default') && mod.default !== undefined) {
+        return mod.default as T;
+      }
+      return mod as unknown as T;
+    } catch (error: unknown) {
+      throw ErrorFactory.createTryCatchError('Failed to import project file', {
+        candidate,
+        projectRoot,
+        relativePath,
+        error,
+      });
+    }
+  };
+
+  return Object.freeze({
+    candidates: () => candidates,
+    path: resolveFirstExistingPath,
+    exists,
+    get,
+  });
+};
+
+export default useFileLoader;