@xmoxmo/bncr 0.2.3 → 0.2.5

package/src/core/connection-capability.ts

@@ -0,0 +1,70 @@
+import type { BncrConnection } from './types.ts';
+
+type CapabilityConnection = BncrConnection & {
+  outboundReadyUntil?: number;
+  preferredForOutboundUntil?: number;
+  inboundOnly?: boolean;
+  lastAckOkAt?: number;
+  lastPushTimeoutAt?: number;
+};
+
+export function applyOutboundCapability(args: {
+  connection: CapabilityConnection;
+  at: number;
+  outboundReadyTtlMs: number;
+  preferredOutboundTtlMs: number;
+  outboundReady?: boolean;
+  preferredForOutbound?: boolean;
+  inboundOnly?: boolean;
+}) {
+  const next: CapabilityConnection = { ...args.connection };
+
+  if (args.inboundOnly === true) {
+    next.inboundOnly = true;
+    next.outboundReadyUntil = undefined;
+    next.preferredForOutboundUntil = undefined;
+  } else {
+    if (typeof args.inboundOnly === 'boolean') next.inboundOnly = false;
+    if (args.outboundReady === true || args.preferredForOutbound === true) {
+      next.outboundReadyUntil = args.at + args.outboundReadyTtlMs;
+    }
+    if (args.preferredForOutbound === true) {
+      next.preferredForOutboundUntil = args.at + args.preferredOutboundTtlMs;
+    }
+  }
+
+  return next;
+}
+
+export function findCapabilityConnection(args: {
+  accountId: string;
+  connId?: string;
+  clientId?: string;
+  connections: Iterable<[string, BncrConnection]>;
+}) {
+  for (const [key, conn] of args.connections) {
+    if (conn.accountId !== args.accountId) continue;
+    if (args.connId && conn.connId !== args.connId) continue;
+    if (args.clientId && conn.clientId !== args.clientId) continue;
+    return {
+      key,
+      connection: conn as CapabilityConnection,
+    };
+  }
+  return null;
+}
+
+export function buildCapabilitySnapshot(connection: CapabilityConnection) {
+  return {
+    outboundReadyUntil: connection.outboundReadyUntil || null,
+    preferredForOutboundUntil: connection.preferredForOutboundUntil || null,
+    inboundOnly: connection.inboundOnly === true,
+  };
+}
+
+export function clearOutboundCapability(connection: CapabilityConnection) {
+  const next: CapabilityConnection = { ...connection };
+  next.outboundReadyUntil = undefined;
+  next.preferredForOutboundUntil = undefined;
+  return next;
+}

package/src/core/connection-reachability.ts

