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

package/js/sdk/activation.ts

@@ -0,0 +1,375 @@
+// Build mode and per-run activation. Loaded in every flag-on build, dormant or
+// not, so it stays small and imports nothing: no React Native, no core.
+//
+// Modes (bundle time):
+//   auto    - measuring from the first frame (EXPO_PUBLIC_PERF_LAB_MODE=auto or PERF_LAB_AUTO=1)
+//   manual  - markers only until a settings link turns collection on (no mode set)
+//   dormant - nothing installed until an activation link; it applies from the NEXT launch
+//
+// The activation record lives in the app sandbox (`perf-lab/activation.json`,
+// written by the native module). hook.polyfill.js reads it once, synchronously,
+// before React loads, and leaves the raw value in __PERFLAB_ACTIVATION__.
+// Its `profile` field picks the React renderer in a PERF_LAB_REACT_PROFILING=switch
+// bundle (js/renderer-switch.js), so a process is wholly one renderer.
+
+export const PERF_LAB_ENABLED = (process.env.EXPO_PUBLIC_KEEPSNAPPY ?? process.env.EXPO_PUBLIC_PERF_LAB) === '1';
+
+export const PERF_LAB_DEEP_LINK_PATH = 'devtools/perf-lab';
+
+export type PerfLabMode = 'auto' | 'manual' | 'dormant';
+
+export const resolveMode = (
+  mode: string | undefined,
+  auto: string | undefined,
+): PerfLabMode => {
+  if (mode === 'dormant' || mode === 'auto') {
+    return mode;
+  }
+  return auto === '1' ? 'auto' : 'manual';
+};
+
+export const MODE: PerfLabMode = resolveMode(
+  (process.env.EXPO_PUBLIC_KEEPSNAPPY_MODE ?? process.env.EXPO_PUBLIC_PERF_LAB_MODE),
+  (process.env.EXPO_PUBLIC_KEEPSNAPPY_AUTO ?? process.env.EXPO_PUBLIC_PERF_LAB_AUTO),
+);
+
+export const DEFAULT_TTL_S = 7200;
+// A run token lives 6 h on the server; an activation never outlives it.
+export const MAX_TTL_S = 21600;
+
+export interface ActivationRecord {
+  active: boolean;
+  runToken: string | null;
+  // Wall clock, ms since epoch.
+  expiresAt: number;
+  // Diagnostic iteration: every raw profile file of the run is kept and uploaded.
+  diag: boolean;
+  // React profiling renderer (switch bundles) plus update causes and render times.
+  profile: boolean;
+  // Hermes sampling rate in Hz, 0 = off.
+  cpuprof: number;
+}
+
+export type ActivationRead = 'polyfill' | 'boot' | 'unavailable' | 'none';
+
+export interface Decision {
+  mode: PerfLabMode;
+  active: boolean;
+  runToken: string | null;
+  expiresAt: number | null;
+  diag: boolean;
+  profile: boolean;
+  cpuprof: number;
+  read: ActivationRead;
+  // The record as read at startup; links in this process update a copy.
+  record: ActivationRecord | null;
+}
+
+export interface ActivationNative {
+  activationRead(): string | null;
+  activationWrite(json: string): boolean;
+}
+
+// What the polyfill leaves behind (see hook.polyfill.js).
+export interface PolyfillActivation {
+  mode: string;
+  read: 'polyfill' | 'deferred' | 'none';
+  // Android only: ms the polyfill's synchronous ExpoModulesCore.installModules() took.
+  installMs?: number;
+  raw: string | null;
+  active: boolean;
+  // Load the profiling renderer (switch bundles). Set once, before React loads.
+  profile: boolean;
+  // Which renderer the switch module loaded, if any.
+  renderer?: 'prod' | 'profiling';
+  t: number;
+}
+
+export const CPU_HZ_MIN = 10;
+export const CPU_HZ_MAX = 10000;
+export const DEFAULT_CPU_HZ = 250;
+
+const hzOf = (value: unknown) =>
+  typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? Math.min(CPU_HZ_MAX, Math.max(CPU_HZ_MIN, Math.round(value)))
+    : 0;
+
+export const parseRecord = (
+  raw: string | null | undefined,
+): ActivationRecord | null => {
+  if (typeof raw !== 'string' || raw === '') {
+    return null;
+  }
+  try {
+    const value = JSON.parse(raw) as Record<string, unknown>;
+    if (!value || typeof value !== 'object') {
+      return null;
+    }
+    return {
+      active: value.active === true,
+      runToken:
+        typeof value.runToken === 'string' && value.runToken !== ''
+          ? value.runToken
+          : null,
+      expiresAt: typeof value.expiresAt === 'number' ? value.expiresAt : 0,
+      diag: value.diag === true,
+      profile: value.profile === true,
+      cpuprof: hzOf(value.cpuprof),
+    };
+  } catch {
+    return null;
+  }
+};
+
+const live = (record: ActivationRecord | null, nowMs: number) =>
+  record !== null && record.expiresAt > nowMs;
+
+const OFF: ActivationRecord = {
+  active: false,
+  runToken: null,
+  expiresAt: 0,
+  diag: false,
+  profile: false,
+  cpuprof: 0,
+};
+
+// Must agree with activeRecord() in hook.polyfill.js (tested on the same fixtures).
+export const decide = (
+  mode: PerfLabMode,
+  record: ActivationRecord | null,
+  nowMs: number,
+  read: ActivationRead,
+): Decision => {
+  if (mode === 'dormant') {
+    const active = live(record, nowMs) && record?.active === true;
+    return {
+      mode,
+      active,
+      runToken: active ? (record?.runToken ?? null) : null,
+      expiresAt: active ? (record?.expiresAt ?? null) : null,
+      diag: active && record?.diag === true,
+      profile: active && record?.profile === true,
+      cpuprof: active ? (record?.cpuprof ?? 0) : 0,
+      read,
+      record,
+    };
+  }
+  // auto / manual measure anyway; a persisted run token still applies until it expires.
+  const token = live(record, nowMs) ? (record?.runToken ?? null) : null;
+  return {
+    mode,
+    active: true,
+    runToken: token,
+    expiresAt: token ? (record?.expiresAt ?? null) : null,
+    diag: token !== null && record?.diag === true,
+    profile: token !== null && record?.profile === true,
+    cpuprof: token !== null ? (record?.cpuprof ?? 0) : 0,
+    read,
+    record,
+  };
+};
+
+const ttlMs = (value: string | undefined) => {
+  const parsed = Number(value);
+  const seconds =
+    value === undefined || value === '' || !Number.isFinite(parsed) || parsed <= 0
+      ? DEFAULT_TTL_S
+      : Math.min(MAX_TTL_S, parsed);
+  return seconds * 1000;
+};
+
+const truthy = (value: string) => value === '1' || value === 'true';
+
+// `cpuprof=1`/`true` samples at `cpuhz` (or 250 Hz); a number above 1 is the
+// rate itself; `0` is off.
+const cpuprofFromLink = (params: Record<string, string>) => {
+  const value = params.cpuprof;
+  if (value === undefined || value === '0' || value === 'false') {
+    return 0;
+  }
+  if (truthy(value)) {
+    return hzOf(Number(params.cpuhz)) || DEFAULT_CPU_HZ;
+  }
+  return hzOf(Number(value));
+};
+
+// The record a settings link asks for, or null when it does not touch activation.
+// `activate=1` (with `runToken`, `ttl`, `diag`, `profile`, `cpuprof`, `cpuhz`),
+// `activate=0`, or a bare `runToken` (keeps the current activation, empty
+// clears the token; `diag`, `profile` and `cpuprof` kept unless given).
+export const recordFromLink = (
+  params: Record<string, string>,
+  current: ActivationRecord | null,
+  nowMs: number,
+): ActivationRecord | null => {
+  if (params.activate !== undefined) {
+    if (truthy(params.activate)) {
+      return {
+        active: true,
+        runToken: params.runToken ? params.runToken : null,
+        expiresAt: nowMs + ttlMs(params.ttl),
+        diag: params.diag !== undefined && truthy(params.diag),
+        profile: params.profile !== undefined && truthy(params.profile),
+        cpuprof: cpuprofFromLink(params),
+      };
+    }
+    return { ...OFF };
+  }
+  if (params.runToken !== undefined) {
+    const kept = live(current, nowMs) ? current : null;
+    return {
+      active: kept?.active === true,
+      runToken: params.runToken === '' ? null : params.runToken,
+      expiresAt: nowMs + ttlMs(params.ttl),
+      diag: params.diag !== undefined ? truthy(params.diag) : kept?.diag === true,
+      profile:
+        params.profile !== undefined ? truthy(params.profile) : kept?.profile === true,
+      cpuprof:
+        params.cpuprof !== undefined ? cpuprofFromLink(params) : (kept?.cpuprof ?? 0),
+    };
+  }
+  return null;
+};
+
+export const parseQuery = (
+  query: string | undefined,
+): Record<string, string> => {
+  if (!query) {
+    return {};
+  }
+  const out: Record<string, string> = {};
+  for (const pair of query.split('&')) {
+    const [key = '', ...rest] = pair.split('=');
+    try {
+      out[decodeURIComponent(key)] = decodeURIComponent(rest.join('='));
+    } catch {
+      out[key] = rest.join('=');
+    }
+  }
+  return out;
+};
+
+export const queryOf = (url: string) => parseQuery(url.split('?')[1]);
+
+interface ActivationGlobal {
+  __PERFLAB_ACTIVATION__?: PolyfillActivation;
+  __PERFLAB_HOOK__?: { ensure: () => string };
+  expo?: { modules?: Record<string, unknown> };
+}
+
+const g = globalThis as unknown as ActivationGlobal;
+
+const isNative = (value: unknown): value is ActivationNative =>
+  !!value &&
+  typeof (value as ActivationNative).activationRead === 'function' &&
+  typeof (value as ActivationNative).activationWrite === 'function';
+
+// Found lazily: only links and a deferred startup read need it.
+export const findActivationNative = (): ActivationNative | null => {
+  const direct = g.expo?.modules?.PerfLab;
+  if (isNative(direct)) {
+    return direct;
+  }
+  if (g.expo?.modules) {
+    return null;
+  }
+  // Android may install `expo.modules` only when expo-modules-core first loads.
+  try {
+    const core = require('expo-modules-core') as {
+      requireOptionalNativeModule?: (name: string) => unknown;
+    };
+    const found = core.requireOptionalNativeModule?.('PerfLab');
+    return isNative(found) ? found : null;
+  } catch {
+    return null;
+  }
+};
+
+// One decision per process, taken by the boot module.
+export const resolveDecision = (
+  nowMs: number = Date.now(),
+  findNative: () => ActivationNative | null = findActivationNative,
+): Decision => {
+  const fromPolyfill = g.__PERFLAB_ACTIVATION__;
+  if (MODE !== 'dormant') {
+    // Not gated: the record only carries a persisted token, read when it is cheap.
+    if (fromPolyfill && fromPolyfill.read === 'polyfill') {
+      return decide(MODE, parseRecord(fromPolyfill.raw), fromPolyfill.t, 'polyfill');
+    }
+    let raw: string | null = null;
+    let read: ActivationRead = 'unavailable';
+    try {
+      const native = findNative();
+      if (native) {
+        raw = native.activationRead();
+        read = 'boot';
+      }
+    } catch {
+      read = 'unavailable';
+    }
+    return decide(MODE, parseRecord(raw), nowMs, read);
+  }
+  if (fromPolyfill && fromPolyfill.read === 'polyfill') {
+    return decide(MODE, parseRecord(fromPolyfill.raw), fromPolyfill.t, 'polyfill');
+  }
+  // The polyfill could not reach the native module: read now, still before the
+  // React renderer loads (it loads when the app's root component first renders).
+  let decision: Decision;
+  try {
+    const native = findNative();
+    decision = native
+      ? decide(MODE, parseRecord(native.activationRead()), nowMs, 'boot')
+      : decide(MODE, null, nowMs, 'unavailable');
+  } catch {
+    decision = decide(MODE, null, nowMs, 'unavailable');
+  }
+  if (decision.active) {
+    g.__PERFLAB_HOOK__?.ensure();
+  }
+  // The polyfill could not choose the renderer; boot still runs before it loads.
+  if (fromPolyfill && fromPolyfill.read === 'deferred') {
+    fromPolyfill.profile = decision.profile;
+  }
+  return decision;
+};
+
+// Links in this process change the record for the NEXT launch only.
+export const createActivationStore = (
+  initial: ActivationRecord | null,
+  findNative: () => ActivationNative | null = findActivationNative,
+) => {
+  let current = initial;
+  let writes = 0;
+  let lastError: string | null = null;
+  return {
+    current: () => current,
+    stats: () => ({ writes, lastError }),
+    // Returns the written record, or null when the link does not touch activation.
+    apply(params: Record<string, string>, nowMs: number = Date.now()) {
+      const next = recordFromLink(params, current, nowMs);
+      if (!next) {
+        return null;
+      }
+      try {
+        const native = findNative();
+        if (!native) {
+          lastError = 'native module unavailable';
+          return null;
+        }
+        if (!native.activationWrite(JSON.stringify(next))) {
+          lastError = 'write failed';
+          return null;
+        }
+        current = next;
+        writes++;
+        lastError = null;
+        return next;
+      } catch (error) {
+        lastError = String(error);
+        return null;
+      }
+    },
+  };
+};
+
+export type ActivationStore = ReturnType<typeof createActivationStore>;

