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

package/js/sdk/artifacts.ts

@@ -0,0 +1,632 @@
+// Raw profile files of a run (Hermes .cpuprofile, React exports) that go to
+// the API at `flush=1`: which ones are kept, the manifest that lists them, and
+// the upload (signed URL from the API, gzip + PUT by the native module, then
+// `complete`). Pure logic with injected deps so it runs under bun; core.ts and
+// push-install.ts wire it. Contract: docs/plans/40-profiler-foundation.md §3.6.
+
+export type ArtifactKind = 'cpuprofile' | 'react-export' | 'commit-stream';
+
+// Why a file is kept: the iteration is diagnostic, or one of its windows broke
+// a budget on the device (a commit longer than a frame, a long task > 50 ms).
+export type ArtifactReason = 'diag' | 'frame-budget' | 'long-task' | 'stream';
+
+export type ArtifactState =
+  // listed, not sent yet (or a window opened before it could be)
+  | 'pending'
+  | 'uploaded'
+  // stays on the device only: no endpoint, no native upload, no push config
+  | 'local'
+  // the API refused it (size, kind); retrying cannot help
+  | 'rejected'
+  // gave up after retries
+  | 'failed';
+
+export interface ArtifactEntry {
+  name: string;
+  kind: ArtifactKind;
+  reasons: ArtifactReason[];
+  windows: number[];
+  bytes: number | null;
+  state: ArtifactState;
+  artifactId: string | null;
+  gzBytes: number | null;
+  sha256: string | null;
+  attempts: number;
+  error: string | null;
+  // The run token current when the file was recorded: it goes up under this
+  // one only, also after a later link changed the token. In memory only; the
+  // manifest on disk leaves it out. Absent: the token given to upload().
+  runToken?: string | null;
+}
+
+export const LONG_TASK_MS = 50;
+
+// The API budget for one run's artifact calls (apps/api/src/modules/artifacts/service.ts has the same three numbers;
+// a test in the api package keeps them equal): the per-run file cap, the calls one file costs (announce + complete)
+// and the calls per minute the run may make. A full export therefore fits in
+// 500 files x 2 calls / 200 calls per minute = 5 minutes, which is the longest the SDK keeps uploading.
+export const ARTIFACT_MAX_FILES_PER_RUN = 500;
+export const ARTIFACT_CALLS_PER_FILE = 2;
+export const ARTIFACT_CALLS_PER_MINUTE = 200;
+export const ARTIFACT_UPLOAD_DEADLINE_MS =
+  ((ARTIFACT_MAX_FILES_PER_RUN * ARTIFACT_CALLS_PER_FILE) / ARTIFACT_CALLS_PER_MINUTE) * 60_000;
+export const ARTIFACT_REQUEST_TIMEOUT_MS = 15_000;
+export const ARTIFACT_PUT_TIMEOUT_MS = 60_000;
+// One deadline per flush, started at the flush link (core.ts flushOnce) and shared by the lines push, the clock
+// report and the artifact upload (this file's ARTIFACT_UPLOAD_DEADLINE_MS is that deadline). The end report gets its
+// own request timeout after it, so `perflab.flushed` is raised at most ARTIFACT_FLUSH_WORST_CASE_MS after the link.
+// The e2e driver's wait for it is derived from this.
+export const ARTIFACT_FLUSH_WORST_CASE_MS = ARTIFACT_UPLOAD_DEADLINE_MS + ARTIFACT_REQUEST_TIMEOUT_MS;
+// Longest pause between two attempts at one file. SDK choice: half the Retry-After cap below, so a failing file never
+// waits longer than a rate-limited one is told to.
+export const ARTIFACT_BACKOFF_MAX_MS = 30_000;
+
+// 429 without a usable Retry-After: wait this long. Source: the API's per-run budget is 200 calls a minute
+// (apps/api/src/modules/artifacts/service.ts), so a one second pause lets a few calls refill.
+export const ARTIFACT_DEFAULT_429_WAIT_MS = 1000;
+// The longest Retry-After the SDK honours (the API's rate-limit window is one minute).
+export const ARTIFACT_MAX_RETRY_AFTER_MS = 60_000;
+
+export interface WrittenFile {
+  name: string;
+  windows: number[];
+  bytes: number | null;
+}
+
+// Diagnostic iteration: every file. Otherwise only files that cover a window
+// that broke a budget (a CPU span covers several windows).
+export const selectArtifacts = (input: {
+  diag: boolean;
+  runToken?: string | null;
+  breaks: ReadonlyMap<number, readonly ArtifactReason[]>;
+  cpu: WrittenFile | null;
+  exports: WrittenFile[];
+  /** Commit-stream segments: kept in every run, the backend splits work by cause from them. */
+  stream?: WrittenFile[];
+}): ArtifactEntry[] => {
+  const out: ArtifactEntry[] = [];
+  const add = (kind: ArtifactKind, file: WrittenFile) => {
+    let reasons: ArtifactReason[];
+    if (kind === 'commit-stream') {
+      reasons = ['stream'];
+    } else if (input.diag) {
+      reasons = ['diag'];
+    } else {
+      const found = new Set<ArtifactReason>();
+      for (const id of file.windows) {
+        for (const reason of input.breaks.get(id) ?? []) {
+          found.add(reason);
+        }
+      }
+      reasons = [...found].sort();
+    }
+    if (reasons.length === 0) {
+      return;
+    }
+    out.push({
+      name: file.name,
+      kind,
+      reasons,
+      windows: [...file.windows],
+      bytes: file.bytes,
+      state: 'pending',
+      artifactId: null,
+      gzBytes: null,
+      sha256: null,
+      attempts: 0,
+      error: null,
+      ...(input.runToken !== undefined ? { runToken: input.runToken } : {}),
+    });
+  };
+  if (input.cpu) {
+    add('cpuprofile', input.cpu);
+  }
+  for (const file of input.exports) {
+    add('react-export', file);
+  }
+  for (const file of input.stream ?? []) {
+    add('commit-stream', file);
+  }
+  return out;
+};
+
+export const manifestName = (processId: string) => `artifacts-${processId}.json`;
+
+export const buildManifest = (input: {
+  processId: string;
+  diag: boolean;
+  frameBudgetMs: number;
+  artifacts: ArtifactEntry[];
+  upload: ArtifactUploadSummary | null;
+}) => ({
+  v: 1,
+  processId: input.processId,
+  diag: input.diag,
+  frameBudgetMs: input.frameBudgetMs,
+  artifacts: input.artifacts.map(withoutToken),
+  upload: input.upload,
+});
+
+const withoutToken = (entry: ArtifactEntry): Omit<ArtifactEntry, 'runToken'> => {
+  const { runToken: _token, ...rest } = entry;
+  return rest;
+};
+
+// Gzips the file (named as written by writeText / cpuProfileDump), hashes the
+// gzip, PUTs it. status 0: no HTTP answer (network, timeout, missing file).
+export interface ArtifactUploadNative {
+  artifactUpload(
+    fileName: string,
+    url: string,
+    headers: Record<string, string>,
+    timeoutMs: number,
+  ): Promise<{
+    status: number;
+    bytes?: number;
+    gzBytes?: number;
+    sha256?: string;
+    error?: string | null;
+  }>;
+}
+
+export interface ArtifactHttpResponse {
+  status: number;
+  headers?: { get(name: string): string | null };
+  json: () => Promise<unknown>;
+}
+
+export interface ArtifactUploaderDeps {
+  url: string;
+  key: string;
+  fetch: (url: string, init: Record<string, unknown>) => Promise<ArtifactHttpResponse>;
+  native: () => ArtifactUploadNative | null;
+  isWindowOpen: () => boolean;
+  now: () => number;
+  sleep: (ms: number) => Promise<void>;
+  log: (message: string) => void;
+  // Per artifact, the request, PUT and complete are each tried this many times.
+  maxAttempts?: number;
+  backoffBaseMs?: number;
+  requestTimeoutMs?: number;
+  putTimeoutMs?: number;
+  // Files in flight at once: the upload must finish inside the driver's wait for the
+  // flush signal, and one file after the other (about 0.85 s each) took 115 s for 135.
+  concurrency?: number;
+  // The whole upload stops here; the rest stays on the device as `failed` and goes up
+  // at the next flush. Default: the time the API's per-run budget needs for a full run.
+  deadlineMs?: number;
+}
+
+export interface ArtifactUploadSummary {
+  total: number;
+  uploaded: number;
+  local: number;
+  rejected: number;
+  failed: number;
+  pending: number;
+  ms: number;
+  // why the upload stopped early, if it did
+  stopped: string | null;
+}
+
+export const summarizeArtifacts = (
+  entries: ArtifactEntry[],
+  ms: number,
+  stopped: string | null,
+): ArtifactUploadSummary => {
+  const count = (state: ArtifactState) => entries.filter(e => e.state === state).length;
+  return {
+    total: entries.length,
+    uploaded: count('uploaded'),
+    local: count('local'),
+    rejected: count('rejected'),
+    failed: count('failed'),
+    pending: count('pending'),
+    ms,
+    stopped,
+  };
+};
+
+interface SignedUpload {
+  artifactId: string;
+  done: boolean;
+  url: string | null;
+  headers: Record<string, string>;
+}
+
+type Step<T> =
+  | { ok: true; value: T }
+  | {
+      ok: false;
+      retry: boolean;
+      stop: string | null;
+      state: ArtifactState;
+      error: string;
+      // 429: not an attempt; wait this long (the API's Retry-After) and ask again.
+      waitMs?: number;
+    };
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const transient = (status: number) => status === 0 || status === 408 || status === 429 || status >= 500;
+
+const stringHeaders = (value: unknown): Record<string, string> => {
+  const out: Record<string, string> = {};
+  if (isObject(value)) {
+    for (const [k, v] of Object.entries(value)) {
+      if (typeof v === 'string') {
+        out[k] = v;
+      }
+    }
+  }
+  return out;
+};
+
+export const parseSignedUpload = (body: unknown): SignedUpload | null => {
+  if (!isObject(body) || typeof body.artifact_id !== 'string') {
+    return null;
+  }
+  if (body.status === 'complete') {
+    return { artifactId: body.artifact_id, done: true, url: null, headers: {} };
+  }
+  const upload = isObject(body.upload) ? body.upload : null;
+  if (!upload || typeof upload.url !== 'string') {
+    return null;
+  }
+  if (upload.method !== undefined && upload.method !== 'PUT') {
+    return null;
+  }
+  return {
+    artifactId: body.artifact_id,
+    done: false,
+    url: upload.url,
+    headers: stringHeaders(upload.headers),
+  };
+};
+
+export const createArtifactUploader = (deps: ArtifactUploaderDeps) => {
+  const base = deps.url.replace(/\/+$/, '');
+  const maxAttempts = deps.maxAttempts ?? 3;
+  const backoffBase = deps.backoffBaseMs ?? 1000;
+  const requestTimeoutMs = deps.requestTimeoutMs ?? ARTIFACT_REQUEST_TIMEOUT_MS;
+  const putTimeoutMs = deps.putTimeoutMs ?? ARTIFACT_PUT_TIMEOUT_MS;
+  const deadlineMs = deps.deadlineMs ?? ARTIFACT_UPLOAD_DEADLINE_MS;
+  const concurrency = Math.max(1, deps.concurrency ?? 4);
+
+  // Rejects after `ms`: a hard bound for work that may ignore its abort signal (a hung fetch, a native PUT).
+  const timeoutAfter = (ms: number) => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const promise = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => reject(new Error('timeout')), ms);
+    });
+    promise.catch(() => undefined);
+    return { promise, clear: () => clearTimeout(timer) };
+  };
+
+  // `limit` is the absolute time (deps.now) the call must be over by; the request timeout applies inside it.
+  const post = async (
+    path: string,
+    token: string,
+    body: Record<string, unknown>,
+    limit: number,
+  ): Promise<{ status: number; body: unknown; error: string | null; retryAfterMs: number | null }> => {
+    const budget = Math.min(requestTimeoutMs, limit - deps.now());
+    if (budget <= 0) {
+      return { status: 0, body: null, error: 'deadline', retryAfterMs: null };
+    }
+    const controller = typeof AbortController === 'function' ? new AbortController() : null;
+    const abortTimer = controller ? setTimeout(() => controller.abort(), budget) : null;
+    const hard = timeoutAfter(budget);
+    try {
+      const res = await Promise.race([
+        deps.fetch(`${base}${path}`, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            'x-perflab-key': deps.key,
+            'x-perflab-run-token': token,
+          },
+          body: JSON.stringify(body),
+          ...(controller ? { signal: controller.signal } : {}),
+        }),
+        hard.promise,
+      ]);
+      let parsed: unknown = null;
+      try {
+        parsed = await Promise.race([res.json(), hard.promise]);
+      } catch {
+        parsed = null;
+      }
+      const seconds = Number(res.headers?.get('retry-after'));
+      const retryAfterMs =
+        Number.isFinite(seconds) && seconds > 0 ? Math.min(ARTIFACT_MAX_RETRY_AFTER_MS, seconds * 1000) : null;
+      return { status: res.status, body: parsed, error: null, retryAfterMs };
+    } catch (error) {
+      return { status: 0, body: null, error: String(error), retryAfterMs: null };
+    } finally {
+      if (abortTimer !== null) {
+        clearTimeout(abortTimer);
+      }
+      hard.clear();
+    }
+  };
+
+  // Maps an API answer that is not a success to what happens next.
+  const failure = (
+    what: string,
+    status: number,
+    error: string | null,
+    retryAfterMs: number | null = null,
+  ): Step<never> => {
+    const text = `${what} ${status === 0 ? (error ?? 'no response') : `http ${status}`}`;
+    if (status === 404) {
+      return { ok: false, retry: false, stop: 'artifact endpoint absent', state: 'local', error: text };
+    }
+    if (status === 401 || status === 403) {
+      return { ok: false, retry: false, stop: `not authorised (${status})`, state: 'local', error: text };
+    }
+    if (status === 429) {
+      return { ok: false, retry: true, stop: null, state: 'failed', error: text, waitMs: retryAfterMs ?? ARTIFACT_DEFAULT_429_WAIT_MS };
+    }
+    if (transient(status)) {
+      return { ok: false, retry: true, stop: null, state: 'failed', error: text };
+    }
+    return { ok: false, retry: false, stop: null, state: 'rejected', error: text };
+  };
+
+  const request = async (
+    entry: ArtifactEntry,
+    token: string,
+    processId: string,
+    deadline: number,
+  ): Promise<Step<SignedUpload>> => {
+    const res = await post('/v1/artifacts', token, {
+      client_id: entry.name,
+      kind: entry.kind,
+      name: entry.name,
+      process_id: processId,
+      windows: entry.windows,
+      reasons: entry.reasons,
+      bytes: entry.bytes,
+      content_type: 'application/gzip',
+    }, deadline);
+    if (res.status === 200 || res.status === 201) {
+      const signed = parseSignedUpload(res.body);
+      return signed
+        ? { ok: true, value: signed }
+        : { ok: false, retry: false, stop: null, state: 'failed', error: 'request: unreadable answer' };
+    }
+    return failure('request', res.status, res.error, res.retryAfterMs);
+  };
+
+  const put = async (entry: ArtifactEntry, signed: SignedUpload, deadline: number): Promise<Step<null>> => {
+    const native = deps.native();
+    if (!native) {
+      return { ok: false, retry: false, stop: 'native upload unavailable', state: 'local', error: 'native upload unavailable' };
+    }
+    const budget = Math.min(putTimeoutMs, deadline - deps.now());
+    if (budget <= 0) {
+      return { ok: false, retry: false, stop: 'deadline', state: 'failed', error: 'put deadline' };
+    }
+    let result: Awaited<ReturnType<ArtifactUploadNative['artifactUpload']>>;
+    const hard = timeoutAfter(budget);
+    try {
+      result = await Promise.race([
+        native.artifactUpload(entry.name, signed.url as string, signed.headers, budget),
+        hard.promise,
+      ]);
+    } catch (error) {
+      return { ok: false, retry: true, stop: null, state: 'failed', error: `put ${String(error)}` };
+    } finally {
+      hard.clear();
+    }
+    if (typeof result.gzBytes === 'number') entry.gzBytes = result.gzBytes;
+    if (typeof result.sha256 === 'string') entry.sha256 = result.sha256;
+    if (typeof result.bytes === 'number') entry.bytes = result.bytes;
+    if (result.status >= 200 && result.status < 300) {
+      return { ok: true, value: null };
+    }
+    // A signed URL that expired or was refused: ask for a new one.
+    const retry = transient(result.status) || result.status === 400 || result.status === 403;
+    return {
+      ok: false,
+      retry,
+      stop: null,
+      state: 'failed',
+      error: `put ${result.status === 0 ? (result.error ?? 'no response') : `http ${result.status}`}`,
+    };
+  };
+
+  const complete = async (
+    entry: ArtifactEntry,
+    artifactId: string,
+    token: string,
+    deadline: number,
+  ): Promise<Step<null>> => {
+    const res = await post(`/v1/artifacts/${encodeURIComponent(artifactId)}/complete`, token, {
+      sha256: entry.sha256,
+      gz_bytes: entry.gzBytes,
+      bytes: entry.bytes,
+    }, deadline);
+    if (res.status === 200 || res.status === 201) {
+      return { ok: true, value: null };
+    }
+    if (res.status === 409) {
+      // The object in storage is not what we hashed: send it again.
+      return { ok: false, retry: true, stop: null, state: 'failed', error: 'complete http 409' };
+    }
+    return failure('complete', res.status, res.error, res.retryAfterMs);
+  };
+
+  // One artifact, request -> PUT -> complete, each failure retried as a whole.
+  const uploadOne = async (
+    entry: ArtifactEntry,
+    token: string,
+    processId: string,
+    deadline: number,
+  ): Promise<string | null> => {
+    while (entry.attempts < maxAttempts) {
+      if (deps.isWindowOpen()) {
+        return 'window open';
+      }
+      if (deps.now() > deadline) {
+        return 'deadline';
+      }
+      entry.attempts++;
+      const signed = await request(entry, token, processId, deadline);
+      let step: Step<unknown> = signed;
+      if (signed.ok) {
+        entry.artifactId = signed.value.artifactId;
+        if (signed.value.done) {
+          entry.state = 'uploaded';
+          entry.error = null;
+          return null;
+        }
+        if (deps.isWindowOpen()) {
+          // The PUT is the heavy part: it waits for the next flush instead.
+          entry.attempts--;
+          entry.state = 'pending';
+          return 'window open';
+        }
+        step = await put(entry, signed.value, deadline);
+        if (step.ok) {
+          step = await complete(entry, signed.value.artifactId, token, deadline);
+        }
+      }
+      if (step.ok) {
+        entry.state = 'uploaded';
+        entry.error = null;
+        return null;
+      }
+      entry.state = step.state;
+      entry.error = step.error;
+      if (step.stop !== null) {
+        return step.stop;
+      }
+      if (!step.retry) {
+        return null;
+      }
+      if (step.waitMs !== undefined) {
+        // Asked to slow down: not the file's fault, so not one of its attempts.
+        entry.attempts--;
+        if (deps.now() + step.waitMs >= deadline) {
+          return 'deadline';
+        }
+        await deps.sleep(step.waitMs);
+        continue;
+      }
+      if (entry.attempts < maxAttempts) {
+        const wait = Math.min(ARTIFACT_BACKOFF_MAX_MS, backoffBase * 2 ** (entry.attempts - 1));
+        if (deps.now() + wait >= deadline) {
+          return 'deadline';
+        }
+        await deps.sleep(wait);
+      }
+    }
+    return null;
+  };
+
+  // Tells the API how many files this flush holds and how it went, so a run whose upload
+  // was cut (the app killed, a stop) shows as partial in the data. Numbers only; the
+  // backend judges. Sent before the first file and after the last; never throws.
+  const report = async (
+    entries: ArtifactEntry[],
+    token: string | null,
+    phase: 'start' | 'end',
+    limit: number,
+    stoppedReason: string | null = null,
+  ) => {
+    const byToken = new Map<string, ArtifactEntry[]>();
+    for (const entry of entries) {
+      const own = entry.runToken !== undefined ? entry.runToken : token;
+      if (own !== null) {
+        byToken.set(own, [...(byToken.get(own) ?? []), entry]);
+      }
+    }
+    await Promise.all(
+      Array.from(byToken, ([own, group]) => {
+        const counts = summarizeArtifacts(group, 0, null);
+        return post('/v1/artifacts/flush', own, {
+          phase,
+          created: counts.total,
+          uploaded: counts.uploaded,
+          pending: counts.pending,
+          failed: counts.failed,
+          rejected: counts.rejected,
+          local: counts.local,
+          stopped: phase === 'end' ? stoppedReason : null,
+        }, limit);
+      }),
+    );
+  };
+
+  // Sends every pending entry under the run token it was recorded with;
+  // mutates their state. Never throws. A token the API refuses (401/403)
+  // leaves its files local and the files of other tokens go on.
+  const upload = async (
+    entries: ArtifactEntry[],
+    token: string | null,
+    processId: string,
+    flushDeadline?: number,
+  ): Promise<ArtifactUploadSummary> => {
+    const t0 = deps.now();
+    const deadline = flushDeadline ?? t0 + deadlineMs;
+    let stopped: string | null = null;
+    let refusedStop: string | null = null;
+    let noToken = false;
+    const refused = new Set<string>();
+    const todo = entries.filter(e => e.state === 'pending' || e.state === 'failed');
+    for (const entry of todo) {
+      entry.attempts = 0;
+    }
+    await report(entries, token, 'start', deadline);
+    const worker = async () => {
+      for (let entry = todo.shift(); entry !== undefined && stopped === null; entry = todo.shift()) {
+        const own = entry.runToken !== undefined ? entry.runToken : token;
+        if (own === null || refused.has(own)) {
+          noToken = noToken || own === null;
+          entry.state = 'local';
+          entry.error = entry.error ?? (own === null ? 'no run token' : refusedStop);
+          continue;
+        }
+        try {
+          const stop = await uploadOne(entry, own, processId, deadline);
+          if (stop !== null && stop.startsWith('not authorised')) {
+            refused.add(own);
+            refusedStop = stop;
+          } else if (stop !== null) {
+            stopped = stopped ?? stop;
+          }
+        } catch (error) {
+          entry.state = 'failed';
+          entry.error = String(error);
+        }
+      }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, todo.length) }, worker));
+    if (stopped !== null) {
+      for (const entry of entries) {
+        if (entry.state === 'pending') {
+          if (stopped === 'deadline') {
+            entry.state = 'failed';
+          } else if (stopped !== 'window open') {
+            entry.state = 'local';
+          }
+          entry.error = entry.error ?? stopped;
+        }
+      }
+    }
+    const reported = stopped ?? refusedStop ?? (noToken ? 'no run token' : null);
+    if (reported !== null) {
+      deps.log(`artifacts upload stopped: ${reported}`);
+    }
+    const summary = summarizeArtifacts(entries, deps.now() - t0, reported);
+    await report(entries, token, 'end', deps.now() + requestTimeoutMs, reported);
+    return summary;
+  };
+
+  return { upload };
+};
+
+export type ArtifactUploader = ReturnType<typeof createArtifactUploader>;

package/js/sdk/boot.ts

@@ -0,0 +1,21 @@
+// perf-lab SDK entry. withPerfLab (metro.js) adds this module to the graph and
+// runs it after InitializeCore, before the app's entry module. The React hook
+// itself was installed earlier by hook.polyfill.js (unless dormant).
+//
+// The measuring SDK (active.ts and everything it imports) is required only when
+// this process measures, so a dormant process never evaluates it.
+
+import { type Decision, PERF_LAB_ENABLED, resolveDecision } from './activation';
+
+if (PERF_LAB_ENABLED) {
+  try {
+    const decision: Decision = resolveDecision();
+    if (decision.active) {
+      (require('./active') as typeof import('./active')).startActive(decision);
+    } else {
+      (require('./dormant') as typeof import('./dormant')).startDormant(decision);
+    }
+  } catch (error) {
+    globalThis.console.log(`PERF_LAB boot failed ${String(error)}`);
+  }
+}