brass-runtime 1.16.0 → 1.17.0

package/docs/frameworks/nestjs.md

@@ -0,0 +1,282 @@
+# 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
+```
+
+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
+```
+

package/docs/frameworks/nextjs.md

@@ -0,0 +1,147 @@
+# Next.js integration
+
+Use Brass in Next.js with a server-only singleton for Route Handlers and a
+same-origin OTLP proxy for browser telemetry.
+
+## Server Singleton
+
+```ts
+// app/lib/brass.server.ts
+import "server-only";
+import { Runtime } from "brass-runtime/core";
+import {
+  defineHttpPolicyPresets,
+  makeDefaultHttpClient,
+} from "brass-runtime/http";
+import {
+  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-next",
+  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,
+});
+
+export const brass = {
+  observability,
+  runtime: new Runtime({ env: observability.env, hooks: observability.hooks }),
+  http: makeDefaultHttpClient({
+    baseUrl: process.env.USERS_API_BASE_URL ?? "https://users-api.internal",
+    preset: "production",
+    timeoutMs: 5_000,
+    policyPresets,
+    middleware: [withHttpObservability(observability)],
+  }),
+};
+```
+
+## Route Handler
+
+Use `makeFetchRequestObservabilityContext` for App Router route handlers.
+
+```ts
+// app/api/users/[id]/route.ts
+import { makeFetchRequestObservabilityContext } from "brass-runtime/observability";
+import { brass } from "@/app/lib/brass.server";
+
+export async function GET(
+  request: Request,
+  { params }: { params: { id: string } | Promise<{ id: string }> },
+) {
+  const { id } = await params;
+  const ctx = makeFetchRequestObservabilityContext(brass.observability, request, {
+    route: "/api/users/[id]",
+  });
+
+  const response = await ctx.run(
+    ctx.withRequestSpan(
+      brass.http.getJson(`/users/${id}`, {
+        policy: "readModel",
+        timeoutMs: 2_000,
+      }),
+    ),
+  );
+
+  return Response.json(response.body);
+}
+```
+
+## Browser OTLP Proxy
+
+Client Components should never hold collector credentials. Use a route handler
+as a narrow same-origin proxy:
+
+```ts
+// app/api/otel/[...path]/route.ts
+const allowedSignals = new Set(["v1/metrics", "v1/traces", "v1/logs"]);
+
+export async function POST(
+  request: Request,
+  { params }: { params: { path: string[] } | Promise<{ path: string[] }> },
+) {
+  const { path } = await params;
+  const signalPath = path.join("/");
+
+  if (!allowedSignals.has(signalPath)) {
+    return new Response("unknown OTLP signal", { status: 404 });
+  }
+
+  const upstream = `${process.env.GRAFANA_OTLP_ENDPOINT}/${signalPath}`;
+  const body = await request.text();
+
+  const response = await fetch(upstream, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...(process.env.GRAFANA_OTLP_AUTHORIZATION
+        ? { Authorization: process.env.GRAFANA_OTLP_AUTHORIZATION }
+        : {}),
+    },
+    body,
+  });
+
+  return new Response(await response.text(), { status: response.status });
+}
+```
+
+For Client Components, reuse the React provider recipe and set
+`otlpEndpoint: "/api/otel"`.
+

package/docs/frameworks/react.md

@@ -0,0 +1,139 @@
+# React integration
+
+React apps should create Brass once, expose it through context, and send
+browser telemetry to a same-origin backend/proxy. Do not put Grafana Cloud or
+collector credentials in client bundles.
+
+## Provider
+
+```tsx
+// BrassProvider.tsx
+import React, { createContext, useContext, useEffect, useMemo } from "react";
+import { Runtime } from "brass-runtime/core";
+import {
+  defineHttpPolicyPresets,
+  makeDefaultHttpClient,
+} from "brass-runtime/http";
+import {
+  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,
+  },
+});
+
+function makeReactBrass() {
+  const observability = makeObservability({
+    serviceName: "shop-react",
+    resource: { "deployment.environment": "browser" },
+    logs: false,
+    sampling: { ratio: 0.1, respectRemoteSampled: true, forceSampleOnError: true },
+    redaction: {},
+    cardinality: { maxValuesPerLabel: 100 },
+    otlp: makeOtlpOptions({
+      endpoint: "/api/otel",
+      timeoutMs: 10_000,
+      retry: { attempts: 2, initialDelayMs: 100, maxDelayMs: 1_000 },
+      pipeline: { maxQueueSize: 2_000, batchSize: 128, dropPolicy: "drop-oldest" },
+    }),
+    flushIntervalMs: 15_000,
+    autoStart: true,
+  });
+
+  const runtime = new Runtime({
+    env: observability.env,
+    hooks: observability.hooks,
+  });
+
+  const http = makeDefaultHttpClient({
+    baseUrl: "/api",
+    preset: "balanced",
+    timeoutMs: 5_000,
+    policyPresets,
+    middleware: [withHttpObservability(observability)],
+  });
+
+  return {
+    observability,
+    runtime,
+    http,
+    shutdown: async () => {
+      await http.shutdown();
+      await observability.shutdown();
+    },
+  };
+}
+
+type ReactBrass = ReturnType<typeof makeReactBrass>;
+
+const BrassContext = createContext<ReactBrass | undefined>(undefined);
+
+export function BrassProvider({ children }: { children: React.ReactNode }) {
+  const brass = useMemo(() => makeReactBrass(), []);
+
+  useEffect(() => {
+    return () => {
+      void brass.shutdown();
+    };
+  }, [brass]);
+
+  return <BrassContext.Provider value={brass}>{children}</BrassContext.Provider>;
+}
+
+export function useBrass() {
+  const brass = useContext(BrassContext);
+  if (!brass) throw new Error("BrassProvider is missing");
+  return brass;
+}
+```
+
+## Component Usage
+
+```tsx
+// Profile.tsx
+import { useEffect, useState } from "react";
+import { useBrass } from "./BrassProvider";
+
+type User = {
+  readonly id: string;
+  readonly name: string;
+};
+
+export function Profile() {
+  const { runtime, http } = useBrass();
+  const [user, setUser] = useState<User | undefined>();
+
+  useEffect(() => {
+    let alive = true;
+
+    void runtime
+      .toPromise(http.getJson<User>("/users/me", { policy: "readModel" }))
+      .then((response) => {
+        if (alive) setUser(response.body);
+      });
+
+    return () => {
+      alive = false;
+    };
+  }, [runtime, http]);
+
+  return <span>{user?.name ?? "Loading..."}</span>;
+}
+```
+
+## Collector Proxy
+
+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.
+