@@ -0,0 +1,141 @@
+import type { BncrConnection, OutboxEntry } from './types.ts';
+
+export function hasRecentInboundReachability(args: {
+  now: number;
+  windowMs: number;
+  lastInboundAt: number;
+  lastActivityAt: number;
+}) {
+  const lastReachableAt = Math.max(args.lastInboundAt, args.lastActivityAt);
+  return lastReachableAt > 0 && args.now - lastReachableAt <= args.windowMs;
+}
+
+export function resolveRecentInboundConnIds(args: {
+  accountId: string;
+  now: number;
+  connectTtlMs: number;
+  recentInboundReachable: boolean;
+  connections: Iterable<BncrConnection>;
+}) {
+  const connIds = new Set<string>();
+  if (!args.recentInboundReachable) return connIds;
+
+  for (const c of args.connections) {
+    if (c.accountId !== args.accountId) continue;
+    if (!c.connId) continue;
+    if (args.now - c.lastSeenAt > args.connectTtlMs * 2) continue;
+    connIds.add(c.connId);
+  }
+
+  return connIds;
+}
+
+export function isRecentlyReachableConn(args: {
+  accountId: string;
+  connId?: string;
+  clientId?: string;
+  recentConnIds: Set<string>;
+  activeConnection?: BncrConnection | null;
+}) {
+  const cid = String(args.connId || '').trim();
+  const client = String(args.clientId || '').trim() || undefined;
+  if (!cid) return false;
+  if (args.recentConnIds.has(cid)) return true;
+
+  const active = args.activeConnection;
+  if (!active?.connId) return false;
+  if (active.accountId !== args.accountId) return false;
+  if (active.connId !== cid) return false;
+  if (client && active.clientId && active.clientId !== client) return false;
+  return true;
+}
+
+export function hasAlternativeLiveConnection(args: {
+  accountId: string;
+  now: number;
+  connectTtlMs: number;
+  currentConnId?: string;
+  currentClientId?: string;
+  connections: Iterable<BncrConnection>;
+}) {
+  const currentConn = String(args.currentConnId || '').trim();
+  const currentClient = String(args.currentClientId || '').trim() || undefined;
+
+  for (const conn of args.connections) {
+    if (conn.accountId !== args.accountId) continue;
+    if (!conn.connId) continue;
+    if (args.now - conn.lastSeenAt > args.connectTtlMs) continue;
+    const sameConn = !!currentConn && conn.connId === currentConn;
+    const sameClient = !currentConn && !!currentClient && conn.clientId === currentClient;
+    if (sameConn || sameClient) continue;
+    return true;
+  }
+  return false;
+}
+
+type ReachableConnection = BncrConnection & {
+  inboundOnly?: boolean;
+  preferredForOutboundUntil?: number;
+  outboundReadyUntil?: number;
+  lastAckOkAt?: number;
+  lastPushTimeoutAt?: number;
+};
+
+export function getRevalidatedAttemptReason(args: {
+  entry: OutboxEntry;
+  connId: string;
+  accountId: string;
+  now: number;
+  connectTtlMs: number;
+  recentInboundReachable: boolean;
+  connections: Iterable<BncrConnection>;
+}) {
+  const targetConnId = String(args.connId || '').trim();
+  if (!targetConnId) return null;
+
+  const lastAttemptAt = Number(args.entry.lastAttemptAt || 0);
+  for (const rawConn of args.connections) {
+    const conn = rawConn as ReachableConnection;
+    if (conn.accountId !== args.accountId) continue;
+    if (conn.connId !== targetConnId) continue;
+    if (args.now - conn.lastSeenAt > args.connectTtlMs) continue;
+    if (conn.inboundOnly === true) continue;
+
+    const preferredForOutboundUntil = Number(conn.preferredForOutboundUntil || 0);
+    const outboundReadyUntil = Number(conn.outboundReadyUntil || 0);
+    const lastAckOkAt = Number(conn.lastAckOkAt || 0);
+    const lastPushTimeoutAt = Number(conn.lastPushTimeoutAt || 0);
+
+    const revalidatedByPreferred = preferredForOutboundUntil > args.now;
+    const revalidatedByReady = outboundReadyUntil > args.now;
+    const revalidatedByAck = lastAckOkAt > 0 && lastAckOkAt > lastAttemptAt;
+    const revalidatedByFreshReachability =
+      args.recentInboundReachable &&
+      lastPushTimeoutAt > 0 &&
+      lastPushTimeoutAt <= lastAttemptAt &&
+      conn.lastSeenAt > lastPushTimeoutAt;
+
+    if (!revalidatedByPreferred && !revalidatedByReady && !revalidatedByAck && !revalidatedByFreshReachability) {
+      return null;
+    }
+
+    return {
+      reason: revalidatedByAck
+        ? 'ack-after-last-attempt'
+        : revalidatedByPreferred
+          ? 'preferred-ttl'
+          : revalidatedByReady
+            ? 'ready-ttl'
+            : 'fresh-reachability',
+      lastAttemptAt,
+      lastAckOkAt: lastAckOkAt || null,
+      lastPushTimeoutAt: lastPushTimeoutAt || null,
+      outboundReadyUntil: outboundReadyUntil || null,
+      preferredForOutboundUntil: preferredForOutboundUntil || null,
+      lastSeenAt: conn.lastSeenAt,
+      recentInboundReachable: args.recentInboundReachable,
+    };
+  }
+
+  return null;
+}

package/src/core/diagnostics.ts

@@ -0,0 +1,49 @@
+import { buildBncrPermissionSummary } from './permissions.ts';
+import { probeBncrAccount } from './probe.ts';
+
+type DiagnosticsPayloadArgs = {
+  cfg: any;
+  channelId: string;
+  accountId: string;
+  runtime: any;
+  diagnostics: any;
+  downlinkHealth: any;
+  runtimeFlags: any;
+  waiters: { messageAck: number; fileAck: number };
+  activeConnections: number;
+  invalidOutboxSessionKeys: number;
+  legacyAccountResidue: number;
+  now: number;
+};
+
+export function buildDiagnosticsPayload(args: DiagnosticsPayloadArgs) {
+  const permissions = buildBncrPermissionSummary(args.cfg ?? {});
+  const probe = probeBncrAccount({
+    accountId: args.accountId,
+    connected: Boolean(args.runtime?.connected),
+    pending: Number(args.runtime?.meta?.pending ?? 0),
+    deadLetter: Number(args.runtime?.meta?.deadLetter ?? 0),
+    activeConnections: args.activeConnections,
+    invalidOutboxSessionKeys: args.invalidOutboxSessionKeys,
+    legacyAccountResidue: args.legacyAccountResidue,
+    lastActivityAt: args.runtime?.meta?.lastActivityAt ?? null,
+    structure: {
+      coreComplete: true,
+      inboundComplete: true,
+      outboundComplete: true,
+    },
+  });
+
+  return {
+    channel: args.channelId,
+    accountId: args.accountId,
+    runtime: args.runtime,
+    diagnostics: args.diagnostics,
+    downlinkHealth: args.downlinkHealth,
+    runtimeFlags: args.runtimeFlags,
+    waiters: args.waiters,
+    permissions,
+    probe,
+    now: args.now,
+  };
+}

