vector-framework 1.2.1 → 1.2.3

package/dist/core/router.js

@@ -1,7 +1,12 @@
 import { APIError, createResponse } from '../http';
 import { STATIC_RESPONSES } from '../constants';
+import { AuthKind } from '../types';
 import { buildRouteRegex } from '../utils/path';
 import { createValidationErrorPayload, extractThrownIssues, isStandardRouteSchema, normalizeValidationIssues, runStandardValidation, } from '../utils/schema-validation';
+const AUTH_KIND_VALUES = new Set(Object.values(AuthKind));
+function isAuthKindValue(value) {
+    return typeof value === 'string' && AUTH_KIND_VALUES.has(value);
+}
 export class VectorRouter {
     middlewareManager;
     authManager;
@@ -13,6 +18,7 @@ export class VectorRouter {
     routeMatchers = [];
     corsHeadersEntries = null;
     corsHandler = null;
+    checkpointGateway = null;
     constructor(middlewareManager, authManager, cacheManager) {
         this.middlewareManager = middlewareManager;
         this.authManager = authManager;
@@ -24,6 +30,9 @@ export class VectorRouter {
     setCorsHandler(handler) {
         this.corsHandler = handler;
     }
+    setCheckpointGateway(gateway) {
+        this.checkpointGateway = gateway;
+    }
     setRouteBooleanDefaults(defaults) {
         this.routeBooleanDefaults = { ...defaults };
     }
@@ -39,6 +48,11 @@ export class VectorRouter {
                 resolved[key] = defaults[key];
             }
         }
+        // If a route explicitly sets auth:true and the global default auth is an AuthKind,
+        // promote the route to that kind so OpenAPI docs and runtime defaults stay aligned.
+        if (resolved.auth === true && isAuthKindValue(defaults.auth)) {
+            resolved.auth = defaults.auth;
+        }
         return resolved;
     }
     route(options, handler) {
@@ -119,243 +133,301 @@ export class VectorRouter {
         catch {
             return APIError.badRequest('Malformed request URL');
         }
-        request._parsedUrl = url;
         const pathname = url.pathname;
+        // Fast path: exact route lookup avoids scanning regex matchers for common static/method routes.
+        const exactPathRoute = this.routeTable[pathname];
+        if (exactPathRoute) {
+            if (exactPathRoute instanceof Response) {
+                // Route table stores a shared Response instance for static routes; clone per request.
+                return this.applyCorsResponse(exactPathRoute.clone(), request);
+            }
+            const exactPathMethodMap = exactPathRoute;
+            const handler = exactPathMethodMap[request.method] ?? (request.method === 'HEAD' ? exactPathMethodMap['GET'] : undefined);
+            if (handler) {
+                const response = await handler(request);
+                if (response) {
+                    return response;
+                }
+            }
+        }
         for (const matcher of this.routeMatchers) {
             const path = matcher.path;
-            const value = this.routeTable[path];
-            if (!value)
+            const routeEntry = this.routeTable[path];
+            if (!routeEntry)
                 continue;
-            if (value instanceof Response)
-                continue;
-            const methodMap = value;
-            if (request.method === 'OPTIONS' || request.method in methodMap) {
-                const match = pathname.match(matcher.regex);
-                if (match) {
-                    try {
-                        request.params = match.groups ?? {};
-                    }
-                    catch {
-                        // Request.params can be readonly on Bun-native requests.
-                    }
-                    const handler = methodMap[request.method] ?? methodMap['GET'];
-                    if (handler) {
-                        const response = await handler(request);
-                        if (response)
-                            return response;
-                    }
+            if (routeEntry instanceof Response) {
+                if (pathname === path) {
+                    // Same reason as exact-path static route handling above.
+                    return this.applyCorsResponse(routeEntry.clone(), request);
                 }
+                continue;
             }
-        }
-        return STATIC_RESPONSES.NOT_FOUND.clone();
-    }
-    prepareRequest(request, options) {
-        if (!request.context) {
-            request.context = {};
-        }
-        const hasEmptyParamsObject = !!request.params &&
-            typeof request.params === 'object' &&
-            !Array.isArray(request.params) &&
-            Object.keys(request.params).length === 0;
-        if (options?.params !== undefined && (request.params === undefined || hasEmptyParamsObject)) {
-            try {
-                request.params = options.params;
+            const methodMap = routeEntry;
+            const handler = methodMap[request.method] ?? (request.method === 'HEAD' ? methodMap['GET'] : undefined);
+            if (!handler) {
+                continue;
             }
-            catch {
-                // params is readonly (set by Bun natively) — use as-is
+            const match = pathname.match(matcher.regex);
+            if (!match) {
+                continue;
             }
+            const response = await handler(request);
+            if (response)
+                return response;
         }
-        if (options?.route !== undefined) {
-            request.route = options.route;
+        // STATIC_RESPONSES are shared singletons; clone before per-request header mutation.
+        return this.applyCorsResponse(STATIC_RESPONSES.NOT_FOUND.clone(), request);
+    }
+    cloneMetadata(value) {
+        if (Array.isArray(value)) {
+            return [...value];
         }
-        if (options?.metadata !== undefined) {
-            request.metadata = options.metadata;
+        if (value && typeof value === 'object') {
+            return { ...value };
         }
-        if (request.query == null && request.url) {
-            try {
-                Object.defineProperty(request, 'query', {
-                    get() {
-                        const url = this._parsedUrl ?? new URL(this.url);
-                        const query = VectorRouter.parseQuery(url);
-                        Object.defineProperty(this, 'query', {
-                            value: query,
-                            writable: true,
-                            configurable: true,
-                            enumerable: true,
-                        });
-                        return query;
-                    },
-                    set(value) {
-                        Object.defineProperty(this, 'query', {
-                            value,
-                            writable: true,
-                            configurable: true,
-                            enumerable: true,
-                        });
-                    },
-                    configurable: true,
-                    enumerable: true,
-                });
+        return value;
+    }
+    createContext(request, options) {
+        const context = {
+            request,
+        };
+        this.setContextField(context, 'metadata', options?.metadata !== undefined ? this.cloneMetadata(options.metadata) : {});
+        this.setContextField(context, 'params', options?.params ?? {});
+        this.setContextField(context, 'query', options?.query ?? {});
+        this.setContextField(context, 'cookies', options?.cookies ?? {});
+        return context;
+    }
+    setContextField(context, key, value) {
+        context[key] = value;
+    }
+    hasOwnContextField(context, key) {
+        return Object.prototype.hasOwnProperty.call(context, key);
+    }
+    buildCheckpointContextPayload(context) {
+        const payload = {};
+        const allowedKeys = ['metadata', 'content', 'validatedInput', 'authUser'];
+        for (const key of allowedKeys) {
+            if (!this.hasOwnContextField(context, key)) {
+                continue;
             }
-            catch {
-                const url = request._parsedUrl ?? new URL(request.url);
-                try {
-                    request.query = VectorRouter.parseQuery(url);
-                }
-                catch {
-                    // Leave query as-is when request shape is non-extensible.
-                }
+            const value = context[key];
+            if (typeof value === 'function' || typeof value === 'symbol' || value === undefined) {
+                continue;
             }
+            payload[key] = value;
         }
-        if (!Object.getOwnPropertyDescriptor(request, 'cookies')) {
-            Object.defineProperty(request, 'cookies', {
-                get() {
-                    const cookieHeader = this.headers.get('cookie') ?? '';
-                    const cookies = {};
-                    if (cookieHeader) {
-                        for (const pair of cookieHeader.split(';')) {
-                            const idx = pair.indexOf('=');
-                            if (idx > 0) {
-                                cookies[pair.slice(0, idx).trim()] = pair.slice(idx + 1).trim();
-                            }
-                        }
-                    }
-                    Object.defineProperty(this, 'cookies', {
-                        value: cookies,
-                        writable: true,
-                        configurable: true,
-                        enumerable: true,
-                    });
-                    return cookies;
-                },
-                configurable: true,
-                enumerable: true,
-            });
-        }
+        return payload;
     }
-    resolveFallbackParams(request, routeMatcher) {
+    resolveFallbackParams(pathname, routeMatcher) {
         if (!routeMatcher) {
             return undefined;
         }
-        const currentParams = request.params;
-        if (currentParams &&
-            typeof currentParams === 'object' &&
-            !Array.isArray(currentParams) &&
-            Object.keys(currentParams).length > 0) {
+        const matched = pathname.match(routeMatcher);
+        if (!matched?.groups) {
             return undefined;
         }
-        let pathname;
+        return matched.groups;
+    }
+    getRequestedCheckpointVersion(request) {
+        if (!this.checkpointGateway) {
+            return null;
+        }
+        const gateway = this.checkpointGateway;
+        if (gateway?.getRequestedVersion) {
+            return gateway.getRequestedVersion(request);
+        }
+        const primary = request.headers.get('x-vector-checkpoint-version');
+        if (primary && primary.trim().length > 0) {
+            return primary.trim();
+        }
+        const fallback = request.headers.get('x-vector-checkpoint');
+        if (fallback && fallback.trim().length > 0) {
+            return fallback.trim();
+        }
+        return null;
+    }
+    getCheckpointCacheKeyOverrideValue(request) {
+        if (!this.checkpointGateway) {
+            return null;
+        }
+        const gateway = this.checkpointGateway;
+        if (gateway?.getCacheKeyOverrideValue) {
+            return gateway.getCacheKeyOverrideValue(request);
+        }
+        const primary = request.headers.get('x-vector-checkpoint-version');
+        if (primary && primary.trim().length > 0) {
+            return `x-vector-checkpoint-version:${primary.trim()}`;
+        }
+        const fallback = request.headers.get('x-vector-checkpoint');
+        if (fallback && fallback.trim().length > 0) {
+            return `x-vector-checkpoint:${fallback.trim()}`;
+        }
+        return null;
+    }
+    applyCheckpointCacheNamespace(cacheKey, request) {
+        const checkpointVersion = this.getRequestedCheckpointVersion(request);
+        if (!checkpointVersion) {
+            return cacheKey;
+        }
+        return `${cacheKey}:checkpoint=${checkpointVersion}`;
+    }
+    applyCheckpointRouteKeyOverride(cacheKey, request) {
+        const override = this.getCheckpointCacheKeyOverrideValue(request);
+        if (!override) {
+            return cacheKey;
+        }
+        return override;
+    }
+    async parseRequestBodyForContext(context, request, checkpointRequested) {
+        let parsedContent = null;
         try {
-            pathname = (request._parsedUrl ?? new URL(request.url)).pathname;
+            // For checkpoint requests we may forward the original stream later, so parse from a clone.
+            const bodyReadRequest = checkpointRequested ? request.clone() : request;
+            const contentType = bodyReadRequest.headers.get('content-type');
+            if (contentType?.startsWith('application/json')) {
+                parsedContent = await bodyReadRequest.json();
+            }
+            else if (contentType?.startsWith('application/x-www-form-urlencoded')) {
+                parsedContent = Object.fromEntries(await bodyReadRequest.formData());
+            }
+            else if (contentType?.startsWith('multipart/form-data')) {
+                parsedContent = await bodyReadRequest.formData();
+            }
+            else {
+                parsedContent = await bodyReadRequest.text();
+            }
         }
         catch {
-            return undefined;
+            parsedContent = null;
         }
-        const matched = pathname.match(routeMatcher);
-        if (!matched?.groups) {
-            return undefined;
+        this.setContextField(context, 'content', parsedContent);
+    }
+    isLikelyStreamingBodyRequest(request) {
+        if (request.method === 'GET' || request.method === 'HEAD') {
+            return false;
         }
-        return matched.groups;
+        if (!request.body) {
+            return false;
+        }
+        if (request.duplex === 'half') {
+            return true;
+        }
+        const transferEncoding = request.headers.get('transfer-encoding');
+        if (transferEncoding) {
+            const hasChunked = transferEncoding.split(',').some((value) => value.trim().toLowerCase() === 'chunked');
+            if (hasChunked) {
+                return true;
+            }
+        }
+        return false;
     }
     wrapHandler(options, handler) {
         const routePath = options.path;
         const routeMatcher = routePath.includes(':') ? buildRouteRegex(routePath) : null;
         return async (request) => {
             const vectorRequest = request;
-            const fallbackParams = this.resolveFallbackParams(request, routeMatcher);
-            this.prepareRequest(vectorRequest, {
-                params: fallbackParams,
-                route: routePath,
+            let pathname = '';
+            try {
+                pathname = new URL(request.url).pathname;
+            }
+            catch {
+                // Ignore malformed URLs here; router.handle() already guards route matching.
+            }
+            const fallbackParams = this.resolveFallbackParams(pathname, routeMatcher);
+            const context = this.createContext(vectorRequest, {
                 metadata: options.metadata,
+                params: this.getRequestParams(request, fallbackParams),
+                query: this.getRequestQuery(request),
+                cookies: this.getRequestCookies(request),
             });
             try {
                 if (options.expose === false) {
                     return APIError.forbidden('Forbidden');
                 }
-                const beforeResult = await this.middlewareManager.executeBefore(vectorRequest);
-                if (beforeResult instanceof Response) {
-                    return beforeResult;
+                const beforeResponse = await this.middlewareManager.executeBefore(context);
+                if (beforeResponse instanceof Response) {
+                    return beforeResponse;
                 }
-                const req = beforeResult;
                 if (options.auth) {
                     try {
-                        await this.authManager.authenticate(req);
+                        await this.authManager.authenticate(context);
                     }
                     catch (error) {
                         return APIError.unauthorized(error instanceof Error ? error.message : 'Authentication failed', options.responseContentType);
                     }
                 }
-                if (!options.rawRequest && req.method !== 'GET' && req.method !== 'HEAD') {
-                    let parsedContent = null;
-                    try {
-                        const contentType = req.headers.get('content-type');
-                        if (contentType?.startsWith('application/json')) {
-                            parsedContent = await req.json();
-                        }
-                        else if (contentType?.startsWith('application/x-www-form-urlencoded')) {
-                            parsedContent = Object.fromEntries(await req.formData());
+                const executeRoute = async () => {
+                    const req = context.request;
+                    const requestForRoute = req;
+                    const checkpointRequested = this.getRequestedCheckpointVersion(requestForRoute) !== null;
+                    // Library-wide behavior: applies to any streaming request with input schema validation enabled,
+                    // regardless of whether checkpoint routing is in play.
+                    const shouldDeferStreamingValidation = this.isLikelyStreamingBodyRequest(requestForRoute) &&
+                        options.schema?.input !== undefined &&
+                        options.validate !== false;
+                    if (!options.rawRequest && req.method !== 'GET' && req.method !== 'HEAD' && !shouldDeferStreamingValidation) {
+                        await this.parseRequestBodyForContext(context, requestForRoute, checkpointRequested);
+                    }
+                    if (shouldDeferStreamingValidation) {
+                        const validationWithoutBody = await this.validateInputSchema(context, options, fallbackParams, {
+                            includeBody: false,
+                            allowBodyDeferral: true,
+                        });
+                        if (validationWithoutBody.response) {
+                            return validationWithoutBody.response;
                         }
-                        else if (contentType?.startsWith('multipart/form-data')) {
-                            parsedContent = await req.formData();
+                        if (validationWithoutBody.requiresBody) {
+                            if (!options.rawRequest && req.method !== 'GET' && req.method !== 'HEAD') {
+                                await this.parseRequestBodyForContext(context, requestForRoute, checkpointRequested);
+                            }
+                            const fullValidation = await this.validateInputSchema(context, options, fallbackParams);
+                            if (fullValidation.response) {
+                                return fullValidation.response;
+                            }
                         }
-                        else {
-                            parsedContent = await req.text();
+                    }
+                    else {
+                        const inputValidation = await this.validateInputSchema(context, options, fallbackParams);
+                        if (inputValidation.response) {
+                            return inputValidation.response;
                         }
                     }
-                    catch {
-                        parsedContent = null;
+                    if (this.checkpointGateway) {
+                        const checkpointResponse = await this.checkpointGateway.handle(req, this.buildCheckpointContextPayload(context));
+                        if (checkpointResponse) {
+                            return checkpointResponse;
+                        }
                     }
-                    this.setContentAndBodyAlias(req, parsedContent);
-                }
-                const inputValidationResponse = await this.validateInputSchema(req, options);
-                if (inputValidationResponse) {
-                    return inputValidationResponse;
-                }
+                    return await handler(context);
+                };
                 let result;
                 const cacheOptions = options.cache;
                 if (cacheOptions && typeof cacheOptions === 'number' && cacheOptions > 0) {
-                    const cacheKey = this.cacheManager.generateKey(req, {
-                        authUser: req.authUser,
-                    });
-                    result = await this.cacheManager.get(cacheKey, async () => {
-                        const res = await handler(req);
-                        if (res instanceof Response) {
-                            return {
-                                _isResponse: true,
-                                body: await res.text(),
-                                status: res.status,
-                                headers: Object.fromEntries(res.headers.entries()),
-                            };
-                        }
-                        return res;
-                    }, cacheOptions);
+                    const cacheKey = this.applyCheckpointCacheNamespace(this.cacheManager.generateKey(context.request, {
+                        authUser: context.authUser,
+                    }), context.request);
+                    result = await this.cacheManager.get(cacheKey, async () => await executeRoute(), cacheOptions);
                 }
                 else if (cacheOptions && typeof cacheOptions === 'object' && cacheOptions.ttl) {
-                    const cacheKey = cacheOptions.key ||
-                        this.cacheManager.generateKey(req, {
-                            authUser: req.authUser,
+                    const hasRouteCacheKey = typeof cacheOptions.key === 'string' && cacheOptions.key.length > 0;
+                    let cacheKey;
+                    if (hasRouteCacheKey) {
+                        cacheKey = this.applyCheckpointRouteKeyOverride(cacheOptions.key, context.request);
+                    }
+                    else {
+                        const generatedKey = this.cacheManager.generateKey(context.request, {
+                            authUser: context.authUser,
                         });
-                    result = await this.cacheManager.get(cacheKey, async () => {
-                        const res = await handler(req);
-                        if (res instanceof Response) {
-                            return {
-                                _isResponse: true,
-                                body: await res.text(),
-                                status: res.status,
-                                headers: Object.fromEntries(res.headers.entries()),
-                            };
-                        }
-                        return res;
-                    }, cacheOptions.ttl);
+                        cacheKey = this.applyCheckpointCacheNamespace(generatedKey, context.request);
+                    }
+                    result = await this.cacheManager.get(cacheKey, async () => await executeRoute(), cacheOptions.ttl);
                 }
                 else {
-                    result = await handler(req);
+                    result = await executeRoute();
                 }
-                if (result && typeof result === 'object' && result._isResponse === true) {
-                    result = new Response(result.body, {
-                        status: result.status,
-                        headers: result.headers,
-                    });
+                if (result instanceof Response && !!cacheOptions) {
+                    // Cache layers can return shared Response instances; clone before per-request mutations.
+                    result = result.clone();
                 }
                 let response;
                 if (options.rawResponse || result instanceof Response) {
@@ -364,21 +436,8 @@ export class VectorRouter {
                 else {
                     response = createResponse(200, result, options.responseContentType);
                 }
-                response = await this.middlewareManager.executeFinally(response, req);
-                // Apply pre-built CORS headers if configured
-                const entries = this.corsHeadersEntries;
-                if (entries) {
-                    for (const [k, v] of entries) {
-                        response.headers.set(k, v);
-                    }
-                }
-                else {
-                    const dynamicCors = this.corsHandler;
-                    if (dynamicCors) {
-                        response = dynamicCors(response, req);
-                    }
-                }
-                return response;
+                response = await this.middlewareManager.executeFinally(response, context);
+                return this.applyCorsResponse(response, context.request);
             }
             catch (error) {
                 if (error instanceof Response) {
@@ -396,10 +455,13 @@ export class VectorRouter {
         const nodeEnv = typeof Bun !== 'undefined' ? Bun.env.NODE_ENV : process.env.NODE_ENV;
         return nodeEnv !== 'production';
     }
-    async buildInputValidationPayload(request, options) {
-        let body = request.content;
-        if (options.rawRequest && request.method !== 'GET' && request.method !== 'HEAD') {
+    async buildInputValidationPayload(context, options, fallbackParams, validationOptions) {
+        const request = context.request;
+        const includeBody = validationOptions?.includeBody !== false;
+        let body = includeBody && this.hasOwnContextField(context, 'content') ? context.content : undefined;
+        if (includeBody && options.rawRequest && request.method !== 'GET' && request.method !== 'HEAD') {
             try {
+                // Read raw body from a clone so handlers/checkpoint forwarding can still consume the original stream.
                 body = await request.clone().text();
             }
             catch {
@@ -407,94 +469,154 @@ export class VectorRouter {
             }
         }
         return {
-            params: request.params ?? {},
-            query: request.query ?? {},
+            params: this.getRequestParams(request, fallbackParams),
+            query: this.getRequestQuery(request),
             headers: Object.fromEntries(request.headers.entries()),
-            cookies: request.cookies ?? {},
+            cookies: this.getRequestCookies(request),
             body,
         };
     }
-    applyValidatedInput(request, validatedValue) {
-        request.validatedInput = validatedValue;
-        if (!validatedValue || typeof validatedValue !== 'object') {
-            return;
+    getRequestParams(request, fallbackParams) {
+        const nativeParams = this.readRequestObjectField(request, 'params');
+        if (nativeParams && Object.keys(nativeParams).length > 0) {
+            return nativeParams;
         }
-        const validated = validatedValue;
-        if ('params' in validated) {
-            try {
-                request.params = validated.params;
-            }
-            catch {
-                // Request.params can be readonly on Bun-native requests.
-            }
+        return fallbackParams ?? {};
+    }
+    getRequestQuery(request) {
+        const nativeQuery = this.readRequestObjectField(request, 'query');
+        if (nativeQuery) {
+            return nativeQuery;
         }
-        if ('query' in validated) {
-            try {
-                request.query = validated.query;
-            }
-            catch {
-                // Request.query can be readonly/non-configurable on some request objects.
-            }
+        try {
+            return VectorRouter.parseQuery(new URL(request.url));
         }
-        if ('cookies' in validated) {
-            try {
-                request.cookies = validated.cookies;
-            }
-            catch {
-                // Request.cookies can be readonly/non-configurable on some request objects.
-            }
+        catch {
+            return {};
         }
-        if ('body' in validated) {
-            this.setContentAndBodyAlias(request, validated.body);
+    }
+    getRequestCookies(request) {
+        const nativeCookies = this.readRequestObjectField(request, 'cookies');
+        if (nativeCookies) {
+            return nativeCookies;
         }
+        return VectorRouter.parseCookies(request.headers.get('cookie'));
     }
-    setContentAndBodyAlias(request, value) {
-        try {
-            request.content = value;
+    readRequestObjectField(request, key) {
+        const value = request[key];
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            return undefined;
         }
-        catch {
-            // Request.content can be readonly/non-configurable on some request objects.
-            return;
+        return value;
+    }
+    applyValidatedInput(context, validatedValue) {
+        this.setContextField(context, 'validatedInput', validatedValue);
+    }
+    issueHasBodyPath(issue) {
+        if (!issue || typeof issue !== 'object' || !('path' in issue)) {
+            return false;
         }
-        this.setBodyAlias(request, value);
+        const path = issue.path;
+        if (!Array.isArray(path) || path.length === 0) {
+            return false;
+        }
+        const segment = path[0];
+        if (segment && typeof segment === 'object' && 'key' in segment) {
+            return segment.key === 'body';
+        }
+        return segment === 'body';
     }
-    setBodyAlias(request, value) {
-        try {
-            request.body = value;
+    issueHasExplicitNonBodyPath(issue) {
+        if (!issue || typeof issue !== 'object' || !('path' in issue)) {
+            return false;
         }
-        catch {
-            // Keep request.content as source of truth when body alias is readonly.
+        const path = issue.path;
+        if (!Array.isArray(path) || path.length === 0) {
+            return false;
         }
+        const segment = path[0];
+        if (segment && typeof segment === 'object' && 'key' in segment) {
+            return segment.key !== 'body';
+        }
+        return segment !== 'body';
+    }
+    issueHasUnknownPath(issue) {
+        if (!issue || typeof issue !== 'object' || !('path' in issue)) {
+            return true;
+        }
+        const path = issue.path;
+        if (!Array.isArray(path)) {
+            return true;
+        }
+        return path.length === 0;
+    }
+    shouldDeferBodyValidation(issues, context, validationOptions) {
+        if (!(validationOptions?.allowBodyDeferral === true && validationOptions?.includeBody === false)) {
+            return false;
+        }
+        const request = context.request;
+        const mayHaveRequestBody = request.method !== 'GET' && request.method !== 'HEAD' && request.body !== null;
+        if (!mayHaveRequestBody || issues.length === 0) {
+            return false;
+        }
+        if (issues.some((issue) => this.issueHasBodyPath(issue))) {
+            return true;
+        }
+        // Conservative fallback: if issues do not identify a non-body target and at least one issue
+        // has unknown/empty path, retry once with body included.
+        const hasExplicitNonBodyPath = issues.some((issue) => this.issueHasExplicitNonBodyPath(issue));
+        const hasUnknownPath = issues.some((issue) => this.issueHasUnknownPath(issue));
+        return !hasExplicitNonBodyPath && hasUnknownPath;
     }
-    async validateInputSchema(request, options) {
+    async validateInputSchema(context, options, fallbackParams, validationOptions) {
         const inputSchema = options.schema?.input;
         if (!inputSchema) {
-            return null;
+            return { response: null, requiresBody: false };
         }
         if (options.validate === false) {
-            return null;
+            return { response: null, requiresBody: false };
         }
         if (!isStandardRouteSchema(inputSchema)) {
-            return APIError.internalServerError('Invalid route schema configuration', options.responseContentType);
+            return {
+                response: APIError.internalServerError('Invalid route schema configuration', options.responseContentType),
+                requiresBody: false,
+            };
         }
         const includeRawIssues = this.isDevelopmentMode();
-        const payload = await this.buildInputValidationPayload(request, options);
+        const payload = await this.buildInputValidationPayload(context, options, fallbackParams, {
+            includeBody: validationOptions?.includeBody,
+        });
         try {
             const validation = await runStandardValidation(inputSchema, payload);
             if (validation.success === false) {
+                if (this.shouldDeferBodyValidation(validation.issues, context, validationOptions)) {
+                    return { response: null, requiresBody: true };
+                }
                 const issues = normalizeValidationIssues(validation.issues, includeRawIssues);
-                return createResponse(422, createValidationErrorPayload('input', issues), options.responseContentType);
+                return {
+                    response: createResponse(422, createValidationErrorPayload('input', issues), options.responseContentType),
+                    requiresBody: false,
+                };
             }
-            this.applyValidatedInput(request, validation.value);
-            return null;
+            this.applyValidatedInput(context, validation.value);
+            return { response: null, requiresBody: false };
         }
         catch (error) {
             const thrownIssues = extractThrownIssues(error);
             if (thrownIssues) {
+                if (this.shouldDeferBodyValidation(thrownIssues, context, validationOptions)) {
+                    return { response: null, requiresBody: true };
+                }
                 const issues = normalizeValidationIssues(thrownIssues, includeRawIssues);
-                return createResponse(422, createValidationErrorPayload('input', issues), options.responseContentType);
+                return {
+                    response: createResponse(422, createValidationErrorPayload('input', issues), options.responseContentType),
+                    requiresBody: false,
+                };
             }
-            return APIError.internalServerError(error instanceof Error ? error.message : 'Validation failed', options.responseContentType);
+            return {
+                response: APIError.internalServerError(error instanceof Error ? error.message : 'Validation failed', options.responseContentType),
+                requiresBody: false,
+            };
         }
     }
     getOrCreateMethodMap(path) {
@@ -547,6 +669,19 @@ export class VectorRouter {
         }
         return query;
     }
+    static parseCookies(cookieHeader) {
+        const cookies = {};
+        if (!cookieHeader) {
+            return cookies;
+        }
+        for (const pair of cookieHeader.split(';')) {
+            const idx = pair.indexOf('=');
+            if (idx > 0) {
+                cookies[pair.slice(0, idx).trim()] = pair.slice(idx + 1).trim();
+            }
+        }
+        return cookies;
+    }
     routeSpecificityScore(path) {
         const STATIC_SEGMENT_WEIGHT = 1000;
         const PARAM_SEGMENT_WEIGHT = 10;
@@ -571,5 +706,19 @@ export class VectorRouter {
         }
         return score;
     }
+    applyCorsResponse(response, request) {
+        const entries = this.corsHeadersEntries;
+        if (entries) {
+            for (const [k, v] of entries) {
+                response.headers.set(k, v);
+            }
+            return response;
+        }
+        const dynamicCors = this.corsHandler;
+        if (dynamicCors) {
+            return dynamicCors(response, request);
+        }
+        return response;
+    }
 }
 //# sourceMappingURL=router.js.map