@klnap/next-proxy-chain 1.0.0

package/dist/core.cjs

@@ -0,0 +1,467 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core.ts
+var core_exports = {};
+__export(core_exports, {
+  DEFAULT_BLOCKED_REQUEST_HEADERS: () => DEFAULT_BLOCKED_REQUEST_HEADERS,
+  NEXT: () => NEXT,
+  RuleTimeoutError: () => RuleTimeoutError,
+  applyMergedToResponse: () => applyMergedToResponse,
+  assertIncludeExcludeNoOverlap: () => assertIncludeExcludeNoOverlap,
+  compileScopes: () => compileScopes,
+  cookieItemsFromHeaders: () => cookieItemsFromHeaders,
+  createConsoleLogger: () => createConsoleLogger,
+  createProxyContext: () => createProxyContext,
+  decodeOverriddenRequestHeaders: () => decodeOverriddenRequestHeaders,
+  formatPipelineLine: () => formatPipelineLine,
+  headersDiffer: () => headersDiffer,
+  headersInitToHeaders: () => headersInitToHeaders,
+  host: () => host,
+  isNextResult: () => isNextResult,
+  isRequestHeaderAllowed: () => isRequestHeaderAllowed,
+  listSetCookie: () => listSetCookie,
+  mergeRequestHeaderOverrides: () => mergeRequestHeaderOverrides,
+  mergeWrites: () => mergeWrites,
+  next: () => next,
+  normalizeHost: () => normalizeHost,
+  parseCookieName: () => parseCookieName,
+  path: () => path,
+  pathMatches: () => pathMatches,
+  responseHeaderItems: () => responseHeaderItems,
+  ruleLabel: () => ruleLabel,
+  ruleMatches: () => ruleMatches,
+  toPathRegex: () => toPathRegex,
+  toRule: () => toRule,
+  toStatelessRegExp: () => toStatelessRegExp,
+  withPaths: () => withPaths,
+  withRuleTimeout: () => withRuleTimeout
+});
+module.exports = __toCommonJS(core_exports);
+var NEXT = /* @__PURE__ */ Symbol.for("proxy-chain.next");
+function next(options = {}) {
+  return { [NEXT]: true, ...options };
+}
+function isNextResult(value) {
+  return typeof value === "object" && value !== null && NEXT in value;
+}
+function createProxyContext() {
+  return /* @__PURE__ */ new Map();
+}
+var USELESS_FN_NAMES = /* @__PURE__ */ new Set(["", "proxy", "anonymous", "run", "next"]);
+function usefulName(value) {
+  if (!value || USELESS_FN_NAMES.has(value)) return void 0;
+  return value;
+}
+function toStatelessRegExp(re) {
+  const flags = re.flags.replace(/[gy]/g, "");
+  return flags === re.flags ? re : new RegExp(re.source, flags);
+}
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function host(matcher) {
+  const list = Array.isArray(matcher) ? matcher : [matcher];
+  const parts = list.map((m) => {
+    if (m instanceof RegExp) return `(?:${toStatelessRegExp(m).source})`;
+    return `(?:${escapeRegex(m.toLowerCase())})`;
+  });
+  return toStatelessRegExp(new RegExp(`^(?:${parts.join("|")})$`, "i"));
+}
+function isScopeObject(value) {
+  return "host" in value || "path" in value;
+}
+function compileScopes(input, pathOptions) {
+  if (input == null) return void 0;
+  const list = Array.isArray(input) ? input : [input];
+  const compilePath = (matcher) => {
+    if (Array.isArray(matcher)) {
+      const parts = matcher.map(
+        (m) => typeof m === "string" ? path(m, pathOptions) : toStatelessRegExp(m)
+      );
+      if (parts.length === 1) return parts[0];
+      return toStatelessRegExp(new RegExp(`(?:${parts.map((r) => `(?:${r.source})`).join("|")})`));
+    }
+    return typeof matcher === "string" ? path(matcher, pathOptions) : toStatelessRegExp(matcher);
+  };
+  const compiled = [];
+  for (const item of list) {
+    if (typeof item === "string" || item instanceof RegExp) {
+      compiled.push({ path: compilePath(item) });
+      continue;
+    }
+    if (item && typeof item === "object" && isScopeObject(item)) {
+      if (item.host == null && item.path == null) {
+        throw new Error("[proxy-chain] scope needs at least `host` or `path`");
+      }
+      compiled.push({
+        host: item.host != null ? host(item.host) : void 0,
+        path: item.path != null ? compilePath(item.path) : void 0
+      });
+      continue;
+    }
+    throw new Error("[proxy-chain] invalid include/exclude scope");
+  }
+  return compiled;
+}
+function scopeMatches(pathname, hostname, scope) {
+  if (scope.host) {
+    if (!hostname || !scope.host.test(hostname)) return false;
+  }
+  if (scope.path) {
+    if (!scope.path.test(pathname)) return false;
+  }
+  return true;
+}
+function toRule(entry) {
+  if (typeof entry === "function") {
+    const name2 = usefulName(entry.name);
+    return name2 ? { run: entry, name: name2 } : { run: entry };
+  }
+  const rule = entry;
+  const runName = typeof rule.run === "function" ? usefulName(rule.run.name) : void 0;
+  const name = usefulName(rule.name) ?? runName;
+  const harden = (scopes) => scopes?.map((s) => ({
+    host: s.host ? toStatelessRegExp(s.host) : void 0,
+    path: s.path ? toStatelessRegExp(s.path) : void 0
+  }));
+  return {
+    ...rule,
+    name: name ?? void 0,
+    include: harden(rule.include),
+    exclude: harden(rule.exclude)
+  };
+}
+function ruleLabel(rule, index) {
+  const runName = typeof rule.run === "function" ? usefulName(rule.run.name) : void 0;
+  return usefulName(rule.name) ?? runName ?? `rule#${index}`;
+}
+function withPaths(entry, filter) {
+  const base = toRule(entry);
+  const opts = filter.pathOptions;
+  const include = compileScopes(filter.include, opts);
+  const exclude = compileScopes(filter.exclude, opts);
+  const name = filter.name ?? base.name;
+  assertIncludeExcludeNoOverlap(include, exclude, name ?? "proxy");
+  return { run: base.run, include, exclude, name };
+}
+function ruleMatches(pathname, hostname, rule) {
+  if (rule.exclude?.some((scope) => scopeMatches(pathname, hostname, scope))) return false;
+  if (rule.include && !rule.include.some((scope) => scopeMatches(pathname, hostname, scope))) {
+    return false;
+  }
+  return true;
+}
+function pathMatches(pathname, rule) {
+  return ruleMatches(pathname, null, rule);
+}
+function normalizeHost(raw) {
+  if (!raw) return null;
+  const first = raw.split(",")[0]?.trim().toLowerCase();
+  if (!first) return null;
+  if (first.startsWith("[")) {
+    const end = first.indexOf("]");
+    return end === -1 ? first : first.slice(1, end);
+  }
+  const withoutPort = first.replace(/:\d+$/, "");
+  return withoutPort || null;
+}
+function parseCookieName(setCookie) {
+  const eq = setCookie.indexOf("=");
+  return (eq === -1 ? setCookie : setCookie.slice(0, eq)).trim();
+}
+function listSetCookie(headers) {
+  const extended = headers;
+  if (typeof extended.getSetCookie === "function") return extended.getSetCookie();
+  const single = headers.get("set-cookie");
+  return single ? [single] : [];
+}
+function cookieItemsFromHeaders(headers) {
+  const map = /* @__PURE__ */ new Map();
+  for (const value of listSetCookie(headers)) {
+    map.set(parseCookieName(value), value);
+  }
+  return map;
+}
+function responseHeaderItems(headers) {
+  const map = /* @__PURE__ */ new Map();
+  headers.forEach((value, key) => {
+    const lower = key.toLowerCase();
+    if (lower === "set-cookie") return;
+    if (lower.startsWith("x-middleware-next") || lower.startsWith("x-middleware-rewrite") || lower.startsWith("x-middleware-override-headers") || lower.startsWith("x-middleware-request-")) {
+      return;
+    }
+    map.set(key, value);
+  });
+  return map;
+}
+function decodeOverriddenRequestHeaders(headers) {
+  const result = new Headers();
+  const overrideHeaderNames = headers.get("x-middleware-override-headers");
+  if (overrideHeaderNames) {
+    for (const name of overrideHeaderNames.split(",")) {
+      const trimmed = name.trim();
+      const val = headers.get(`x-middleware-request-${trimmed}`);
+      if (val !== null) {
+        result.set(trimmed, val);
+      }
+    }
+  }
+  return result;
+}
+function mergeWrites(writes, strategy, onConflict) {
+  const resolved = /* @__PURE__ */ new Map();
+  const setBy = /* @__PURE__ */ new Map();
+  for (const write of writes) {
+    for (const [key, value] of write.items) {
+      const existing = resolved.get(key);
+      if (existing === void 0) {
+        resolved.set(key, value);
+        setBy.set(key, write.ruleName);
+        continue;
+      }
+      const previousRule = setBy.get(key);
+      if (typeof strategy === "function") {
+        const result = strategy(key, existing, value);
+        if (result === null) resolved.delete(key);
+        else resolved.set(key, result);
+        setBy.set(key, write.ruleName);
+        continue;
+      }
+      if (strategy === "first-write-wins") {
+        onConflict?.(key, previousRule, write.ruleName);
+        continue;
+      }
+      onConflict?.(key, write.ruleName, previousRule);
+      resolved.set(key, value);
+      setBy.set(key, write.ruleName);
+    }
+  }
+  return resolved;
+}
+function applyMergedToResponse(res, headers, cookies) {
+  for (const [key, value] of headers) {
+    res.headers.set(key, value);
+  }
+  res.headers.delete("set-cookie");
+  for (const cookie of cookies.values()) {
+    res.headers.append("set-cookie", cookie);
+  }
+}
+var DEFAULT_BLOCKED_REQUEST_HEADERS = [
+  "host",
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+  "content-length",
+  "cookie",
+  "authorization",
+  "x-forwarded-host",
+  "x-forwarded-for",
+  "x-forwarded-proto",
+  "x-real-ip",
+  "x-middleware-next",
+  "x-middleware-override-headers"
+];
+function normalizeHeaderName(name) {
+  return name.toLowerCase();
+}
+function isRequestHeaderAllowed(name, policy = {}) {
+  const key = normalizeHeaderName(name);
+  const allowed = new Set((policy.allowed ?? []).map(normalizeHeaderName));
+  if (allowed.has(key)) return true;
+  if (key.startsWith("x-middleware-")) return false;
+  const blocked = /* @__PURE__ */ new Set([
+    ...DEFAULT_BLOCKED_REQUEST_HEADERS.map(normalizeHeaderName),
+    ...(policy.blocked ?? []).map(normalizeHeaderName)
+  ]);
+  return !blocked.has(key);
+}
+function mergeRequestHeaderOverrides(target, overrides, policy = {}) {
+  const dropped = [];
+  let applied = 0;
+  overrides.forEach((value, key) => {
+    if (!isRequestHeaderAllowed(key, policy)) {
+      dropped.push(key);
+      return;
+    }
+    target.set(key, value);
+    applied++;
+  });
+  return { applied, dropped };
+}
+function headersInitToHeaders(init) {
+  return new Headers(init);
+}
+function headersDiffer(base, overrides) {
+  for (const [key, value] of overrides.entries()) {
+    if (base.get(key) !== value) return true;
+  }
+  return false;
+}
+function segmentToRegex(segment) {
+  if (segment === "**") return "(?:.*)";
+  if (segment === "*") return "[^/]+";
+  if (segment.startsWith(":")) return "[^/]+";
+  return escapeRegex(segment);
+}
+function path(pattern, options = {}) {
+  const { locales = [] } = options;
+  const localePrefix = locales.length > 0 ? `(?:(?:${locales.map(escapeRegex).join("|")})\\/)?` : "";
+  if (pattern instanceof RegExp) {
+    const body2 = pattern.source.replace(/^\^/, "").replace(/\$$/, "");
+    const needsStart = !pattern.source.startsWith("^");
+    const needsEnd = !pattern.source.endsWith("$");
+    return toStatelessRegExp(
+      new RegExp(
+        `${needsStart ? "^" : ""}${localePrefix ? `/${localePrefix}` : ""}${body2}${needsEnd ? "$" : ""}`,
+        pattern.flags
+      )
+    );
+  }
+  const normalized = (pattern.startsWith("/") ? pattern : `/${pattern}`).replace(/\/$/, "") || "/";
+  const segments = normalized.slice(1).split("/");
+  const trailingStar = segments.length > 0 && segments[segments.length - 1] === "*";
+  const suffix = trailingStar ? "(?:\\/.*)?$" : "$";
+  const body = trailingStar ? segments.slice(0, -1).map(segmentToRegex).concat("[^/]+").join("\\/") : segments.map(segmentToRegex).join("\\/");
+  return new RegExp(`^/${localePrefix}${body}${suffix}`);
+}
+function toPathRegex(matcher, options) {
+  const list = Array.isArray(matcher) ? matcher : [matcher];
+  const regexes = list.map((m) => path(m, options));
+  if (regexes.length === 1) return toStatelessRegExp(regexes[0]);
+  return toStatelessRegExp(new RegExp(`(?:${regexes.map((r) => `(?:${r.source})`).join("|")})`));
+}
+function scopeKey(scope) {
+  return `${scope.host?.source ?? "*"}::${scope.host?.flags ?? ""}|${scope.path?.source ?? "*"}::${scope.path?.flags ?? ""}`;
+}
+function assertIncludeExcludeNoOverlap(include, exclude, label) {
+  if (!include?.length || !exclude?.length) return;
+  const excluded = new Set(exclude.map(scopeKey));
+  for (const scope of include) {
+    if (excluded.has(scopeKey(scope))) {
+      throw new Error(
+        `[proxy-chain] ${label}: include and exclude share an identical scope. Remove one.`
+      );
+    }
+  }
+}
+var LEVEL_RANK = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40
+};
+function createConsoleLogger(minLevel = "info") {
+  const min = LEVEL_RANK[minLevel];
+  const write = (level) => (obj, msg) => {
+    if (LEVEL_RANK[level] < min) return;
+    if (typeof obj === "string") {
+      console[level](obj);
+      return;
+    }
+    const message = msg ?? "";
+    if (message) console[level](`[proxy-chain] ${message}`, obj);
+    else console[level]("[proxy-chain]", obj);
+  };
+  return {
+    debug: write("debug"),
+    info: write("info"),
+    warn: write("warn"),
+    error: write("error")
+  };
+}
+function formatDuration(ms) {
+  return `${ms.toFixed(2)}ms`;
+}
+function formatPipelineLine(input) {
+  const trace = input.traceId ? ` [${input.traceId.slice(0, 8)}]` : "";
+  const req = `${input.method} ${input.path}${trace}`;
+  const { name, outcome } = input;
+  switch (outcome.kind) {
+    case "passed":
+      return `[proxy-chain] \xB7 ${req} | ${name} (${formatDuration(outcome.duration)}) -> passed`;
+    case "next":
+      return `[proxy-chain] ~ ${req} | ${name} (${formatDuration(outcome.duration)}) -> headers mutated (${outcome.headers})`;
+    case "stop":
+      return `[proxy-chain] \xD7 ${req} | ${name} (${formatDuration(outcome.duration)}) -> stop ${outcome.status}`;
+  }
+}
+var RuleTimeoutError = class extends Error {
+  ruleName;
+  timeoutMs;
+  constructor(ruleName, timeoutMs) {
+    super(`[proxy-chain] ${ruleName} timed out after ${timeoutMs}ms`);
+    this.name = "RuleTimeoutError";
+    this.ruleName = ruleName;
+    this.timeoutMs = timeoutMs;
+  }
+};
+async function withRuleTimeout(promise, timeoutMs, ruleName) {
+  if (!timeoutMs || timeoutMs <= 0) return promise;
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new RuleTimeoutError(ruleName, timeoutMs)), timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_BLOCKED_REQUEST_HEADERS,
+  NEXT,
+  RuleTimeoutError,
+  applyMergedToResponse,
+  assertIncludeExcludeNoOverlap,
+  compileScopes,
+  cookieItemsFromHeaders,
+  createConsoleLogger,
+  createProxyContext,
+  decodeOverriddenRequestHeaders,
+  formatPipelineLine,
+  headersDiffer,
+  headersInitToHeaders,
+  host,
+  isNextResult,
+  isRequestHeaderAllowed,
+  listSetCookie,
+  mergeRequestHeaderOverrides,
+  mergeWrites,
+  next,
+  normalizeHost,
+  parseCookieName,
+  path,
+  pathMatches,
+  responseHeaderItems,
+  ruleLabel,
+  ruleMatches,
+  toPathRegex,
+  toRule,
+  toStatelessRegExp,
+  withPaths,
+  withRuleTimeout
+});

