@klnap/next-proxy-chain 1.0.0

package/README.md

@@ -0,0 +1,126 @@
+# `@repo/next-proxy-chain`
+
+Composable Next.js Edge proxy pipeline with pure Web API core, pass-through detection, context threading, header/cookie accumulation, and zero external runtime dependencies.
+
+---
+
+## Key Features
+
+- **Linear Pipeline Composition**: Order middleware steps clearly without nested wrapper hell.
+- **Pass-through Interoperability**: Transparently supports `NextResponse.next()` from third-party middlewares via `x-middleware-next: 1` detection.
+- **Per-request Context**: Type-safe, isolated `Map` context (`TContext`) threaded across all rules.
+- **Header & Cookie Accumulation**: Collects and merges request headers, response headers, and cookies across rules before writing to the outgoing response.
+- **Host & Path Scoping**: Declarative `include` / `exclude` routing rules with glob, RegExp, and next-intl locale support.
+- **Header Injection & Leak Protection**: Automatically filters internal `x-middleware-*` transport headers from client responses.
+- **100% Edge-Safe**: Built purely on standard Web APIs (`Headers`, `Map`, `Response`, `Request`).
+
+---
+
+## Quick Start
+
+### 1. Define Reusable Proxies
+
+```ts
+import { defineProxy, next } from "@repo/next-proxy-chain"
+
+// Request ID injector
+export const requestIdProxy = defineProxy("requestId", (req) => {
+  const id = crypto.randomUUID()
+  return next({
+    request: { "x-request-id": id },
+    headers: { "x-request-id": id },
+  })
+})
+
+// Authentication guard
+export const authProxy = defineProxy("auth", async (req, ctx) => {
+  const token = req.cookies.get("auth-token")?.value
+  if (!token) {
+    return NextResponse.redirect(new URL("/login", req.url))
+  }
+  ctx.set("userId", "user_123")
+  return next()
+})
+```
+
+### 2. Assemble the Pipeline in `proxy.ts`
+
+```ts
+import { proxyChain, path } from "@repo/next-proxy-chain"
+import { requestIdProxy } from "./proxies/request-id"
+import { authProxy } from "./proxies/auth"
+import { i18nProxy } from "./proxies/i18n"
+
+const isDev = process.env.NODE_ENV !== "production"
+
+export default proxyChain({ debug: isDev }, [
+  requestIdProxy,
+  authProxy({
+    include: path("/dashboard/*"),
+    exclude: path("/dashboard/public"),
+  }),
+  i18nProxy,
+])
+
+export const config = {
+  matcher: "/((?!api|_next|.*\\..*).*)",
+}
+```
+
+---
+
+## Scope Matching Rules
+
+Scoping supports globs, RegExps, host matching, and combinations:
+
+```ts
+// Path on any host
+include: path("/admin/*")
+
+// Any path on a specific host
+include: { host: "shop.localhost" }
+
+// Specific path on a specific host
+include: { host: "shop.localhost", path: "/checkout/*" }
+
+// OR combinations
+include: [
+  path("/health"),
+  { host: "shop.localhost", path: "/checkout/*" },
+]
+
+// Exclude always wins
+exclude: { host: "museum.localhost" }
+```
+
+---
+
+## Error Handling
+
+By default, any unhandled error inside a rule logs safely and returns an HTTP 500 (`safeInternalError`). You can supply a custom `onError` handler:
+
+```ts
+export default proxyChain(
+  {
+    onError: (err, ruleIndex, req, ctx) => {
+      return new NextResponse("Service Unavailable", { status: 503 })
+    },
+  },
+  [
+    // rules...
+  ]
+)
+```
+
+---
+
+## API Reference
+
+### Core Functions
+
+- `proxyChain(options?, rules)`: Combines rules into an Edge proxy handler.
+- `defineProxy(name?, fn)`: Creates a proxy function that can be called with `{ include, exclude }` to scope.
+- `withPaths(rule, filter)`: Scopes any rule function with path/host filters.
+- `next(options?)`: Signals pipeline continuation with optional `{ request?, headers? }` mutations.
+- `decodeOverriddenRequestHeaders(headers)`: Extracts Next.js middleware request header overrides.
+- `createProxyContext()`: Instantiates a fresh `Map` for per-request context.

package/dist/chunk-PTAOIFNB.js

@@ -0,0 +1,412 @@
+// src/core.ts
+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);
+  }
+}
+
+export {
+  NEXT,
+  next,
+  isNextResult,
+  createProxyContext,
+  toStatelessRegExp,
+  host,
+  compileScopes,
+  toRule,
+  ruleLabel,
+  withPaths,
+  ruleMatches,
+  pathMatches,
+  normalizeHost,
+  parseCookieName,
+  listSetCookie,
+  cookieItemsFromHeaders,
+  responseHeaderItems,
+  decodeOverriddenRequestHeaders,
+  mergeWrites,
+  applyMergedToResponse,
+  DEFAULT_BLOCKED_REQUEST_HEADERS,
+  isRequestHeaderAllowed,
+  mergeRequestHeaderOverrides,
+  headersInitToHeaders,
+  headersDiffer,
+  path,
+  toPathRegex,
+  assertIncludeExcludeNoOverlap,
+  createConsoleLogger,
+  formatPipelineLine,
+  RuleTimeoutError,
+  withRuleTimeout
+};