@scalebun-release/react-native 2.5.0

package/src/features/crash/nativeCrashBridge.ts

@@ -0,0 +1,352 @@
+import { NativeModules } from 'react-native';
+import { nativeModuleVia } from '../../core/architecture';
+import { logger } from '../../core/logger/internalLogger';
+import { getCrashReporter } from './CrashReporter';
+import { scrubText, scrubStack } from './scrubCrash';
+
+/**
+ * Wraps the ScaleBunCrash native module (Android/iOS).
+ * Call installNativeCrashHandler() once at SDK init to register handlers.
+ * Call drainNativeCrash() once at SDK init to replay any crash from the previous run.
+ *
+ * Both calls are no-ops when the native module is unavailable (e.g. JS-only
+ * environments, Expo Go without native build).
+ */
+
+let _crashModule: { mod: any } | undefined;
+
+function getCrashModule(): any {
+    if (_crashModule) return _crashModule.mod;
+
+    // New Architecture: prefer the codegen-backed TurboModule. Lazy + guarded so
+    // platforms without TurboModuleRegistry (web/SSR) don't throw at import.
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const turbo = require('../../specs/NativeScaleBunCrash').default;
+        if (turbo) {
+            __DEV__ && logger.debug(`[NativeCrash] resolved via ${nativeModuleVia()}`);
+            _crashModule = { mod: turbo };
+            return turbo;
+        }
+    } catch {
+        // fall through to the legacy lookup
+    }
+
+    // Old Architecture, New-Arch interop, or no native build.
+    const legacy = NativeModules?.ScaleBunCrash ?? null;
+    if (legacy) logger.debug('[NativeCrash] resolved via legacy NativeModules');
+    _crashModule = { mod: legacy };
+    return legacy;
+}
+
+/**
+ * Install the native crash handler (UncaughtExceptionHandler on Android,
+ * NSSetUncaughtExceptionHandler + signal handlers on iOS).
+ * Safe to call multiple times — native side is idempotent.
+ */
+/**
+ * Tell native which session is live, so a crash that happens next can name it.
+ *
+ * Called once per session — never per event. Native writes it to crash-safe storage immediately,
+ * because a fatal handler cannot call back into JS to ask, and by the time it runs the JS thread may
+ * already be gone.
+ *
+ * Fire-and-forget and no-throw: losing this degrades a recovered crash to unattributed, which is the
+ * old behaviour. It must never be able to fail a session start.
+ */
+/**
+ * The session last handed to native — which must be the INGESTION session (the `ses-` id whose row
+ * the backend holds), never an id the backend has not seen.
+ *
+ * Kept here so the JS fatal path can stamp the same owner synchronously: persistFatalJsCrash runs
+ * inside the global error handler and cannot await anything.
+ */
+let _activeSessionId: string | null = null;
+
+/** The session a crash happening right now belongs to, or null before any session opened. */
+export function getNativeActiveSession(): string | null {
+    return _activeSessionId;
+}
+
+export async function setNativeActiveSession(sessionId: string): Promise<void> {
+    if (sessionId) _activeSessionId = sessionId;
+    try {
+        const mod = getCrashModule();
+        if (!mod?.setActiveSessionId || !sessionId) return;
+        await mod.setActiveSessionId(sessionId);
+        __DEV__ && logger.debug(`[NativeCrash] Active session → ${sessionId}`);
+    } catch {
+        // No-throw
+    }
+}
+
+export async function installNativeCrashHandler(): Promise<void> {
+    try {
+        const mod = getCrashModule();
+        if (!mod?.install) {
+            __DEV__ && logger.debug('[NativeCrash] Native module not available — skipping install');
+            return;
+        }
+        await mod.install();
+        __DEV__ && logger.debug('[NativeCrash] Handler installed');
+    } catch {
+        // No-throw
+    }
+}
+
+/**
+ * How many pending crashes one launch will deliver.
+ *
+ * The native spool holds three (a device that crashes, restarts offline, and crashes again), but
+ * `drainPendingCrash` hands back the OLDEST ONE ONLY. Draining once per launch therefore needed three
+ * launches to clear three crashes — and a fourth crash evicts the oldest, so on a device crashing in a
+ * loop the spool loses faster than a one-per-launch drain empties it.
+ *
+ * Bounded, not `while (true)`: this loop is driven by native state and stops the moment delivery
+ * fails, but the bound is what makes it impossible for a native bug — a clear that silently does
+ * nothing — to spin the drain forever at startup.
+ */
+const MAX_DRAIN_PER_LAUNCH = 4;
+
+/**
+ * Drain the crash records left from previous process runs.
+ * Returns true if at least one pending crash was found.
+ *
+ * Stops early the first time delivery fails: if the network is down for one crash it is down for the
+ * next, and every extra attempt is a request that cannot succeed made during app startup.
+ */
+export async function drainNativeCrash(): Promise<boolean> {
+    let found = false;
+    const seen = new Set<string>();
+    for (let i = 0; i < MAX_DRAIN_PER_LAUNCH; i++) {
+        const outcome = await drainOne(seen);
+        if (outcome === 'none') break;
+        found = true;
+        // 'kept' means the backend did not take it. The rest of the spool is behind the same
+        // network, so stop rather than fail three more times.
+        if (outcome === 'kept') break;
+    }
+    return found;
+}
+
+/** One record: read → report → clear if the backend took it. */
+async function drainOne(seen: Set<string>): Promise<'none' | 'cleared' | 'kept'> {
+    try {
+        const mod = getCrashModule();
+        if (!mod?.drainPendingCrash) return 'none';
+
+        const crash = await mod.drainPendingCrash();
+        if (!crash) return 'none';
+
+        /*
+         * The same record twice means the previous clear did not take effect — a native failure we
+         * cannot fix from here. Reporting it again would deliver a duplicate on every iteration, so
+         * treat it as the end of the spool.
+         */
+        const seenKey = typeof crash.crashId === 'string' ? crash.crashId : '';
+        // `''` is a deliberate sentinel for the single legacy record, which has no id. Tracking it
+        // too means a legacy clear that silently fails stops the loop instead of redelivering the
+        // same crash on every one of the remaining iterations.
+        if (seen.has(seenKey)) return 'none';
+        seen.add(seenKey);
+
+        const stackArr: string[] = Array.isArray(crash.stackTrace) ? crash.stackTrace : [];
+
+        // 1) Desktop debug stream — keep the rich native-crash envelope.
+        // D2: a rich envelope used to be written here into memoryQueue — a queue
+        // whose drain was never wired, so the native crash's forensic detail was
+        // captured and then discarded. The flattened report below now carries the
+        // same fields in `metadata` (D12), through the pipeline that actually lands.
+
+        // 2) SaaS backend errors endpoint (dashboard Crashes view) — route the
+        // same normalized report through the central reporter. This is what
+        // makes native crashes visible in the dashboard, not just the desktop.
+        const recordType = typeof crash.type === 'string' ? crash.type : 'native';
+        const recordSource = typeof crash.source === 'string' ? crash.source : 'native';
+        getCrashReporter().report({
+            source: recordSource,
+            type: recordType,
+            isFatal: true,
+            message: crash.message ?? crash.exceptionType ?? 'Native crash',
+            stack: stackArr.length
+                ? stackArr.join('\n')
+                : crash.stack
+                  ? String(crash.stack)
+                  : undefined,
+            // Set for a recovered JS crash; a native crash has no JS screen.
+            ...(crash.screenName ? { screenName: String(crash.screenName) } : {}),
+            platform: crash.platform,
+            /**
+             * THE ORIGINAL SESSION — the entire point of the recovery path.
+             *
+             * This crash happened in a process that no longer exists, so it does NOT belong to the
+             * session running now. Passing it explicitly is what stops the reporter routing it
+             * through the current SessionManager and attributing it to the session created after
+             * the restart.
+             *
+             * Undefined on records written before this shipped, and on a crash that beat the first
+             * session. The sink then keeps the legacy behaviour rather than guessing an owner.
+             */
+            ...(crash.sessionId ? { sessionId: String(crash.sessionId) } : {}),
+            /**
+             * The stable id, carried through so it becomes the backend's dedupe key.
+             *
+             * Written once when the crash was first persisted — never regenerated here. If this were
+             * minted per attempt, every retry would arrive as a brand-new crash and at-least-once
+             * delivery would turn into duplicate-every-time.
+             */
+            ...(crash.crashId ? { crashId: String(crash.crashId) } : {}),
+            metadata: {
+                exceptionType: crash.exceptionType,
+                threadName: crash.threadName,
+                ...(crash.signal !== undefined ? { signal: crash.signal } : {}),
+            },
+        });
+
+        /**
+         * DELETE ONLY AFTER THE BACKEND HAS IT.
+         *
+         * The read above is non-destructive, so the crash is still on disk right now. It is removed
+         * only once delivery has actually succeeded — previously the record was destroyed at read
+         * time, so a failed upload lost the crash permanently: the app had proof of a crash, deleted
+         * it, and then failed to send it.
+         *
+         * On failure we simply do NOT clear. The crash stays pending and is retried on the next
+         * launch, which is what makes this at-least-once. Duplicate delivery is safe because the
+         * crash carries a stable `crashId` that the backend dedupes on — a retry produces no second
+         * record.
+         *
+         * A record with no `crashId` is legacy: it predates stable ids, so it cannot be safely
+         * retried (a redelivery WOULD duplicate) and is cleared immediately, preserving exactly the
+         * old at-most-once behaviour for old data rather than silently changing it.
+         */
+        const crashId = seenKey;
+        if (!crashId) {
+            await mod.clearPendingCrash?.('');
+            __DEV__ && logger.info('[NativeCrash] Legacy crash (no id) drained and cleared');
+            return 'cleared';
+        }
+
+        const delivered = await confirmDelivery();
+        if (delivered) {
+            await mod.clearPendingCrash?.(crashId);
+            __DEV__ && logger.info(`[NativeCrash] Crash ${crashId} delivered → cleared`);
+            return 'cleared';
+        }
+        __DEV__ && logger.info(`[NativeCrash] Crash ${crashId} not yet delivered → kept for retry`);
+        return 'kept';
+    } catch {
+        // Unknown state — stop the loop rather than risk spinning on a failure we cannot diagnose.
+        return 'none';
+    }
+}
+
+/**
+ * Has the crash actually reached the backend?
+ *
+ * The reporter's sinks are fire-and-forget by design (a crash report must never block or throw), so
+ * "delivered" is asked of the transport rather than inferred from `report()` returning. If the
+ * transport is not up yet — the drain can win the race against SessionManager — the answer is NO and
+ * the crash stays on disk for the next launch. That is strictly better than the old behaviour, where
+ * exactly that race deleted the record and dropped the crash silently.
+ */
+async function confirmDelivery(): Promise<boolean> {
+    try {
+        const { SessionManager } = await import('../session/SessionManager');
+        const transport = SessionManager.getExistingInstance()?.getBackendTransport();
+        // No transport yet — the drain can win the startup race. That is a delivery FAILURE, not a
+        // reason to give up: the record stays on disk and the next launch retries it. This exact
+        // path used to delete the crash and send nothing.
+        if (!transport) return false;
+        /**
+         * The BOOLEAN, not merely "it resolved".
+         *
+         * flushErrors used to return void and swallow its own errors, so awaiting it proved only
+         * that the call finished. Deleting a crash on that basis would have thrown away crashes
+         * that never reached the backend — the failure this whole change exists to prevent.
+         */
+        return (await transport.flushErrors()) === true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * DEV/TEST ONLY — ask the native module to crash the process right now, so the
+ * native handler captures it and the next launch drains it to the backend.
+ * No-op when the native module or `crashNow` is unavailable.
+ */
+export async function triggerNativeCrash(): Promise<void> {
+    try {
+        const mod = getCrashModule();
+        if (!mod?.crashNow) {
+            logger.warn('[NativeCrash] crashNow unavailable — rebuild native app to enable');
+            return;
+        }
+        await mod.crashNow();
+    } catch {
+        // The process is expected to die; nothing to handle.
+    }
+}
+/**
+ * Persist a FATAL JS crash to disk BEFORE the process dies.
+ *
+ * A fatal JS error tears the process down almost immediately. The normal error
+ * path queues the crash and POSTs it asynchronously, which loses the race: the
+ * process is gone before the request finishes, and nothing is on disk to retry.
+ * This is why a JS crash could vanish while a native one always survived.
+ *
+ * The fix is the native module's SYNCHRONOUS persistJsCrash: it writes the
+ * record to the same store native crashes use and returns before this function
+ * returns — so by the time the JS handler unwinds, the crash is durable. The
+ * existing drain path then delivers it on the next launch, at least once,
+ * deduped on crashId.
+ *
+ * Synchronous and no-throw by construction: this runs inside the global error
+ * handler, where an exception would replace one crash with another.
+ */
+export function persistFatalJsCrash(input: {
+    message: string;
+    stack?: string;
+    screenName?: string;
+    platform?: string;
+    sessionId?: string;
+}): boolean {
+    try {
+        const mod = getCrashModule();
+        if (!mod?.persistJsCrash) return false;
+        // Minted once, here, so a retry from disk dedupes on the backend rather
+        // than arriving as a fresh crash every launch.
+        const crashId = `jscrash-${nowMs()}-${counter()}`;
+        const record = {
+            crashId,
+            type: 'crash',
+            source: 'js',
+            isFatal: true,
+            // Scrubbed before it touches disk: this record is written BEFORE the reporter runs,
+            // and it sits in the app's storage until the next launch delivers it.
+            message: scrubText(input.message),
+            stack: scrubStack(input.stack),
+            screenName: input.screenName,
+            platform: input.platform,
+            // The owner of THIS crash: the next launch is a different session, and a record with
+            // no id would be filed under that one when it is drained.
+            sessionId: input.sessionId ?? _activeSessionId ?? undefined,
+            timestamp: new Date().toISOString(),
+        };
+        return mod.persistJsCrash(JSON.stringify(record)) === true;
+    } catch {
+        return false;
+    }
+}
+
+/** Monotonic-ish parts for a unique id without pulling in a uuid dependency. */
+let _seq = 0;
+function counter(): number {
+    _seq = (_seq + 1) % 1_000_000;
+    return _seq;
+}
+function nowMs(): number {
+    return Date.now();
+}
+

package/src/features/crash/rejectionHandler.ts

@@ -0,0 +1,196 @@
+import { noThrow } from '../../core/lifecycle/crashSafe';
+import { logger } from '../../core/logger/internalLogger';
+
+/**
+ * Capture UNHANDLED PROMISE REJECTIONS.
+ *
+ * THE GAP THIS CLOSES
+ * `ErrorUtils.setGlobalHandler` (see ./globalHandler) catches uncaught *throws* and nothing else. A
+ * rejected promise with no `.catch()` does not pass through it — React Native routes those to its own
+ * rejection tracker, which prints a LogBox warning in development and does nothing whatsoever in
+ * production. So `await doThing()` with no catch was reported by the WEB SDK (which listens for
+ * `unhandledrejection`) and silently lost on mobile. Same product, same mistake in the host's code,
+ * one platform reporting it — the cross-SDK asymmetry CLAUDE.md §2 exists to catch.
+ *
+ * WHY `require`, GUARDED, AND NOT AN IMPORT
+ * `promise/setimmediate/rejection-tracking` is React Native's own tracker: it arrives with
+ * react-native in any real app, and adding it to this package's dependencies would put a third-party
+ * runtime dep into the SDK for something the platform already ships. It is therefore resolved at
+ * runtime and treated as optional — the same shape as `globalHandler`'s `ErrorUtils` feature-detect,
+ * for the same reason. When it cannot be resolved this logs once and no-ops; nothing throws.
+ *
+ * ⚠️ `enable()` REPLACES the current handlers — it does not chain, and the module exposes no way to
+ * read the previous ones. Calling it therefore takes over from React Native's own dev-mode warning,
+ * so this re-emits that warning itself under `__DEV__`. Without it, installing the SDK would make
+ * unhandled rejections *quieter* in development than they were before, which is a poor trade for
+ * catching them in production.
+ */
+
+/** The slice of `promise/setimmediate/rejection-tracking` this uses. */
+export interface RejectionTracker {
+    enable(options: {
+        allRejections: boolean;
+        onUnhandled: (id: number, error: unknown) => void;
+        onHandled: (id: number) => void;
+    }): void;
+}
+
+/**
+ * Pick the tracker that owns the Promise the app actually uses.
+ *
+ * HERMES FIRST. On Hermes (every RN app since 0.70 by default) `global.Promise` is Hermes' own
+ * built-in, and React Native's polyfillPromise keeps it. The npm `promise` library's tracker only
+ * sees promises created by THAT library's constructor — none, on Hermes — so hooking it caught
+ * nothing: every `await` with no catch in a Hermes app went unreported, in debug and release alike.
+ * Hermes ships its own tracker with the same option shape; RN enables it only under __DEV__ (for
+ * LogBox), so in a release build it is ours to enable.
+ *
+ * The npm tracker remains the fallback for JSC, where the polyfill IS that library.
+ *
+ * Exported for tests; `env` stands in for the global object and `load` for require.
+ */
+export function resolveRejectionTracker(
+    env: { HermesInternal?: any } = globalThis as any,
+    load: (id: string) => unknown = (id) => require(id),
+): RejectionTracker | null {
+    const hermes = env?.HermesInternal;
+    try {
+        if (
+            hermes &&
+            typeof hermes.enablePromiseRejectionTracker === 'function' &&
+            // hasPromise() is true when global.Promise is Hermes' own. When it is absent (older
+            // Hermes) the polyfill decides; trust the tracker only when the question can be asked.
+            typeof hermes.hasPromise === 'function' &&
+            hermes.hasPromise() === true
+        ) {
+            return { enable: (options) => hermes.enablePromiseRejectionTracker(options) };
+        }
+    } catch {
+        // fall through to the library tracker
+    }
+    try {
+        return load('promise/setimmediate/rejection-tracking') as RejectionTracker;
+    } catch {
+        return null;
+    }
+}
+
+function defaultResolveTracker(): RejectionTracker | null {
+    return resolveRejectionTracker();
+}
+
+/**
+ * Anything can be rejected — `throw 'a string'` is legal. Normalise without inventing a stack.
+ *
+ * A NON-Error value is DESCRIBED, never serialised. It used to be `JSON.stringify`'d whole, and
+ * apps reject with raw response objects (`reject(res)` from an HTTP or socket client) — headers with
+ * the Authorization token, bodies with phone numbers — all of which would have been stored as the
+ * error message. The description keeps what triages the error (its type, a status, a message, the
+ * shape) and nothing that could be a value.
+ */
+function toError(value: unknown): Error {
+    if (value instanceof Error) return value;
+    if (typeof value === 'string') return new Error(value);
+    return new Error(`Non-Error rejection: ${describeRejection(value)}`);
+}
+
+const MAX_DESCRIBED_KEYS = 10;
+const MAX_DESCRIBED_MESSAGE = 200;
+
+/** Exported for tests. Type, status, message and key NAMES only — never a value. */
+export function describeRejection(value: unknown): string {
+    if (value === null) return 'null';
+    if (value === undefined) return 'undefined';
+    if (typeof value !== 'object') return typeof value;
+    try {
+        const o = value as Record<string, unknown>;
+        const parts: string[] = [];
+        const status = typeof o.status === 'number' ? o.status : typeof o.statusCode === 'number' ? o.statusCode : null;
+        if (status !== null) parts.push(`status ${status}`);
+        if (typeof o.message === 'string') parts.push(`message "${o.message.slice(0, MAX_DESCRIBED_MESSAGE)}"`);
+        const keys = Object.keys(o);
+        const shown = keys.slice(0, MAX_DESCRIBED_KEYS).join(', ');
+        parts.push(`keys [${shown}${keys.length > MAX_DESCRIBED_KEYS ? `, +${keys.length - MAX_DESCRIBED_KEYS} more` : ''}]`);
+        const ctor = (o as { constructor?: { name?: unknown } }).constructor?.name;
+        return `${typeof ctor === 'string' && ctor ? ctor : 'Object'} (${parts.join(', ')})`;
+    } catch {
+        return 'object';
+    }
+}
+
+/**
+ * Install the unhandled-rejection handler.
+ *
+ * @returns true when the tracker was available and handlers were installed.
+ */
+export function installRejectionHandler(
+    onRejection: (error: Error) => void,
+    deps?: { resolveTracker?: () => RejectionTracker | null; isDev?: boolean },
+): boolean {
+    return (
+        noThrow(() => {
+            const tracker = (deps?.resolveTracker ?? defaultResolveTracker)();
+            if (!tracker || typeof tracker.enable !== 'function') {
+                __DEV__ && logger.debug(
+                    '[Crash] promise rejection tracking unavailable — unhandled rejections not captured',
+                );
+                return false;
+            }
+
+            const isDev = deps?.isDev ?? (typeof __DEV__ !== 'undefined' && __DEV__);
+
+            tracker.enable({
+                /**
+                 * `allRejections: true` reports a rejection that is still unhandled when the tracker's
+                 * grace period elapses. `onHandled` below is the other half: a promise caught LATE —
+                 * a very common pattern, e.g. attaching `.catch()` after an `await` chain — fires
+                 * `onUnhandled` first and `onHandled` afterwards. Reporting on the first and saying
+                 * nothing on the second would file a crash for code that handled its own error.
+                 */
+                allRejections: true,
+                onUnhandled: (id: number, error: unknown) => {
+                    const err = toError(error);
+                    pending.set(id, err);
+                    onRejection(err);
+                    if (isDev) {
+                        // Re-emit what RN's own tracker would have said, since enable() displaced it.
+                        // eslint-disable-next-line no-console
+                        console.warn(`Possible unhandled promise rejection (id: ${id}):`, err?.message ?? err);
+                    }
+                },
+                onHandled: (id: number) => {
+                    pending.delete(id);
+                    if (isDev) {
+                        // eslint-disable-next-line no-console
+                        console.warn(
+                            `Promise rejection handled late (id: ${id}) — it was already reported.`,
+                        );
+                    }
+                },
+            });
+
+            __DEV__ && logger.debug('Unhandled promise rejection handler installed');
+            return true;
+        }) ?? false
+    );
+}
+
+/**
+ * Rejections reported but not yet seen handled.
+ *
+ * Deliberately NOT used to suppress the report — by the time `onUnhandled` fires the rejection has
+ * already gone unhandled for the tracker's whole grace period, and holding it back on the chance
+ * that a late `.catch()` arrives would mean losing genuine production errors to a guess. This exists
+ * so `onHandled` has somewhere to clear from, and so a test can observe the pairing.
+ */
+const pending = new Map<number, Error>();
+
+/** Test seam — number of reported-and-not-yet-handled rejections. */
+export function __pendingRejectionCount(): number {
+    return pending.size;
+}
+
+/** Test seam — clear state between cases. */
+export function __resetRejectionsForTests(): void {
+    pending.clear();
+}