@klnap/next-proxy-chain 1.0.2 → 1.0.4

package/dist/index.d.cts

@@ -4,10 +4,6 @@ import { NextRequest, NextFetchEvent, NextResponse } from 'next/server';
  * Unique symbol identifying an explicit continue action in the proxy chain pipeline.
  */
 declare const NEXT: unique symbol;
-/**
- * Protected request headers that cannot be rewritten unless explicitly permitted by policy.
- */
-declare const DEFAULT_BLOCKED_REQUEST_HEADERS: readonly string[];
 
 /**
  * Configuration options for chain continuation.
@@ -15,7 +11,7 @@ declare const DEFAULT_BLOCKED_REQUEST_HEADERS: readonly string[];
 type NextOptions = {
     /** Request header overrides visible to downstream rules and handlers. */
     request?: HeadersInit;
-    /** Response headers merged into the final outgoing response. */
+    /** Response headers merged into the final outgoing response. `set-cookie` is extracted as cookies. */
     headers?: HeadersInit;
 };
 /**
@@ -29,12 +25,7 @@ type NextResult = NextOptions & {
  * Backed by Map to eliminate prototype-pollution risks.
  */
 type ProxyContext = Map<string, unknown>;
-type ProxyResult<TResponse = NextResponse | Response> = TResponse | NextResult | undefined | void;
 type PathMatcher = RegExp | string;
