@zintrust/core 0.1.28 → 0.1.30

package/src/http/Controller.js

@@ -0,0 +1,46 @@
+/**
+ * Base Controller
+ * All controllers extend this class
+ */
+/**
+ * Base Controller
+ * Sealed namespace for immutability
+ */
+export const Controller = Object.freeze({
+    /**
+     * Send JSON response
+     */
+    json(res, data, statusCode = 200) {
+        res.setStatus(statusCode).json(data);
+    },
+    /**
+     * Send error response
+     */
+    error(res, message, statusCode = 400) {
+        res.setStatus(statusCode).json({ error: message });
+    },
+    /**
+     * Redirect response
+     */
+    redirect(res, url, statusCode = 302) {
+        res.redirect(url, statusCode);
+    },
+    /**
+     * Get route parameter
+     */
+    param(req, name) {
+        return req.getParam(name);
+    },
+    /**
+     * Get query parameter
+     */
+    query(req, name) {
+        return req.getQueryParam(name);
+    },
+    /**
+     * Get request body
+     */
+    body(req) {
+        return req.getBody();
+    },
+});

package/src/http/ErrorResponse.d.ts

@@ -0,0 +1,28 @@
+export interface IErrorResponse {
+    statusCode: number;
+    message: string;
+    code: string;
+    requestId: string;
+    timestamp: string;
+    details?: Record<string, unknown>;
+    stack?: string;
+}
+export declare const ErrorResponse: Readonly<{
+    create: (params: {
+        statusCode: number;
+        message: string;
+        code: string;
+        requestId?: string;
+        details?: Record<string, unknown>;
+        stack?: string;
+    }) => IErrorResponse;
+    notFound(resource: string, requestId?: string): IErrorResponse;
+    badRequest(message: string, requestId?: string, details?: Record<string, unknown>): IErrorResponse;
+    unauthorized(message: string, requestId?: string): IErrorResponse;
+    forbidden(message: string, requestId?: string): IErrorResponse;
+    conflict(message: string, requestId?: string): IErrorResponse;
+    internalServerError(message?: string, requestId?: string, stack?: string): IErrorResponse;
+    serviceUnavailable(message?: string, requestId?: string): IErrorResponse;
+}>;
+export default ErrorResponse;
+//# sourceMappingURL=ErrorResponse.d.ts.map

package/src/http/ErrorResponse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorResponse.d.ts","sourceRoot":"","sources":["../../../src/http/ErrorResponse.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAsBD,eAAO,MAAM,aAAa;qBApBF;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,KAAG,cAAc;uBAgBG,MAAM,cAAc,MAAM,GAAG,cAAc;wBAUnD,MAAM,cACH,MAAM,YACR,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,cAAc;0BAIK,MAAM,cAAc,MAAM,GAAG,cAAc;uBAI9C,MAAM,cAAc,MAAM,GAAG,cAAc;sBAI5C,MAAM,cAAc,MAAM,GAAG,cAAc;kCAKlD,MAAM,cACH,MAAM,UACV,MAAM,GACb,cAAc;iCAIW,MAAM,cAAsC,MAAM,GAAG,cAAc;EAG/F,CAAC;AAEH,eAAe,aAAa,CAAC"}

package/src/http/ErrorResponse.js

@@ -0,0 +1,42 @@
+const create = (params) => {
+    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, requestId) {
+        return create({
+            statusCode: 404,
+            message: `${resource} not found`,
+            code: 'NOT_FOUND',
+            requestId,
+        });
+    },
+    badRequest(message, requestId, details) {
+        return create({ statusCode: 400, message, code: 'BAD_REQUEST', requestId, details });
+    },
+    unauthorized(message, requestId) {
+        return create({ statusCode: 401, message, code: 'UNAUTHORIZED', requestId });
+    },
+    forbidden(message, requestId) {
+        return create({ statusCode: 403, message, code: 'FORBIDDEN', requestId });
+    },
+    conflict(message, requestId) {
+        return create({ statusCode: 409, message, code: 'CONFLICT', requestId });
+    },
+    internalServerError(message = 'Internal server error', requestId, stack) {
+        return create({ statusCode: 500, message, code: 'INTERNAL_SERVER_ERROR', requestId, stack });
+    },
+    serviceUnavailable(message = 'Service unavailable', requestId) {
+        return create({ statusCode: 503, message, code: 'SERVICE_UNAVAILABLE', requestId });
+    },
+});
+export default ErrorResponse;

