@zintrust/core 3.5.1 → 3.5.2

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/HttpStatus.d.ts

@@ -0,0 +1,12 @@
+export declare const formatHttpStatus: (status: number) => string;
+type HttpRequestLogParams = {
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+    requestId?: string;
+    traceId?: string;
+};
+export declare const formatHttpRequestLog: (params: HttpRequestLogParams) => string;
+export default formatHttpStatus;
+//# sourceMappingURL=HttpStatus.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HttpStatus.d.ts","sourceRoot":"","sources":["../../../src/http/HttpStatus.ts"],"names":[],"mappings":"AAiEA,eAAO,MAAM,gBAAgB,GAAI,QAAQ,MAAM,KAAG,MAGjD,CAAC;AAEF,KAAK,oBAAoB,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,QAAQ,oBAAoB,KAAG,MAanE,CAAC;AAEF,eAAe,gBAAgB,CAAC"}

package/src/http/HttpStatus.js

@@ -0,0 +1,80 @@
+const HTTP_STATUS_TEXT = Object.freeze({
+    100: 'Continue',
+    101: 'Switching Protocols',
+    102: 'Processing',
+    103: 'Early Hints',
+    200: 'OK',
+    201: 'Created',
+    202: 'Accepted',
+    203: 'Non-Authoritative Information',
+    204: 'No Content',
+    205: 'Reset Content',
+    206: 'Partial Content',
+    207: 'Multi-Status',
+    208: 'Already Reported',
+    226: 'IM Used',
+    300: 'Multiple Choices',
+    301: 'Moved Permanently',
+    302: 'Found',
+    303: 'See Other',
+    304: 'Not Modified',
+    305: 'Use Proxy',
+    307: 'Temporary Redirect',
+    308: 'Permanent Redirect',
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    402: 'Payment Required',
+    403: 'Forbidden',
+    404: 'Not Found',
+    405: 'Method Not Allowed',
+    406: 'Not Acceptable',
+    407: 'Proxy Authentication Required',
+    408: 'Request Timeout',
+    409: 'Conflict',
+    410: 'Gone',
+    411: 'Length Required',
+    412: 'Precondition Failed',
+    413: 'Payload Too Large',
+    414: 'URI Too Long',
+    415: 'Unsupported Media Type',
+    416: 'Range Not Satisfiable',
+    417: 'Expectation Failed',
+    418: "I'm a teapot",
+    421: 'Misdirected Request',
+    422: 'Unprocessable Entity',
+    423: 'Locked',
+    424: 'Failed Dependency',
+    425: 'Too Early',
+    426: 'Upgrade Required',
+    428: 'Precondition Required',
+    429: 'Too Many Requests',
+    431: 'Request Header Fields Too Large',
+    451: 'Unavailable For Legal Reasons',
+    500: 'Internal Server Error',
+    501: 'Not Implemented',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+    504: 'Gateway Timeout',
+    505: 'HTTP Version Not Supported',
+    506: 'Variant Also Negotiates',
+    507: 'Insufficient Storage',
+    508: 'Loop Detected',
+    510: 'Not Extended',
+    511: 'Network Authentication Required',
+});
+export const formatHttpStatus = (status) => {
+    const statusText = HTTP_STATUS_TEXT[String(status)];
+    return typeof statusText === 'string' ? `${status} ${statusText}` : String(status);
+};
+export const formatHttpRequestLog = (params) => {
+    const base = `[${params.method}] ${params.path} ${formatHttpStatus(params.status)} (${params.durationMs}ms)`;
+    const meta = [];
+    if (typeof params.requestId === 'string' && params.requestId.trim() !== '') {
+        meta.push(`requestId=${params.requestId}`);
+    }
+    if (typeof params.traceId === 'string' && params.traceId.trim() !== '') {
+        meta.push(`trace=${params.traceId}`);
+    }
+    return meta.length > 0 ? `${base} [${meta.join(' ')}]` : base;
+};
+export default formatHttpStatus;

package/src/http/Kernel.d.ts

@@ -0,0 +1,29 @@
+/**
+ * HTTP Kernel - Request handling and middleware pipeline
+ */
+import type { IServiceContainer } from '../container/ServiceContainer.js';
+import type { IRouter } from '../routes/Router.js';
+import type { IRequest } from './Request.js';
+import type { IResponse } from './Response.js';
+import type { IMiddlewareStack, Middleware } from '../middleware/MiddlewareStack.js';
+import type { IncomingMessage, ServerResponse } from '../node-singletons/http.js';
+import type { ISchedule } from '../scheduler/types.js';
+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,EAAc,MAAM,qBAAqB,CAAC;AAE/D,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;AAgBpE,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;AA8ZD,eAAO,MAAM,MAAM;qBAvEK,OAAO,aAAa,iBAAiB,KAAG,OAAO;EAyErE,CAAC;AAEH,eAAe,MAAM,CAAC"}

package/src/http/Kernel.js

