@zintrust/core 0.1.26 → 0.1.28

package/src/node-singletons/module.ts

@@ -0,0 +1,12 @@
+/**
+ * Node.js Module Singleton
+ * Wrapper for node:module imports
+ * CLI-only - should not be imported in API code
+ */
+
+import * as module from 'node:module';
+
+export { createRequire } from 'node:module';
+
+// Default export for compatibility
+export default module;

package/src/node-singletons/net.ts

@@ -0,0 +1,10 @@
+/**
+ * node-singletons/net
+ * Centralized export for Node's net module.
+ * NOTE: Node-only.
+ */
+
+import * as net from 'node:net';
+
+export default net;
+export * from 'node:net';

package/src/node-singletons/os.ts

@@ -0,0 +1,20 @@
+/**
+ * Node.js OS Module Singleton
+ * CLI-only: Should not be imported in API/serverless code
+ * Exported from node:os built-in
+ */
+
+import * as os from 'node:os';
+
+export const arch = os.arch;
+export const cpus = os.cpus;
+export const freemem = os.freemem;
+export const hostname = os.hostname;
+export const loadavg = os.loadavg;
+export const platform = os.platform;
+export const tmpdir = os.tmpdir;
+export const totalmem = os.totalmem;
+export const type = os.type;
+export const uptime = os.uptime;
+
+export default os;

package/src/node-singletons/path.ts

@@ -0,0 +1,11 @@
+/**
+ * Node.js Path Module Singleton
+ * CLI-only: Should not be imported in API/serverless code
+ * Exported from node:path built-in
+ */
+
+import * as path from 'node:path';
+
+export const { basename, delimiter, dirname, extname, join, relative, resolve, sep } = path;
+
+export default path;

package/src/node-singletons/perf-hooks.ts

@@ -0,0 +1,11 @@
+/**
+ * Node.js Performance Hooks Module Singleton
+ * Safe to import in both API and CLI code
+ * Exported from node:perf_hooks built-in
+ */
+
+import * as perf_hooks from 'node:perf_hooks';
+
+export const { performance } = perf_hooks;
+
+export default perf_hooks;

package/src/node-singletons/process.ts

@@ -0,0 +1,58 @@
+/**
+ * Node.js Process Module Singleton
+ * Safe to import in both API and CLI code
+ * Exported from node:process built-in
+ */
+
+import * as processModule from 'node:process';
+
+export const {
+  arch,
+  argv,
+  argv0,
+  chdir,
+  config,
+  connected,
+  cpuUsage,
+  cwd,
+  debugPort,
+  disconnect,
+  emitWarning,
+  env,
+  execArgv,
+  execPath,
+  exit,
+  exitCode,
+  getegid,
+  geteuid,
+  getgid,
+  getgroups,
+  getuid,
+  hasUncaughtExceptionCaptureCallback,
+  hrtime,
+  kill,
+  memoryUsage,
+  nextTick,
+  pid,
+  platform,
+  ppid,
+  release,
+  report,
+  resourceUsage,
+  setegid,
+  seteuid,
+  setgid,
+  setgroups,
+  setuid,
+  setUncaughtExceptionCaptureCallback,
+  stderr,
+  stdin,
+  stdout,
+  title,
+  umask,
+  uptime,
+  version,
+  versions,
+} = processModule;
+
+export default processModule;

package/src/node-singletons/readline.ts

@@ -0,0 +1,12 @@
+/**
+ * Node.js Readline Module Singleton
+ * CLI-only: Should not be imported in API/serverless code
+ * Exported from node:readline built-in
+ */
+
+import * as readline from 'node:readline';
+
+export const { createInterface, cursorTo } = readline;
+export type { Interface } from 'node:readline';
+
+export default readline;

package/src/node-singletons/tls.ts

@@ -0,0 +1,10 @@
+/**
+ * node-singletons/tls
+ Centralized export for Node's tls module.
+ * NOTE: Node-only.
+ */
+
+import * as tls from 'node:tls';
+
+export default tls;
+export * from 'node:tls';

package/src/node-singletons/url.ts