-type PathOptions = {
-    /** Optional locale prefixes for path matching. */
-    locales?: readonly string[];
-};
 type HostMatcher = string | RegExp | readonly (string | RegExp)[];
 /**
  * Scoping configuration for rule inclusion or exclusion.
@@ -62,7 +53,6 @@ type ProxyPathFilter = {
     include?: RouteScopeList;
     exclude?: RouteScopeList;
     name?: string;
-    pathOptions?: PathOptions;
 };
 /**
  * A single proxy execution function.
@@ -72,39 +62,40 @@ type ProxyRule<TContext = ProxyContext> = BaseProxyRule<ProxyFn<TContext>>;
 type DefinedProxy<TContext = ProxyContext> = ProxyFn<TContext> & ((filter: ProxyPathFilter) => ProxyRule<TContext>);
 type Entry<TContext = ProxyContext> = ProxyFn<TContext> | ProxyRule<TContext>;
 type MergeStrategy = "last-write-wins" | "first-write-wins" | ((key: string, existing: string, incoming: string) => string | null);
-interface EntryWrite {
-    ruleIndex: number;
-    ruleName: string;
-    items: Map<string, string>;
-}
-type LogLevel = "debug" | "info" | "warn" | "error";
 interface ChainLogger {
     debug: (metaOrMsg: unknown, maybeMsg?: string) => void;
     info: (metaOrMsg: unknown, maybeMsg?: string) => void;
     warn: (metaOrMsg: unknown, maybeMsg?: string) => void;
     error: (metaOrMsg: unknown, maybeMsg?: string) => void;
 }
-type PipelineOutcome = {
-    kind: "passed";
-    duration: number;
-} | {
-    kind: "next";
-    duration: number;
-    headers: number;
-} | {
-    kind: "stop";
-    duration: number;
-    status: number;
-};
 interface RequestHeaderPolicy {
     blocked?: readonly string[];
     allowed?: readonly string[];
 }
+/**
+ * Value returned from `onError`.
+ *
+ * - `Response` — stop the pipeline and return it
+ * - `NextResult` (`next()`) — continue to the next rule (rule-level errors only)
+ * - `undefined` / `void` / `null` — fail closed (`500`)
+ */
+type OnErrorResult = NextResponse | Response | NextResult | undefined | void | null;
+type OnErrorHandler<TContext = ProxyContext> = (err: unknown, 
+/**
+ * 0-based index of the rule that threw.
+ * `-1` means the error originated in the pipeline engine after context creation.
+ * Engine-level errors cannot continue; only a `Response` is honored.
+ */
+ruleIndex: number, req: NextRequest, ctx: TContext) => OnErrorResult | Promise<OnErrorResult>;
 interface ChainConfig<TContext = ProxyContext> {
     createContext: (req: NextRequest, event: NextFetchEvent) => TContext;
     cookieMergeStrategy: MergeStrategy;
+    /**
+     * How conflicting **response** headers from different rules are resolved.
+     * Request header overrides always use last-write-wins and ignore this option.
+     */
     headerMergeStrategy: MergeStrategy;
-    onError?: (err: unknown, ruleIndex: number, req: NextRequest, ctx: TContext) => NextResponse | Response | undefined | void | Promise<NextResponse | Response | undefined | void>;
+    onError?: OnErrorHandler<TContext>;
     debug: boolean;
     logger: ChainLogger;
     /** Maximum wall-clock execution time per rule in milliseconds. 0 disables timeout. */
@@ -112,101 +103,41 @@ interface ChainConfig<TContext = ProxyContext> {
     requestHeaderPolicy: RequestHeaderPolicy;
     /** Throw an error on startup if the runtime platform does not support request header overrides. */
     strictOverrideCheck?: boolean;
+    /**
+     * Request header name that prefixes rewrites with a physical host folder
+     * (multi-tenant `app/(sites)/shop` layouts). Unset = disabled.
+     */
+    hostFolderHeader?: string;
 }
 type ProxyChainOptions<TContext = ProxyContext> = Partial<ChainConfig<TContext>>;
 
 /**
- * Creates an isolated per-request context instance.
- * Backed by Map to eliminate prototype pollution risks.
- */
-declare function createProxyContext(): ProxyContext;
-
-/**
- * Strips sticky and global flags (g, y) from RegExp instances.
- * On Edge runtimes, compiled regex instances can be shared across requests;
- * sticky and global flags mutate stateful indices, causing non-deterministic matching.
- */
-declare function toStatelessRegExp(re: RegExp): RegExp;
-/**
- * Builds a compiled Host matcher RegExp from domain names, wildcards, or regex patterns.
- */
-declare function host(matcher: HostMatcher): RegExp;
-/**
- * Compiles a path pattern (glob string, param pattern, or RegExp) into a stateless regular expression.
- */
-declare function path(pattern: string | RegExp, options?: PathOptions): RegExp;
-declare function toPathRegex(matcher: PathMatcher | PathMatcher[], options?: PathOptions): RegExp;
-/**
- * Compiles route scoping declarations into normalized regex clauses.
- */
-declare function compileScopes(input: RouteScopeList | undefined, pathOptions?: PathOptions): CompiledScope[] | undefined;
-declare function toRule<TFn>(entry: TFn | BaseProxyRule<TFn>): BaseProxyRule<TFn>;
-declare function ruleLabel<TFn>(rule: BaseProxyRule<TFn>, index: number): string;
-/**
- * Decorates a proxy entry with declarative path and host inclusion/exclusion filters.
- */
-declare function withPaths<TFn>(entry: TFn | BaseProxyRule<TFn>, filter: ProxyPathFilter): BaseProxyRule<TFn>;
-/**
- * Determines whether a given request matches a rule's scoping constraints.
- */
-declare function ruleMatches<TFn>(pathname: string, hostname: string | null, rule: BaseProxyRule<TFn>): boolean;
-declare function pathMatches<TFn>(pathname: string, rule: BaseProxyRule<TFn>): boolean;
-/**
- * Normalizes Host or X-Forwarded-Host header values to lower-case hostname without port.
- */
-declare function normalizeHost(raw: string | null | undefined): string | null;
-/**
- * Validates that an identical scope is not declared simultaneously in include and exclude.
- */
-declare function assertIncludeExcludeNoOverlap(include: CompiledScope[] | undefined, exclude: CompiledScope[] | undefined, label: string): void;
-
-/**
- * Converts HeadersInit or undefined to a standard Web Headers instance.
- */
-declare function headersInitToHeaders(init?: HeadersInit): Headers;
-/**
- * Compares two Headers instances to determine if overrides contain differences.
- */
-declare function headersDiffer(base: Headers, overrides: Headers): boolean;
-/**
- * Checks whether a request header is permitted to be mutated under the configured policy.
- */
-declare function isRequestHeaderAllowed(name: string, policy?: RequestHeaderPolicy): boolean;
-/**
- * Merges new request header overrides into the target Headers instance, filtering prohibited headers.
- */
-declare function mergeRequestHeaderOverrides(target: Headers, overrides: Headers, policy?: RequestHeaderPolicy): {
-    applied: number;
-    dropped: string[];
-};
-/**
- * Extracts cookie name from a raw Set-Cookie directive.
- */
-declare function parseCookieName(setCookie: string): string;
-/**
- * Extracts all Set-Cookie directives using standard getSetCookie() when available.
- */
-declare function listSetCookie(headers: Headers): string[];
-/**
- * Maps cookie name to Set-Cookie header value from a Headers instance.
- */
-declare function cookieItemsFromHeaders(headers: Headers): Map<string, string>;
-/**
- * Filters out Set-Cookie and internal transport headers (x-middleware-*) from response headers.
- */
-declare function responseHeaderItems(headers: Headers): Map<string, string>;
-/**
- * Decodes Next.js request header overrides encoded into response headers.
- */
-declare function decodeOverriddenRequestHeaders(headers: Headers): Headers;
-/**
- * Deterministically merges writes across rules based on configured strategy.
+ * Creates a reusable, scope-aware proxy rule function.
+ *
+ * @example
+ * const authRule = defineProxy("auth", async (req, ctx) => next())
+ * const scopedAuthRule = authRule({ include: path("/admin/*") })
  */
-declare function mergeWrites(writes: EntryWrite[], strategy: MergeStrategy, onConflict?: (key: string, winner: string, loser: string) => void): Map<string, string>;
+declare function defineProxy<TContext = ProxyContext>(run: ProxyFn<TContext>): DefinedProxy<TContext>;
+declare function defineProxy<TContext = ProxyContext>(name: string, run: ProxyFn<TContext>): DefinedProxy<TContext>;
+type ProxyHandler = (req: NextRequest, event: NextFetchEvent) => Promise<NextResponse | Response>;
 /**
- * Applies merged headers and deduplicated cookies onto an outgoing response.
+ * Composes independent proxy rules into a single pipeline for Next.js 15 (middleware.ts) and Next.js 16 (proxy.ts).
+ *
+ * Custom `TContext` requires `createContext`. Without it, context is `ProxyContext` (`Map`).
+ *
+ * @example
+ * export default proxyChain({ debug: true }, [
+ *   requestIdRule,
+ *   authRule({ include: path("/dashboard/*") }),
+ *   i18nRule,
+ * ])
  */
-declare function applyMergedToResponse(res: Response, headers: Map<string, string>, cookies: Map<string, string>): void;
+declare function proxyChain(entries: Entry<ProxyContext>[]): ProxyHandler;
+declare function proxyChain(options: ProxyChainOptions<ProxyContext>, entries: Entry<ProxyContext>[]): ProxyHandler;
+declare function proxyChain<TContext>(options: ProxyChainOptions<TContext> & {
+    createContext: (req: NextRequest, event: NextFetchEvent) => TContext;
+}, entries: Entry<TContext>[]): ProxyHandler;
 
 /**
  * Creates a continuation action instructing the proxy chain to proceed to subsequent rules.
@@ -223,63 +154,28 @@ declare function next(options?: NextOptions): NextResult;
  */
 declare function isNextResult(value: unknown): value is NextResult;
 
-declare function createConsoleLogger(minLevel?: LogLevel): ChainLogger;
 /**
- * Formats a single structured log line for an executed proxy rule.
+ * Builds a compiled Host matcher RegExp from domain names, `*.example.com` wildcards, or regex patterns.
+ */
+declare function host(matcher: HostMatcher): RegExp;
+/**
+ * Compiles a path pattern (glob string, param pattern, or RegExp) into a stateless regular expression.
+ *
+ * - `*` — exactly one path segment
+ * - `**` — zero or more subsequent segments
+ */
+declare function path(pattern: string | RegExp): RegExp;
+
+/**
+ * Creates an isolated per-request context instance.
+ * Backed by Map to eliminate prototype pollution risks.
  */
-declare function formatPipelineLine(input: {
-    method: string;
-    path: string;
-    name: string;
-    traceId?: string;
-    outcome: PipelineOutcome;
-}): string;
+declare function createProxyContext(): ProxyContext;
 
 declare class RuleTimeoutError extends Error {
     readonly ruleName: string;
     readonly timeoutMs: number;
     constructor(ruleName: string, timeoutMs: number);
 }
-/**
- * Enforces a strict execution time budget on an asynchronous rule operation.
- */
-declare function withRuleTimeout<T>(promise: Promise<T>, timeoutMs: number | undefined, ruleName: string): Promise<T>;
-
-declare function safeInternalError(): NextResponse;
-declare function assertOverrideMechanismSupported(strict?: boolean): boolean;
-type ResolvedOutcome = {
-    kind: "continue";
-    request?: Headers;
-    responseHeaders: Map<string, string>;
-    cookies: Map<string, string>;
-    rewriteUrl?: string;
-} | {
-    kind: "stop";
-    response: NextResponse | Response;
-};
-declare function resolveRuleResult(res: NextResponse | Response | NextResult | undefined | void, requestHeaderPolicy: RequestHeaderPolicy, logger: ChainLogger, debug: boolean): ResolvedOutcome;
-declare function finalizeResponse(res: NextResponse | Response, headerWrites: EntryWrite[], cookieWrites: EntryWrite[], headerStrategy: MergeStrategy, cookieStrategy: MergeStrategy, logger: ChainLogger, debug: boolean): NextResponse | Response;
-
-/**
- * Creates a reusable, scope-aware proxy rule function.
- *
- * @example
- * const authRule = defineProxy("auth", async (req, ctx) => next())
- * const scopedAuthRule = authRule({ include: path("/admin/*") })
- */
-declare function defineProxy<TContext = ProxyContext>(run: ProxyFn<TContext>): DefinedProxy<TContext>;
-declare function defineProxy<TContext = ProxyContext>(name: string, run: ProxyFn<TContext>): DefinedProxy<TContext>;
-/**
- * Composes independent proxy rules into a single pipeline for Next.js 15 (middleware.ts) and Next.js 16 (proxy.ts).
- *
- * @example
- * export default proxyChain({ debug: true }, [
- *   requestIdRule,
- *   authRule({ include: path("/dashboard/*") }),
- *   i18nRule,
- * ])
- */
-declare function proxyChain<TContext = ProxyContext>(entries: Entry<TContext>[]): (req: NextRequest, event: NextFetchEvent) => Promise<NextResponse | Response>;
-declare function proxyChain<TContext = ProxyContext>(options: ProxyChainOptions<TContext>, entries: Entry<TContext>[]): (req: NextRequest, event: NextFetchEvent) => Promise<NextResponse | Response>;
 
-export { type BaseProxyRule, type ChainConfig, type ChainLogger, type CompiledScope, DEFAULT_BLOCKED_REQUEST_HEADERS, type DefinedProxy, type Entry, type EntryWrite, type HostMatcher, type LogLevel, type MergeStrategy, NEXT, type NextOptions, type NextResult, type PathMatcher, type PathOptions, type PipelineOutcome, type ProxyChainOptions, type ProxyContext, type ProxyFn, type ProxyPathFilter, type ProxyResult, type ProxyRule, type RequestHeaderPolicy, type ResolvedOutcome, type RouteScopeInput, type RouteScopeList, RuleTimeoutError, applyMergedToResponse, assertIncludeExcludeNoOverlap, assertOverrideMechanismSupported, compileScopes, cookieItemsFromHeaders, createConsoleLogger, createProxyContext, decodeOverriddenRequestHeaders, defineProxy, finalizeResponse, formatPipelineLine, headersDiffer, headersInitToHeaders, host, isNextResult, isRequestHeaderAllowed, listSetCookie, mergeRequestHeaderOverrides, mergeWrites, next, normalizeHost, parseCookieName, path, pathMatches, proxyChain, resolveRuleResult, responseHeaderItems, ruleLabel, ruleMatches, safeInternalError, toPathRegex, toRule, toStatelessRegExp, withPaths, withRuleTimeout };
+export { type ChainLogger, type DefinedProxy, type Entry, type HostMatcher, type MergeStrategy, type NextOptions, type NextResult, type OnErrorHandler, type OnErrorResult, type PathMatcher, type ProxyChainOptions, type ProxyContext, type ProxyFn, type ProxyPathFilter, type ProxyRule, type RequestHeaderPolicy, RuleTimeoutError, createProxyContext, defineProxy, host, isNextResult, next, path, proxyChain };

package/dist/index.d.ts

@@ -4,10 +4,6 @@ import { NextRequest, NextFetchEvent, NextResponse } from 'next/server';
  * Unique symbol identifying an explicit continue action in the proxy chain pipeline.
  */
 declare const NEXT: unique symbol;
-/**
- * Protected request headers that cannot be rewritten unless explicitly permitted by policy.
- */
-declare const DEFAULT_BLOCKED_REQUEST_HEADERS: readonly string[];
 
 /**
  * Configuration options for chain continuation.
@@ -15,7 +11,7 @@ declare const DEFAULT_BLOCKED_REQUEST_HEADERS: readonly string[];
 type NextOptions = {
     /** Request header overrides visible to downstream rules and handlers. */
     request?: HeadersInit;
-    /** Response headers merged into the final outgoing response. */
+    /** Response headers merged into the final outgoing response. `set-cookie` is extracted as cookies. */
     headers?: HeadersInit;
 };
 /**
@@ -29,12 +25,7 @@ type NextResult = NextOptions & {
  * Backed by Map to eliminate prototype-pollution risks.
  */
 type ProxyContext = Map<string, unknown>;
