brass-runtime 1.16.1 → 1.18.0

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/nestjs.md

@@ -0,0 +1,6 @@
+# NestJS integration
+
+The NestJS recipe now lives at [`docs/frameworks/nestjs.md`](./frameworks/nestjs.md).
+
+This file is kept as a compatibility pointer for older links.
+

package/docs/observability-framework-examples.md

@@ -7,6 +7,10 @@ flush OTLP metrics/traces.
 They use optional framework dependencies so the runtime package does not force
 Express, Fastify, or Nest into normal installs.
 
+For production-style integration recipes across React, Next.js, Angular,
+Express, Fastify, and Nest, see
+[`docs/framework-integrations.md`](./framework-integrations.md).
+
 ## Express
 
 ```bash
@@ -61,9 +65,17 @@ curl http://localhost:3002/metrics
 
 Source: `src/examples/observabilityNest.ts`.
 
+For a production-style Nest module with DI tokens, Grafana/OTLP configuration,
+an observed Brass HTTP client, and shutdown wiring, see
+[`docs/frameworks/nestjs.md`](./frameworks/nestjs.md).
+
 ## What the examples demonstrate
 
 - `makeObservabilityFromEnv(process.env)` for deployment-style setup.
+- `makeOtlpOptions(...)` for collector endpoint configuration without adding
+  vendor-specific code to Brass.
+- `withHttpObservability(...)` around the Brass HTTP client for outbound
+  metrics, spans, logs, policy context, and trace propagation.
 - Framework-specific request adapters:
   - `makeExpressRequestObservabilityContext`
   - `makeFastifyRequestObservabilityContext`

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
@@ -327,6 +412,156 @@ collector does not create overlapping exports.
 Finished spans are pruned after successful export and can also be bounded with
 `traces.maxFinishedSpans` / `traces.maxSpanAgeMs`.
 
+### Vendor-neutral collector recipes
+
+Brass intentionally does not know about Grafana Cloud, AppDynamics, or any
+OpenTelemetry SDK implementation. The runtime only needs OTLP HTTP endpoint
+URLs, headers, and optional export tuning. Keep vendor naming in application
+code by writing small helpers that call the backend-neutral `makeOtlpOptions`.
+
+```ts
+import {
+  makeObservability,
+  makeOtlpOptions,
+  type ObservabilityOtlpOptions,
+} from "brass-runtime/observability";
+
+function productionOtlp(input: {
+  readonly endpoint: string;
+  readonly headers?: Record<string, string>;
+}): ObservabilityOtlpOptions {
+  return makeOtlpOptions({
+    endpoint: input.endpoint,
+    headers: input.headers,
+    timeoutMs: 10_000,
+    retry: { attempts: 3, initialDelayMs: 100, maxDelayMs: 2_000 },
+    pipeline: {
+      maxQueueSize: 10_000,
+      batchSize: 512,
+      dropPolicy: "drop-oldest",
+      shutdownTimeoutMs: 10_000,
+    },
+  });
+}
+```
+
+Grafana Cloud can be configured as a direct OTLP endpoint or through
+Grafana Alloy/OpenTelemetry Collector. The helper stays in your app and only
+returns Brass OTLP config:
+
+```ts
+function grafanaCloudCollector(input: {
+  readonly endpoint: string;
+  readonly authorization?: string;
+}): ObservabilityOtlpOptions {
+  return productionOtlp({
+    endpoint: input.endpoint,
+    headers: input.authorization
+      ? { Authorization: input.authorization }
+      : undefined,
+  });
+}
+
+const observability = makeObservability({
+  serviceName: "shopping-ms",
+  serviceVersion: "1.2.3",
+  resource: {
+    "service.namespace": "shopping",
+    "deployment.environment": "production",
+  },
+  otlp: grafanaCloudCollector({
+    endpoint: process.env.GRAFANA_OTLP_ENDPOINT!,
+    authorization: process.env.GRAFANA_OTLP_AUTHORIZATION,
+  }),
+});
+```
+
+For AppDynamics, prefer sending Brass telemetry to the AppDynamics/OpenTelemetry
+Collector deployed next to the service. Authentication and vendor-specific
+exporters stay in the collector config:
+
+```ts
+function appDynamicsCollector(input: {
+  readonly endpoint: string;
+}): ObservabilityOtlpOptions {
+  return productionOtlp({
+    endpoint: input.endpoint,
+  });
+}
+
+const observability = makeObservability({
+  serviceName: "car-rental-ms",
+  serviceVersion: "1.2.3",
+  resource: {
+    "service.namespace": "car-rental",
+    "deployment.environment": "production",
+  },
+  otlp: appDynamicsCollector({
+    endpoint: process.env.APPD_OTEL_COLLECTOR_ENDPOINT ?? "http://appd-otel-collector:4318",
+  }),
+});
+```
+
+Then attach the same observability instance to HTTP without changing the
+collector helpers:
+
+```ts
+import { makeDefaultHttpClient } from "brass-runtime/http";
+import { withHttpObservability } from "brass-runtime/observability";
+
+const http = makeDefaultHttpClient({
+  baseUrl: "https://api.example.com",
+  middleware: [withHttpObservability(observability)],
+});
+```
+
+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
@@ -423,6 +658,10 @@ const router = makeHttpRouter([
 
 Runnable framework examples live in
 [`docs/observability-framework-examples.md`](./observability-framework-examples.md).
+Production-style framework integration recipes live in
+[`docs/framework-integrations.md`](./framework-integrations.md).
+For a NestJS module recipe with Grafana/OTLP, DI tokens, HTTP client
+observability, and shutdown wiring, see [`docs/frameworks/nestjs.md`](./frameworks/nestjs.md).
 
 Collector smoke and performance budget helpers:
 

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brass-runtime",
-  "version": "1.16.1",
+  "version": "1.18.0",
   "description": "Effect runtime utilities for TypeScript",
   "license": "MIT",
   "author": "Augusto Vivaldelli",
@@ -116,6 +116,9 @@
     "benchmark:runtime": "tsx src/benchmarks/runner.ts runtime-performance-track",
     "benchmark:runtime:budget": "node scripts/check-runtime-benchmark-budget.mjs",
     "benchmark:http": "tsx src/benchmarks/runner.ts http-concurrent",
+    "benchmark:http:proxy": "BRASS_HTTP_BENCH_VARIANTS=node-http-text,default-minimal-json,default-proxy-json,default-proxy-node-json,default-json tsx src/benchmarks/runner.ts http-concurrent",
+    "benchmark:http:proxy:300tps": "BRASS_HTTP_RAMP_CLIENT=proxy BRASS_HTTP_RAMP_MAX_TPS=300 BRASS_HTTP_RAMP_STEP_TPS=300 BRASS_HTTP_RAMP_STEP_SECONDS=180 BRASS_HTTP_RAMP_CONCURRENCY=600 tsx src/benchmarks/runner.ts http-ramp-tps",
+    "benchmark:http:overhead": "tsx src/benchmarks/runner.ts http-local-overhead",
     "benchmark:http:soak": "BRASS_HTTP_BENCH_MODE=soak tsx src/benchmarks/runner.ts http-concurrent",
     "benchmark:http:budget": "node scripts/check-http-benchmark-budget.mjs",
     "benchmark:http:ramp": "tsx src/benchmarks/runner.ts http-ramp-tps",