@@ -0,0 +1,11 @@
+/**
+ * Node.js URL Module Singleton
+ * CLI-only: Should not be imported in API/serverless code
+ * Exported from node:url built-in
+ */
+
+import * as url from 'node:url';
+
+export const { fileURLToPath, pathToFileURL } = url;
+
+export default url;

package/src/node-singletons/util.ts

@@ -0,0 +1,6 @@
+/**
+ * Node built-in util singleton
+ * Avoids issues with stubbing in tests
+ */
+
+export * from 'node:util';

package/src/node.ts

@@ -0,0 +1,32 @@
+import { Logger } from '@config/logger';
+// Runtime marker to make this re-export-only module coverable in V8 coverage.
+const __coverageMarker = true;
+if (__coverageMarker !== true) {
+  throw Logger.error('Unreachable');
+}
+
+export { default, default as process } from '@node-singletons/process';
+
+export { cleanOnce, FileLogWriter } from '@config/FileLogWriter';
+
+export { listTemplates, loadTemplate, renderTemplate } from '@mail/templates';
+export { MailFake } from '@mail/testing';
+
+export { FakeStorage } from '@tools/storage/testing';
+
+export { TestEnvironment, TestHttp } from '@/testing/index';
+export type {
+  ITestEnvironment,
+  TestEnvironmentOptions,
+  TestHeaders,
+  TestHttpRequestInput,
+  TestHttpResponseRecorder,
+  TestRequestInput,
+  TestResponse,
+} from '@/testing/index';
+
+export {
+  listTemplates as listNotificationTemplates,
+  loadTemplate as loadNotificationTemplate,
+  renderTemplate as renderNotificationTemplate,
+} from '@notification/templates/markdown';

package/src/observability/OpenTelemetry.ts

