brass-runtime 1.16.0 → 1.17.0

package/docs/modules.md

@@ -0,0 +1,285 @@
+# 📦 Modules — brass-runtime
+
+This document describes the current and planned modules in **brass-runtime**, how they relate to each other, and how users are expected to navigate them.
+
+The structure intentionally mirrors the mental model of **ZIO**:
+- a small, principled **core**
+- optional, layered **modules**
+- everything expressed in terms of typed effects and structured concurrency
+
+---
+
+## Core modules (foundation)
+
+These modules form the **runtime kernel**. Everything else builds on top of them.
+
+### `runtime`
+**Status:** ✅ stable
+
+Responsible for executing effects.
+
+Contents:
+- `Scheduler` — cooperative, deterministic task scheduler
+- task queue, microtask flushing
+- fairness and explicit async boundaries
+
+You almost never interact with this directly as a user.
+
+---
+
+### `asyncEffect` / `types`
+**Status:** ✅ stable
+
+The heart of the system.
+
+Key types:
+- `Effect<R, E, A>`
+- `Async<R, E, A>`
+- `Exit<E, A>`
+
+Capabilities:
+- sync + async algebra (no Promises in semantics)
+- `map`, `flatMap`, `fold`, etc.
+- explicit async registration via callbacks
+
+This is the **semantic core** of brass.
+
+---
+
+### `fiber`
+**Status:** ✅ stable
+
+Lightweight fibers with structured lifecycle.
+
+Features:
+- `Fiber<E, A>` abstraction
+- cooperative interruption
+- `join`, `interrupt`
+- LIFO finalizers
+
+Fibers are always run under a `Scope`.
+
+---
+
+### `scope`
+**Status:** ✅ stable
+
+Structured concurrency and resource safety.
+
+Features:
+- parent / child scopes
+- deterministic cleanup
+- `addFinalizer`, `close`
+- used by fibers, streams, HTTP, resources
+
+Scopes ensure:
+> no leaks, no zombies, no forgotten cleanup
+
+---
+
+### `resource`
+**Status:** ✅ stable
+
+Resource-safe acquisition.
+
+API:
+- `acquireRelease`
+- `fromResource`
+
+Ties resource lifetimes to scopes.
+
+---
+
+## Concurrency combinators
+
+### `concurrency`
+**Status:** ✅ stable
+
+High-level structured concurrency.
+
+Includes:
+- `race`
+- `zipPar`
+- `collectAllPar`
+- `fork`
+
+Semantics:
+- loser fibers are interrupted
+- errors propagate deterministically
+- scopes are respected
+
+---
+
+## Stream modules (ZStream-like)
+
+### `stream`
+**Status:** 🚧 active
+
+Pull-based, resource-safe streams.
+
+Key ideas:
+- `Pull<R, E, A>`
+- `ZStream<R, E, A>`
+- explicit backpressure
+- scope-aware
+
+Includes:
+- constructors (`fromArray`, `fromPull`, `empty`)
+- transformations (`map`, `filter`)
+- execution (`runCollect`, `collectStream`)
+
+---
+
+### `buffer`
+**Status:** 🚧 active
+
+Stream buffering with backpressure.
+
+Features:
+- bounded buffers
+- backpressure vs dropping modes
+- deterministic cleanup
+
+This is the foundation for:
+- pipelines
+- async boundaries in streams
+- future hubs
+
+---
+
+### Planned stream modules
+**Status:** ⏳ planned
+
+- `pipeline` — ZPipeline-style transformations
+- `sink` — consumers / reducers
+- `hub` — broadcast / pub-sub streams
+- `channel` — low-level streaming algebra
+
+---
+
+## HTTP module
+
+### `http`
+**Status:** ✅ usable / evolving
+
+ZIO-HTTP–inspired client built on brass runtime.
+
+Layers:
+- **wire layer**: `HttpClient = Request => Async<_, HttpError, HttpWireResponse>`
+- **middleware**: request/response transforms
+- **DX layer**: ergonomic helpers (`getJson`, `postJson`, etc.)
+
+Key concepts:
+- fully lazy
+- cancelable via fibers
+- no Promises in core semantics
+- middleware-style composition (`withMeta`, logging, retries, auth)
+
+Submodules:
+- `client.ts` — low-level HTTP execution
+- `httpClient.ts` — DX + helpers
+- `withMeta` — response enrichment middleware
+
+Example usage:
+```ts
+const http = httpClientBuilder({ baseUrl }).withMeta();
+
+const post = await toPromise(http.getJson<Post>("/posts/1"), {});
+```
+
+---
+
+## Interop modules
+
+### `promise`
+**Status:** ✅ stable
+
+Interop with Promise-based APIs.
+
+Includes:
+- `toPromise` — await effects externally
+- `fromPromiseAbortable`
+- `tryPromiseAbortable`
+
+Important:
+> Promises are **interop only**, never a runtime primitive.
+
+---
+
+## Examples module
+
+### `examples`
+**Status:** ✅ maintained
+
+Executable documentation.
+
+Covers:
+- fibers & interruption
+- scopes & finalizers
+- abortable promises
+- streams + buffering
+- HTTP usage
+
+If you’re new:
+👉 start here.
+
+---
+
+## How to navigate the project
+
+### If you want to…
+
+**Understand the runtime**
+- `asyncEffect`
+- `scheduler`
+- `fiber`
+- `scope`
+
+**Use effects**
+- `map`, `flatMap`, `fold`
+- `toPromise` (interop only)
+
+**Do concurrency**
+- `race`
+- `zipPar`
+- `fork`
+
+**Work with streams**
+- `stream`
+- `buffer`
+
+**Call HTTP**
+- `http/client`
+- `http/httpClient`
+- middleware like `withMeta`
+
+---
+
+## Design philosophy
+
+- Explicit > implicit
+- Structured > ad-hoc
+- Lazy by default
+- Cancellation is cooperative and visible
+- No hidden async semantics
+
+brass is not trying to be “easy first” — it’s trying to be **correct first**.
+
+---
+
+## Future directions
+
+- Public API stabilization
+- Docs site (mdbook / Docusaurus)
+- ZIO-style module layering (`Layer`-like)
+- Metrics & tracing middleware
+- Typed errors across HTTP + streams
+
+---
+
+If you want:
+- a **diagram** of module dependencies
+- a **shorter npm-facing version**
+- or a **ZIO comparison table**
+
+say the word.

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-collector-smoke.md

