pulse-updates 1.3.8 → 1.3.9

package/lib/module/links.js

@@ -184,6 +184,11 @@ export function createPulseLinkClient(options) {
   let accountRetryAt = 0;
   let accountAttempts = 0;
   let deterministicEpoch = 0;
+  // Invalidates every host callback that crossed an await when this client is reset/disposed.
+  // This is deliberately separate from deterministicEpoch: captures during a committed callback
+  // have intentional last-touch semantics, whereas a lifecycle boundary must forbid every stale
+  // state write, retry and outcome from the old instance.
+  let lifecycleGeneration = 0;
   // Host navigation is irreversible once any routing callback has started: it may perform its
   // side effect synchronously before returning a Promise. Serialize captures against that commit
   // boundary and keep the newer accepted token durable for the next client lifecycle instead of
@@ -402,6 +407,9 @@ export function createPulseLinkClient(options) {
     return acknowledgeTerminalDelivery(tombstone);
   };
   const completeFirstOpen = (status, outcome) => {
+    const completionLifecycleGeneration = lifecycleGeneration;
+    const completionDeterministicEpoch = deterministicEpoch;
+    const completionIsCurrent = () => !disposed && lifecycleGeneration === completionLifecycleGeneration && deterministicEpoch === completionDeterministicEpoch;
     let shouldQueue = Boolean(options.onFirstOpenResult);
     if (shouldQueue && options.shouldQueueFirstOpenResult) {
       try {
@@ -410,6 +418,9 @@ export function createPulseLinkClient(options) {
         shouldQueue = false;
         reportError(error);
       }
+      // Privacy/diagnostic hooks are host code and may synchronously reset, dispose, or capture a
+      // deterministic destination. Never resurrect the terminal first-open state they invalidated.
+      if (!completionIsCurrent()) return;
     }
     if (!shouldQueue) {
       state = {
@@ -453,8 +464,10 @@ export function createPulseLinkClient(options) {
     void flushTerminalDelivery();
   };
   const blockFirstOpenForDeterministic = () => {
+    const blockingLifecycleGeneration = lifecycleGeneration;
     deterministicEpoch += 1;
-    if (state.firstOpen.completed && state.firstOpen.nextRetryAt === 0) return;
+    const blockingDeterministicEpoch = deterministicEpoch;
+    if (state.firstOpen.completed && state.firstOpen.nextRetryAt === 0) return true;
     state = {
       ...state,
       firstOpen: {
@@ -464,14 +477,23 @@ export function createPulseLinkClient(options) {
       }
     };
     persistAndNotify();
+    return !disposed && lifecycleGeneration === blockingLifecycleGeneration && deterministicEpoch === blockingDeterministicEpoch;
   };
-  const isAccountReady = () => {
+  const readAccountReadiness = () => {
+    const readinessLifecycleGeneration = lifecycleGeneration;
+    const readinessDeterministicEpoch = deterministicEpoch;
+    let ready = false;
     try {
-      return options.isAccountReady?.() ?? false;
+      ready = options.isAccountReady?.() ?? false;
     } catch (error) {
       reportError(error);
-      return false;
     }
+    return {
+      ready,
+      // Readiness is host code, not a pure getter. A reset/dispose/capture inside it invalidates
+      // the caller's snapshot and must be observed before any waiting/retry/application write.
+      current: !disposed && lifecycleGeneration === readinessLifecycleGeneration && deterministicEpoch === readinessDeterministicEpoch
+    };
   };
   const schedulePendingRetry = () => {
     const pending = state.pending;
@@ -679,7 +701,9 @@ export function createPulseLinkClient(options) {
         if (!sourceToken || state.pending?.token === sourceToken) clearPendingAsTerminal();
         return false;
       }
-      if (!isAccountReady()) {
+      const accountReadiness = readAccountReadiness();
+      if (!accountReadiness.current) return false;
+      if (!accountReadiness.ready) {
         patchState({
           status: 'waiting_for_account'
         });
@@ -701,13 +725,23 @@ export function createPulseLinkClient(options) {
     let applicationFailed = false;
     let applicationError;
     const applicationEpoch = deterministicEpoch;
+    const applicationLifecycleGeneration = lifecycleGeneration;
+    const lifecycleIsCurrent = () => !disposed && lifecycleGeneration === applicationLifecycleGeneration;
     const hasNewerPendingIntent = () => deterministicEpoch !== applicationEpoch && state.pending !== null
     // A provenance upgrade or rejected lower-priority capture for the token already being
     // applied does not represent another destination and must not leave that token pending.
     && (sourceToken === null || state.pending.token !== sourceToken);
     routingApplicationInFlight = true;
     emitOutcome(link, 'app_open_confirmed');
+    if (!lifecycleIsCurrent()) {
+      routingApplicationInFlight = false;
+      return false;
+    }
     emitOutcome(link, 'deferred_link_resolved');
+    if (!lifecycleIsCurrent()) {
+      routingApplicationInFlight = false;
+      return false;
+    }
     // `emitOutcome` invokes host diagnostics synchronously. If those hooks re-enter capture with
     // a newer accepted destination, it still arrived before the routing callback and must win.
     if (hasNewerPendingIntent()) {
@@ -730,10 +764,19 @@ export function createPulseLinkClient(options) {
     } finally {
       routingApplicationInFlight = false;
     }
+
+    // The callback may resolve after reset/dispose and after another client has already committed
+    // a newer journey into the same storage. The old instance must not schedule a retry, rewrite
+    // state, or emit action_applied regardless of whether the callback returned true/false/threw.
+    if (!lifecycleIsCurrent()) return false;
     const newerIntentArrivedDuringApplication = hasNewerPendingIntent();
     if (applicationFailed) {
       reportError(applicationError);
-      if (newerIntentArrivedDuringApplication) {
+      if (!lifecycleIsCurrent()) return false;
+      // onError is host code too: it may capture a newer deterministic destination while reporting
+      // this failure. Re-evaluate after the callback instead of arming a stale retry from the value
+      // observed before diagnostics ran.
+      if (hasNewerPendingIntent()) {
         // The current action did not commit. Resume the newer accepted intent that was captured
         // while its callback was suspended, without scheduling a retry for the superseded one.
         void process();
@@ -768,11 +811,13 @@ export function createPulseLinkClient(options) {
       appliedIds
     };
     persistAndNotify();
+    if (!lifecycleIsCurrent()) return false;
     if (link.matchBasis === 'account_bound') {
       accountAttempts = 0;
       accountRetryAt = 0;
     }
     emitOutcome(link, 'action_applied');
+    if (!lifecycleIsCurrent()) return false;
     if (stillPending && state.pending?.token !== deterministicTokenDeferredAfterCommittedJourney) {
       void process();
     }
@@ -825,11 +870,13 @@ export function createPulseLinkClient(options) {
         return;
       }
       const token = pending.token;
+      const pendingLifecycleGeneration = lifecycleGeneration;
       patchState({
         status: 'resolving'
       });
+      if (disposed || lifecycleGeneration !== pendingLifecycleGeneration || state.pending?.token !== token) return;
       const publicResult = await resolvePublic(token, pending.matchBasis);
-      if (disposed || state.pending?.token !== token) return;
+      if (disposed || lifecycleGeneration !== pendingLifecycleGeneration || state.pending?.token !== token) return;
       if (publicResult.kind === 'resolved') {
         await applyResolved(publicResult.link, token);
         return;
@@ -838,7 +885,15 @@ export function createPulseLinkClient(options) {
         schedulePendingRetry();
         return;
       }
-      if (!options.accountBridge || !isAccountReady()) {
+      if (!options.accountBridge) {
+        patchState({
+          status: 'waiting_for_account'
+        });
+        return;
+      }
+      const accountReadiness = readAccountReadiness();
+      if (!accountReadiness.current || disposed || lifecycleGeneration !== pendingLifecycleGeneration || state.pending?.token !== token) return;
+      if (!accountReadiness.ready) {
         patchState({
           status: 'waiting_for_account'
         });
@@ -846,7 +901,7 @@ export function createPulseLinkClient(options) {
       }
       try {
         const raw = await withPromiseTimeout(() => options.accountBridge.claim(token), requestTimeoutMs, 'account claim');
-        if (disposed || state.pending?.token !== token) return;
+        if (disposed || lifecycleGeneration !== pendingLifecycleGeneration || state.pending?.token !== token) return;
         const normalizedClaim = normalizeResolved(raw, token, 'account_bound', allowedActions, now());
         const claimed = normalizedClaim ? {
           ...normalizedClaim,
@@ -855,23 +910,28 @@ export function createPulseLinkClient(options) {
           confidence: 1
         } : null;
         if (claimed) {
-          blockFirstOpenForDeterministic();
+          if (!blockFirstOpenForDeterministic()) return;
           await applyResolved(claimed, token);
         } else clearPendingAsTerminal();
       } catch (error) {
+        if (disposed || lifecycleGeneration !== pendingLifecycleGeneration || state.pending?.token !== token) return;
         reportError(error);
-        if (state.pending?.token === token) schedulePendingRetry();
+        if (!disposed && lifecycleGeneration === pendingLifecycleGeneration && state.pending?.token === token) schedulePendingRetry();
       }
       return;
     }
-    if (!options.accountBridge || !isAccountReady() || accountRetryAt > now()) return;
+    if (!options.accountBridge) return;
+    const accountReadiness = readAccountReadiness();
+    if (!accountReadiness.current || state.pending) return;
+    if (!accountReadiness.ready || accountRetryAt > now()) return;
     const accountPendingEpoch = deterministicEpoch;
+    const accountPendingLifecycleGeneration = lifecycleGeneration;
     try {
       const raw = await withPromiseTimeout(() => options.accountBridge.pending(), requestTimeoutMs, 'account pending');
       // A URL/paste/referrer captured while the account lookup was in flight is newer explicit
       // user intent. Ignore the stale bridge response and let the requested drain resolve the
       // captured token; otherwise both deterministic destinations could be applied.
-      if (disposed || deterministicEpoch !== accountPendingEpoch || state.pending) return;
+      if (disposed || lifecycleGeneration !== accountPendingLifecycleGeneration || deterministicEpoch !== accountPendingEpoch || state.pending) return;
       if (!raw) {
         accountAttempts = 0;
         accountRetryAt = 0;
@@ -894,7 +954,7 @@ export function createPulseLinkClient(options) {
         // Reserve the first-open journey for deterministic recovery before invoking any host
         // callback. This also covers an already-applied account item restored from older SDK
         // state, which must still prevent a second probabilistic destination.
-        blockFirstOpenForDeterministic();
+        if (!blockFirstOpenForDeterministic()) return;
         if (!state.appliedIds.includes(pendingLink.id)) {
           await applyResolved(pendingLink, null);
         } else if (state.status !== 'applied') {
@@ -904,8 +964,9 @@ export function createPulseLinkClient(options) {
         }
       }
     } catch (error) {
-      if (disposed || deterministicEpoch !== accountPendingEpoch || state.pending) return;
+      if (disposed || lifecycleGeneration !== accountPendingLifecycleGeneration || deterministicEpoch !== accountPendingEpoch || state.pending) return;
       reportError(error);
+      if (disposed || lifecycleGeneration !== accountPendingLifecycleGeneration || deterministicEpoch !== accountPendingEpoch || state.pending) return;
       // No token was consumed; the authenticated server outbox remains authoritative.
       scheduleAccountRetry();
     }
@@ -1008,7 +1069,14 @@ export function createPulseLinkClient(options) {
     lastFirstOpenContext = context;
     if (state.pending) return 'deterministic_pending';
     if (state.firstOpen.completed) return 'already_completed';
-    if (state.firstOpen.nextRetryAt > now()) return 'backoff';
+    if (state.firstOpen.nextRetryAt > now()) {
+      // On a fresh client lifecycle scheduleWake() ran before the host supplied this ephemeral
+      // context, so the persisted first-open deadline could not be part of its candidates. Re-arm
+      // now that retrying is possible; otherwise a 503 followed by process death remains asleep
+      // until some unrelated foreground/manual call invokes matchFirstOpen again.
+      scheduleWake();
+      return 'backoff';
+    }
     if (!isEligibleFirstOpen(context, now(), recentInstallMaxAgeMs)) return 'ineligible';
 
     // The client starts account recovery at construction. Join that deterministic rail before
@@ -1017,13 +1085,20 @@ export function createPulseLinkClient(options) {
     await process();
     if (disposed) return 'ineligible';
     if (state.pending || state.firstOpen.completed) return 'deterministic_pending';
-    if (options.accountBridge && isAccountReady() && accountRetryAt > now()) {
-      if (state.firstOpen.nextRetryAt === 0) scheduleFirstOpenRetry();
-      return 'retry_scheduled';
+    if (options.accountBridge) {
+      const accountReadiness = readAccountReadiness();
+      if (!accountReadiness.current) {
+        return disposed ? 'ineligible' : 'deterministic_pending';
+      }
+      if (accountReadiness.ready && accountRetryAt > now()) {
+        if (state.firstOpen.nextRetryAt === 0) scheduleFirstOpenRetry();
+        return 'retry_scheduled';
+      }
     }
     if (!isEligibleFirstOpen(context, now(), recentInstallMaxAgeMs)) return 'ineligible';
     const installAttemptId = state.firstOpen.installAttemptId ?? makeInstallAttemptId(options.randomUUID);
     const startingDeterministicEpoch = deterministicEpoch;
+    const startingLifecycleGeneration = lifecycleGeneration;
     state = {
       ...state,
       status: 'resolving',
@@ -1033,14 +1108,44 @@ export function createPulseLinkClient(options) {
         attemptedAt: now()
       }
     };
-    persistAndNotify();
+    const firstOpenReservationPersisted = persistAndNotify();
+    // Persistence notifies host state hooks synchronously. They may reset/dispose this client or
+    // capture a deterministic destination. In all three cases the reserved id no longer belongs to
+    // the current lifecycle and must never cross the network boundary.
+    if (disposed) return 'ineligible';
+    if (lifecycleGeneration !== startingLifecycleGeneration || deterministicEpoch !== startingDeterministicEpoch || state.pending || state.firstOpen.completed) return 'deterministic_pending';
+    if (options.storage && !firstOpenReservationPersisted) {
+      // An unpersisted id must never leave the process: after a crash the retry would mint a new
+      // id and the server could count/route the same install twice. Keep the exact nonce in memory,
+      // arm a persistence retry without incrementing matcher attempts, and send nothing until a
+      // synchronous durable write succeeds. Memory-only clients have no restart contract and may
+      // continue normally.
+      state = {
+        ...state,
+        status: 'retryable_error',
+        firstOpen: {
+          ...state.firstOpen,
+          nextRetryAt: now() + retryBaseMs
+        }
+      };
+      reportError(new Error('Pulse Links: first-open install attempt id was not durably persisted'));
+      notifyState();
+      return 'retry_scheduled';
+    }
+    const accountEmail = normalizeAccountEmail(context.accountEmail);
     const body = {
       appBundleId: context.appBundleId.trim(),
       platform: 'ios',
       locale: normalizeLocale(context.locale),
       firstOpen: true,
       installAttemptId,
-      ...normalizeAnonymousFirstOpenSignals(context)
+      ...normalizeAnonymousFirstOpenSignals(context),
+      // Sent only when the app already knows it. The resolver treats an address that matches
+      // exactly one recent message as proof of origin; anything else falls back to the
+      // probabilistic path, so a shared or unknown address costs nothing.
+      ...(accountEmail ? {
+        accountEmail
+      } : {})
     };
     try {
       const response = await withTimeout(fetcher, matchUrlOf(resolverBaseUrl), {
@@ -1166,6 +1271,8 @@ export function createPulseLinkClient(options) {
     return owned;
   };
   const captureAndroidInstallReferrer = async bridge => {
+    const referrerLifecycleGeneration = lifecycleGeneration;
+    const referrerDeterministicEpoch = deterministicEpoch;
     let raw;
     try {
       raw = await bridge.getDeferredHandoff();
@@ -1178,6 +1285,7 @@ export function createPulseLinkClient(options) {
       };
     }
     const result = normalizeAndroidInstallReferrerResult(raw);
+    if (disposed || lifecycleGeneration !== referrerLifecycleGeneration || deterministicEpoch !== referrerDeterministicEpoch) return result;
     if (result.status === 'OK' && result.token) {
       capture(result.token, 'android_install_referrer');
     }
@@ -1234,6 +1342,7 @@ export function createPulseLinkClient(options) {
     dispose: () => {
       if (disposed) return;
       disposed = true;
+      lifecycleGeneration += 1;
       deterministicEpoch += 1;
       terminalDeliveryGeneration += 1;
       if (retryTimer) clearTimeout(retryTimer);
@@ -1245,6 +1354,7 @@ export function createPulseLinkClient(options) {
     reset: () => {
       accountRetryAt = 0;
       accountAttempts = 0;
+      lifecycleGeneration += 1;
       deterministicEpoch += 1;
       terminalDeliveryGeneration += 1;
       terminalDeliverySending = null;
@@ -1445,6 +1555,20 @@ function resolverOutcomeRetryDelay(eventId, attempts, retryBaseMs, retryMaxMs) {
   const jitter = 0.5 + hash / 0xffffffff * 0.5;
   return Math.max(1, Math.floor(ceiling * jitter));
 }
+
+/**
+ * An address is only useful to the resolver if it is the same shape the send was recorded with.
+ * Anything that is not plausibly an address is dropped rather than sent: a malformed value can
+ * only ever fail to match, and not sending it keeps the payload free of stray user input.
+ */
+export function normalizeAccountEmail(raw) {
+  const value = (raw ?? '').trim().toLowerCase();
+  if (value.length < 3 || value.length > 255) return null;
+  const at = value.indexOf('@');
+  if (at <= 0 || at !== value.lastIndexOf('@') || at === value.length - 1) return null;
+  if (/\s/.test(value)) return null;
+  return value;
+}
 async function withTimeout(fetcher, input, init, timeoutMs) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);