@zintrust/core 0.1.19 → 0.1.21

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;

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

@@ -1 +1 @@
-{"version":3,"file":"Response.d.ts","sourceRoot":"","sources":["../../../src/http/Response.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAE9C,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,SAAS,IAAI,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IAC7D,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IACvD,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjD,MAAM,IAAI,IAAI,CAAC,cAAc,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ;IACnB;;OAEG;gBACS,IAAI,CAAC,cAAc,GAAG,SAAS;EA0D3C,CAAC;AAEH,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"Response.d.ts","sourceRoot":"","sources":["../../../src/http/Response.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAEnD,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,SAAS,IAAI,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IAC7D,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IACvD,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjD,MAAM,IAAI,IAAI,CAAC,cAAc,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ;IACnB;;OAEG;gBACS,IAAI,CAAC,cAAc,GAAG,SAAS;EA0D3C,CAAC;AAEH,eAAe,QAAQ,CAAC"}

package/src/http/ValidationHelper.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Validation Helper
+ * Utilities for working with validated request data
+ */
+import type { IRequest } from './Request';
+/**
+ * Extract validated body from request
+ * Returns the validated body if present, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const body = getValidatedBody(req);
+ * if (!body) {
+ *   Logger.error('Validation middleware not configured');
+ *   return res.setStatus(500).json({ error: 'Internal server error' });
+ * }
+ * const email = getString(body['email']);
+ * ```
+ */
+export declare function getValidatedBody<T = Record<string, unknown>>(req: IRequest): T | undefined;
+/**
+ * Check if request has a validated body
+ * Type guard for validated body existence
+ *
+ * @example
+ * ```typescript
+ * if (!hasValidatedBody(req)) {
+ *   Logger.error('Validation middleware not configured');
+ *   return res.setStatus(500).json({ error: 'Internal server error' });
+ * }
+ * const body = getValidatedBody(req)!; // Safe to use non-null assertion
+ * ```
+ */
+export declare function hasValidatedBody(req: IRequest): boolean;
+/**
+ * Extract validated body or throw error
+ * Throws if validation middleware is not properly configured
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const body = requireValidatedBody(req);
+ *   const email = getString(body['email']);
+ * } catch (error) {
+ *   Logger.error('Validation middleware error', error);
+ *   return res.setStatus(500).json({ error: 'Internal server error' });
+ * }
+ * ```
+ */
+export declare function requireValidatedBody<T = Record<string, unknown>>(req: IRequest): T;
+/**
+ * Extract validated query parameters from request
+ * Returns the validated query if present, undefined otherwise
+ */
+export declare function getValidatedQuery<T = Record<string, unknown>>(req: IRequest): T | undefined;
+/**
+ * Extract validated route parameters from request
+ * Returns the validated params if present, undefined otherwise
+ */
+export declare function getValidatedParams<T = Record<string, unknown>>(req: IRequest): T | undefined;
+/**
+ * Extract validated headers from request
+ * Returns the validated headers if present, undefined otherwise
+ */
+export declare function getValidatedHeaders<T = Record<string, unknown>>(req: IRequest): T | undefined;
+/**
+ * Validation Helper - Sealed namespace
+ */
+export declare const ValidationHelper: Readonly<{
+    getValidatedBody: typeof getValidatedBody;
+    hasValidatedBody: typeof hasValidatedBody;
+    requireValidatedBody: typeof requireValidatedBody;
+    getValidatedQuery: typeof getValidatedQuery;
+    getValidatedParams: typeof getValidatedParams;
+    getValidatedHeaders: typeof getValidatedHeaders;
+}>;
+export default ValidationHelper;
+//# sourceMappingURL=ValidationHelper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ValidationHelper.d.ts","sourceRoot":"","sources":["../../../src/http/ValidationHelper.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAa9C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,GAAG,SAAS,CAK1F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAKvD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,CAQlF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,GAAG,SAAS,CAK3F;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,GAAG,SAAS,CAK5F;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,GAAG,SAAS,CAK7F;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;EAO3B,CAAC;AAEH,eAAe,gBAAgB,CAAC"}