@zintrust/core 0.4.17 → 0.4.18

package/src/http/Controller.ts

@@ -1,64 +0,0 @@
-/**
- * Base Controller
- * All controllers extend this class
- */
-
-import type { IRequest } from '@http/Request';
-import type { IResponse } from '@http/Response';
-
-export interface IController {
-  json(res: IResponse, data: unknown, statusCode?: number): void;
-  error(res: IResponse, message: string, statusCode?: number): void;
-  redirect(res: IResponse, url: string, statusCode?: number): void;
-  param(req: IRequest, name: string): string | undefined;
-  query(req: IRequest, name: string): string | string[] | undefined;
-  body(req: IRequest): unknown;
-}
-
-/**
- * Base Controller
- * Sealed namespace for immutability
- */
-export const Controller: IController = Object.freeze({
-  /**
-   * Send JSON response
-   */
-  json(res: IResponse, data: unknown, statusCode: number = 200): void {
-    res.setStatus(statusCode).json(data);
-  },
-
-  /**
-   * Send error response
-   */
-  error(res: IResponse, message: string, statusCode: number = 400): void {
-    res.setStatus(statusCode).json({ error: message });
-  },
-
-  /**
-   * Redirect response
-   */
-  redirect(res: IResponse, url: string, statusCode: number = 302): void {
-    res.redirect(url, statusCode);
-  },
-
-  /**
-   * Get route parameter
-   */
-  param(req: IRequest, name: string): string | undefined {
-    return req.getParam(name);
-  },
-
-  /**
-   * Get query parameter
-   */
-  query(req: IRequest, name: string): string | string[] | undefined {
-    return req.getQueryParam(name);
-  },
-
-  /**
-   * Get request body
-   */
-  body(req: IRequest): unknown {
-    return req.getBody();
-  },
-});

package/src/http/ErrorResponse.ts

@@ -1,76 +0,0 @@
-export interface IErrorResponse {
-  statusCode: number;
-  message: string;
-  code: string;
-  requestId: string;
-  timestamp: string;
-  details?: Record<string, unknown>;
-  stack?: string;
-}
-
-const create = (params: {
-  statusCode: number;
-  message: string;
-  code: string;
-  requestId?: string;
-  details?: Record<string, unknown>;
-  stack?: string;
-}): IErrorResponse => {
-  const hasStack = typeof params.stack === 'string' && params.stack.trim().length > 0;
-  return {
-    statusCode: params.statusCode,
-    message: params.message,
-    code: params.code,
-    requestId: params.requestId ?? '',
-    timestamp: new Date().toISOString(),
-    ...(params.details ? { details: params.details } : {}),
-    ...(hasStack ? { stack: params.stack } : {}),
-  };
-};
-
-export const ErrorResponse = Object.freeze({
-  create,
-
-  notFound(resource: string, requestId?: string): IErrorResponse {
-    return create({
-      statusCode: 404,
-      message: `${resource} not found`,
-      code: 'NOT_FOUND',
-      requestId,
-    });
-  },
-
-  badRequest(
-    message: string,
-    requestId?: string,
-    details?: Record<string, unknown>
-  ): IErrorResponse {
-    return create({ statusCode: 400, message, code: 'BAD_REQUEST', requestId, details });
-  },
-
-  unauthorized(message: string, requestId?: string): IErrorResponse {
-    return create({ statusCode: 401, message, code: 'UNAUTHORIZED', requestId });
-  },
-
-  forbidden(message: string, requestId?: string): IErrorResponse {
-    return create({ statusCode: 403, message, code: 'FORBIDDEN', requestId });
-  },
-
-  conflict(message: string, requestId?: string): IErrorResponse {
-    return create({ statusCode: 409, message, code: 'CONFLICT', requestId });
-  },
-
-  internalServerError(
-    message: string = 'Internal server error',
-    requestId?: string,
-    stack?: string
-  ): IErrorResponse {
-    return create({ statusCode: 500, message, code: 'INTERNAL_SERVER_ERROR', requestId, stack });
-  },
-
-  serviceUnavailable(message: string = 'Service unavailable', requestId?: string): IErrorResponse {
-    return create({ statusCode: 503, message, code: 'SERVICE_UNAVAILABLE', requestId });
-  },
-});
-
-export default ErrorResponse;

