@klnap/next-proxy-chain 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to `@klnap/next-proxy-chain` will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.4] - 2026-08-27
+
+### Breaking
+
+- `onError` returning `undefined` / `void` / `null` now **fails closed** with a 500. Continue only by returning `next()`.
+- `x-internal-host-folder` is no longer a magic routing header. Enable it with `hostFolderHeader: "x-internal-host-folder"`.
+- Public exports are limited to the documented API. Internals (`mergeWrites`, `compileScopes`, `withRuleTimeout`, `./core`, …) are no longer exported.
+- Custom `TContext` requires `createContext`. `proxyChain<{ user: string }>(rules)` without a factory is a type error.
+- Removed `PathOptions` and `pathOptions`; `path()` no longer accepts a `locales` option. Match locale-prefixed routes in the pattern string or RegExp.
+- `ruleTimeoutMs`: passing `NaN`, `Infinity`, or `-Infinity` now throws a `RangeError` at proxy-chain configuration time instead of silently disabling the timeout. If you were relying on an unvalidated computed value (e.g. from `parseInt` without a fallback) resulting in a disabled timeout, this is a breaking change — validate your config value before passing it.
+
+### Fixed
+
+- `path()` no longer drops `^` / `$` from user RegExp.
+- Trailing `*` matches exactly one segment; `**` matches nested paths.
+- `compileScopes()` runs RegExp matchers through `path()`.
+- `next({ headers: { "set-cookie": … } })` reaches the final response.
+- Cookies with the same name and different `Path` / `Domain` are not collapsed.
+- Custom header merge returning `null` deletes the header from the terminal response.
+- Rewrite continuation no longer mutates the incoming `NextRequest`.
+- Timed-out rules no longer leave an unhandled rejection.
+- `host("*.example.com")` matches one DNS label.
+- `strictOverrideCheck` cache no longer pins the first call’s strictness for later calls.
+
+### Changed
+
+- `headerMergeStrategy` applies only to **response** headers. Request overrides stay last-write-wins.
+- Package metadata: `repository`, `bugs`, `homepage`.
+- Tests run on `bun:test`; removed Typedoc site and monorepo tooling from the package repo.
+
+## [1.0.3] - 2026-08-26
+
+npm patch. No detailed notes were kept for 1.0.1–1.0.3 at publish time.
+
+## [1.0.0] - 2026-08-23
+
+### Added
+
+- Composable Edge-safe proxy pipeline via `proxyChain()`.
+- Transparent Next.js pass-through detection on `x-middleware-next: 1` with request override extraction.
+- Automatic filtering of internal `x-middleware-*` transport headers from client responses.
+- Request header blocklist preventing rule injection of sensitive headers (`host`, `authorization`, `x-middleware-*`).
+- Context threading via isolated per-request `Map` instances (`TContext`).
+- Header and cookie accumulation with `last-write-wins`, `first-write-wins`, and custom merge strategies.
+- Path and host scoping (`include`, `exclude`) with construction-time overlap validation.
+- Cached startup self-test for `NextResponse.next()` request overrides.
+- Error isolation with safe 500 fallback.

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,117 +1,70 @@
 # @klnap/next-proxy-chain
 
-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.
+Composable request pipeline for Next.js middleware and proxy.
 
