brass-runtime 1.17.0 → 1.18.0

package/docs/frameworks/nextjs.md

@@ -145,3 +145,58 @@ export async function POST(
 For Client Components, reuse the React provider recipe and set
 `otlpEndpoint: "/api/otel"`.
 
+## Layer Variant
+
+For Route Handlers, keep a server-only layer singleton and close it from your
+process lifecycle when the platform exposes one:
+
+```ts
+// app/lib/brass.server.ts
+import "server-only";
+import { Layer, Runtime, RuntimeService, makeConfigLayer } from "brass-runtime/core";
+import { s } from "brass-runtime/schema";
+import { HttpClientService } from "brass-runtime/http";
+import {
+  ObservabilityService,
+  makeObservabilityLayer,
+  makeObservedRuntimeLayer,
+  makeObservedHttpClientLayer,
+  makeOtlpOptions,
+} from "brass-runtime/observability";
+
+const Config = Layer.tag<{ serviceName: string; apiBaseUrl: string; otlpEndpoint: string }>("Config");
+const AppLayer = Layer.composeAll(
+  makeConfigLayer(Config, s.object({
+    serviceName: s.nonEmptyString(),
+    apiBaseUrl: s.url(),
+    otlpEndpoint: s.url(),
+  }), {
+    serviceName: process.env.OTEL_SERVICE_NAME ?? "shop-next",
+    apiBaseUrl: process.env.USERS_API_BASE_URL ?? "https://users-api.internal",
+    otlpEndpoint: process.env.GRAFANA_OTLP_ENDPOINT ?? "http://grafana-alloy:4318",
+  }),
+  makeObservabilityLayer((ctx) => {
+    const config = ctx.unsafeGet(Config);
+    return { serviceName: config.serviceName, otlp: makeOtlpOptions({ endpoint: config.otlpEndpoint }) };
+  }),
+  makeObservedRuntimeLayer(),
+  makeObservedHttpClientLayer((ctx) => ({
+    baseUrl: ctx.unsafeGet(Config).apiBaseUrl,
+    preset: "production",
+  })),
+);
+
+const built = await Runtime.make({}).toPromise(Layer.build(AppLayer));
+
+export const brass = {
+  observability: built.service.unsafeGet(ObservabilityService),
+  runtime: built.service.unsafeGet(RuntimeService),
+  http: built.service.unsafeGet(HttpClientService),
+  shutdown: () => Runtime.make({}).toPromise(built.close()),
+};
+```
+
+## Runnable Example
+
+A minimal runnable app lives at
+[examples/nextjs](https://github.com/BaldrVivaldelli/brass-runtime/tree/main/examples/nextjs).

package/docs/frameworks/react.md

@@ -137,3 +137,47 @@ export function Profile() {
 Point `/api/otel` to a server route that owns the collector credentials. The
 Next.js recipe includes one proxy example; the same idea works in any BFF.
 
+## Layer Variant
+
+The provider can build a layer graph instead of manually constructing each
+service. In browser apps, use a same-origin OTLP proxy and close the layer from
+the React cleanup:
+
+```tsx
+import { Layer, Runtime, RuntimeService, makeConfigLayer } from "brass-runtime/core";
+import { s } from "brass-runtime/schema";
+import { HttpClientService } from "brass-runtime/http";
+import {
+  makeObservabilityLayer,
+  makeObservedRuntimeLayer,
+  makeObservedHttpClientLayer,
+  makeOtlpOptions,
+} from "brass-runtime/observability";
+
+const Config = Layer.tag<{ serviceName: string; apiBaseUrl: string; otlpEndpoint: string }>("Config");
+const AppLayer = Layer.composeAll(
+  makeConfigLayer(Config, s.object({
+    serviceName: s.nonEmptyString(),
+    apiBaseUrl: s.string(),
+    otlpEndpoint: s.string(),
+  }), { serviceName: "shop-react", apiBaseUrl: "/api", otlpEndpoint: "/api/otel" }),
+  makeObservabilityLayer((ctx) => {
+    const config = ctx.unsafeGet(Config);
+    return { serviceName: config.serviceName, otlp: makeOtlpOptions({ endpoint: config.otlpEndpoint }) };
+  }),
+  makeObservedRuntimeLayer(),
+  makeObservedHttpClientLayer((ctx) => ({ baseUrl: ctx.unsafeGet(Config).apiBaseUrl, preset: "balanced" })),
+);
+
+const built = await Runtime.make({}).toPromise(Layer.build(AppLayer));
+const brass = {
+  runtime: built.service.unsafeGet(RuntimeService),
+  http: built.service.unsafeGet(HttpClientService),
+  shutdown: () => Runtime.make({}).toPromise(built.close()),
+};
+```
+
+## Runnable Example
+
+A minimal runnable app lives at
+[examples/react](https://github.com/BaldrVivaldelli/brass-runtime/tree/main/examples/react).

package/docs/frameworks/vanilla.md

@@ -222,3 +222,59 @@ process.once("SIGTERM", async () => {
 server.listen(process.env.PORT ?? 3000);
 ```
 
+## Layer Variant
+
+For scripts, CLIs, workers, or small Node servers, a layer graph keeps startup
+and teardown explicit without a framework:
+
+```ts
+import { Layer, Runtime, RuntimeService, makeConfigLayer } from "brass-runtime/core";
+import { s } from "brass-runtime/schema";
+import { HttpClientService } from "brass-runtime/http";
+import {
+  ObservabilityService,
+  makeObservabilityLayer,
+  makeObservedRuntimeLayer,
+  makeObservedHttpClientLayer,
+  makeOtlpOptions,
+} from "brass-runtime/observability";
+
+const Config = Layer.tag<{ serviceName: string; apiBaseUrl: string; otlpEndpoint: string }>("Config");
+const AppLayer = Layer.composeAll(
+  makeConfigLayer(Config, s.object({
+    serviceName: s.nonEmptyString(),
+    apiBaseUrl: s.url(),
+    otlpEndpoint: s.url(),
+  }), {
+    serviceName: "worker",
+    apiBaseUrl: "https://users-api.internal",
+    otlpEndpoint: "http://grafana-alloy:4318",
+  }),
+  makeObservabilityLayer((ctx) => {
+    const config = ctx.unsafeGet(Config);
+    return { serviceName: config.serviceName, otlp: makeOtlpOptions({ endpoint: config.otlpEndpoint }) };
+  }),
+  makeObservedRuntimeLayer(),
+  makeObservedHttpClientLayer((ctx) => ({
+    baseUrl: ctx.unsafeGet(Config).apiBaseUrl,
+    preset: "production",
+  })),
+);
+
+const built = await Runtime.make({}).toPromise(Layer.build(AppLayer));
+const runtime = built.service.unsafeGet(RuntimeService);
+const http = built.service.unsafeGet(HttpClientService);
+const observability = built.service.unsafeGet(ObservabilityService);
+
+try {
+  await runtime.toPromise(http.getJson("/users/42"));
+  console.log(observability.prometheus.export());
+} finally {
+  await Runtime.make({}).toPromise(built.close());
+}
+```
+
+## Runnable Example
+
+A minimal runnable app lives at
+[examples/vanilla](https://github.com/BaldrVivaldelli/brass-runtime/tree/main/examples/vanilla).

package/docs/guides/layers.md

@@ -111,6 +111,136 @@ await runtime.toPromise(
 );
 ```
 
+For wider independent graphs, prefer `Layer.all(...)` / `mergeAll(...)` over
+deeply nested `merge(...)` calls:
+
+```ts
+const AppLayer = Layer.all(ConfigLayer, DbLayer, CacheLayer);
+```
+
+For ordered graphs where each context layer reads services produced by previous
+layers, use `Layer.composeAll(...)`:
+
+```ts
+const AppLayer = Layer.composeAll(ConfigLayer, DbLayer, RepoLayer);
+```
+
+## Accessing Services
+
+Use `Layer.use(...)` or `Layer.useAll(...)` when a program should consume
+services without manually calling `ctx.unsafeGet(...)`.
+
+```ts
+import { Layer, asyncSucceed } from "brass-runtime";
+
+const Config = Layer.tag<{ readonly baseUrl: string }>("Config");
+const Http = Layer.tag<{ readonly get: (path: string) => string }>("Http");
+
+const ConfigLayer = Layer.value(Config, { baseUrl: "https://api.example.com" });
+const HttpLayer = Layer.effect(Http, (ctx) => {
+  const config = ctx.unsafeGet(Config);
+  return asyncSucceed({
+    get: (path) => `${config.baseUrl}${path}`,
+  });
+});
+
+const AppLayer = Layer.composeAll(ConfigLayer, HttpLayer);
+
+await runtime.toPromise(
+  Layer.provideContext(
+    AppLayer,
+    Layer.useAll({ config: Config, http: Http }, ({ config, http }) =>
+      asyncSucceed(http.get(`/users?origin=${config.baseUrl}`)),
+    ),
+  ),
+);
+```
+
+`getService(tag)` and `getServices({ ...tags })` remain available when a program
+is directly evaluated with a `LayerContext` as its environment. `Layer.use(...)`
+and `Layer.useAll(...)` are better fits for `Layer.provideContext(...)`.
+
+## Application Graphs
+
+Application modules can model config, observability, and HTTP clients as
+services. That keeps framework code focused on wiring and lets tests swap any
+piece with a smaller layer.
+
+```ts
+import { Runtime, Layer, makeConfigLayer } from "brass-runtime/core";
+import { s } from "brass-runtime/schema";
+import { defineHttpPolicyPresets, HttpClientService } from "brass-runtime/http";
+import {
+  makeObservabilityLayer,
+  makeObservedRuntimeLayer,
+  makeObservedHttpClientLayer,
+  makeOtlpOptions,
+} from "brass-runtime/observability";
+
+type AppConfig = {
+  readonly serviceName: string;
+  readonly apiBaseUrl: string;
+  readonly otlpEndpoint: string;
+};
+
+const AppConfig = Layer.tag<AppConfig>("AppConfig");
+const AppConfigSchema = s.object({
+  serviceName: s.nonEmptyString(),
+  apiBaseUrl: s.url(),
+  otlpEndpoint: s.url(),
+});
+
+const policyPresets = defineHttpPolicyPresets({
+  readModel: { lane: "read-model", priority: 3, retry: { maxRetries: 2 } },
+  command: { lane: "command", priority: 1, retry: false },
+});
+
+const ConfigLayer = makeConfigLayer(AppConfig, AppConfigSchema, {
+  serviceName: "orders-api",
+  apiBaseUrl: "https://users-api.internal",
+  otlpEndpoint: "http://grafana-alloy:4318",
+});
+
+const ObservabilityLayer = makeObservabilityLayer((ctx) => {
+  const config = ctx.unsafeGet(AppConfig);
+  return {
+    serviceName: config.serviceName,
+    otlp: makeOtlpOptions({ endpoint: config.otlpEndpoint }),
+    flushIntervalMs: 10_000,
+    autoStart: true,
+  };
+});
+
+const HttpLayer = makeObservedHttpClientLayer((ctx) => {
+  const config = ctx.unsafeGet(AppConfig);
+  return {
+    baseUrl: config.apiBaseUrl,
+    preset: "production",
+    policyPresets,
+  };
+}, {
+  httpObservability: {
+    policy: { labelKeys: ["preset", "lane"] },
+  },
+});
+
+const AppLayer = Layer.composeAll(
+  ConfigLayer,
+  ObservabilityLayer,
+  makeObservedRuntimeLayer(),
+  HttpLayer,
+);
+
+const program = Layer.use(HttpClientService, (http) =>
+  http.getJson("/users/42", { policy: "readModel" }),
+);
+
+const runtime = Runtime.make({});
+const response = await runtime.toPromise(
+  Layer.provideContext(AppLayer, program),
+);
+```
+
 ## Scoped Builds
 
 Use `buildLayer` or `Layer.build` when a caller wants manual lifecycle control.

package/docs/http-recipes.md

@@ -72,6 +72,35 @@ configs automatically. `.json()` infers Axios/Fetch-shaped responses. Use
 `.json((res) => res.payload, (res) => ({ status: res.code }))` when the
 external client uses a different response shape.
 
+## Node Proxy Transport
+
+```ts
+import { toPromise } from "brass-runtime";
+import { makeNodeHttpProxyClient } from "brass-runtime/http";
+
+const http = makeNodeHttpProxyClient({
+  baseUrl: "https://api.example.com",
+  nodeTransport: {
+    maxSockets: 512,
+    maxFreeSockets: 512,
+  },
+  pool: {
+    key: "origin",
+    concurrency: 512,
+    maxQueue: 512,
+  },
+});
+
+await http.getJson("/users/1").unsafeRunPromise();
+await toPromise(http.shutdown(), {});
+```
+
+Use this in Node BFF/proxy services when benchmark evidence shows the default
+`fetch` backend is the bottleneck. The factory uses
+`preset: "highThroughputProxy"` and performs the final I/O through
+`node:http` / `node:https` keep-alive agents while keeping Brass cancellation,
+pooling, stats, policy, and observability.
+
 ## Named Policy Presets
 
 ```ts
@@ -363,7 +392,8 @@ try {
 `preset: "production"` is the explicit name for the full default stack:
 timeout, priority, retry, dedup, adaptive limiter, safe-method response cache,
 response compression, stats, and shutdown. `preset: "default"` is the same
-stack kept for compatibility.
+stack kept for compatibility. `preset: "highThroughputProxy"` is the explicit
+hot BFF/proxy preset, and `preset: "proxy"` is its shorter compatibility alias.
 
 Construction-time validation catches invalid setup before traffic starts:
 

package/docs/http.md

@@ -205,6 +205,28 @@ That keeps timeout, pool/adaptive limiter, stats, retry, cache, deduplication
 and cancellation in Brass while letting the final I/O backend be `fetch`,
 Axios, undici, a test double, or an internal client.
 
+For Node BFF/proxy workloads where `fetch`/Undici is the limiting cost, Brass
+also ships a first-party `node:http` / `node:https` transport and a Node-only
+factory for the recommended high-throughput proxy shape:
+
+```ts
+import { toPromise } from "brass-runtime";
+import { makeNodeHttpProxyClient } from "brass-runtime/http";
+
+const http = makeNodeHttpProxyClient({
+  baseUrl: "https://api.example.com",
+  nodeTransport: {
+    maxSockets: 512,
+    maxFreeSockets: 512,
+  },
+});
+
+await toPromise(http.shutdown(), {}); // closes owned Node agents
+```
+
+Use this path only in Node services. Browser and edge runtimes should keep the
+default `fetch` transport or inject their platform client.
+
 ```ts
 import {
   makeDefaultHttpClient,
@@ -358,7 +380,10 @@ Named presets are available as `conservative`, `balanced`, and `aggressive`.
 The default HTTP client uses `balanced` for `preset: "balanced"` and
 `aggressive` for `preset: "default"` / `preset: "production"`.
 `production` is the explicit name for the full production-ready default stack;
-`default` remains as the compatibility name. Use `adaptiveLimiterPresets` or
+`default` remains as the compatibility name. Use
+`preset: "highThroughputProxy"` for high-throughput BFF/proxy paths where
+Brass should not add priority/adaptive queues or timeout timers by default;
+`preset: "proxy"` is the shorter compatibility alias. Use `adaptiveLimiterPresets` or
 `makeAdaptiveLimiterConfig(preset, overrides)` when you want a documented
 adaptive limiter baseline with a few local overrides.
 
@@ -371,6 +396,25 @@ attributes receive `preset`, `lane`, `poolKey`, `dedupKey`, `priority`, and retr
 overrides automatically, while metric labels stay opt-in through
 `policy.labelKeys` to avoid accidental high-cardinality metrics.
 
+For application graphs, the HTTP subpath also exposes a DI layer helper. The
+layer owns the default client lifecycle and calls `shutdown()` when released:
+
+```ts
+import { Layer } from "brass-runtime/core";
+import { HttpClientService, makeDefaultHttpClientLayer } from "brass-runtime/http";
+
+const Config = Layer.tag<{ readonly apiBaseUrl: string }>("Config");
+
+const HttpLayer = makeDefaultHttpClientLayer((ctx) => ({
+  baseUrl: ctx.unsafeGet(Config).apiBaseUrl,
+  preset: "production",
+}));
+
+const program = Layer.use(HttpClientService, (http) =>
+  http.getJson("/users/42"),
+);
+```
+
 See [`http-recipes.md`](http-recipes.md) for typed API client, testing,
 observability, retry, adaptive limiter, and config validation recipes.
 
@@ -490,6 +534,7 @@ adopters' tests:
 ```ts
 import {
   makeJsonHttpResponse,
+  makeMockDefaultHttpClientLayer,
   makeMockHttpClient,
   runHttpEffect,
   withMockFetch,
@@ -497,6 +542,10 @@ import {
 
 const mock = makeMockHttpClient((req) => makeJsonHttpResponse({ url: req.url }));
 const wire = await runHttpEffect(mock({ method: "GET", url: "/users/1" }));
+
+const MockHttpLayer = makeMockDefaultHttpClientLayer((req) =>
+  makeJsonHttpResponse({ url: req.url }),
+);
 ```
 
 ---

package/docs/observability.md

@@ -236,6 +236,91 @@ The exporters are dependency-free:
 - `makeObservability` returns `hooks`, `env`, `metrics`, `tracer`, exporters,
   plus `flush()`, `start()`, `stop()`, and `shutdown()`.
 
+### High-TPS HTTP proxy path
+
+For BFF/proxy paths where p99 matters more than full per-request tracing, keep
+HTTP client metrics separate from global runtime hooks. Runtime hooks are useful
+for fiber/span/log visibility, but on a hot proxy path they add work to every
+effect execution.
+
+```ts
+import { Runtime } from "brass-runtime/core";
+import { makeDefaultHttpClient } from "brass-runtime/http";
+import { makeObservability, withHttpObservability } from "brass-runtime/observability";
+
+const observability = makeObservability({
+  metrics: false,
+  logs: false,
+  traces: false,
+  autoStart: false,
+});
+
+// Deliberately no observability hooks on this runtime.
+const runtime = Runtime.make({});
+
+const http = makeDefaultHttpClient({
+  baseUrl: "https://api.example.com",
+  preset: "highThroughputProxy",
+  middleware: [
+    withHttpObservability({
+      metrics: observability.metrics,
+      logs: false,
+      spans: false,
+      adaptiveLimiter: false,
+      injectTraceHeaders: false,
+      includeHostLabel: false,
+      route: "/downstream/:id",
+    }),
+  ],
+});
+
+await runtime.toPromise(http.getJson("/downstream/123"));
+```
+
+Use stable `route` values instead of raw URLs, and enable `includeHostLabel`
+only when the client really talks to multiple downstream hosts. If you need
+traces on the same path, prefer HTTP-only sampled spans through `spanSink`
+instead of global runtime hooks. Use a separate fully observed runtime/client
+for diagnostic flows that need every fiber event.
+
+For a sampled span path with lower per-request overhead, keep runtime metrics
+off, avoid runtime hooks, avoid per-request HTTP span events, and only inject
+`traceparent` when a downstream needs propagation:
+
+```ts
+const traced = makeObservability({
+  metrics: false,
+  logs: false,
+  sampling: 0.001,
+  autoStart: false,
+});
+
+const tracedRuntime = new Runtime({
+  env: traced.env,
+});
+
+const tracedHttp = makeDefaultHttpClient({
+  baseUrl: "https://api.example.com",
+  preset: "highThroughputProxy",
+  middleware: [
+    withHttpObservability({
+      metrics: traced.metrics,
+      logs: false,
+      spans: { events: false, sampleRate: 0.001 },
+      spanSink: traced.tracer,
+      adaptiveLimiter: false,
+      injectTraceHeaders: false,
+      includeHostLabel: false,
+      route: "/downstream/:id",
+    }),
+  ],
+});
+```
+
+`sampleRate` lets the HTTP middleware skip tracing before touching the current
+fiber/runtime on unsampled requests. This keeps p99 low on hot proxy paths while
+still retaining a sampled trace stream.
+
 ### HTTP policy observability
 
 ```ts
@@ -430,6 +515,53 @@ const http = makeDefaultHttpClient({
 });
 ```
 
+For applications that use Brass layers, observability can own both the
+observability lifecycle and an observed HTTP client:
+
+```ts
+import { Layer } from "brass-runtime/core";
+import { HttpClientService } from "brass-runtime/http";
+import {
+  makeObservabilityLayer,
+  makeObservedRuntimeLayer,
+  makeObservedHttpClientLayer,
+  makeOtlpOptions,
+} from "brass-runtime/observability";
+
+const Config = Layer.tag<{
+  readonly serviceName: string;
+  readonly apiBaseUrl: string;
+  readonly otlpEndpoint: string;
+}>("Config");
+
+const ConfigLayer = Layer.value(Config, {
+  serviceName: "orders-api",
+  apiBaseUrl: "https://users-api.internal",
+  otlpEndpoint: "http://grafana-alloy:4318",
+});
+
+const ObservabilityLayer = makeObservabilityLayer((ctx) => {
+  const config = ctx.unsafeGet(Config);
+  return {
+    serviceName: config.serviceName,
+    otlp: makeOtlpOptions({ endpoint: config.otlpEndpoint }),
+    flushIntervalMs: 10_000,
+    autoStart: true,
+  };
+});
+
+const HttpLayer = makeObservedHttpClientLayer((ctx) => ({
+  baseUrl: ctx.unsafeGet(Config).apiBaseUrl,
+  preset: "production",
+}));
+
+const AppLayer = Layer.composeAll(ConfigLayer, ObservabilityLayer, makeObservedRuntimeLayer(), HttpLayer);
+
+const program = Layer.use(HttpClientService, (http) =>
+  http.getJson("/users/42"),
+);
+```
+
 Sampling can be configured globally, by ratio, or with rules:
 
 ```ts

package/docs/performance-profiler.md

@@ -128,6 +128,9 @@ HTTP layer profile:
 - `node-http-text`
 - `wire-raw`
 - `default-minimal-json`
+- `default-proxy-json`
+- `default-proxy-node-json`
+- `high-throughput-proxy-node-json`
 - `default-balanced-no-adaptive-json`
 - `default-balanced-json`
 - `default-json`
@@ -141,8 +144,9 @@ HTTP long-run memory lab:
 
 - defaults to `forceGc: true`, so use `node --expose-gc` for the strongest
   retained-memory signal
-- compares node transport, wire raw, minimal, balanced without adaptive,
-  balanced, default, and default+observability variants
+- compares node transport, wire raw, minimal, proxy, proxy+node transport,
+  high-throughput proxy+node transport, balanced without adaptive, balanced,
+  default, and default+observability variants
 - reports heap/rss totals, max p99, mean throughput, errors, and
   `heapDeltaPer10kRequestsMb`
 - highlights whether memory is `ok`, `watch`, `critical`, or `unknown-gc`

package/docs/recipes/layers.md

@@ -32,8 +32,9 @@ const RepoLayer = Layer.effect(Repo, (ctx: LayerContext) => {
 const AppLayer = Layer.compose(ConfigLayer, RepoLayer);
 
 const userUrl = await runPromise(
-  provideContext(AppLayer, (ctx) =>
-    asyncSucceed(ctx.unsafeGet(Repo).findUser("u1")),
+  provideContext(
+    AppLayer,
+    Layer.use(Repo, (repo) => asyncSucceed(repo.findUser("u1"))),
   ),
 );
 
@@ -42,3 +43,46 @@ console.log(userUrl);
 
 Missing services throw `MissingLayerServiceError`; use `formatLayerError` when
 surfacing the message.
+
+For independent layers, `Layer.all(...)` keeps composition readable. For
+ordered context graphs where later layers read earlier services, use
+`Layer.composeAll(...)`. `Layer.useAll(...)` reads multiple services without
+manual context access:
+
+```ts
+const Logger = defineService<{ readonly info: (message: string) => void }>("Logger");
+const LoggerLayer = Layer.value(Logger, console);
+
+const AppLayer2 = Layer.composeAll(ConfigLayer, RepoLayer, LoggerLayer);
+
+await runPromise(
+  provideContext(
+    AppLayer2,
+    Layer.useAll({ repo: Repo, logger: Logger }, ({ repo, logger }) => {
+      logger.info("loading user");
+      return asyncSucceed(repo.findUser("u1"));
+    }),
+  ),
+);
+```
+
+For app wiring, prefer the focused helpers:
+
+```ts
+import { RuntimeService, makeConfigLayer, makeRuntimeLayer, makeTestLayer } from "brass-runtime";
+import { s } from "brass-runtime/schema";
+
+const ConfigSchema = s.object({ baseUrl: s.url() });
+
+const ConfigLayer2 = makeConfigLayer(Config, ConfigSchema, {
+  baseUrl: "https://api.example.com",
+});
+
+const RuntimeLayer = makeRuntimeLayer((ctx) => ({
+  config: ctx.unsafeGet(Config),
+}));
+
+const TestConfigLayer = makeTestLayer(Config, {
+  baseUrl: "https://test.example.com",
+});
+```

package/docs/recipes/testing.md

@@ -33,6 +33,31 @@ const response = await runHttpEffect(client({ method: "GET", url: "/health" }));
 console.log(response.status);
 ```
 
+Layer-based applications can swap services with `makeTestLayer`,
+`makeTestLayers`, or a mock default HTTP client layer:
+
+```ts
+import { Layer, makeTestLayer } from "brass-runtime/core";
+import { HttpClientService } from "brass-runtime/http";
+import {
+  makeJsonHttpResponse,
+  makeMockDefaultHttpClientLayer,
+} from "brass-runtime/http/testing";
+
+const Config = Layer.tag<{ readonly baseUrl: string }>("Config");
+
+const TestLayer = Layer.composeAll(
+  makeTestLayer(Config, { baseUrl: "test://users" }),
+  makeMockDefaultHttpClientLayer((req) =>
+    makeJsonHttpResponse({ url: req.url }),
+  ),
+);
+
+const program = Layer.use(HttpClientService, (http) =>
+  http.getJson("/users/1"),
+);
+```
+
 For typed failures, assert on `Exit` instead of catching thrown values.
 
 ```ts