@zintrust/core 0.1.28 → 0.1.29

package/src/node-singletons/module.ts

@@ -1,12 +0,0 @@
-/**
- * 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

@@ -1,10 +0,0 @@
-/**
- * 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

@@ -1,20 +0,0 @@
-/**
- * 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

@@ -1,11 +0,0 @@
-/**
- * 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

@@ -1,11 +0,0 @@
-/**
- * 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

@@ -1,58 +0,0 @@
-/**
- * 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

@@ -1,12 +0,0 @@
-/**
- * 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

@@ -1,10 +0,0 @@
-/**
- * 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

@@ -1,11 +0,0 @@
-/**
- * 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

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

package/src/node.ts

@@ -1,32 +0,0 @@
-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

@@ -1,295 +0,0 @@
-/**
- * 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

@@ -1,161 +0,0 @@
-/**
- * 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;