----
-
-## Overview & Motivation
+[![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)
 
-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-*`).
+## Features
 
-`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`).
+- **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 continue, or a terminal `Response` / `NextResponse.redirect` / `NextResponse.json` to stop. `NextResponse.rewrite` **continues** the pipeline (rewrite is applied at the end unless a later rule stops).
+- **Timeouts & Error Recovery**: Optional per-rule timeouts (`ruleTimeoutMs`). `onError` is fail-closed: returning nothing yields 500; return `next()` to continue; return a `Response` to stop.
+- **Zero Runtime Dependencies**: Fully typed in TypeScript with no runtime dependencies (`next` is a peer).
 
 ---
 
 ## Installation
 
-Install the package via your preferred package manager:
-
 ```bash
-# npm
 npm install @klnap/next-proxy-chain
+```
 
-# bun
-bun add @klnap/next-proxy-chain
+Or with your preferred package manager:
 
-# pnpm
+```bash
 pnpm add @klnap/next-proxy-chain
-
-# yarn
+# or
+bun add @klnap/next-proxy-chain
+# or
 yarn add @klnap/next-proxy-chain
 ```
 
 ---
 
-## 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]
-```
-
-### 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:
+## Quick Start
 
 ```typescript
-// middleware.ts
+// proxy.ts or 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 },
-  })
-})
-
-const authProxy = defineProxy("auth", async (req, ctx) => {
+const auth = defineProxy("auth", (req, ctx) => {
   const token = req.cookies.get("session")?.value
-
   if (!token) {
     return NextResponse.redirect(new URL("/login", req.url))
   }
-
-  ctx.set("userId", "usr_100")
+  ctx.set("userId", "usr_123")
   return next()
 })
 
-export const middleware = proxyChain([
-  requestIdProxy,
-  authProxy({ include: path("/dashboard/*") }),
+const security = defineProxy("security", () => {
+  return next({
+    headers: { "x-frame-options": "DENY" },
+  })
+})
+
+export default proxyChain({ debug: process.env.NODE_ENV !== "production" }, [
+  auth({ include: path("/dashboard/*") }),
+  security,
 ])
 
 export const config = {
@@ -119,103 +72,169 @@ export const config = {
 }
 ```
 
-### Next.js 16 Integration (`proxy.ts`)
+---
+
+## Routing & Scoping
 
-In Next.js 16, export the proxy chain as default or named `proxy` export:
+Scope rules to specific paths, hosts, or combinations using `defineProxy`:
 
 ```typescript
-// proxy.ts
-import { defineProxy, host, next, path, proxyChain } from "@klnap/next-proxy-chain"
-import { NextResponse } from "next/server"
+import { defineProxy, host, next, path } from "@klnap/next-proxy-chain"
 
-const multiTenantProxy = defineProxy("multiTenant", (req, ctx) => {
-  const hostname = req.headers.get("host") ?? ""
+const apiAuth = defineProxy("apiAuth", async (req, ctx) => {
+  // Executed only for /api/* requests except /api/public/*
+  return next()
+})
 
-  if (hostname.startsWith("admin.")) {
-    ctx.set("tenant", "admin")
-    return next({
-      request: { "x-tenant-id": "admin-portal" },
-    })
-  }
+// Scoped rule configuration
+const scopedRule = apiAuth({
+  include: path("/api/*"),
+  exclude: path("/api/public/*"),
+})
 
-  if (hostname.startsWith("app.")) {
-    ctx.set("tenant", "app")
-    return next({
-      request: { "x-tenant-id": "customer-app" },
-    })
-  }
+// Combined path and host filter
+const adminRule = apiAuth({
+  include: {
+    host: host("admin.example.com"),
+    path: path("/settings/**"),
+  },
+})
+```
+
+### Path Patterns
+
+- `path("/api/*")` — exactly one segment (`/api/users` yes, `/api/users/123` no)
+- `path("/docs/**")` — the prefix plus zero or more extra segments (`/docs`, `/docs/a/b`)
+- `path("/users/:id")` — one segment (no capture groups; matching only)
+- `path(/^\/foo$/)` — user anchors are kept (`/foo` yes, `/x/foo` no)
+
+### Host Patterns
+
+- `host("admin.example.com")` — exact hostname (case-insensitive, port stripped at match time)
+- `host("*.example.com")` — one DNS label (`foo.example.com` yes, `example.com` no, `a.b.example.com` no)
+- `host(/shop\.localhost$/)` — raw RegExp
+
+---
+
+## State & Header Mutation
+
+### Request Context
 
+Default context is an isolated `Map<string, unknown>` per request. For a typed object, pass `createContext` — TypeScript then follows the factory, not a fake generic:
+
+```typescript
+type Ctx = { user?: { id: string; role: string } }
+
+const enrichUser = defineProxy<Ctx>("enrichUser", async (req, ctx) => {
+  ctx.user = { id: "usr_1", role: "admin" }
   return next()
 })
 
-const securityHeadersProxy = defineProxy("securityHeaders", () => {
-  return next({
-    headers: {
-      "x-content-type-options": "nosniff",
-      "x-frame-options": "DENY",
-    },
-  })
+const checkPermission = defineProxy<Ctx>("checkPermission", (req, ctx) => {
+  if (ctx.user?.role !== "admin") {
+    return new Response("Forbidden", { status: 403 })
+  }
+  return next()
 })
 
-export default proxyChain({ debug: process.env.NODE_ENV !== "production" }, [
-  multiTenantProxy,
-  securityHeadersProxy,
-])
+export default proxyChain({ createContext: (): Ctx => ({}) }, [enrichUser, checkPermission])
 ```
 
+Without `createContext`, `ctx` is `ProxyContext` (`Map`). Do not write `proxyChain<{ user: string }>(rules)` — that is a type error.
+
+### Request and Response Headers
+
+Use `next()` to inject **request** headers (visible to downstream rules and route handlers) and **response** headers (including `Set-Cookie`):
+
+```typescript
+return next({
+  // Downstream request headers (NextRequest & server components). Always last-write-wins.
+  request: {
+    "x-user-id": "usr_123",
+  },
+  // Final outgoing response headers / Set-Cookie
+  headers: {
+    "cache-control": "no-store",
+    "set-cookie": "session=abc; Path=/",
+  },
+})
+```
+
+- `headerMergeStrategy` / `cookieMergeStrategy` apply to **response** headers and cookies only.
+- Request overrides ignore those strategies (last write wins).
+- Cookies are keyed by **name + domain + path**, so `session; Path=/` and `session; Path=/admin` both survive.
+- Custom merge `return null` removes that response header from the final `Response`.
+
 ---
 
 ## API Reference
 
 ### 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. |
+| 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)` | `(pattern: string \| RegExp) => RegExp` | Compiles a path pattern into a stateless `RegExp`. |
+| `host(matcher)` | `(matcher: HostMatcher) => RegExp` | Compiles hostname(s) into an anchored `RegExp` (`*` = one DNS label). |
+| `createProxyContext()` | `() => ProxyContext` | Creates a new `Map<string, unknown>` context instance. |
+| `isNextResult(value)` | `(value: unknown) => boolean` | Type guard for `next()` continuation tokens. |
+| `RuleTimeoutError` | `Error` | Thrown internally when `ruleTimeoutMs` is exceeded (catchable in `onError`). |
 
 ### 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`). |
