@xmoxmo/bncr 0.3.5 → 0.3.7

package/src/plugin/outbox-route.ts

@@ -0,0 +1,181 @@
+import { normalizeAccountId } from '../core/accounts.ts';
+import {
+  isEligibleOutboundPushConnection,
+  selectOrderedOutboundPushConnections,
+} from '../core/connection-reachability.ts';
+import type { BncrConnection } from '../core/types.ts';
+
+type BncrConnectionWithOutboundHints = BncrConnection & {
+  outboundReadyUntil?: number;
+  preferredForOutboundUntil?: number;
+};
+
+export type BncrOutboxRouteRuntime = {
+  bridgeId: string;
+  now: () => number;
+  connectTtlMs: number;
+  finiteNumberOr: (value: unknown, fallback: number) => number;
+  connections: Map<string, BncrConnection>;
+  activeConnectionByAccount: Map<string, string>;
+  resolveRecentInboundConnIds: (accountId: string) => Set<string>;
+  connectionKey: (accountId: string, clientId?: string) => string;
+  logInfo: (scope: string, message: string, options?: { debugOnly?: boolean }) => void;
+  buildActiveConnectionDebugList: (
+    accountId: string,
+    options?: { includeOutboundState?: boolean },
+  ) => unknown;
+};
+
+export function createBncrOutboxRoute(runtime: BncrOutboxRouteRuntime) {
+  const resolveOutboxPushOwner = (accountId: string): BncrConnectionWithOutboundHints | null => {
+    const acc = normalizeAccountId(accountId);
+    const t = runtime.now();
+    const primaryKey = runtime.activeConnectionByAccount.get(acc);
+    const primary = primaryKey
+      ? ((runtime.connections.get(primaryKey) as BncrConnectionWithOutboundHints | undefined) ??
+        null)
+      : null;
+
+    const recentInboundConnIds = runtime.resolveRecentInboundConnIds(acc);
+
+    if (primary) {
+      if (
+        isEligibleOutboundPushConnection({
+          connection: primary,
+          now: t,
+          connectTtlMs: runtime.connectTtlMs,
+        })
+      ) {
+        const preferredForOutboundUntil = runtime.finiteNumberOr(
+          primary.preferredForOutboundUntil,
+          0,
+        );
+        const outboundReadyUntil = runtime.finiteNumberOr(primary.outboundReadyUntil, 0);
+        if (preferredForOutboundUntil > t || outboundReadyUntil > t) return primary;
+      }
+    }
+
+    const candidates = selectOrderedOutboundPushConnections({
+      accountId: acc,
+      now: t,
+      connectTtlMs: runtime.connectTtlMs,
+      recentInboundConnIds,
+      connections: runtime.connections.values(),
+    });
+
+    const next = (candidates[0] as BncrConnectionWithOutboundHints | undefined) || null;
+    if (!next) return null;
+
+    const nextKey = runtime.connectionKey(acc, next.clientId);
+    if (primaryKey !== nextKey) {
+      runtime.activeConnectionByAccount.set(acc, nextKey);
+      runtime.logInfo(
+        'connection',
+        `owner:promote ${JSON.stringify({
+          bridge: runtime.bridgeId,
+          accountId: acc,
+          previousActiveKey: primaryKey || null,
+          previousActiveConn: primary || null,
+          nextActiveKey: nextKey,
+          nextActiveConn: {
+            connId: next.connId,
+            clientId: next.clientId,
+            connectedAt: next.connectedAt,
+            lastSeenAt: next.lastSeenAt,
+            outboundReadyUntil: next.outboundReadyUntil || null,
+            preferredForOutboundUntil: next.preferredForOutboundUntil || null,
+            inboundOnly: next.inboundOnly === true,
+          },
+          reason: 'better-outbound-candidate',
+        })}`,
+        { debugOnly: true },
+      );
+    }
+
+    return next;
+  };
+
+  const resolvePushConnIds = (accountId: string): Set<string> => {
+    const acc = normalizeAccountId(accountId);
+    const t = runtime.now();
+    const connIds = new Set<string>();
+
+    const recentInboundConnIds = runtime.resolveRecentInboundConnIds(acc);
+
+    const primaryKey = runtime.activeConnectionByAccount.get(acc);
+    if (primaryKey) {
+      const primary = runtime.connections.get(primaryKey) ?? null;
+      if (
+        primary &&
+        isEligibleOutboundPushConnection({
+          connection: primary,
+          now: t,
+          connectTtlMs: runtime.connectTtlMs,
+        })
+      ) {
+        connIds.add(primary.connId);
+      }
+    }
+
+    const candidates = selectOrderedOutboundPushConnections({
+      accountId: acc,
+      now: t,
+      connectTtlMs: runtime.connectTtlMs,
+      recentInboundConnIds,
+      connections: runtime.connections.values(),
+    });
+
+    for (const c of candidates) {
+      connIds.add(c.connId);
+    }
+
+    if (connIds.size > 0) return connIds;
+
+    for (const c of runtime.connections.values()) {
+      if (c.accountId !== acc) continue;
+      if (!c.connId) continue;
+      if (t - c.lastSeenAt > runtime.connectTtlMs) continue;
+      connIds.add(c.connId);
+    }
+
+    return connIds;
+  };
+
+  const buildTransferRouteDiagnostics = (args: {
+    accountId: string;
+    recentInboundReachable: boolean;
+  }) => {
+    const directConnIds = resolvePushConnIds(args.accountId);
+    const recentConnIds = args.recentInboundReachable
+      ? runtime.resolveRecentInboundConnIds(args.accountId)
+      : new Set<string>();
+    const activeConnectionKey = runtime.activeConnectionByAccount.get(args.accountId) || null;
+    const accountConnections = runtime.buildActiveConnectionDebugList(args.accountId);
+
+    return {
+      directConnIds,
+      recentConnIds,
+      activeConnectionKey,
+      accountConnections,
+    };
+  };
+
+  const selectTransferConnIds = (args: {
+    directConnIds: Set<string>;
+    recentConnIds: Set<string>;
+    recentInboundReachable: boolean;
+  }) => {
+    let connIds = args.directConnIds;
+    if (!connIds.size && args.recentInboundReachable) {
+      connIds = args.recentConnIds;
+    }
+    return connIds;
+  };
+
+  return {
+    resolveOutboxPushOwner,
+    resolvePushConnIds,
+    buildTransferRouteDiagnostics,
+    selectTransferConnIds,
+  };
+}