package/src/core/downlink-health.ts

@@ -0,0 +1,56 @@
+import type { OutboxEntry } from './types.ts';
+
+type DownlinkHealthInput = {
+  accountId: string;
+  now: number;
+  outboxEntries: Iterable<OutboxEntry>;
+  lastAckOkAt: number | null;
+  lastAckTimeoutAt: number | null;
+  recentAckTimeoutCount: number;
+  activeConnectionCount: number;
+  lastInboundAt: number | null;
+  lastActivityAt: number | null;
+  onlineByConn: boolean;
+};
+
+export function buildDownlinkHealth(input: DownlinkHealthInput) {
+  const pending = Array.from(input.outboxEntries).filter((v) => v.accountId === input.accountId);
+  const pendingCount = pending.length;
+  const oldestPendingCreatedAt = pending.length
+    ? Math.min(...pending.map((entry) => Number(entry.createdAt || input.now)))
+    : null;
+  const oldestPendingAgeMs = oldestPendingCreatedAt
+    ? Math.max(0, input.now - oldestPendingCreatedAt)
+    : 0;
+  const lastSignalAt =
+    Math.max(Number(input.lastInboundAt || 0), Number(input.lastActivityAt || 0)) || null;
+  const inboundHealthy = !!lastSignalAt && input.now - lastSignalAt <= 5 * 60 * 1000;
+  const ackRecentlyHealthy =
+    !!input.lastAckOkAt && input.now - input.lastAckOkAt <= 5 * 60 * 1000;
+  const ackTimeoutRecent =
+    !!input.lastAckTimeoutAt && input.now - input.lastAckTimeoutAt <= 5 * 60 * 1000;
+  const ackStalled =
+    pendingCount > 0 &&
+    input.activeConnectionCount === 1 &&
+    inboundHealthy &&
+    ackTimeoutRecent &&
+    input.recentAckTimeoutCount > 0 &&
+    !ackRecentlyHealthy;
+
+  return {
+    pendingOutbox: pendingCount,
+    oldestPendingCreatedAt,
+    oldestPendingAgeMs,
+    lastAckOkAt: input.lastAckOkAt,
+    lastAckTimeoutAt: input.lastAckTimeoutAt,
+    recentAckTimeoutCount: input.recentAckTimeoutCount,
+    activeConnectionCount: input.activeConnectionCount,
+    recentInboundReachable: inboundHealthy,
+    onlineByConn: input.onlineByConn,
+    ackStalled,
+    recommendReconnect: ackStalled,
+    recommendReason: ackStalled
+      ? 'single-conn pending outbox with recent ack timeout and no recent ack-ok while inbound/activity is still alive'
+      : '',
+  };
+}

package/src/core/extended-diagnostics.ts

@@ -0,0 +1,65 @@
+import type { RegisterTraceEntry } from './register-trace.ts';
+
+type ExtendedDiagnosticsInput = {
+  diagnostics: Record<string, any>;
+  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: Record<string, any>;
+    lastDriftSnapshot: any;
+  };
+  connection: {
+    active: number;
+    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;
+    }>;
+  };
+  protocol: {
+    bridgeVersion: number;
+    protocolVersion: number;
+    minClientProtocol: number;
+    features: Record<string, boolean>;
+  };
+  stale: Record<string, any>;
+};
+
+export function buildExtendedDiagnostics(input: ExtendedDiagnosticsInput) {
+  return {
+    ...input.diagnostics,
+    register: {
+      ...input.register,
+      traceRecent: input.register.traceRecent.slice(),
+    },
+    connection: {
+      ...input.connection,
+      recent: input.connection.recent.map((entry) => ({ ...entry })),
+    },
+    protocol: {
+      ...input.protocol,
+      features: { ...input.protocol.features },
+    },
+    stale: { ...input.stale },
+  };
+}