@@ -0,0 +1,31 @@
+# Observability collector smoke
+
+This smoke test sends one metric payload, one trace payload, and one log payload
+to a real OpenTelemetry Collector over OTLP/HTTP.
+
+Start the collector:
+
+```bash
+docker compose -f docker-compose.observability.yml up
+```
+
+In another shell:
+
+```bash
+npm run build:ts
+npm run smoke:observability:collector
+```
+
+The collector config is `docs/otel-collector-smoke.yaml` and uses the debug
+exporter, so accepted telemetry is printed in the collector logs.
+
+Useful environment variables:
+
+```bash
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+OTEL_SERVICE_NAME=brass-observability-smoke
+BRASS_OBSERVABILITY_EXPORT_TIMEOUT_MS=5000
+```
+
+The smoke intentionally uses the public built package from `dist` so it checks
+the same CJS/ESM package surface that users consume after a build.

package/docs/observability-framework-examples.md

@@ -0,0 +1,110 @@
+# Observability framework examples
+
+These examples show how to seed Brass runtime traces from inbound HTTP headers,
+create a request span, emit structured logs, expose Prometheus metrics, and
+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
+npm install --save-dev express
+npm run example:observability:express
+```
+
+Try it:
+
+```bash
+curl -H 'traceparent: 00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01' \
+  http://localhost:3000/users/42
+
+curl http://localhost:3000/metrics
+```
+
+Source: `src/examples/observabilityExpress.ts`.
+
+## Fastify
+
+```bash
+npm install --save-dev fastify
+npm run example:observability:fastify
+```
+
+Try it:
+
+```bash
+curl -H 'traceparent: 00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01' \
+  http://localhost:3001/users/42
+
+curl http://localhost:3001/metrics
+```
+
+Source: `src/examples/observabilityFastify.ts`.
+
+## Nest
+
+```bash
+npm install --save-dev @nestjs/core @nestjs/common @nestjs/platform-express reflect-metadata rxjs
+npm run example:observability:nest
+```
+
+Try it:
+
+```bash
+curl -H 'traceparent: 00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01' \
+  http://localhost:3002/users/42
+
+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`
+- W3C `traceparent` extraction from inbound headers.
+- `ctx.withRequestSpan(...)` around request work.
+- `logEffect(...)` with redaction of sensitive fields like `authorization`.
+- `/metrics` endpoint using the Prometheus exporter.
+- OTLP export through a fake local `fetch` that prints payload sizes.
+
+## Benchmark
+
+Run only the observability overhead benchmark:
+
+```bash
+npm run benchmark:observability
+npm run benchmark:observability:budget
+```
+
+Or include it in the full benchmark suite:
+
+```bash
+npm run benchmark
+```
+
+The benchmark source is `src/benchmarks/observability-overhead.bench.ts` and
+measures:
+
+- baseline `asyncSucceed`
+- `withSpan` start/end overhead
+- `logEffect` structured sink overhead
+- composed span + event + log overhead
+- OTLP trace flush for 25 spans