package/src/http/FileUpload.d.ts

@@ -0,0 +1,68 @@
+/**
+ * File Upload Handler
+ * Handles multipart/form-data file uploads with validation and storage integration
+ */
+import type { IRequest } from './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;
+    mimeTypes?: string[];
+    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[]>;
+    };
+}
+/**
+ * Create file upload handler for request
+ */
+export declare const createFileUploadHandler: (req: IRequest) => IFileUploadHandler;
+export declare const FileUpload: Readonly<{
+    /**
+     * Create handler for request
+     */
+    createHandler(req: IRequest): IFileUploadHandler;
+    /**
+     * Validate uploaded files
+     */
+    validateFiles(files: UploadedFile[], options: {
+        required?: boolean;
+        minCount?: number;
+        maxCount?: number;
+        mimeTypes?: string[];
+        maxSize?: number;
+    }): {
+        valid: boolean;
+        error?: string;
+    };
+}>;
+export default FileUpload;
+//# sourceMappingURL=FileUpload.d.ts.map

package/src/http/FileUpload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileUpload.d.ts","sourceRoot":"","sources":["../../../src/http/FileUpload.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,QAAQ,CAAC;IAExB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,YAAY,GAAG,SAAS,CAAC;IAC/E,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,YAAY,EAAE,CAAC;IACtE,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,QAAQ,IAAI;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;KAAE,CAAC;CAClE;AAoBD;;GAEG;AACH,eAAO,MAAM,uBAAuB,GAAI,KAAK,QAAQ,KAAG,kBAsEvD,CAAC;AAEF,eAAO,MAAM,UAAU;IACrB;;OAEG;uBACgB,QAAQ,GAAG,kBAAkB;IAIhD;;OAEG;yBAEM,YAAY,EAAE,WACZ;QACP,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GACA;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;EA6BrC,CAAC;AAEH,eAAe,UAAU,CAAC"}

package/src/http/FileUpload.js

