@klnap/next-proxy-chain 1.0.3 → 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/README.md

@@ -16,9 +16,9 @@ Composable request pipeline for Next.js middleware and proxy.
 - **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.
+- **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).
 
 ---
 
@@ -103,10 +103,16 @@ const adminRule = apiAuth({
 
 ### 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]+\/.*/)`
+- `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
 
 ---
 
@@ -114,40 +120,51 @@ const adminRule = apiAuth({
 
 ### Request Context
 
-Rules share state via an isolated `Map<string, unknown>` created per request:
+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
-const enrichUser = defineProxy("enrichUser", async (req, ctx) => {
-  ctx.set("user", { id: "usr_1", role: "admin" })
+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 checkPermission = defineProxy("checkPermission", (req, ctx) => {
-  const user = ctx.get("user") as { id: string; role: string } | undefined
-  if (user?.role !== "admin") {
+const checkPermission = defineProxy<Ctx>("checkPermission", (req, ctx) => {
+  if (ctx.user?.role !== "admin") {
     return new Response("Forbidden", { status: 403 })
   }
   return next()
 })
+
+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:
+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)
+  // Downstream request headers (NextRequest & server components). Always last-write-wins.
   request: {
     "x-user-id": "usr_123",
   },
-  // Final outgoing response headers
+  // 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
@@ -160,22 +177,40 @@ return next({
 | `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`. |
+| `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, 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`). |
+| `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
 
@@ -183,12 +218,12 @@ A rule (`ProxyFn`) can return:
 
 | Return Value | Behavior |
 | :--- | :--- |
-| `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. |
+| `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. |
 
 ---