@statewalker/webrun-http-proxy 0.2.2 → 0.3.0

package/README.md

@@ -1,8 +1,59 @@
 # @statewalker/webrun-http-proxy
 
-Re-issue an HTTP request to an outside origin, safely. **One function.**
+## What it is
 
-**Zero runtime dependencies. One entry point.**
+One function, `urlUpstream`, that turns a base URL into a
+`(Request) => Promise<Response>` handler. The handler re-issues each incoming
+request to that outside origin: it drops the headers that must not leave this
+hop, adds the destination's own headers and credential, streams the body, and
+reports failures as `502` responses instead of exceptions.
+
+## Why it exists
+
+Forwarding a request to a third-party origin looks like one line,
+`fetch(new Request(target, request))`, and is wrong in several quiet ways. The
+caller's own credential leaks to the upstream. Hop-by-hop headers go along. In
+Firefox the body is silently dropped. An upstream redirect throws inside the
+`try` and is reported as unreachable. An abandoned caller leaves the upstream
+call running. `urlUpstream` handles each of these, and a browser page and a
+Node process use the same code.
+
+Routing is not part of it. Prefix matching and path rewriting are what any
+router (Hono, a `URLPattern` table, a `switch`) already does, so the package
+takes a request that is already addressed and leaves routing to the caller.
+
+## How to use
+
+```sh
+pnpm add @statewalker/webrun-http-proxy
+```
+
+- **Peer dependencies:** none. **Runtime dependencies:** none.
+- **Entry point:** one, `.`. ESM only: `dist/index.js` with `dist/index.d.ts`.
+  The `source` export condition points at `src/index.ts`.
+- **Environment:** any runtime with `fetch`, `Request`, `Response` and
+  `Headers`: Node, browsers, workers, Deno, Bun. No DOM API and no `node:`
+  import; `tests/boundary.test.ts` enforces that.
+
+| Export | What it is |
+| --- | --- |
+| `urlUpstream(init)` | Returns an `Upstream` that re-issues requests against `init.base`. |
+| `UrlUpstreamInit` | Its options (below). |
+| `Upstream`, `FetchHandler` | Both `(request: Request) => Response \| Promise<Response>`: the same type as `FetchHandler` in `@statewalker/webrun-http-streams`, declared here to keep zero dependencies. |
+| `MARKER` | `"x-webrun-proxy"`, the header on responses this package makes itself. |
+
+| `UrlUpstreamInit` field | Default | Meaning |
+| --- | --- | --- |
+| `base` | required | Origin and optional base path. The request's path and query are appended to it. |
+| `stripRequestHeaders` | `[]` | Request headers to drop before re-issuing, beyond the hop-by-hop set. |
+| `headers` | none | Static headers for this destination, set after the caller's. |
+| `credential` | none | `() => Record<string, string> \| undefined`, read on every request and set last. |
+| `via` | none | `Via` header value; omitted, no `Via` is added. |
+| `fetchImpl` | `globalThis.fetch` | Injected `fetch`, for tests. |
+
+## Examples
+
+### Behind a Hono route
 
 ```ts
 import { Hono } from "hono";
@@ -20,72 +71,113 @@ app.all("/openai/:rest{.*}", (c) => {
 });
 ```
 