@@ -0,0 +1,295 @@
+/**
+ * Optional OpenTelemetry integration.
+ *
+ * Design goals:
+ * - No hard dependency on SDKs/exporters (apps bring their own).
+ * - Safe to import in runtimes without tracing configured (no-op behavior).
+ * - Best-effort: never breaks request handling.
+ *
+ * Tiny Node enablement snippet (exporter is app-owned):
+ *
+ *   npm i @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node \
+ *     @opentelemetry/exporter-trace-otlp-http
+ *
+ *   // in your app entrypoint (before creating the server)
+ *   import { NodeSDK } from '@opentelemetry/sdk-node';
+ *   import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+ *   import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+ *
+ *   const sdk = new NodeSDK({
+ *     traceExporter: new OTLPTraceExporter({ url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT }),
+ *     instrumentations: [getNodeAutoInstrumentations()],
+ *   });
+ *   await sdk.start();
+ *   process.env.OTEL_ENABLED = 'true';
+ */
+
+import { Env } from '@config/env';
+import { createRequire } from '@node-singletons/module';
+import type { Context, Span } from '@opentelemetry/api';
+
+type OpenTelemetryApi = typeof import('@opentelemetry/api');
+
+let cachedApi: OpenTelemetryApi | null | undefined;
+
+const resolveOpenTelemetryApi = (): OpenTelemetryApi | null => {
+  if (cachedApi !== undefined) return cachedApi;
+
+  // Check for injected API (used for testing)
+  const injected = (globalThis as unknown as { __zintrustOpenTelemetryApi?: unknown })
+    .__zintrustOpenTelemetryApi;
+  if (injected !== undefined && injected !== null) {
+    cachedApi = injected as OpenTelemetryApi;
+    return cachedApi;
+  }
+
+  try {
+    const require = createRequire(import.meta.url);
+
+    cachedApi = require('@opentelemetry/api') as OpenTelemetryApi;
+    return cachedApi;
+  } catch {
+    cachedApi = null;
+    return null;
+  }
+};
+
+const noopSpan: Span = {
+  setAttribute: () => undefined,
+  updateName: () => undefined,
+  setStatus: () => undefined,
+  end: () => undefined,
+} as unknown as Span;
+
+const fallbackContext = {
+  active: () => ({}) as Context,
+  with: <A extends unknown[], F extends (...args: A) => ReturnType<F>>(
+    _ctx: Context,
+    fn: F,
+    _thisArg?: ThisParameterType<F>,
+    ...args: A
+  ): ReturnType<F> => fn(...args),
+};
+
+const fallbackPropagation = {
+  extract: (_ctx: Context) => _ctx,
+  inject: () => undefined,
+};
+
+const fallbackTrace = {
+  getTracer: () => ({
+    startSpan: () => noopSpan,
+  }),
+  getSpan: () => undefined,
+  setSpan: (ctx: Context) => ctx,
+};
+
+const fallbackSpanKind = {
+  SERVER: 1,
+  CLIENT: 2,
+} as const;
+
+const fallbackSpanStatusCode = {
+  OK: 1,
+  ERROR: 2,
+} as const;
+
+const otel = (): OpenTelemetryApi | null => resolveOpenTelemetryApi();
+
+export interface StartHttpServerSpanInput {
+  method: string;
+  path: string;
+  requestId?: string;
+  serviceName?: string;
+  userId?: string;
+  tenantId?: string;
+  userAgent?: string;
+}
+
+export interface EndHttpServerSpanInput {
+  route?: string;
+  status?: number;
+  error?: unknown;
+}
+
+export interface StartedSpan {
+  span: Span;
+  context: Context;
+}
+
+export interface RecordDbQuerySpanInput {
+  driver: string;
+  durationMs: number;
+}
+
+type HeaderGetter = {
+  getHeader(name: string): unknown;
+};
+
+const isEnabled = (): boolean => {
+  return Env.getBool('OTEL_ENABLED', false);
+};
+
+const extractContextFromHeaders = (req: HeaderGetter): Context => {
+  const active = otel()?.context?.active() ?? fallbackContext.active();
+
+  try {
+    const extractor = otel()?.propagation?.extract ?? fallbackPropagation.extract;
+    return extractor(active, req, {
+      get(carrier: HeaderGetter, key: string) {
+        const value = carrier.getHeader(key);
+        if (typeof value === 'string') return value;
+        if (Array.isArray(value)) return value.join(',');
+        return undefined;
+      },
+      keys() {
+        return [];
+      },
+    });
+  } catch {
+    return active;
+  }
+};
+
+const startHttpServerSpan = (req: HeaderGetter, input: StartHttpServerSpanInput): StartedSpan => {
+  const parent = extractContextFromHeaders(req);
+  const tracer = (otel()?.trace ?? fallbackTrace).getTracer('zintrust');
+
+  const span = tracer.startSpan(
+    `${input.method} unmatched`,
+    {
+      kind: (otel()?.SpanKind ?? fallbackSpanKind).SERVER,
+      attributes: {
+        'http.method': input.method,
+        'http.target': input.path,
+        'http.user_agent': input.userAgent ?? '',
+        'service.name': input.serviceName ?? '',
+        'enduser.id': input.userId ?? '',
+        'zintrust.tenant_id': input.tenantId ?? '',
+        'zintrust.request_id': input.requestId ?? '',
+      },
+    },
+    parent
+  );
+
+  const spanContext = (otel()?.trace ?? fallbackTrace).setSpan(parent, span);
+  return { span, context: spanContext };
+};
+
+const runWithContext = async <T>(ctx: Context, fn: () => Promise<T>): Promise<T> => {
+  const runner = otel()?.context?.with ?? fallbackContext.with;
+  return runner(ctx, fn);
+};
+
+const setHttpRoute = (span: Span, method: string, route: string): void => {
+  try {
+    span.setAttribute('http.route', route);
+    span.updateName(`${method} ${route}`);
+  } catch {
+    // best-effort
+  }
+};
+
+const endHttpServerSpan = (span: Span, input: EndHttpServerSpanInput): void => {
+  try {
+    if (input.route !== undefined && input.route.trim() !== '') {
+      span.setAttribute('http.route', input.route);
+    }
+
+    if (typeof input.status === 'number') {
+      span.setAttribute('http.status_code', input.status);
+
+      if (input.status >= 500) {
+        span.setStatus({ code: (otel()?.SpanStatusCode ?? fallbackSpanStatusCode).ERROR });
+      } else {
+        span.setStatus({ code: (otel()?.SpanStatusCode ?? fallbackSpanStatusCode).OK });
+      }
+    }
+
+    if (input.error !== undefined) {
+      // Avoid throwing; represent as a string attribute.
+      span.setAttribute(
+        'zintrust.error',
+        input.error instanceof Error ? input.error.message : String(input.error)
+      );
+      span.setStatus({ code: (otel()?.SpanStatusCode ?? fallbackSpanStatusCode).ERROR });
+    }
+
+    span.end();
+  } catch {
+    // best-effort
+  }
+};
+
+const injectTraceHeaders = (headers: Record<string, string>): Record<string, string> => {
+  try {
+    const injector = otel()?.propagation?.inject ?? fallbackPropagation.inject;
+    injector(otel()?.context?.active() ?? fallbackContext.active(), headers);
+  } catch {
+    // best-effort
+  }
+
+  return headers;
+};
+
+const mapDbSystem = (driver: string): string => {
+  switch (driver) {
+    case 'postgresql':
+      return 'postgresql';
+    case 'mysql':
+      return 'mysql';
+    case 'sqlserver':
+      return 'mssql';
+    case 'd1':
+    case 'd1-remote':
+    case 'sqlite':
+    default:
+      return 'sqlite';
+  }
+};
+
+const recordDbQuerySpan = (input: RecordDbQuerySpanInput): void => {
+  if (isEnabled() === false) return;
+
+  try {
+    // Only create a DB span if we're already inside a request trace.
+    const traceApi = otel()?.trace ?? fallbackTrace;
+    const parentSpan = traceApi.getSpan(otel()?.context?.active() ?? fallbackContext.active());
+    if (!parentSpan) return;
+
+    const tracer = traceApi.getTracer('zintrust');
+    const now = Date.now();
+    const durationMs = Number.isFinite(input.durationMs) ? Math.max(0, input.durationMs) : 0;
+    const startTime = now - durationMs;
+
+    const span = tracer.startSpan(
+      'db.query',
+      {
+        kind: (otel()?.SpanKind ?? fallbackSpanKind).CLIENT,
+        startTime,
+        attributes: {
+          'db.system': mapDbSystem(input.driver),
+          'db.operation': 'query',
+          'zintrust.db.driver': input.driver,
+        },
+      },
+      otel()?.context?.active() ?? fallbackContext.active()
+    );
+
+    span.end(now);
+  } catch {
+    // best-effort
+  }
+};
+
+export const OpenTelemetry = Object.freeze({
+  isEnabled,
+  startHttpServerSpan,
+  runWithContext,
+  setHttpRoute,
+  endHttpServerSpan,
+  injectTraceHeaders,
+  recordDbQuerySpan,
+});
+
+export default OpenTelemetry;

