@shivaedev/test-story 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.9.0 - 2026-10-18
+
+### Added
+
+- `forwardingProxy(upstream, options?)` and `ForwardingProxyOptions` from `@shivaedev/test-story/forwardingProxy.ts` provide a scoped loopback proxy for host stories. It forwards requests and responses, appends the caller to `x-forwarded-for`, and applies the story's configured headers.
+
 ## 0.8.0 - 2026-10-18
 
 ### Added

package/README.md

@@ -233,6 +233,24 @@ app.it("a request continues its supplied trace", [], function* ({ request, reque
 
 Detachment only removes the incoming parent: spans that application startup explicitly creates still follow native Effect semantics.
 
+#### Forwarding requests to a host
+
+Use `forwardingProxy` from `@shivaedev/test-story/forwardingProxy.ts` in the kit's scoped `create` or `after` hook after starting the host under test:
+
+```ts
+import { forwardingProxy } from "@shivaedev/test-story/forwardingProxy.ts";
+
+const proxy = yield* forwardingProxy(upstream, {
+  headers: {
+    host: "internal.test",
+    "x-forwarded-host": "app.example",
+    "x-forwarded-proto": "https",
+  },
+});
+```
+
+Point story requests at `proxy.url`. The proxy listens on IPv4 and IPv6 loopback on the same allocated port, forwards the request's method, path, query, body and headers to `upstream`, and returns the host's status, headers and body. It appends the connecting caller's address to `x-forwarded-for`, preserving any existing chain. The optional `headers` map overrides incoming and generated headers, including `x-forwarded-for` when the story needs a fixed chain. The proxy returns 502 if it cannot connect to the host. Both listeners close with the story's Scope.
+
 #### Reading OTLP exports
 
 Use `otlpReceiver` from `@shivaedev/test-story/otlpReceiver.ts` in a kit's scoped `create` hook. It listens on an allocated loopback port and closes with the story scope. Point the application's real exporter at `${receiver.url}/v1/traces`, then flush the exporter before reading:
@@ -519,6 +537,7 @@ Import each module with the prefix `@shivaedev/test-story/`; there is no root en
 | `genreTags.ts` | `genreTags(...kitNames)`, `GenreTag` |
 | `domEnvironment.config.ts` | Default Vitest environment preserving Node host globals and happy-dom document transport |
 | `fakeHttpService.ts` | `fakeHttpService(options)`, `FakeHttpRoute`, `FakeHttpRequest`, `FakeHttpReply`, `FakeHttpHold`, `FakeHttpServiceOptions` |
+| `forwardingProxy.ts` | `forwardingProxy(upstream, options?)`, `ForwardingProxyOptions` |
 | `otlpReceiver.ts` | `otlpReceiver(options?)`, `OtlpSpan`, `OtlpExport`, `OtlpReceiverOptions` |
 
 ### Install and limits

package/dist/server/forwardingProxy.d.ts

@@ -0,0 +1,8 @@
+import { Effect } from "effect";
+export interface ForwardingProxyOptions {
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export declare const forwardingProxy: (upstream: string, options?: ForwardingProxyOptions | undefined) => Effect.Effect<{
+    url: string;
+}, import("effect/Cause").UnknownError, import("effect/Scope").Scope>;
+//# sourceMappingURL=forwardingProxy.d.ts.map

package/dist/server/forwardingProxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwardingProxy.d.ts","sourceRoot":"","sources":["../../src/server/forwardingProxy.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,eAAO,MAAM,eAAe;;qEA8B1B,CAAC"}

package/dist/server/forwardingProxy.js

@@ -0,0 +1,32 @@
+import { createServer, request } from "node:http";
+import { Effect } from "effect";
+import { loopbackServer } from "#internal/loopback.ts";
+export const forwardingProxy = Effect.fnUntraced(function* (upstream, options = {}) {
+    const forward = (incoming, response) => {
+        const outgoing = request(`${upstream}${incoming.url}`, {
+            headers: {
+                ...incoming.headers,
+                "x-forwarded-for": [incoming.headers["x-forwarded-for"], incoming.socket.remoteAddress].filter(Boolean).join(", "),
+                ...options.headers,
+            },
+            method: incoming.method,
+        }, (result) => {
+            response.writeHead(result.statusCode ?? 502, result.headers);
+            result.pipe(response);
+        });
+        outgoing.on("error", (error) => {
+            if (response.headersSent) {
+                response.destroy(error);
+            }
+            else {
+                response.writeHead(502).end();
+            }
+        });
+        response.on("close", () => outgoing.destroy());
+        incoming.pipe(outgoing);
+    };
+    const url = yield* loopbackServer(createServer(forward));
+    yield* loopbackServer(createServer(forward), { host: "::1", port: Number(new URL(url).port) });
+    return { url };
+});
+//# sourceMappingURL=forwardingProxy.js.map

package/dist/server/forwardingProxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwardingProxy.js","sourceRoot":"","sources":["../../src/server/forwardingProxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAwB,OAAO,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAMvD,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,QAAgB,EAAE,OAAO,GAA2B,EAAE;IACjH,MAAM,OAAO,GAAoB,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE;QACvD,MAAM,QAAQ,GAAG,OAAO,CACvB,GAAG,QAAQ,GAAG,QAAQ,CAAC,GAAG,EAAE,EAC5B;YACC,OAAO,EAAE;gBACR,GAAG,QAAQ,CAAC,OAAO;gBACnB,iBAAiB,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;gBAClH,GAAG,OAAO,CAAC,OAAO;aAClB;YACD,MAAM,EAAE,QAAQ,CAAC,MAAM;SACvB,EACD,CAAC,MAAM,EAAE,EAAE;YACV,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,IAAI,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;YAC7D,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC,CACD,CAAC;QACF,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC9B,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;gBAC1B,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACzB,CAAC;iBAAM,CAAC;gBACP,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;YAC/B,CAAC;QACF,CAAC,CAAC,CAAC;QACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QAC/C,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACzB,CAAC,CAAC;IACF,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IACzD,KAAK,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC/F,OAAO,EAAE,GAAG,EAAE,CAAC;AAChB,CAAC,CAAC,CAAC"}

package/dist/server/internal/loopback.d.ts

@@ -1,4 +1,7 @@
 import type { Server } from "node:http";
 import { Effect } from "effect";
-export declare const loopbackServer: (server: Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>) => Effect.Effect<string, import("effect/Cause").UnknownError, import("effect/Scope").Scope>;
+export declare const loopbackServer: (server: Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>, options?: {
+    readonly host?: string;
+    readonly port?: number;
+} | undefined) => Effect.Effect<string, import("effect/Cause").UnknownError, import("effect/Scope").Scope>;
 //# sourceMappingURL=loopback.d.ts.map

package/dist/server/internal/loopback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loopback.d.ts","sourceRoot":"","sources":["../../../src/server/internal/loopback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,eAAO,MAAM,cAAc,2LA0BzB,CAAC"}
+{"version":3,"file":"loopback.d.ts","sourceRoot":"","sources":["../../../src/server/internal/loopback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,eAAO,MAAM,cAAc;oBAA2E,MAAM;oBAAkB,MAAM;0GA0BlI,CAAC"}

package/dist/server/internal/loopback.js

@@ -1,8 +1,8 @@
 import { Effect } from "effect";
-export const loopbackServer = Effect.fnUntraced(function* (server) {
+export const loopbackServer = Effect.fnUntraced(function* (server, options = {}) {
     yield* Effect.acquireRelease(Effect.tryPromise(() => new Promise((resolve, reject) => {
         server.once("error", reject);
-        server.listen(0, "127.0.0.1", () => {
+        server.listen(options.port ?? 0, options.host ?? "127.0.0.1", () => {
             server.off("error", reject);
             resolve();
         });

package/dist/server/internal/loopback.js.map

@@ -1 +1 @@
-{"version":3,"file":"loopback.js","sourceRoot":"","sources":["../../../src/server/internal/loopback.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAc;IACxE,KAAK,CAAC,CAAC,MAAM,CAAC,cAAc,CAC3B,MAAM,CAAC,UAAU,CAChB,GAAG,EAAE,CACJ,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE;YAClC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC5B,OAAO,EAAE,CAAC;QACX,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CACH,EACD,GAAG,EAAE,CACJ,MAAM,CAAC,OAAO,CACb,GAAG,EAAE,CACJ,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAC7D,MAAM,CAAC,mBAAmB,EAAE,CAAC;IAC9B,CAAC,CAAC,CACH,CACF,CAAC;IACF,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IACjC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QACrD,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,+GAA+G,CAAC,CAAC;IAC3I,CAAC;IACD,OAAO,oBAAoB,OAAO,CAAC,IAAI,EAAE,CAAC;AAC3C,CAAC,CAAC,CAAC"}
+{"version":3,"file":"loopback.js","sourceRoot":"","sources":["../../../src/server/internal/loopback.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAc,EAAE,OAAO,GAAuD,EAAE;IAC1I,KAAK,CAAC,CAAC,MAAM,CAAC,cAAc,CAC3B,MAAM,CAAC,UAAU,CAChB,GAAG,EAAE,CACJ,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7B,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,IAAI,WAAW,EAAE,GAAG,EAAE;YAClE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC5B,OAAO,EAAE,CAAC;QACX,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CACH,EACD,GAAG,EAAE,CACJ,MAAM,CAAC,OAAO,CACb,GAAG,EAAE,CACJ,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAC7D,MAAM,CAAC,mBAAmB,EAAE,CAAC;IAC9B,CAAC,CAAC,CACH,CACF,CAAC;IACF,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IACjC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QACrD,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,+GAA+G,CAAC,CAAC;IAC3I,CAAC;IACD,OAAO,oBAAoB,OAAO,CAAC,IAAI,EAAE,CAAC;AAC3C,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/test-story",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Tests that read like stories over the real engine: a story kit per engine with its own it, traits per feature, and a failure that prints the story, where it stopped and the engine's state",
   "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/test-story#readme",
   "bugs": {
@@ -46,7 +46,7 @@
   },
   "devDependencies": {
     "@effect/vitest": "4.0.4",
-    "@shivaedev/quality": "0.26.0",
+    "@shivaedev/quality": "0.27.0",
     "@types/node": "24.19.2",
     "effect": "4.0.4",
     "happy-dom": "20.14.6",

package/src/server/forwardingProxy.ts

@@ -0,0 +1,39 @@
+import { createServer, type RequestListener, request } from "node:http";
+import { Effect } from "effect";
+import { loopbackServer } from "#internal/loopback.ts";
+
+export interface ForwardingProxyOptions {
+	readonly headers?: Readonly<Record<string, string>>;
+}
+
+export const forwardingProxy = Effect.fnUntraced(function* (upstream: string, options: ForwardingProxyOptions = {}) {
+	const forward: RequestListener = (incoming, response) => {
+		const outgoing = request(
+			`${upstream}${incoming.url}`,
+			{
+				headers: {
+					...incoming.headers,
+					"x-forwarded-for": [incoming.headers["x-forwarded-for"], incoming.socket.remoteAddress].filter(Boolean).join(", "),
+					...options.headers,
+				},
+				method: incoming.method,
+			},
+			(result) => {
+				response.writeHead(result.statusCode ?? 502, result.headers);
+				result.pipe(response);
+			},
+		);
+		outgoing.on("error", (error) => {
+			if (response.headersSent) {
+				response.destroy(error);
+			} else {
+				response.writeHead(502).end();
+			}
+		});
+		response.on("close", () => outgoing.destroy());
+		incoming.pipe(outgoing);
+	};
+	const url = yield* loopbackServer(createServer(forward));
+	yield* loopbackServer(createServer(forward), { host: "::1", port: Number(new URL(url).port) });
+	return { url };
+});

package/src/server/internal/loopback.ts

@@ -1,13 +1,13 @@
 import type { Server } from "node:http";
 import { Effect } from "effect";
 
-export const loopbackServer = Effect.fnUntraced(function* (server: Server) {
+export const loopbackServer = Effect.fnUntraced(function* (server: Server, options: { readonly host?: string; readonly port?: number } = {}) {
 	yield* Effect.acquireRelease(
 		Effect.tryPromise(
 			() =>
 				new Promise<void>((resolve, reject) => {
 					server.once("error", reject);
-					server.listen(0, "127.0.0.1", () => {
+					server.listen(options.port ?? 0, options.host ?? "127.0.0.1", () => {
 						server.off("error", reject);
 						resolve();
 					});