service-bridge 1.1.1-dev.31 → 1.6.0-dev.33

package/README.md

@@ -2,7 +2,7 @@
 
 # service-bridge
 
-[![npm version](https://img.shields.io/npm/v/%40service-bridge%2Fnode?color=cb3837&logo=npm)](https://www.npmjs.com/package/service-bridge)
+[![npm version](https://img.shields.io/npm/v/service-bridge?color=cb3837&logo=npm)](https://www.npmjs.com/package/service-bridge)
 [![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/)
@@ -218,7 +218,7 @@ Every step above — RPC, event publish, event delivery, workflow execution —
 
 ### 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
+- **Durable Events** — fan-out delivery, guaranteed delivery (RabbitMQ-style), at-least-once guarantees, retries, DLQ, replay, idempotency. If a consumer is offline, the message waits in the server-side queue and is dispatched the moment the consumer reconnects — no retry budget consumed while waiting.
 - **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
@@ -335,6 +335,7 @@ Calls a registered RPC handler on another service. Direct gRPC path, no proxy.
 | `retryDelay` | `number` | Base retry delay override. |
 | `traceId` | `string` | Explicit trace id. |
 | `parentSpanId` | `string` | Explicit parent span id. |
+| `mode` | `"direct" \| "proxy"` | Transport mode. `"direct"` (default) connects directly to the worker. `"proxy"` routes through the control plane when direct connection is unavailable. |
 
 ```ts
 const user = await sb.rpc<{ id: string; name: string }>("users/get", { id: "u_1" }, {
@@ -347,6 +348,8 @@ const user = await sb.rpc<{ id: string; name: string }>("users/get", { id: "u_1"
 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`.
 
+Retry delay uses exponential backoff: `retryDelay * 2^(attempt-1)`.
+
 ---
 
 ### `event(topic, payload?, opts?)`
@@ -407,10 +410,10 @@ await sb.job("billing/collect", {
 ### `workflow(name, steps, opts?)`
 
 ```ts
-workflow(name: string, steps: WorkflowStep[], opts?: WorkflowOpts): Promise<void>
+workflow(name: string, steps: WorkflowStep[], opts?: WorkflowOpts): Promise<string>
 ```
 
-Registers (or updates) a workflow definition as a DAG of typed steps.
+Registers (or updates) a workflow definition as a DAG of typed steps. Returns the workflow name.
 
 `WorkflowStep`:
 
@@ -471,6 +474,12 @@ An alternative to scheduling via `job(target, { via: "workflow" })` — triggers
 
 Returns `{ runId, traceId }`. Use `traceId` with `watchRun()` to observe execution in real time.
 
+`RunWorkflowOpts`:
+
+| Option | Type | Description |
+|---|---|---|
+| `traceId` | `string` | Override trace ID for this workflow run. |
+
 ```ts
 const { runId, traceId } = await sb.runWorkflow("user.onboarding", { userId: "u_123" });
 ```
@@ -503,6 +512,14 @@ handleRpc(
 
 Registers an RPC handler. Chainable.
 
+`RpcContext`:
+
+| Field | Type | Description |
+|---|---|---|
+| `traceId` | `string` | Current trace ID. |
+| `spanId` | `string` | Current span ID. |
+| `stream` | `StreamWriter` | Real-time stream writer. |
+
 `HandleRpcOpts`:
 
 | Option | Type | Description |
@@ -521,6 +538,13 @@ sb.handleRpc("ai/generate", async (payload: { prompt: string }, ctx) => {
 });
 ```
 
+`StreamWriter`:
+
+| Method | Signature | Description |
+|---|---|---|
+| `write` | `write(data: unknown, key?: string): Promise<void>` | Append a real-time chunk to the run stream. |
+| `end` | `end(key?: string): Promise<void>` | No-op placeholder for API symmetry (lifecycle managed by runtime). |
+
 ---
 
 ### `handleEvent(pattern, handler, opts?)`
@@ -547,10 +571,18 @@ Registers an event consumer handler. Chainable.
 
 Duplicate `groupName` registration throws an error.
 
+**Delivery guarantee**: once a message is accepted by the runtime, delivery to each consumer group
+is guaranteed. If the consumer is offline, the message waits in the server-side queue and is
+dispatched automatically the moment the service reconnects and registers its handlers — no retry
+budget is consumed while waiting. After `SERVICEBRIDGE_DELIVERY_TTL_DAYS` (default 7) days without
+a consumer, the delivery moves to DLQ with reason `delivery_ttl_exceeded`.
+
 `EventContext` helpers:
 
+- `ctx.traceId` — current trace ID
+- `ctx.spanId` — current span ID
 - `ctx.retry(delayMs?)` — ask for redelivery with optional delay
-- `ctx.reject(reason)` — reject without retry
+- `ctx.reject(reason)` — move to DLQ immediately, bypassing remaining retries
 - `ctx.refs` — metadata (`topic`, `groupName`, `messageId`, `attempt`, `headers`)
 - `ctx.stream.write(...)` — append real-time chunks to run stream
 
@@ -575,7 +607,7 @@ serve(opts?: ServeOpts): Promise<void>
 
 Starts the worker gRPC server and registers handlers with the control plane.
 The promise resolves once startup/registration is complete (it does not block
-the Node.js process).
+the Node.js process). Throws immediately if no handlers are registered (neither `handleRpc()` nor `handleEvent()` have been called).
 
 `ServeOpts`:
 
@@ -865,6 +897,22 @@ Runs a Fastify handler inside the current trace context so downstream SDK calls
 
 ---
 
+### Trace Utilities (HTTP Plugins)
+
+#### `extractTraceFromHeaders(headers)`
+
+```ts
+import { extractTraceFromHeaders } from "service-bridge/express";
+// or
+import { extractTraceFromHeaders } from "service-bridge/fastify";
+
+const { traceId, parentSpanId } = extractTraceFromHeaders(req.headers);
+```
+
+Extracts trace context from HTTP headers. Supports W3C `traceparent`, `x-trace-id`/`x-span-id` headers, and generates random IDs as fallback. Useful for custom HTTP framework integrations (Hono, Koa, etc.).
+
+---
+
 ## Configuration
 
 ### TLS behavior
@@ -1142,6 +1190,36 @@ const mode = session.resolveTransportMode('payment-svc/charge'); // 'proxy'
 | `TransportMode` | type | `'direct' \| 'proxy'` |
 | `HelloAckV2` | interface | Данные HelloAck от сервера |
 | `TransportConfigV2` | interface | ConfigPush payload |
+| `ReconcileRequestV2` | interface | Declarative worker registration request |
+| `FunctionDeclarationV2` | interface | Function declaration for Reconcile |
+| `ConsumerGroupDeclarationV2` | interface | Consumer group declaration |
+| `HttpRouteDeclarationV2` | interface | HTTP route declaration |
+| `JobDeclarationV2` | interface | Job declaration |
+| `WorkflowDeclarationV2` | interface | Workflow declaration |
+| `SubscribeRequestV2` | interface | Registry subscribe request |
+| `WorkerEndpointV2` | interface | Worker endpoint info |
+| `IssueCertificateRequestV2` | interface | Certificate request |
+| `IssueCertificateResponseV2` | interface | Certificate response |
+| `CircuitBreakerConfigV2` | interface | Circuit breaker config |
+| `ZoneConfigV2` | interface | Zone-aware config |
+| `ServiceTransportOverride` | interface | Per-service transport override |
+| `FunctionTransportOverride` | interface | Per-function transport override |
+| `ResumeState` | interface | Reconnect resume state |
+
+Key types available for import:
+
+```ts
+import type {
+  WorkflowStep,
+  WorkerTLSOpts,
+  RpcContext,
+  EventContext,
+  StreamWriter,
+  TraceCtx,
+  RetryPolicy,
+  ServiceBridgeErrorSeverity,
+} from "service-bridge";
+```
 
 ---