brass-runtime 1.16.1 → 1.18.0

package/docs/frameworks/nextjs.md

@@ -0,0 +1,202 @@
+# 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"`.
+
+## Layer Variant
+
+For Route Handlers, keep a server-only layer singleton and close it from your
+process lifecycle when the platform exposes one:
+
+```ts
+// app/lib/brass.server.ts
+import "server-only";
+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-next",
+    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 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/nextjs](https://github.com/BaldrVivaldelli/brass-runtime/tree/main/examples/nextjs).

package/docs/frameworks/react.md

@@ -0,0 +1,183 @@
+# 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.
+
+## Layer Variant
+
+The provider can build a layer graph instead of manually constructing each
+service. In browser apps, use a same-origin OTLP proxy and close the layer from
+the React cleanup:
+
+```tsx
+import { Layer, Runtime, RuntimeService, makeConfigLayer } from "brass-runtime/core";
+import { s } from "brass-runtime/schema";
+import { HttpClientService } from "brass-runtime/http";
+import {
+  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.string(),
+    otlpEndpoint: s.string(),
+  }), { serviceName: "shop-react", apiBaseUrl: "/api", otlpEndpoint: "/api/otel" }),
+  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: "balanced" })),
+);
+
+const built = await Runtime.make({}).toPromise(Layer.build(AppLayer));
+const brass = {
+  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/react](https://github.com/BaldrVivaldelli/brass-runtime/tree/main/examples/react).

package/docs/frameworks/vanilla.md

@@ -0,0 +1,280 @@
+# Vanilla integration
+
+Use this when an app does not have a framework-level DI or lifecycle system.
+The same shape works for plain browser TypeScript, Node HTTP handlers, CLIs,
+and small services.
+
+## Browser
+
+Browser apps should send telemetry to a same-origin proxy. Do not ship Grafana
+Cloud or collector credentials to the client.
+
+```ts
+// brass.browser.ts
+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,
+  },
+});
+
+export const brass = (() => {
+  const observability = makeObservability({
+    serviceName: "shop-web",
+    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();
+    },
+  };
+})();
+```
+
+Use it from ordinary browser code:
+
+```ts
+type User = {
+  readonly id: string;
+  readonly name: string;
+};
+
+export async function loadCurrentUser(): Promise<User> {
+  const response = await brass.runtime.toPromise(
+    brass.http.getJson<User>("/users/me", {
+      policy: "readModel",
+      timeoutMs: 2_000,
+    }),
+  );
+
+  return response.body;
+}
+
+window.addEventListener("pagehide", () => {
+  void brass.shutdown();
+});
+```
+
+## Node
+
+On the server, Brass can send directly to a collector because credentials stay
+inside the trusted process.
+
+```ts
+// brass.node.ts
+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,
+  },
+});
+
+export const brass = (() => {
+  const observability = makeObservability({
+    serviceName: process.env.OTEL_SERVICE_NAME ?? "vanilla-node",
+    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 runtime = new Runtime({
+    env: observability.env,
+    hooks: observability.hooks,
+  });
+
+  const http = makeDefaultHttpClient({
+    baseUrl: process.env.API_BASE_URL ?? "https://api.internal",
+    preset: "production",
+    timeoutMs: 5_000,
+    policyPresets,
+    middleware: [withHttpObservability(observability)],
+  });
+
+  return {
+    observability,
+    runtime,
+    http,
+    shutdown: async () => {
+      await http.shutdown();
+      await observability.shutdown();
+    },
+  };
+})();
+```
+
+Use the Node request adapter when you receive `IncomingMessage`-like requests:
+
+```ts
+import { createServer } from "node:http";
+import {
+  makeNodeRequestObservabilityContext,
+} from "brass-runtime/observability";
+import { brass } from "./brass.node";
+
+const server = createServer(async (req, res) => {
+  const ctx = makeNodeRequestObservabilityContext(brass.observability, req, {
+    route: req.url?.startsWith("/users/") ? "/users/:id" : req.url,
+  });
+
+  const response = await ctx.run(
+    ctx.withRequestSpan(
+      brass.http.getJson("/users/42", {
+        policy: "readModel",
+        timeoutMs: 2_000,
+      }),
+    ),
+  );
+
+  res.setHeader("content-type", "application/json");
+  res.end(JSON.stringify(response.body));
+});
+
+process.once("SIGTERM", async () => {
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  await brass.shutdown();
+});
+
+server.listen(process.env.PORT ?? 3000);
+```
+
+## Layer Variant
+
+For scripts, CLIs, workers, or small Node servers, a layer graph keeps startup
+and teardown explicit without a framework:
+
+```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: "worker",
+    apiBaseUrl: "https://users-api.internal",
+    otlpEndpoint: "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));
+const runtime = built.service.unsafeGet(RuntimeService);
+const http = built.service.unsafeGet(HttpClientService);
+const observability = built.service.unsafeGet(ObservabilityService);
+
+try {
+  await runtime.toPromise(http.getJson("/users/42"));
+  console.log(observability.prometheus.export());
+} finally {
+  await Runtime.make({}).toPromise(built.close());
+}
+```
+
+## Runnable Example
+
+A minimal runnable app lives at
+[examples/vanilla](https://github.com/BaldrVivaldelli/brass-runtime/tree/main/examples/vanilla).