package/src/plugin/outbox-text-push-flow.ts

@@ -0,0 +1,90 @@
+import { resolveTextPushGuard } from '../core/outbox-text-push-guards.ts';
+import { prepareTextPushRouteSelection } from '../core/outbox-text-push-prep.ts';
+import type { BncrConnection, OutboxEntry } from '../core/types.ts';
+import { selectOutboxRouteCandidates } from '../messaging/outbound/queue-selectors.ts';
+
+export async function runBncrTextOutboxPush(args: {
+  entry: OutboxEntry;
+  gatewayContext: unknown;
+  owner: BncrConnection | null;
+  resolvePushConnIds: (accountId: string) => Set<string>;
+  resolveRecentInboundConnIds: (accountId: string) => Set<string>;
+  hasRecentInboundReachability: (accountId: string) => boolean;
+  isRevalidatedAttemptedConn: (connId: string) => boolean;
+  recordOutboxPrePushFailure: (args: {
+    entry: OutboxEntry;
+    lastError: string;
+    persist?: boolean;
+  }) => void;
+  logOutboxPushSkip: (args: {
+    messageId: string;
+    accountId: string;
+    reason: string;
+    recentInboundReachable?: boolean;
+    routeReason?: string;
+    connIds?: Iterable<string>;
+    ownerConnId?: string;
+    ownerClientId?: string;
+  }) => void;
+  pushTextSuccessPath: (args: {
+    entry: OutboxEntry;
+    owner: BncrConnection | null;
+    connIds: Iterable<string>;
+    recentInboundReachable: boolean;
+    routeReason: string;
+    ownerConnId?: string;
+  }) => void;
+  handleTextPushFailure: (args: { entry: OutboxEntry; error: unknown }) => void;
+}) {
+  const selection = prepareTextPushRouteSelection({
+    entry: args.entry,
+    owner: args.owner,
+    resolvePushConnIds: args.resolvePushConnIds,
+    resolveRecentInboundConnIds: args.resolveRecentInboundConnIds,
+    hasRecentInboundReachability: args.hasRecentInboundReachability,
+    isRevalidatedAttemptedConn: args.isRevalidatedAttemptedConn,
+    selectOutboxRouteCandidates,
+  });
+  const guard = resolveTextPushGuard({
+    gatewayContext: args.gatewayContext,
+    entry: args.entry,
+    routeSelection: selection,
+  });
+  if (!guard.ok) {
+    args.recordOutboxPrePushFailure({
+      entry: args.entry,
+      lastError:
+        guard.reason === 'no-gateway-context'
+          ? 'gateway context unavailable'
+          : 'no active bncr client',
+      persist: true,
+    });
+    args.logOutboxPushSkip({
+      messageId: args.entry.messageId,
+      accountId: args.entry.accountId,
+      reason: guard.reason,
+      recentInboundReachable:
+        guard.reason === 'no-active-connection' ? guard.recentInboundReachable : undefined,
+      routeReason: selection.routeReason,
+      connIds: selection.connIds,
+      ownerConnId: selection.ownerConnId,
+      ownerClientId: args.owner?.clientId,
+    });
+    return false;
+  }
+
+  try {
+    args.pushTextSuccessPath({
+      entry: args.entry,
+      owner: args.owner,
+      connIds: guard.connIds,
+      recentInboundReachable: guard.recentInboundReachable,
+      routeReason: guard.routeReason,
+      ownerConnId: guard.ownerConnId,
+    });
+    return true;
+  } catch (error) {
+    args.handleTextPushFailure({ entry: args.entry, error });
+    return false;
+  }
+}

