service-bridge 1.0.17 → 1.1.0-dev.27

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();
@@ -444,7 +639,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 +678,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 +701,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 +716,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 +853,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"
       });
@@ -676,18 +915,21 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
       onlineRestoreTimer = null;
       if (!stopped) {
         isOnline = true;
+        const queueLen = offlineQueue.length;
+        console.info(`[servicebridge] reconnected to runtime${queueLen > 0 ? ` — flushing ${queueLen} queued operation(s)` : ""}`);
         flushQueue().catch((err) => {
           if (isConnectionError(err))
             scheduleOnlineRestore();
           else
             reportSDKError("flush-on-restore", err);
         });
+        scheduleNextHeartbeat(100);
       }
     }, 2000);
   }
   function isConnectionError(e) {
     const code = e?.code;
-    return code === grpc.status.UNAVAILABLE || code === grpc.status.UNKNOWN;
+    return code === grpc.status.UNAVAILABLE || code === grpc.status.UNKNOWN || code === grpc.status.DEADLINE_EXCEEDED || code === grpc.status.RESOURCE_EXHAUSTED || code === grpc.status.INTERNAL;
   }
   function normalizeUnknownErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -716,6 +958,9 @@ 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();
         enqueueOffline({
@@ -734,6 +979,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 +987,7 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
         spanId,
         fn,
         startedAt,
+        durationMs,
         inputBuf,
         success,
         attempt,
@@ -754,6 +1001,7 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
       spanId,
       fn,
       startedAt,
+      durationMs,
       inputBuf,
       success,
       attempt,
@@ -761,6 +1009,9 @@ 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();
         enqueueOffline({
@@ -769,6 +1020,7 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
           spanId,
           fn,
           startedAt,
+          durationMs,
           inputBuf,
           success,
           attempt,
@@ -781,6 +1033,10 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
     });
   }
   async function flushQueue() {
+    if (offlineQueue.length === 0)
+      return;
+    const snapshot = offlineQueue.slice();
+    let flushed = 0;
     while (offlineQueue.length > 0 && isOnline) {
       const op = offlineQueue[0];
       try {
@@ -789,7 +1045,7 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
             stub.Publish({
               topic: op.topic,
               payload: toJsonBuffer(op.payload),
-              headers: op.opts?.headers ?? {},
+              headers: toWireStringMap(op.opts?.headers),
               trace_id: op.opts?.traceId ?? "",
               parent_span_id: op.opts?.parentSpanId ?? "",
               producer_service: service,
@@ -824,8 +1080,12 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
           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;
           scheduleOnlineRestore();
           break;
@@ -834,6 +1094,18 @@ function servicebridge(url, serviceKey, service = "", globalOpts = {}) {
         break;
       }
     }
+    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 +1130,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 +1158,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,6 +1252,9 @@ 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();
       } else if (isRegistryResyncRequiredError(err)) {
@@ -996,12 +1284,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 +1371,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 +1475,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 +1679,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 +1693,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 +1711,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,7 +1779,9 @@ 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() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "service-bridge",
-  "version": "1.0.17",
+  "version": "1.1.0-dev.27",
   "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": [