package/src/core/lease-state.ts

@@ -0,0 +1,94 @@
+export type LeaseEventKind =
+  | 'connect'
+  | 'inbound'
+  | 'activity'
+  | 'ack'
+  | 'file.init'
+  | 'file.chunk'
+  | 'file.complete'
+  | 'file.abort';
+
+export type LeaseObservationReason = 'missing' | 'ok' | 'mismatch';
+
+export type LeaseObservationResult = {
+  stale: boolean;
+  reason: LeaseObservationReason;
+};
+
+export type StaleCounters = {
+  staleConnect: number;
+  staleInbound: number;
+  staleActivity: number;
+  staleAck: number;
+  staleFileInit: number;
+  staleFileChunk: number;
+  staleFileComplete: number;
+  staleFileAbort: number;
+  lastStaleAt: number | null;
+};
+
+export function observeLeaseState(args: {
+  kind: LeaseEventKind;
+  params: { leaseId?: string; connectionEpoch?: number };
+  currentLeaseId: string | null;
+  currentConnectionEpoch: number;
+  now: number;
+  staleCounters: StaleCounters;
+}): LeaseObservationResult {
+  const leaseId = typeof args.params.leaseId === 'string' ? args.params.leaseId.trim() : '';
+  const connectionEpoch =
+    typeof args.params.connectionEpoch === 'number' ? args.params.connectionEpoch : undefined;
+  if (!leaseId && connectionEpoch == null) return { stale: false, reason: 'missing' };
+
+  const staleByLease = !!leaseId && args.currentLeaseId != null && leaseId !== args.currentLeaseId;
+  const staleByEpoch =
+    connectionEpoch != null &&
+    args.currentConnectionEpoch > 0 &&
+    connectionEpoch !== args.currentConnectionEpoch;
+  const stale = staleByLease || staleByEpoch;
+  if (!stale) return { stale: false, reason: 'ok' };
+
+  args.staleCounters.lastStaleAt = args.now;
+  switch (args.kind) {
+    case 'connect':
+      args.staleCounters.staleConnect += 1;
+      break;
+    case 'inbound':
+      args.staleCounters.staleInbound += 1;
+      break;
+    case 'activity':
+      args.staleCounters.staleActivity += 1;
+      break;
+    case 'ack':
+      args.staleCounters.staleAck += 1;
+      break;
+    case 'file.init':
+      args.staleCounters.staleFileInit += 1;
+      break;
+    case 'file.chunk':
+      args.staleCounters.staleFileChunk += 1;
+      break;
+    case 'file.complete':
+      args.staleCounters.staleFileComplete += 1;
+      break;
+    case 'file.abort':
+      args.staleCounters.staleFileAbort += 1;
+      break;
+  }
+  return { stale: true, reason: 'mismatch' };
+}
+
+export function matchesTransferOwner(args: {
+  ownerConnId?: string;
+  ownerClientId?: string;
+  connId: string;
+  clientId?: string;
+}) {
+  const sameConn = !!args.ownerConnId && args.ownerConnId === args.connId;
+  const sameClient =
+    !args.ownerConnId &&
+    !!args.ownerClientId &&
+    !!args.clientId &&
+    args.ownerClientId === args.clientId;
+  return sameConn || sameClient;
+}

package/src/core/outbox-enqueue.ts

@@ -0,0 +1,22 @@
+import type { OutboxEntry } from './types.ts';
+
+export function buildOutboxEnqueueDebugInfo(args: {
+  bridgeId: string;
+  entry: OutboxEntry;
+  asString: (value: unknown) => string;
+  formatDisplayScope: (route: OutboxEntry['route']) => string;
+}) {
+  const msg = (args.entry.payload as any)?.message || {};
+  const type = args.asString(msg.type || (args.entry.payload as any)?.type || 'unknown');
+  const text = args.asString(msg.msg || '');
+  return {
+    bridge: args.bridgeId,
+    messageId: args.entry.messageId,
+    accountId: args.entry.accountId,
+    sessionKey: args.entry.sessionKey,
+    scope: args.formatDisplayScope(args.entry.route),
+    type,
+    textLen: text.length,
+    textPreview: text.slice(0, 120),
+  };
+}

package/src/core/outbox-entry-builders.ts