-## Bring your own router
-
-This package used to ship a route table as well — prefix matching, path
-rewriting, a listing endpoint, a marker header on unmatched paths, a route
-store. That turned out to be the uninteresting half: it is what a router does,
-and every caller already has one.
-
-The evidence is in `tests/scenarios.ts`. Twelve scenarios established this
-proxy's behaviour in the prototype; they now run against **a plain Hono
-router** and pass unchanged. Nothing was lost with the table, and the segment
-matching got better — Hono matches on segment boundaries, so `/open` no longer
-swallows `/openai`, which the hand-written table had to special-case.
-
-Persisting route configuration went with the router, for the same reason: the
-shape of that configuration belongs to whoever defines the routes. If you store
-routes, store the credential's header **name** and never its **value** — the
-value belongs in memory, merged per request through `credential`. (An earlier
-shape of this API stored a whole route, and building a proxy page on it would
-have written bearer keys into `localStorage`.)
-
-## What `urlUpstream` actually does
-
-None of this is obvious, and all of it was found by measurement:
-
-- Whatever `stripRequestHeaders` names — the caller's own credential and
-  whatever else its system treats as proven identity — is **consumed by this
-  hop**, the way `Proxy-Authorization` is consumed by the proxy it names. A
-  third-party origin has no business seeing it: forwarding a mesh token once
-  handed it to an upstream that echoed it straight back.
-- `authorization` is **not** special. It belongs to the application calling
-  the upstream (a page calling an API with that API's key) and is forwarded
-  unless you name it in `stripRequestHeaders`. `credential` still wins over it.
-- Hop-by-hop headers (RFC 9110 §7.6.1) are dropped.
-- `credential` is read at **request** time, so a key can be typed while traffic
-  flows.
-- The body **streams** rather than buffering, and the caller's `signal` is
-  forwarded, so an abandoned request abandons the upstream call.
-- An **opaque redirect** is reported as a redirect. It has status `0`, and
-  constructing a `Response` with status 0 throws *inside* the `try` — which
-  reported a redirecting upstream as `502 upstream-unreachable`.
-
-A **local** handler is just a `FetchHandler` you route to directly: do not put
-it behind this. Calling a handler on this side of the proxy must **not** strip
-the caller's credential, because it still needs to know who is calling.
-
-## One row a browser cannot pass
-
-`Via` is a forbidden header name under the Fetch spec — a page may not set it,
-and the browser drops it with no error. ADR-0015 has an intermediary announce
-itself with `Via`, so that part is unimplementable in a browser-hosted
-intermediary. A fact about the platform, not about this code.
-
-## No platform
-
-No transport, no crypto, no platform code at all — re-issuing a request needs
-none of it, which is why a proxy **page** and a Node process use the same entry
-point. `tests/boundary.test.ts` asserts there is no platform entry point left
-to exempt, and the dependency list is **empty**.
-
-## Where it came from
-
-Extracted from `@statewalker/httpeers-expose`, where it was a mesh concept by
-accident of where it was written. Nothing in it is about peers. The one place
-the old package knew about meshes is now `stripRequestHeaders`: httpeers passes
-its membership-token and proven-peer headers there.
-
-**9 tests**, and the twelve scenarios run inside two of them — the suite
-asserts that every scenario ran (guarding against an empty list) and that none
-failed.
+Only the path and query of the incoming URL are used, so the host in
+`http://upstream…` is irrelevant. `POST /openai/chat/completions?x=1` is
+re-issued as `POST https://api.openai.com/v1/chat/completions?x=1` with the
+body streamed and `authorization` set from `credential`.
+
+### Keeping your own credential off the upstream
+
+```ts
+import { urlUpstream } from "@statewalker/webrun-http-proxy";
+
+const upstream = urlUpstream({
+  base: "https://example.org/api",
+  stripRequestHeaders: ["x-mesh-token", "x-proven-peer"],
+});
+```
+
+## Internals
+
+### What the proxy does to a request
+
+```
+incoming Request
+  ├─ delete stripRequestHeaders            (caller's own identity)
+  ├─ delete hop-by-hop headers             (RFC 9110 §7.6.1)
+  ├─ set via                                (if configured)
+  ├─ set headers                            (operator configuration)
+  ├─ set credential()                       (read now, wins over everything)
+  ├─ body: stream, or buffer on Firefox     (never for GET/HEAD)
+  └─ fetch(base + path + query, { signal, redirect: "manual" })
+        ├─ opaque redirect  -> 502, x-webrun-proxy: upstream-redirect
+        ├─ throws           -> 502, x-webrun-proxy: upstream-unreachable
+        └─ otherwise        -> upstream status, headers and streamed body
+```
+
+### Your credential is consumed by this hop
+
+Whatever `stripRequestHeaders` names is removed before the request leaves, the
+way `Proxy-Authorization` is consumed by the proxy it names. That is where a
+system puts its own credential and anything it treats as proven identity: a
+third-party origin has no business seeing them, and an upstream that echoes
+headers back would hand them to whoever reads the response.
+
+`authorization` is not on any built-in list. It usually belongs to the
+application talking to the upstream (a page calling an API with that API's
+key), and dropping it would make that call impossible through the proxy. A
+system that keeps its own credential in `authorization` names it in
+`stripRequestHeaders`. `credential` still overrides whatever the caller sent.
+
+Hop-by-hop headers are always dropped: `connection`, `keep-alive`,
+`proxy-authenticate`, `proxy-authorization`, `te`, `trailer`,
+`transfer-encoding`, `upgrade`.
+
+`credential` is called per request, so a key can be entered or rotated while
+traffic flows, and it is never stored in the proxy's configuration. If you
+persist proxy routes, store the credential header's name, never its value.
+
+### The body streams, except where the platform cannot
+
+`GET` and `HEAD` never carry a body; the Fetch spec forbids one. Otherwise, if
+`request.body` is a stream it is passed on with `duplex: "half"`, so a large
+upload is never held in memory. Firefox (checked against 155) has no
+`Request.prototype.body`; there `request.body` reads `undefined` even for a real
+payload, and passing it on would send nothing. The proxy then buffers with
+`request.arrayBuffer()`. An empty buffer is treated as no body. `duplex` is set
+from the branch taken, not from `body instanceof ReadableStream`, because a
+stream from another realm fails that check and `new Request` would then throw
+`duplex option is required`.
+
+The caller's `signal` is forwarded, so an abandoned request abandons the
+upstream call.
+
+### Failures are responses, not exceptions
+
+| Situation | Response |
+| --- | --- |
+| Upstream answers with a redirect | `502`, `x-webrun-proxy: upstream-redirect`, body `upstream redirected; the proxy does not follow redirects` |
+| Network error, CORS refusal, body already read, any other throw | `502`, `x-webrun-proxy: upstream-unreachable`, body `upstream <base> could not be reached: <message>` and a line suggesting the upstream may not permit cross-origin requests |
+
+Redirects are not followed (`redirect: "manual"`). In a browser that yields an
+opaque redirect with status `0`, and `new Response(body, { status: 0 })`
+throws, which would otherwise surface as `upstream-unreachable`. The proxy
+checks for it first and reports it as a redirect.
+
+The `x-webrun-proxy` header marks responses the proxy made itself, so they are
+never mistaken for the upstream's.
+
+### `Via` does not work in a browser
+
+`Via` is a forbidden request header under the Fetch spec. A page may not set
+it, and the browser drops it without an error. The `via` option therefore only
+takes effect outside a browser.
+
+### Dependencies
+
+Zero runtime dependencies. `hono` is a dev dependency: `tests/scenarios.ts`
+runs its scenarios through a plain Hono router to show the proxy needs no
+router of its own.
+
+### Scripts
+
+```sh
+pnpm test             # vitest run
+pnpm run build        # rolldown + tsc --emitDeclarationOnly
+pnpm run typecheck    # tsc --noEmit
+pnpm run lint         # biome check src tests
+```
+
+## License
+
+MIT

package/dist/proxy.d.ts

@@ -23,17 +23,19 @@
  *      upstream call running. It is forwarded.
  */
 /**
- * A handler, in the only shape this package needs.
+ * A handler: sync or async, as a Service Worker's or a Durable Object's `fetch`.
  *
- * Declared here rather than imported: it is one line, and depending on another
- * package for it would give a proxy a dependency it has no other use for.
+ * The same type as `FetchHandler` in `@statewalker/webrun-http-streams` (a type
+ * test there keeps them identical). Declared here rather than imported: it is
+ * one line, and depending on another package for it would give a proxy a
+ * dependency it has no other use for.
  */
-export type FetchHandler = (request: Request) => Promise<Response>;
+export type FetchHandler = (request: Request) => Response | Promise<Response>;
 /** Marks this layer's OWN responses, so they are never mistaken for an upstream's. Same header the proxy already uses. */
 export declare const MARKER = "x-webrun-proxy";
 /**
  * An upstream is just a handler. That is the whole merge: a local service, a
- * remote origin and another peer are all `(Request) => Promise<Response>`.
+ * remote origin and another peer are all a `FetchHandler`.
  */
 export type Upstream = FetchHandler;
 export interface UrlUpstreamInit {

package/dist/proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEnE,0HAA0H;AAC1H,eAAO,MAAM,MAAM,mBAAmB,CAAC;AAEvC;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,CAAC;AAEpC,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAExC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,+FAA+F;IAC/F,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IACtD,qDAAqD;IACrD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,QAAQ,CAkH3D"}
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE9E,0HAA0H;AAC1H,eAAO,MAAM,MAAM,mBAAmB,CAAC;AAEvC;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,CAAC;AAEpC,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAExC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,+FAA+F;IAC/F,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IACtD,qDAAqD;IACrD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,QAAQ,CAkH3D"}

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@statewalker/webrun-http-proxy",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "type": "module",
   "description": "Re-issue an HTTP request to an outside origin, safely: credentials consumed, hop-by-hop headers dropped, body streamed.",
+  "bugs": {
+    "url": "https://github.com/statewalker/webrun-wire/issues"
+  },
+  "homepage": "https://github.com/statewalker/webrun-wire/tree/main/packages/webrun-http-proxy#readme",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/statewalker/webrun-wire.git",
+    "url": "git+https://github.com/statewalker/webrun-wire.git",
     "directory": "packages/webrun-http-proxy"
   },
   "main": "./dist/index.js",
@@ -31,7 +35,7 @@
     "rimraf": "^6.1.3",
     "rolldown": "^1.2.12",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.5"
   },
   "publishConfig": {
     "access": "public"

package/src/proxy.ts

@@ -24,19 +24,21 @@
  */
 
 /**
- * A handler, in the only shape this package needs.
+ * A handler: sync or async, as a Service Worker's or a Durable Object's `fetch`.
  *
- * Declared here rather than imported: it is one line, and depending on another
- * package for it would give a proxy a dependency it has no other use for.
+ * The same type as `FetchHandler` in `@statewalker/webrun-http-streams` (a type
+ * test there keeps them identical). Declared here rather than imported: it is
+ * one line, and depending on another package for it would give a proxy a
+ * dependency it has no other use for.
  */
-export type FetchHandler = (request: Request) => Promise<Response>;
+export type FetchHandler = (request: Request) => Response | Promise<Response>;
 
 /** Marks this layer's OWN responses, so they are never mistaken for an upstream's. Same header the proxy already uses. */
 export const MARKER = "x-webrun-proxy";
 
 /**
  * An upstream is just a handler. That is the whole merge: a local service, a
- * remote origin and another peer are all `(Request) => Promise<Response>`.
+ * remote origin and another peer are all a `FetchHandler`.
  */
 export type Upstream = FetchHandler;