@xmoxmo/bncr 0.3.4 → 0.3.6

package/src/runtime/register-trace-runtime.ts

@@ -0,0 +1,102 @@
+import {
+  appendBoundedRegisterTrace,
+  buildRegisterDriftSnapshot,
+  buildRegisterTraceEntry,
+  buildRegisterTraceSummary,
+  type RegisterDriftSnapshot,
+  type RegisterTraceEntry,
+  type RegisterTraceSummary,
+} from '../core/register-trace.ts';
+
+export type RegisterTraceRuntimeState = {
+  registerCount: number;
+  apiGeneration: number;
+  firstRegisterAt: number | null;
+  lastRegisterAt: number | null;
+  lastApiRebindAt: number | null;
+  pluginSource: string | null;
+  pluginVersion: string | null;
+  lastApiInstanceId: string | null;
+  lastRegistryFingerprint: string | null;
+  lastDriftSnapshot: RegisterDriftSnapshot | null;
+  registerTraceRecent: RegisterTraceEntry[];
+};
+
+export type RegisterTraceRuntimeMeta = {
+  source?: string;
+  pluginVersion?: string;
+  apiRebound?: boolean;
+  apiInstanceId?: string;
+  registryFingerprint?: string;
+};
+
+export function buildRegisterTraceRuntimeSummary(args: {
+  state: Pick<RegisterTraceRuntimeState, 'registerTraceRecent' | 'firstRegisterAt'>;
+  warmupWindowMs: number;
+}): RegisterTraceSummary {
+  return buildRegisterTraceSummary({
+    traceRecent: args.state.registerTraceRecent,
+    firstRegisterAt: args.state.firstRegisterAt,
+    warmupWindowMs: args.warmupWindowMs,
+  });
+}
+
+export function noteRegisterTraceRuntime(args: {
+  state: RegisterTraceRuntimeState;
+  meta: RegisterTraceRuntimeMeta;
+  ts: number;
+  stack: string;
+  bridgeId: string;
+  gatewayPid: number;
+  warmupWindowMs: number;
+  maxTraceEntries?: number;
+}): { trace: RegisterTraceEntry; summary: RegisterTraceSummary; capturedDriftSnapshot: boolean } {
+  const { state, meta } = args;
+  state.registerCount += 1;
+  if (state.firstRegisterAt == null) state.firstRegisterAt = args.ts;
+  state.lastRegisterAt = args.ts;
+  if (meta.apiRebound) {
+    state.apiGeneration += 1;
+    state.lastApiRebindAt = args.ts;
+  } else if (state.registerCount === 1 && state.apiGeneration === 0) {
+    state.apiGeneration = 1;
+  }
+  if (meta.source) state.pluginSource = meta.source;
+  if (meta.pluginVersion) state.pluginVersion = meta.pluginVersion;
+  if (meta.apiInstanceId) state.lastApiInstanceId = meta.apiInstanceId;
+  if (meta.registryFingerprint) state.lastRegistryFingerprint = meta.registryFingerprint;
+
+  const trace = buildRegisterTraceEntry({
+    ts: args.ts,
+    bridgeId: args.bridgeId,
+    gatewayPid: args.gatewayPid,
+    registerCount: state.registerCount,
+    apiGeneration: state.apiGeneration,
+    apiRebound: meta.apiRebound === true,
+    apiInstanceId: state.lastApiInstanceId,
+    registryFingerprint: state.lastRegistryFingerprint,
+    source: state.pluginSource,
+    pluginVersion: state.pluginVersion,
+    stack: args.stack,
+  });
+  appendBoundedRegisterTrace(state.registerTraceRecent, trace, args.maxTraceEntries ?? 12);
+
+  const summary = buildRegisterTraceRuntimeSummary({
+    state,
+    warmupWindowMs: args.warmupWindowMs,
+  });
+  const capturedDriftSnapshot = summary.postWarmupRegisterCount > 0;
+  if (capturedDriftSnapshot) {
+    state.lastDriftSnapshot = buildRegisterDriftSnapshot({
+      capturedAt: args.ts,
+      registerCount: state.registerCount,
+      apiGeneration: state.apiGeneration,
+      summary,
+      apiInstanceId: state.lastApiInstanceId,
+      registryFingerprint: state.lastRegistryFingerprint,
+      traceRecent: state.registerTraceRecent,
+    });
+  }
+
+  return { trace, summary, capturedDriftSnapshot };
+}

package/src/runtime/status-snapshots.ts

@@ -46,6 +46,10 @@ export function buildRuntimeEventCounters(args: {
   };
 }
 
