@klnap/next-proxy-chain 1.0.1 → 1.0.2

package/README.md

@@ -1,250 +1,221 @@
 # @klnap/next-proxy-chain
 
-> Composable Next.js 16+ Edge proxy and middleware rule chain with deterministic header/cookie accumulation, isolated per-request context, and a pure Web API core.
-
-[![npm version](https://img.shields.io/npm/v/@klnap/next-proxy-chain.svg)](https://www.npmjs.com/package/@klnap/next-proxy-chain)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6.svg)](https://www.typescriptlang.org/)
-[![Runtime: Edge / Node / Bun / Deno](https://img.shields.io/badge/Runtime-Edge%20%7C%20Node%20%7C%20Bun%20%7C%20Deno-black.svg)](https://bun.sh)
+A composable request-chaining and proxy engine for Next.js architectures with deterministic header and cookie accumulation, isolated request context, and a pure core design.
 
 ---
 
-## Why `@klnap/next-proxy-chain`?
+## Overview & Motivation
 
-Next.js 16 introduces the `proxy.ts` file convention to replace monolithic middleware files. In non-trivial production applications, middleware pipelines easily devolve into deeply nested wrappers, conflicting `Set-Cookie` headers, race conditions from stateful regular expressions, and leaked transport headers.
+In modern Next.js architectures, edge routing, backend-for-frontend (BFF) layers, multi-tenant resolution, and security policies frequently require multi-hop request processing. Standard monolithic middleware implementations lead to architectural challenges:
 
-`@klnap/next-proxy-chain` solves this by providing:
+- **Nested Wrapper Hell**: Composing authentication, localization, rate limiting, and multi-tenant routing often results in deeply nested higher-order functions with fragile control flow.
+- **Header Mutation Conflicts**: Independent middleware steps often overwrite request headers (`x-middleware-request-*`) or drop previously injected values.
+- **Cookie Directive Overwrites**: Multiple intermediate steps setting `Set-Cookie` directives risk clobbering each other or emitting duplicate headers that CDNs and browsers handle unpredictably.
+- **Stateful Concurrency Hazards**: Shared state or stateful regular expressions (such as `RegExp` instances with global `g` or sticky `y` flags) cause non-deterministic route matching under high concurrency in Edge worker runtimes.
+- **Header Injection Vulnerabilities**: Untrusted incoming requests can attempt to manipulate protected transport headers such as `Host`, `Authorization`, or Next.js internal headers (`x-middleware-*`).
 
-1. **Linear Pipeline Execution**: Run multiple independent proxy rules sequentially without nested wrapper callbacks.
-2. **Deterministic Header & Cookie Merging**: Combines request mutations (`x-middleware-request-*`), outgoing response headers, and multiple `Set-Cookie` directives without silent overwrites.
-3. **Pure Web API Core**: Zero Next.js dependencies in `@klnap/next-proxy-chain/core` — fully testable on Cloudflare Workers, Fastly, Bun, Deno, and standard Web runtimes.
-4. **Edge Runtime Hardening**: Strips stateful RegExp flags (`g`, `y`) to eliminate concurrent request cross-talk in multi-tenant edge workers, enforces per-rule timeouts, and protects against prototype pollution via `Map` context.
-5. **Header Poisoning Defense**: Protects client responses by stripping sensitive transport headers (`x-middleware-*`) and blocks unauthorized override of protected headers (`Host`, `Authorization`, `Connection`).
+`next-proxy-chain` provides a linear, deterministic execution pipeline with zero framework-specific adapter boilerplate. It executes natively in both Next.js 15 (`middleware.ts`) and Next.js 16 (`proxy.ts`).
 
 ---
 
 ## Installation
 
-```bash
-# Using Bun
-bun add @klnap/next-proxy-chain
+Install the package via your preferred package manager:
 
-# Using npm
+```bash
+# npm
 npm install @klnap/next-proxy-chain
 
-# Using pnpm
+# bun
+bun add @klnap/next-proxy-chain
+
+# pnpm
 pnpm add @klnap/next-proxy-chain
 
-# Using Yarn
+# yarn
 yarn add @klnap/next-proxy-chain
 ```
 
 ---
 
-## Quick Start
+## Core Architecture
+
+`next-proxy-chain` orchestrates incoming requests through a linear pipeline of isolated rules:
+
+```
+[Incoming Request]
+        │
+        ▼
+ ┌──────────────┐
+ │ createContext│  ───> Map<string, unknown> (Isolated per request)
+ └──────┬───────┘
+        │
+        ▼
+ ┌──────────────┐   (Matched by path/host filter)
+ │    Rule 1    │  ───> return next({ request, headers })
+ └──────┬───────┘
+        │ Materializes mutated NextRequest only when next rule executes
+        ▼
+ ┌──────────────┐   (Matched by path/host filter)
+ │    Rule 2    │  ───> return next() | NextResponse.redirect()
+ └──────┬───────┘
+        │
+        ▼
+ ┌──────────────┐
+ │ Final Merge  │  ───> Merges all request overrides, response headers, & cookies
+ └──────┬───────┘
+        │
+        ▼
+[Outgoing NextResponse / Response]
+```
 
-### 1. Define Modular Proxy Rules
+### Key Architectural Properties
 
-Create self-contained proxy rules in your application:
+1. **Pure Core**: The underlying rule engine operates strictly on Web Standards (`Request`, `Response`, `Headers`, `URL`, `Map`).
+2. **Deterministic Conflict Resolution**: Outgoing response headers and cookies are merged according to configurable strategies (`last-write-wins`, `first-write-wins`, or custom resolvers).
+3. **Lazy Request Materialization**: Cloned `NextRequest` objects are only instantiated when downstream rules read mutated headers, minimizing memory allocations.
+4. **Edge Runtime Hardening**: Strips `g` and `y` flags from regular expressions to prevent race conditions during concurrent request processing.
+5. **Fail-Safe Recovery**: Unhandled rule exceptions are caught and routed through optional `onError` handlers, falling back to a safe HTTP 500 response.
 
-```typescript
-// src/proxies/request-id.ts
-import { defineProxy, next } from "@klnap/next-proxy-chain"
+---
 
-export const requestIdProxy = defineProxy("requestId", (req) => {
-  const requestId = req.headers.get("x-request-id") ?? crypto.randomUUID()
+## Integration Guide
 
-  return next({
-    request: { "x-request-id": requestId },
-    headers: { "x-request-id": requestId },
-  })
-})
-```
+### Next.js 15 Integration (`middleware.ts`)
+
+In Next.js 15, export the proxy chain directly as the middleware handler:
 
 ```typescript
-// src/proxies/auth.ts
-import { defineProxy, next } from "@klnap/next-proxy-chain"
+// middleware.ts
+import { defineProxy, next, path, proxyChain } from "@klnap/next-proxy-chain"
 import { NextResponse } from "next/server"
 
-export const authProxy = defineProxy("auth", async (req, ctx) => {
-  const token = req.cookies.get("session_token")?.value
+const requestIdProxy = defineProxy("requestId", (req) => {
+  const id = req.headers.get("x-request-id") ?? crypto.randomUUID()
+  return next({
+    request: { "x-request-id": id },
+    headers: { "x-request-id": id },
+  })
+})
+
+const authProxy = defineProxy("auth", async (req, ctx) => {
+  const token = req.cookies.get("session")?.value
 
   if (!token) {
-    const loginUrl = new URL("/login", req.url)
-    loginUrl.searchParams.set("from", req.nextUrl.pathname)
-    return NextResponse.redirect(loginUrl)
+    return NextResponse.redirect(new URL("/login", req.url))
   }
 
-  // Store user info in isolated per-request context
-  ctx.set("userId", "user_abc123")
+  ctx.set("userId", "usr_100")
   return next()
 })
-```
-
-### 2. Assemble Pipeline in `src/proxy.ts` (Next.js 16)
-
-```typescript
-// src/proxy.ts
-import { proxyChain, path } from "@klnap/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 }, [
-  // 1. Injects request ID on all incoming traffic
+export const middleware = proxyChain([
   requestIdProxy,
-
-  // 2. Guards dashboard routes, excluding public preview assets
-  authProxy({
-    include: path("/dashboard/*"),
-    exclude: path("/dashboard/public/*"),
-  }),
-
-  // 3. Handles internationalization routing
-  i18nProxy,
+  authProxy({ include: path("/dashboard/*") }),
 ])
 
 export const config = {
-  matcher: "/((?!api|_next|.*\\..*).*)",
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
 }
 ```
 
----
-
-## Route & Host Scoping
+### Next.js 16 Integration (`proxy.ts`)
 
-Rules can be declaratively scoped by path, host, or combinations. Scoping evaluates exclusions first — if an exclusion matches, the rule is skipped immediately.
+In Next.js 16, export the proxy chain as default or named `proxy` export:
 
 ```typescript
-import { defineProxy, path, host } from "@klnap/next-proxy-chain"
+// proxy.ts
+import { defineProxy, host, next, path, proxyChain } from "@klnap/next-proxy-chain"
+import { NextResponse } from "next/server"
 
-// Scoped to specific path patterns on ANY host
-const adminRule = defineProxy("admin", handler, {
-  include: path("/admin/*"),
-})
+const multiTenantProxy = defineProxy("multiTenant", (req, ctx) => {
+  const hostname = req.headers.get("host") ?? ""
 
-// Scoped to a specific domain or tenant
-const tenantRule = defineProxy("tenant", handler, {
-  include: { host: "app.example.com" },
-})
+  if (hostname.startsWith("admin.")) {
+    ctx.set("tenant", "admin")
+    return next({
+      request: { "x-tenant-id": "admin-portal" },
+    })
+  }
 
-// Scoped to specific path on a specific host
-const checkoutRule = defineProxy("checkout", handler, {
-  include: { host: "store.example.com", path: "/checkout/*" },
-})
+  if (hostname.startsWith("app.")) {
+    ctx.set("tenant", "app")
+    return next({
+      request: { "x-tenant-id": "customer-app" },
+    })
+  }
 
-// Array of clauses (OR evaluation) with strict exclusions
-const apiRule = defineProxy("apiGuard", handler, {
-  include: [
-    path("/api/v1/*"),
-    { host: "api.example.com" },
-  ],
-  exclude: [
-    path("/api/v1/health"),
-    { host: "internal.example.com" },
-  ],
+  return next()
 })
-```
-
----
 
-## Deterministic Header & Cookie Merging
-
-When multiple rules in the chain mutate headers or cookies, `@klnap/next-proxy-chain` merges them deterministically:
-
-- **Request Overrides (`next({ request: { ... } })`)**: Downstream rules and final page route handlers receive the accumulated mutated headers via Next.js request override encoding.
-- **Response Headers (`next({ headers: { ... } })`)**: Accumulated using last-write-wins strategy, written to the terminal response.
-- **Cookies (`Set-Cookie`)**: Multiple `Set-Cookie` directives across different rules are deduplicated by name and path attributes without dropping earlier cookies.
-
-```typescript
-import { defineProxy, next } from "@klnap/next-proxy-chain"
-
-export const headerEnricher = defineProxy("enricher", () => {
+const securityHeadersProxy = defineProxy("securityHeaders", () => {
   return next({
-    request: {
-      "x-geo-region": "eu-central",
-    },
     headers: {
       "x-content-type-options": "nosniff",
       "x-frame-options": "DENY",
     },
   })
 })
-```
-
----
-
-## Pure Web API Core (`@klnap/next-proxy-chain/core`)
-
-For non-Next.js environments (Cloudflare Workers, Fastly Compute, Deno Deploy, Bun HTTP servers), use the pure core subpath:
-
-```typescript
-import {
-  createProxyContext,
-  mergeWrites,
-  withPaths,
-  next,
-  isNextResult,
-  toStatelessRegExp
-} from "@klnap/next-proxy-chain/core"
-
-// Zero dependencies on next/server — standard Fetch API only
-const context = createProxyContext()
-```
-
----
 
-## Error Handling & Timeout Budgets
-
-Prevent unresponsive downstream authentication services or external APIs from blocking Edge execution:
-
-```typescript
-import { proxyChain } from "@klnap/next-proxy-chain"
-import { NextResponse } from "next/server"
-
-export default proxyChain(
-  {
-    timeoutMs: 3000, // Global timeout budget per rule in milliseconds
-    onError: (error, ruleIndex, req, ctx) => {
-      console.error(`Rule at index ${ruleIndex} failed:`, error)
-      return new NextResponse("Service Temporarily Unavailable", { status: 503 })
-    },
-  },
-  [
-    // rules...
-  ]
-)
+export default proxyChain({ debug: process.env.NODE_ENV !== "production" }, [
+  multiTenantProxy,
+  securityHeadersProxy,
+])
 ```
 
 ---
 
 ## API Reference
 
-### Exported Functions (`@klnap/next-proxy-chain`)
-
-| Function | Description |
+### Core Functions
+
+| Function | Parameters | Return Type | Description |
+| :--- | :--- | :--- | :--- |
+| `proxyChain(rules)` | `Entry<TContext>[]` | `(req: NextRequest, event: NextFetchEvent) => Promise<NextResponse \| Response>` | Creates an execution pipeline from an array of rules. |
+| `proxyChain(options, rules)` | `ProxyChainOptions<TContext>, Entry<TContext>[]` | `(req: NextRequest, event: NextFetchEvent) => Promise<NextResponse \| Response>` | Creates an execution pipeline with custom configuration. |
+| `defineProxy(name?, fn)` | `string?, ProxyFn<TContext>` | `DefinedProxy<TContext>` | Creates a reusable rule with path and host scoping capabilities. |
+| `next(options?)` | `NextOptions?` | `NextResult` | Generates a pipeline continuation token with optional header mutations. |
+| `path(pattern, options?)` | `string \| RegExp, PathOptions?` | `RegExp` | Compiles a glob pattern, parameterized route, or regex into a stateless path matcher. |
+| `host(matcher)` | `HostMatcher` | `RegExp` | Compiles a single or list of hostnames/patterns into an anchored host matcher. |
+| `createProxyContext()` | `None` | `ProxyContext` | Instantiates a new Map instance for isolated request context storage. |
+
+### Configuration Options (`ProxyChainOptions`)
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `createContext` | `(req: NextRequest, event: NextFetchEvent) => TContext` | `() => new Map()` | Custom factory function for request context instantiation. |
+| `cookieMergeStrategy` | `MergeStrategy` | `"last-write-wins"` | Strategy for resolving conflicting `Set-Cookie` directives across rules. |
+| `headerMergeStrategy` | `MergeStrategy` | `"last-write-wins"` | Strategy for resolving conflicting response headers. |
+| `debug` | `boolean` | `false` | Enables structured single-line execution logs for each rule. |
+| `ruleTimeoutMs` | `number` | `0` | Wall-clock execution budget per rule in milliseconds (`0` disables timeout). |
+| `requestHeaderPolicy` | `RequestHeaderPolicy` | `{}` | Custom policy defining blocked and allowed request header mutations. |
+| `strictOverrideCheck` | `boolean` | `false` | Throws an exception at initialization if platform request overrides are unsupported. |
+| `onError` | `(err, index, req, ctx) => Response \| undefined` | `undefined` | Hook invoked when a rule throws an exception to allow custom error recovery. |
+
+### Rule Scoping Options (`ProxyPathFilter`)
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `include` | `RouteScopeList` | Routes or hosts where the rule must execute. |
+| `exclude` | `RouteScopeList` | Routes or hosts where the rule must be skipped (takes precedence over `include`). |
+| `name` | `string` | Human-readable identifier used for logs and diagnostic metrics. |
+| `pathOptions` | `PathOptions` | Route compilation options, such as locale prefixes (`locales`). |
+
+### Return Value Protocol
+
+A `ProxyFn` rule function must return one of the following:
+
+| Return Value | Pipeline Behavior |
 | :--- | :--- |
-| `proxyChain(options?, rules)` | Assembles rules into a Next.js proxy/middleware handler. |
-| `defineProxy(name, fn, filter?)` | Factory creating a reusable, scope-aware proxy rule function. |
-| `withPaths(fn, filter)` | Wraps a raw proxy function with declarative path/host matching rules. |
-| `next(options?)` | Returns a continuation action with optional `{ request?, headers? }` mutations. |
-| `path(pattern)` | Helper compiling glob or RegExp string into a path matcher. |
-| `host(matcher)` | Helper compiling domain or RegExp matcher into a host matcher. |
-| `createProxyContext()` | Creates a clean, isolated `Map<string, unknown>` context. |
-| `decodeOverriddenRequestHeaders(headers)` | Extracts internal Next.js middleware request header overrides. |
-
-### Exported Types
-
-- `ProxyFn<TContext>`: Contract for individual proxy execution functions.
-- `ProxyRule<TContext>`: Composed rule containing execution handler and compiled scope filters.
-- `ProxyContext`: Isolated `Map<string, unknown>` instance passed to each rule.
-- `NextResult`: Continuation action containing mutation payloads.
-- `ProxyPathFilter`: Declarative configuration containing `include` and `exclude` clauses.
+| `next({ request?, headers? })` | Continues execution, staging request header mutations and response headers. |
+| `undefined` or `void` | Continues execution without mutating headers or state. |
+| `NextResponse.next()` | Continues execution while extracting any internal request header overrides. |
+| `NextResponse.rewrite(url)` | Continues execution while setting the rewrite target for downstream rules. |
+| `NextResponse.redirect(url)` | Halts pipeline execution immediately and returns the redirect response. |
+| `NextResponse.json(...)` or `Response` | Halts pipeline execution immediately and returns the terminal response. |
 
 ---
 
 ## License
 
-MIT © [klnap](https://github.com/klnap)
+MIT