brass-runtime 1.16.0 → 1.17.0

package/docs/framework-integrations.md

@@ -0,0 +1,38 @@
+# Framework integrations
+
+These recipes show how to wire Brass into common TypeScript application
+frameworks without adding framework-specific dependencies to `brass-runtime`.
+
+The common shape is:
+
+- create one `Observability` instance near the application boundary;
+- create one `Runtime` when framework handlers need to run effects;
+- create one `makeDefaultHttpClient(...)` with `withHttpObservability(...)`;
+- keep collector/vendor config in the application;
+- shut down HTTP and observability queues from the host lifecycle when possible.
+
+For browser apps, never expose Grafana Cloud tokens or collector secrets. Send
+browser telemetry to a same-origin proxy such as `/api/otel`, then forward to
+Grafana, Alloy, AppDynamics, or OpenTelemetry Collector from a trusted server.
+
+## Recipes
+
+| Framework | Recipe | Covers |
+|-----------|--------|--------|
+| Vanilla | [`docs/frameworks/vanilla.md`](./frameworks/vanilla.md) | Browser and Node setup without a framework |
+| React | [`docs/frameworks/react.md`](./frameworks/react.md) | Context provider, hook, component usage |
+| Next.js | [`docs/frameworks/nextjs.md`](./frameworks/nextjs.md) | App Router, server singleton, OTLP proxy |
+| Angular | [`docs/frameworks/angular.md`](./frameworks/angular.md) | InjectionToken providers and services |
+| Express | [`docs/frameworks/express.md`](./frameworks/express.md) | Request spans, `/metrics`, shutdown |
+| Fastify | [`docs/frameworks/fastify.md`](./frameworks/fastify.md) | Request adapter, `/metrics`, shutdown |
+| NestJS | [`docs/frameworks/nestjs.md`](./frameworks/nestjs.md) | Module providers, DI tokens, shutdown hooks |
+
+Runnable dependency-optional examples live in:
+
+- `src/examples/observabilityExpress.ts`
+- `src/examples/observabilityFastify.ts`
+- `src/examples/observabilityNest.ts`
+
+See also [`docs/observability-framework-examples.md`](./observability-framework-examples.md)
+for commands that run those examples locally.
+

package/docs/frameworks/angular.md

@@ -0,0 +1,153 @@
+# Angular integration
+
+Angular apps should expose Brass through `InjectionToken`s. Browser telemetry
+should go to a same-origin proxy such as `/api/otel`; collector credentials
+belong on the server side.
+
+## Providers
+
+```ts
+// brass.providers.ts
+import { inject, InjectionToken, type Provider } from "@angular/core";
+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 makeAngularBrass() {
+  const observability = makeObservability({
+    serviceName: "shop-angular",
+    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();
+    },
+  };
+}
+
+export const BRASS = new InjectionToken<ReturnType<typeof makeAngularBrass>>("BRASS");
+
+export function provideBrass(): Provider[] {
+  return [
+    {
+      provide: BRASS,
+      useFactory: () => makeAngularBrass(),
+    },
+  ];
+}
+
+export function injectBrass() {
+  return inject(BRASS);
+}
+```
+
+Register the provider:
+
+```ts
+// app.config.ts
+import { type ApplicationConfig } from "@angular/core";
+import { provideBrass } from "./brass.providers";
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    ...provideBrass(),
+  ],
+};
+```
+
+## Service Usage
+
+```ts
+// users.service.ts
+import { Injectable } from "@angular/core";
+import { injectBrass } from "./brass.providers";
+
+type User = {
+  readonly id: string;
+  readonly name: string;
+};
+
+@Injectable({ providedIn: "root" })
+export class UsersService {
+  private readonly brass = injectBrass();
+
+  getUser(id: string): Promise<User> {
+    return this.brass.runtime
+      .toPromise(
+        this.brass.http.getJson<User>(`/users/${id}`, {
+          policy: "readModel",
+          timeoutMs: 2_000,
+        }),
+      )
+      .then((response) => response.body);
+  }
+}
+```
+
+## Shutdown
+
+Browser apps often do not have a reliable shutdown hook, but you can flush on
+page lifecycle events:
+
+```ts
+import { injectBrass } from "./brass.providers";
+
+export function installBrassBrowserShutdown() {
+  const brass = injectBrass();
+
+  window.addEventListener("pagehide", () => {
+    void brass.shutdown();
+  });
+}
+```
+

package/docs/frameworks/express.md

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

package/docs/frameworks/fastify.md

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