@shivaedev/test-story 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.7.0 - 2026-10-18
+
+### Added
+
+- `fakeHttpService` serves a scoped loopback API for story kits, with named path-param routes, an auth guard, JSON pages, one-shot replies, request holds and an ordered request log. Bind `narrate(story.tell)` to tell requests and controls in the story.
+
+### Changed
+
+- Point application story authors to the shared `story-testing` skill and align README guidance with observable results, explicit assertions and database isolation.
+
 ## 0.6.0 - 2026-10-18
 
 ### Added

package/README.md

@@ -41,6 +41,8 @@ The first line is the assertion's own message. The box under it tells a reader w
 
 ## Using it
 
+Before writing or reviewing application stories, follow the [story-testing skill](https://github.com/ShivaeDev/platform/blob/main/packages/skills/skills/story-testing/SKILL.md), shipped by `@shivaedev/skills`. It owns the rules for observable evidence, boundary-driven setup, verbs and readouts, assertions, jobs, framework gaps, faked preconditions, database isolation and focused runs. The examples below explain this package's API; framework fixtures exercise this package's responsibilities, rather than prescribe application scenarios.
+
 ### How to think about it
 
 An application has an **engine**: the real thing a test drives, such as a bakery simulation, a game store or a service with its database. A **story** is one test's run of a fresh engine. It starts from **traits**, sentences of setup in domain words that each change the engine, and goes on through **verbs**, the entry points a user or caller reaches, such as `baker.kneads(2)` or `oven.bakesEverything()`. The engine may also run on its own, one **step** at a time, until something the test waits for holds. Every trait tells a line, and verbs and steps tell what they do, so the story is both the plan the test gave and the trace of what happened, in order.
@@ -222,6 +224,42 @@ expect(receiver.requests.some(({ body }) => body.includes(Buffer.from("planted-s
 
 For timeout stories, return `undefined` from the `status` callback to accept an export without sending response headers. Set `answer: null` to send headers without completing the response body.
 
+#### Faking an outbound HTTP API
+
+Use `fakeHttpService` from `@shivaedev/test-story/fakeHttpService.ts` in a kit's scoped `create` hook. Like the OTLP receiver, it listens on an allocated loopback port and closes with the scope. Routes have names for controls, a method (default `GET`), and a path whose `:segments` become decoded `request.params`. A reply receives the request and returns a JSON `body`, optional `status` (default 200), and optional response `headers`.
+
+```ts
+import { fakeHttpService } from "@shivaedev/test-story/fakeHttpService.ts";
+
+const api = yield* fakeHttpService({
+  guard: ({ headers }) => headers.authorization === "Bearer story-key",
+  routes: {
+    user: { path: "/users/:id", reply: ({ params }) => ({ body: { id: params.id } }) },
+    items: { path: "/items", pages: [["paper", "ink"], ["pens"]] },
+  },
+});
+```
+
+Point the application's real HTTP client at `api.url`, or use the kit's `outbound` map to route its external hostname there. A service-wide `guard` returns a boolean; a missing or wrong credential gets 401 before holds or scripted replies are consumed. Omit the guard for a public fake. Unmatched paths and methods get 404.
+
+In `verbs`, bind `api.narrate(story.tell)` to tell received requests, replies, rejections and hold controls through the story. An optional `tell` callback can also be supplied at acquisition. The service keeps request headers and bytes in its log; narration of normal requests includes only method, path and status.
+
+```ts
+api.narrate(story.tell);
+yield* api.failOnce("user", { status: 502, body: { error: "try again" } });
+const paused = yield* api.hold("user");
+const pending = yield* Effect.forkChild(application.loadUser("alice"));
+yield* paused.waiting;
+yield* paused.release;
+const user = yield* Fiber.join(pending);
+```
+
+`application.loadUser` is the application's real client call. `failOnce` affects the next authorized matching request to that named route, then the route answers normally. `hold` pauses that route until `release`; `waiting` completes when a request reaches the hold, so a story needs no polling to know when to release it. Other routes still answer. Effects that wait for HTTP should use a live-clock kit.
+
+A `pages` route accepts a one-based `?page=` query and returns `{ items, next }`, with `next: null` on the last page. No query means page 1; a page past the end returns an empty list; a non-positive or non-integer page gets 400. `api.requests` reads a snapshot of the request log, including rejected and held requests, with `method`, `path` (including query), raw `body` Buffer, `headers`, `params` and `query`.
+
+The [fake HTTP stories](https://github.com/ShivaeDev/platform/blob/main/packages/test-story/src/server/outboundApi.spec.ts) use Node fetch to check params, credentials, pages, one-shot failure, hold/release ordering, request logs, narration and listener cleanup.
+
 ### 2. Once per feature: traits and verbs
 
 A trait is a line and a change, tagged with a stage:
@@ -346,29 +384,9 @@ Set `runIf: hasPostgres` in the kit definition to gate all its stories once, whe
 
 The [order feature kit](https://github.com/ShivaeDev/platform/tree/main/packages/effect-react/src/test-support/order-example) runs the existing feature’s services, repository, contracts, JSON serialization and authentication middleware over a loopback HTTP listener. Its [stories](https://github.com/ShivaeDev/platform/blob/main/packages/effect-react/src/orderStory.dom.spec.tsx) test visible commits through a separate PostgreSQL pool, rollback of a rejected write without publication, cross-owner rejection, a native React action refreshing a list, and an editor retaining rejected input before a corrected save.
 
-```ts
-import { app, realPostgres } from "./test-support/application.ts";
-import { aliceHasOrder } from "./test-support/traits.ts";
-
-app.it("a save commits and a rejected write leaves storage intact", [realPostgres(), aliceHasOrder("paper")], function* ({ saveOrder, rejectOrder, storedOrderIs, changesAre }) {
-  yield* saveOrder("paper", "Office chairs", 8);
-  yield* storedOrderIs("paper", "Office chairs", 8);
-  yield* rejectOrder("paper", -1);
-  yield* storedOrderIs("paper", "Office chairs", 8);
-  yield* changesAre(1);
-});
-```
-
-The application’s worker Layer leases a uniquely named disposable database, opens native PgClient pools and runs `migratePostgres`. Multiple kits in the worker share the database; the last lease drops it after the pools close. The PostgreSQL trait checks that infrastructure and the declared policy; it does not start a database. The application validates its local disposable destination before database creation or reset and skips database stories without `PLATFORM_EFFECT_SQL_TEST_DATABASE_URL`. Tests sharing that database run serially; parallelism belongs between workers or inside one story.
-
-| Application mode | Reset policy | Transaction policy | Coverage |
-| --- | --- | --- | --- |
-| HTTP | Truncate application tables and restart identities before and after the story; retain the migration ledger. | Commands perform real commits. | RPC serialization/transport, independent persistence reads, React refresh and forms. |
-| Local | Reset the baseline before and after the story. | Wrap creation, seeds and body in an outer Platform `transact`, then force rollback after success with a private sentinel. | Local repositories and services, transactional seeds and nested writes. |
-
-The kit’s `around` implements that policy. HTTP requests run in separate fibers, so an outer test transaction cannot isolate their writes. Local rollback starts with Platform `transact`; putting it inside a native outer transaction violates transaction ownership. Catch only the wrapper’s private rollback sentinel, let other failures escape, and check independent storage before cleanup truncation so cleanup cannot hide an accidental commit.
+For full-app stories, use `around: withIsolatedDatabase` from `@shivaedev/effect-test-sql/withIsolatedDatabase.ts` with a PostgreSQL test layer prepared from the application's migrations. Each story gets a database cloned from that template, and HTTP and worker pools commit into the same clone. The clone is dropped after scoped hosts and pools close. The starter's [application kit](https://github.com/ShivaeDev/platform/blob/main/examples/starter/src/test-support/application.ts) uses this isolation path.
 
-Application-authored seed builders reuse application schemas, validate overrides, insert actual rows and return generated values. Traits retain aliases such as `"paper"` so specs avoid generated IDs. There is no shared factory or automatic relationship seeding.
+For repository-level tests on a migrated template, `withTestTransaction` from `@shivaedev/effect-test-sql/withTestTransaction.ts` provides rollback isolation when all work uses its transaction connection. See the [database test helpers](https://github.com/ShivaeDev/platform/blob/main/packages/effect-test-sql/README.md) for template preparation and both wrappers.
 
 React screen traits acquire roots in Scope and use a fresh native atom registry for each screen. Cleanup unmounts roots before disposing registries and servers. Screen verbs dispatch DOM events and use bounded observations of rendered output. Select a live clock once on an HTTP/DOM kit; keep TestClock for deterministic local stories. `runUntil` is for engines with a meaningful step hook, not HTTP or DOM polling. Creation forms can use the same pattern with the existing `useCreate` path.
 
@@ -415,22 +433,7 @@ const cookieApp = storyKit({
 });
 ```
 
-`startHost`, `postgres` and `authVerbs` are application plumbing. The starter's [cookie application kit](https://github.com/ShivaeDev/platform/blob/main/examples/starter/src/test-support/cookieApp.ts) shows the full setup. Its Better Auth client signs up and signs in, and its verbs read `/api/auth/get-session` and post to `/api/auth/sign-out` through the DOM fetch. They do not copy cookies into request headers or use bearer tokens.
-
-```ts
-cookieApp.it("sign-up and sign-in keep their cookie sessions against the PostgreSQL host", [], function* ({ signUp, signIn, signOut, sessionIs }) {
-  yield* signUp();
-  yield* sessionIs("alice@starter.test");
-  yield* signOut();
-  yield* sessionIs(null);
-  yield* signIn();
-  yield* sessionIs("alice@starter.test");
-  yield* signOut();
-  yield* sessionIs(null);
-});
-```
-
-This story proves Better Auth cookie sessions across real loopback HTTP requests from happy-dom with an in-process PostgreSQL host. It also reads sessions through Better Auth's client and checks the fetch response's status, headers and JSON body.
+`startHost`, `postgres` and `authVerbs` are application plumbing. Actions in `authVerbs` perform requests, and readouts return response data for assertions in the spec. A sign-in story drives its real sign-in flow; feature stories start from a faked signed-in precondition as described in the shared skill.
 
 #### Social sign-in through an outbound provider
 
@@ -450,20 +453,23 @@ const socialApp = storyKit({
       await engine.screen.click();
       await domNavigate();
     }),
-    signedInPageIs: (email: string) => Effect.promise(async () => {
-      expect(document.querySelector("h1")?.textContent).toBe(`Signed in as ${email}`);
-      expect(await (await engine.fetch("/api/auth/get-session")).json()).toMatchObject({ user: { email } });
-    }),
+    signedInPage: () => Effect.promise(async () => ({
+      heading: document.querySelector("h1")?.textContent,
+      session: await (await engine.fetch("/api/auth/get-session")).json(),
+    })),
   }),
 });
 
-socialApp.it("a social sign-in returns with a cookie session", [], function* ({ signInWithGitHub, signedInPageIs }) {
+socialApp.it("a social sign-in returns with a cookie session", [], function* ({ signInWithGitHub, signedInPage }) {
   yield* signInWithGitHub();
-  yield* signedInPageIs("alice@social.test");
+  expect(yield* signedInPage()).toMatchObject({
+    heading: "Signed in as alice@social.test",
+    session: { user: { email: "alice@social.test" } },
+  });
 });
 ```
 
-`socialDefinition` starts the host and renders the screen with a Better Auth client whose `customFetchImpl` is `domFetch(baseUrl)`. The [story](https://github.com/ShivaeDev/platform/blob/main/examples/starter/src/server/socialSessions.dom.spec.ts) also checks the authorize, token and user requests at the fake, persisted PostgreSQL rows, and an HttpOnly session cookie read through a later document request. It does not copy cookies into request headers.
+`socialDefinition` starts the host and renders the screen with a Better Auth client whose `customFetchImpl` is `domFetch(baseUrl)`. The authorize, token and user requests at the fake and a later session response provide evidence across the provider and application boundaries. It does not copy cookies into request headers.
 
 `domFetch` uses the current window and its cookie jar; it does not isolate multiple users. Run stories using that window serially, and let the application's cleanup end its sessions, restore the page location and close its host. Cookies follow hostnames, not listener ports, so a different loopback port alone does not isolate accounts.
 
@@ -478,6 +484,8 @@ Import each module with the prefix `@shivaedev/test-story/`; there is no root en
 | `domNavigate.ts` | `domNavigate(url?)` |
 | `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` |
+| `otlpReceiver.ts` | `otlpReceiver(options?)`, `OtlpSpan`, `OtlpExport`, `OtlpReceiverOptions` |
 
 ### Install and limits
 

package/dist/server/fakeHttpService.d.ts

@@ -0,0 +1,42 @@
+import { type IncomingHttpHeaders } from "node:http";
+import { Effect } from "effect";
+export interface FakeHttpRequest {
+    readonly body: Buffer;
+    readonly headers: IncomingHttpHeaders;
+    readonly method: string;
+    readonly params: Readonly<Record<string, string>>;
+    readonly path: string;
+    readonly query: URLSearchParams;
+}
+export interface FakeHttpReply {
+    readonly body?: unknown;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly status?: number;
+}
+export type FakeHttpRoute = {
+    readonly method?: string;
+    readonly path: string;
+} & ({
+    readonly reply: (request: FakeHttpRequest) => FakeHttpReply;
+    readonly pages?: never;
+} | {
+    readonly pages: readonly (readonly unknown[])[];
+    readonly reply?: never;
+});
+export interface FakeHttpServiceOptions {
+    readonly guard?: (request: FakeHttpRequest) => boolean;
+    readonly routes: Readonly<Record<string, FakeHttpRoute>>;
+    readonly tell?: (line: string) => void;
+}
+export interface FakeHttpHold {
+    readonly release: Effect.Effect<void>;
+    readonly waiting: Effect.Effect<void>;
+}
+export declare const fakeHttpService: (options: FakeHttpServiceOptions) => Effect.Effect<{
+    failOnce: (route: string, reply: FakeHttpReply) => Effect.Effect<void, never, never>;
+    hold: (route: string) => Effect.Effect<FakeHttpHold, never, never>;
+    narrate: (sink: (line: string) => void) => void;
+    readonly requests: readonly FakeHttpRequest[];
+    url: string;
+}, import("effect/Cause").UnknownError, import("effect/Scope").Scope>;
+//# sourceMappingURL=fakeHttpService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fakeHttpService.d.ts","sourceRoot":"","sources":["../../src/server/fakeHttpService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAKhC,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,aAAa,GAAG;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB,GAAG,CACD;IAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,aAAa,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GACvF;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,CAC7E,CAAC;AAEF,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC;IACvD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IACzD,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CACtC;AAED,eAAO,MAAM,eAAe;sBAgBR,MAAM,SAAS,aAAa;kBAChC,MAAM;oBACJ,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;uBAGtB,SAAS,eAAe,EAAE;;qEAK1C,CAAC"}

package/dist/server/fakeHttpService.js

@@ -0,0 +1,33 @@
+import { createServer } from "node:http";
+import { Effect } from "effect";
+import { fakeHttpControls } from "#internal/fakeHttpControls.ts";
+import { fakeHttpReceive } from "#internal/fakeHttpReceive.ts";
+import { loopbackServer } from "#internal/loopback.ts";
+export const fakeHttpService = Effect.fnUntraced(function* (options) {
+    const requests = [];
+    let narrate = options.tell;
+    function tell(line) {
+        narrate?.(line);
+    }
+    const controls = fakeHttpControls(tell);
+    const server = createServer((request, response) => fakeHttpReceive(request, response, options, requests, controls, tell));
+    const url = yield* loopbackServer(server);
+    yield* Effect.addFinalizer(() => Effect.sync(controls.close));
+    function checkRoute(route) {
+        if (!Object.hasOwn(options.routes, route)) {
+            throw new Error(`Unknown fake HTTP route "${route}".\nhelp: Use a name from fakeHttpService's routes when scripting a reply or hold.`);
+        }
+    }
+    return {
+        failOnce: (route, reply) => Effect.sync(() => checkRoute(route)).pipe(Effect.andThen(controls.failOnce(route, reply))),
+        hold: (route) => Effect.sync(() => checkRoute(route)).pipe(Effect.andThen(controls.hold(route))),
+        narrate: (sink) => {
+            narrate = sink;
+        },
+        get requests() {
+            return requests.slice();
+        },
+        url,
+    };
+});
+//# sourceMappingURL=fakeHttpService.js.map

package/dist/server/fakeHttpService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fakeHttpService.js","sourceRoot":"","sources":["../../src/server/fakeHttpService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA4B,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAoCvD,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,OAA+B;IAC1F,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,IAAI,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3B,SAAS,IAAI,CAAC,IAAY;QACzB,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IACD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,CAAC,eAAe,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;IAC1H,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IAC1C,KAAK,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9D,SAAS,UAAU,CAAC,KAAa;QAChC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CAAC,4BAA4B,KAAK,oFAAoF,CAAC,CAAC;QACxI,CAAC;IACF,CAAC;IACD,OAAO;QACN,QAAQ,EAAE,CAAC,KAAa,EAAE,KAAoB,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;QAC7I,IAAI,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QACxG,OAAO,EAAE,CAAC,IAA4B,EAAE,EAAE;YACzC,OAAO,GAAG,IAAI,CAAC;QAChB,CAAC;QACD,IAAI,QAAQ;YACX,OAAO,QAAQ,CAAC,KAAK,EAAE,CAAC;QACzB,CAAC;QACD,GAAG;KACH,CAAC;AACH,CAAC,CAAC,CAAC"}

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

@@ -0,0 +1,10 @@
+import { Effect } from "effect";
+import type { FakeHttpHold, FakeHttpReply } from "#fakeHttpService.ts";
+export declare function fakeHttpControls(tell: (line: string) => void): {
+    close: () => void;
+    failOnce: (route: string, reply: FakeHttpReply) => Effect.Effect<void, never, never>;
+    hold: (route: string) => Effect.Effect<FakeHttpHold>;
+    pause: (route: string) => Promise<void>;
+    takeFailure: (route: string) => FakeHttpReply | undefined;
+};
+//# sourceMappingURL=fakeHttpControls.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fakeHttpControls.d.ts","sourceRoot":"","sources":["../../../src/server/internal/fakeHttpControls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEvE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;IAI3D,KAAK;IAKL,QAAQ,UAAU,MAAM,SAAS,aAAa;IAO9C,IAAI,UAAU,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC;IA0BlD,KAAK,UAAgB,MAAM;IAG3B,WAAW,UAAU,MAAM;EAE5B"}

package/dist/server/internal/fakeHttpControls.js

@@ -0,0 +1,48 @@
+import { Deferred, Effect } from "effect";
+export function fakeHttpControls(tell) {
+    const failures = new Map();
+    const holds = new Map();
+    return {
+        close: () => {
+            for (const hold of holds.values()) {
+                hold.release();
+            }
+        },
+        failOnce: (route, reply) => Effect.sync(() => {
+            const queue = failures.get(route) ?? [];
+            queue.push(reply);
+            failures.set(route, queue);
+            tell(`fake HTTP ${route} will answer once with ${reply.status ?? 200}`);
+        }),
+        hold: (route) => Effect.sync(() => {
+            if (holds.has(route)) {
+                throw new Error(`Fake HTTP route "${route}" is already held.\nhelp: Release its current hold before holding the route again.`);
+            }
+            const waiting = Deferred.makeUnsafe();
+            const released = Promise.withResolvers();
+            const hold = {
+                enter: () => {
+                    tell(`fake HTTP ${route} has a waiting request`);
+                    Deferred.doneUnsafe(waiting, Effect.void);
+                    return released.promise;
+                },
+                release: () => {
+                    if (holds.get(route) !== hold) {
+                        return;
+                    }
+                    holds.delete(route);
+                    released.resolve();
+                    tell(`fake HTTP ${route} released`);
+                },
+            };
+            holds.set(route, hold);
+            tell(`fake HTTP ${route} held`);
+            return { release: Effect.sync(hold.release), waiting: Deferred.await(waiting) };
+        }),
+        pause: async (route) => {
+            await holds.get(route)?.enter();
+        },
+        takeFailure: (route) => failures.get(route)?.shift(),
+    };
+}
+//# sourceMappingURL=fakeHttpControls.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fakeHttpControls.js","sourceRoot":"","sources":["../../../src/server/internal/fakeHttpControls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAG1C,MAAM,UAAU,gBAAgB,CAAC,IAA4B;IAC5D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAC;IACpD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAiF,CAAC;IACvG,OAAO;QACN,KAAK,EAAE,GAAG,EAAE;YACX,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;gBACnC,IAAI,CAAC,OAAO,EAAE,CAAC;YAChB,CAAC;QACF,CAAC;QACD,QAAQ,EAAE,CAAC,KAAa,EAAE,KAAoB,EAAE,EAAE,CACjD,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;YAChB,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YACxC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClB,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAC3B,IAAI,CAAC,aAAa,KAAK,0BAA0B,KAAK,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC;QACzE,CAAC,CAAC;QACH,IAAI,EAAE,CAAC,KAAa,EAA+B,EAAE,CACpD,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;YAChB,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACtB,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,oFAAoF,CAAC,CAAC;YAChI,CAAC;YACD,MAAM,OAAO,GAAG,QAAQ,CAAC,UAAU,EAAQ,CAAC;YAC5C,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,EAAQ,CAAC;YAC/C,MAAM,IAAI,GAAG;gBACZ,KAAK,EAAE,GAAG,EAAE;oBACX,IAAI,CAAC,aAAa,KAAK,wBAAwB,CAAC,CAAC;oBACjD,QAAQ,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;oBAC1C,OAAO,QAAQ,CAAC,OAAO,CAAC;gBACzB,CAAC;gBACD,OAAO,EAAE,GAAG,EAAE;oBACb,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;wBAC/B,OAAO;oBACR,CAAC;oBACD,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBACpB,QAAQ,CAAC,OAAO,EAAE,CAAC;oBACnB,IAAI,CAAC,aAAa,KAAK,WAAW,CAAC,CAAC;gBACrC,CAAC;aACD,CAAC;YACF,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YACvB,IAAI,CAAC,aAAa,KAAK,OAAO,CAAC,CAAC;YAChC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACjF,CAAC,CAAC;QACH,KAAK,EAAE,KAAK,EAAE,KAAa,EAAE,EAAE;YAC9B,MAAM,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC;QACjC,CAAC;QACD,WAAW,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE;KAC5D,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,5 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { FakeHttpRequest, FakeHttpServiceOptions } from "#fakeHttpService.ts";
+import type { fakeHttpControls } from "#internal/fakeHttpControls.ts";
+export declare function fakeHttpReceive(incoming: IncomingMessage, response: ServerResponse, options: FakeHttpServiceOptions, requests: FakeHttpRequest[], controls: ReturnType<typeof fakeHttpControls>, tell: (line: string) => void): Promise<void>;
+//# sourceMappingURL=fakeHttpReceive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fakeHttpReceive.d.ts","sourceRoot":"","sources":["../../../src/server/internal/fakeHttpReceive.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAiB,eAAe,EAAiB,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACjH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAmDtE,wBAAsB,eAAe,CACpC,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,sBAAsB,EAC/B,QAAQ,EAAE,eAAe,EAAE,EAC3B,QAAQ,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,EAC7C,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,iBAoD5B"}

package/dist/server/internal/fakeHttpReceive.js

@@ -0,0 +1,102 @@
+function match(route, method, pathname) {
+    if ((route.method ?? "GET").toUpperCase() !== method) {
+        return;
+    }
+    const pattern = route.path.split("/");
+    const segments = pathname.split("/");
+    if (pattern.length !== segments.length) {
+        return;
+    }
+    const params = {};
+    for (const [index, part] of pattern.entries()) {
+        const segment = segments[index] ?? "";
+        if (part.startsWith(":")) {
+            params[part.slice(1)] = segment;
+        }
+        else if (part !== segment) {
+            return;
+        }
+    }
+    return params;
+}
+function decodeParams(params) {
+    try {
+        for (const [name, value] of Object.entries(params)) {
+            params[name] = decodeURIComponent(value);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function pageReply(route, request) {
+    if (route.reply) {
+        return route.reply(request);
+    }
+    const page = Number(request.query.get("page") ?? "1");
+    if (!Number.isInteger(page) || page < 1) {
+        return { body: { error: "page must be a positive integer" }, status: 400 };
+    }
+    return { body: { items: route.pages[page - 1] ?? [], next: page < route.pages.length ? page + 1 : null } };
+}
+function send(response, reply) {
+    const body = reply.body === undefined ? undefined : JSON.stringify(reply.body);
+    response.writeHead(reply.status ?? 200, { "content-type": "application/json", ...reply.headers });
+    response.end(body);
+}
+export async function fakeHttpReceive(incoming, response, options, requests, controls, tell) {
+    try {
+        const path = incoming.url ?? "/";
+        const url = new URL(path, "http://127.0.0.1");
+        const method = incoming.method ?? "GET";
+        const found = Object.entries(options.routes).flatMap(([name, route]) => {
+            const params = match(route, method, url.pathname);
+            return params ? [{ name, params, route }] : [];
+        })[0];
+        const chunks = [];
+        for await (const chunk of incoming) {
+            chunks.push(Buffer.from(chunk));
+        }
+        const params = found?.params ?? {};
+        const request = {
+            body: Buffer.concat(chunks),
+            headers: incoming.headers,
+            method,
+            params,
+            path,
+            query: url.searchParams,
+        };
+        requests.push(request);
+        tell(`fake HTTP received ${method} ${path}`);
+        if (!decodeParams(params)) {
+            tell(`fake HTTP rejected ${method} ${path} with 400`);
+            send(response, { status: 400 });
+            return;
+        }
+        if (options.guard && !options.guard(request)) {
+            tell(`fake HTTP rejected ${method} ${path} with 401`);
+            send(response, { status: 401 });
+            return;
+        }
+        if (!found) {
+            tell(`fake HTTP answered ${method} ${path} with 404`);
+            send(response, { status: 404 });
+            return;
+        }
+        await controls.pause(found.name);
+        const reply = controls.takeFailure(found.name) ?? pageReply(found.route, request);
+        tell(`fake HTTP answered ${method} ${path} with ${reply.status ?? 200}`);
+        send(response, reply);
+    }
+    catch (error) {
+        tell(`fake HTTP could not answer: ${String(error)}`);
+        if (response.headersSent) {
+            response.end();
+        }
+        else {
+            send(response, { status: 500 });
+        }
+    }
+}
+//# sourceMappingURL=fakeHttpReceive.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fakeHttpReceive.js","sourceRoot":"","sources":["../../../src/server/internal/fakeHttpReceive.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,4 @@
+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>;
+//# sourceMappingURL=loopback.d.ts.map

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

@@ -0,0 +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"}

package/dist/server/internal/loopback.js

@@ -0,0 +1,19 @@
+import { Effect } from "effect";
+export const loopbackServer = Effect.fnUntraced(function* (server) {
+    yield* Effect.acquireRelease(Effect.tryPromise(() => new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    })), () => Effect.promise(() => new Promise((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+        server.closeAllConnections();
+    })));
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        return yield* Effect.die("Missing loopback HTTP server address.\nhelp: The scoped HTTP server must be listening before reading its URL.");
+    }
+    return `http://127.0.0.1:${address.port}`;
+});
+//# sourceMappingURL=loopback.js.map

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

@@ -0,0 +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"}

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

@@ -1 +1 @@
-{"version":3,"file":"otlpReceiver.d.ts","sourceRoot":"","sources":["../../src/server/otlpReceiver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,mBAAmB,EAA6C,MAAM,WAAW,CAAC;AAC9G,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAC9D,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AACD,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;CACrE;AAmCD,eAAO,MAAM,YAAY;uBA4Ba,SAAS,UAAU,EAAE;oBAAkB,SAAS,QAAQ,EAAE;kBAAgB,MAAM;qEAMpH,CAAC"}
+{"version":3,"file":"otlpReceiver.d.ts","sourceRoot":"","sources":["../../src/server/otlpReceiver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,mBAAmB,EAA6C,MAAM,WAAW,CAAC;AAC9G,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAC9D,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AACD,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;CACrE;AAmCD,eAAO,MAAM,YAAY;uBAKa,SAAS,UAAU,EAAE;oBAAkB,SAAS,QAAQ,EAAE;kBAAgB,MAAM;qEAMpH,CAAC"}

package/dist/server/otlpReceiver.js

@@ -1,5 +1,6 @@
 import { createServer } from "node:http";
 import { Effect } from "effect";
+import { loopbackServer } from "#internal/loopback.ts";
 import { otlpReadout } from "#internal/otlpReadout.ts";
 async function receive(request, response, requests, spans, options) {
     try {
@@ -39,24 +40,11 @@ export const otlpReceiver = Effect.fnUntraced(function* (options = {}) {
     const requests = [];
     const spans = [];
     const server = createServer((request, response) => receive(request, response, requests, spans, options));
-    yield* Effect.acquireRelease(Effect.tryPromise(() => new Promise((resolve, reject) => {
-        server.once("error", reject);
-        server.listen(0, "127.0.0.1", () => {
-            server.off("error", reject);
-            resolve();
-        });
-    })), () => Effect.promise(() => new Promise((resolve, reject) => {
-        server.close((error) => (error ? reject(error) : resolve()));
-        server.closeAllConnections();
-    })));
-    const address = server.address();
-    if (address === null || typeof address === "string") {
-        return yield* Effect.die("Missing OTLP receiver address");
-    }
+    const url = yield* loopbackServer(server);
     const receiver = {
         requests,
         spans,
-        url: `http://127.0.0.1:${address.port}`,
+        url,
     };
     return receiver;
 });

package/dist/server/otlpReceiver.js.map

@@ -1 +1 @@
-{"version":3,"file":"otlpReceiver.js","sourceRoot":"","sources":["../../src/server/otlpReceiver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"otlpReceiver.js","sourceRoot":"","sources":["../../src/server/otlpReceiver.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/test-story",
-  "version": "0.6.0",
+  "version": "0.7.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": {
@@ -47,7 +47,7 @@
   },
   "devDependencies": {
     "@effect/vitest": "4.0.4",
-    "@shivaedev/quality": "0.23.0",
+    "@shivaedev/quality": "0.24.0",
     "@types/node": "24.19.2",
     "@typescript/native": "npm:typescript@7.0.2",
     "effect": "4.0.4",

package/src/server/fakeHttpService.ts

@@ -0,0 +1,67 @@
+import { createServer, type IncomingHttpHeaders } from "node:http";
+import { Effect } from "effect";
+import { fakeHttpControls } from "#internal/fakeHttpControls.ts";
+import { fakeHttpReceive } from "#internal/fakeHttpReceive.ts";
+import { loopbackServer } from "#internal/loopback.ts";
+
+export interface FakeHttpRequest {
+	readonly body: Buffer;
+	readonly headers: IncomingHttpHeaders;
+	readonly method: string;
+	readonly params: Readonly<Record<string, string>>;
+	readonly path: string;
+	readonly query: URLSearchParams;
+}
+
+export interface FakeHttpReply {
+	readonly body?: unknown;
+	readonly headers?: Readonly<Record<string, string>>;
+	readonly status?: number;
+}
+
+export type FakeHttpRoute = {
+	readonly method?: string;
+	readonly path: string;
+} & (
+	| { readonly reply: (request: FakeHttpRequest) => FakeHttpReply; readonly pages?: never }
+	| { readonly pages: readonly (readonly unknown[])[]; readonly reply?: never }
+);
+
+export interface FakeHttpServiceOptions {
+	readonly guard?: (request: FakeHttpRequest) => boolean;
+	readonly routes: Readonly<Record<string, FakeHttpRoute>>;
+	readonly tell?: (line: string) => void;
+}
+
+export interface FakeHttpHold {
+	readonly release: Effect.Effect<void>;
+	readonly waiting: Effect.Effect<void>;
+}
+
+export const fakeHttpService = Effect.fnUntraced(function* (options: FakeHttpServiceOptions) {
+	const requests: FakeHttpRequest[] = [];
+	let narrate = options.tell;
+	function tell(line: string) {
+		narrate?.(line);
+	}
+	const controls = fakeHttpControls(tell);
+	const server = createServer((request, response) => fakeHttpReceive(request, response, options, requests, controls, tell));
+	const url = yield* loopbackServer(server);
+	yield* Effect.addFinalizer(() => Effect.sync(controls.close));
+	function checkRoute(route: string) {
+		if (!Object.hasOwn(options.routes, route)) {
+			throw new Error(`Unknown fake HTTP route "${route}".\nhelp: Use a name from fakeHttpService's routes when scripting a reply or hold.`);
+		}
+	}
+	return {
+		failOnce: (route: string, reply: FakeHttpReply) => Effect.sync(() => checkRoute(route)).pipe(Effect.andThen(controls.failOnce(route, reply))),
+		hold: (route: string) => Effect.sync(() => checkRoute(route)).pipe(Effect.andThen(controls.hold(route))),
+		narrate: (sink: (line: string) => void) => {
+			narrate = sink;
+		},
+		get requests(): readonly FakeHttpRequest[] {
+			return requests.slice();
+		},
+		url,
+	};
+});

package/src/server/internal/fakeHttpControls.ts

@@ -0,0 +1,51 @@
+import { Deferred, Effect } from "effect";
+import type { FakeHttpHold, FakeHttpReply } from "#fakeHttpService.ts";
+
+export function fakeHttpControls(tell: (line: string) => void) {
+	const failures = new Map<string, FakeHttpReply[]>();
+	const holds = new Map<string, { readonly enter: () => Promise<void>; readonly release: () => void }>();
+	return {
+		close: () => {
+			for (const hold of holds.values()) {
+				hold.release();
+			}
+		},
+		failOnce: (route: string, reply: FakeHttpReply) =>
+			Effect.sync(() => {
+				const queue = failures.get(route) ?? [];
+				queue.push(reply);
+				failures.set(route, queue);
+				tell(`fake HTTP ${route} will answer once with ${reply.status ?? 200}`);
+			}),
+		hold: (route: string): Effect.Effect<FakeHttpHold> =>
+			Effect.sync(() => {
+				if (holds.has(route)) {
+					throw new Error(`Fake HTTP route "${route}" is already held.\nhelp: Release its current hold before holding the route again.`);
+				}
+				const waiting = Deferred.makeUnsafe<void>();
+				const released = Promise.withResolvers<void>();
+				const hold = {
+					enter: () => {
+						tell(`fake HTTP ${route} has a waiting request`);
+						Deferred.doneUnsafe(waiting, Effect.void);
+						return released.promise;
+					},
+					release: () => {
+						if (holds.get(route) !== hold) {
+							return;
+						}
+						holds.delete(route);
+						released.resolve();
+						tell(`fake HTTP ${route} released`);
+					},
+				};
+				holds.set(route, hold);
+				tell(`fake HTTP ${route} held`);
+				return { release: Effect.sync(hold.release), waiting: Deferred.await(waiting) };
+			}),
+		pause: async (route: string) => {
+			await holds.get(route)?.enter();
+		},
+		takeFailure: (route: string) => failures.get(route)?.shift(),
+	};
+}

package/src/server/internal/fakeHttpReceive.ts

@@ -0,0 +1,112 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { FakeHttpReply, FakeHttpRequest, FakeHttpRoute, FakeHttpServiceOptions } from "#fakeHttpService.ts";
+import type { fakeHttpControls } from "#internal/fakeHttpControls.ts";
+
+function match(route: FakeHttpRoute, method: string, pathname: string) {
+	if ((route.method ?? "GET").toUpperCase() !== method) {
+		return;
+	}
+	const pattern = route.path.split("/");
+	const segments = pathname.split("/");
+	if (pattern.length !== segments.length) {
+		return;
+	}
+	const params: Record<string, string> = {};
+	for (const [index, part] of pattern.entries()) {
+		const segment = segments[index] ?? "";
+		if (part.startsWith(":")) {
+			params[part.slice(1)] = segment;
+		} else if (part !== segment) {
+			return;
+		}
+	}
+	return params;
+}
+
+function decodeParams(params: Record<string, string>) {
+	try {
+		for (const [name, value] of Object.entries(params)) {
+			params[name] = decodeURIComponent(value);
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function pageReply(route: FakeHttpRoute, request: FakeHttpRequest): FakeHttpReply {
+	if (route.reply) {
+		return route.reply(request);
+	}
+	const page = Number(request.query.get("page") ?? "1");
+	if (!Number.isInteger(page) || page < 1) {
+		return { body: { error: "page must be a positive integer" }, status: 400 };
+	}
+	return { body: { items: route.pages[page - 1] ?? [], next: page < route.pages.length ? page + 1 : null } };
+}
+
+function send(response: ServerResponse, reply: FakeHttpReply) {
+	const body = reply.body === undefined ? undefined : JSON.stringify(reply.body);
+	response.writeHead(reply.status ?? 200, { "content-type": "application/json", ...reply.headers });
+	response.end(body);
+}
+
+export async function fakeHttpReceive(
+	incoming: IncomingMessage,
+	response: ServerResponse,
+	options: FakeHttpServiceOptions,
+	requests: FakeHttpRequest[],
+	controls: ReturnType<typeof fakeHttpControls>,
+	tell: (line: string) => void,
+) {
+	try {
+		const path = incoming.url ?? "/";
+		const url = new URL(path, "http://127.0.0.1");
+		const method = incoming.method ?? "GET";
+		const found = Object.entries(options.routes).flatMap(([name, route]) => {
+			const params = match(route, method, url.pathname);
+			return params ? [{ name, params, route }] : [];
+		})[0];
+		const chunks: Buffer[] = [];
+		for await (const chunk of incoming) {
+			chunks.push(Buffer.from(chunk));
+		}
+		const params = found?.params ?? {};
+		const request: FakeHttpRequest = {
+			body: Buffer.concat(chunks),
+			headers: incoming.headers,
+			method,
+			params,
+			path,
+			query: url.searchParams,
+		};
+		requests.push(request);
+		tell(`fake HTTP received ${method} ${path}`);
+		if (!decodeParams(params)) {
+			tell(`fake HTTP rejected ${method} ${path} with 400`);
+			send(response, { status: 400 });
+			return;
+		}
+		if (options.guard && !options.guard(request)) {
+			tell(`fake HTTP rejected ${method} ${path} with 401`);
+			send(response, { status: 401 });
+			return;
+		}
+		if (!found) {
+			tell(`fake HTTP answered ${method} ${path} with 404`);
+			send(response, { status: 404 });
+			return;
+		}
+		await controls.pause(found.name);
+		const reply = controls.takeFailure(found.name) ?? pageReply(found.route, request);
+		tell(`fake HTTP answered ${method} ${path} with ${reply.status ?? 200}`);
+		send(response, reply);
+	} catch (error) {
+		tell(`fake HTTP could not answer: ${String(error)}`);
+		if (response.headersSent) {
+			response.end();
+		} else {
+			send(response, { status: 500 });
+		}
+	}
+}

package/src/server/internal/loopback.ts

@@ -0,0 +1,30 @@
+import type { Server } from "node:http";
+import { Effect } from "effect";
+
+export const loopbackServer = Effect.fnUntraced(function* (server: Server) {
+	yield* Effect.acquireRelease(
+		Effect.tryPromise(
+			() =>
+				new Promise<void>((resolve, reject) => {
+					server.once("error", reject);
+					server.listen(0, "127.0.0.1", () => {
+						server.off("error", reject);
+						resolve();
+					});
+				}),
+		),
+		() =>
+			Effect.promise(
+				() =>
+					new Promise<void>((resolve, reject) => {
+						server.close((error) => (error ? reject(error) : resolve()));
+						server.closeAllConnections();
+					}),
+			),
+	);
+	const address = server.address();
+	if (address === null || typeof address === "string") {
+		return yield* Effect.die("Missing loopback HTTP server address.\nhelp: The scoped HTTP server must be listening before reading its URL.");
+	}
+	return `http://127.0.0.1:${address.port}`;
+});

package/src/server/otlpReceiver.ts

@@ -1,5 +1,6 @@
 import { createServer, type IncomingHttpHeaders, type IncomingMessage, type ServerResponse } from "node:http";
 import { Effect } from "effect";
+import { loopbackServer } from "#internal/loopback.ts";
 import { otlpReadout } from "#internal/otlpReadout.ts";
 
 export type OtlpSpan = ReturnType<typeof otlpReadout>[number];
@@ -52,34 +53,11 @@ export const otlpReceiver = Effect.fnUntraced(function* (options: OtlpReceiverOp
 	const requests: OtlpExport[] = [];
 	const spans: OtlpSpan[] = [];
 	const server = createServer((request, response) => receive(request, response, requests, spans, options));
-	yield* Effect.acquireRelease(
-		Effect.tryPromise(
-			() =>
-				new Promise<void>((resolve, reject) => {
-					server.once("error", reject);
-					server.listen(0, "127.0.0.1", () => {
-						server.off("error", reject);
-						resolve();
-					});
-				}),
-		),
-		() =>
-			Effect.promise(
-				() =>
-					new Promise<void>((resolve, reject) => {
-						server.close((error) => (error ? reject(error) : resolve()));
-						server.closeAllConnections();
-					}),
-			),
-	);
-	const address = server.address();
-	if (address === null || typeof address === "string") {
-		return yield* Effect.die("Missing OTLP receiver address");
-	}
+	const url = yield* loopbackServer(server);
 	const receiver: { readonly requests: readonly OtlpExport[]; readonly spans: readonly OtlpSpan[]; readonly url: string } = {
 		requests,
 		spans,
-		url: `http://127.0.0.1:${address.port}`,
+		url,
 	};
 	return receiver;
 });