service-bridge 1.0.17 → 1.1.1-dev.29

package/README.md

@@ -97,7 +97,6 @@ import { servicebridge } from "service-bridge";
 const sb = servicebridge(
   process.env.SERVICEBRIDGE_URL ?? "localhost:14445",
   process.env.SERVICEBRIDGE_SERVICE_KEY!,
-  "payments",
 );
 
 sb.handleRpc("charge", async (payload: { orderId: string; amount: number }) => {
@@ -115,7 +114,6 @@ import { servicebridge } from "service-bridge";
 const sb = servicebridge(
   process.env.SERVICEBRIDGE_URL ?? "localhost:14445",
   process.env.SERVICEBRIDGE_SERVICE_KEY!,
-  "orders",
 );
 
 const result = await sb.rpc<{ ok: boolean; txId: string }>("payments/charge", {
@@ -153,7 +151,7 @@ import { servicebridge } from "service-bridge";
 
 // --- Payments service (worker) ---
 
-const payments = servicebridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!, "payments");
+const payments = servicebridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!);
 
 payments.handleRpc("charge", async (payload: { orderId: string; amount: number }, ctx) => {
   await ctx?.stream.write({ status: "charging", orderId: payload.orderId }, "progress");
@@ -170,7 +168,7 @@ await payments.serve({ host: "localhost" });
 ```ts
 // --- Orders service (caller + event publisher) ---
 
-const orders = servicebridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!, "orders");
+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", {
@@ -190,7 +188,7 @@ await orders.event("orders.completed", {
 ```ts
 // --- Notifications service (event consumer) ---
 
-const notifications = servicebridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!, "notifications");
+const notifications = servicebridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!);
 
 notifications.handleEvent("orders.*", async (payload, ctx) => {
   const body = payload as { orderId: string; txId: string };
@@ -273,18 +271,19 @@ across all three SDKs. Parity differences are naming-only (language idioms):
 - 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?)`
+### `servicebridge(url, serviceKey, opts?)`
 
 ```ts
 function servicebridge(
   url: string,
   serviceKey: string,
-  service?: string,
-  globalOpts?: ServiceBridgeOpts,
+  serviceOrOpts?: string | ServiceBridgeOpts,
+  maybeGlobalOpts?: ServiceBridgeOpts,
 ): ServiceBridgeService
 ```
 
 Creates an SDK client instance.
+Service identity is resolved by the runtime from `serviceKey`; passing a third `service` argument is legacy-only.
 
 `ServiceBridgeOpts`:
 
@@ -540,7 +539,7 @@ Registers an event consumer handler. Chainable.
 
 | Option | Type | Description |
 |---|---|---|
-| `groupName` | `string` | Consumer group name. Default: `<service>.<pattern>`. |
+| `groupName` | `string` | Consumer group name. Default: `<service-key-id>.<pattern>`. |
 | `concurrency` | `number` | Advisory concurrency hint (currently not hard-enforced). |
 | `prefetch` | `number` | Advisory prefetch hint (currently not hard-enforced). |
 | `retryPolicyJson` | `string` | Retry policy JSON string. |
@@ -766,7 +765,7 @@ import express from "express";
 import { servicebridge } from "service-bridge";
 import { servicebridgeMiddleware, registerExpressRoutes } from "service-bridge/express";
 
-const sb = servicebridge(process.env.SERVICEBRIDGE_URL!, process.env.SERVICEBRIDGE_SERVICE_KEY!, "api");
+const sb = servicebridge(process.env.SERVICEBRIDGE_URL!, process.env.SERVICEBRIDGE_SERVICE_KEY!);
 const app = express();
 
 app.use(servicebridgeMiddleware({
@@ -822,7 +821,7 @@ import Fastify from "fastify";
 import { servicebridge } from "service-bridge";
 import { servicebridgePlugin, wrapHandler } from "service-bridge/fastify";
 
-const sb = servicebridge(process.env.SERVICEBRIDGE_URL!, process.env.SERVICEBRIDGE_SERVICE_KEY!, "api");
+const sb = servicebridge(process.env.SERVICEBRIDGE_URL!, process.env.SERVICEBRIDGE_SERVICE_KEY!);
 const app = Fastify();
 
 await app.register(servicebridgePlugin, {
@@ -895,13 +894,11 @@ The SDK requires values you pass into `servicebridge(...)`. Common setup:
 |---|---|---|---|
 | `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 |
 
 ```ts
 const sb = servicebridge(
   process.env.SERVICEBRIDGE_URL ?? "localhost:14445",
   process.env.SERVICEBRIDGE_SERVICE_KEY!,
-  process.env.SERVICEBRIDGE_SERVICE ?? "orders",
 );
 ```
 

package/dist/index.js

@@ -90,7 +90,27 @@ class ServiceBridgeError extends Error {
     this.operation = opts.operation;
     this.severity = opts.severity;
     this.retryable = opts.severity === "retriable";
-    this.cause = opts.cause;
+    Object.defineProperty(this, "cause", {
+      value: opts.cause,
+      writable: true,
+      enumerable: false,
+      configurable: true
+    });
+  }
+  toString() {
+    return `ServiceBridgeError [${this.severity}]: ${this.message} (${this.operation})`;
+  }
+  [Symbol.for("nodejs.util.inspect.custom")]() {
+    const lines = [
+      `ServiceBridgeError [${this.severity}]`,
+      `  operation: ${this.operation}`,
+      `  message:   ${this.message}`
+    ];
+    if (this.code !== undefined) {
+      lines.push(`  code:      ${this.code}`);
+    }
+    return lines.join(`
+`);
   }
 }
 function containsValue(values, value) {
@@ -214,7 +234,14 @@ function normalizeServiceError(err, operation, component = "control-plane") {
   }
   const grpcErr = err;
   const code = typeof grpcErr?.code === "number" ? grpcErr.code : undefined;
-  const message = typeof grpcErr?.message === "string" && grpcErr.message.length > 0 ? grpcErr.message : err instanceof Error ? err.message : String(err);
+  const details = typeof grpcErr?.details === "string" && grpcErr.details.trim() ? grpcErr.details.trim() : undefined;
+  const rawMsg = (() => {
+    const m = typeof grpcErr?.message === "string" && grpcErr.message ? grpcErr.message : err instanceof Error ? err.message : String(err);
+    return m.replace(/^\d+\s+[A-Z_]+:\s*/, "").trim() || m;
+  })();
+  const base = friendlyGrpcMessage(code, details ?? rawMsg);
+  const appendDetails = details && (code === grpc.status.INTERNAL || code === grpc.status.UNKNOWN || code === undefined);
+  const message = appendDetails ? `${base}: ${details}` : base;
   return new ServiceBridgeError({
     message,
     code,
@@ -224,13 +251,74 @@ function normalizeServiceError(err, operation, component = "control-plane") {
     cause: err
   });
 }
+function friendlyGrpcMessage(code, rawMessage) {
+  if (code === undefined)
+    return rawMessage || "unknown error";
+  switch (code) {
+    case grpc.status.UNAVAILABLE:
+      return "control plane unavailable";
+    case grpc.status.DEADLINE_EXCEEDED:
+      return "request timed out";
+    case grpc.status.UNAUTHENTICATED:
+      return "authentication failed — check service key";
+    case grpc.status.PERMISSION_DENIED:
+      return "permission denied — check service key";
+    case grpc.status.RESOURCE_EXHAUSTED:
+      return "rate limit exceeded";
+    case grpc.status.NOT_FOUND:
+      return "resource not found";
+    case grpc.status.INTERNAL:
+      return "internal server error";
+    case grpc.status.FAILED_PRECONDITION:
+      return "precondition failed";
+    case grpc.status.CANCELLED:
+      return "request cancelled";
+    case grpc.status.UNIMPLEMENTED:
+      return "operation not supported by control plane";
+    case grpc.status.UNKNOWN:
+      return "unknown error from control plane";
+    default:
+      return rawMessage || "unknown error";
+  }
+}
+function friendlySDKMessage(operation, err) {
+  const base = err.message;
+  switch (operation) {
+    case "open-worker-session":
+    case "worker-session":
+      return err.severity === "retriable" ? `${base} — waiting for reconnect` : `worker session error: ${base}`;
+    case "worker-session-end":
+      return `worker session cleanup: ${base}`;
+    case "worker-session-command":
+      return `worker command error: ${base}`;
+    case "heartbeat":
+      return `heartbeat failed: ${base}`;
+    case "http-heartbeat":
+      return `HTTP heartbeat failed: ${base}`;
+    case "flush-offline-queue":
+      return `offline queue flush failed: ${base}`;
+    case "flush-on-ready":
+    case "flush-on-restore":
+      return `offline queue flush failed: ${base}`;
+    case "report-call-start":
+    case "report-call":
+      return `call report failed: ${base}`;
+    case "worker-force-shutdown":
+    case "worker-try-shutdown":
+      return `worker shutdown error: ${base}`;
+    case "close-control-plane-client":
+      return `control plane disconnect: ${base}`;
+    default:
+      return `${operation}: ${base}`;
+  }
+}
 function reportSDKError(operation, err, component = "sdk") {
   const normalized = normalizeServiceError(err, operation, component);
-  const message = `[servicebridge] ${normalized.component}.${normalized.operation}: ${normalized.message}`;
+  const friendly = friendlySDKMessage(operation, normalized);
   if (normalized.severity === "fatal") {
-    console.error(message, err);
+    console.error(`[servicebridge] ${friendly}`);
   } else {
-    console.warn(message, err);
+    console.warn(`[servicebridge] ${friendly}`);
   }
   return normalized;
 }
@@ -260,6 +348,101 @@ function workerChannelOptions(tlsOpts) {
 function workerClientCredentials(tlsOpts) {
   return grpc.credentials.createSsl(toPemBuffer(tlsOpts?.caCert), toPemBuffer(tlsOpts?.key), toPemBuffer(tlsOpts?.cert));
 }
+var _wireStringMapMode = null;
+function detectWireStringMapMode() {
+  const publishMethod = servicebridgeProto.ServiceBridge.service?.Publish;
+  const serialize = publishMethod?.requestSerialize;
+  if (typeof serialize !== "function") {
+    return "entries";
+  }
+  const baseReq = {
+    topic: "__probe__",
+    payload: Buffer.alloc(0),
+    trace_id: "",
+    parent_span_id: "",
+    producer_service: "",
+    idempotency_key: ""
+  };
+  try {
+    serialize({
+      ...baseReq,
+      headers: { probe: "1" }
+    });
+    return "object";
+  } catch {
+    try {
+      serialize({
+        ...baseReq,
+        headers: [{ key: "probe", value: "1" }]
+      });
+      return "entries";
+    } catch {
+      return "entries";
+    }
+  }
+}
+function wireStringMapMode() {
+  if (_wireStringMapMode === null) {
+    _wireStringMapMode = detectWireStringMapMode();
+  }
+  return _wireStringMapMode;
+}
+function normalizeStringMap(raw) {
+  const normalized = {};
+  if (!raw)
+    return normalized;
+  for (const [key, value] of Object.entries(raw)) {
+    const k = key.trim();
+    if (!k)
+      continue;
+    if (typeof value === "string") {
+      normalized[k] = value;
+      continue;
+    }
+    if (value == null) {
+      normalized[k] = "";
+      continue;
+    }
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+      normalized[k] = String(value);
+      continue;
+    }
+    try {
+      normalized[k] = JSON.stringify(value);
+    } catch {
+      normalized[k] = String(value);
+    }
+  }
+  return normalized;
+}
+function toWireStringMap(raw) {
+  const normalized = normalizeStringMap(raw);
+  if (wireStringMapMode() === "entries") {
+    return Object.entries(normalized).map(([key, value]) => ({
+      key,
+      value
+    }));
+  }
+  return normalized;
+}
+function fromWireStringMap(raw) {
+  if (Array.isArray(raw)) {
+    const out = {};
+    for (const entry of raw) {
+      if (typeof entry?.key !== "string")
+        continue;
+      const key = entry.key.trim();
+      if (!key)
+        continue;
+      out[key] = typeof entry.value === "string" ? entry.value : entry.value == null ? "" : String(entry.value);
+    }
+    return out;
+  }
+  if (raw && typeof raw === "object") {
+    return normalizeStringMap(raw);
+  }
+  return {};
+}
 async function provisionWorkerTLS(controlClient, md, serviceName, extraIps) {
   const { privateKey, publicKey } = crypto.generateKeyPairSync("ec", {
     namedCurve: "P-256",
@@ -296,8 +479,16 @@ function ensureSbResolverRegistered() {
     listener;
     refreshTimer = null;
     constructor(target, listener) {
-      this.clientId = target.authority ?? "";
-      this.canonicalName = (target.path ?? "").replace(/^\/+/, "");
+      const authority = (target.authority ?? "").trim();
+      const normalizedPath = (target.path ?? "").replace(/^\/+/, "");
+      if (authority && authority !== "localhost" && _sbContexts.has(authority)) {
+        this.clientId = authority;
+        this.canonicalName = normalizedPath;
+      } else {
+        const [clientIdFromPath = "", ...canonicalParts] = normalizedPath.split("/");
+        this.clientId = clientIdFromPath.trim();
+        this.canonicalName = canonicalParts.join("/").trim();
+      }
       this.listener = listener;
       this.init().catch(() => {});
     }
@@ -309,7 +500,7 @@ function ensureSbResolverRegistered() {
           error: {
             code: 14,
             details: `No SB context for clientId=${this.clientId}`,
-            metadata: {}
+            metadata: new grpc.Metadata
           }
         }, {}, null, "sb-resolver");
         return;
@@ -336,7 +527,7 @@ function ensureSbResolverRegistered() {
           error: {
             code: 14,
             details: `No live endpoints for ${this.canonicalName}`,
-            metadata: {}
+            metadata: new grpc.Metadata
           }
         }, {}, null, "sb-resolver");
         return;
@@ -355,7 +546,11 @@ function ensureSbResolverRegistered() {
   }
   registerResolver("sb", SbResolver);
 }
-function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
+function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}) {
+  const service = typeof serviceOrOpts === "string" ? serviceOrOpts.trim() : "";
+  const globalOpts = typeof serviceOrOpts === "string" ? maybeGlobalOpts : serviceOrOpts ?? {};
+  const parsedServiceKey = parseServiceKeyV2(serviceKey);
+  const defaultConsumerPrefix = service || parsedServiceKey.keyId || "consumer";
   const meta = new grpc.Metadata;
   meta.add("x-service-key", serviceKey);
   const rawUrl = url.trim();
@@ -396,8 +591,9 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
   const fnAliasMap = new Map;
   const functionChannels = new Map;
   let isOnline = false;
+  let isFlushing = false;
   let stopped = false;
-  let onlineRestoreTimer = null;
+  let isWatchingChannel = false;
   const offlineQueue = [];
   let workerServer = null;
   let workerSessionStream = null;
@@ -444,7 +640,30 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
     md.add("x-caller-service", service);
     return md;
   }
+  function sessionSend(msg) {
+    if (!workerSessionStream)
+      return false;
+    try {
+      workerSessionStream.write(msg);
+      return true;
+    } catch {
+      return false;
+    }
+  }
   async function sendReportCallStart(op) {
+    if (sessionSend({
+      telemetry_start: {
+        trace_id: op.traceId,
+        span_id: op.spanId,
+        parent_span_id: op.parentSpanId,
+        fn: op.fn,
+        started_at: String(op.startedAt),
+        input: op.inputBuf,
+        attempt: op.attempt
+      }
+    })) {
+      return;
+    }
     await new Promise((resolve, reject) => {
       stub.ReportCallStart({
         trace_id: op.traceId,
@@ -460,6 +679,22 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
     });
   }
   async function sendReportCall(op) {
+    if (sessionSend({
+      telemetry_finish: {
+        trace_id: op.traceId,
+        span_id: op.spanId,
+        fn: op.fn,
+        started_at: String(op.startedAt),
+        duration_ms: String(op.durationMs),
+        success: op.success,
+        error: op.error ?? "",
+        input: op.inputBuf,
+        output: op.outputBuf ?? Buffer.alloc(0),
+        attempt: op.attempt
+      }
+    })) {
+      return;
+    }
     await new Promise((resolve, reject) => {
       stub.ReportCall({
         trace_id: op.traceId,
@@ -467,7 +702,7 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
         fn: op.fn,
         service_name: service,
         started_at: String(op.startedAt),
-        duration_ms: String(computeDurationMs(op.startedAt)),
+        duration_ms: String(op.durationMs),
         success: op.success,
         error: op.error ?? "",
         input: op.inputBuf,
@@ -482,12 +717,17 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
   function flushLogs() {
     if (logBatch.length === 0)
       return;
-    const entries = logBatch;
+    const entries = logBatch.map((entry) => ({
+      ...entry,
+      attributes: toWireStringMap(entry.attributes)
+    }));
     logBatch = [];
     if (logFlushTimer !== null) {
       clearTimeout(logFlushTimer);
       logFlushTimer = null;
     }
+    if (sessionSend({ telemetry_log: { entries } }))
+      return;
     stub.ReportLog({ entries }, meta, unaryDeadlineOptions(), () => {});
   }
   function pushLog(level, msg, attrs) {
@@ -614,7 +854,7 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
         throw new Error("worker TLS is not configured");
       }
       const creds = workerClientCredentials(tlsOpts);
-      ch = new grpc.Channel(`sb://${clientId}/${canonicalName}`, creds, {
+      ch = new grpc.Channel(`sb://localhost/${clientId}/${canonicalName}`, creds, {
         ...workerChannelOptions(tlsOpts ?? undefined),
         "grpc.lb_policy_name": "round_robin"
       });
@@ -661,29 +901,39 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
     }
   }
   _controlReady.then(() => {
-    isOnline = true;
-    flushQueue().catch((err) => {
-      if (isConnectionError(err))
-        scheduleOnlineRestore();
-      else
-        reportSDKError("flush-on-ready", err);
-    });
+    watchChannelConnectivity();
   }).catch(() => {});
-  function scheduleOnlineRestore() {
-    if (stopped || isOnline || onlineRestoreTimer)
+  function watchChannelConnectivity() {
+    isWatchingChannel = false;
+    if (stopped)
       return;
-    onlineRestoreTimer = setTimeout(() => {
-      onlineRestoreTimer = null;
-      if (!stopped) {
+    const channel = stub.getChannel();
+    const state = channel.getConnectivityState(true);
+    if (state === grpc.connectivityState.READY) {
+      if (!isOnline) {
         isOnline = true;
-        flushQueue().catch((err) => {
-          if (isConnectionError(err))
-            scheduleOnlineRestore();
-          else
-            reportSDKError("flush-on-restore", err);
+        const queueLen = offlineQueue.length;
+        console.info(`[servicebridge] reconnected to runtime${queueLen > 0 ? ` — flushing ${queueLen} queued operation(s)` : ""}`);
+        flushQueue().then(() => {
+          if (isOnline)
+            scheduleNextHeartbeat(100);
+        }).catch((err) => {
+          reportSDKError("flush-on-restore", err);
         });
       }
-    }, 2000);
+    } else if (state === grpc.connectivityState.TRANSIENT_FAILURE) {
+      if (isOnline) {
+        isOnline = false;
+        console.warn("[servicebridge] lost connection to runtime — entering offline mode");
+      }
+    }
+    isWatchingChannel = true;
+    channel.watchConnectivityState(state, Infinity, watchChannelConnectivity);
+  }
+  function ensureChannelWatch() {
+    if (!isWatchingChannel && !stopped) {
+      watchChannelConnectivity();
+    }
   }
   function isConnectionError(e) {
     const code = e?.code;
@@ -716,8 +966,11 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
       attempt
     }).catch((err) => {
       if (isConnectionError(err)) {
+        if (isOnline) {
+          console.warn("[servicebridge] lost connection to runtime — entering offline mode");
+        }
         isOnline = false;
-        scheduleOnlineRestore();
+        ensureChannelWatch();
         enqueueOffline({
           type: "reportCallStart",
           traceId,
@@ -734,6 +987,7 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
     });
   }
   function reportCallAsync(traceId, spanId, fn, startedAt, inputBuf, success, attempt, outputBuf, error = "") {
+    const durationMs = computeDurationMs(startedAt);
     if (!isOnline) {
       enqueueOffline({
         type: "reportCall",
@@ -741,6 +995,7 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
         spanId,
         fn,
         startedAt,
+        durationMs,
         inputBuf,
         success,
         attempt,
@@ -754,6 +1009,7 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
       spanId,
       fn,
       startedAt,
+      durationMs,
       inputBuf,
       success,
       attempt,
@@ -761,14 +1017,18 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
       error
     }).catch((err) => {
       if (isConnectionError(err)) {
+        if (isOnline) {
+          console.warn("[servicebridge] lost connection to runtime — entering offline mode");
+        }
         isOnline = false;
-        scheduleOnlineRestore();
+        ensureChannelWatch();
         enqueueOffline({
           type: "reportCall",
           traceId,
           spanId,
           fn,
           startedAt,
+          durationMs,
           inputBuf,
           success,
           attempt,
@@ -781,59 +1041,84 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
     });
   }
   async function flushQueue() {
-    while (offlineQueue.length > 0 && isOnline) {
-      const op = offlineQueue[0];
-      try {
-        if (op.type === "event") {
-          await new Promise((res, rej) => {
-            stub.Publish({
-              topic: op.topic,
-              payload: toJsonBuffer(op.payload),
-              headers: op.opts?.headers ?? {},
-              trace_id: op.opts?.traceId ?? "",
-              parent_span_id: op.opts?.parentSpanId ?? "",
-              producer_service: service,
-              idempotency_key: op.opts?.idempotencyKey ?? ""
-            }, meta, unaryDeadlineOptions(), (err) => err ? rej(err) : res());
-          });
-        } else if (op.type === "job") {
-          await new Promise((res, rej) => {
-            stub.RegisterJob({
-              cron_expr: op.opts.cron ?? "",
-              timezone: op.opts.timezone ?? "UTC",
-              misfire_policy: op.opts.misfire ?? "fire_now",
-              target_type: op.opts.via ?? "rpc",
-              target_ref: op.target,
-              delay_ms: op.opts.delay ?? 0,
-              service_name: service,
-              retry_policy_json: op.opts.retryPolicyJson ?? "{}"
-            }, meta, unaryDeadlineOptions(), (err) => err ? rej(err) : res());
-          });
-        } else if (op.type === "workflow") {
-          await new Promise((res, rej) => {
-            stub.RegisterWorkflow({
-              name: op.name,
-              definition: JSON.stringify(op.steps),
-              opts: op.opts ? JSON.stringify(op.opts) : "{}",
-              service_name: service
-            }, meta, unaryDeadlineOptions(), (err) => err ? rej(err) : res());
-          });
-        } else if (op.type === "reportCallStart") {
-          await sendReportCallStart({ ...op });
-        } else if (op.type === "reportCall") {
-          await sendReportCall(op);
-        }
-        offlineQueue.shift();
-      } catch (err) {
-        if (isConnectionError(err)) {
-          isOnline = false;
-          scheduleOnlineRestore();
-          break;
+    if (isFlushing || offlineQueue.length === 0)
+      return;
+    isFlushing = true;
+    const snapshot = offlineQueue.slice();
+    let flushed = 0;
+    try {
+      while (offlineQueue.length > 0 && isOnline) {
+        const op = offlineQueue[0];
+        try {
+          if (op.type === "event") {
+            await new Promise((res, rej) => {
+              stub.Publish({
+                topic: op.topic,
+                payload: toJsonBuffer(op.payload),
+                headers: toWireStringMap(op.opts?.headers),
+                trace_id: op.opts?.traceId ?? "",
+                parent_span_id: op.opts?.parentSpanId ?? "",
+                producer_service: service,
+                idempotency_key: op.opts?.idempotencyKey ?? ""
+              }, meta, unaryDeadlineOptions(), (err) => err ? rej(err) : res());
+            });
+          } else if (op.type === "job") {
+            await new Promise((res, rej) => {
+              stub.RegisterJob({
+                cron_expr: op.opts.cron ?? "",
+                timezone: op.opts.timezone ?? "UTC",
+                misfire_policy: op.opts.misfire ?? "fire_now",
+                target_type: op.opts.via ?? "rpc",
+                target_ref: op.target,
+                delay_ms: op.opts.delay ?? 0,
+                service_name: service,
+                retry_policy_json: op.opts.retryPolicyJson ?? "{}"
+              }, meta, unaryDeadlineOptions(), (err) => err ? rej(err) : res());
+            });
+          } else if (op.type === "workflow") {
+            await new Promise((res, rej) => {
+              stub.RegisterWorkflow({
+                name: op.name,
+                definition: JSON.stringify(op.steps),
+                opts: op.opts ? JSON.stringify(op.opts) : "{}",
+                service_name: service
+              }, meta, unaryDeadlineOptions(), (err) => err ? rej(err) : res());
+            });
+          } else if (op.type === "reportCallStart") {
+            await sendReportCallStart({ ...op });
+          } else if (op.type === "reportCall") {
+            await sendReportCall(op);
+          }
+          offlineQueue.shift();
+          flushed++;
+        } catch (err) {
+          if (isConnectionError(err)) {
+            if (isOnline) {
+              console.warn("[servicebridge] lost connection to runtime — entering offline mode");
+            }
+            isOnline = false;
+            ensureChannelWatch();
+            break;
+          }
+          reportSDKError("flush-offline-queue", err);
+          offlineQueue.shift();
         }
-        reportSDKError("flush-offline-queue", err);
-        break;
       }
+    } finally {
+      isFlushing = false;
     }
+    if (flushed > 0) {
+      const remaining = offlineQueue.length;
+      const sentOps = snapshot.slice(0, flushed);
+      console.info(`[servicebridge] flushed ${flushed}/${snapshot.length} queued operation(s) to runtime` + ` (${formatQueueSummary(sentOps)})` + (remaining > 0 ? ` — ${remaining} still queued` : ""));
+    }
+  }
+  function formatQueueSummary(ops) {
+    const counts = {};
+    for (const op of ops) {
+      counts[op.type] = (counts[op.type] ?? 0) + 1;
+    }
+    return Object.entries(counts).map(([type, n]) => `${n} ${type}`).join(", ");
   }
   function requirePeerCN(call, allowedCallers, isDeliver) {
     const peerCN = extractPeerCN(call);
@@ -858,6 +1143,17 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
       return;
     const state = serveState;
     const metrics = getProcessMetrics();
+    const hbMsg = {
+      endpoint: state.endpoint,
+      group_names: [...registeredGroups],
+      function_names: [...fnHandlers.keys()]
+    };
+    if (metrics.cpuPercent != null)
+      hbMsg.cpu_percent = metrics.cpuPercent;
+    if (metrics.ramMb != null)
+      hbMsg.ram_mb = metrics.ramMb;
+    if (sessionSend({ heartbeat: hbMsg }))
+      return;
     const req = {
       service_name: service,
       instance_id: state.instanceId,
@@ -875,6 +1171,8 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
     });
   }
   async function sendHttpHeartbeat(instanceId) {
+    if (sessionSend({ http_heartbeat: {} }))
+      return;
     await new Promise((resolve, reject) => {
       stub.HeartbeatHttpEndpoint({ service_name: service, instance_id: instanceId }, meta, unaryDeadlineOptions(), (err, res) => {
         if (err) {
@@ -967,8 +1265,11 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
       }
     } catch (err) {
       if (isConnectionError(err)) {
+        if (isOnline) {
+          console.warn("[servicebridge] lost connection to runtime — entering offline mode");
+        }
         isOnline = false;
-        scheduleOnlineRestore();
+        ensureChannelWatch();
       } else if (isRegistryResyncRequiredError(err)) {
         await syncRegistrations("heartbeat-resync");
       } else {
@@ -996,12 +1297,12 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
     const append = (data, key = "default") => {
       if (!isOnline || !runId)
         return Promise.resolve();
+      const dataBuf = Buffer.from(JSON.stringify(data));
+      if (sessionSend({ append_stream: { run_id: runId, key, data: dataBuf } })) {
+        return Promise.resolve();
+      }
       return new Promise((resolve, reject) => {
-        stub.AppendStream({
-          run_id: runId,
-          key,
-          data: Buffer.from(JSON.stringify(data))
-        }, meta, unaryDeadlineOptions(), (err) => err ? reject(normalizeServiceError(err, `append-stream:${runId}`)) : resolve());
+        stub.AppendStream({ run_id: runId, key, data: dataBuf }, meta, unaryDeadlineOptions(), (err) => err ? reject(normalizeServiceError(err, `append-stream:${runId}`)) : resolve());
       });
     };
     return {
@@ -1083,7 +1384,7 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
         groupName: entry.groupName,
         messageId: String(req.message_id ?? ""),
         attempt: Number(req.attempt ?? 0),
-        headers: req.headers ?? {}
+        headers: fromWireStringMap(req.headers)
       },
       retry(delayMs = 1000) {
         shouldRetry = true;
@@ -1187,7 +1488,7 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
           group_name: String(event.group_name ?? ""),
           topic: String(event.topic ?? ""),
           payload: event.payload ? Buffer.from(event.payload) : Buffer.alloc(0),
-          headers: event.headers ?? {},
+          headers: fromWireStringMap(event.headers),
           trace_id: String(event.trace_id ?? ""),
           parent_span_id: String(event.parent_span_id ?? ""),
           attempt: Number(event.attempt ?? 0)
@@ -1391,7 +1692,7 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
         stub.Publish({
           topic,
           payload: toJsonBuffer(payload),
-          headers: opts?.headers ?? {},
+          headers: toWireStringMap(opts?.headers),
           trace_id: opts?.traceId ?? tc?.traceId ?? "",
           parent_span_id: opts?.parentSpanId ?? tc?.spanId ?? "",
           producer_service: service,
@@ -1405,7 +1706,7 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
     },
     handleEvent(pattern, handler, opts) {
       const normalizedOpts = opts ?? {};
-      const groupName = normalizedOpts.groupName || `${service}.${pattern}`;
+      const groupName = normalizedOpts.groupName || `${defaultConsumerPrefix}.${pattern}`;
       if (eventHandlers.has(groupName)) {
         throw new Error(`Duplicate event consumer group "${groupName}". ` + "Use a distinct groupName for each handleEvent() registration.");
       }
@@ -1423,9 +1724,6 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
       if (fnHandlers.size === 0 && eventHandlers.size === 0) {
         throw new Error("No handlers registered. Call handleRpc() or handleEvent() before serve().");
       }
-      if (!service.trim()) {
-        throw new Error("serve() requires a non-empty service name");
-      }
       if (opts.maxInFlight != null && (!Number.isInteger(opts.maxInFlight) || opts.maxInFlight < 1)) {
         throw new Error("serve() maxInFlight must be a positive integer");
       }
@@ -1494,17 +1792,17 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
         closeWorkerSession();
         serveState = null;
         shutdownWorkerServerGracefully();
-        throw normalizeServiceError(err, "serve");
+        const fatal = normalizeServiceError(err, "serve");
+        console.error(`[servicebridge] startup failed: ${fatal.message}`);
+        throw fatal;
       }
     },
     stop() {
       stopped = true;
       isOnline = false;
-      if (onlineRestoreTimer)
-        clearTimeout(onlineRestoreTimer);
+      isWatchingChannel = false;
       if (heartbeatTimer)
         clearTimeout(heartbeatTimer);
-      onlineRestoreTimer = null;
       heartbeatTimer = null;
       registeredGroups.clear();
       closeWorkerSession();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "service-bridge",
-  "version": "1.0.17",
+  "version": "1.1.1-dev.29",
   "type": "module",
   "description": "ServiceBridge SDK for Node.js — production-ready RPC, durable events, workflows, jobs, and distributed tracing. One Go runtime + PostgreSQL replaces Istio, RabbitMQ, Temporal, and Jaeger.",
   "keywords": [