-type ProxyResult<TResponse = NextResponse | Response> = TResponse | NextResult | undefined | void;
 type PathMatcher = RegExp | string;
-type PathOptions = {
-    /** Optional locale prefixes for path matching. */
-    locales?: readonly string[];
-};
 type HostMatcher = string | RegExp | readonly (string | RegExp)[];
 /**
  * Scoping configuration for rule inclusion or exclusion.
@@ -62,7 +53,6 @@ type ProxyPathFilter = {
     include?: RouteScopeList;
     exclude?: RouteScopeList;
     name?: string;
-    pathOptions?: PathOptions;
 };
 /**
  * A single proxy execution function.
@@ -72,39 +62,40 @@ type ProxyRule<TContext = ProxyContext> = BaseProxyRule<ProxyFn<TContext>>;
 type DefinedProxy<TContext = ProxyContext> = ProxyFn<TContext> & ((filter: ProxyPathFilter) => ProxyRule<TContext>);
 type Entry<TContext = ProxyContext> = ProxyFn<TContext> | ProxyRule<TContext>;
 type MergeStrategy = "last-write-wins" | "first-write-wins" | ((key: string, existing: string, incoming: string) => string | null);
-interface EntryWrite {
-    ruleIndex: number;
-    ruleName: string;
-    items: Map<string, string>;
-}
-type LogLevel = "debug" | "info" | "warn" | "error";
 interface ChainLogger {
     debug: (metaOrMsg: unknown, maybeMsg?: string) => void;
     info: (metaOrMsg: unknown, maybeMsg?: string) => void;
     warn: (metaOrMsg: unknown, maybeMsg?: string) => void;
     error: (metaOrMsg: unknown, maybeMsg?: string) => void;
 }
-type PipelineOutcome = {
-    kind: "passed";
-    duration: number;
-} | {
-    kind: "next";
-    duration: number;
-    headers: number;
-} | {
-    kind: "stop";
-    duration: number;
-    status: number;
-};
 interface RequestHeaderPolicy {
     blocked?: readonly string[];
     allowed?: readonly string[];
 }
+/**
+ * Value returned from `onError`.
+ *
+ * - `Response` — stop the pipeline and return it
+ * - `NextResult` (`next()`) — continue to the next rule (rule-level errors only)
+ * - `undefined` / `void` / `null` — fail closed (`500`)
+ */
+type OnErrorResult = NextResponse | Response | NextResult | undefined | void | null;
+type OnErrorHandler<TContext = ProxyContext> = (err: unknown, 
+/**
+ * 0-based index of the rule that threw.
+ * `-1` means the error originated in the pipeline engine after context creation.
+ * Engine-level errors cannot continue; only a `Response` is honored.
+ */
+ruleIndex: number, req: NextRequest, ctx: TContext) => OnErrorResult | Promise<OnErrorResult>;
 interface ChainConfig<TContext = ProxyContext> {
     createContext: (req: NextRequest, event: NextFetchEvent) => TContext;
     cookieMergeStrategy: MergeStrategy;
+    /**
+     * How conflicting **response** headers from different rules are resolved.
+     * Request header overrides always use last-write-wins and ignore this option.
+     */
     headerMergeStrategy: MergeStrategy;
-    onError?: (err: unknown, ruleIndex: number, req: NextRequest, ctx: TContext) => NextResponse | Response | undefined | void | Promise<NextResponse | Response | undefined | void>;
+    onError?: OnErrorHandler<TContext>;
     debug: boolean;
     logger: ChainLogger;
     /** Maximum wall-clock execution time per rule in milliseconds. 0 disables timeout. */
@@ -112,101 +103,41 @@ interface ChainConfig<TContext = ProxyContext> {
     requestHeaderPolicy: RequestHeaderPolicy;
     /** Throw an error on startup if the runtime platform does not support request header overrides. */
     strictOverrideCheck?: boolean;
+    /**
+     * Request header name that prefixes rewrites with a physical host folder
+     * (multi-tenant `app/(sites)/shop` layouts). Unset = disabled.
+     */
+    hostFolderHeader?: string;
 }
 type ProxyChainOptions<TContext = ProxyContext> = Partial<ChainConfig<TContext>>;
 
 /**
- * Creates an isolated per-request context instance.
- * Backed by Map to eliminate prototype pollution risks.
- */
-declare function createProxyContext(): ProxyContext;
-
-/**
- * Strips sticky and global flags (g, y) from RegExp instances.
- * On Edge runtimes, compiled regex instances can be shared across requests;
- * sticky and global flags mutate stateful indices, causing non-deterministic matching.
- */
-declare function toStatelessRegExp(re: RegExp): RegExp;
-/**
- * Builds a compiled Host matcher RegExp from domain names, wildcards, or regex patterns.
- */
-declare function host(matcher: HostMatcher): RegExp;
-/**
- * Compiles a path pattern (glob string, param pattern, or RegExp) into a stateless regular expression.
- */
-declare function path(pattern: string | RegExp, options?: PathOptions): RegExp;
-declare function toPathRegex(matcher: PathMatcher | PathMatcher[], options?: PathOptions): RegExp;
-/**
- * Compiles route scoping declarations into normalized regex clauses.
- */
-declare function compileScopes(input: RouteScopeList | undefined, pathOptions?: PathOptions): CompiledScope[] | undefined;
-declare function toRule<TFn>(entry: TFn | BaseProxyRule<TFn>): BaseProxyRule<TFn>;
-declare function ruleLabel<TFn>(rule: BaseProxyRule<TFn>, index: number): string;
-/**
- * Decorates a proxy entry with declarative path and host inclusion/exclusion filters.
- */
-declare function withPaths<TFn>(entry: TFn | BaseProxyRule<TFn>, filter: ProxyPathFilter): BaseProxyRule<TFn>;
-/**
- * Determines whether a given request matches a rule's scoping constraints.
- */
-declare function ruleMatches<TFn>(pathname: string, hostname: string | null, rule: BaseProxyRule<TFn>): boolean;
-declare function pathMatches<TFn>(pathname: string, rule: BaseProxyRule<TFn>): boolean;
-/**
- * Normalizes Host or X-Forwarded-Host header values to lower-case hostname without port.
- */
-declare function normalizeHost(raw: string | null | undefined): string | null;
-/**
- * Validates that an identical scope is not declared simultaneously in include and exclude.
- */
-declare function assertIncludeExcludeNoOverlap(include: CompiledScope[] | undefined, exclude: CompiledScope[] | undefined, label: string): void;
-
-/**
- * Converts HeadersInit or undefined to a standard Web Headers instance.
- */
-declare function headersInitToHeaders(init?: HeadersInit): Headers;
-/**
- * Compares two Headers instances to determine if overrides contain differences.
- */
-declare function headersDiffer(base: Headers, overrides: Headers): boolean;
-/**
- * Checks whether a request header is permitted to be mutated under the configured policy.
- */
-declare function isRequestHeaderAllowed(name: string, policy?: RequestHeaderPolicy): boolean;
-/**
- * Merges new request header overrides into the target Headers instance, filtering prohibited headers.
- */
-declare function mergeRequestHeaderOverrides(target: Headers, overrides: Headers, policy?: RequestHeaderPolicy): {
-    applied: number;
-    dropped: string[];
-};
-/**
- * Extracts cookie name from a raw Set-Cookie directive.
- */
-declare function parseCookieName(setCookie: string): string;
-/**
- * Extracts all Set-Cookie directives using standard getSetCookie() when available.
- */
-declare function listSetCookie(headers: Headers): string[];
-/**
- * Maps cookie name to Set-Cookie header value from a Headers instance.
- */
-declare function cookieItemsFromHeaders(headers: Headers): Map<string, string>;
-/**
- * Filters out Set-Cookie and internal transport headers (x-middleware-*) from response headers.
- */
-declare function responseHeaderItems(headers: Headers): Map<string, string>;
-/**
- * Decodes Next.js request header overrides encoded into response headers.
- */
-declare function decodeOverriddenRequestHeaders(headers: Headers): Headers;
-/**
- * Deterministically merges writes across rules based on configured strategy.
+ * Creates a reusable, scope-aware proxy rule function.
+ *
+ * @example
+ * const authRule = defineProxy("auth", async (req, ctx) => next())
+ * const scopedAuthRule = authRule({ include: path("/admin/*") })
  */
-declare function mergeWrites(writes: EntryWrite[], strategy: MergeStrategy, onConflict?: (key: string, winner: string, loser: string) => void): Map<string, string>;
+declare function defineProxy<TContext = ProxyContext>(run: ProxyFn<TContext>): DefinedProxy<TContext>;
+declare function defineProxy<TContext = ProxyContext>(name: string, run: ProxyFn<TContext>): DefinedProxy<TContext>;
+type ProxyHandler = (req: NextRequest, event: NextFetchEvent) => Promise<NextResponse | Response>;
 /**
- * Applies merged headers and deduplicated cookies onto an outgoing response.
+ * Composes independent proxy rules into a single pipeline for Next.js 15 (middleware.ts) and Next.js 16 (proxy.ts).
+ *
+ * Custom `TContext` requires `createContext`. Without it, context is `ProxyContext` (`Map`).
+ *
+ * @example
+ * export default proxyChain({ debug: true }, [
+ *   requestIdRule,
+ *   authRule({ include: path("/dashboard/*") }),
+ *   i18nRule,
+ * ])
  */
-declare function applyMergedToResponse(res: Response, headers: Map<string, string>, cookies: Map<string, string>): void;
+declare function proxyChain(entries: Entry<ProxyContext>[]): ProxyHandler;
+declare function proxyChain(options: ProxyChainOptions<ProxyContext>, entries: Entry<ProxyContext>[]): ProxyHandler;
+declare function proxyChain<TContext>(options: ProxyChainOptions<TContext> & {
+    createContext: (req: NextRequest, event: NextFetchEvent) => TContext;
+}, entries: Entry<TContext>[]): ProxyHandler;
 
 /**
  * Creates a continuation action instructing the proxy chain to proceed to subsequent rules.
@@ -223,63 +154,28 @@ declare function next(options?: NextOptions): NextResult;
  */
 declare function isNextResult(value: unknown): value is NextResult;
 
-declare function createConsoleLogger(minLevel?: LogLevel): ChainLogger;
 /**
- * Formats a single structured log line for an executed proxy rule.
+ * Builds a compiled Host matcher RegExp from domain names, `*.example.com` wildcards, or regex patterns.
+ */
+declare function host(matcher: HostMatcher): RegExp;
+/**
+ * Compiles a path pattern (glob string, param pattern, or RegExp) into a stateless regular expression.
+ *
+ * - `*` — exactly one path segment
+ * - `**` — zero or more subsequent segments
+ */
+declare function path(pattern: string | RegExp): RegExp;
+
+/**
+ * Creates an isolated per-request context instance.
+ * Backed by Map to eliminate prototype pollution risks.
  */
-declare function formatPipelineLine(input: {
-    method: string;
-    path: string;
-    name: string;
-    traceId?: string;
-    outcome: PipelineOutcome;
-}): string;
+declare function createProxyContext(): ProxyContext;
 
 declare class RuleTimeoutError extends Error {
     readonly ruleName: string;
     readonly timeoutMs: number;
     constructor(ruleName: string, timeoutMs: number);
 }
-/**
- * Enforces a strict execution time budget on an asynchronous rule operation.
- */
-declare function withRuleTimeout<T>(promise: Promise<T>, timeoutMs: number | undefined, ruleName: string): Promise<T>;
-
-declare function safeInternalError(): NextResponse;
-declare function assertOverrideMechanismSupported(strict?: boolean): boolean;
-type ResolvedOutcome = {
-    kind: "continue";
-    request?: Headers;
-    responseHeaders: Map<string, string>;
-    cookies: Map<string, string>;
-    rewriteUrl?: string;
-} | {
-    kind: "stop";
-    response: NextResponse | Response;
-};
-declare function resolveRuleResult(res: NextResponse | Response | NextResult | undefined | void, requestHeaderPolicy: RequestHeaderPolicy, logger: ChainLogger, debug: boolean): ResolvedOutcome;
-declare function finalizeResponse(res: NextResponse | Response, headerWrites: EntryWrite[], cookieWrites: EntryWrite[], headerStrategy: MergeStrategy, cookieStrategy: MergeStrategy, logger: ChainLogger, debug: boolean): NextResponse | Response;
-
-/**
- * Creates a reusable, scope-aware proxy rule function.
- *
- * @example
- * const authRule = defineProxy("auth", async (req, ctx) => next())
- * const scopedAuthRule = authRule({ include: path("/admin/*") })
- */
-declare function defineProxy<TContext = ProxyContext>(run: ProxyFn<TContext>): DefinedProxy<TContext>;
-declare function defineProxy<TContext = ProxyContext>(name: string, run: ProxyFn<TContext>): DefinedProxy<TContext>;
-/**
- * Composes independent proxy rules into a single pipeline for Next.js 15 (middleware.ts) and Next.js 16 (proxy.ts).
- *
- * @example
- * export default proxyChain({ debug: true }, [
- *   requestIdRule,
- *   authRule({ include: path("/dashboard/*") }),
- *   i18nRule,
- * ])
- */
-declare function proxyChain<TContext = ProxyContext>(entries: Entry<TContext>[]): (req: NextRequest, event: NextFetchEvent) => Promise<NextResponse | Response>;
-declare function proxyChain<TContext = ProxyContext>(options: ProxyChainOptions<TContext>, entries: Entry<TContext>[]): (req: NextRequest, event: NextFetchEvent) => Promise<NextResponse | Response>;
 
-export { type BaseProxyRule, type ChainConfig, type ChainLogger, type CompiledScope, DEFAULT_BLOCKED_REQUEST_HEADERS, type DefinedProxy, type Entry, type EntryWrite, type HostMatcher, type LogLevel, type MergeStrategy, NEXT, type NextOptions, type NextResult, type PathMatcher, type PathOptions, type PipelineOutcome, type ProxyChainOptions, type ProxyContext, type ProxyFn, type ProxyPathFilter, type ProxyResult, type ProxyRule, type RequestHeaderPolicy, type ResolvedOutcome, type RouteScopeInput, type RouteScopeList, RuleTimeoutError, applyMergedToResponse, assertIncludeExcludeNoOverlap, assertOverrideMechanismSupported, compileScopes, cookieItemsFromHeaders, createConsoleLogger, createProxyContext, decodeOverriddenRequestHeaders, defineProxy, finalizeResponse, formatPipelineLine, headersDiffer, headersInitToHeaders, host, isNextResult, isRequestHeaderAllowed, listSetCookie, mergeRequestHeaderOverrides, mergeWrites, next, normalizeHost, parseCookieName, path, pathMatches, proxyChain, resolveRuleResult, responseHeaderItems, ruleLabel, ruleMatches, safeInternalError, toPathRegex, toRule, toStatelessRegExp, withPaths, withRuleTimeout };
+export { type ChainLogger, type DefinedProxy, type Entry, type HostMatcher, type MergeStrategy, type NextOptions, type NextResult, type OnErrorHandler, type OnErrorResult, type PathMatcher, type ProxyChainOptions, type ProxyContext, type ProxyFn, type ProxyPathFilter, type ProxyRule, type RequestHeaderPolicy, RuleTimeoutError, createProxyContext, defineProxy, host, isNextResult, next, path, proxyChain };