@service-bridge/node 0.1.3

package/README.md

@@ -0,0 +1,854 @@
+# @service-bridge/node
+
+[![npm version](https://img.shields.io/npm/v/%40service-bridge%2Fnode?color=cb3837&logo=npm)](https://www.npmjs.com/package/@service-bridge/node)
+[![License](https://img.shields.io/badge/License-Free%20%2F%20Commercial-blue)](../LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5%2B-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Node](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+
+**The Unified Bridge for Microservices Interaction**
+
+Node.js SDK for [ServiceBridge](https://servicebridge.dev) — production-ready RPC, durable events, workflows, jobs, and distributed tracing in a single SDK. One Go runtime and PostgreSQL.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    BEFORE: 10 moving parts                      │
+│  Istio · Envoy · RabbitMQ · Temporal · Jaeger · Consul ·       │
+│  cert-manager · Alertmanager · cron · custom glue              │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│               AFTER: ServiceBridge + PostgreSQL                 │
+│  RPC · Events · Workflows · Jobs · Tracing · mTLS · Dashboard  │
+│            One SDK  ·  One runtime  ·  Zero sidecars            │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Table of Contents
+
+- [Why ServiceBridge](#why-servicebridge)
+- [Use Cases](#use-cases)
+- [Quick Start](#quick-start)
+- [Install](#install)
+- [Runtime Setup](#runtime-setup)
+- [End-to-End Example](#end-to-end-example)
+- [Platform Features](#platform-features)
+- [How It Compares](#how-it-compares)
+- [API Reference](#api-reference)
+- [HTTP Plugins](#http-plugins)
+- [Configuration](#configuration)
+- [Environment Variables](#environment-variables)
+- [Error Handling](#error-handling)
+- [When to Use / When Not to Use](#when-to-use--when-not-to-use)
+- [FAQ](#faq)
+- [Community and Support](#community-and-support)
+- [License](#license)
+
+---
+
+## Why ServiceBridge
+
+| Problem | Without ServiceBridge | With ServiceBridge |
+|---|---|---|
+| Service-to-service calls | Istio/Envoy sidecar proxy per pod | **Direct SDK-to-worker gRPC, zero proxy hops** |
+| Async messaging | Kafka/RabbitMQ + retry logic + DLQ setup | **Built-in durable events with retry, DLQ, replay** |
+| Background jobs | Bull/BullMQ + Redis + cron daemon | **Built-in cron and delayed jobs** |
+| Workflow orchestration | Temporal/Conductor cluster + persistence | **Built-in DAG workflows** |
+| Distributed tracing | Jaeger/Tempo + OTEL collector + dashboards | **Built-in traces + realtime UI** |
+| Service discovery | Consul/etcd + DNS glue | **Built-in registry + health-aware balancing** |
+| mTLS | cert-manager + Vault PKI | **Auto-provisioned certs from service key** |
+
+**Result**: `10 tools → 1 runtime`. One Go binary + PostgreSQL replaces the entire stack.
+
+---
+
+## Use Cases
+
+**Microservice communication** — Replace sidecar mesh with direct RPC calls. Get sub-millisecond overhead instead of double proxy hop latency.
+
+**Event-driven architecture** — Publish durable events with fan-out, retries, DLQ, idempotency, and server-side filtering. No broker infrastructure to manage.
+
+**Background job scheduling** — Cron jobs, delayed execution, and job-triggered workflows in a single API. No Redis, no separate queue workers.
+
+**Saga / distributed transactions** — DAG workflows with typed steps (`rpc`, `event`, `event_wait`, `sleep`, child workflow). Compensations and rollbacks via workflow step dependencies.
+
+**AI agent orchestration** — Stream LLM tokens via realtime run streams with replay. Orchestrate multi-step AI pipelines as workflows.
+
+**Full-stack observability** — Every RPC call, event delivery, workflow step, and HTTP request traced automatically. One timeline, one dashboard. Prometheus metrics and Loki-compatible log API included.
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install @service-bridge/node
+# or
+bun add @service-bridge/node
+```
+
+### 2. Create a worker (service that handles calls)
+
+```ts
+import { servicebridge } from "@service-bridge/node";
+
+const sb = servicebridge(
+  process.env.SERVICEBRIDGE_URL ?? "127.0.0.1:14445",
+  process.env.SERVICE_KEY!,
+  "payments",
+);
+
+sb.handleRpc("charge", async (payload: { orderId: string; amount: number }) => {
+  return { ok: true, txId: `tx_${Date.now()}`, orderId: payload.orderId };
+});
+
+await sb.serve({ host: "127.0.0.1" });
+```
+
+### 3. Call it from another service
+
+```ts
+import { servicebridge } from "@service-bridge/node";
+
+const sb = servicebridge(
+  process.env.SERVICEBRIDGE_URL ?? "127.0.0.1:14445",
+  process.env.SERVICE_KEY!,
+  "orders",
+);
+
+const result = await sb.rpc<{ ok: boolean; txId: string }>("payments/charge", {
+  orderId: "ord_42",
+  amount: 4990,
+});
+
+console.log(result.txId); // tx_1711234567890
+```
+
+That's it. No broker, no sidecar, no proxy — direct gRPC call between services.
+
+---
+
+## Runtime Setup
+
+The SDK connects to a ServiceBridge runtime. The fastest way to start:
+
+```bash
+bash <(curl -fsSL https://servicebridge.dev/install.sh)
+```
+
+This installs ServiceBridge + PostgreSQL via Docker Compose and generates an admin password automatically. After install, the dashboard is at `http://localhost:14444` and the gRPC control plane at `127.0.0.1:14445`.
+
+For manual Docker Compose setup, configuration reference, and all runtime environment variables, see the **[Runtime Setup](../README.md#runtime-setup)** section in the main SDK README.
+
+---
+
+## End-to-End Example
+
+A complete order flow: HTTP request → RPC → Event → Event handler with streaming.
+
+```ts
+import { servicebridge } from "@service-bridge/node";
+
+// --- Payments service (worker) ---
+
+const payments = servicebridge("127.0.0.1:14445", process.env.SERVICE_KEY!, "payments");
+
+payments.handleRpc("charge", async (payload: { orderId: string; amount: number }, ctx) => {
+  await ctx?.stream.write({ status: "charging", orderId: payload.orderId }, "progress");
+
+  // ... charge logic ...
+
+  await ctx?.stream.write({ status: "charged" }, "progress");
+  return { ok: true, txId: `tx_${Date.now()}` };
+});
+
+await payments.serve({ host: "127.0.0.1" });
+```
+
+```ts
+// --- Orders service (caller + event publisher) ---
+
+const orders = servicebridge("127.0.0.1:14445", process.env.SERVICE_KEY!, "orders");
+
+// Call payments, then publish event
+const charge = await orders.rpc<{ ok: boolean; txId: string }>("payments/charge", {
+  orderId: "ord_42",
+  amount: 4990,
+});
+
+await orders.event("orders.completed", {
+  orderId: "ord_42",
+  txId: charge.txId,
+}, {
+  idempotencyKey: "order:ord_42:completed",
+  headers: { source: "checkout" },
+});
+```
+
+```ts
+// --- Notifications service (event consumer) ---
+
+const notifications = servicebridge("127.0.0.1:14445", process.env.SERVICE_KEY!, "notifications");
+
+notifications.handleEvent("orders.*", async (payload, ctx) => {
+  const body = payload as { orderId: string; txId: string };
+  await ctx.stream.write({ status: "sending_email", orderId: body.orderId }, "progress");
+  // ... send email ...
+});
+
+await notifications.serve({ host: "127.0.0.1" });
+```
+
+```ts
+// --- Orchestrate as a workflow ---
+
+await orders.workflow("order.fulfillment", [
+  { id: "reserve",  type: "rpc",   ref: "inventory/reserve" },
+  { id: "charge",   type: "rpc",   ref: "payments/charge",       deps: ["reserve"] },
+  { id: "wait_dlv", type: "event_wait", ref: "shipping.delivered", deps: ["charge"] },
+  { id: "notify",   type: "event", ref: "orders.fulfilled",      deps: ["wait_dlv"] },
+]);
+```
+
+Every step above — RPC, event publish, event delivery, workflow execution — appears in a single trace timeline in the built-in dashboard.
+
+---
+
+## Platform Features
+
+### Communication
+- **Direct RPC** — zero-hop gRPC calls with retries, deadlines, and mTLS identity
+- **Durable Events** — fan-out delivery, at-least-once guarantees, retries, DLQ, replay, idempotency
+- **Realtime Streams** — live chunks with replay for AI/progress/log streaming
+- **Service Discovery** — automatic endpoint resolution and round-robin balancing
+- **HTTP Middleware** — Express and Fastify instrumentation with automatic trace propagation
+
+### Orchestration
+- **Workflows** — DAG steps: `rpc`, `event`, `event_wait`, `sleep`, child workflow
+- **Jobs** — cron, delayed, and workflow-triggered scheduling
+
+### Security
+- **Auto mTLS** — automatic certificate provisioning for workers
+- **Access Policy** — service-level caller/target restrictions and RBAC
+
+### Observability
+- **Unified Tracing** — single trace timeline across HTTP, RPC, events, workflows, and jobs
+- **Metrics** — Prometheus-compatible `/metrics` endpoint (30+ metric families)
+- **Logs** — structured log ingest with Loki-compatible query API
+- **Alerts** — runtime alerts for delivery failures, errors, and service health
+- **Dashboard** — realtime web UI for runs, events, workflows, jobs, DLQ, service map, and service keys
+
+---
+
+## How It Compares
+
+| Concern | Istio + Envoy | Dapr | Temporal + Kafka | ServiceBridge |
+|---|---|---|---|---|
+| RPC data path | Sidecar proxy hop | Sidecar/daemon hop | N/A | **Direct (proxyless)** |
+| Service discovery | K8s control plane | Sidecar placement | External registry | **Built-in registry** |
+| Durable events + DLQ | External broker | Pub/Sub component | Kafka + consumers | **Built-in** |
+| Workflow orchestration | External engine | External engine | Built-in | **Built-in** |
+| Job scheduling | External cron/queue | External scheduler | External scheduler | **Built-in** |
+| Traces + UI | Jaeger/Tempo + dashboards | OTEL backend + dashboards | Temporal UI | **Built-in** |
+| Logs for Grafana | Loki + Promtail pipeline | Log pipeline | Log pipeline | **Built-in Loki API** |
+| Metrics | App/exporter setup | App/exporter setup | Multiple exporters | **Built-in `/metrics`** |
+| Security model | Mesh PKI + policy | Deployment-dependent mTLS | Mixed | **Service keys + auto mTLS** |
+| Operational footprint | Multi-component mesh | Runtime + sidecars | Workflow + broker + DB | **One binary + PostgreSQL** |
+
+---
+
+## API Reference
+
+### `servicebridge(url, serviceKey, serviceName?, opts?)`
+
+```ts
+function servicebridge(
+  url: string,
+  serviceKey: string,
+  service?: string,
+  globalOpts?: ServiceBridgeOpts,
+): ServiceBridgeService
+```
+
+Creates an SDK client instance.
+
+`ServiceBridgeOpts`:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `timeout` | `number` | `30000` | Default timeout (ms) for SDK operations. |
+| `retries` | `number` | `3` | Default retry count for `rpc()`. |
+| `retryDelay` | `number` | `300` | Base backoff delay (ms) for `rpc()`. |
+| `discoveryRefreshMs` | `number` | `10000` | Discovery refresh period for endpoint updates. |
+| `queueMaxSize` | `number` | `1000` | Max offline queue size for control-plane writes. |
+| `queueOverflow` | `"drop-oldest" \| "drop-newest" \| "error"` | `"drop-oldest"` | Overflow strategy for offline queue. |
+| `heartbeatIntervalMs` | `number` | `10000` | Base heartbeat period for worker registrations. |
+| `workerTransport` | `"tls"` | `"tls"` | Worker server transport. |
+| `workerTLS` | `WorkerTLSOpts` | auto | Explicit cert/key/CA for worker mTLS. |
+| `adminUrl` | `string` | derived from `url` | HTTP admin base URL (TLS provisioning and management API calls). |
+| `captureLogs` | `boolean` | `true` | Forward `console.*` logs to ServiceBridge. |
+
+`WorkerTLSOpts`:
+
+```ts
+type WorkerTLSOpts = {
+  caCert?: string | Buffer;
+  cert?: string | Buffer;
+  key?: string | Buffer;
+  serverName?: string;
+}
+```
+
+---
+
+### `rpc(fn, payload?, opts?)`
+
+```ts
+rpc<T = unknown>(fn: string, payload?: unknown, opts?: RpcOpts): Promise<T>
+```
+
+Calls a registered RPC handler on another service. Direct gRPC path, no proxy.
+
+`RpcOpts`:
+
+| Option | Type | Description |
+|---|---|---|
+| `timeout` | `number` | Call timeout in ms. |
+| `retries` | `number` | Retry count override. |
+| `retryDelay` | `number` | Base retry delay override. |
+| `traceId` | `string` | Explicit trace id. |
+| `parentSpanId` | `string` | Explicit parent span id. |
+
+```ts
+const user = await sb.rpc<{ id: string; name: string }>("users/get", { id: "u_1" }, {
+  timeout: 5000,
+  retries: 2,
+});
+```
+
+---
+
+### `event(topic, payload?, opts?)`
+
+```ts
+event(topic: string, payload?: unknown, opts?: EventOpts): Promise<string>
+```
+
+Publishes a durable event. Returns `messageId` when online.
+
+`EventOpts`:
+
+| Option | Type | Description |
+|---|---|---|
+| `traceId` | `string` | Explicit trace id. |
+| `parentSpanId` | `string` | Explicit parent span id. |
+| `idempotencyKey` | `string` | Idempotency key for dedup-safe publishing. |
+| `headers` | `Record<string, string>` | Custom metadata headers. |
+
+```ts
+await sb.event("orders.created", { orderId: "ord_42" }, {
+  idempotencyKey: "order:ord_42",
+  headers: { source: "checkout" },
+});
+```
+
+---
+
+### `job(target, opts)`
+
+```ts
+job(target: string, opts: ScheduleOpts): Promise<string>
+```
+
+Registers a scheduled or delayed job.
+
+`ScheduleOpts`:
+
+| Option | Type | Description |
+|---|---|---|
+| `cron` | `string` | Cron expression. |
+| `delay` | `number` | Delay in ms before execution. |
+| `timezone` | `string` | Timezone for cron execution. |
+| `misfire` | `"fire_now" \| "skip"` | Misfire policy. |
+| `via` | `"event" \| "rpc" \| "workflow"` | Target type. |
+| `retryPolicyJson` | `string` | Retry policy JSON string. |
+
+```ts
+await sb.job("billing/collect", {
+  cron: "0 * * * *",
+  timezone: "UTC",
+  via: "rpc",
+});
+```
+
+---
+
+### `workflow(name, steps)`
+
+```ts
+workflow(name: string, steps: WorkflowStep[]): Promise<string>
+```
+
+Registers a workflow definition as a DAG of typed steps.
+
+```ts
+await sb.workflow("order.fulfillment", [
+  { id: "reserve", type: "rpc", ref: "inventory/reserve" },
+  { id: "charge", type: "rpc", ref: "payments/charge", deps: ["reserve"] },
+  { id: "notify", type: "event", ref: "orders.fulfilled", deps: ["charge"] },
+]);
+```
+
+---
+
+### `cancelWorkflowRun(runId)`
+
+```ts
+cancelWorkflowRun(runId: string): Promise<void>
+```
+
+Cancels a running workflow instance.
+
+```ts
+await sb.cancelWorkflowRun("run_01HQ...XYZ");
+```
+
+---
+
+### `handleRpc(fn, handler, opts?)`
+
+```ts
+handleRpc(
+  fn: string,
+  handler: (payload: unknown, ctx?: RpcContext) => unknown | Promise<unknown>,
+  opts?: HandleRpcOpts,
+): ServiceBridgeService
+```
+
+Registers an RPC handler. Chainable.
+
+`HandleRpcOpts`:
+
+| Option | Type | Description |
+|---|---|---|
+| `timeout` | `number` | Handler timeout hint. |
+| `retryable` | `boolean` | Retryable hint for runtime policies. |
+| `concurrency` | `number` | Worker-side concurrency hint. |
+| `schema` | `RpcSchemaOpts` | Inline protobuf schema for binary encode/decode. |
+| `allowedCallers` | `string[]` | Allow-list of caller service names. |
+
+```ts
+sb.handleRpc("ai/generate", async (payload: { prompt: string }, ctx) => {
+  await ctx?.stream.write({ token: "Hello" }, "output");
+  await ctx?.stream.write({ token: " world" }, "output");
+  return { text: "Hello world" };
+});
+```
+
+---
+
+### `handleEvent(pattern, handler, opts?)`
+
+```ts
+handleEvent(
+  pattern: string,
+  handler: (payload: unknown, ctx: EventContext) => void | Promise<void>,
+  opts?: HandleEventOpts,
+): ServiceBridgeService
+```
+
+Registers an event consumer handler. Chainable.
+
+`HandleEventOpts`:
+
+| Option | Type | Description |
+|---|---|---|
+| `groupName` | `string` | Consumer group name. Default: `<service>:<pattern>`. |
+| `concurrency` | `number` | Concurrency hint for consumer processing. |
+| `prefetch` | `number` | Prefetch hint. |
+| `retryPolicyJson` | `string` | Retry policy JSON string. |
+| `filterExpr` | `string` | Server-side filter expression. |
+
+`EventContext` helpers:
+
+- `ctx.retry(delayMs?)` — ask for redelivery with optional delay
+- `ctx.reject(reason)` — reject without retry
+- `ctx.refs` — metadata (`topic`, `groupName`, `messageId`, `attempt`, `headers`)
+- `ctx.stream.write(...)` — append real-time chunks to run stream
+
+```ts
+sb.handleEvent("orders.*", async (payload, ctx) => {
+  const body = payload as { orderId?: string };
+  if (!body.orderId) {
+    ctx.reject("missing_order_id");
+    return;
+  }
+  await ctx.stream.write({ status: "processing", orderId: body.orderId }, "progress");
+});
+```
+
+---
+
+### `serve(opts?)`
+
+```ts
+serve(opts?: ServeOpts): Promise<void>
+```
+
+Starts the worker gRPC server and registers handlers with the control plane.
+
+`ServeOpts`:
+
+| Option | Type | Description |
+|---|---|---|
+| `host` | `string` | Bind host. Default: `127.0.0.1`. |
+| `instanceId` | `string` | Stable worker instance identifier. |
+| `weight` | `number` | Scheduling/discovery weight hint. |
+| `transport` | `"tls"` | Worker transport. |
+| `tls` | `WorkerTLSOpts` | Per-serve TLS override. |
+
+```ts
+await sb.serve({
+  host: "0.0.0.0",
+  instanceId: process.env.HOSTNAME,
+});
+```
+
+---
+
+### `stop()`
+
+```ts
+stop(): void
+```
+
+Stops worker server, heartbeats, channels, and SDK internals.
+
+---
+
+### `startHttpSpan(opts)`
+
+```ts
+startHttpSpan(opts: {
+  method: string;
+  path: string;
+  traceId?: string;
+  parentSpanId?: string;
+}): HttpSpan
+```
+
+Manual HTTP tracing primitive.
+
+```ts
+const span = sb.startHttpSpan({ method: "GET", path: "/health" });
+try {
+  span.end({ statusCode: 200, success: true });
+} catch (e) {
+  span.end({ success: false, error: String(e) });
+}
+```
+
+---
+
+### `registerHttpEndpoint(opts)`
+
+```ts
+registerHttpEndpoint(opts: {
+  method: string;
+  route: string;
+  instanceId?: string;
+  endpoint?: string;
+  allowedCallers?: string[];
+}): Promise<void>
+```
+
+Registers HTTP route metadata in the ServiceBridge service catalog.
+
+```ts
+await sb.registerHttpEndpoint({ method: "GET", route: "/users/:id" });
+```
+
+---
+
+### `watchRun(runId, opts?)`
+
+```ts
+watchRun(runId: string, opts?: WatchRunOpts): AsyncIterable<RunStreamEvent>
+```
+
+Subscribes to a run stream with replay and live updates.
+
+`WatchRunOpts`:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `key` | `string` | `"default"` | Stream key filter. |
+| `fromSequence` | `number` | `0` | Replay from sequence cursor. |
+
+```ts
+for await (const evt of sb.watchRun(runId, { key: "output", fromSequence: 0 })) {
+  if (evt.type === "chunk") {
+    process.stdout.write(String((evt.data as { token?: string }).token ?? ""));
+  }
+}
+```
+
+---
+
+### Trace Utilities
+
+#### `getTraceContext()`
+
+```ts
+getTraceContext(): { traceId: string; spanId: string } | undefined
+```
+
+Returns the current async-local trace context.
+
+#### `runWithTraceContext(ctx, fn)`
+
+```ts
+runWithTraceContext<T>(ctx: { traceId: string; spanId: string }, fn: () => T): T
+```
+
+Runs a function inside an explicit trace context.
+
+```ts
+runWithTraceContext({ traceId: "trace-1", spanId: "span-1" }, async () => {
+  await sb.event("audit.log", { action: "user.login" });
+});
+```
+
+---
+
+## HTTP Plugins
+
+### Express (`@service-bridge/node/express`)
+
+```bash
+npm install express
+```
+
+```ts
+import express from "express";
+import { servicebridge } from "@service-bridge/node";
+import { servicebridgeMiddleware, registerExpressRoutes } from "@service-bridge/node/express";
+
+const sb = servicebridge(process.env.SERVICEBRIDGE_URL!, process.env.SERVICE_KEY!, "api");
+const app = express();
+
+app.use(servicebridgeMiddleware({
+  client: sb,
+  excludePaths: ["/health"],
+  autoRegister: true,
+}));
+
+app.get("/users/:id", async (req, res) => {
+  const user = await req.servicebridge.rpc("users/get", { id: req.params.id });
+  res.json(user);
+});
+```
+
+#### `servicebridgeMiddleware(options)`
+
+```ts
+servicebridgeMiddleware(options: {
+  client: ServiceBridgeService;
+  excludePaths?: string[];
+  propagateTraceHeader?: boolean;
+  autoRegister?: boolean;
+}): express.RequestHandler
+```
+
+- Attaches `req.servicebridge`, `req.traceId`, `req.spanId`
+- Starts/ends HTTP span automatically
+- Optionally sets `x-trace-id` response header
+- Optionally auto-registers route pattern in catalog on first hit
+
+#### `registerExpressRoutes(app, client, opts?)`
+
+Eager route catalog registration without waiting for first request.
+
+```ts
+await registerExpressRoutes(app, sb, {
+  endpoint: "http://10.0.0.5:3000",
+  allowedCallers: ["api-gateway"],
+  excludePaths: ["/health"],
+});
+```
+
+---
+
+### Fastify (`@service-bridge/node/fastify`)
+
+```bash
+npm install fastify
+```
+
+```ts
+import Fastify from "fastify";
+import { servicebridge } from "@service-bridge/node";
+import { servicebridgePlugin, wrapHandler } from "@service-bridge/node/fastify";
+
+const sb = servicebridge(process.env.SERVICEBRIDGE_URL!, process.env.SERVICE_KEY!, "api");
+const app = Fastify();
+
+await app.register(servicebridgePlugin, {
+  client: sb,
+  excludePaths: ["/health"],
+  autoRegister: true,
+});
+
+app.get("/users/:id", wrapHandler(async (request, reply) => {
+  const user = await request.servicebridge.rpc("users/get", {
+    id: (request.params as any).id,
+  });
+  return reply.send(user);
+}));
+```
+
+#### `servicebridgePlugin(fastify, options)`
+
+```ts
+servicebridgePlugin(fastify, {
+  client,
+  excludePaths?,
+  propagateTraceHeader?,
+  autoRegister?,
+  register?: {
+    instanceId?,
+    endpoint?,
+    allowedCallers?,
+    excludePaths?,
+  },
+})
+```
+
+- Decorates `request.servicebridge`, `request.traceId`, `request.spanId`
+- Traces HTTP lifecycle via hooks
+- Auto-registers routes on `onRoute` before traffic
+
+#### `wrapHandler(handler)`
+
+Runs a Fastify handler inside the current trace context so downstream SDK calls inherit the trace.
+
+---
+
+## Configuration
+
+### TLS behavior
+
+- Worker transport is TLS-only.
+- If `workerTLS` is not provided, SDK auto-provisions certs through the admin API.
+- `workerTLS.cert` and `workerTLS.key` must be provided together.
+- `serve({ tls })` overrides global `workerTLS` for a specific worker instance.
+
+### Offline queue behavior
+
+When the control plane is unavailable, SDK queues write operations (`event`, `job`, `workflow`, telemetry writes).
+
+- Queue size: `queueMaxSize` (default: 1000)
+- Overflow policy: `queueOverflow` (default: `"drop-oldest"`)
+- Return values for queued writes may be empty strings until flushed
+
+---
+
+## Environment Variables
+
+The SDK requires values you pass into `servicebridge(...)`. Common setup:
+
+| Variable | Required | Example | Description |
+|---|---|---|---|
+| `SERVICEBRIDGE_URL` | yes | `127.0.0.1:14445` | gRPC control plane URL |
+| `SERVICE_KEY` | yes | `sb_live_...` | Service authentication key |
+| `SERVICEBRIDGE_SERVICE` | yes (worker mode) | `orders` | Service name in registry |
+| `SERVICEBRIDGE_ADMIN_URL` | optional | `http://127.0.0.1:14444` | Explicit admin API base URL |
+
+```ts
+const sb = servicebridge(
+  process.env.SERVICEBRIDGE_URL ?? "127.0.0.1:14445",
+  process.env.SERVICE_KEY!,
+  process.env.SERVICEBRIDGE_SERVICE ?? "orders",
+  {
+    adminUrl: process.env.SERVICEBRIDGE_ADMIN_URL,
+  },
+);
+```
+
+---
+
+## Error Handling
+
+`ServiceBridgeError` is exported for normalized SDK and runtime errors.
+
+```ts
+import { servicebridge, ServiceBridgeError } from "@service-bridge/node";
+
+try {
+  await sb.rpc("payments/charge", { orderId: "ord_1" });
+} catch (e) {
+  if (e instanceof ServiceBridgeError) {
+    console.error(e.component, e.operation, e.severity, e.code);
+  }
+  throw e;
+}
+```
+
+---
+
+## When to Use / When Not to Use
+
+### ServiceBridge is a good fit when you:
+
+- Have **3+ microservices** that need to communicate via RPC, events, or both
+- Want **RPC + events + workflows + jobs** without managing separate infrastructure for each
+- Need **end-to-end tracing** across all communication patterns in one timeline
+- Want to **eliminate sidecar proxies** and reduce operational overhead
+- Need **durable event delivery** with retry, DLQ, and replay without running a broker
+- Are building **AI/LLM pipelines** and need realtime streaming with replay
+
+### Consider alternatives when you:
+
+- Run a **single monolith** with no service decomposition plans
+- Need **ultra-high-throughput event streaming** (100K+ msg/s sustained) — Kafka is purpose-built for this
+- Need a **full API gateway** with rate limiting, auth plugins, and request transformation — use Kong/Envoy Gateway
+- Already have a **mature Istio/Linkerd mesh** and only need traffic management (no events/workflows/jobs)
+- Need **multi-region event replication** — ServiceBridge currently targets single-region deployments
+
+---
+
+## FAQ
+
+**How does ServiceBridge handle service failures?**
+RPC calls have configurable retries with exponential backoff. Events are durable (PostgreSQL-backed) with at-least-once delivery per consumer group. Failed deliveries are retried according to policy, then moved to DLQ. Workflows track step state and can be resumed.
+
+**Is there vendor lock-in?**
+ServiceBridge is self-hosted. The runtime is a single Go binary + PostgreSQL. SDK calls map to standard patterns (RPC, pub/sub, cron) — migrating away means replacing SDK calls with equivalent library calls.
+
+**How does tracing work without an OTEL collector?**
+The SDK automatically reports trace spans for every RPC call, event publish/delivery, workflow step, and HTTP request. The runtime stores traces in PostgreSQL and serves them via the built-in dashboard and a Loki-compatible API for Grafana integration.
+
+**Can I use ServiceBridge alongside existing infrastructure?**
+Yes. You can adopt incrementally — start with RPC between two services, add events later, then workflows. ServiceBridge doesn't require replacing your existing broker or mesh all at once.
+
+**What happens when the control plane is down?**
+In-flight direct RPC calls continue working (they go service-to-service, not through the control plane). New discovery lookups, event publishes, and telemetry writes are queued in the SDK offline queue and flushed when the control plane recovers.
+
+**What databases does the runtime support?**
+PostgreSQL 16+. The runtime uses PostgreSQL for all persistence: traces, events, workflows, jobs, service registry, and configuration.
+
+---
+
+## Community and Support
+
+- Website: [servicebridge.dev](https://servicebridge.dev)
+- GitHub: [github.com/service-bridge](https://github.com/service-bridge)
+- SDK monorepo: [README.md](../README.md)
+
+---
+
+## License
+
+Free for non-commercial use. Commercial use requires a separate license. See [LICENSE](../LICENSE).
+
+Copyright (c) 2026 Eugene Surkov.