package/src/plugin/runtime-diagnostics-assembler.ts

@@ -0,0 +1,183 @@
+import type { BncrExtendedDiagnostics } from '../core/extended-diagnostics.ts';
+import { buildExtendedDiagnostics as buildExtendedDiagnosticsFromRuntime } from '../core/extended-diagnostics.ts';
+import type {
+  RegisterDriftSnapshot,
+  RegisterTraceEntry,
+  RegisterTraceSummary,
+} from '../core/register-trace.ts';
+import { buildExtendedOutboundDiagnostics } from '../messaging/outbound/diagnostics.ts';
+import type {
+  buildBncrDeadLetterDiagnosticsSnapshot,
+  ExtendedDiagnosticsAssemblerOptions,
+  ExtendedDiagnosticsAssemblerRuntime,
+} from './runtime-diagnostics-helpers.ts';
+import {
+  buildBncrExtendedConnectionDiagnostics,
+  buildBncrExtendedOutboundDiagnosticsInput,
+  buildBncrExtendedRegisterDiagnostics,
+} from './runtime-diagnostics-payload-builders.ts';
+
+export function createBncrExtendedDiagnosticsAssembler(
+  runtime: ExtendedDiagnosticsAssemblerRuntime,
+) {
+  return (
+    accountId: string,
+    options: ExtendedDiagnosticsAssemblerOptions = {},
+  ): BncrExtendedDiagnostics => {
+    const acc = runtime.normalizeAccountId(accountId);
+    const diagnostics =
+      options.integratedDiagnostics ||
+      runtime.buildIntegratedDiagnostics(acc, options.runtimeStatusInput);
+    const outboxDiagnostics = runtime.buildOutboxDiagnostics(acc);
+    const ackObservability = runtime.buildRuntimeAckObservability(acc);
+    const prePushGuardSkipCount = runtime.getCounter(runtime.prePushGuardSkipCountByAccount, acc);
+    const lastPrePushGuardSkipAt = runtime.lastPrePushGuardSkipAtByAccount.get(acc) || null;
+    const lastPrePushGuardSkipReason = runtime.lastPrePushGuardSkipReasonByAccount.get(acc) || null;
+    const hasGatewayContext = runtime.hasGatewayContext();
+    const registerRuntime = runtime.getRegisterRuntime();
+    const connectionRuntime = runtime.getConnectionRuntime();
+    const outboundRuntime = runtime.getOutboundRuntime();
+
+    return buildBncrExtendedDiagnosticsSnapshot({
+      diagnostics,
+      runtimeSurface: runtime.buildRuntimeSurfaceDiagnostics(),
+      register: buildBncrExtendedRegisterDiagnostics({
+        bridgeId: registerRuntime.bridgeId,
+        gatewayPid: registerRuntime.gatewayPid,
+        pluginVersion: registerRuntime.pluginVersion,
+        source: registerRuntime.pluginSource,
+        apiInstanceId: registerRuntime.lastApiInstanceId,
+        registryFingerprint: registerRuntime.lastRegistryFingerprint,
+        registerCount: registerRuntime.registerCount,
+        firstRegisterAt: registerRuntime.firstRegisterAt,
+        lastRegisterAt: registerRuntime.lastRegisterAt,
+        lastApiRebindAt: registerRuntime.lastApiRebindAt,
+        apiGeneration: registerRuntime.apiGeneration,
+        traceRecent: registerRuntime.registerTraceRecent,
+        traceSummary: runtime.buildRegisterTraceSummary(),
+        lastDriftSnapshot: registerRuntime.lastDriftSnapshot ?? null,
+      }),
+      connection: buildBncrExtendedConnectionDiagnostics({
+        active: runtime.activeConnectionCount(acc),
+        hasGatewayContext,
+        lastGatewayContextAt: connectionRuntime.lastGatewayContextAt,
+        primaryLeaseId: connectionRuntime.primaryLeaseId,
+        primaryEpoch: connectionRuntime.connectionEpoch || null,
+        acceptedConnections: connectionRuntime.acceptedConnections,
+        lastConnectAt: connectionRuntime.lastConnectAt,
+        lastDisconnectAt: connectionRuntime.lastDisconnectAt,
+        lastActivityAt: connectionRuntime.lastActivityAtGlobal,
+        lastInboundAt: connectionRuntime.lastInboundAtGlobal,
+        lastAckAt: connectionRuntime.lastAckAtGlobal,
+        recentConnections: connectionRuntime.recentConnections,
+      }),
+      outbound: buildBncrExtendedOutboundDiagnosticsInput({
+        outbox: outboxDiagnostics,
+        enqueueCount: runtime.getCounter(outboundRuntime.outboundEnqueueCountByAccount, acc),
+        lastEnqueueAt: outboundRuntime.lastOutboundEnqueueAtByAccount.get(acc) || null,
+        prePushGuardSkipCount,
+        lastPrePushGuardSkipAt,
+        lastPrePushGuardSkipReason,
+        hasGatewayContext,
+        lastGatewayContextAt: connectionRuntime.lastGatewayContextAt,
+        ackObservability,
+        nowMs: runtime.now(),
+      }),
+      deadLetterSummary: runtime.buildDeadLetterDiagnostics(acc),
+      protocol: {
+        bridgeVersion: runtime.bridgeVersion,
+        protocolVersion: 2,
+        minClientProtocol: 1,
+        features: {
+          leaseId: true,
+          connectionEpoch: true,
+          staleObserveOnly: true,
+          staleRejectAck: false,
+          staleRejectFile: false,
+        },
+      },
+      stale: runtime.staleCounters,
+      nowMs: runtime.now(),
+    });
+  };
+}
+
+export function buildBncrExtendedDiagnosticsSnapshot(args: {
+  diagnostics: import('../core/types.ts').BncrDiagnosticsSummary;
+  runtimeSurface: ReturnType<
+    typeof import('../openclaw/runtime-surface.ts')['buildOpenClawChannelRuntimeSurfaceDiagnostics']
+  >;
+  register: {
+    bridgeId: string;
+    gatewayPid: number;
+    pluginVersion: string | null;
+    source: string | null;
+    apiInstanceId: string | null;
+    registryFingerprint: string | null;
+    registerCount: number;
+    firstRegisterAt: number | null;
+    lastRegisterAt: number | null;
+    lastApiRebindAt: number | null;
+    apiGeneration: number;
+    traceRecent: RegisterTraceEntry[];
+    traceSummary: RegisterTraceSummary;
+    lastDriftSnapshot: RegisterDriftSnapshot | null;
+  };
+  connection: {
+    active: number;
+    hasGatewayContext: boolean;
+    lastGatewayContextAt: number | null;
+    primaryLeaseId: string | null;
+    primaryEpoch: number | null;
+    acceptedConnections: number;
+    lastConnectAt: number | null;
+    lastDisconnectAt: number | null;
+    lastActivityAt: number | null;
+    lastInboundAt: number | null;
+    lastAckAt: number | null;
+    recent: Array<{
+      leaseId: string;
+      epoch: number;
+      connectedAt: number;
+      lastActivityAt: number | null;
+      isPrimary: boolean;
+    }>;
+  };
+  outbound: Parameters<typeof buildExtendedOutboundDiagnostics>[0];
+  deadLetterSummary: ReturnType<typeof buildBncrDeadLetterDiagnosticsSnapshot>;
+  protocol: {
+    bridgeVersion: number;
+    protocolVersion: number;
+    minClientProtocol: number;
+    features: {
+      leaseId: boolean;
+      connectionEpoch: boolean;
+      staleObserveOnly: boolean;
+      staleRejectAck: boolean;
+      staleRejectFile: boolean;
+    };
+  };
+  stale: {
+    staleConnect: number;
+    staleInbound: number;
+    staleActivity: number;
+    staleAck: number;
+    staleFileInit: number;
+    staleFileChunk: number;
+    staleFileComplete: number;
+    staleFileAbort: number;
+    lastStaleAt: number | null;
+  };
+  nowMs: number;
+}): BncrExtendedDiagnostics {
+  return buildExtendedDiagnosticsFromRuntime({
+    diagnostics: args.diagnostics,
+    runtimeSurface: args.runtimeSurface,
+    register: args.register,
+    connection: args.connection,
+    outbound: buildExtendedOutboundDiagnostics(args.outbound),
+    deadLetterSummary: args.deadLetterSummary,
+    protocol: args.protocol,
+    stale: args.stale,
+  });
+}