+function nullableMapNumber(map: Map<string, number>, key: string): number | null {
+  return map.get(key) ?? null;
+}
+
 export function buildRuntimeActivitySnapshot(args: {
   accountId: string;
   activeConnectionCount: (accountId: string) => number;
@@ -58,9 +62,9 @@ export function buildRuntimeActivitySnapshot(args: {
   return {
     activeConnections: args.activeConnectionCount(accountId),
     lastSession: args.lastSessionByAccount.get(accountId) || null,
-    lastActivityAt: args.lastActivityByAccount.get(accountId) || null,
-    lastInboundAt: args.lastInboundByAccount.get(accountId) || null,
-    lastOutboundAt: args.lastOutboundByAccount.get(accountId) || null,
+    lastActivityAt: nullableMapNumber(args.lastActivityByAccount, accountId),
+    lastInboundAt: nullableMapNumber(args.lastInboundByAccount, accountId),
+    lastOutboundAt: nullableMapNumber(args.lastOutboundByAccount, accountId),
   };
 }
 

package/src/runtime/status-worker.ts

@@ -15,8 +15,58 @@ export type ChannelAccountWorkerHandle = {
   timer: NodeJS.Timeout;
   finish: (reason: string) => void;
   cleanupAbortListener?: () => void;
+  healthLogState?: HealthStatusLogState;
 };
 
+export const HEALTH_STATUS_STABLE_WINDOW_MS = 10_000;
+
+export type HealthStatusLogState = {
+  emittedSig: string | null;
+  pendingSig: string | null;
+  pendingSince: number;
+};
+
+export function createHealthStatusLogState(): HealthStatusLogState {
+  return { emittedSig: null, pendingSig: null, pendingSince: 0 };
+}
+
+function finiteNumberOr(value: unknown, fallback: number): number {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function nonNegativeFiniteNumberOr(value: unknown, fallback: number): number {
+  return Math.max(0, finiteNumberOr(value, fallback));
+}
+
+export function updateHealthStatusLogState(args: {
+  state: HealthStatusLogState;
+  sig: string;
+  nowMs: number;
+  stableWindowMs?: number;
+}): 'pending' | 'stable' | 'unchanged' {
+  const stableWindowMs = nonNegativeFiniteNumberOr(
+    args.stableWindowMs,
+    HEALTH_STATUS_STABLE_WINDOW_MS,
+  );
+  const nowMs = finiteNumberOr(args.nowMs, 0);
+  if (args.state.emittedSig === args.sig) {
+    args.state.pendingSig = null;
+    args.state.pendingSince = 0;
+    return 'unchanged';
+  }
+  if (args.state.pendingSig !== args.sig) {
+    args.state.pendingSig = args.sig;
+    args.state.pendingSince = nowMs;
+    if (stableWindowMs > 0) return 'pending';
+  }
+  if (nowMs - args.state.pendingSince < stableWindowMs) return 'pending';
+  args.state.emittedSig = args.sig;
+  args.state.pendingSig = null;
+  args.state.pendingSince = 0;
+  return 'stable';
+}
+
 type StatusWorkerHooks = {
   isOnline: (accountId: string) => boolean;
   hasRecentInboundReachability: (accountId: string) => boolean;
@@ -30,6 +80,8 @@ type StatusWorkerHooks = {
     message: string,
     options: { key: string; sig: string; debugOnly?: boolean; windowMs?: number },
   ) => void;
+  now?: () => number;
+  healthStableWindowMs?: number;
 };
 
 type StatusWorkerRuntime = {
@@ -66,6 +118,7 @@ export async function startBncrStatusWorker(
 ) {
   const accountId = normalizeAccountId(ctx.accountId);
   clearBncrStatusWorker(runtime, accountId, 'start-replace');
+  let worker!: ChannelAccountWorkerHandle;
 
   const tick = () => {
     const previous = ctx.getStatus?.() || {};
@@ -84,14 +137,20 @@ export async function startBncrStatusWorker(
       activeConnections,
     });
     const conns = activeConnections.length;
-    runtime.hooks.logInfoDedup(
-      'health',
-      `status-tick ${accountId}|changed|${connected ? 'linked' : 'configured'}|onlineByConn=${onlineByConn}|recentInboundReachable=${recentInboundReachable}|conns=${conns}`,
-      {
-        key: `health-status-tick:${accountId}`,
-        sig: healthSig,
-      },
-    );
+    const healthLogState = worker.healthLogState || createHealthStatusLogState();
+    worker.healthLogState = healthLogState;
+    const healthLogDecision = updateHealthStatusLogState({
+      state: healthLogState,
+      sig: healthSig,
+      nowMs: runtime.hooks.now?.() ?? Date.now(),
+      stableWindowMs: runtime.hooks.healthStableWindowMs,
+    });
+    if (healthLogDecision === 'stable') {
+      runtime.hooks.logInfo(
+        'health',
+        `status-tick ${accountId}|stable|${connected ? 'linked' : 'configured'}|onlineByConn=${onlineByConn}|recentInboundReachable=${recentInboundReachable}|conns=${conns}`,
+      );
+    }
     runtime.hooks.logInfoDedup('health', `status-tick ${healthSig}`, {
       key: `health-status-tick-debug:${accountId}`,
       sig: healthSig,
@@ -111,9 +170,7 @@ export async function startBncrStatusWorker(
     });
   };
 
-  tick();
   const timer = setInterval(tick, 5_000);
-  let worker!: ChannelAccountWorkerHandle;
   const done = new Promise<void>((resolve) => {
     let settled = false;
     const finish = (reason: string) => {
@@ -135,9 +192,11 @@ export async function startBncrStatusWorker(
       resolve();
     };
 
-    worker = { timer, finish };
+    worker = { timer, finish, healthLogState: createHealthStatusLogState() };
     runtime.workers.set(accountId, worker);
 
+    tick();
+
     const onAbort = () => finish('abort');
     const abortSignal = ctx.abortSignal;