@@ -0,0 +1,120 @@
+/**
+ * File Upload Handler
+ * Handles multipart/form-data file uploads with validation and storage integration
+ */
+/**
+ * Check if MIME type is allowed
+ */
+const isMimeTypeAllowed = (mimeType, allowed) => {
+    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) => {
+    // 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 = new Map();
+    // Extract files from request if available
+    const requestBody = req.getBody?.();
+    if (typeof requestBody === 'object' && requestBody !== null && '__files' in requestBody) {
+        const filesData = requestBody.__files;
+        if (typeof filesData === 'object' && filesData !== null) {
+            for (const [fieldName, files] of Object.entries(filesData)) {
+                if (Array.isArray(files)) {
+                    uploadedFiles.set(fieldName, files);
+                }
+            }
+        }
+    }
+    return {
+        file(fieldName, options) {
+            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, options) {
+            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) {
+            const files = uploadedFiles.get(fieldName);
+            return files !== undefined && files.length > 0;
+        },
+        validate() {
+            const errors = {};
+            return { valid: Object.keys(errors).length === 0, errors };
+        },
+    };
+};
+export const FileUpload = Object.freeze({
+    /**
+     * Create handler for request
+     */
+    createHandler(req) {
+        return createFileUploadHandler(req);
+    },
+    /**
+     * Validate uploaded files
+     */
+    validateFiles(files, options) {
+        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.d.ts

@@ -0,0 +1,29 @@
+/**
+ * HTTP Kernel - Request handling and middleware pipeline
+ */
+import type { IServiceContainer } from '../container/ServiceContainer';
+import type { IRouter } from '../routes/Router';
+import type { IRequest } from './Request';
+import type { IResponse } from './Response';
+import type { IMiddlewareStack, Middleware } from '../middleware/MiddlewareStack';
+import type { IncomingMessage, ServerResponse } from '../node-singletons/http';
+import type { ISchedule } from '../scheduler/types';
+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;
+    registerSchedule(schedule: ISchedule): void;
+    startSchedules(): void;
+    stopSchedules(): Promise<void>;
+    runScheduleOnce(name: string): Promise<void>;
+}
+export declare const Kernel: Readonly<{
+    create: (router: IRouter, container: IServiceContainer) => IKernel;
+}>;
+export default Kernel;
+//# sourceMappingURL=Kernel.d.ts.map

package/src/http/Kernel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Kernel.d.ts","sourceRoot":"","sources":["../../../src/http/Kernel.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAErE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEhF,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAK7E,OAAO,KAAK,EAAE,SAAS,EAAmB,MAAM,mBAAmB,CAAC;AAGpE,MAAM,WAAW,OAAO;IACtB,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,GAAG,IAAI,CAAC;IAC/C,wBAAwB,CAAC,GAAG,UAAU,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IAC5D,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACpE,SAAS,IAAI,OAAO,CAAC;IACrB,YAAY,IAAI,iBAAiB,CAAC;IAClC,kBAAkB,IAAI,gBAAgB,CAAC;IAGvC,gBAAgB,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5C,cAAc,IAAI,IAAI,CAAC;IACvB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAuTD,eAAO,MAAM,MAAM;qBA1DK,OAAO,aAAa,iBAAiB,KAAG,OAAO;EA4DrE,CAAC;AAEH,eAAe,MAAM,CAAC"}

package/src/http/Kernel.js

@@ -0,0 +1,254 @@
+/**
+ * HTTP Kernel - Request handling and middleware pipeline
+ */
+import { Logger } from '../config/logger.js';
+import { middlewareConfig } from '../config/middleware.js';
+import { ErrorRouting } from '../routes/error.js';
+import { Router } from '../routes/Router.js';
+import { Request } from './Request.js';
+import { RequestContext } from './RequestContext.js';
+import { Response } from './Response.js';
+import { MiddlewareStack } from '../middleware/MiddlewareStack.js';
+import { OpenTelemetry } from '../observability/OpenTelemetry.js';
+import { PrometheusMetrics } from '../observability/PrometheusMetrics.js';
+import { create as createScheduleRunner } from '../scheduler/ScheduleRunner.js';
+import { Env } from '../config/env.js';
+/**
+ * Terminate request lifecycle
+ */
+function terminate(_req, _res) {
+    // Cleanup, logging, etc.
+}
+const isWritableEnded = (res) => {
+    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.writableEnded);
+};
+const getStatusSafe = (res) => {
+    try {
+        if (typeof res.getStatus === 'function')
+            return res.getStatus();
+    }
+    catch {
+        // ignore
+    }
+    try {
+        if (typeof res.getRaw === 'function') {
+            const raw = res.getRaw();
+            const maybeStatusCode = raw.statusCode;
+            if (typeof maybeStatusCode === 'number')
+                return maybeStatusCode;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return 0;
+};
+const resolveMiddlewareForRoute = (route, globalMiddleware, routeMiddleware) => {
+    const routeAny = route;
+    const routeMiddlewareNames = Array.isArray(routeAny.middleware)
+        ? routeAny.middleware.filter((m) => typeof m === 'string')
+        : [];
+    const resolvedRouteMiddleware = routeMiddlewareNames
+        .map((name) => routeMiddleware[name])
+        .filter((mw) => typeof mw === 'function');
+    return [...globalMiddleware, ...resolvedRouteMiddleware];
+};
+const maybeStartKernelTraceSpan = (req, context) => {
+    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, method, routeLabel) => {
+    if (!traceSpan)
+        return;
+    OpenTelemetry.setHttpRoute(traceSpan.span, method, routeLabel);
+};
+const runKernelPipeline = async (router, globalMiddleware, routeMiddleware, req, res, context, traceSpan) => {
+    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) => {
+        if (typeof r !== 'object' || r === null)
+            return false;
+        const rp = r.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;
+    // Coerce route params (which may be undefined or non-string) into the
+    // expected Record<string, string> shape required by Request.setParams.
+    const safeParams = {};
+    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 () => {
+        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, res, routeLabel, thrown, traceSpan) => {
+    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, globalMiddleware, routeMiddleware) => {
+    return async (req, res) => {
+        const context = RequestContext.create(req);
+        let routeLabel = 'unmatched';
+        let traceSpan;
+        let thrown;
+        try {
+            await RequestContext.run(context, async () => {
+                traceSpan = maybeStartKernelTraceSpan(req, context);
+                const run = async () => 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);
+            if (!isWritableEnded(res)) {
+                ErrorRouting.handleInternalServerErrorWithWrappers(req, res, error, context.requestId);
+            }
+        }
+        finally {
+            finalizeKernelObservability(context, res, routeLabel, thrown, traceSpan);
+            terminate(req, res);
+        }
+    };
+};
+const createHandle = (handleRequest) => async (nodeReq, nodeRes) => {
+    const req = Request.create(nodeReq);
+    const res = Response.create(nodeRes);
+    await handleRequest(req, res);
+};
+/**
+ * HTTP Kernel Factory
+ */
+const create = (router, container) => {
+    const globalMiddleware = [];
+    const routeMiddleware = {};
+    const middlewareStack = MiddlewareStack.create();
+    // Scheduling runner (for long-running runtimes)
+    const scheduleRunner = createScheduleRunner();
+    const scheduleKernel = 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) {
+            globalMiddleware.push(...middleware);
+        },
+        registerRouteMiddleware(name, middleware) {
+            routeMiddleware[name] = middleware;
+        },
+        getRouter: () => router,
+        getContainer: () => container,
+        getMiddlewareStack: () => middlewareStack,
+        // Scheduling API
+        registerSchedule(schedule) {
+            scheduleRunner.register(schedule);
+        },
+        startSchedules() {
+            // Delegated to the internal ScheduleRunner. Kernel will call startSchedules
+            // during boot for long-running runtimes (Node / Fargate).
+            scheduleRunner.start(scheduleKernel);
+        },
+        async stopSchedules() {
+            const timeoutMs = Env.getInt('SCHEDULE_SHUTDOWN_TIMEOUT_MS', 30000);
+            await scheduleRunner.stop(timeoutMs);
+        },
+        async runScheduleOnce(name) {
+            await scheduleRunner.runOnce(name, scheduleKernel);
+        },
+    };
+};
+export const Kernel = Object.freeze({
+    create,
+});
+export default Kernel;

package/src/http/Request.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Request - HTTP Request wrapper
+ * Wraps Node.js IncomingMessage with additional utilities
+ */
+import type { FileUploadOptions, IFileUploadHandler, UploadedFile } from './FileUpload';
+import type * as http from '../node-singletons/http';
+import type { JwtPayload } from '../security/JwtManager';
+type HeadParam = string | string[] | undefined;
+export interface IRequest {
+    sessionId: HeadParam;
+    user: JwtPayload | undefined;
+    params: Record<string, string>;
+    body: Record<string, unknown>;
+    validated: {
+        body?: unknown;
+        query?: unknown;
+        params?: unknown;
+        headers?: unknown;
+    };
+    getMethod(): string;
+    getPath(): string;
+    getHeaders(): http.IncomingHttpHeaders;
+    readonly headers: http.IncomingHttpHeaders;
+    getHeader(name: string): HeadParam;
+    getParams(): Record<string, string>;
+    getParam(key: string): string | undefined;
+    setParams(params: Record<string, string>): void;
+    getQuery(): Record<string, string | string[]>;
+    getQueryParam(key: string): HeadParam;
+    setBody(body: unknown): void;
+    getBody(): unknown;
+    isJson(): boolean;
+    getRaw(): http.IncomingMessage;
+    context: Record<string, unknown>;
+    file(fieldName: string, options?: FileUploadOptions): UploadedFile | undefined;
+    files(fieldName: string, options?: FileUploadOptions): UploadedFile[];
+    hasFile(fieldName: string): boolean;
+    fileUpload(): IFileUploadHandler;
+    /**
+     * Unified data access
+     * Returns merged object from Body > Path Params > Query Params
+     */
+    data(): Record<string, unknown>;
+    /**
+     * Get specific field from unified data
+     */
+    get<T = unknown>(key: string, defaultValue?: T): T;
+}
+export type ValidatedRequest<TBody = unknown, TQuery = unknown, TParams = unknown, THeaders = unknown> = Omit<IRequest, 'validated'> & {
+    validated: {
+        body: TBody;
+        query: TQuery;
+        params: TParams;
+        headers: THeaders;
+    };
+};
+export declare const Request: Readonly<{
+    /**
+     * Create a new request instance
+     */
+    create(req: http.IncomingMessage): IRequest;
+}>;
+export default Request;
+//# sourceMappingURL=Request.d.ts.map

package/src/http/Request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Request.d.ts","sourceRoot":"","sources":["../../../src/http/Request.ts"],"names":[],"mappings":"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"}