package/src/http/FileUpload.ts

@@ -1,196 +0,0 @@
-/**
- * File Upload Handler
- * Handles multipart/form-data file uploads with validation and storage integration
- */
-
-import type { ReadableOptions } from '@/node-singletons/stream';
-import type { IRequest } from '@http/Request';
-
-type Streamer = ReadableOptions | NodeJS.ReadableStream;
-
-export interface UploadedFile {
-  fieldName: string;
-  originalName: string;
-  mimeType: string;
-  size: number;
-  encoding?: string;
-
-  /**
-   * Legacy in-memory payload (Phase 3). Optional in Phase 4.
-   */
-  buffer?: Buffer;
-
-  /**
-   * Disk-backed upload path (Phase 4, provided by @zintrust/storage).
-   */
-  path?: string;
-
-  /**
-   * Returns a fresh readable stream for the uploaded content.
-   */
-  stream?: () => Streamer;
-
-  /**
-   * Optional cleanup hook (e.g., delete temp file after response).
-   */
-  cleanup?: () => Promise<void>;
-}
-
-export interface FileUploadOptions {
-  maxSize?: number; // bytes, default 10MB
-  mimeTypes?: string[]; // allowed MIME types, default all
-  required?: boolean;
-}
-
-export interface IFileUploadHandler {
-  file(fieldName: string, options?: FileUploadOptions): UploadedFile | undefined;
-  files(fieldName: string, options?: FileUploadOptions): UploadedFile[];
-  hasFile(fieldName: string): boolean;
-  validate(): { valid: boolean; errors: Record<string, string[]> };
-}
-
-/**
- * Check if MIME type is allowed
- */
-const isMimeTypeAllowed = (mimeType: string, allowed?: string[]): boolean => {
-  if (!allowed || allowed.length === 0) return true;
-
-  // Support wildcards like "image/*"
-  for (const allowedType of allowed) {
-    if (allowedType === mimeType) return true;
-    if (allowedType.endsWith('/*')) {
-      const prefix = allowedType.slice(0, -2);
-      if (mimeType.startsWith(prefix + '/')) return true;
-    }
-  }
-
-  return false;
-};
-
-/**
- * Create file upload handler for request
- */
-export const createFileUploadHandler = (req: IRequest): IFileUploadHandler => {
-  // Files would be extracted from multipart/form-data parsing
-  // This is a placeholder structure - actual implementation depends on
-  // how multipart data is parsed and stored on the request
-
-  const uploadedFiles: Map<string, UploadedFile[]> = new Map();
-
-  // Extract files from request if available
-  const requestBody = req.getBody?.();
-  if (typeof requestBody === 'object' && requestBody !== null && '__files' in requestBody) {
-    const filesData = (requestBody as { __files?: unknown }).__files;
-    if (typeof filesData === 'object' && filesData !== null) {
-      for (const [fieldName, files] of Object.entries(filesData)) {
-        if (Array.isArray(files)) {
-          uploadedFiles.set(fieldName, files as UploadedFile[]);
-        }
-      }
-    }
-  }
-
-  return {
-    file(fieldName: string, options?: FileUploadOptions): UploadedFile | undefined {
-      const files = uploadedFiles.get(fieldName);
-      if (!files || files.length === 0) return undefined;
-
-      const file = files[0];
-
-      // Validate MIME type
-      if (!isMimeTypeAllowed(file.mimeType, options?.mimeTypes)) {
-        return undefined;
-      }
-
-      // Validate size
-      const maxSize = options?.maxSize ?? 10 * 1024 * 1024; // 10MB default
-      if (file.size > maxSize) {
-        return undefined;
-      }
-
-      return file;
-    },
-
-    files(fieldName: string, options?: FileUploadOptions): UploadedFile[] {
-      const files = uploadedFiles.get(fieldName) ?? [];
-
-      return files.filter((file) => {
-        // Validate MIME type
-        if (!isMimeTypeAllowed(file.mimeType, options?.mimeTypes)) {
-          return false;
-        }
-
-        // Validate size
-        const maxSize = options?.maxSize ?? 10 * 1024 * 1024; // 10MB default
-        if (file.size > maxSize) {
-          return false;
-        }
-
-        return true;
-      });
-    },
-
-    hasFile(fieldName: string): boolean {
-      const files = uploadedFiles.get(fieldName);
-      return files !== undefined && files.length > 0;
-    },
-
-    validate(): { valid: boolean; errors: Record<string, string[]> } {
-      const errors: Record<string, string[]> = {};
-      return { valid: Object.keys(errors).length === 0, errors };
-    },
-  };
-};
-
-export const FileUpload = Object.freeze({
-  /**
-   * Create handler for request
-   */
-  createHandler(req: IRequest): IFileUploadHandler {
-    return createFileUploadHandler(req);
-  },
-
-  /**
-   * Validate uploaded files
-   */
-  validateFiles(
-    files: UploadedFile[],
-    options: {
-      required?: boolean;
-      minCount?: number;
-      maxCount?: number;
-      mimeTypes?: string[];
-      maxSize?: number;
-    }
-  ): { valid: boolean; error?: string } {
-    if (options.required === true && files.length === 0) {
-      return { valid: false, error: 'At least one file is required' };
-    }
-
-    if (typeof options.minCount === 'number' && files.length < options.minCount) {
-      return { valid: false, error: `At least ${options.minCount} files required` };
-    }
-
-    if (typeof options.maxCount === 'number' && files.length > options.maxCount) {
-      return { valid: false, error: `Maximum ${options.maxCount} files allowed` };
-    }
-
-    for (const file of files) {
-      if (!isMimeTypeAllowed(file.mimeType, options.mimeTypes)) {
-        return { valid: false, error: `File type not allowed: ${file.mimeType}` };
-      }
-
-      const maxSize = options.maxSize ?? 10 * 1024 * 1024;
-      if (file.size > maxSize) {
-        return {
-          valid: false,
-          error: `File too large: ${file.originalName} (${file.size} bytes)`,
-        };
-      }
-    }
-
-    return { valid: true };
-  },
-});
-
-export default FileUpload;

