service-bridge 1.0.7 → 1.0.8-dev.19

package/README.md

@@ -95,7 +95,7 @@ bun add service-bridge
 import { servicebridge } from "service-bridge";
 
 const sb = servicebridge(
-  process.env.SERVICEBRIDGE_URL ?? "0.0.0.0:14445",
+  process.env.SERVICEBRIDGE_URL ?? "localhost:14445",
   process.env.SERVICEBRIDGE_SERVICE_KEY!,
   "payments",
 );
@@ -104,7 +104,7 @@ sb.handleRpc("charge", async (payload: { orderId: string; amount: number }) => {
   return { ok: true, txId: `tx_${Date.now()}`, orderId: payload.orderId };
 });
 
-await sb.serve({ host: "0.0.0.0" });
+await sb.serve({ host: "localhost" });
 ```
 
 ### 3. Call it from another service
@@ -113,7 +113,7 @@ await sb.serve({ host: "0.0.0.0" });
 import { servicebridge } from "service-bridge";
 
 const sb = servicebridge(
-  process.env.SERVICEBRIDGE_URL ?? "0.0.0.0:14445",
+  process.env.SERVICEBRIDGE_URL ?? "localhost:14445",
   process.env.SERVICEBRIDGE_SERVICE_KEY!,
   "orders",
 );
@@ -138,7 +138,7 @@ The SDK connects to a ServiceBridge runtime. The fastest way to start:
 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 `0.0.0.0:14445`.
+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 `localhost: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.
 
@@ -153,7 +153,7 @@ import { servicebridge } from "service-bridge";
 
 // --- Payments service (worker) ---
 
