@meshconnect/uwc-core 1.2.3-snapshot.dcfdbbf → 1.3.0

package/src/observability/relay-drop-tracker.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest'
+import { EventManager } from '../managers/event-manager'
+import { trackRelayDropsDuringHandoff } from './relay-drop-tracker'
+
+describe('trackRelayDropsDuringHandoff', () => {
+  it('counts each relay drop seen during a WalletConnect handoff', () => {
+    const em = new EventManager()
+    const tracker = trackRelayDropsDuringHandoff(em, 'walletConnect')
+
+    expect(tracker.summary()).toEqual({ relayDropCount: 0 })
+
+    em.emit('relayDisconnected', undefined)
+    em.emit('relayDisconnected', undefined)
+    expect(tracker.summary()).toEqual({ relayDropCount: 2 })
+  })
+
+  it('reports undefined (not 0) off WalletConnect so the terminal omits the field', () => {
+    // A `0` on an injected handoff would read as "a relay we watched, and it
+    // held" — but no relay is in play, so the field must be absent entirely.
+    const em = new EventManager()
+    for (const mode of ['injected', 'tonConnect'] as const) {
+      const tracker = trackRelayDropsDuringHandoff(em, mode)
+      expect(tracker.summary()).toEqual({ relayDropCount: undefined })
+    }
+  })
+
+  it('does NOT subscribe off WalletConnect — a relay flap on the shared bus is ignored', () => {
+    const em = new EventManager()
+    const tracker = trackRelayDropsDuringHandoff(em, 'injected')
+
+    // The bus is client-global; a WC relay drop firing while an injected handoff
+    // is in flight must not be attributed to it.
+    em.emit('relayDisconnected', undefined)
+    em.emit('relayDisconnected', undefined)
+    expect(tracker.summary()).toEqual({ relayDropCount: undefined })
+  })
+
+  it('stops counting after stop() — drops outside the blind window do not accrue', () => {
+    const em = new EventManager()
+    const tracker = trackRelayDropsDuringHandoff(em, 'walletConnect')
+
+    em.emit('relayDisconnected', undefined)
+    tracker.stop()
+    em.emit('relayDisconnected', undefined)
+    em.emit('relayDisconnected', undefined)
+
+    expect(tracker.summary()).toEqual({ relayDropCount: 1 })
+  })
+
+  it('only counts relayDisconnected — reconnects and other bus events are ignored', () => {
+    const em = new EventManager()
+    const tracker = trackRelayDropsDuringHandoff(em, 'walletConnect')
+
+    em.emit('relayDisconnected', undefined)
+    em.emit('relayReconnected', undefined)
+    em.emit('relayReconnected', undefined)
+
+    expect(tracker.summary()).toEqual({ relayDropCount: 1 })
+  })
+
+  it('stop() is a safe no-op off WalletConnect (nothing was subscribed)', () => {
+    const em = new EventManager()
+    const tracker = trackRelayDropsDuringHandoff(em, 'tonConnect')
+    expect(() => tracker.stop()).not.toThrow()
+    expect(tracker.summary()).toEqual({ relayDropCount: undefined })
+  })
+
+  it('two concurrent WalletConnect handoffs count independently and unsubscribe independently', () => {
+    // The bus is shared; each tracker owns its own listener, so stopping one
+    // must not silence the other (and both saw the same drop).
+    const em = new EventManager()
+    const a = trackRelayDropsDuringHandoff(em, 'walletConnect')
+    const b = trackRelayDropsDuringHandoff(em, 'walletConnect')
+
+    em.emit('relayDisconnected', undefined)
+    expect(a.summary()).toEqual({ relayDropCount: 1 })
+    expect(b.summary()).toEqual({ relayDropCount: 1 })
+
+    a.stop()
+    em.emit('relayDisconnected', undefined)
+    expect(a.summary()).toEqual({ relayDropCount: 1 })
+    expect(b.summary()).toEqual({ relayDropCount: 2 })
+  })
+})

package/src/observability/relay-drop-tracker.ts

