service-bridge 1.6.0-dev.33 → 1.7.0-dev.50

package/README.md

@@ -73,7 +73,7 @@ Node.js SDK for [ServiceBridge](https://servicebridge.dev) — production-ready
 
 **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.
+**AI agent orchestration** — Stream LLM tokens via realtime trace 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.
 
@@ -116,7 +116,7 @@ const sb = servicebridge(
   process.env.SERVICEBRIDGE_SERVICE_KEY!,
 );
 
-const result = await sb.rpc<{ ok: boolean; txId: string }>("payments/charge", {
+const result = await sb.rpc<{ ok: boolean; txId: string }>("payment.charge", {
   orderId: "ord_42",
   amount: 4990,
 });
@@ -171,7 +171,7 @@ await payments.serve({ host: "localhost" });
 const orders = servicebridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!);
 
 // Call payments, then publish event
-const charge = await orders.rpc<{ ok: boolean; txId: string }>("payments/charge", {
+const charge = await orders.rpc<{ ok: boolean; txId: string }>("payment.charge", {
   orderId: "ord_42",
   amount: 4990,
 });
@@ -203,8 +203,8 @@ await notifications.serve({ host: "localhost" });
 // --- 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: "reserve",  type: "rpc",        ref: "inventory.reserve" },
+  { id: "charge",   type: "rpc",        ref: "payment.charge",      deps: ["reserve"] },
   { id: "wait_dlv", type: "event_wait", ref: "shipping.delivered",   deps: ["charge"] },
   { id: "notify",   type: "event",      ref: "orders.fulfilled",     deps: ["wait_dlv"] },
 ]);
@@ -236,7 +236,7 @@ Every step above — RPC, event publish, event delivery, workflow execution —
 - **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
+- **Dashboard** — realtime web UI for traces, events, workflows, jobs, DLQ, service map, and service keys
 
 ---
 
@@ -262,7 +262,7 @@ Every step above — RPC, event publish, event delivery, workflow execution —
 ### Cross-SDK parity notes
 
 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, RPC, events, jobs, workflows, `executeWorkflow`, streams, serve/stop, and `ServiceBridgeError`.
 
 Constructor-level defaults for `timeout`, `retries`, and `retryDelay` are available
 across all three SDKs. Parity differences are naming-only (language idioms):
@@ -324,7 +324,9 @@ type WorkerTLSOpts = {
 rpc<T = unknown>(fn: string, payload?: unknown, opts?: RpcOpts): Promise<T>
 ```
 
-Calls a registered RPC handler on another service. Direct gRPC path, no proxy.
+Calls a registered RPC handler on another worker. Direct gRPC path, no proxy.
+
+**Function name** — `fn` is a single **global function name** (the same string passed to `handleRpc` on the callee), e.g. `payment.charge` or `user.get`. It must be unique in the catalog and **must not contain `/`**.
 
 `RpcOpts`:
 
@@ -338,7 +340,9 @@ Calls a registered RPC handler on another service. Direct gRPC path, no proxy.
 | `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" }, {
+const user = await sb.rpc<{ id: string; name: string }>("user.get", { id: "u_1" });
+
+const user2 = await sb.rpc<{ id: string; name: string }>("user.get", { id: "u_1" }, {
   timeout: 5000,
   retries: 2,
 });
@@ -398,7 +402,7 @@ Registers a scheduled or delayed job.
 | `retryPolicyJson` | `string` | Retry policy JSON string. |
 
 ```ts
-await sb.job("billing/collect", {
+await sb.job("billing.collect", {
   cron: "0 * * * *",
   timezone: "UTC",
   via: "rpc",
@@ -443,8 +447,8 @@ interface WorkflowOpts {
 
 ```ts
 await sb.workflow("order.fulfillment", [
-  { id: "reserve", type: "rpc", ref: "inventory/reserve" },
-  { id: "charge", type: "rpc", ref: "payments/charge", deps: ["reserve"] },
+  { id: "reserve", type: "rpc", ref: "inventory.reserve" },
+  { id: "charge", type: "rpc", ref: "payment.charge", deps: ["reserve"] },
   { id: "wait_5m", type: "sleep", durationMs: 300_000, deps: ["charge"] },
   { id: "notify", type: "event", ref: "orders.fulfilled", deps: ["wait_5m"] },
 ]);
@@ -458,44 +462,44 @@ await sb.workflow("checkout.flow", steps, { stepTimeoutMs: 60_000 });
 
 ---
 
-### `runWorkflow(name, input?, opts?)`
+### `executeWorkflow(name, input?, opts?)`
 
 ```ts
-runWorkflow(name: string, input?: unknown, opts?: RunWorkflowOpts): Promise<{ runId: string; traceId: string }>
+executeWorkflow(name: string, input?: unknown, opts?: ExecuteWorkflowOpts): Promise<{ traceId: string; groupTraceId: string }>
 ```
 
-Starts a workflow run on demand. The workflow must be registered first via `workflow()`.
-An alternative to scheduling via `job(target, { via: "workflow" })` — triggers the run immediately.
+Starts a workflow execution on demand. The workflow must be registered first via `workflow()`.
+An alternative to scheduling via `job(target, { via: "workflow" })` — triggers the execution immediately.
 
 | Parameter | Type | Default | Description |
 |---|---|---|---|
 | `name` | `string` | required | Name of a previously registered workflow. |
 | `input` | `unknown` | `undefined` | Optional JSON-serializable input payload. |
 
-Returns `{ runId, traceId }`. Use `traceId` with `watchRun()` to observe execution in real time.
+Returns `{ traceId, groupTraceId }`. Use `traceId` with `watchTrace()` to observe execution in real time.
 
-`RunWorkflowOpts`:
+`ExecuteWorkflowOpts`:
 
 | Option | Type | Description |
 |---|---|---|
-| `traceId` | `string` | Override trace ID for this workflow run. |
+| `traceId` | `string` | Override trace ID for this workflow execution. |
 
 ```ts
-const { runId, traceId } = await sb.runWorkflow("user.onboarding", { userId: "u_123" });
+const { traceId, groupTraceId } = await sb.executeWorkflow("user.onboarding", { userId: "u_123" });
 ```
 
 ---
 
-### `cancelWorkflowRun(runId)`
+### `cancelWorkflow(traceId)`
 
 ```ts
-cancelWorkflowRun(runId: string): Promise<void>
+cancelWorkflow(traceId: string): Promise<void>
 ```
 
 Cancels a running workflow instance.
 
 ```ts
-await sb.cancelWorkflowRun("run_01HQ...XYZ");
+await sb.cancelWorkflow("trace_01HQ...XYZ");
 ```
 
 ---
@@ -531,7 +535,7 @@ Registers an RPC handler. Chainable.
 | `allowedCallers` | `string[]` | Allow-list of caller service names. |
 
 ```ts
-sb.handleRpc("ai/generate", async (payload: { prompt: string }, ctx) => {
+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" };
@@ -542,7 +546,7 @@ sb.handleRpc("ai/generate", async (payload: { prompt: string }, ctx) => {
 
 | Method | Signature | Description |
 |---|---|---|
-| `write` | `write(data: unknown, key?: string): Promise<void>` | Append a real-time chunk to the run stream. |
+| `write` | `write(data: unknown, key?: string): Promise<void>` | Append a real-time chunk to the trace stream. |
 | `end` | `end(key?: string): Promise<void>` | No-op placeholder for API symmetry (lifecycle managed by runtime). |
 
 ---
@@ -584,7 +588,7 @@ a consumer, the delivery moves to DLQ with reason `delivery_ttl_exceeded`.
 - `ctx.retry(delayMs?)` — ask for redelivery with optional delay
 - `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
+- `ctx.stream.write(...)` — append real-time chunks to trace stream
 
 ```ts
 sb.handleEvent("orders.*", async (payload, ctx) => {
@@ -702,32 +706,32 @@ await sb.registerHttpEndpoint({
 
 ---
 
-### `watchRun(runId, opts?)`
+### `watchTrace(traceId, opts?)`
 
 ```ts
-watchRun(runId: string, opts?: WatchRunOpts): AsyncIterable<RunStreamEvent>
+watchTrace(traceId: string, opts?: WatchTraceOpts): AsyncIterable<TraceStreamEvent>
 ```
 
-Subscribes to a run stream with replay and live updates. `runId` is the stream
-identifier used by `ctx.stream.write(...)` (typically a trace ID).
+Subscribes to a trace stream with replay and live updates. `traceId` is the stream
+identifier used by `ctx.stream.write(...)`.
 
-`WatchRunOpts`:
+`WatchTraceOpts`:
 
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `key` | `string` | `""` | Stream key filter (`""` = all keys). |
 | `fromSequence` | `number` | `0` | Replay from sequence cursor. |
 
-`RunStreamEvent`:
+`TraceStreamEvent`:
 
 | Field | Type | Description |
 |---|---|---|
-| `type` | `"chunk" \| "run_complete"` | Event kind. |
-| `runId` | `string` | Stream/run identifier being watched. |
+| `type` | `"chunk" \| "trace_complete"` | Event kind. |
+| `traceId` | `string` | Trace identifier being watched. |
 | `key` | `string` | Stream lane key. |
 | `sequence` | `number` | Monotonic sequence number. |
 | `data` | `unknown` | JSON-decoded chunk payload. |
-| `runStatus` | `string \| undefined` | Final status on `run_complete`. |
+| `traceStatus` | `string \| undefined` | Final status on `trace_complete`. |
 
 Behavior:
 
@@ -737,11 +741,11 @@ Behavior:
 - 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 })) {
+for await (const evt of sb.watchTrace(traceId, { key: "output", fromSequence: 0 })) {
   if (evt.type === "chunk") {
     process.stdout.write(String((evt.data as { token?: string }).token ?? ""));
   }
-  if (evt.type === "run_complete") break;
+  if (evt.type === "trace_complete") break;
 }
 ```
 
@@ -766,18 +770,18 @@ if (tc) {
 }
 ```
 
-#### `runWithTraceContext(ctx, fn)`
+#### `withTraceContext(ctx, fn)`
 
 ```ts
-runWithTraceContext<T>(ctx: { traceId: string; spanId: string }, fn: () => T): T
+withTraceContext<T>(ctx: { traceId: string; spanId: string }, fn: () => T): T
 ```
 
 Runs a function inside an explicit trace context.
 
 ```ts
-import { runWithTraceContext } from "service-bridge";
+import { withTraceContext } from "service-bridge";
 
-runWithTraceContext({ traceId: "trace-1", spanId: "span-1" }, async () => {
+withTraceContext({ traceId: "trace-1", spanId: "span-1" }, async () => {
   await sb.event("audit.log", { action: "user.login" });
 });
 ```
@@ -807,7 +811,7 @@ app.use(servicebridgeMiddleware({
 }));
 
 app.get("/users/:id", async (req, res) => {
-  const user = await req.servicebridge.rpc("users/get", { id: req.params.id });
+  const user = await req.servicebridge.rpc("user.get", { id: req.params.id });
   res.json(user);
 });
 ```
@@ -863,7 +867,7 @@ await app.register(servicebridgePlugin, {
 });
 
 app.get("/users/:id", wrapHandler(async (request, reply) => {
-  const user = await request.servicebridge.rpc("users/get", {
+  const user = await request.servicebridge.rpc("user.get", {
     id: (request.params as any).id,
   });
   return reply.send(user);
@@ -960,7 +964,7 @@ const sb = servicebridge(
 import { servicebridge, ServiceBridgeError } from "service-bridge";
 
 try {
-  await sb.rpc("payments/charge", { orderId: "ord_1" });
+  await sb.rpc("payment.charge", { orderId: "ord_1" });
 } catch (e) {
   if (e instanceof ServiceBridgeError) {
     console.error(e.component, e.operation, e.severity, e.retryable, e.code);
@@ -1148,12 +1152,12 @@ session.onConfigPush({
     'payment-svc': { mode: 'proxy', fallbackPolicy: 'fallback_to_direct' },
   },
   functionOverrides: {
-    'payment-svc/charge': { mode: 'proxy', timeoutMs: 5000 },
+    'payment.charge': { mode: 'proxy', timeoutMs: 5000 },
   },
 });
 
 // Разрешить транспорт для функции
-const mode = session.resolveTransportMode('payment-svc/charge'); // 'proxy'
+const mode = session.resolveTransportMode('payment.charge'); // 'proxy'
 ```
 
 ### Все события сессии

package/dist/express.js

@@ -1,5 +1,5 @@
 // http/src/express.ts
-import { runWithTraceContext } from "service-bridge";
+import { withTraceContext } from "service-bridge";
 
 // http/src/trace.ts
 function parseTraceparent(traceparent) {
@@ -86,7 +86,7 @@ function servicebridgeMiddleware(options) {
     };
     res.on("finish", onFinish);
     res.on("close", onFinish);
-    runWithTraceContext({ traceId: span.traceId, spanId: span.spanId }, () => {
+    withTraceContext({ traceId: span.traceId, spanId: span.spanId }, () => {
       next();
     });
   };

package/dist/fastify.js

@@ -1,5 +1,5 @@
 // http/src/fastify.ts
-import { runWithTraceContext } from "service-bridge";
+import { withTraceContext } from "service-bridge";
 
 // http/src/trace.ts
 function parseTraceparent(traceparent) {
@@ -111,7 +111,7 @@ function wrapHandler(handler) {
     const traceId = request.traceId;
     const spanId = request.spanId;
     if (traceId && spanId) {
-      return runWithTraceContext({ traceId, spanId }, () => handler(request, reply));
+      return withTraceContext({ traceId, spanId }, () => handler(request, reply));
     }
     return handler(request, reply);
   };