package/src/http/Kernel.ts

@@ -1,361 +0,0 @@
-/**
- * HTTP Kernel - Request handling and middleware pipeline
- */
-
-import { Logger } from '@config/logger';
-import { middlewareConfig } from '@config/middleware';
-import type { IServiceContainer } from '@container/ServiceContainer';
-import { ErrorRouting } from '@core-routes/error';
-import type { IRouter } from '@core-routes/Router';
-import { Router } from '@core-routes/Router';
-import type { IRequest } from '@http/Request';
-import { Request } from '@http/Request';
-import { RequestContext, type IRequestContext } from '@http/RequestContext';
-import type { IResponse } from '@http/Response';
-import { Response } from '@http/Response';
-import type { IMiddlewareStack, Middleware } from '@middleware/MiddlewareStack';
-import { MiddlewareStack } from '@middleware/MiddlewareStack';
-import type { IncomingMessage, ServerResponse } from '@node-singletons/http';
-
-import { OpenTelemetry } from '@/observability/OpenTelemetry';
-import { PrometheusMetrics } from '@/observability/PrometheusMetrics';
-import { create as createScheduleRunner } from '@/scheduler/ScheduleRunner';
-import type { ISchedule, IScheduleKernel } from '@/scheduler/types';
-import { Env } from '@config/env';
-
-export interface IKernel {
-  handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
-  handleRequest(req: IRequest, res: IResponse): Promise<void>;
-  terminate(req: IRequest, res: IResponse): void;
-  registerGlobalMiddleware(...middleware: Middleware[]): void;
-  registerRouteMiddleware(name: string, middleware: Middleware): void;
-  getRouter(): IRouter;
-  getContainer(): IServiceContainer;
-  getMiddlewareStack(): IMiddlewareStack;
-
-  // Scheduling API
-  registerSchedule(schedule: ISchedule): void;
-  startSchedules(): void;
-  stopSchedules(): Promise<void>;
-  runScheduleOnce(name: string): Promise<void>;
-}
-
-/**
- * Terminate request lifecycle
- */
-function terminate(_req: IRequest, _res: IResponse): void {
-  // Cleanup, logging, etc.
-}
-
-const isWritableEnded = (res: IResponse): boolean => {
-  if (typeof res.getRaw !== 'function') return false;
-  const raw = res.getRaw();
-  if (typeof raw !== 'object' || raw === null) return false;
-  if (!('writableEnded' in raw)) return false;
-  return Boolean((raw as unknown as { writableEnded?: boolean }).writableEnded);
-};
-
-const getStatusSafe = (res: IResponse): number => {
-  try {
-    if (typeof res.getStatus === 'function') return res.getStatus();
-  } catch {
-    // ignore
-  }
-
-  try {
-    if (typeof res.getRaw === 'function') {
-      const raw = res.getRaw();
-      const maybeStatusCode = (raw as unknown as { statusCode?: unknown }).statusCode;
-      if (typeof maybeStatusCode === 'number') return maybeStatusCode;
-    }
-  } catch {
-    // ignore
-  }
-
-  return 0;
-};
-
-const resolveMiddlewareForRoute = (
-  route: unknown,
-  globalMiddleware: Middleware[],
-  routeMiddleware: Record<string, Middleware>
-): Middleware[] => {
-  const routeAny = route as { middleware?: unknown };
-  const routeMiddlewareNames = Array.isArray(routeAny.middleware)
-    ? routeAny.middleware.filter((m): m is string => typeof m === 'string')
-    : [];
-
-  const resolvedRouteMiddleware = routeMiddlewareNames
-    .map((name) => routeMiddleware[name])
-    .filter((mw): mw is Middleware => typeof mw === 'function');
-
-  return [...globalMiddleware, ...resolvedRouteMiddleware];
-};
-
-type KernelTraceSpan = ReturnType<typeof OpenTelemetry.startHttpServerSpan>;
-
-const maybeStartKernelTraceSpan = (
-  req: IRequest,
-  context: IRequestContext
-): KernelTraceSpan | undefined => {
-  if (OpenTelemetry.isEnabled() === false) return undefined;
-
-  try {
-    return OpenTelemetry.startHttpServerSpan(req, {
-      method: context.method,
-      path: req.getPath(),
-      requestId: context.requestId,
-      serviceName: Env.APP_NAME,
-      userAgent: context.userAgent,
-      userId: context.userId,
-      tenantId: context.tenantId,
-    });
-  } catch {
-    return undefined;
-  }
-};
-
-const maybeSetKernelTraceRoute = (
-  traceSpan: KernelTraceSpan | undefined,
-  method: string,
-  routeLabel: string
-): void => {
-  if (!traceSpan) return;
-  OpenTelemetry.setHttpRoute(traceSpan.span, method, routeLabel);
-};
-
-const runKernelPipeline = async (
-  router: IRouter,
-  globalMiddleware: Middleware[],
-  routeMiddleware: Record<string, Middleware>,
-  req: IRequest,
-  res: IResponse,
-  context: IRequestContext,
-  traceSpan: KernelTraceSpan | undefined
-): Promise<string> => {
-  Logger.info(`[${req.getMethod()}] ${req.getPath()}`);
-
-  const route = Router.match(router, req.getMethod(), req.getPath());
-  if (!route) {
-    const routeLabel = 'not_found';
-    maybeSetKernelTraceRoute(traceSpan, context.method, routeLabel);
-    const handleNotFound = ErrorRouting.handleNotFound as (
-      request: IRequest,
-      response: IResponse,
-      requestId?: string
-    ) => Promise<void>;
-    await handleNotFound(req, res, context.requestId);
-    return routeLabel;
-  }
-
-  // Safe type guard to ensure route.routePath is a non-empty string before calling .trim()
-  const hasNonEmptyRoutePath = (r: unknown): r is { routePath: string } => {
-    if (typeof r !== 'object' || r === null) return false;
-    const rp = (r as { routePath?: unknown }).routePath;
-    return typeof rp === 'string' && rp.trim() !== '';
-  };
-
-  const routeLabel = hasNonEmptyRoutePath(route) ? route.routePath : req.getPath();
-
-  maybeSetKernelTraceRoute(traceSpan, context.method, routeLabel);
-
-  // Use a typed view of the matched route to avoid unsafe member access
-  const matchedRoute = route as {
-    params?: Record<string, unknown>;
-    handler: (req: IRequest, res: IResponse) => Promise<void> | void;
-    routePath?: string;
-  };
-
-  // Coerce route params (which may be undefined or non-string) into the
-  // expected Record<string, string> shape required by Request.setParams.
-  const safeParams: Record<string, string> = {};
-  if (typeof matchedRoute.params === 'object' && matchedRoute.params !== null) {
-    for (const [k, v] of Object.entries(matchedRoute.params)) {
-      if (v === undefined || v === null) continue;
-      safeParams[k] = typeof v === 'string' ? v : String(v);
-    }
-  }
-  req.setParams(safeParams);
-
-  const middlewareToRun = resolveMiddlewareForRoute(
-    matchedRoute,
-    globalMiddleware,
-    routeMiddleware
-  );
-
-  let index = 0;
-  const next = async (): Promise<void> => {
-    if (index < middlewareToRun.length) {
-      const mw = middlewareToRun[index++];
-      await mw(req, res, next);
-      return;
-    }
-    await matchedRoute.handler(req, res);
-  };
-
-  await next();
-  return routeLabel;
-};
-
-const finalizeKernelObservability = (
-  context: IRequestContext,
-  res: IResponse,
-  routeLabel: string,
-  thrown: unknown,
-  traceSpan: KernelTraceSpan | undefined
-): void => {
-  if (Env.getBool('METRICS_ENABLED', false)) {
-    const status = getStatusSafe(res);
-    const durationMs = Date.now() - context.startTime;
-    void PrometheusMetrics.observeHttpRequest({
-      method: context.method,
-      route: routeLabel,
-      status,
-      durationMs,
-    }).catch(() => {
-      // best-effort
-    });
-  }
-
-  if (traceSpan) {
-    const status = getStatusSafe(res);
-
-    // Late-bind context-derived attributes so auth/tenant middleware can populate them.
-    try {
-      if (typeof context.userId === 'string' && context.userId.trim() !== '') {
-        traceSpan.span.setAttribute('enduser.id', context.userId);
-      }
-      if (typeof context.tenantId === 'string' && context.tenantId.trim() !== '') {
-        traceSpan.span.setAttribute('zintrust.tenant_id', context.tenantId);
-      }
-      if (typeof context.traceId === 'string' && context.traceId.trim() !== '') {
-        traceSpan.span.setAttribute('zintrust.trace_id', context.traceId);
-      }
-    } catch {
-      // best-effort
-    }
-
-    OpenTelemetry.endHttpServerSpan(traceSpan.span, {
-      route: routeLabel,
-      status,
-      error: thrown,
-    });
-  }
-};
-
-const createHandleRequest = (
-  router: IRouter,
-  globalMiddleware: Middleware[],
-  routeMiddleware: Record<string, Middleware>
-): ((req: IRequest, res: IResponse) => Promise<void>) => {
-  return async (req: IRequest, res: IResponse): Promise<void> => {
-    const context = RequestContext.create(req);
-    let routeLabel = 'unmatched';
-    let traceSpan: KernelTraceSpan | undefined;
-    let thrown: unknown;
-    try {
-      await RequestContext.run(context, async () => {
-        traceSpan = maybeStartKernelTraceSpan(req, context);
-
-        const run = async (): Promise<string> =>
-          runKernelPipeline(
-            router,
-            globalMiddleware,
-            routeMiddleware,
-            req,
-            res,
-            context,
-            traceSpan
-          );
-
-        routeLabel = traceSpan
-          ? await OpenTelemetry.runWithContext(traceSpan.context, run)
-          : await run();
-      });
-    } catch (error) {
-      thrown = error;
-      Logger.error('Kernel error:', error as Error);
-      if (!isWritableEnded(res)) {
-        ErrorRouting.handleInternalServerErrorWithWrappers(req, res, error, context.requestId);
-      }
-    } finally {
-      finalizeKernelObservability(context, res, routeLabel, thrown, traceSpan);
-      terminate(req, res);
-    }
-  };
-};
-
-const createHandle =
-  (handleRequest: (req: IRequest, res: IResponse) => Promise<void>) =>
-  async (nodeReq: IncomingMessage, nodeRes: ServerResponse): Promise<void> => {
-    const req = Request.create(nodeReq);
-    const res = Response.create(nodeRes);
-    await handleRequest(req, res);
-  };
-
-/**
- * HTTP Kernel Factory
- */
-const create = (router: IRouter, container: IServiceContainer): IKernel => {
-  const globalMiddleware: Middleware[] = <Middleware[]>[];
-  const routeMiddleware: Record<string, Middleware> = {};
-  const middlewareStack = MiddlewareStack.create();
-
-  // Scheduling runner (for long-running runtimes)
-  const scheduleRunner = createScheduleRunner();
-
-  const scheduleKernel: IScheduleKernel = Object.freeze({
-    getContainer: () => container,
-    getRouter: () => router,
-  });
-
-  // Register default middleware config
-  globalMiddleware.push(...middlewareConfig.global);
-  for (const [name, mw] of Object.entries(middlewareConfig.route)) {
-    routeMiddleware[name] = mw;
-  }
-
-  const handleRequest = createHandleRequest(router, globalMiddleware, routeMiddleware);
-  const handle = createHandle(handleRequest);
-
-  return {
-    handle,
-    handleRequest,
-    terminate,
-    registerGlobalMiddleware(...middleware: Middleware[]): void {
-      globalMiddleware.push(...middleware);
-    },
-    registerRouteMiddleware(name: string, middleware: Middleware): void {
-      routeMiddleware[name] = middleware;
-    },
-    getRouter: (): IRouter => router,
-    getContainer: (): IServiceContainer => container,
-    getMiddlewareStack: (): IMiddlewareStack => middlewareStack,
-
-    // Scheduling API
-    registerSchedule(schedule: ISchedule): void {
-      scheduleRunner.register(schedule);
-    },
-
-    startSchedules(): void {
-      // Delegated to the internal ScheduleRunner. Kernel will call startSchedules
-      // during boot for long-running runtimes (Node / Fargate).
-      scheduleRunner.start(scheduleKernel);
-    },
-
-    async stopSchedules(): Promise<void> {
-      const timeoutMs = Env.getInt('SCHEDULE_SHUTDOWN_TIMEOUT_MS', 30000);
-      await scheduleRunner.stop(timeoutMs);
-    },
-
-    async runScheduleOnce(name: string): Promise<void> {
-      await scheduleRunner.runOnce(name, scheduleKernel);
-    },
-  };
-};
-
-export const Kernel = Object.freeze({
-  create,
-});
-
-export default Kernel;