@@ -0,0 +1,53 @@
+import type { ConnectionMode } from '@meshconnect/uwc-types'
+import type { EventManager } from '../managers/event-manager'
+
+/** Handle returned by `trackRelayDropsDuringHandoff`. */
+export interface RelayDropHandoffTracker {
+  /**
+   * Remove the relay-drop subscription. Always call on settle (no-op off
+   * WalletConnect, where nothing was subscribed).
+   */
+  stop: () => void
+  /**
+   * Relay-drop count at call time, or `undefined` off WalletConnect. Undefined
+   * (not `0`) so the terminal's `compactUndefined` omits the field entirely — a
+   * `0` on an injected/TON handoff would falsely imply "a WC relay we watched,
+   * and it held", when in fact no relay was in play.
+   */
+  summary: () => { relayDropCount: number | undefined }
+}
+
+/**
+ * While a wallet handoff is pending, count relay-socket drops seen on the UWC
+ * event bus. The WalletConnect client emits `relayDisconnected` once per outage
+ * (see `attachRelayLifecycleListeners`); this is the CARE-263 signal — an
+ * iOS-suspended WebView drops the relay socket mid-handoff and strands the
+ * in-flight sign/connect response until WC core's slow heartbeat reconnects, so
+ * the drop count on a terminal explains a long/failed handoff that focus timing
+ * alone can't.
+ *
+ * WalletConnect ONLY. The relay bus is client-global, so an injected or TON
+ * handoff that happens to be in flight during a WC relay flap would otherwise
+ * misattribute the drop; off WalletConnect this is a no-op tracker whose
+ * `summary()` reports `undefined`. Mirrors `trackFocusDuringHandoff`: attach
+ * right after `awaitingWallet`, and `stop()` (called the instant the op settles)
+ * removes the subscription so drops are only counted during the blind window.
+ */
+export function trackRelayDropsDuringHandoff(
+  eventManager: EventManager,
+  connectionMode: ConnectionMode
+): RelayDropHandoffTracker {
+  if (connectionMode !== 'walletConnect') {
+    return { stop: () => {}, summary: () => ({ relayDropCount: undefined }) }
+  }
+
+  let relayDropCount = 0
+  const off = eventManager.on('relayDisconnected', () => {
+    relayDropCount++
+  })
+
+  return {
+    stop: off,
+    summary: () => ({ relayDropCount })
+  }
+}

package/src/observability/telemetry.test.ts

@@ -520,6 +520,24 @@ describe('normalizeEvent', () => {
     expect(JSON.stringify(out)).not.toContain('0xAbC123')
   })
 
