vector-framework 1.2.2 → 1.2.3

package/src/core/router.ts

@@ -3,7 +3,9 @@ import type { CacheManager } from '../cache/manager';
 import { APIError, createResponse } from '../http';
 import type { MiddlewareManager } from '../middleware/manager';
 import { STATIC_RESPONSES } from '../constants';
+import { AuthKind } from '../types';
 import { buildRouteRegex } from '../utils/path';
+import type { CheckpointGateway } from '../checkpoint/gateway';
 import type {
   BunMethodMap,
   BunRouteTable,
@@ -14,6 +16,7 @@ import type {
   RouteHandler,
   RouteOptions,
   RouteSchemaDefinition,
+  VectorContext,
   VectorRequest,
   VectorTypes,
 } from '../types';
@@ -25,6 +28,12 @@ import {
   runStandardValidation,
 } from '../utils/schema-validation';
 
+const AUTH_KIND_VALUES = new Set<string>(Object.values(AuthKind));
+
+function isAuthKindValue(value: unknown): value is AuthKind {
+  return typeof value === 'string' && AUTH_KIND_VALUES.has(value);
+}
+
 export interface RegisteredRouteDefinition<TTypes extends VectorTypes = DefaultVectorTypes> {
   method: string;
   path: string;
@@ -37,6 +46,11 @@ interface RouteMatcher {
   specificity: number;
 }
 
+interface InputValidationResult {
+  response: Response | null;
+  requiresBody: boolean;
+}
+
 export class VectorRouter<TTypes extends VectorTypes = DefaultVectorTypes> {
   private middlewareManager: MiddlewareManager<TTypes>;
   private authManager: AuthManager<TTypes>;
@@ -48,6 +62,7 @@ export class VectorRouter<TTypes extends VectorTypes = DefaultVectorTypes> {
   private routeMatchers: RouteMatcher[] = [];
   private corsHeadersEntries: [string, string][] | null = null;
   private corsHandler: ((response: Response, request: Request) => Response) | null = null;
+  private checkpointGateway: CheckpointGateway | null = null;
 
   constructor(
     middlewareManager: MiddlewareManager<TTypes>,
@@ -67,6 +82,10 @@ export class VectorRouter<TTypes extends VectorTypes = DefaultVectorTypes> {
     this.corsHandler = handler;
   }
 
+  setCheckpointGateway(gateway: CheckpointGateway | null): void {
+    this.checkpointGateway = gateway;
+  }
+
   setRouteBooleanDefaults(defaults?: RouteBooleanDefaults): void {
     this.routeBooleanDefaults = { ...defaults };
   }
@@ -87,6 +106,12 @@ export class VectorRouter<TTypes extends VectorTypes = DefaultVectorTypes> {
       }
     }
 
+    // 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;
   }
 
@@ -181,157 +206,249 @@ export class VectorRouter<TTypes extends VectorTypes = DefaultVectorTypes> {
     } catch {
       return APIError.badRequest('Malformed request URL');
     }
-    (request as any)._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() as unknown as Response, request);
+      }
+
+      const exactPathMethodMap = exactPathRoute as BunMethodMap;
+      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) continue;
-      if (value instanceof Response) continue;
-      const methodMap = value as BunMethodMap;
-      if (request.method === 'OPTIONS' || request.method in methodMap) {
-        const match = pathname.match(matcher.regex);
-        if (match) {
-          try {
-            (request as any).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;
-          }
+      const routeEntry = this.routeTable[path];
+      if (!routeEntry) continue;
+      if (routeEntry instanceof Response) {
+        if (pathname === path) {
+          // Same reason as exact-path static route handling above.
+          return this.applyCorsResponse(routeEntry.clone() as unknown as Response, request);
         }
+        continue;
+      }
+      const methodMap = routeEntry as BunMethodMap;
+      const handler = methodMap[request.method] ?? (request.method === 'HEAD' ? methodMap['GET'] : undefined);
+      if (!handler) {
+        continue;
       }
+
+      const match = pathname.match(matcher.regex);
+      if (!match) {
+        continue;
+      }
+
+      const response = await handler(request);
+      if (response) return response;
     }
 
-    return STATIC_RESPONSES.NOT_FOUND.clone() as unknown as Response;
+    // STATIC_RESPONSES are shared singletons; clone before per-request header mutation.
+    return this.applyCorsResponse(STATIC_RESPONSES.NOT_FOUND.clone() as unknown as Response, request);
   }
 