+| `createContext` | `(req, event) => TContext` | `() => new Map()` | Factory for custom per-request context. Required for a non-`Map` `TContext`. |
+| `headerMergeStrategy` | `"last-write-wins" \| "first-write-wins" \| Function` | `"last-write-wins"` | Conflict strategy for **response** headers only. |
+| `cookieMergeStrategy` | `"last-write-wins" \| "first-write-wins" \| Function` | `"last-write-wins"` | Conflict strategy for `Set-Cookie` (same name+domain+path). |
+| `ruleTimeoutMs` | `number` | `0` | Wall-clock timeout per rule in ms (`0` disables). Does not abort the rule function; leftover rejections are swallowed. |
+| `onError` | `(err, index, req, ctx) => Response \| NextResult \| void` | `undefined` | Recovery hook. See **Errors** below. |
+| `requestHeaderPolicy` | `{ blocked?: string[], allowed?: string[] }` | `{}` | Blocklist/allowlist for **request** header mutations. |
+| `debug` | `boolean` | `false` | Structured one-line logs per rule. |
+| `logger` | `ChainLogger` | `console` | Custom logger (`debug`, `info`, `warn`, `error`). |
+| `strictOverrideCheck` | `boolean` | `false` | Throw at init if `NextResponse.next()` request overrides look unsupported. |
+| `hostFolderHeader` | `string` | unset | Opt-in: request header name that prefixes rewrites with a physical folder (e.g. `"x-internal-host-folder"`). Off by default. |
+
+### Errors (`onError`)
+
+| `onError` returns | Behavior |
+| :--- | :--- |
+| `Response` | Stop and return that response (headers/cookies still merged). |
+| `next()` | Continue to the next rule (rule-level errors only). |
+| `undefined` / `void` / `null` | **Fail closed** — `500 Internal Server Error`. |
+| throws | `500 Internal Server Error`. |
+| omitted | Rule throw → `500`. |
+
+`ruleIndex` is `0`-based. `-1` means an engine-level error after context creation; only a `Response` is honored (the pipeline cannot continue).
+
+A logging-only `onError: (err) => { console.error(err) }` does **not** skip the failure.
 
 ### Return Value Protocol
 
-A `ProxyFn` rule function must return one of the following:
+A rule (`ProxyFn`) can return:
 
-| Return Value | Pipeline Behavior |
+| Return Value | 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. |
+| `next({ request?, headers? })` | Continues. Queues request overrides, response headers, and `Set-Cookie`. |
+| `undefined` / `void` | Continues without mutations. |
+| `NextResponse.next()` | Continues; extracts Next.js request override headers and cookies. |
+| `NextResponse.rewrite(url)` | **Continues**. Stages a rewrite for later rules; the incoming `NextRequest` is not mutated. The rewrite is applied when the chain finishes unless a later rule returns a terminal response. |
+| `NextResponse.redirect(url)` | Stops immediately with the redirect. |
+| `Response` / `NextResponse.json()` | Stops immediately with that response. |
+
+---
+
+## Links
+
+- [GitHub](https://github.com/klnap/next-proxy-chain)
+- [npm](https://www.npmjs.com/package/@klnap/next-proxy-chain?activeTab=code)
 
 ---
 
 ## License
 
-MIT
+[MIT](./LICENSE)
+