@klnap/next-proxy-chain 1.0.0 → 1.0.2

package/README.md

@@ -1,126 +1,221 @@
-# `@repo/next-proxy-chain`
+# @klnap/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.
+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.
 
 ---
 
-## Key Features
+## Overview & Motivation
 
-- **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`).
+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:
+
+- **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-*`).
+
+`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`).
 
 ---
 
-## Quick Start
+## Installation
+
+Install the package via your preferred package manager:
+
+```bash
+# npm
+npm install @klnap/next-proxy-chain
+
+# bun
+bun add @klnap/next-proxy-chain
+
+# pnpm
+pnpm add @klnap/next-proxy-chain
 
-### 1. Define Reusable Proxies
+# yarn
+yarn add @klnap/next-proxy-chain
+```
+
+---
 
-```ts
-import { defineProxy, next } from "@repo/next-proxy-chain"
+## Core Architecture
 
-// Request ID injector
-export const requestIdProxy = defineProxy("requestId", (req) => {
-  const id = crypto.randomUUID()
+`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]
+```
+
+### Key Architectural Properties
+
+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.
+
+---
+
+## Integration Guide
+
+### Next.js 15 Integration (`middleware.ts`)
+
+In Next.js 15, export the proxy chain directly as the middleware handler:
+
+```typescript
+// middleware.ts
+import { defineProxy, next, path, proxyChain } from "@klnap/next-proxy-chain"
+import { NextResponse } from "next/server"
+
+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 },
   })
 })
 
-// Authentication guard
-export const authProxy = defineProxy("auth", async (req, ctx) => {
-  const token = req.cookies.get("auth-token")?.value
+const authProxy = defineProxy("auth", async (req, ctx) => {
+  const token = req.cookies.get("session")?.value
+
   if (!token) {
     return NextResponse.redirect(new URL("/login", req.url))
   }
-  ctx.set("userId", "user_123")
+
+  ctx.set("userId", "usr_100")
   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 }, [
+export const middleware = proxyChain([
   requestIdProxy,
-  authProxy({
-    include: path("/dashboard/*"),
-    exclude: path("/dashboard/public"),
-  }),
-  i18nProxy,
+  authProxy({ include: path("/dashboard/*") }),
 ])
 
 export const config = {
-  matcher: "/((?!api|_next|.*\\..*).*)",
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
 }
 ```
 
----
+### Next.js 16 Integration (`proxy.ts`)
 
-## Scope Matching Rules
+In Next.js 16, export the proxy chain as default or named `proxy` export:
 
-Scoping supports globs, RegExps, host matching, and combinations:
+```typescript
+// proxy.ts
+import { defineProxy, host, next, path, proxyChain } from "@klnap/next-proxy-chain"
+import { NextResponse } from "next/server"
 
-```ts
-// Path on any host
-include: path("/admin/*")
+const multiTenantProxy = defineProxy("multiTenant", (req, ctx) => {
+  const hostname = req.headers.get("host") ?? ""
 
-// Any path on a specific host
-include: { host: "shop.localhost" }
+  if (hostname.startsWith("admin.")) {
+    ctx.set("tenant", "admin")
+    return next({
+      request: { "x-tenant-id": "admin-portal" },
+    })
+  }
 
-// Specific path on a specific host
-include: { host: "shop.localhost", path: "/checkout/*" }
+  if (hostname.startsWith("app.")) {
+    ctx.set("tenant", "app")
+    return next({
+      request: { "x-tenant-id": "customer-app" },
+    })
+  }
 
-// OR combinations
-include: [
-  path("/health"),
-  { host: "shop.localhost", path: "/checkout/*" },
-]
+  return next()
+})
+
+const securityHeadersProxy = defineProxy("securityHeaders", () => {
+  return next({
+    headers: {
+      "x-content-type-options": "nosniff",
+      "x-frame-options": "DENY",
+    },
+  })
+})
 
-// Exclude always wins
-exclude: { host: "museum.localhost" }
+export default proxyChain({ debug: process.env.NODE_ENV !== "production" }, [
+  multiTenantProxy,
+  securityHeadersProxy,
+])
 ```
 
 ---
 
-## Error Handling
+## API Reference
 
-By default, any unhandled error inside a rule logs safely and returns an HTTP 500 (`safeInternalError`). You can supply a custom `onError` handler:
+### Core Functions
 
-```ts
-export default proxyChain(
-  {
-    onError: (err, ruleIndex, req, ctx) => {
-      return new NextResponse("Service Unavailable", { status: 503 })
-    },
-  },
-  [
-    // rules...
-  ]
-)
-```
+| 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 |
+| :--- | :--- |
+| `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. |
 
 ---
 
-## API Reference
-
-### Core Functions
+## License
 
-- `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.
+MIT