+  it('normalizes relayDisconnected as an unclassified walletConnect signal (void, no reason)', () => {
+    // The relayer carries no payload, so the event is void — never an error, and
+    // observational (no failureKind, so it can't inflate failure metrics).
+    const out = normalizeEvent('relayDisconnected', undefined, SDK_SESSION, NOW)
+    expect(out.connectionMode).toBe('walletConnect')
+    expect(out.source).toBe('provider')
+    expect(out.error).toBeUndefined()
+    expect(out.failureKind).toBeUndefined()
+  })
+
+  it('normalizes relayReconnected as an unclassified walletConnect signal', () => {
+    const out = normalizeEvent('relayReconnected', undefined, SDK_SESSION, NOW)
+    expect(out.name).toBe('relayReconnected')
+    expect(out.connectionMode).toBe('walletConnect')
+    expect(out.source).toBe('provider')
+    expect(out.failureKind).toBeUndefined()
+  })
+
   it('normalizes walletConnectInitError as a walletConnect client_init_failed, message scrubbed', () => {
     const out = normalizeEvent(
       'walletConnectInitError',

package/src/observability/telemetry.ts

@@ -154,6 +154,14 @@ export interface UWCTelemetryEvent {
    * handoffCovered to avoid double-counting.
    */
   handoffCovered?: boolean | undefined
+  /** `pageVisibleDuringHandoff` only: how long the page was hidden for that segment (ms). */
+  hiddenMs?: number | undefined
+  /** Handoff terminals: cumulative time the page was backgrounded during the handoff (ms). */
+  backgroundedMs?: number | undefined
+  /** Handoff terminals: how many times the page was backgrounded during the handoff. */
+  backgroundCount?: number | undefined
+  /** Handoff terminals, WalletConnect only: relay-socket drops seen while the handoff was pending. */
+  relayDropCount?: number | undefined
 }
 
 /**
@@ -362,7 +370,10 @@ function buildTelemetryEvent<K extends UWCEventName>(
         durationMs: d.durationMs,
         timedOut: d.timedOut,
         timeoutMs: d.timeoutMs,
-        targetAlreadyActive: d.targetAlreadyActive
+        targetAlreadyActive: d.targetAlreadyActive,
+        backgroundedMs: d.backgroundedMs,
+        backgroundCount: d.backgroundCount,
+        relayDropCount: d.relayDropCount
       }
     }
     case 'walletRejected': {
@@ -381,7 +392,10 @@ function buildTelemetryEvent<K extends UWCEventName>(
         targetAlreadyActive: d.targetAlreadyActive,
         errorCode: d.errorCode,
         failureKind: d.failureKind,
-        source: d.source
+        source: d.source,
+        backgroundedMs: d.backgroundedMs,
+        backgroundCount: d.backgroundCount,
+        relayDropCount: d.relayDropCount
       }
     }
     case 'walletTimedOut': {
@@ -396,7 +410,10 @@ function buildTelemetryEvent<K extends UWCEventName>(
         handoffId: d.handoffId,
         durationMs: d.durationMs,
         timeoutMs: d.timeoutMs,
-        targetAlreadyActive: d.targetAlreadyActive
+        targetAlreadyActive: d.targetAlreadyActive,
+        backgroundedMs: d.backgroundedMs,
+        backgroundCount: d.backgroundCount,
+        relayDropCount: d.relayDropCount
       }
     }
     case 'walletFailed': {
@@ -416,7 +433,10 @@ function buildTelemetryEvent<K extends UWCEventName>(
         errorCode: d.errorCode,
         failureKind: d.failureKind,
         source: d.source,
-        error: { type: d.error.type, message: scrubMessage(d.error.message) }
+        error: { type: d.error.type, message: scrubMessage(d.error.message) },
+        backgroundedMs: d.backgroundedMs,
+        backgroundCount: d.backgroundCount,
+        relayDropCount: d.relayDropCount
       }
     }
     case 'capabilitiesUpdated': {
@@ -448,8 +468,15 @@ function buildTelemetryEvent<K extends UWCEventName>(
     }
     case 'pageHiddenDuringHandoff':
     case 'pageVisibleDuringHandoff': {
-      const d = data as UWCEventMap['pageHiddenDuringHandoff']
-      return { ...base, handoffId: d.handoffId, platform: d.platform }
+      // Cast to the visible shape (superset). `hiddenMs` is absent on the hidden
+      // event → undefined → dropped by compactUndefined.
+      const d = data as UWCEventMap['pageVisibleDuringHandoff']
+      return {
+        ...base,
+        handoffId: d.handoffId,
+        platform: d.platform,
+        hiddenMs: d.hiddenMs
+      }
     }
     case 'bridgeError': {
       const d = data as UWCEventMap['bridgeError']
@@ -473,6 +500,14 @@ function buildTelemetryEvent<K extends UWCEventName>(
         error: { type: d.error.type, message: scrubMessage(d.error.message) }
       }
     }
+    case 'relayDisconnected':
+    case 'relayReconnected': {
+      // Relay transport lifecycle (WalletConnect). Observational — NOT a failure,
+      // so deliberately no `failureKind` (never inflates failure metrics). The
+      // relayer carries no payload; pair the two by sdkSessionId + timestamp for
+      // the dead-window duration.
+      return { ...base, connectionMode: 'walletConnect', source: 'provider' }
+    }
     case 'walletConnectInitError': {
       const d = data as UWCEventMap['walletConnectInitError']
       // SignClient.init failed — the WC client never came up. Distinct from

package/src/services/connection-service.test.ts

@@ -863,277 +863,5 @@ describe('ConnectionService', () => {
       // No connection → no lifecycle evaluation, so no "unavailable" noise.
       expect(unavail).toHaveLength(0)
     })
-
-    it('a real accountsChanged from the connector updates activeAddress and emits sessionChanged', async () => {
-      let emitAccounts!: (accounts: string[]) => void
-      mockConnector.onAccountsChanged = (l: (accounts: string[]) => void) => {
-        emitAccounts = l
-        return () => {}
-      }
-      const sessions: Array<{ activeAddress: string | null }> = []
-      eventManager.on('sessionChanged', d =>
-        sessions.push({ activeAddress: d.session.activeAddress })
-      )
-
-      await connectionService.connect('injected', 'metamask', 'eip155:1')
-      emitAccounts(['0xNEW'])
-
-      expect(sessionManager.getSession().activeAddress).toBe('0xNEW')
-      expect(sessions[sessions.length - 1]?.activeAddress).toBe('0xNEW')
-    })
-
-    it('updates the matching availableAddresses entries for the changed namespace', async () => {
-      let emitAccounts!: (accounts: string[]) => void
-      mockConnector.onAccountsChanged = (l: (accounts: string[]) => void) => {
-        emitAccounts = l
-        return () => {}
-      }
-
-      await connectionService.connect('injected', 'metamask', 'eip155:1')
-      emitAccounts(['0xNEW'])
-
-      expect(sessionManager.getSession().availableAddresses).toEqual([
-        { address: '0xNEW', networkId: 'eip155:1' }
-      ])
-    })
-
-    it('an empty accounts list triggers a full disconnect AND calls connector.disconnect for local-state cleanup', async () => {
-      // The wallet already ended the session on its own side, but the
-      // connector's own LOCAL state (e.g. EthereumWalletService's cached
-      // account/uuid) still needs clearing — otherwise a later connect to a
-      // DIFFERENT wallet reads the stale cached account via
-      // checkExistingConnections() and never rebinds to the new wallet's
-      // provider/uuid. disconnect() must still be called here; it's a
-      // fire-and-forget, error-swallowed call (see the next test) so a
-      // protocol-based connector that rejects on an already-closed session
-      // can't break this path.
-      let emitAccounts!: (accounts: string[]) => void
-      mockConnector.onAccountsChanged = (l: (accounts: string[]) => void) => {
-        emitAccounts = l
-        return () => {}
-      }
-      const disconnectSpy = vi.fn().mockResolvedValue(undefined)
-      mockConnector.disconnect = disconnectSpy
-
-      await connectionService.connect('injected', 'metamask', 'eip155:1')
-      emitAccounts([])
-
-      expect(sessionManager.getSession().activeAddress).toBeNull()
-      expect(sessionManager.getSession().connectionMode).toBeNull()
-      expect(disconnectSpy).toHaveBeenCalledTimes(1)
-    })
-
-    it('does not let a rejecting connector.disconnect() break the wallet-initiated disconnect path', async () => {
-      let emitAccounts!: (accounts: string[]) => void
-      mockConnector.onAccountsChanged = (l: (accounts: string[]) => void) => {
-        emitAccounts = l
-        return () => {}
-      }
-      mockConnector.disconnect = vi
-        .fn()
-        .mockRejectedValue(new Error('already closed'))
-
-      await connectionService.connect('injected', 'metamask', 'eip155:1')
-
-      expect(() => emitAccounts([])).not.toThrow()
-      expect(sessionManager.getSession().activeAddress).toBeNull()
-      // Let the fire-and-forget rejection settle so it doesn't surface as an
-      // unhandled rejection in a later test.
-      await Promise.resolve()
-      await Promise.resolve()
-    })
-
-    it('a wallet that double-fires an empty accountsChanged does not double-emit disconnected/sessionChanged', async () => {
-      // handleAccountsChanged([]) -> finishDisconnect() runs synchronously
-      // FROM INSIDE the connector's own accountsChanged dispatch (the
-      // teardown it triggers removes that very listener re-entrantly). If a
-      // wallet emits the empty-array disconnect signal twice in quick
-      // succession — or the second emission slips through before teardown
-      // takes effect — finishDisconnect must be a no-op the second time
-      // rather than clearing an already-cleared session and re-emitting.
-      let emitAccounts!: (accounts: string[]) => void
-      mockConnector.onAccountsChanged = (l: (accounts: string[]) => void) => {
-        emitAccounts = l
-        return () => {}
-      }
-      mockConnector.disconnect = vi.fn().mockResolvedValue(undefined)
-      const disconnectedEvents: unknown[] = []
-      const sessionChangedEvents: unknown[] = []
-      eventManager.on('disconnected', d => disconnectedEvents.push(d))
-      eventManager.on('sessionChanged', d => sessionChangedEvents.push(d))
-
-      await connectionService.connect('injected', 'metamask', 'eip155:1')
-      sessionChangedEvents.length = 0 // drop the connect's own sessionChanged
-
-      emitAccounts([])
-      emitAccounts([]) // the wallet (or a race) delivers the same signal again
-
-      expect(disconnectedEvents).toHaveLength(1)
-      expect(sessionChangedEvents).toHaveLength(1)
-      expect(mockConnector.disconnect).toHaveBeenCalledTimes(1)
-    })
-
-    it('reattachLifecycle() seeds address-echo suppression with the just-active address', async () => {
-      const accountSubscribers: Array<(accounts: string[]) => void> = []
-      mockConnector.onAccountsChanged = (l: (accounts: string[]) => void) => {
-        accountSubscribers.push(l)
-        return () => {}
-      }
-      const sessions: unknown[] = []
-      eventManager.on('sessionChanged', d => sessions.push(d))
-
-      await connectionService.connect('injected', 'metamask', 'eip155:1')
-      sessions.length = 0
-      connectionService.reattachLifecycle()
-
-      // The reattached provider echoes the session's own current address →
-      // suppressed, no redundant sessionChanged.
-      accountSubscribers[1]!(['0x1234'])
-      expect(sessions).toHaveLength(0)
-
-      // A later, genuinely different address is a real change.
-      accountSubscribers[1]!(['0xDIFFERENT'])
-      expect(sessions).toHaveLength(1)
-    })
-
-    it("does not move activeAddress when the changed namespace no longer matches the session's active namespace (stale subscription after a cross-namespace switch)", async () => {
-      let emitAccounts!: (accounts: string[]) => void
-      mockConnector.onAccountsChanged = (l: (accounts: string[]) => void) => {
-        emitAccounts = l
-        return () => {}
-      }
-
-      await connectionService.connect('injected', 'metamask', 'eip155:1')
-      const connectTimeAddress = sessionManager.getSession().activeAddress
-
-      // Simulate the session's active network having already moved to a
-      // different namespace (e.g. mid-cross-namespace-switch) WITHOUT this
-      // stream having been reattached yet — it's still the eip155 one from
-      // connect time.
-      sessionManager.updateSession({
-        activeNetwork: {
-          ...sessionManager.getSession().activeNetwork,
-          namespace: 'solana'
-        } as any
-      })
-
-      emitAccounts(['0xNEW'])
-
-      // activeAddress belongs to the now-active (solana) namespace and must
-      // not be clobbered by a stale eip155 subscription's account change.
-      expect(sessionManager.getSession().activeAddress).toBe(connectTimeAddress)
-      // availableAddresses for the eip155 entry IS still updated — the address
-      // change is real, just not the currently-active one.
-      expect(sessionManager.getSession().availableAddresses).toEqual([
-        { address: '0xNEW', networkId: 'eip155:1' }
-      ])
-    })
-  })
-
-  describe('secondary-namespace account sync', () => {
-    // A multi-namespace wallet (e.g. MetaMask with Solana support) connected
-    // on a SOLANA-active session: the cross-namespace gather seeds eip155
-    // addresses into availableAddresses at connect time, but the lifecycle
-    // attach used to observe only the ACTIVE namespace — an eip155 account
-    // switch in the extension was never observed and the session served the
-    // connect-time eip155 addresses forever.
-    let accountSubs: Map<string, (accounts: string[]) => void>
-    let teardownsByNamespace: Map<string, number>
-
-    beforeEach(() => {
-      networks.push({
-        id: 'solana:mainnet',
-        internalId: 101,
-        namespace: 'solana',
-        name: 'Solana',
-        logoUrl: '',
-        nativeCurrency: { name: 'SOL', symbol: 'SOL', decimals: 9 },
-        networkType: 'solana'
-      } as never)
-      wallets[0]!.extensionInjectedProvider = {
-        supportedNetworkIds: ['solana:mainnet', 'eip155:1']
-      } as never
-      mockConnector.connect = vi.fn().mockResolvedValue({
-        networkId: 'solana:mainnet',
-        address: 'SoLAddr111',
-        availableAddresses: [
-          { address: 'SoLAddr111', networkId: 'solana:mainnet' },
-          { address: '0x1234', networkId: 'eip155:1' }
-        ]
-      })
-      accountSubs = new Map()
-      teardownsByNamespace = new Map()
-      mockConnector.onAccountsChanged = ((
-        listener: (accounts: string[]) => void,
-        context: { namespace: string }
-      ) => {
-        accountSubs.set(context.namespace, listener)
-        return () => {
-          teardownsByNamespace.set(
-            context.namespace,
-            (teardownsByNamespace.get(context.namespace) ?? 0) + 1
-          )
-        }
-      }) as never
-    })
-
-    it('attaches an accounts-sync subscription for every namespace present in availableAddresses, not only the active one', async () => {
-      await connectionService.connect('injected', 'metamask', 'solana:mainnet')
-
-      expect([...accountSubs.keys()].sort()).toEqual(['eip155', 'solana'])
-    })
-
-    it("a secondary namespace's accountsChanged updates its availableAddresses entries without touching activeAddress", async () => {
-      await connectionService.connect('injected', 'metamask', 'solana:mainnet')
-
-      accountSubs.get('eip155')!(['0xSWITCHED'])
-
-      const session = sessionManager.getSession()
-      expect(session.activeAddress).toBe('SoLAddr111')
-      expect(session.availableAddresses).toEqual([
-        { address: 'SoLAddr111', networkId: 'solana:mainnet' },
-        { address: '0xSWITCHED', networkId: 'eip155:1' }
-      ])
-    })
-
-    it('an empty accounts list from a SECONDARY namespace does not disconnect the session', async () => {
-      // Only the ACTIVE namespace's stream may signal the full
-      // wallet-initiated disconnect — a secondary namespace reporting []
-      // means that namespace's own authorization ended, not the session.
-      const disconnectSpy = vi.fn().mockResolvedValue(undefined)
-      mockConnector.disconnect = disconnectSpy
-
-      await connectionService.connect('injected', 'metamask', 'solana:mainnet')
-      accountSubs.get('eip155')!([])
-
-      const session = sessionManager.getSession()
-      expect(session.connectionMode).toBe('injected')
-      expect(session.activeAddress).toBe('SoLAddr111')
-      expect(disconnectSpy).not.toHaveBeenCalled()
-    })
-
-    it('disconnect() tears down the secondary subscriptions too', async () => {
-      await connectionService.connect('injected', 'metamask', 'solana:mainnet')
-
-      await connectionService.disconnect()
-
-      expect(teardownsByNamespace.get('eip155')).toBe(1)
-      expect(teardownsByNamespace.get('solana')).toBe(1)
-    })
-
-    it('reattachLifecycle() re-derives the secondary set for the CURRENT session without stacking duplicates', async () => {
-      await connectionService.connect('injected', 'metamask', 'solana:mainnet')
-
-      connectionService.reattachLifecycle()
-
-      // Old eip155 secondary attachment released, exactly one fresh one live.
-      expect(teardownsByNamespace.get('eip155')).toBe(1)
-      accountSubs.get('eip155')!(['0xAFTER'])
-      expect(
-        sessionManager
-          .getSession()
-          .availableAddresses.find(a => a.networkId === 'eip155:1')?.address
-      ).toBe('0xAFTER')
-    })
   })
 })