@zintrust/core 0.1.19 → 0.1.20

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

@@ -1,12 +1,12 @@
 /**
  * HTTP Kernel - Request handling and middleware pipeline
  */
-import { IServiceContainer } from '../container/ServiceContainer';
-import { IRequest } from './Request';
-import { IResponse } from './Response';
-import { IMiddlewareStack, Middleware } from '../middleware/MiddlewareStack';
+import type { IServiceContainer } from '../container/ServiceContainer';
+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 { IRouter } from '../routing/Router';
+import type { IRouter } from '../routing/Router';
 import type { ISchedule } from '../scheduler/types';
 export interface IKernel {
     handle(req: IncomingMessage, res: ServerResponse): Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"Kernel.d.ts","sourceRoot":"","sources":["../../../src/http/Kernel.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhE,OAAO,EAAE,QAAQ,EAAW,MAAM,eAAe,CAAC;AAElD,OAAO,EAAE,SAAS,EAAY,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAmB,MAAM,6BAA6B,CAAC;AAC5F,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAU,MAAM,iBAAiB,CAAC;AAGlD,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;AAuJD,eAAO,MAAM,MAAM;qBA1DK,OAAO,aAAa,iBAAiB,KAAG,OAAO;EA4DrE,CAAC;AAEH,eAAe,MAAM,CAAC"}
+{"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;AACrE,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;AAC7E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAO/C,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

@@ -3,12 +3,14 @@
  */
 import { Logger } from '../config/logger.js';
 import { middlewareConfig } from '../config/middleware.js';
-import { ErrorResponse } from './ErrorResponse.js';
 import { Request } from './Request.js';
 import { RequestContext } from './RequestContext.js';
 import { Response } from './Response.js';
 import { MiddlewareStack } from '../middleware/MiddlewareStack.js';
 import { Router } from '../routing/Router.js';
+import { ErrorRouting } from '../routing/error.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';
 /**
@@ -27,6 +29,27 @@ const isWritableEnded = (res) => {
         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)
@@ -37,41 +60,134 @@ const resolveMiddlewareForRoute = (route, globalMiddleware, routeMiddleware) =>
         .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 () => {
-                Logger.info(`[${req.getMethod()}] ${req.getPath()}`);
-                // Match route
-                const route = Router.match(router, req.getMethod(), req.getPath());
-                if (!route) {
-                    res.setStatus(404).json(ErrorResponse.notFound('Route', context.requestId));
-                    return;
-                }
-                req.setParams(route.params);
-                const middlewareToRun = resolveMiddlewareForRoute(route, globalMiddleware, routeMiddleware);
-                let index = 0;
-                const next = async () => {
-                    if (index < middlewareToRun.length) {
-                        const mw = middlewareToRun[index++];
-                        await mw(req, res, next);
-                        return;
-                    }
-                    await route.handler(req, res);
-                };
-                await next();
+                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)) {
-                res
-                    .setStatus(500)
-                    .json(ErrorResponse.internalServerError('Internal server error', context.requestId));
+                ErrorRouting.handleInternalServerErrorWithWrappers(req, res, error, context.requestId);
             }
         }
         finally {
+            finalizeKernelObservability(context, res, routeLabel, thrown, traceSpan);
             terminate(req, res);
         }
     };

package/src/http/Request.d.ts

@@ -2,7 +2,8 @@
  * Request - HTTP Request wrapper
  * Wraps Node.js IncomingMessage with additional utilities
  */
-import * as http from '../node-singletons/http';
+import type { FileUploadOptions, IFileUploadHandler, UploadedFile } from './FileUpload';
+import type * as http from '../node-singletons/http';
 type HeadParam = string | string[] | undefined;
 type JwtPayload = import('../index').JwtPayload;
 export interface IRequest {
@@ -10,6 +11,12 @@ export interface IRequest {
     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;
@@ -25,7 +32,19 @@ export interface IRequest {
     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;
 }
+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

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

@@ -1 +1 @@
-{"version":3,"file":"Request.d.ts","sourceRoot":"","sources":["../../../src/http/Request.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAE9C,KAAK,SAAS,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;AAC/C,KAAK,UAAU,GAAG,OAAO,SAAS,EAAE,UAAU,CAAC;AAE/C,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,SAAS,CAAC;IACrB,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,SAAS,IAAI,MAAM,CAAC;IACpB,OAAO,IAAI,MAAM,CAAC;IAClB,UAAU,IAAI,IAAI,CAAC,mBAAmB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,mBAAmB,CAAC;IAC3C,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC1C,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAChD,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,OAAO,IAAI,OAAO,CAAC;IACnB,MAAM,IAAI,OAAO,CAAC;IAClB,MAAM,IAAI,IAAI,CAAC,eAAe,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAkKD,eAAO,MAAM,OAAO;IAClB;;OAEG;gBACS,IAAI,CAAC,eAAe,GAAG,QAAQ;EAO3C,CAAC;AAEH,eAAe,OAAO,CAAC"}
+{"version":3,"file":"Request.d.ts","sourceRoot":"","sources":["../../../src/http/Request.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE5F,OAAO,KAAK,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAEnD,KAAK,SAAS,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;AAC/C,KAAK,UAAU,GAAG,OAAO,SAAS,EAAE,UAAU,CAAC;AAE/C,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,SAAS,CAAC;IACrB,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE;QACT,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,SAAS,IAAI,MAAM,CAAC;IACpB,OAAO,IAAI,MAAM,CAAC;IAClB,UAAU,IAAI,IAAI,CAAC,mBAAmB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,mBAAmB,CAAC;IAC3C,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC1C,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAChD,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,OAAO,IAAI,OAAO,CAAC;IACnB,MAAM,IAAI,OAAO,CAAC;IAClB,MAAM,IAAI,IAAI,CAAC,eAAe,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAGjC,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,UAAU,IAAI,kBAAkB,CAAC;CAClC;AAED,MAAM,MAAM,gBAAgB,CAC1B,KAAK,GAAG,OAAO,EACf,MAAM,GAAG,OAAO,EAChB,OAAO,GAAG,OAAO,EACjB,QAAQ,GAAG,OAAO,IAChB,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG;IAChC,SAAS,EAAE;QACT,IAAI,EAAE,KAAK,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,OAAO,CAAC;QAChB,OAAO,EAAE,QAAQ,CAAC;KACnB,CAAC;CACH,CAAC;AAoMF,eAAO,MAAM,OAAO;IAClB;;OAEG;gBACS,IAAI,CAAC,eAAe,GAAG,QAAQ;EAO3C,CAAC;AAEH,eAAe,OAAO,CAAC"}

package/src/http/Request.js

@@ -2,6 +2,7 @@
  * Request - HTTP Request wrapper
  * Wraps Node.js IncomingMessage with additional utilities
  */
+import { FileUpload } from './FileUpload.js';
 /**
  * Request - HTTP Request wrapper
  * Refactored to Functional Object pattern
@@ -39,6 +40,7 @@ const createRequestState = (req) => {
         params: {},
         body: null,
         bodyRecord: {},
+        validated: {},
     };
 };
 const setBodyState = (state, newBody) => {
@@ -72,6 +74,12 @@ const createRequestProperties = (state, context) => {
         set body(newBody) {
             setBodyState(state, newBody);
         },
+        get validated() {
+            return state.validated;
+        },
+        set validated(v) {
+            state.validated = v;
+        },
     };
 };
 const createRequestMethods = (req, query, state) => {
@@ -117,6 +125,21 @@ const createRequestMethods = (req, query, state) => {
             const contentType = this.getHeader('content-type');
             return typeof contentType === 'string' && contentType.includes('application/json');
         },
+        file(fieldName, options) {
+            const handler = FileUpload.createHandler(this);
+            return handler.file(fieldName, options);
+        },
+        files(fieldName, options) {
+            const handler = FileUpload.createHandler(this);
+            return handler.files(fieldName, options);
+        },
+        hasFile(fieldName) {
+            const handler = FileUpload.createHandler(this);
+            return handler.hasFile(fieldName);
+        },
+        fileUpload() {
+            return FileUpload.createHandler(this);
+        },
         getRaw() {
             return req;
         },

package/src/http/RequestContext.d.ts

@@ -1,6 +1,9 @@
 import type { IRequest } from './Request';
 export interface IRequestContext {
     requestId: string;
+    traceId?: string;
+    userId?: string;
+    tenantId?: string;
     startTime: number;
     method: string;
     path: string;
@@ -15,6 +18,9 @@ export declare const RequestContext: Readonly<{
     attach(req: IRequest, context: IRequestContext): void;
     get(req: IRequest): IRequestContext | undefined;
     enrich(context: IRequestContext, status: number): IRequestContext;
+    setUserId(req: IRequest, userId: string | undefined): void;
+    setTenantId(req: IRequest, tenantId: string | undefined): void;
+    setTraceId(req: IRequest, traceId: string | undefined): void;
 }>;
 export default RequestContext;
 //# sourceMappingURL=RequestContext.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"RequestContext.d.ts","sourceRoot":"","sources":["../../../src/http/RequestContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA6CD,eAAO,MAAM,cAAc;QACf,CAAC,WAAW,eAAe,YAAY,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;eAKpD,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;gBAKzC,QAAQ,GAAG,eAAe;gBAoB1B,QAAQ,WAAW,eAAe,GAAG,IAAI;aAM5C,QAAQ,GAAG,eAAe,GAAG,SAAS;oBAM/B,eAAe,UAAU,MAAM,GAAG,eAAe;EAQjE,CAAC;AAEH,eAAe,cAAc,CAAC"}
+{"version":3,"file":"RequestContext.d.ts","sourceRoot":"","sources":["../../../src/http/RequestContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAgGD,eAAO,MAAM,cAAc;QACf,CAAC,WAAW,eAAe,YAAY,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;eAKpD,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;gBAKzC,QAAQ,GAAG,eAAe;gBAmC1B,QAAQ,WAAW,eAAe,GAAG,IAAI;aAS5C,QAAQ,GAAG,eAAe,GAAG,SAAS;oBAM/B,eAAe,UAAU,MAAM,GAAG,eAAe;mBASlD,QAAQ,UAAU,MAAM,GAAG,SAAS,GAAG,IAAI;qBAIzC,QAAQ,YAAY,MAAM,GAAG,SAAS,GAAG,IAAI;oBAI9C,QAAQ,WAAW,MAAM,GAAG,SAAS,GAAG,IAAI;EAG5D,CAAC;AAEH,eAAe,cAAc,CAAC"}

package/src/http/RequestContext.js

@@ -1,4 +1,4 @@
-import { generateUuid } from '../common/uuid.js';
+import { generateUuid } from '../common/utility.js';
 const createFallbackStorage = () => {
     let store;
     return {
@@ -30,6 +30,52 @@ const getHeaderString = (req, name) => {
     const value = req.getHeader(name);
     return typeof value === 'string' ? value : undefined;
 };
+const extractTraceIdFromTraceparent = (traceparent) => {
+    if (typeof traceparent !== 'string')
+        return undefined;
+    const trimmed = traceparent.trim();
+    if (trimmed === '')
+        return undefined;
+    // W3C traceparent: version-traceid-spanid-flags
+    // Example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+    const parts = trimmed.split('-');
+    if (parts.length !== 4)
+        return undefined;
+    const traceId = parts[1] ?? '';
+    if (/^[0-9a-f]{32}$/i.test(traceId) === false)
+        return undefined;
+    // Disallow all-zero traceId
+    if (/^0{32}$/i.test(traceId))
+        return undefined;
+    return traceId.toLowerCase();
+};
+const getTraceIdFromMicroserviceTraceContext = (req) => {
+    const anyReq = req;
+    const trace = anyReq.context?.['trace'];
+    if (typeof trace !== 'object' || trace === null)
+        return undefined;
+    const traceId = trace.traceId;
+    return typeof traceId === 'string' && traceId.trim() !== '' ? traceId : undefined;
+};
+const getOptionalContextString = (req, key) => {
+    const anyReq = req;
+    const value = anyReq.context?.[key];
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number')
+        return String(value);
+    return undefined;
+};
+const setContextField = (req, field, value) => {
+    req.context ??= {};
+    if (typeof value === 'string' && value.trim() !== '') {
+        req.context[field] = value;
+    }
+    const ctx = RequestContext.get(req);
+    if (ctx) {
+        ctx[field] = value;
+    }
+};
 const STORAGE_PROMISE = resolveStorage();
 export const RequestContext = Object.freeze({
     async run(context, callback) {
@@ -44,14 +90,29 @@ export const RequestContext = Object.freeze({
         req.context ??= {};
         const requestIdFromHeader = getHeaderString(req, 'x-request-id');
         const requestId = requestIdFromHeader ?? generateUuid();
+        const traceId = extractTraceIdFromTraceparent(getHeaderString(req, 'traceparent')) ??
+            getHeaderString(req, 'x-trace-id') ??
+            getTraceIdFromMicroserviceTraceContext(req) ??
+            getOptionalContextString(req, 'traceId');
+        const userId = getOptionalContextString(req, 'userId');
+        const tenantId = getOptionalContextString(req, 'tenantId');
         const ctx = {
             requestId,
+            traceId,
+            userId,
+            tenantId,
             startTime: Date.now(),
             method: req.getMethod(),
             path: req.getPath(),
             userAgent: getHeaderString(req, 'user-agent'),
         };
         req.context['requestId'] = requestId;
+        if (traceId !== undefined)
+            req.context['traceId'] = traceId;
+        if (userId !== undefined)
+            req.context['userId'] = userId;
+        if (tenantId !== undefined)
+            req.context['tenantId'] = tenantId;
         req.context['requestContext'] = ctx;
         return ctx;
     },
@@ -59,6 +120,12 @@ export const RequestContext = Object.freeze({
         req.context ??= {};
         req.context['requestContext'] = context;
         req.context['requestId'] = context.requestId;
+        if (context.traceId !== undefined)
+            req.context['traceId'] = context.traceId;
+        if (context.userId !== undefined)
+            req.context['userId'] = context.userId;
+        if (context.tenantId !== undefined)
+            req.context['tenantId'] = context.tenantId;
     },
     get(req) {
         const anyReq = req;
@@ -73,5 +140,14 @@ export const RequestContext = Object.freeze({
             duration,
         };
     },
+    setUserId(req, userId) {
+        setContextField(req, 'userId', userId);
+    },
+    setTenantId(req, tenantId) {
+        setContextField(req, 'tenantId', tenantId);
+    },
+    setTraceId(req, traceId) {
+        setContextField(req, 'traceId', traceId);
+    },
 });
 export default RequestContext;

package/src/http/Response.d.ts

@@ -2,7 +2,7 @@
  * Response - HTTP Response wrapper
  * Wraps Node.js ServerResponse with additional utilities
  */
-import * as http from '../node-singletons/http';
+import type * as http from '../node-singletons/http';
 export interface IResponse {
     status(code: number): IResponse;
     setStatus(code: number): IResponse;