@@ -0,0 +1,329 @@
+/**
+ * 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 getRouteMiddlewareNames = (route) => {
+    const routeAny = route;
+    return Array.isArray(routeAny.middleware)
+        ? routeAny.middleware.filter((m) => typeof m === 'string')
+        : [];
+};
+const getTraceMiddlewareEmitter = () => {
+    const globalState = globalThis;
+    return typeof globalState.__zintrust_trace_middleware_emit__ === 'function'
+        ? globalState.__zintrust_trace_middleware_emit__
+        : undefined;
+};
+const PREFLIGHT_FALLBACK_METHODS = Object.freeze([
+    'GET',
+    'HEAD',
+    'POST',
+    'PUT',
+    'PATCH',
+    'DELETE',
+    '*',
+]);
+const resolveRouteWithPreflightFallback = (router, method, path) => {
+    const direct = Router.match(router, method, path);
+    if (direct !== null || method !== 'OPTIONS')
+        return direct;
+    for (const fallbackMethod of PREFLIGHT_FALLBACK_METHODS) {
+        const matched = Router.match(router, fallbackMethod, path);
+        if (matched === null)
+            continue;
+        return {
+            ...matched,
+            handler: async () => {
+                await Promise.resolve();
+            },
+        };
+    }
+    return null;
+};
+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 runMiddlewareChain = async (middleware, req, res, terminal) => {
+    let index = 0;
+    const next = async () => {
+        if (index < middleware.length) {
+            const mw = middleware[index++];
+            await mw(req, res, next);
+            return;
+        }
+        await terminal();
+    };
+    await next();
+};
+// 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 coerceRouteParams = (params) => {
+    const safeParams = {};
+    if (typeof params !== 'object' || params === null)
+        return safeParams;
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === null)
+            continue;
+        safeParams[k] = typeof v === 'string' ? v : String(v);
+    }
+    return safeParams;
+};
+const resolveWrappedRouteMiddleware = (routeMiddlewareNames, routeMiddleware) => {
+    const traceMiddlewareEmitter = getTraceMiddlewareEmitter();
+    return routeMiddlewareNames
+        .map((name) => ({ name, middleware: routeMiddleware[name] }))
+        .filter((entry) => typeof entry.middleware === 'function')
+        .map(({ name, middleware }) => {
+        if (traceMiddlewareEmitter === undefined)
+            return middleware;
+        const wrapped = async (request, response, next) => {
+            const start = Date.now();
+            traceMiddlewareEmitter(name, 'before');
+            try {
+                await middleware(request, response, next);
+            }
+            finally {
+                traceMiddlewareEmitter(name, 'after', Date.now() - start);
+            }
+        };
+        return wrapped;
+    });
+};
+const runNotFoundPipeline = async (globalMiddleware, req, res, context, traceSpan) => {
+    // Run global middleware (including HttpWatcher) so routing 404s are still observed.
+    // Route middleware is intentionally skipped — there is no matched route.
+    const routeLabel = 'not_found';
+    maybeSetKernelTraceRoute(traceSpan, context.method, routeLabel);
+    req.context['traceRouteMiddleware'] = [];
+    const handleNotFound = ErrorRouting.handleNotFound;
+    await runMiddlewareChain(globalMiddleware, req, res, async () => {
+        await handleNotFound(req, res, context.requestId);
+    });
+    return routeLabel;
+};
+const runKernelPipeline = async (router, globalMiddleware, routeMiddleware, req, res, context, traceSpan) => {
+    const route = resolveRouteWithPreflightFallback(router, req.getMethod(), req.getPath());
+    if (route === null) {
+        return runNotFoundPipeline(globalMiddleware, req, res, context, traceSpan);
+    }
+    const matchedRoute = route;
+    const routeLabel = hasNonEmptyRoutePath(matchedRoute) ? matchedRoute.routePath : req.getPath();
+    maybeSetKernelTraceRoute(traceSpan, context.method, routeLabel);
+    req.setParams(coerceRouteParams(matchedRoute.params));
+    const routeMiddlewareNames = getRouteMiddlewareNames(matchedRoute);
+    req.context['traceRouteMiddleware'] = routeMiddlewareNames;
+    const middlewareToRun = [
+        ...globalMiddleware,
+        ...resolveWrappedRouteMiddleware(routeMiddlewareNames, routeMiddleware),
+    ];
+    await runMiddlewareChain(middlewareToRun, req, res, async () => {
+        await matchedRoute.handler(req, res);
+    });
+    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();
+    const globalMiddlewareRegistrarState = globalThis;
+    // 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);
+    if (Array.isArray(globalMiddlewareRegistrarState.__zintrust_pending_global_middlewares__)) {
+        globalMiddleware.push(...globalMiddlewareRegistrarState.__zintrust_pending_global_middlewares__);
+        globalMiddlewareRegistrarState.__zintrust_pending_global_middlewares__ = [];
+    }
+    globalMiddlewareRegistrarState.__zintrust_register_global_middleware__ = (...middleware) => {
+        globalMiddleware.push(...middleware);
+    };
+    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,65 @@
+/**
+ * Request - HTTP Request wrapper
+ * Wraps Node.js IncomingMessage with additional utilities
+ */
+import type { FileUploadOptions, IFileUploadHandler, UploadedFile } from './FileUpload.js';
+import type * as http from '../node-singletons/http.js';
+import type { JwtPayload } from '../security/JwtManager.js';
+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;
+    header(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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"}