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

package/js/sdk/push.ts

@@ -0,0 +1,819 @@
+// Push client: sends window lines to the farm ingest (POST /v1/windows) so a
+// device farm needs no tunnel. Pure logic with injected deps so it runs under
+// bun without React Native (see push-install.ts for the wiring).
+//
+// The run token is taken when a line is queued, not when it is sent, and a
+// batch never mixes tokens: a window belongs to the run that was current when
+// it was recorded. With a spool, every queued line is also journalled in the
+// app sandbox; lines a killed process never sent are queued again, with their
+// own token, by the next process that pushes (resume()). The journal is read
+// lazily (first send or explicit flush, never inside a measured window) and is
+// rewritten to the live queue whenever it outgrows twice the queue caps, so it
+// stays bounded while the ingest is unreachable.
+
+export interface DeviceInfo {
+  model: string | null;
+  os: string | null;
+  install_id: string;
+  app_build: string | null;
+  platform?: string | null;
+  // @keepsnappy/react-native version of the build (layer 0 fingerprint).
+  sdk_version?: string | null;
+}
+
+// Append-only journal of the queue (native file). `append` must not block.
+export interface PushSpool {
+  read(): string | null;
+  append(record: string): void;
+  replace(content: string): boolean;
+}
+
+export interface PushDeps {
+  url: string;
+  key: string;
+  fetch: (
+    url: string,
+    init: Record<string, unknown>,
+  ) => Promise<{ status: number; json?: () => Promise<unknown> }>;
+  now: () => number;
+  setTimer: (run: () => void, ms: number) => unknown;
+  clearTimer: (handle: unknown) => void;
+  isWindowOpen: () => boolean;
+  getRunToken: () => string | null;
+  getDevice: () => Promise<DeviceInfo>;
+  spool?: PushSpool | null;
+  // false: nothing is sent on its own (no idle timer, no retry timer); lines go
+  // out only on flushAll(), e.g. at the end of a measured farm iteration.
+  autoFlush?: boolean;
+  idleFlushMs?: number;
+  maxBatchBytes?: number;
+  maxBatchItems?: number;
+  maxQueueLines?: number;
+  maxQueueBytes?: number;
+  // The journal is rewritten to the live queue past these (default 2x the queue caps).
+  maxJournalBytes?: number;
+  maxJournalRecords?: number;
+  backoffBaseMs?: number;
+  backoffMaxMs?: number;
+  requestTimeoutMs?: number;
+}
+
+export interface PushStats {
+  enabled: boolean;
+  autoFlush: boolean;
+  queued: number;
+  queuedBytes: number;
+  enqueued: number;
+  dropped: number;
+  batchesSent: number;
+  batchesFailed: number;
+  batchesRejected: number;
+  linesSent: number;
+  bytesSent: number;
+  lastStatus: number | null;
+  lastError: string | null;
+  lastSentAt: number | null;
+  retryInMs: number | null;
+  resumed: number;
+  resumeDropped: number;
+  spoolErrors: number;
+  journalBytes: number;
+  journalRewrites: number;
+  // Round trips to the ingest not reported yet (plan 51 G1.4).
+  clockPending: number;
+}
+
+// One push round trip: t0/t3 this device's send/receive, t1/t2 the server's
+// receive/send. The server compares them with the Maestro host's own, which
+// says how far the window times and the step markers are apart.
+export interface ClockSample {
+  t0: number;
+  t1: number;
+  t2: number;
+  t3: number;
+}
+
+const MAX_CLOCK_SAMPLES = 16;
+
+const serverClock = async (res: { json?: () => Promise<unknown> }) => {
+  try {
+    const body = (await res.json?.()) as { clock?: { recv_ms?: unknown; send_ms?: unknown } } | undefined;
+    const t1 = body?.clock?.recv_ms;
+    const t2 = body?.clock?.send_ms;
+    return typeof t1 === 'number' && typeof t2 === 'number' ? { t1, t2 } : null;
+  } catch {
+    return null;
+  }
+};
+
+interface Item {
+  line: string;
+  bytes: number;
+  token: string | null;
+  // The process that recorded the line (its bootId) and its sequence there.
+  origin: string;
+  seq: number;
+  // Id of the batch this line was first sent in: a resend keeps exactly that batch.
+  batch?: string;
+}
+
+interface Batch {
+  id: string;
+  items: Item[];
+  token: string | null;
+  bytes: number;
+}
+
+interface SpoolAdd {
+  o: string;
+  s: number;
+  t: string | null;
+  l: string;
+}
+
+interface SpoolDone {
+  d: string;
+  s: number[];
+  // set when the lines were dropped (queue cap), not delivered
+  n?: number;
+}
+
+// The lines of one batch, journalled before it is first sent.
+interface SpoolBatch {
+  b: string;
+  o: string;
+  s: number[];
+}
+
+// Lines dropped (queue cap) before they were delivered, carried across rewrites.
+interface SpoolNote {
+  n: number;
+}
+
+export type PendingLine = SpoolAdd & { b?: string };
+
+// Lines still owed by earlier processes, in recording order, each with the
+// batch it was already sent in (if any), and the dropped-lines note.
+export const readSpool = (content: string | null): { pending: PendingLine[]; dropped: number } => {
+  if (!content) {
+    return { pending: [], dropped: 0 };
+  }
+  const adds = new Map<string, SpoolAdd>();
+  const batchOf = new Map<string, string>();
+  let dropped = 0;
+  for (const text of content.split('\n')) {
+    if (text === '') {
+      continue;
+    }
+    let record: Partial<SpoolAdd & SpoolDone & SpoolBatch & SpoolNote>;
+    try {
+      record = JSON.parse(text) as Partial<SpoolAdd & SpoolDone & SpoolBatch & SpoolNote>;
+    } catch {
+      // a line cut by a kill mid-write
+      continue;
+    }
+    if (typeof record.o === 'string' && typeof record.s === 'number' && typeof record.l === 'string') {
+      adds.set(`${record.o}:${record.s}`, {
+        o: record.o,
+        s: record.s,
+        t: typeof record.t === 'string' ? record.t : null,
+        l: record.l,
+      });
+    } else if (typeof record.d === 'string' && Array.isArray(record.s)) {
+      for (const seq of record.s) {
+        adds.delete(`${record.d}:${seq}`);
+      }
+      if (typeof record.n === 'number' && record.n > 0) {
+        dropped += record.n;
+      }
+    } else if (typeof record.b === 'string' && typeof record.o === 'string' && Array.isArray(record.s)) {
+      for (const seq of record.s) {
+        batchOf.set(`${record.o}:${seq}`, record.b);
+      }
+    } else if (typeof record.n === 'number' && record.n > 0) {
+      dropped += record.n;
+    }
+  }
+  const pending = [...adds.values()].map(add => {
+    const b = batchOf.get(`${add.o}:${add.s}`);
+    return b === undefined ? add : { ...add, b };
+  });
+  return { pending, dropped };
+};
+
+export const pendingFromSpool = (content: string | null): PendingLine[] =>
+  readSpool(content).pending;
+
+const utf8Length = (text: string) => {
+  let n = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    if (c < 0x80) {
+      n += 1;
+    } else if (c < 0x800) {
+      n += 2;
+    } else if (c >= 0xd800 && c <= 0xdbff) {
+      n += 4;
+      i++;
+    } else {
+      n += 3;
+    }
+  }
+  return n;
+};
+
+// Retrying cannot fix these; the batch is dropped instead of blocking the queue.
+const isPermanent = (status: number) =>
+  status >= 400 && status < 500 && status !== 408 && status !== 429;
+
+export const createPushClient = (deps: PushDeps) => {
+  const idleFlushMs = deps.idleFlushMs ?? 10_000;
+  const maxBatchBytes = deps.maxBatchBytes ?? 256 * 1024;
+  const maxBatchItems = deps.maxBatchItems ?? 400;
+  const maxQueueLines = deps.maxQueueLines ?? 2000;
+  const maxQueueBytes = deps.maxQueueBytes ?? 8 * 1024 * 1024;
+  const maxJournalBytes = deps.maxJournalBytes ?? 2 * maxQueueBytes;
+  const maxJournalRecords = deps.maxJournalRecords ?? 2 * maxQueueLines;
+  const backoffBase = deps.backoffBaseMs ?? 2000;
+  const backoffMax = deps.backoffMaxMs ?? 60_000;
+  const timeoutMs = deps.requestTimeoutMs ?? 15_000;
+  const endpoint = `${deps.url.replace(/\/+$/, '')}/v1/windows`;
+  // Set by flushAll: the time (deps.now) every request of that flush must be over by.
+  let flushLimit: number | null = null;
+  // Rejects after `ms`; a hard bound for a fetch that ignores its abort signal.
+  const timeoutAfter = (ms: number) => {
+    let handle: unknown;
+    const promise = new Promise<never>((_, reject) => {
+      handle = deps.setTimer(() => reject(new Error('timeout')), ms);
+    });
+    promise.catch(() => undefined);
+    return { promise, clear: () => deps.clearTimer(handle) };
+  };
+  const clockEndpoint = `${deps.url.replace(/\/+$/, '')}/v1/clock`;
+  // Unique per process: two processes started in the same millisecond must not
+  // share line keys in the journal.
+  const bootId = `${deps.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+
+  const queue: Item[] = [];
+  const spool = deps.spool ?? null;
+  const autoFlush = deps.autoFlush ?? true;
+  let nextSeq = 0;
+  let queuedBytes = 0;
+  let retryBatch: Batch | null = null;
+  let attempts = 0;
+  let timer: unknown = null;
+  let retryAt: number | null = null;
+  let device: DeviceInfo | null = null;
+  let sending = false;
+  let resumed = false;
+  let journalBytes = 0;
+  let journalRecords = 0;
+  // Lines dropped before delivery, by this process and (from the note) earlier ones.
+  let undelivered = 0;
+  // Round trips not reported yet, each with the run token it was measured under.
+  let clockPending: { token: string; sample: ClockSample }[] = [];
+  const clockOf = (token: string | null) =>
+    token ? clockPending.filter(c => c.token === token).map(c => c.sample) : [];
+  const keepClock = (token: string, sample: ClockSample) => {
+    clockPending.push({ token, sample });
+    if (clockPending.length > MAX_CLOCK_SAMPLES) {
+      clockPending = clockPending.slice(-MAX_CLOCK_SAMPLES);
+    }
+  };
+  const dropClock = (sent: ClockSample[]) => {
+    clockPending = clockPending.filter(c => !sent.includes(c.sample));
+  };
+
+  const stats: PushStats = {
+    enabled: true,
+    autoFlush,
+    queued: 0,
+    queuedBytes: 0,
+    enqueued: 0,
+    dropped: 0,
+    batchesSent: 0,
+    batchesFailed: 0,
+    batchesRejected: 0,
+    linesSent: 0,
+    bytesSent: 0,
+    lastStatus: null,
+    lastError: null,
+    lastSentAt: null,
+    retryInMs: null,
+    resumed: 0,
+    resumeDropped: 0,
+    spoolErrors: 0,
+    journalBytes: 0,
+    journalRewrites: 0,
+    clockPending: 0,
+  };
+
+  const key = (origin: string, seq: number) => `${origin}:${seq}`;
+
+  // Owed lines in sending order: the batch being sent or retried, then the queue.
+  const owed = (): Item[] => [...(retryBatch?.items ?? []), ...queue];
+
+  // The journal becomes exactly the owed lines (and their batches), so its size
+  // follows the queue caps however long the ingest stays unreachable.
+  const rewrite = () => {
+    if (!spool) {
+      return;
+    }
+    const records: string[] = [];
+    if (undelivered > 0) {
+      records.push(JSON.stringify({ n: undelivered } satisfies SpoolNote));
+    }
+    const batches = new Map<string, SpoolBatch>();
+    for (const item of owed()) {
+      records.push(
+        JSON.stringify({ o: item.origin, s: item.seq, t: item.token, l: item.line } satisfies SpoolAdd),
+      );
+      if (item.batch !== undefined) {
+        const b = batches.get(item.batch) ?? { b: item.batch, o: item.origin, s: [] };
+        b.s.push(item.seq);
+        batches.set(item.batch, b);
+      }
+    }
+    for (const b of batches.values()) {
+      records.push(JSON.stringify(b));
+    }
+    const content = records.map(r => `${r}\n`).join('');
+    try {
+      spool.replace(content);
+      journalBytes = utf8Length(content);
+      journalRecords = records.length;
+      stats.journalRewrites++;
+    } catch {
+      stats.spoolErrors++;
+    }
+  };
+
+  const journal = (record: SpoolAdd | SpoolDone | SpoolBatch) => {
+    if (!spool) {
+      return;
+    }
+    const text = JSON.stringify(record);
+    try {
+      spool.append(text);
+    } catch {
+      stats.spoolErrors++;
+      return;
+    }
+    journalBytes += utf8Length(text) + 1;
+    journalRecords++;
+    if (journalBytes > maxJournalBytes || journalRecords > maxJournalRecords) {
+      if (!resumed) {
+        // resume() rewrites the journal itself, keeping earlier processes' lines.
+        resume();
+      } else {
+        rewrite();
+      }
+    }
+  };
+
+  const markDone = (items: Item[], dropped = false) => {
+    const byOrigin = new Map<string, number[]>();
+    for (const item of items) {
+      const list = byOrigin.get(item.origin) ?? [];
+      list.push(item.seq);
+      byOrigin.set(item.origin, list);
+    }
+    for (const [origin, seqs] of byOrigin) {
+      journal(dropped ? { d: origin, s: seqs, n: seqs.length } : { d: origin, s: seqs });
+    }
+  };
+
+  // Everything delivered: start the journal over so it never grows across a long session.
+  const compactIfIdle = () => {
+    if (spool && resumed && queue.length === 0 && !retryBatch) {
+      try {
+        spool.replace('');
+        journalBytes = 0;
+        journalRecords = 0;
+        undelivered = 0;
+      } catch {
+        stats.spoolErrors++;
+      }
+    }
+  };
+
+  const readStats = (): PushStats => ({
+    ...stats,
+    queued: queue.length + (retryBatch?.items.length ?? 0),
+    queuedBytes,
+    journalBytes,
+    clockPending: clockPending.length,
+    retryInMs: retryAt === null ? null : Math.max(0, retryAt - deps.now()),
+  });
+
+  const schedule = (ms: number) => {
+    if (!autoFlush) {
+      return;
+    }
+    if (timer !== null) {
+      deps.clearTimer(timer);
+    }
+    timer = deps.setTimer(() => {
+      timer = null;
+      void flush('timer');
+    }, ms);
+  };
+
+  // Drops the oldest queued lines above the caps.
+  const trim = () => {
+    const dropped: Item[] = [];
+    while (
+      queue.length > 1 &&
+      (queue.length > maxQueueLines || queuedBytes > maxQueueBytes)
+    ) {
+      const oldest = queue.shift();
+      if (oldest) {
+        queuedBytes -= oldest.bytes;
+        dropped.push(oldest);
+      }
+    }
+    undelivered += dropped.length;
+    return dropped;
+  };
+
+  const enqueue = (line: string) => {
+    const bytes = utf8Length(line);
+    if (bytes > maxBatchBytes) {
+      stats.dropped++;
+      undelivered++;
+      stats.lastError = `line of ${bytes} bytes exceeds batch limit`;
+      return;
+    }
+    const item: Item = {
+      line,
+      bytes,
+      token: deps.getRunToken(),
+      origin: bootId,
+      seq: nextSeq++,
+    };
+    queue.push(item);
+    queuedBytes += item.bytes;
+    stats.enqueued++;
+    const dropped = trim();
+    stats.dropped += dropped.length;
+    if (dropped.length > 0) {
+      markDone(dropped, true);
+    }
+    journal({ o: item.origin, s: item.seq, t: item.token, l: item.line });
+    if (timer === null) {
+      schedule(idleFlushMs);
+    }
+  };
+
+  // Queues what earlier processes recorded and never sent, ahead of this
+  // process's lines, and rewrites the journal to the owed lines. Runs once, at
+  // the first send or explicit flush (or when the journal outgrows its cap).
+  function resume(): number {
+    if (resumed) {
+      return 0;
+    }
+    resumed = true;
+    if (!spool) {
+      return 0;
+    }
+    let state: ReturnType<typeof readSpool>;
+    try {
+      state = readSpool(spool.read());
+    } catch {
+      stats.spoolErrors++;
+      return 0;
+    }
+    undelivered += state.dropped;
+    stats.resumeDropped += state.dropped;
+    const earlier: Item[] = [];
+    for (const record of state.pending) {
+      if (record.o === bootId) {
+        // journalled by this process before the resume: already queued
+        continue;
+      }
+      const bytes = utf8Length(record.l);
+      if (bytes > maxBatchBytes) {
+        stats.resumeDropped++;
+        undelivered++;
+        continue;
+      }
+      earlier.push({
+        line: record.l,
+        bytes,
+        token: record.t,
+        origin: record.o,
+        seq: record.s,
+        ...(record.b === undefined ? {} : { batch: record.b }),
+      });
+    }
+    queue.unshift(...earlier);
+    for (const item of earlier) {
+      queuedBytes += item.bytes;
+    }
+    const dropped = trim();
+    for (const item of dropped) {
+      if (item.origin === bootId) {
+        stats.dropped++;
+      } else {
+        stats.resumeDropped++;
+      }
+    }
+    const left = new Set(queue.map(item => key(item.origin, item.seq)));
+    const kept = earlier.filter(item => left.has(key(item.origin, item.seq))).length;
+    rewrite();
+    stats.resumed += kept;
+    if (queue.length > 0 && timer === null) {
+      schedule(idleFlushMs);
+    }
+    return kept;
+  }
+
+  const takeBatch = (): Batch | null => {
+    if (retryBatch) {
+      return retryBatch;
+    }
+    if (queue.length === 0) {
+      return null;
+    }
+    const first = queue[0] as Item;
+    const items: Item[] = [];
+    let bytes = 0;
+    if (first.batch !== undefined) {
+      // Already sent once (by a killed process): resend exactly that batch.
+      while (queue.length > 0 && queue[0]?.batch === first.batch) {
+        const next = queue.shift() as Item;
+        queuedBytes -= next.bytes;
+        items.push(next);
+        bytes += next.bytes;
+      }
+      return { id: first.batch, items, token: first.token, bytes };
+    }
+    while (queue.length > 0 && items.length < maxBatchItems) {
+      const next = queue[0];
+      if (
+        !next ||
+        next.batch !== undefined ||
+        next.token !== first.token ||
+        next.origin !== first.origin ||
+        (items.length > 0 && bytes + next.bytes > maxBatchBytes)
+      ) {
+        break;
+      }
+      queue.shift();
+      queuedBytes -= next.bytes;
+      items.push(next);
+      bytes += next.bytes;
+    }
+    return { id: '', items, token: first.token, bytes };
+  };
+
+  let inflight: Promise<void> | null = null;
+
+  const flush = (reason: string, force = false): Promise<void> => {
+    if (sending) {
+      return inflight ?? Promise.resolve();
+    }
+    inflight = sendNext(reason, force);
+    return inflight;
+  };
+
+  const sendNext = async (reason: string, force: boolean): Promise<void> => {
+    if (!force && deps.isWindowOpen()) {
+      // A measured window is open: never send inside it. Try again when idle.
+      if (queue.length > 0 || retryBatch) {
+        schedule(Math.min(idleFlushMs, 2000));
+      }
+      return;
+    }
+    if (!force && retryAt !== null && deps.now() < retryAt) {
+      schedule(retryAt - deps.now());
+      return;
+    }
+    resume();
+    if (flushLimit !== null && flushLimit - deps.now() <= 0) {
+      // The flush deadline is over: the lines stay queued (and in the journal) for the next flush.
+      return;
+    }
+    const batch = takeBatch();
+    if (!batch) {
+      return;
+    }
+    // Owed until the server answers: a rewrite meanwhile keeps its lines.
+    retryBatch = batch;
+    sending = true;
+    try {
+      if (!device) {
+        device = await deps.getDevice();
+      }
+      if (!batch.id) {
+        // Names exactly these lines (process, first and last sequence, count),
+        // so a different set of lines is always a different batch. It is
+        // journalled before the first send: a later process that resends after
+        // a kill sends the same lines under the same id, and the server's
+        // replay check can only ever drop lines it already has.
+        const first = batch.items[0] as Item;
+        const last = batch.items[batch.items.length - 1] as Item;
+        batch.id = `${device.install_id}-${first.origin}-${first.seq}-${last.seq}-${batch.items.length}`;
+        for (const item of batch.items) {
+          item.batch = batch.id;
+        }
+        journal({ b: batch.id, o: first.origin, s: batch.items.map(item => item.seq) });
+      }
+      const runToken = batch.token;
+      const reported = clockOf(runToken);
+      const body = JSON.stringify({
+        batch_id: batch.id,
+        device,
+        items: batch.items.map(item => item.line),
+        ...(runToken ? { run_token: runToken } : {}),
+        ...(reported.length ? { clock: reported } : {}),
+      });
+      const headers: Record<string, string> = {
+        'content-type': 'application/json',
+        'x-perflab-key': deps.key,
+      };
+      if (runToken) {
+        headers['x-perflab-run-token'] = runToken;
+      }
+      const budget = flushLimit !== null ? Math.max(1, Math.min(timeoutMs, flushLimit - deps.now())) : timeoutMs;
+      const controller =
+        typeof AbortController === 'function' ? new AbortController() : null;
+      const abort = controller
+        ? deps.setTimer(() => controller.abort(), budget)
+        : null;
+      const hard = flushLimit !== null ? timeoutAfter(budget) : null;
+      let status = 0;
+      try {
+        const t0 = deps.now();
+        const pending = deps.fetch(endpoint, {
+          method: 'POST',
+          headers,
+          body,
+          ...(controller ? { signal: controller.signal } : {}),
+        });
+        const res = hard ? await Promise.race([pending, hard.promise]) : await pending;
+        const t3 = deps.now();
+        status = res.status;
+        if (runToken && (status === 200 || status === 202)) {
+          const server = await serverClock(res);
+          if (server) {
+            // Stored only by a fresh batch; a duplicate's samples go again.
+            if (status === 202) {
+              dropClock(reported);
+            }
+            keepClock(runToken, { t0, ...server, t3 });
+          }
+        }
+      } finally {
+        if (abort !== null) {
+          deps.clearTimer(abort);
+        }
+        hard?.clear();
+      }
+      stats.lastStatus = status;
+      if (status === 200 || status === 202) {
+        stats.batchesSent++;
+        stats.linesSent += batch.items.length;
+        stats.bytesSent += utf8Length(body);
+        stats.lastSentAt = deps.now();
+        stats.lastError = null;
+        retryBatch = null;
+        retryAt = null;
+        attempts = 0;
+        markDone(batch.items);
+        compactIfIdle();
+      } else if (isPermanent(status)) {
+        stats.batchesRejected++;
+        stats.lastError = `rejected ${status}, batch ${batch.id} dropped`;
+        retryBatch = null;
+        retryAt = null;
+        attempts = 0;
+        markDone(batch.items);
+        compactIfIdle();
+      } else {
+        throw new Error(`http ${status}`);
+      }
+    } catch (error) {
+      stats.batchesFailed++;
+      stats.lastError = `${reason}: ${String(error)}`;
+      retryBatch = batch;
+      attempts++;
+      const wait = Math.min(backoffMax, backoffBase * 2 ** (attempts - 1));
+      retryAt = deps.now() + wait;
+    } finally {
+      sending = false;
+    }
+    if (queue.length > 0 || retryBatch) {
+      schedule(retryAt !== null ? Math.max(0, retryAt - deps.now()) : 0);
+    }
+  };
+
+  const sleep = (ms: number) =>
+    new Promise<void>(resolve => {
+      deps.setTimer(resolve, ms);
+    });
+
+  // The round trips no later batch will carry, one request per run token.
+  // Called only by flushAll, i.e. outside measured windows. Never throws.
+  const sendClock = async (limit: number | null) => {
+    for (const token of [...new Set(clockPending.map(c => c.token))]) {
+      const samples = clockOf(token);
+      const budget = Math.min(timeoutMs, limit === null ? timeoutMs : limit - deps.now());
+      if (budget <= 0) {
+        return;
+      }
+      const controller = typeof AbortController === 'function' ? new AbortController() : null;
+      const abort = controller ? deps.setTimer(() => controller.abort(), budget) : null;
+      const hard = timeoutAfter(budget);
+      try {
+        const res = await Promise.race([
+          deps.fetch(clockEndpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+            body: JSON.stringify({ source: 'device', samples }),
+            ...(controller ? { signal: controller.signal } : {}),
+          }),
+          hard.promise,
+        ]);
+        if (res.status === 202 || (res.status >= 400 && res.status < 500)) {
+          dropClock(samples);
+        }
+      } catch {
+        // kept for the next flush
+      } finally {
+        if (abort !== null) {
+          deps.clearTimer(abort);
+        }
+        hard.clear();
+      }
+    }
+  };
+
+  // Sends everything queued now, whatever the windows and the backoff say, and
+  // reports how it went. A failed batch is retried `attempts` times in all.
+  const flushAll = async (
+    maxAttempts = 3,
+    deadline: number | null = null,
+  ): Promise<{ ok: boolean; batches: number; lines: number; error: string | null }> => {
+    if (timer !== null) {
+      deps.clearTimer(timer);
+      timer = null;
+    }
+    resume();
+    const sentBefore = stats.batchesSent;
+    const linesBefore = stats.linesSent;
+    let failures = 0;
+    flushLimit = deadline;
+    try {
+      if (inflight) {
+        await inflight;
+      }
+      while (
+        (queue.length > 0 || retryBatch) &&
+        failures < maxAttempts &&
+        (deadline === null || deps.now() < deadline)
+      ) {
+        const failedBefore = stats.batchesFailed;
+        await flush('explicit', true);
+        if (stats.batchesFailed > failedBefore) {
+          failures++;
+          if (failures < maxAttempts) {
+            const wait = Math.min(backoffMax, backoffBase * failures);
+            const pause = deadline === null ? wait : Math.min(wait, deadline - deps.now());
+            if (pause > 0) {
+              await sleep(pause);
+            }
+          }
+        }
+      }
+      const ok = queue.length === 0 && !retryBatch;
+      if (ok) {
+        await sendClock(deadline);
+      }
+      return {
+        ok,
+        batches: stats.batchesSent - sentBefore,
+        lines: stats.linesSent - linesBefore,
+        error: ok ? null : (stats.lastError ?? 'flush deadline'),
+      };
+    } finally {
+      flushLimit = null;
+    }
+  };
+
+  // Lines a killed process left behind go out at the first idle flush; the
+  // journal is not read before then.
+  if (spool && autoFlush) {
+    schedule(idleFlushMs);
+  }
+
+  return {
+    enqueue,
+    flush,
+    flushAll,
+    resume,
+    stats: readStats,
+  };
+};
+
+export type PushClient = ReturnType<typeof createPushClient>;