package/dist/core.d.cts

@@ -0,0 +1,210 @@
+/**
+ * Platform-agnostic proxy-chain primitives.
+ * No Next.js imports — unit-testable on any Web API runtime.
+ */
+/**
+ * Brand for an explicit "continue the chain" action.
+ * Mirrors the mental model of middleware `next()`, without relying on
+ * Next.js private response headers.
+ */
+declare const NEXT: unique symbol;
+type NextOptions = {
+    /** Request header overrides visible to later rules and the final handler. */
+    request?: HeadersInit;
+    /** Response headers merged into the eventual outgoing response (last-write-wins). */
+    headers?: HeadersInit;
+};
+/**
+ * Continue the pipeline. Prefer this over returning a framework `NextResponse.next()`.
+ *
+ * @example
+ * return next({ request: { "x-request-id": id }, headers: { "x-request-id": id } })
+ */
+type NextResult = NextOptions & {
+    readonly [NEXT]: true;
+};
+declare function next(options?: NextOptions): NextResult;
+declare function isNextResult(value: unknown): value is NextResult;
+/**
+ * Shared state for one request. `Map` avoids prototype-poisoning risks that
+ * come with plain objects and attacker-controlled keys.
+ */
+type ProxyContext = Map<string, unknown>;
+declare function createProxyContext(): ProxyContext;
+type ProxyResult<TResponse> = TResponse | NextResult | undefined | void;
+type PathMatcher = RegExp | string;
+type PathOptions = {
+    /** Optional locale prefixes, e.g. next-intl `as-needed` routes. */
+    locales?: readonly string[];
+};
+type HostMatcher = string | RegExp | readonly (string | RegExp)[];
+/**
+ * One include/exclude clause.
+ *
+ * - `path("/admin/*")` — that path on **any** host
+ * - `{ host: "shop.localhost" }` — **any** path on that host
+ * - `{ host: "shop.localhost", path: "/checkout/*" }` — both must match
+ *
+ * Lists are OR. Exclude is checked before include and always wins.
+ */
+type RouteScopeInput = PathMatcher | {
+    host: HostMatcher;
+    path?: PathMatcher | PathMatcher[];
+} | {
+    path: PathMatcher | PathMatcher[];
+    host?: HostMatcher;
+};
+type RouteScopeList = RouteScopeInput | RouteScopeInput[];
+/** Compiled clause used at request time. Missing host/path means "any". */
+type CompiledScope = {
+    host?: RegExp;
+    path?: RegExp;
+};
+interface BaseProxyRule<TFn> {
+    run: TFn;
+    include?: CompiledScope[];
+    exclude?: CompiledScope[];
+    name?: string;
+}
+type ProxyPathFilter = {
+    include?: RouteScopeList;
+    exclude?: RouteScopeList;
+    pathOptions?: PathOptions;
+    name?: string;
+};
+type Entry<TFn> = TFn | BaseProxyRule<TFn>;
+/**
+ * Sticky RegExp flags (`g`, `y`) mutate `lastIndex` on each `.test()`.
+ * On Edge, one compiled pattern is shared across concurrent requests, so a
+ * sticky flag can make path matching flip between true/false spuriously.
+ * Always compile path filters without those flags.
+ */
+declare function toStatelessRegExp(re: RegExp): RegExp;
+/**
+ * Build a host matcher RegExp from exact names and/or patterns.
+ * Exact strings are anchored; RegExp sources are OR-combined (sticky flags stripped).
+ */
+declare function host(matcher: HostMatcher): RegExp;
+/**
+ * Compile user-facing include/exclude into stateless host/path clauses.
+ * Strings/globs go through `path()` (locale options apply). Raw RegExp is kept as-is
+ * (only sticky flags stripped) so prefix patterns like `/^\/admin/` keep working.
+ */
+declare function compileScopes(input: RouteScopeList | undefined, pathOptions?: PathOptions): CompiledScope[] | undefined;
+declare function toRule<TFn>(entry: Entry<TFn>): BaseProxyRule<TFn>;
+declare function ruleLabel<TFn>(rule: BaseProxyRule<TFn>, index: number): string;
+/**
+ * Scope a rule with path/host filters.
+ */
+declare function withPaths<TFn>(entry: Entry<TFn>, filter: ProxyPathFilter): BaseProxyRule<TFn>;
+/**
+ * Whether a rule applies to this request.
+ *
+ * Rules:
+ * 1. If any `exclude` clause matches -> skip (exclude wins).
+ * 2. If `include` is set -> run only when at least one clause matches (OR).
+ * 3. Path-only clauses apply to every host; host-only clauses apply to every path.
+ * 4. Mixing bare paths with host-scoped paths is not a conflict: OR widens the match.
+ */
+declare function ruleMatches<TFn>(pathname: string, hostname: string | null, rule: BaseProxyRule<TFn>): boolean;
+/** Path-only helper for tests (host treated as unrestricted). */
+declare function pathMatches<TFn>(pathname: string, rule: BaseProxyRule<TFn>): boolean;
+/** Normalize `Host` / `X-Forwarded-Host` into a bare lowercase hostname (no port). */
+declare function normalizeHost(raw: string | null | undefined): string | null;
+declare function parseCookieName(setCookie: string): string;
+/**
+ * Collect `Set-Cookie` entries. Prefer the multi-value `getSetCookie()` API;
+ * a single `get("set-cookie")` is only a last-resort fallback on older runtimes.
+ */
+declare function listSetCookie(headers: Headers): string[];
+declare function cookieItemsFromHeaders(headers: Headers): Map<string, string>;
+/**
+ * Response headers eligible for merge.
+ * Filters out `set-cookie` and internal Next.js middleware headers (`x-middleware-*`)
+ * to prevent leaking internal transport headers to client responses.
+ */
+declare function responseHeaderItems(headers: Headers): Map<string, string>;
+/**
+ * Decode request header overrides encoded by Next.js `NextResponse.next({ request: { headers } })`.
+ */
+declare function decodeOverriddenRequestHeaders(headers: Headers): Headers;
+interface EntryWrite {
+    ruleIndex: number;
+    ruleName: string;
+    items: Map<string, string>;
+}
+type MergeStrategy = "last-write-wins" | "first-write-wins" | ((key: string, existing: string, incoming: string) => string | null);
+declare function mergeWrites(writes: EntryWrite[], strategy: MergeStrategy, onConflict?: (key: string, winner: string, loser: string) => void): Map<string, string>;
+/**
+ * Apply merged headers and cookies onto the terminal response.
+ *
+ * Headers use last-write-wins via `set` (overwrite).
+ * Cookies are rebuilt from a name->value map so the same cookie never appears
+ * twice — browsers and CDNs behave unpredictably with duplicate Set-Cookie.
+ */
+declare function applyMergedToResponse(res: Response, headers: Map<string, string>, cookies: Map<string, string>): void;
+/**
+ * Headers that must not be rewritten by a rule unless explicitly allow-listed.
+ * Covers hop-by-hop framing, identity, Next.js internal headers, and common trust headers.
+ */
+declare const DEFAULT_BLOCKED_REQUEST_HEADERS: readonly ["host", "connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer", "transfer-encoding", "upgrade", "content-length", "cookie", "authorization", "x-forwarded-host", "x-forwarded-for", "x-forwarded-proto", "x-real-ip", "x-middleware-next", "x-middleware-override-headers"];
+type RequestHeaderPolicy = {
+    blocked?: readonly string[];
+    /** Opt-in exceptions to the block list (lower-case names). */
+    allowed?: readonly string[];
+};
+declare function isRequestHeaderAllowed(name: string, policy?: RequestHeaderPolicy): boolean;
+declare function mergeRequestHeaderOverrides(target: Headers, overrides: Headers, policy?: RequestHeaderPolicy): {
+    applied: number;
+    dropped: string[];
+};
+declare function headersInitToHeaders(init?: HeadersInit): Headers;
+declare function headersDiffer(base: Headers, overrides: Headers): boolean;
+/**
+ * Build a stateless path matcher from a glob, param path, or RegExp.
+ *
+ * @example
+ * path("/admin/*")
+ * path("/admin/:id")
+ * path("/admin/*", { locales: ["en", "pl"] })
+ */
+declare function path(pattern: string | RegExp, options?: PathOptions): RegExp;
+declare function toPathRegex(matcher: PathMatcher | PathMatcher[], options?: PathOptions): RegExp;
+/** Throw when the same clause appears in both include and exclude (always a no-op / footgun). */
+declare function assertIncludeExcludeNoOverlap(include: CompiledScope[] | undefined, exclude: CompiledScope[] | undefined, label: string): void;
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface ChainLogger {
+    debug: (obj: unknown, msg?: string) => void;
+    info: (obj: unknown, msg?: string) => void;
+    warn: (obj: unknown, msg?: string) => void;
+    error: (obj: unknown, msg?: string) => void;
+}
+declare function createConsoleLogger(minLevel?: LogLevel): ChainLogger;
+type PipelineOutcome = {
+    kind: "passed";
+    duration: number;
+} | {
+    kind: "next";
+    duration: number;
+    headers: number;
+} | {
+    kind: "stop";
+    duration: number;
+    status: number;
+};
+/** One line per executed rule — method + path first so parallel Edge logs stay scannable. */
+declare function formatPipelineLine(input: {
+    method: string;
+    path: string;
+    name: string;
+    traceId?: string;
+    outcome: PipelineOutcome;
+}): string;
+declare class RuleTimeoutError extends Error {
+    readonly ruleName: string;
+    readonly timeoutMs: number;
+    constructor(ruleName: string, timeoutMs: number);
+}
+declare function withRuleTimeout<T>(promise: Promise<T>, timeoutMs: number | undefined, ruleName: string): Promise<T>;
+
+export { type BaseProxyRule, type ChainLogger, type CompiledScope, DEFAULT_BLOCKED_REQUEST_HEADERS, type EntryWrite, type HostMatcher, type LogLevel, type MergeStrategy, NEXT, type NextOptions, type NextResult, type PathMatcher, type PathOptions, type PipelineOutcome, type ProxyContext, type ProxyPathFilter, type ProxyResult, type RequestHeaderPolicy, type RouteScopeInput, type RouteScopeList, RuleTimeoutError, applyMergedToResponse, assertIncludeExcludeNoOverlap, compileScopes, cookieItemsFromHeaders, createConsoleLogger, createProxyContext, decodeOverriddenRequestHeaders, formatPipelineLine, headersDiffer, headersInitToHeaders, host, isNextResult, isRequestHeaderAllowed, listSetCookie, mergeRequestHeaderOverrides, mergeWrites, next, normalizeHost, parseCookieName, path, pathMatches, responseHeaderItems, ruleLabel, ruleMatches, toPathRegex, toRule, toStatelessRegExp, withPaths, withRuleTimeout };