@@ -0,0 +1,91 @@
+import type { BncrRoute, OutboxEntry } from './types.ts';
+
+export function buildFileTransferOutboxEntry(args: {
+  createMessageId: () => string;
+  now: () => number;
+  normalizeAccountId: (accountId?: string | null) => string;
+  pushEvent: string;
+  accountId: string;
+  sessionKey: string;
+  route: BncrRoute;
+  mediaUrl: string;
+  mediaLocalRoots?: readonly string[];
+  text: string;
+  asVoice?: boolean;
+  audioAsVoice?: boolean;
+  kind?: 'tool' | 'block' | 'final';
+  replyToId?: string;
+}): OutboxEntry {
+  const messageId = args.createMessageId();
+  const createdAt = args.now();
+  return {
+    messageId,
+    accountId: args.normalizeAccountId(args.accountId),
+    sessionKey: args.sessionKey,
+    route: args.route,
+    payload: {
+      type: 'message.outbound',
+      sessionKey: args.sessionKey,
+      _meta: {
+        kind: 'file-transfer',
+        mediaUrl: args.mediaUrl,
+        mediaLocalRoots: args.mediaLocalRoots ? Array.from(args.mediaLocalRoots) : undefined,
+        text: args.text,
+        asVoice: args.asVoice === true,
+        audioAsVoice: args.audioAsVoice === true,
+        finalEvent: args.pushEvent,
+        replyToId: args.replyToId,
+        messageKind: args.kind,
+      },
+    },
+    createdAt,
+    retryCount: 0,
+    nextAttemptAt: createdAt,
+  };
+}
+
+export function buildTextOutboxEntry(args: {
+  createMessageId: () => string;
+  now: () => number;
+  normalizeAccountId: (accountId?: string | null) => string;
+  normalizeReplyToId: (value?: string | null) => string;
+  accountId: string;
+  sessionKey: string;
+  route: BncrRoute;
+  text: string;
+  kind?: 'tool' | 'block' | 'final';
+  replyToId?: string;
+}): OutboxEntry {
+  const messageId = args.createMessageId();
+  const createdAt = args.now();
+  const frame = {
+    type: 'message.outbound',
+    messageId,
+    idempotencyKey: messageId,
+    sessionKey: args.sessionKey,
+    replyToId: args.normalizeReplyToId(args.replyToId) || undefined,
+    message: {
+      platform: args.route.platform,
+      groupId: args.route.groupId,
+      userId: args.route.userId,
+      type: 'text',
+      kind: args.kind,
+      msg: args.text,
+      path: '',
+      base64: '',
+      fileName: '',
+    },
+    ts: createdAt,
+  };
+
+  return {
+    messageId,
+    accountId: args.normalizeAccountId(args.accountId),
+    sessionKey: args.sessionKey,
+    route: args.route,
+    payload: frame,
+    createdAt,
+    retryCount: 0,
+    nextAttemptAt: createdAt,
+  };
+}

package/src/core/outbox-file-transfer-bookkeeping.ts

@@ -0,0 +1,31 @@
+import type { BncrConnection, OutboxEntry } from './types.ts';
+import { buildPushOkArgs } from './outbox-push-args.ts';
+
+export function buildFileTransferPushSuccessArgs(args: {
+  entry: OutboxEntry;
+  connIds: Iterable<string>;
+  owner: BncrConnection | null;
+}) {
+  return {
+    entry: args.entry,
+    connIds: args.connIds,
+    ownerConnId: args.owner?.connId,
+    ownerClientId: args.owner?.clientId,
+    clearLastError: true,
+  };
+}
+
+export function buildFileTransferPushOkArgs(args: {
+  entry: OutboxEntry;
+  connIds: Iterable<string>;
+  recentInboundReachable: boolean;
+  event: string;
+}) {
+  return buildPushOkArgs({
+    entry: args.entry,
+    connIds: args.connIds,
+    recentInboundReachable: args.recentInboundReachable,
+    event: args.event,
+    kind: 'file-transfer',
+  });
+}

package/src/core/outbox-file-transfer-failure.ts

@@ -0,0 +1,25 @@
+import type { OutboxEntry } from './types.ts';
+import { buildPushFailureArgs } from './outbox-push-args.ts';
+
+export function resolveFileTransferFailureState(args: {
+  entry: OutboxEntry;
+  error: unknown;
+  isRetryableFileTransferError: (error: unknown) => boolean;
+}) {
+  const retryable = args.isRetryableFileTransferError(args.error);
+  return {
+    retryable,
+    deadLetterReason: args.entry.lastError || 'file-transfer-failed',
+  };
+}
+
+export function buildFileTransferPushFailureArgs(args: {
+  entry: OutboxEntry;
+  retryable: boolean;
+}) {
+  return buildPushFailureArgs({
+    entry: args.entry,
+    retryable: args.retryable,
+    kind: 'file-transfer',
+  });
+}