@zintrust/core 0.1.26 → 0.1.28

package/src/http/ErrorResponse.ts

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

@@ -0,0 +1,194 @@
+/**
+ * File Upload Handler
+ * Handles multipart/form-data file uploads with validation and storage integration
+ */
+
+import type { IRequest } from '@http/Request';
+import type { Readable } from 'node:stream';
+
+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?: () => Readable;
+
+  /**
+   * 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

@@ -0,0 +1,356 @@
+/**
+ * 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);
+    ErrorRouting.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;