package/js/sdk/active.ts

@@ -0,0 +1,62 @@
+// The measuring SDK. boot.ts requires this module only when the process
+// measures: always in auto/manual builds, after an activation in dormant ones.
+
+import { createActivationStore, type Decision } from './activation';
+import {
+  addStartupSection,
+  applySettings,
+  attachHook,
+  exposeGlobal,
+  handlePerfLabDeepLink,
+  logStartup,
+  perfLog,
+  setActivation,
+} from './core';
+import { causeStats, installCauses } from './causes';
+import { installInteractions, interactionStats } from './interactions';
+import { installLinks, linkPatchStatus, redactUrl } from './links';
+import { installNav } from './nav';
+import { installNet } from './net-install';
+import { installPush } from './push-install';
+import { installScreens, noteAppLink, screenStats } from './screens';
+
+const guarded = (label: string, run: () => void) => {
+  try {
+    run();
+  } catch (error) {
+    globalThis.console.log(
+      `PERF_LAB boot step failed ${label} ${String(error)}`,
+    );
+  }
+};
+
+export const startActive = (decision: Decision) => {
+  setActivation(decision, createActivationStore(decision.record));
+  // First: it wraps the timers and the scheduler before the app's modules and the renderer read them.
+  guarded('causes', () => installCauses());
+  guarded('hook', attachHook);
+  guarded('global', exposeGlobal);
+  guarded('settings', () => applySettings({}));
+  guarded('links', () =>
+    installLinks(
+      (url, via) => {
+        perfLog(`link via=${via} ${redactUrl(url)}`);
+        handlePerfLabDeepLink(url);
+      },
+      noteAppLink,
+    ),
+  );
+  guarded('interactions', installInteractions);
+  guarded('net', installNet);
+  guarded('nav', installNav);
+  guarded('screens', installScreens);
+  guarded('push', installPush);
+  addStartupSection('causes', () => ({ ...causeStats }));
+  addStartupSection('interactions', interactionStats);
+  addStartupSection('screens', screenStats);
+  addStartupSection('links', linkPatchStatus);
+  logStartup('boot');
+  // By now the renderer has injected into the hook and Expo has installed its
+  // native modules, so the second report shows both.
+  setTimeout(() => logStartup('boot+5s'), 5000);
+};