@keepsnappy/react-native 0.0.0-stage → 0.1.0-alpha.11

package/js/sdk/links.ts

@@ -0,0 +1,201 @@
+// Settings links (`<scheme>://devtools/perf-lab?...`) without app code: the SDK
+// runs before the router subscribes to Linking, so it wraps the link sources.
+// A perf-lab link goes to the handler here and never reaches the app's
+// listeners, so the router does not navigate to an unmatched route. Only a URL
+// whose host and path are exactly `devtools/perf-lab` on a custom (non-web)
+// scheme is one; every other URL passes through unchanged after one substring
+// check: in a dormant build this is the only work the SDK does after startup.
+
+import { Linking } from 'react-native';
+
+import { PERF_LAB_DEEP_LINK_PATH } from './activation';
+
+export type LinkHandler = (url: string, via: string) => void;
+// Told when an app URL (not a perf-lab one) is handed to the app, before the
+// app sees it: the start of a link-driven navigation.
+export type AppLinkHandler = (url: string, via: string) => void;
+
+type UrlListener = (event: { url: string }) => void;
+
+// `<scheme>://devtools/perf-lab[/][?query][#fragment]`, also with an empty host
+// (`<scheme>:///devtools/perf-lab`). Universal links (http/https) never match,
+// so a web page cannot route a link here.
+// Spells out PERF_LAB_DEEP_LINK_PATH.
+const SETTINGS_LINK = /^([a-z][a-z0-9+.-]*):\/\/\/?devtools\/perf-lab\/?(?:[?#]|$)/i;
+const WEB_SCHEMES = new Set(['http', 'https']);
+
+export const isPerfLabUrl = (url: unknown): url is string => {
+  if (typeof url !== 'string' || !url.includes(PERF_LAB_DEEP_LINK_PATH)) {
+    return false;
+  }
+  const match = SETTINGS_LINK.exec(url);
+  return match !== null && !WEB_SCHEMES.has((match[1] ?? '').toLowerCase());
+};
+
+// The same link can arrive twice (cold-start URL and a `url` event).
+const DUPLICATE_MS = 2000;
+let lastApplied: { url: string; t: number } | null = null;
+
+let handler: LinkHandler = () => undefined;
+let appLinkHandler: AppLinkHandler | null = null;
+
+const noteAppLink = (url: unknown, via: string) => {
+  if (appLinkHandler && typeof url === 'string' && url !== '') {
+    try {
+      appLinkHandler(url, via);
+    } catch {
+      // never breaks the app's link handling
+    }
+  }
+};
+
+const apply = (url: string, via: string) => {
+  const t = Date.now();
+  if (
+    lastApplied &&
+    lastApplied.url === url &&
+    t - lastApplied.t < DUPLICATE_MS
+  ) {
+    return;
+  }
+  lastApplied = { url, t };
+  handler(url, via);
+};
+
+// Every `runToken` value, however often and however its name is encoded.
+export const redactUrl = (url: string) => {
+  const q = url.indexOf('?');
+  if (q < 0) {
+    return url;
+  }
+  const pairs = url
+    .slice(q + 1)
+    .split('&')
+    .map(pair => {
+      const raw = pair.split('=')[0] ?? '';
+      let name = raw;
+      try {
+        name = decodeURIComponent(raw);
+      } catch {
+        // keeps the raw name
+      }
+      return name === 'runToken' ? `${raw}=<redacted>` : pair;
+    });
+  return `${url.slice(0, q + 1)}${pairs.join('&')}`;
+};
+
+const linkStats = { patched: [] as string[], failed: [] as string[] };
+
+export const linkPatchStatus = () => linkStats;
+
+const patch = (
+  target: Record<string, unknown>,
+  method: string,
+  label: string,
+  wrap: (
+    original: (...args: unknown[]) => unknown,
+  ) => (...args: unknown[]) => unknown,
+) => {
+  const original = target[method];
+  if (typeof original !== 'function') {
+    linkStats.failed.push(`${label}: not a function`);
+    return;
+  }
+  const wrapped = wrap((...args: unknown[]) =>
+    (original as (...a: unknown[]) => unknown).apply(target, args),
+  );
+  try {
+    target[method] = wrapped;
+  } catch {
+    // ESM namespace bindings can be getter-only.
+  }
+  if (target[method] !== wrapped) {
+    try {
+      Object.defineProperty(target, method, {
+        configurable: true,
+        enumerable: true,
+        writable: true,
+        value: wrapped,
+      });
+    } catch (error) {
+      linkStats.failed.push(`${label}: ${String(error)}`);
+      return;
+    }
+  }
+  linkStats.patched.push(label);
+};
+
+const filterInitial = (url: unknown, via: string) => {
+  if (isPerfLabUrl(url)) {
+    apply(url, via);
+    return null;
+  }
+  noteAppLink(url, via);
+  return url;
+};
+
+let installed = false;
+
+export const installLinks = (
+  onLink: LinkHandler,
+  onAppLink: AppLinkHandler | null = null,
+) => {
+  handler = onLink;
+  appLinkHandler = onAppLink;
+  if (installed) {
+    return;
+  }
+  installed = true;
+  const rnLinking = Linking as unknown as Record<string, unknown>;
+
+  patch(
+    rnLinking,
+    'addEventListener',
+    'Linking.addEventListener',
+    original => (type: unknown, listener: unknown) => {
+      if (type !== 'url' || typeof listener !== 'function') {
+        return original(type, listener);
+      }
+      const filtered: UrlListener = event => {
+        if (isPerfLabUrl(event?.url)) {
+          apply(event.url, 'event');
+          return;
+        }
+        noteAppLink(event?.url, 'event');
+        (listener as UrlListener)(event);
+      };
+      return original(type, filtered);
+    },
+  );
+
+  patch(
+    rnLinking,
+    'getInitialURL',
+    'Linking.getInitialURL',
+    original => () =>
+      Promise.resolve(original()).then(url => filterInitial(url, 'initial')),
+  );
+
+  try {
+    const expoLinking = require('expo-linking') as Record<string, unknown>;
+    patch(
+      expoLinking,
+      'getLinkingURL',
+      'expo-linking.getLinkingURL',
+      original => () => filterInitial(original(), 'linkingURL'),
+    );
+    patch(
+      expoLinking,
+      'getInitialURL',
+      'expo-linking.getInitialURL',
+      original => () =>
+        Promise.resolve(original()).then(url => filterInitial(url, 'initial')),
+    );
+  } catch (error) {
+    linkStats.failed.push(`expo-linking: ${String(error)}`);
+  }
+
+  // Nothing subscribes to `url` events in an app that only reads the initial
+  // URL; this listener makes runtime links work there too.
+  Linking.addEventListener('url', () => undefined);
+};

package/js/sdk/nav.ts

@@ -0,0 +1,383 @@
+// React Navigation containers found in the commit walk, with no app code: the
+// NavigationContainerRefContext provider value is the container's imperative
+// handle. Each container's `state` event gives the focused route chain; the
+// unstable `__unsafe_action__` event, when it fires, timestamps the dispatch.
+
+import { type CauseRoot, currentCause } from './causes';
+import {
+  fmt,
+  lastRoot,
+  now,
+  onAfterCommit,
+  percentile,
+  perfLog,
+  settings,
+} from './core';
+import {
+  CONTEXT_PROVIDER,
+  type Fiber,
+  findInTree,
+  type NavigationRef,
+  noteContainer,
+  onNavigationContainer,
+  registrySizes,
+} from './fiber';
+
+export interface RoutePart {
+  name: string;
+  key: string | null;
+}
+
+export interface NavAction {
+  t: number;
+  type: string;
+  // The action (touch, link, typing) behind the code that dispatched it (causes.ts).
+  cause: CauseRoot | null;
+}
+
+export interface NavSnapshot {
+  chain: RoutePart[];
+  stateT: number;
+  action: NavAction | null;
+  // The action behind the state change: the cause of the code that emitted the first `state` event.
+  cause: CauseRoot | null;
+}
+
+interface Container {
+  id: number;
+  fiber: Fiber;
+  ref: NavigationRef;
+  depth: number;
+  foundAt: number;
+  source: 'mount' | 'scan';
+  routesAtDiscovery: number;
+  unsubscribe: (() => void)[];
+}
+
+const containers = new Map<Fiber, Container>();
+let nextContainerId = 1;
+
+interface IndexedRoute {
+  name: string;
+  path: string;
+}
+
+const MAX_INDEXED_KEYS = 1000;
+const keyIndex = new Map<string, IndexedRoute>();
+
+// Action types that don't move the user anywhere, so they never end a window.
+const PASSIVE_ACTIONS = new Set(['SET_PARAMS', 'PRELOAD']);
+
+const MAX_COST_SAMPLES = 1000;
+const MAX_LISTED = 100;
+
+const stats = {
+  firstContainerAt: null as number | null,
+  stateEvents: 0,
+  evaluations: 0,
+  actions: { n: 0, noop: 0, byType: {} as Record<string, number> },
+  costMs: [] as number[],
+  chains: new Set<string>(),
+  errors: 0,
+};
+
+let pendingStateT: number | null = null;
+let pendingStateCause: CauseRoot | null = null;
+let pendingAction: NavAction | null = null;
+let evaluateScheduled = false;
+let scanned = false;
+let scanning = false;
+
+let snapshotListener: ((snapshot: NavSnapshot) => void) | null = null;
+let actionListener: ((action: NavAction) => void) | null = null;
+
+export const onNavSnapshot = (listener: (snapshot: NavSnapshot) => void) => {
+  snapshotListener = listener;
+};
+
+export const onNavAction = (listener: (action: NavAction) => void) => {
+  actionListener = listener;
+};
+
+export const containerCount = () => containers.size;
+
+export const resolveRouteKey = (key: string) => keyIndex.get(key) ?? null;
+
+export const recordNavCost = (ms: number) => {
+  if (stats.costMs.length < MAX_COST_SAMPLES) {
+    stats.costMs.push(ms);
+  }
+};
+
+const noteError = (where: string, error: unknown) => {
+  stats.errors++;
+  if (stats.errors <= 3) {
+    perfLog(`nav error ${where} ${String(error)}`);
+  }
+};
+
+interface StateLike {
+  index?: unknown;
+  routes?: unknown;
+}
+
+interface RouteLike {
+  name?: unknown;
+  key?: unknown;
+  state?: unknown;
+}
+
+const indexKeys = (state: StateLike | undefined, prefix: string) => {
+  if (!state || !Array.isArray(state.routes)) {
+    return;
+  }
+  for (const route of state.routes as RouteLike[]) {
+    if (typeof route?.name !== 'string') {
+      continue;
+    }
+    const path = prefix ? `${prefix}/${route.name}` : route.name;
+    if (typeof route.key === 'string') {
+      keyIndex.delete(route.key);
+      keyIndex.set(route.key, { name: route.name, path });
+      if (keyIndex.size > MAX_INDEXED_KEYS) {
+        const oldest = keyIndex.keys().next().value;
+        if (oldest !== undefined) {
+          keyIndex.delete(oldest);
+        }
+      }
+    }
+    indexKeys(route.state as StateLike | undefined, path);
+  }
+};
+
+// Same rule as React Navigation's findFocusedRoute: a partial state without
+// `index` focuses its first route.
+const focusedChainOf = (root: unknown): RoutePart[] => {
+  const chain: RoutePart[] = [];
+  let state = root as StateLike | undefined;
+  while (state && Array.isArray(state.routes)) {
+    const index = typeof state.index === 'number' ? state.index : 0;
+    const route = state.routes[index] as RouteLike | undefined;
+    if (!route || typeof route.name !== 'string') {
+      break;
+    }
+    chain.push({
+      name: route.name,
+      key: typeof route.key === 'string' ? route.key : null,
+    });
+    state = route.state as StateLike | undefined;
+  }
+  return chain;
+};
+
+// Nested independent containers (e.g. a sheet with its own navigator) extend
+// the chain of the containers above them, as the route-prop scan did.
+const evaluate = () => {
+  evaluateScheduled = false;
+  if (!settings.hook) {
+    pendingStateT = null;
+    pendingStateCause = null;
+    return;
+  }
+  const t0 = now();
+  stats.evaluations++;
+  const ordered = [...containers.values()].sort((a, b) => a.depth - b.depth);
+  const chain: RoutePart[] = [];
+  for (const container of ordered) {
+    try {
+      const root = container.ref.getRootState();
+      indexKeys(root as StateLike | undefined, '');
+      chain.push(...focusedChainOf(root));
+    } catch (error) {
+      noteError('getRootState', error);
+    }
+  }
+  const snapshot: NavSnapshot = {
+    chain,
+    stateT: pendingStateT ?? t0,
+    action: pendingAction,
+    cause: pendingStateCause,
+  };
+  pendingStateT = null;
+  pendingStateCause = null;
+  if (chain.length > 0 && stats.chains.size < MAX_LISTED) {
+    stats.chains.add(chain.map(part => part.name).join('/'));
+  }
+  snapshotListener?.(snapshot);
+  recordNavCost(now() - t0);
+};
+
+const scheduleEvaluate = () => {
+  if (!evaluateScheduled) {
+    evaluateScheduled = true;
+    setTimeout(evaluate, 0);
+  }
+};
+
+// Called by the visit logic once a snapshot started a visit, so an older
+// action is not reused as the start of a later navigation.
+export const consumeAction = () => {
+  pendingAction = null;
+};
+
+const onState = () => {
+  stats.stateEvents++;
+  if (pendingStateT === null) {
+    pendingStateT = now();
+    pendingStateCause = currentCause();
+  }
+  scheduleEvaluate();
+};
+
+const onUnsafeAction = (event: unknown) => {
+  const t = now();
+  const data = (
+    event as { data?: { action?: { type?: unknown }; noop?: unknown } }
+  )?.data;
+  const type =
+    typeof data?.action?.type === 'string' ? data.action.type : 'unknown';
+  stats.actions.n++;
+  stats.actions.byType[type] = (stats.actions.byType[type] ?? 0) + 1;
+  if (data?.noop === true) {
+    stats.actions.noop++;
+    return;
+  }
+  perfLog(`nav action type=${type} t=${fmt(t)}`);
+  if (PASSIVE_ACTIONS.has(type)) {
+    return;
+  }
+  pendingAction = { t, type, cause: currentCause() };
+  actionListener?.(pendingAction);
+};
+
+const subscribe = (
+  ref: NavigationRef,
+  type: string,
+  listener: (event: unknown) => void,
+) => {
+  try {
+    const off = ref.addListener(type, listener);
+    return typeof off === 'function' ? (off as () => void) : null;
+  } catch (error) {
+    noteError(`addListener ${type}`, error);
+    return null;
+  }
+};
+
+const added = (
+  fiber: Fiber,
+  ref: NavigationRef,
+  depth: number,
+  source: Container['source'],
+) => {
+  const container: Container = {
+    id: nextContainerId++,
+    fiber,
+    ref,
+    depth,
+    foundAt: now(),
+    source,
+    routesAtDiscovery: registrySizes().routes,
+    unsubscribe: [],
+  };
+  stats.firstContainerAt ??= container.foundAt;
+  // Subscribed during the commit, before passive effects run, so the
+  // container's first `state` emit (on mount) is not missed.
+  for (const [type, listener] of [
+    ['state', onState],
+    ['__unsafe_action__', onUnsafeAction],
+  ] as const) {
+    const off = subscribe(ref, type, listener);
+    if (off) {
+      container.unsubscribe.push(off);
+    }
+  }
+  containers.set(fiber, container);
+  perfLog(
+    `nav container id=${container.id} depth=${depth} source=${source} t=${fmt(container.foundAt)} routesBefore=${container.routesAtDiscovery}`,
+  );
+  scheduleEvaluate();
+};
+
+const removed = (fiber: Fiber) => {
+  const container = containers.get(fiber);
+  if (!container) {
+    return;
+  }
+  for (const off of container.unsubscribe) {
+    try {
+      off();
+    } catch (error) {
+      noteError('unsubscribe', error);
+    }
+  }
+  containers.delete(fiber);
+  perfLog(`nav container removed id=${container.id} t=${fmt(now())}`);
+  scheduleEvaluate();
+};
+
+// Containers mounted before the hook was switched on (settings.hook off at
+// boot) were never seen mounting; look for them once in the current tree.
+const scanOnce = () => {
+  if (scanned || containers.size > 0 || !settings.hook) {
+    return;
+  }
+  scanned = true;
+  const root = lastRoot(1);
+  if (!root) {
+    return;
+  }
+  scanning = true;
+  try {
+    findInTree(root.current, fiber => {
+      if (fiber.tag === CONTEXT_PROVIDER) {
+        noteContainer(fiber);
+      }
+      return null;
+    });
+  } finally {
+    scanning = false;
+  }
+};
+
+export const navStats = () => ({
+  containers: [...containers.values()].map(c => ({
+    id: c.id,
+    depth: c.depth,
+    foundAt: c.foundAt,
+    source: c.source,
+    routesAtDiscovery: c.routesAtDiscovery,
+    subscriptions: c.unsubscribe.length,
+  })),
+  firstContainerAt: stats.firstContainerAt,
+  stateEvents: stats.stateEvents,
+  evaluations: stats.evaluations,
+  actions: { ...stats.actions, byType: { ...stats.actions.byType } },
+  indexedKeys: keyIndex.size,
+  chains: [...stats.chains],
+  costMs: {
+    n: stats.costMs.length,
+    mean:
+      stats.costMs.length === 0
+        ? null
+        : stats.costMs.reduce((s, n) => s + n, 0) / stats.costMs.length,
+    p99: percentile(stats.costMs, 99),
+    max: percentile(stats.costMs, 100),
+  },
+  errors: stats.errors,
+});
+
+let installed = false;
+
+export const installNav = () => {
+  if (installed) {
+    return;
+  }
+  installed = true;
+  onNavigationContainer({
+    added: (fiber, ref, depth) =>
+      added(fiber, ref, depth, scanning ? 'scan' : 'mount'),
+    removed,
+  });
+  onAfterCommit(scanOnce);
+};

package/js/sdk/net-install.ts

@@ -0,0 +1,49 @@
+// Wires the request counter to the app's fetch and XMLHttpRequest. Expo installs
+// its own fetch when the app imports `expo`, after this runs, so the hooks are
+// re-applied once the entry module has loaded, at the first commit and at every
+// window start (a descriptor check when nothing changed).
+
+import {
+  addStartupSection,
+  net,
+  onAfterCommit,
+  onWindowStart,
+  settings,
+} from './core';
+import { createNetHooks, type NetHooks } from './net';
+
+let hooks: NetHooks | null = null;
+
+export const installNet = () => {
+  if (hooks) {
+    return;
+  }
+  const installed = createNetHooks({
+    target: globalThis as unknown as Record<string, unknown>,
+    counter: net,
+    enabled: () => settings.net,
+  });
+  hooks = installed;
+  const first = installed.ensure();
+  setTimeout(() => installed.ensure(), 0);
+  let committed = false;
+  onAfterCommit(() => {
+    if (!committed) {
+      committed = true;
+      installed.ensure();
+    }
+  });
+  onWindowStart(() => installed.ensure());
+  addStartupSection('net', () => ({
+    enabled: settings.net,
+    atBoot: first,
+    hooks: installed.stats(),
+    counter: net.stats(),
+  }));
+};
+
+// The SDK's own requests (push client) go through this and are never counted.
+export const ownFetch = (url: string, init: Record<string, unknown>) => {
+  const run = () => fetch(url, init as RequestInit);
+  return hooks ? hooks.own(run) : run();
+};