package/src/observability/PrometheusMetrics.ts

@@ -0,0 +1,161 @@
+/**
+ * Prometheus Metrics (prom-client)
+ *
+ * Lazy-initialized so importing this module is safe in non-Node runtimes.
+ */
+
+import { Env } from '@config/env';
+
+import type { Counter, Histogram, Registry } from 'prom-client';
+
+type PromClientModule = typeof import('prom-client');
+
+type MetricsState = {
+  client: PromClientModule;
+  registry: Registry;
+  httpRequestsTotal: Counter<string>;
+  httpRequestDurationSeconds: Histogram<string>;
+  dbQueriesTotal: Counter<string>;
+  dbQueryDurationSeconds: Histogram<string>;
+};
+
+let statePromise: Promise<MetricsState> | null = null;
+
+const DEFAULT_CONTENT_TYPE = 'text/plain; version=0.0.4; charset=utf-8';
+
+const createNoopState = (): MetricsState => {
+  const noopCounter = { inc: () => undefined } as unknown as Counter<string>;
+  const noopHistogram = { observe: () => undefined } as unknown as Histogram<string>;
+  const noopRegistry = {
+    contentType: DEFAULT_CONTENT_TYPE,
+    metrics: () => '',
+  } as unknown as Registry;
+
+  return {
+    client: {} as PromClientModule,
+    registry: noopRegistry,
+    httpRequestsTotal: noopCounter,
+    httpRequestDurationSeconds: noopHistogram,
+    dbQueriesTotal: noopCounter,
+    dbQueryDurationSeconds: noopHistogram,
+  };
+};
+
+async function ensureState(): Promise<MetricsState> {
+  if (statePromise !== null) return statePromise;
+
+  statePromise = (async () => {
+    let client: PromClientModule;
+    try {
+      client = await import('prom-client');
+    } catch {
+      // prom-client is intentionally optional at runtime.
+      return createNoopState();
+    }
+
+    const registry = new client.Registry();
+    const appName = Env.get('APP_NAME', 'ZinTrust');
+    if (appName.trim() !== '') {
+      registry.setDefaultLabels({ app: appName });
+    }
+
+    // Default metrics (process/memory/event loop) for Node runtimes.
+    // `collectDefaultMetrics` exists in prom-client; keep this lazy and best-effort.
+    try {
+      client.collectDefaultMetrics({ register: registry });
+    } catch {
+      // ignore
+    }
+
+    const httpRequestsTotal: Counter<string> = new client.Counter({
+      name: 'http_requests_total',
+      help: 'Total number of HTTP requests',
+      labelNames: ['method', 'route', 'status'],
+      registers: [registry],
+    });
+
+    const httpRequestDurationSeconds: Histogram<string> = new client.Histogram({
+      name: 'http_request_duration_seconds',
+      help: 'HTTP request duration in seconds',
+      labelNames: ['method', 'route', 'status'],
+      // Sensible default buckets for web apps (in seconds)
+      buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+      registers: [registry],
+    });
+
+    const dbQueriesTotal: Counter<string> = new client.Counter({
+      name: 'db_queries_total',
+      help: 'Total number of database queries',
+      labelNames: ['driver'],
+      registers: [registry],
+    });
+
+    const dbQueryDurationSeconds: Histogram<string> = new client.Histogram({
+      name: 'db_query_duration_seconds',
+      help: 'Database query duration in seconds',
+      labelNames: ['driver'],
+      buckets: [0.001, 0.0025, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5],
+      registers: [registry],
+    });
+
+    return {
+      client,
+      registry,
+      httpRequestsTotal,
+      httpRequestDurationSeconds,
+      dbQueriesTotal,
+      dbQueryDurationSeconds,
+    };
+  })();
+
+  return statePromise;
+}
+
+export type ObserveHttpRequestInput = {
+  method: string;
+  route: string;
+  status: number;
+  durationMs: number;
+};
+
+export type ObserveDbQueryInput = {
+  driver: string;
+  durationMs: number;
+};
+
+export const PrometheusMetrics = Object.freeze({
+  async getMetricsText(): Promise<{ contentType: string; body: string }> {
+    const state = await ensureState();
+    const body = await state.registry.metrics();
+    const contentType =
+      typeof (state.registry as unknown as { contentType?: unknown }).contentType === 'string'
+        ? (state.registry as unknown as { contentType: string }).contentType
+        : DEFAULT_CONTENT_TYPE;
+
+    return { contentType, body };
+  },
+
+  async observeHttpRequest(input: ObserveHttpRequestInput): Promise<void> {
+    const state = await ensureState();
+
+    const method = input.method || 'UNKNOWN';
+    const route = input.route || 'unknown';
+    const status = Number.isFinite(input.status) ? String(input.status) : '0';
+    const durationSeconds = Math.max(0, input.durationMs / 1000);
+
+    state.httpRequestsTotal.inc({ method, route, status }, 1);
+    state.httpRequestDurationSeconds.observe({ method, route, status }, durationSeconds);
+  },
+
+  async observeDbQuery(input: ObserveDbQueryInput): Promise<void> {
+    const state = await ensureState();
+
+    const driver = input.driver || 'unknown';
+    const durationSeconds = Math.max(0, input.durationMs / 1000);
+
+    state.dbQueriesTotal.inc({ driver }, 1);
+    state.dbQueryDurationSeconds.observe({ driver }, durationSeconds);
+  },
+});
+
+export default PrometheusMetrics;