-  private prepareRequest(
+  private cloneMetadata<T>(value: T): T {
+    if (Array.isArray(value)) {
+      return [...value] as unknown as T;
+    }
+
+    if (value && typeof value === 'object') {
+      return { ...(value as Record<string, unknown>) } as unknown as T;
+    }
+
+    return value;
+  }
+
+  private createContext(
     request: VectorRequest<TTypes>,
     options?: {
-      params?: Record<string, string>;
-      route?: string;
       metadata?: any;
+      params?: Record<string, string>;
+      query?: Record<string, string | string[]>;
+      cookies?: Record<string, string>;
+    }
+  ): VectorContext<TTypes> {
+    const context = {
+      request,
+    } as VectorContext<TTypes>;
+
+    this.setContextField(
+      context,
+      'metadata',
+      options?.metadata !== undefined ? this.cloneMetadata(options.metadata) : ({} as any)
+    );
+    this.setContextField(context, 'params', options?.params ?? {});
+    this.setContextField(context, 'query', options?.query ?? {});
+    this.setContextField(context, 'cookies', options?.cookies ?? {});
+
+    return context;
+  }
+
+  private setContextField(context: VectorContext<TTypes>, key: string, value: unknown): void {
+    (context as Record<string, unknown>)[key] = value;
+  }
+
+  private hasOwnContextField(context: VectorContext<TTypes>, key: string): boolean {
+    return Object.prototype.hasOwnProperty.call(context, key);
+  }
+
+  private buildCheckpointContextPayload(context: VectorContext<TTypes>): Record<string, unknown> {
+    const payload: Record<string, unknown> = {};
+    const allowedKeys = ['metadata', 'content', 'validatedInput', 'authUser'] as const;
+    for (const key of allowedKeys) {
+      if (!this.hasOwnContextField(context, key)) {
+        continue;
+      }
+
+      const value = (context as Record<string, unknown>)[key];
+      if (typeof value === 'function' || typeof value === 'symbol' || value === undefined) {
+        continue;
+      }
+      payload[key] = value;
     }
-  ): void {
-    if (!request.context) {
-      request.context = {} as any;
+    return payload;
+  }
+
+  private resolveFallbackParams(pathname: string, routeMatcher: RegExp | null): Record<string, string> | undefined {
+    if (!routeMatcher) {
+      return undefined;
     }
 
-    const hasEmptyParamsObject =
-      !!request.params &&
-      typeof request.params === 'object' &&
-      !Array.isArray(request.params) &&
-      Object.keys(request.params as Record<string, unknown>).length === 0;
+    const matched = pathname.match(routeMatcher);
+    if (!matched?.groups) {
+      return undefined;
+    }
 
-    if (options?.params !== undefined && (request.params === undefined || hasEmptyParamsObject)) {
-      try {
-        request.params = options.params;
-      } catch {
-        // params is readonly (set by Bun natively) — use as-is
-      }
+    return matched.groups as Record<string, string>;
+  }
+
+  private getRequestedCheckpointVersion(request: Request): string | null {
+    if (!this.checkpointGateway) {
+      return null;
     }
-    if (options?.route !== undefined) {
-      request.route = options.route;
+
+    const gateway = this.checkpointGateway as unknown as {
+      getRequestedVersion?: (request: Request) => string | null;
+    } | null;
+    if (gateway?.getRequestedVersion) {
+      return gateway.getRequestedVersion(request);
     }
-    if (options?.metadata !== undefined) {
-      request.metadata = options.metadata;
+
+    const primary = request.headers.get('x-vector-checkpoint-version');
+    if (primary && primary.trim().length > 0) {
+      return primary.trim();
     }
 
-    if (request.query == null && request.url) {
-      try {
-        Object.defineProperty(request, 'query', {
-          get() {
-            const url = (this as any)._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,
-        });
-      } catch {
-        const url = (request as any)._parsedUrl ?? new URL(request.url);
-        try {
-          request.query = VectorRouter.parseQuery(url);
-        } catch {
-          // Leave query as-is when request shape is non-extensible.
-        }
-      }
+    const fallback = request.headers.get('x-vector-checkpoint');
+    if (fallback && fallback.trim().length > 0) {
+      return fallback.trim();
     }
 
-    if (!Object.getOwnPropertyDescriptor(request, 'cookies')) {
-      Object.defineProperty(request, 'cookies', {
-        get() {
-          const cookieHeader = this.headers.get('cookie') ?? '';
-          const cookies: Record<string, string> = {};
-          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 null;
+  }
+
+  private getCheckpointCacheKeyOverrideValue(request: Request): string | null {
+    if (!this.checkpointGateway) {
+      return null;
+    }
+
+    const gateway = this.checkpointGateway as unknown as {
+      getCacheKeyOverrideValue?: (request: Request) => string | null;
+    } | null;
+    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;
   }
 
-  private resolveFallbackParams(request: Request, routeMatcher: RegExp | null): Record<string, string> | undefined {
-    if (!routeMatcher) {
-      return undefined;
+  private applyCheckpointCacheNamespace(cacheKey: string, request: Request): string {
+    const checkpointVersion = this.getRequestedCheckpointVersion(request);
+    if (!checkpointVersion) {
+      return cacheKey;
     }
 
-    const currentParams = (request as any).params;
-    if (
-      currentParams &&
-      typeof currentParams === 'object' &&
-      !Array.isArray(currentParams) &&
-      Object.keys(currentParams as Record<string, unknown>).length > 0
-    ) {
-      return undefined;
+    return `${cacheKey}:checkpoint=${checkpointVersion}`;
+  }
+
+  private applyCheckpointRouteKeyOverride(cacheKey: string, request: Request): string {
+    const override = this.getCheckpointCacheKeyOverrideValue(request);
+    if (!override) {
+      return cacheKey;
     }
 
-    let pathname: string;
+    return override;
+  }
+
+  private async parseRequestBodyForContext(
+    context: VectorContext<TTypes>,
+    request: Request,
+    checkpointRequested: boolean
+  ): Promise<void> {
+    let parsedContent: unknown = null;
     try {
-      pathname = ((request as any)._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);
+  }
+
+  private isLikelyStreamingBodyRequest(request: Request): boolean {
+    if (request.method === 'GET' || request.method === 'HEAD') {
+      return false;
     }
 
-    return matched.groups as Record<string, string>;
+    if (!request.body) {
+      return false;
+    }
+
+    if ((request as { duplex?: unknown }).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;
   }
 
   private wrapHandler(options: RouteOptions<TTypes>, handler: RouteHandler<TTypes>) {
@@ -340,12 +457,18 @@ export class VectorRouter<TTypes extends VectorTypes = DefaultVectorTypes> {
 
     return async (request: Request) => {
       const vectorRequest = request as unknown as VectorRequest<TTypes>;
-      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 {
@@ -353,15 +476,14 @@ export class VectorRouter<TTypes extends VectorTypes = DefaultVectorTypes> {
           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 as VectorRequest<TTypes>;
 
         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',
@@ -370,84 +492,93 @@ export class VectorRouter<TTypes extends VectorTypes = DefaultVectorTypes> {
           }
         }
 
-        if (!options.rawRequest && req.method !== 'GET' && req.method !== 'HEAD') {
-          let parsedContent: unknown = 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());
-            } else if (contentType?.startsWith('multipart/form-data')) {
-              parsedContent = await req.formData();
-            } else {
-              parsedContent = await req.text();
+        const executeRoute = async (): Promise<unknown> => {
+          const req = context.request;
+          const requestForRoute = req as unknown as Request;
+          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;
+            }
+
+            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 {
+            const inputValidation = await this.validateInputSchema(context, options, fallbackParams);
+            if (inputValidation.response) {
+              return inputValidation.response;
             }
-          } catch {
-            parsedContent = null;
           }
-          this.setContentAndBodyAlias(req, parsedContent);
-        }
 
-        const inputValidationResponse = await this.validateInputSchema(req, options);
-        if (inputValidationResponse) {
-          return inputValidationResponse;
-        }
+          if (this.checkpointGateway) {
+            const checkpointResponse = await this.checkpointGateway.handle(
+              req as unknown as Request,
+              this.buildCheckpointContextPayload(context)
+            );
+            if (checkpointResponse) {
+              return checkpointResponse;
+            }
+          }
+
+          return await handler(context as any);
+        };
 
-        let result;
+        let result: any;
         const cacheOptions = options.cache;
 
         if (cacheOptions && typeof cacheOptions === 'number' && cacheOptions > 0) {
-          const cacheKey = this.cacheManager.generateKey(req as any, {
-            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 as any, {
+              authUser: context.authUser,
+            }),
+            context.request as unknown as 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 as any, {
-              authUser: req.authUser,
+          const hasRouteCacheKey = typeof cacheOptions.key === 'string' && cacheOptions.key.length > 0;
+          let cacheKey: string;
+          if (hasRouteCacheKey) {
+            cacheKey = this.applyCheckpointRouteKeyOverride(
+              cacheOptions.key as string,
+              context.request as unknown as Request
+            );
+          } else {
+            const generatedKey = this.cacheManager.generateKey(context.request as any, {
+              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 as unknown as 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: Response;
@@ -457,22 +588,9 @@ export class VectorRouter<TTypes extends VectorTypes = DefaultVectorTypes> {
           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 as unknown as Request);
-          }
-        }
+        response = await this.middlewareManager.executeFinally(response, context);
 
-        return response;
+        return this.applyCorsResponse(response, context.request as unknown as Request);
       } catch (error) {
         if (error instanceof Response) {
           return error;
@@ -497,13 +615,18 @@ export class VectorRouter<TTypes extends VectorTypes = DefaultVectorTypes> {
   }
 
   private async buildInputValidationPayload(
-    request: VectorRequest<TTypes>,
-    options: RouteOptions<TTypes>
+    context: VectorContext<TTypes>,
+    options: RouteOptions<TTypes>,
+    fallbackParams?: Record<string, string>,
+    validationOptions?: { includeBody?: boolean }
   ): Promise<Record<string, unknown>> {
-    let body = request.content;
+    const request = context.request;
+    const includeBody = validationOptions?.includeBody !== false;
+    let body = includeBody && this.hasOwnContextField(context, 'content') ? context.content : undefined;
 
-    if (options.rawRequest && request.method !== 'GET' && request.method !== 'HEAD') {
+    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 as unknown as Request).clone().text();
       } catch {
         body = null;
@@ -511,109 +634,194 @@ export class VectorRouter<TTypes extends VectorTypes = DefaultVectorTypes> {
     }
 
     return {
-      params: request.params ?? {},
-      query: request.query ?? {},
+      params: this.getRequestParams(request as unknown as Request, fallbackParams),
+      query: this.getRequestQuery(request as unknown as Request),
       headers: Object.fromEntries(request.headers.entries()),
-      cookies: request.cookies ?? {},
+      cookies: this.getRequestCookies(request as unknown as Request),
       body,
     };
   }
 
-  private applyValidatedInput(request: VectorRequest<TTypes>, validatedValue: unknown): void {
-    request.validatedInput = validatedValue;
+  private getRequestParams(request: Request, fallbackParams?: Record<string, string>): Record<string, string> {
+    const nativeParams = this.readRequestObjectField(request, 'params');
+    if (nativeParams && Object.keys(nativeParams).length > 0) {
+      return nativeParams as Record<string, string>;
+    }
+    return fallbackParams ?? {};
+  }
 
-    if (!validatedValue || typeof validatedValue !== 'object') {
-      return;
+  private getRequestQuery(request: Request): Record<string, string | string[]> {
+    const nativeQuery = this.readRequestObjectField(request, 'query');
+    if (nativeQuery) {
+      return nativeQuery as Record<string, string | string[]>;
     }
 
-    const validated = validatedValue as Record<string, unknown>;
+    try {
+      return VectorRouter.parseQuery(new URL(request.url));
+    } catch {
+      return {};
+    }
+  }
 
-    if ('params' in validated) {
-      try {
-        request.params = validated.params as any;
-      } catch {
-        // Request.params can be readonly on Bun-native requests.
-      }
+  private getRequestCookies(request: Request): Record<string, string> {
+    const nativeCookies = this.readRequestObjectField(request, 'cookies');
+    if (nativeCookies) {
+      return nativeCookies as Record<string, string>;
     }
-    if ('query' in validated) {
-      try {
-        request.query = validated.query as any;
-      } catch {
-        // Request.query can be readonly/non-configurable on some request objects.
-      }
+
+    return VectorRouter.parseCookies(request.headers.get('cookie'));
+  }
+
+  private readRequestObjectField(request: Request, key: string): Record<string, unknown> | undefined {
+    const value = (request as any)[key];
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      return undefined;
     }
-    if ('cookies' in validated) {
-      try {
-        request.cookies = validated.cookies as any;
-      } catch {
-        // Request.cookies can be readonly/non-configurable on some request objects.
-      }
+    return value as Record<string, unknown>;
+  }
+
+  private applyValidatedInput(context: VectorContext<TTypes>, validatedValue: unknown): void {
+    this.setContextField(context, 'validatedInput', validatedValue as any);
+  }
+
+  private issueHasBodyPath(issue: unknown): boolean {
+    if (!issue || typeof issue !== 'object' || !('path' in (issue as Record<string, unknown>))) {
+      return false;
     }
-    if ('body' in validated) {
-      this.setContentAndBodyAlias(request, validated.body);
+
+    const path = (issue as { path?: unknown }).path;
+    if (!Array.isArray(path) || path.length === 0) {
+      return false;
+    }
+
+    const segment = path[0];
+    if (segment && typeof segment === 'object' && 'key' in (segment as Record<string, unknown>)) {
+      return (segment as { key?: unknown }).key === 'body';
     }
+    return segment === 'body';
   }
 
-  private setContentAndBodyAlias(request: VectorRequest<TTypes>, value: unknown): void {
-    try {
-      request.content = value;
-    } catch {
-      // Request.content can be readonly/non-configurable on some request objects.
-      return;
+  private issueHasExplicitNonBodyPath(issue: unknown): boolean {
+    if (!issue || typeof issue !== 'object' || !('path' in (issue as Record<string, unknown>))) {
+      return false;
     }
 
-    this.setBodyAlias(request, value);
+    const path = (issue as { path?: unknown }).path;
+    if (!Array.isArray(path) || path.length === 0) {
+      return false;
+    }
+
+    const segment = path[0];
+    if (segment && typeof segment === 'object' && 'key' in (segment as Record<string, unknown>)) {
+      return (segment as { key?: unknown }).key !== 'body';
+    }
+    return segment !== 'body';
   }
 
-  private setBodyAlias(request: VectorRequest<TTypes>, value: unknown): void {
-    try {
-      request.body = value as any;
-    } catch {
-      // Keep request.content as source of truth when body alias is readonly.
+  private issueHasUnknownPath(issue: unknown): boolean {
+    if (!issue || typeof issue !== 'object' || !('path' in (issue as Record<string, unknown>))) {
+      return true;
+    }
+
+    const path = (issue as { path?: unknown }).path;
+    if (!Array.isArray(path)) {
+      return true;
+    }
+
+    return path.length === 0;
+  }
+
+  private shouldDeferBodyValidation(
+    issues: readonly unknown[],
+    context: VectorContext<TTypes>,
+    validationOptions?: { includeBody?: boolean; allowBodyDeferral?: boolean }
+  ): boolean {
+    if (!(validationOptions?.allowBodyDeferral === true && validationOptions?.includeBody === false)) {
+      return false;
+    }
+
+    const request = context.request as unknown as 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;
   }
 
   private async validateInputSchema(
-    request: VectorRequest<TTypes>,
-    options: RouteOptions<TTypes>
-  ): Promise<Response | null> {
+    context: VectorContext<TTypes>,
+    options: RouteOptions<TTypes>,
+    fallbackParams?: Record<string, string>,
+    validationOptions?: { includeBody?: boolean; allowBodyDeferral?: boolean }
+  ): Promise<InputValidationResult> {
     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,
+      };
     }
   }
 
@@ -672,6 +880,22 @@ export class VectorRouter<TTypes extends VectorTypes = DefaultVectorTypes> {
     return query;
   }
 
+  private static parseCookies(cookieHeader: string | null): Record<string, string> {
+    const cookies: Record<string, string> = {};
+    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;
+  }
+
   private routeSpecificityScore(path: string): number {
     const STATIC_SEGMENT_WEIGHT = 1000;
     const PARAM_SEGMENT_WEIGHT = 10;
@@ -698,4 +922,21 @@ export class VectorRouter<TTypes extends VectorTypes = DefaultVectorTypes> {
 
     return score;
   }
+
+  private applyCorsResponse(response: Response, request: Request): Response {
+    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;
+  }
 }