@klnap/next-proxy-chain 1.0.1 → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 klnap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,41 +1,40 @@
 # @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.
+Composable request pipeline for Next.js middleware and proxy.
 
-[![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)
+[![npm version](https://img.shields.io/npm/v/@klnap/next-proxy-chain)](https://www.npmjs.com/package/@klnap/next-proxy-chain)
+[![npm downloads](https://img.shields.io/npm/dm/@klnap/next-proxy-chain)](https://www.npmjs.com/package/@klnap/next-proxy-chain)
+[![license](https://img.shields.io/npm/l/@klnap/next-proxy-chain)](https://github.com/klnap/next-proxy-chain/blob/main/LICENSE)
 
 ---
 
-## Why `@klnap/next-proxy-chain`?
+## Features
 
-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.
-
-`@klnap/next-proxy-chain` solves this by providing:
-
-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`).
+- **Linear Composition**: Chain independent rules sequentially into a single Next.js middleware or proxy handler.
+- **Next.js 15 & 16**: Supports both `middleware.ts` and `proxy.ts`.
+- **Request-Scoped Context**: Isolated per-request context for sharing state between rules without global state.
+- **Deterministic Header & Cookie Merging**: Propagate request header overrides downstream, deduplicate `Set-Cookie` headers, and merge response headers with configurable conflict strategies.
+- **Route & Host Scoping**: Declarative path matching (globs, parameters, regex) and host filtering with `include` and `exclude` rules.
+- **Safe Pattern Matching**: Normalizes stateful regular expressions to avoid `lastIndex`-related matching issues.
+- **Explicit Flow Control**: Return `next({ request, headers })` to pass data downstream, or return standard `Response` / `NextResponse` (`redirect`, `rewrite`, `json`) to exit early.
+- **Timeouts & Error Recovery**: Optional per-rule timeouts (`ruleTimeoutMs`) and error recovery handlers (`onError`).
+- **Zero Runtime Dependencies**: Fully typed in TypeScript with no runtime dependencies.
 
 ---
 
 ## Installation
 
 ```bash
-# Using Bun
-bun add @klnap/next-proxy-chain
-
-# Using npm
 npm install @klnap/next-proxy-chain
+```
 
-# Using pnpm
-pnpm add @klnap/next-proxy-chain
+Or with your preferred package manager:
 
-# Using Yarn
+```bash
+pnpm add @klnap/next-proxy-chain
+# or
+bun add @klnap/next-proxy-chain
+# or
 yarn add @klnap/next-proxy-chain
 ```
 
@@ -43,208 +42,164 @@ yarn add @klnap/next-proxy-chain
 
 ## Quick Start
 
-### 1. Define Modular Proxy Rules
-
-Create self-contained proxy rules in your application:
-
-```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()
-
-  return next({
-    request: { "x-request-id": requestId },
-    headers: { "x-request-id": requestId },
-  })
-})
-```
-
 ```typescript
-// src/proxies/auth.ts
-import { defineProxy, next } from "@klnap/next-proxy-chain"
+// proxy.ts or 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 auth = defineProxy("auth", (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_123")
   return next()
 })
-```
 
-### 2. Assemble Pipeline in `src/proxy.ts` (Next.js 16)
+const security = defineProxy("security", () => {
+  return next({
+    headers: { "x-frame-options": "DENY" },
+  })
+})
 
-```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
-  requestIdProxy,
-
-  // 2. Guards dashboard routes, excluding public preview assets
-  authProxy({
-    include: path("/dashboard/*"),
-    exclude: path("/dashboard/public/*"),
-  }),
-
-  // 3. Handles internationalization routing
-  i18nProxy,
+export default proxyChain({ debug: process.env.NODE_ENV !== "production" }, [
+  auth({ include: path("/dashboard/*") }),
+  security,
 ])
 
 export const config = {
-  matcher: "/((?!api|_next|.*\\..*).*)",
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
 }
 ```
 
 ---
 
-## Route & Host Scoping
+## Routing & Scoping
 
-Rules can be declaratively scoped by path, host, or combinations. Scoping evaluates exclusions first — if an exclusion matches, the rule is skipped immediately.
+Scope rules to specific paths, hosts, or combinations using `defineProxy`:
 
 ```typescript
-import { defineProxy, path, host } from "@klnap/next-proxy-chain"
-
-// Scoped to specific path patterns on ANY host
-const adminRule = defineProxy("admin", handler, {
-  include: path("/admin/*"),
-})
+import { defineProxy, host, next, path } from "@klnap/next-proxy-chain"
 
-// Scoped to a specific domain or tenant
-const tenantRule = defineProxy("tenant", handler, {
-  include: { host: "app.example.com" },
+const apiAuth = defineProxy("apiAuth", async (req, ctx) => {
+  // Executed only for /api/* requests except /api/public/*
+  return next()
 })
 
-// Scoped to specific path on a specific host
-const checkoutRule = defineProxy("checkout", handler, {
-  include: { host: "store.example.com", path: "/checkout/*" },
+// Scoped rule configuration
+const scopedRule = apiAuth({
+  include: path("/api/*"),
+  exclude: path("/api/public/*"),
 })
 
-// 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" },
-  ],
+// Combined path and host filter
+const adminRule = apiAuth({
+  include: {
+    host: host("admin.example.com"),
+    path: path("/settings/**"),
+  },
 })
 ```
 
+### Path Patterns
+
+- Wildcards: `path("/api/*")` (single segment) or `path("/docs/**")` (multi-segment)
+- Parameterized: `path("/users/:id")`
+- Locales: `path("/dashboard", { locales: ["en", "pl", "de"] })`
+- Regular expressions: `path(/^\/v[0-9]+\/.*/)`
+
 ---
 
-## Deterministic Header & Cookie Merging
+## State & Header Mutation
 
-When multiple rules in the chain mutate headers or cookies, `@klnap/next-proxy-chain` merges them deterministically:
+### Request Context
 
-- **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.
+Rules share state via an isolated `Map<string, unknown>` created per request:
 
 ```typescript
-import { defineProxy, next } from "@klnap/next-proxy-chain"
+const enrichUser = defineProxy("enrichUser", async (req, ctx) => {
+  ctx.set("user", { id: "usr_1", role: "admin" })
+  return next()
+})
 
-export const headerEnricher = defineProxy("enricher", () => {
-  return next({
-    request: {
-      "x-geo-region": "eu-central",
-    },
-    headers: {
-      "x-content-type-options": "nosniff",
-      "x-frame-options": "DENY",
-    },
-  })
+const checkPermission = defineProxy("checkPermission", (req, ctx) => {
+  const user = ctx.get("user") as { id: string; role: string } | undefined
+  if (user?.role !== "admin") {
+    return new Response("Forbidden", { status: 403 })
+  }
+  return next()
 })
 ```
 
----
+### Request and Response Headers
 
-## 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:
+Use `next()` to inject request headers (visible to downstream rules and route handlers) and response headers:
 
 ```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()
+return next({
+  // Downstream request headers (NextRequest & server components)
+  request: {
+    "x-user-id": "usr_123",
+  },
+  // Final outgoing response headers
+  headers: {
+    "cache-control": "no-store",
+  },
+})
 ```
 
 ---
 
-## Error Handling & Timeout Budgets
+## API Reference
 
-Prevent unresponsive downstream authentication services or external APIs from blocking Edge execution:
+### Core Functions
 
-```typescript
-import { proxyChain } from "@klnap/next-proxy-chain"
-import { NextResponse } from "next/server"
+| Function | Signature | Description |
+| :--- | :--- | :--- |
+| `proxyChain(rules)` | `(rules: Entry[]) => Handler` | Creates a middleware/proxy handler from a list of rules. |
+| `proxyChain(options, rules)` | `(options: ProxyChainOptions, rules: Entry[]) => Handler` | Creates a handler with custom pipeline options. |
+| `defineProxy(name?, fn)` | `(name?: string, fn: ProxyFn) => DefinedProxy` | Defines a reusable proxy rule with scoping capabilities. |
+| `next(options?)` | `(options?: NextOptions) => NextResult` | Returns a continuation token with optional header mutations. |
+| `path(pattern, options?)` | `(pattern: string \| RegExp, options?: PathOptions) => RegExp` | Compiles a path pattern into a stateless `RegExp`. |
+| `host(matcher)` | `(matcher: HostMatcher) => RegExp` | Compiles hostname(s) into an anchored `RegExp`. |
+| `createProxyContext()` | `() => ProxyContext` | Creates a new `Map<string, unknown>` context instance. |
 
-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...
-  ]
-)
-```
+### Configuration Options (`ProxyChainOptions`)
 
----
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `createContext` | `(req, event) => TContext` | `() => new Map()` | Factory for custom per-request context objects. |
+| `headerMergeStrategy` | `"last-write-wins" \| "first-write-wins" \| Function` | `"last-write-wins"` | Strategy for resolving conflicting response headers. |
+| `cookieMergeStrategy` | `"last-write-wins" \| "first-write-wins" \| Function` | `"last-write-wins"` | Strategy for resolving duplicate `Set-Cookie` directives. |
+| `ruleTimeoutMs` | `number` | `0` | Wall-clock execution timeout per rule in milliseconds (`0` disables timeout). |
+| `onError` | `(err, index, req, ctx) => Response \| void` | `undefined` | Custom error recovery hook when a rule throws. |
+| `requestHeaderPolicy` | `{ blocked?: string[], allowed?: string[] }` | `{}` | Custom blocklist/allowlist for request header mutations. |
+| `debug` | `boolean` | `false` | Enables structured single-line execution logs per rule. |
+| `logger` | `ChainLogger` | `console` | Custom logger instance (`debug`, `info`, `warn`, `error`). |
 
-## API Reference
+### Return Value Protocol
 
-### Exported Functions (`@klnap/next-proxy-chain`)
+A rule (`ProxyFn`) can return:
 
-| Function | Description |
+| Return Value | 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 to next rule, queuing header mutations. |
+| `undefined` / `void` | Continues to next rule without mutating headers. |
+| `NextResponse.next()` | Continues execution while extracting any internal request header overrides. |
+| `NextResponse.rewrite(url)` | Stages a URL rewrite for downstream rules while continuing pipeline execution. |
+| `NextResponse.redirect(url)` | Stops pipeline immediately and returns redirect response. |
+| `Response` / `NextResponse.json()` | Stops pipeline immediately and returns terminal response. |
+
+---
+
+## Links
+
+- [GitHub](https://github.com/klnap/next-proxy-chain)
+- [npm](https://www.npmjs.com/package/@klnap/next-proxy-chain?activeTab=code)
 
 ---
 
 ## License
 
-MIT © [klnap](https://github.com/klnap)
+[MIT](./LICENSE)
+