-const payments = servicebridge("0.0.0.0:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!, "payments");
+const payments = servicebridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!, "payments");
 
 payments.handleRpc("charge", async (payload: { orderId: string; amount: number }, ctx) => {
   await ctx?.stream.write({ status: "charging", orderId: payload.orderId }, "progress");
@@ -164,13 +164,13 @@ payments.handleRpc("charge", async (payload: { orderId: string; amount: number }
   return { ok: true, txId: `tx_${Date.now()}` };
 });
 
-await payments.serve({ host: "0.0.0.0" });
+await payments.serve({ host: "localhost" });
 ```
 
 ```ts
 // --- Orders service (caller + event publisher) ---
 
-const orders = servicebridge("0.0.0.0:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!, "orders");
+const orders = servicebridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!, "orders");
 
 // Call payments, then publish event
 const charge = await orders.rpc<{ ok: boolean; txId: string }>("payments/charge", {
@@ -190,7 +190,7 @@ await orders.event("orders.completed", {
 ```ts
 // --- Notifications service (event consumer) ---
 
-const notifications = servicebridge("0.0.0.0:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!, "notifications");
+const notifications = servicebridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!, "notifications");
 
 notifications.handleEvent("orders.*", async (payload, ctx) => {
   const body = payload as { orderId: string; txId: string };
@@ -198,7 +198,7 @@ notifications.handleEvent("orders.*", async (payload, ctx) => {
   // ... send email ...
 });
 
-await notifications.serve({ host: "0.0.0.0" });
+await notifications.serve({ host: "localhost" });
 ```
 
 ```ts
@@ -230,7 +230,7 @@ Every step above — RPC, event publish, event delivery, workflow execution —
 - **Jobs** — cron, delayed, and workflow-triggered scheduling
 
 ### Security
-- **Auto mTLS** — automatic certificate provisioning for workers
+- **TLS by default** — control plane TLS + worker mTLS with gRPC certificate provisioning
 - **Access Policy** — service-level caller/target restrictions and RBAC
 
 ### Observability
@@ -267,11 +267,11 @@ ServiceBridge keeps the core API shape consistent across Node.js, Go, and Python
 constructor, RPC, events, jobs, workflows, `runWorkflow`, streams, serve/stop, and `ServiceBridgeError`.
 
 Constructor-level defaults for `timeout`, `retries`, and `retryDelay` are available
-across all three SDKs. The following are intentionally language-specific today:
+across all three SDKs. Parity differences are naming-only (language idioms):
 
-- Node-only constructor options: `workerTransport`, `workerTLS`
-- Node-only handler hints: `handleRpc.timeout`, `handleRpc.retryable`, `handleRpc.concurrency`, `handleEvent.concurrency`, `handleEvent.prefetch`
-- Node-only `serve()` fields: `instanceId`, `weight`, `transport`, `tls`
+- Constructor TLS overrides: `workerTLS`/`caCert` (Node), `WorkerTLS`/`CACert` (Go), `worker_tls`/`ca_cert` (Python)
+- Handler hints: timeout/retryable/concurrency/prefetch are advisory in all SDKs
+- Shared `serve()` fields across SDKs: host, max in-flight, instance ID, weight, and per-serve TLS override
 
 ### `servicebridge(url, serviceKey, serviceName?, opts?)`
 
@@ -290,21 +290,22 @@ Creates an SDK client instance.
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `timeout` | `number` | `30000` | Default timeout (ms) for SDK operations. |
+| `timeout` | `number` | `30000` | Default hard timeout per RPC attempt (ms). |
 | `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). |
-| `adminSessionCookie` | `string` | `undefined` | Admin session cookie for browser-authenticated endpoints (e.g. `cancelWorkflowRun`). |
-| `adminCsrfToken` | `string` | `undefined` | CSRF token paired with `adminSessionCookie` for unsafe HTTP methods. |
-| `adminOrigin` | `string` | `undefined` | Origin header required by admin CSRF/origin checks. |
 | `captureLogs` | `boolean` | `true` | Forward `console.*` logs to ServiceBridge. |
 
+### Advanced TLS overrides
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `workerTLS` | `WorkerTLSOpts` | auto | Explicit cert/key/CA for worker mTLS. |
+| `caCert` | `string \| Buffer` | from `serviceKey` | Optional control-plane CA override. By default SDK reads CA from sbv2 service key. |
+
 `WorkerTLSOpts`:
 
 ```ts
@@ -343,6 +344,10 @@ const user = await sb.rpc<{ id: string; name: string }>("users/get", { id: "u_1"
 });
 ```
 
+`rpc()` is bounded even when a downstream worker is silent:
+each attempt has a hard local timeout, retries are finite (`retries + 1` total attempts),
+and after the final failed attempt the root RPC span is closed with `error`.
+
 ---
 
 ### `event(topic, payload?, opts?)`
@@ -503,9 +508,9 @@ Registers an RPC handler. Chainable.
 
 | Option | Type | Description |
 |---|---|---|
-| `timeout` | `number` | Node-only timeout hint (currently not hard-enforced by runtime). |
-| `retryable` | `boolean` | Node-only retry hint (currently metadata-level, not a strict policy switch). |
-| `concurrency` | `number` | Node-only concurrency hint (currently not hard-enforced). |
+| `timeout` | `number` | Advisory timeout hint (currently metadata-level, not hard-enforced by runtime). |
+| `retryable` | `boolean` | Advisory retry hint (currently metadata-level, not a strict policy switch). |
+| `concurrency` | `number` | Advisory concurrency hint (currently not hard-enforced). |
 | `schema` | `RpcSchemaOpts` | Inline protobuf schema for binary encode/decode. |
 | `allowedCallers` | `string[]` | Allow-list of caller service names. |
 
@@ -536,8 +541,8 @@ Registers an event consumer handler. Chainable.
 | Option | Type | Description |
 |---|---|---|
 | `groupName` | `string` | Consumer group name. Default: `<service>.<pattern>`. |
-| `concurrency` | `number` | Node-only concurrency hint (currently not hard-enforced). |
-| `prefetch` | `number` | Node-only prefetch hint (currently not hard-enforced). |
+| `concurrency` | `number` | Advisory concurrency hint (currently not hard-enforced). |
+| `prefetch` | `number` | Advisory prefetch hint (currently not hard-enforced). |
 | `retryPolicyJson` | `string` | Retry policy JSON string. |
 | `filterExpr` | `string` | Server-side filter expression. |
 
@@ -577,15 +582,15 @@ the Node.js process).
 
 | Option | Type | Description |
 |---|---|---|
-| `host` | `string` | Bind host. Default: `0.0.0.0`. |
-| `instanceId` | `string` | Stable worker instance identifier (Node-only). |
-| `weight` | `number` | Scheduling/discovery weight hint (Node-only). |
-| `transport` | `"tls"` | Worker transport (Node-only in `serve()`). |
-| `tls` | `WorkerTLSOpts` | Per-serve TLS override (Node-only in `serve()`). |
+| `host` | `string` | Bind host. Default: `localhost`. Use `0.0.0.0` in Docker/Kubernetes so ServiceBridge can reach the worker. |
+| `maxInFlight` | `number` | Max in-flight runtime-originated commands over `OpenWorkerSession`. Default: `128`. |
+| `instanceId` | `string` | Stable worker instance identifier. |
+| `weight` | `number` | Scheduling/discovery weight hint. |
+| `tls` | `WorkerTLSOpts` | Per-serve worker TLS override. |
 
 ```ts
 await sb.serve({
-  host: "0.0.0.0",
+  host: "localhost",
   instanceId: process.env.HOSTNAME,
 });
 ```
@@ -693,6 +698,13 @@ identifier used by `ctx.stream.write(...)` (typically a trace ID).
 | `data` | `unknown` | JSON-decoded chunk payload. |
 | `runStatus` | `string \| undefined` | Final status on `run_complete`. |
 
+Behavior:
+
+- Auto-reconnect with exponential backoff (`500ms` → `5000ms`) on retryable stream failures.
+- Deduplicates by `sequence` across reconnects.
+- Enforces strict JSON for `type="chunk"` payloads (non-JSON chunk terminates stream with fatal error).
+- Enforces internal queue limit `256`; overflow is fatal (consumer must drain promptly).
+
 ```ts
 for await (const evt of sb.watchRun(runId, { key: "output", fromSequence: 0 })) {
   if (evt.type === "chunk") {
@@ -859,7 +871,9 @@ Runs a Fastify handler inside the current trace context so downstream SDK calls
 ### TLS behavior
 
 - Worker transport is TLS-only.
-- If `workerTLS` is not provided, SDK auto-provisions certs through the admin API.
+- Control plane is TLS-only. Trust source is embedded into sbv2 service key by default.
+- Embedded/explicit CA PEM is validated with strict x509 parsing.
+- If `workerTLS` is not provided, SDK auto-provisions worker certs via gRPC `ProvisionWorkerCertificate`.
 - `workerTLS.cert` and `workerTLS.key` must be provided together.
 - `serve({ tls })` overrides global `workerTLS` for a specific worker instance.
 
@@ -879,19 +893,15 @@ The SDK requires values you pass into `servicebridge(...)`. Common setup:
 
 | Variable | Required | Example | Description |
 |---|---|---|---|
-| `SERVICEBRIDGE_URL` | yes | `0.0.0.0:14445` | gRPC control plane URL |
-| `SERVICEBRIDGE_SERVICE_KEY` | yes | `sb_live_...` | Service authentication key |
+| `SERVICEBRIDGE_URL` | yes | `localhost:14445` | gRPC control plane URL |
+| `SERVICEBRIDGE_SERVICE_KEY` | yes | `sbv2.<id>.<secret>.<ca>` | Service authentication key (sbv2 only) |
 | `SERVICEBRIDGE_SERVICE` | yes (worker mode) | `orders` | Service name in registry |
-| `SERVICEBRIDGE_ADMIN_URL` | optional | `http://0.0.0.0:14444` | Explicit admin API base URL |
 
 ```ts
 const sb = servicebridge(
-  process.env.SERVICEBRIDGE_URL ?? "0.0.0.0:14445",
+  process.env.SERVICEBRIDGE_URL ?? "localhost:14445",
   process.env.SERVICEBRIDGE_SERVICE_KEY!,
   process.env.SERVICEBRIDGE_SERVICE ?? "orders",
-  {
-    adminUrl: process.env.SERVICEBRIDGE_ADMIN_URL,
-  },
 );
 ```
 
@@ -949,7 +959,7 @@ try {
 ## 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.
+RPC calls have configurable retries with exponential backoff and hard per-attempt timeouts, so a silent downstream service cannot keep a call pending forever. 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.