brass-runtime 1.16.1 → 1.18.0

package/docs/frameworks/express.md

@@ -0,0 +1,183 @@
+# Express integration
+
+Express can wire Brass directly at process startup: one observability instance,
+one runtime, one HTTP client, and a shutdown handler.
+
+## App Setup
+
+```ts
+import express from "express";
+import { asyncFlatMap } from "brass-runtime/core";
+import {
+  defineHttpPolicyPresets,
+  makeDefaultHttpClient,
+} from "brass-runtime/http";
+import {
+  logEffect,
+  makeExpressRequestObservabilityContext,
+  makeObservability,
+  makeOtlpOptions,
+  withHttpObservability,
+} from "brass-runtime/observability";
+
+const policyPresets = defineHttpPolicyPresets({
+  readModel: {
+    lane: "read-model",
+    priority: 3,
+    retry: { maxRetries: 2, baseDelayMs: 100, maxDelayMs: 1_000 },
+  },
+  command: {
+    lane: "command",
+    priority: 1,
+    retry: false,
+  },
+});
+
+const observability = makeObservability({
+  serviceName: process.env.OTEL_SERVICE_NAME ?? "shop-express",
+  serviceVersion: process.env.OTEL_SERVICE_VERSION,
+  resource: {
+    "deployment.environment": process.env.NODE_ENV ?? "development",
+  },
+  logs: { minLevel: "info" },
+  sampling: { ratio: 0.25, respectRemoteSampled: true, forceSampleOnError: true },
+  redaction: {},
+  cardinality: { maxValuesPerLabel: 100 },
+  otlp: makeOtlpOptions({
+    endpoint: process.env.GRAFANA_OTLP_ENDPOINT ?? "http://grafana-alloy:4318",
+    headers: process.env.GRAFANA_OTLP_AUTHORIZATION
+      ? { Authorization: process.env.GRAFANA_OTLP_AUTHORIZATION }
+      : undefined,
+    timeoutMs: 10_000,
+    retry: { attempts: 3, initialDelayMs: 100, maxDelayMs: 2_000 },
+    pipeline: {
+      maxQueueSize: 10_000,
+      batchSize: 512,
+      dropPolicy: "drop-oldest",
+      shutdownTimeoutMs: 10_000,
+    },
+  }),
+  flushIntervalMs: 10_000,
+  autoStart: true,
+});
+
+const http = makeDefaultHttpClient({
+  baseUrl: process.env.USERS_API_BASE_URL ?? "https://users-api.internal",
+  preset: "production",
+  timeoutMs: 5_000,
+  policyPresets,
+  middleware: [withHttpObservability(observability)],
+});
+
+const app = express();
+```
+
+## Routes
+
+```ts
+app.get("/users/:id", async (req, res, next) => {
+  const ctx = makeExpressRequestObservabilityContext(observability, req, {
+    route: "/users/:id",
+  });
+
+  try {
+    const response = await ctx.run(
+      ctx.withRequestSpan(
+        asyncFlatMap(
+          logEffect("info", "users.lookup", {
+            userId: req.params.id,
+            authorization: req.headers.authorization,
+          }),
+          () =>
+            http.getJson(`/users/${req.params.id}`, {
+              policy: "readModel",
+              timeoutMs: 2_000,
+            }),
+        ),
+      ),
+    );
+
+    res.json(response.body);
+  } catch (error) {
+    next(error);
+  }
+});
+
+app.get("/metrics", (_req, res) => {
+  res
+    .type(observability.prometheus.contentType)
+    .send(observability.prometheus.export());
+});
+```
+
+## Shutdown
+
+```ts
+const server = app.listen(process.env.PORT ?? 3000);
+
+process.once("SIGTERM", async () => {
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  await http.shutdown();
+  await observability.shutdown();
+});
+```
+
+Runnable repo example: `src/examples/observabilityExpress.ts`.
+
+## Layer Variant
+
+For larger Express apps, use the Layer/DI helpers to keep startup wiring and
+shutdown ownership together:
+
+```ts
+import { Layer, Runtime, RuntimeService, makeConfigLayer } from "brass-runtime/core";
+import { s } from "brass-runtime/schema";
+import { defineHttpPolicyPresets, 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 ConfigSchema = s.object({
+  serviceName: s.nonEmptyString(),
+  apiBaseUrl: s.url(),
+  otlpEndpoint: s.url(),
+});
+
+const ConfigLayer = makeConfigLayer(Config, ConfigSchema, {
+  serviceName: process.env.OTEL_SERVICE_NAME ?? "shop-express",
+  apiBaseUrl: process.env.USERS_API_BASE_URL ?? "https://users-api.internal",
+  otlpEndpoint: process.env.GRAFANA_OTLP_ENDPOINT ?? "http://grafana-alloy:4318",
+});
+
+const AppLayer = Layer.composeAll(
+  ConfigLayer,
+  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",
+    policyPresets,
+  })),
+);
+
+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/express](https://github.com/BaldrVivaldelli/brass-runtime/tree/main/examples/express).

package/docs/frameworks/fastify.md

@@ -0,0 +1,173 @@
+# Fastify integration
+
+Fastify has its own request shape, so use
+`makeFastifyRequestObservabilityContext` for inbound spans and a shared Brass
+HTTP client for downstream calls.
+
+## App Setup
+
+```ts
+import Fastify from "fastify";
+import { asyncFlatMap } from "brass-runtime/core";
+import {
+  defineHttpPolicyPresets,
+  makeDefaultHttpClient,
+} from "brass-runtime/http";
+import {
+  logEffect,
+  makeFastifyRequestObservabilityContext,
+  makeObservability,
+  makeOtlpOptions,
+  withHttpObservability,
+} from "brass-runtime/observability";
+
+const policyPresets = defineHttpPolicyPresets({
+  readModel: {
+    lane: "read-model",
+    priority: 3,
+    retry: { maxRetries: 2, baseDelayMs: 100, maxDelayMs: 1_000 },
+  },
+  command: {
+    lane: "command",
+    priority: 1,
+    retry: false,
+  },
+});
+
+const observability = makeObservability({
+  serviceName: process.env.OTEL_SERVICE_NAME ?? "shop-fastify",
+  serviceVersion: process.env.OTEL_SERVICE_VERSION,
+  resource: {
+    "deployment.environment": process.env.NODE_ENV ?? "development",
+  },
+  logs: { minLevel: "info" },
+  sampling: { ratio: 0.25, respectRemoteSampled: true, forceSampleOnError: true },
+  redaction: {},
+  cardinality: { maxValuesPerLabel: 100 },
+  otlp: makeOtlpOptions({
+    endpoint: process.env.GRAFANA_OTLP_ENDPOINT ?? "http://grafana-alloy:4318",
+    headers: process.env.GRAFANA_OTLP_AUTHORIZATION
+      ? { Authorization: process.env.GRAFANA_OTLP_AUTHORIZATION }
+      : undefined,
+    timeoutMs: 10_000,
+    retry: { attempts: 3, initialDelayMs: 100, maxDelayMs: 2_000 },
+    pipeline: {
+      maxQueueSize: 10_000,
+      batchSize: 512,
+      dropPolicy: "drop-oldest",
+      shutdownTimeoutMs: 10_000,
+    },
+  }),
+  flushIntervalMs: 10_000,
+  autoStart: true,
+});
+
+const http = makeDefaultHttpClient({
+  baseUrl: process.env.USERS_API_BASE_URL ?? "https://users-api.internal",
+  preset: "production",
+  timeoutMs: 5_000,
+  policyPresets,
+  middleware: [withHttpObservability(observability)],
+});
+
+const app = Fastify({ logger: true });
+```
+
+## Routes
+
+```ts
+app.get("/users/:id", async (request, reply) => {
+  const params = request.params as { id: string };
+  const ctx = makeFastifyRequestObservabilityContext(observability, request, {
+    route: "/users/:id",
+  });
+
+  const response = await ctx.run(
+    ctx.withRequestSpan(
+      asyncFlatMap(
+        logEffect("info", "users.lookup", {
+          userId: params.id,
+          authorization: request.headers.authorization,
+        }),
+        () =>
+          http.getJson(`/users/${params.id}`, {
+            policy: "readModel",
+            timeoutMs: 2_000,
+          }),
+      ),
+    ),
+  );
+
+  return reply.send(response.body);
+});
+
+app.get("/metrics", async (_request, reply) => {
+  return reply
+    .type(observability.prometheus.contentType)
+    .send(observability.prometheus.export());
+});
+```
+
+## Shutdown
+
+```ts
+await app.listen({ port: Number(process.env.PORT ?? 3000), host: "0.0.0.0" });
+
+process.once("SIGTERM", async () => {
+  await app.close();
+  await http.shutdown();
+  await observability.shutdown();
+});
+```
+
+Runnable repo example: `src/examples/observabilityFastify.ts`.
+
+## Layer Variant
+
+Fastify can use the same app graph shape as Express. Build it once during
+startup, read services from the produced `LayerContext`, and close the layer in
+`onClose`/shutdown:
+
+```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: process.env.OTEL_SERVICE_NAME ?? "shop-fastify",
+    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));
+app.decorate("brass", {
+  observability: built.service.unsafeGet(ObservabilityService),
+  runtime: built.service.unsafeGet(RuntimeService),
+  http: built.service.unsafeGet(HttpClientService),
+});
+app.addHook("onClose", () => Runtime.make({}).toPromise(built.close()));
+```

package/docs/frameworks/nestjs.md

@@ -0,0 +1,335 @@
+# NestJS integration
+
+This recipe shows one way to wire Brass into a Nest application with:
+
+- one shared `Observability` instance;
+- OTLP HTTP export to Grafana Cloud, Grafana Alloy, or any collector;
+- one shared production HTTP client with Brass retry, cache, policy,
+  adaptive limiter, and HTTP observability;
+- graceful shutdown for the HTTP client and exporter queues.
+
+Brass stays vendor-neutral. The only Grafana-specific value is the endpoint and
+authorization header supplied by the application.
+
+## Install
+
+```bash
+npm install brass-runtime
+npm install @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata rxjs
+npm install --save-dev @types/express
+```
+
+Example environment:
+
+```bash
+OTEL_SERVICE_NAME=orders-api
+OTEL_SERVICE_VERSION=1.2.3
+GRAFANA_OTLP_ENDPOINT=http://grafana-alloy:4318
+GRAFANA_OTLP_AUTHORIZATION='Basic <grafana-cloud-otlp-token>'
+USERS_API_BASE_URL=https://users-api.internal
+```
+
+`GRAFANA_OTLP_ENDPOINT` can point to Grafana Alloy/OpenTelemetry Collector next
+to the service, or to a direct Grafana Cloud OTLP HTTP endpoint. When you need
+different URLs per signal, pass `otlp: { metricsUrl, tracesUrl, logsUrl }`
+directly instead of `makeOtlpOptions`.
+
+## Brass Module
+
+Create one global module and inject Brass through Nest providers:
+
+```ts
+// brass.module.ts
+import { Global, Inject, Injectable, Module, type OnApplicationShutdown } from "@nestjs/common";
+import { Runtime } from "brass-runtime/core";
+import {
+  defineHttpPolicyPresets,
+  makeDefaultHttpClient,
+  type DefaultHttpClient,
+} from "brass-runtime/http";
+import {
+  makeObservability,
+  makeOtlpOptions,
+  withHttpObservability,
+  type Observability,
+} from "brass-runtime/observability";
+
+export const BRASS_OBSERVABILITY = Symbol("BRASS_OBSERVABILITY");
+export const BRASS_RUNTIME = Symbol("BRASS_RUNTIME");
+export const BRASS_HTTP = Symbol("BRASS_HTTP");
+
+const policyPresets = defineHttpPolicyPresets({
+  readModel: {
+    lane: "read-model",
+    priority: 3,
+    retry: { maxRetries: 2, baseDelayMs: 100, maxDelayMs: 1_000 },
+  },
+  command: {
+    lane: "command",
+    priority: 1,
+    retry: false,
+  },
+});
+
+function grafanaOtlp() {
+  const authorization = process.env.GRAFANA_OTLP_AUTHORIZATION;
+
+  return makeOtlpOptions({
+    endpoint: process.env.GRAFANA_OTLP_ENDPOINT ?? "http://grafana-alloy:4318",
+    headers: authorization ? { Authorization: authorization } : undefined,
+    timeoutMs: 10_000,
+    retry: { attempts: 3, initialDelayMs: 100, maxDelayMs: 2_000 },
+    pipeline: {
+      maxQueueSize: 10_000,
+      batchSize: 512,
+      dropPolicy: "drop-oldest",
+      shutdownTimeoutMs: 10_000,
+    },
+  });
+}
+
+@Injectable()
+class BrassShutdown implements OnApplicationShutdown {
+  constructor(
+    @Inject(BRASS_OBSERVABILITY) private readonly observability: Observability,
+    @Inject(BRASS_HTTP) private readonly http: DefaultHttpClient,
+  ) {}
+
+  async onApplicationShutdown() {
+    await this.http.shutdown();
+    await this.observability.shutdown();
+  }
+}
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: BRASS_OBSERVABILITY,
+      useFactory: () =>
+        makeObservability({
+          serviceName: process.env.OTEL_SERVICE_NAME ?? "orders-api",
+          serviceVersion: process.env.OTEL_SERVICE_VERSION,
+          resource: {
+            "service.namespace": "commerce",
+            "deployment.environment": process.env.NODE_ENV ?? "development",
+          },
+          logs: { minLevel: "info" },
+          sampling: { ratio: 0.25, respectRemoteSampled: true, forceSampleOnError: true },
+          redaction: {},
+          cardinality: { maxValuesPerLabel: 100 },
+          otlp: grafanaOtlp(),
+          flushIntervalMs: 10_000,
+          autoStart: true,
+        }),
+    },
+    {
+      provide: BRASS_RUNTIME,
+      useFactory: (observability: Observability) =>
+        new Runtime({ env: observability.env, hooks: observability.hooks }),
+      inject: [BRASS_OBSERVABILITY],
+    },
+    {
+      provide: BRASS_HTTP,
+      useFactory: (observability: Observability) =>
+        makeDefaultHttpClient({
+          baseUrl: process.env.USERS_API_BASE_URL,
+          preset: "production",
+          timeoutMs: 5_000,
+          policyPresets,
+          middleware: [withHttpObservability(observability)],
+        }),
+      inject: [BRASS_OBSERVABILITY],
+    },
+    BrassShutdown,
+  ],
+  exports: [BRASS_OBSERVABILITY, BRASS_RUNTIME, BRASS_HTTP],
+})
+export class BrassModule {}
+```
+
+Enable shutdown hooks once in `main.ts` so Nest calls `BrassShutdown`:
+
+```ts
+const app = await NestFactory.create(AppModule);
+app.enableShutdownHooks();
+await app.listen(process.env.PORT ?? 3000);
+```
+
+## Use The HTTP Client
+
+Inject the Brass runtime and HTTP client where you call downstream services.
+`withHttpObservability` records outbound metrics, logs, spans, policy context,
+and W3C trace headers.
+
+```ts
+// users.client.ts
+import { Inject, Injectable } from "@nestjs/common";
+import { Runtime } from "brass-runtime/core";
+import type { DefaultHttpClient } from "brass-runtime/http";
+import { BRASS_HTTP, BRASS_RUNTIME } from "./brass.module";
+
+type UserDto = {
+  readonly id: string;
+  readonly name: string;
+};
+
+@Injectable()
+export class UsersClient {
+  constructor(
+    @Inject(BRASS_RUNTIME) private readonly runtime: Runtime<any>,
+    @Inject(BRASS_HTTP) private readonly http: DefaultHttpClient,
+  ) {}
+
+  async getUser(id: string): Promise<UserDto> {
+    const response = await this.runtime.toPromise(
+      this.http.getJson<UserDto>(`/users/${id}`, {
+        policy: "readModel",
+        headers: { "x-client": "orders-api" },
+        timeoutMs: 2_000,
+      }),
+    );
+
+    return response.body;
+  }
+}
+```
+
+For command-style calls, choose a different policy:
+
+```ts
+await this.runtime.toPromise(
+  this.http.postJson("/users", body, {
+    policy: "command",
+    timeoutMs: 3_000,
+  }),
+);
+```
+
+## Inbound Request Spans
+
+For Express-backed Nest apps, reuse the Express request adapter. The request
+context seeds the Brass runtime from inbound `traceparent` / `baggage` headers,
+then wraps your effect in a server span.
+
+```ts
+import { Controller, Get, Inject, Param, Req, Res } from "@nestjs/common";
+import type { Request, Response } from "express";
+import { asyncFlatMap } from "brass-runtime/core";
+import {
+  logEffect,
+  makeExpressRequestObservabilityContext,
+  type Observability,
+} from "brass-runtime/observability";
+import type { DefaultHttpClient } from "brass-runtime/http";
+import { BRASS_HTTP, BRASS_OBSERVABILITY } from "./brass.module";
+
+@Controller()
+export class UsersController {
+  constructor(
+    @Inject(BRASS_OBSERVABILITY) private readonly observability: Observability,
+    @Inject(BRASS_HTTP) private readonly http: DefaultHttpClient,
+  ) {}
+
+  @Get("/users/:id")
+  getUser(@Req() req: Request, @Param("id") id: string) {
+    const ctx = makeExpressRequestObservabilityContext(this.observability, req, {
+      route: "/users/:id",
+    });
+
+    return ctx.run(
+      ctx.withRequestSpan(
+        asyncFlatMap(
+          logEffect("info", "users.lookup", {
+            userId: id,
+            authorization: req.headers.authorization,
+          }),
+          () => this.http.getJson(`/users/${id}`, { policy: "readModel" }),
+        ),
+      ),
+    );
+  }
+
+  @Get("/metrics")
+  metrics(@Res() res: Response) {
+    return res
+      .type(this.observability.prometheus.contentType)
+      .send(this.observability.prometheus.export());
+  }
+}
+```
+
+The `authorization` field is redacted by the default observability redactor.
+
+## Runnable Repo Example
+
+The repo also includes a dependency-optional Nest example:
+
+```bash
+npm install --save-dev @nestjs/core @nestjs/common @nestjs/platform-express reflect-metadata rxjs
+npm run example:observability:nest
+```
+
+## Layer Variant
+
+Nest providers can also be backed by one Brass layer graph. This keeps
+validation, runtime hooks, HTTP observability, and shutdown in one place:
+
+```ts
+import { Runtime, Layer, 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 ?? "orders-api",
+    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 brassProviders = [
+  { provide: BRASS_OBSERVABILITY, useValue: built.service.unsafeGet(ObservabilityService) },
+  { provide: BRASS_RUNTIME, useValue: built.service.unsafeGet(RuntimeService) },
+  { provide: BRASS_HTTP, useValue: built.service.unsafeGet(HttpClientService) },
+  { provide: BRASS_LAYER_CLOSE, useValue: () => Runtime.make({}).toPromise(built.close()) },
+];
+```
+
+It uses a fake OTLP `fetch` by default so it can run without a collector. To
+send to Grafana/Alloy instead:
+
+```bash
+BRASS_EXAMPLE_REAL_OTLP=true \
+GRAFANA_OTLP_ENDPOINT=http://grafana-alloy:4318 \
+GRAFANA_OTLP_AUTHORIZATION='Basic <token>' \
+npm run example:observability:nest
+```
+
+## Runnable Example
+
+A minimal runnable app lives at
+[examples/nestjs](https://github.com/BaldrVivaldelli/brass-runtime/tree/main/examples/nestjs).