@scalebun-release/react-native 2.5.0

package/src/transport/http/httpClient.ts

@@ -0,0 +1,73 @@
+import { noThrow } from '../../core/lifecycle/crashSafe';
+import { sdkSession } from '../auth/sdkSession';
+
+export interface HttpResponse {
+    status: number;
+    data?: any;
+}
+
+/** Default request deadline (ms). After this the request is aborted. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 10000;
+
+/**
+ * Error thrown when a request is aborted because it exceeded the deadline.
+ * Distinct from a bare AbortError so callers can report `reason: timeout`.
+ */
+export class RequestTimeoutError extends Error {
+    readonly isTimeout = true;
+    constructor(public readonly timeoutMs: number, public readonly cause?: unknown) {
+        super(`Request timed out after ${timeoutMs}ms`);
+        this.name = 'TimeoutError';
+    }
+}
+
+export class HttpClient {
+    constructor(
+        private baseUrl: string,
+        private timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS,
+    ) { }
+
+    async post(path: string, body: any, headers?: Record<string, string>): Promise<HttpResponse> {
+        const controller = new AbortController();
+        let timedOut = false;
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, this.timeoutMs);
+
+        const authHeader: Record<string, string> = {};
+        const token = sdkSession.getToken();
+        if (token) {
+            authHeader['Authorization'] = `Bearer ${token}`;
+        }
+
+        try {
+            const response = await fetch(`${this.baseUrl}${path}`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...authHeader,
+                    ...headers,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+
+            clearTimeout(timeout);
+            const data = await noThrow(() => response.json());
+
+            return {
+                status: response.status,
+                data,
+            };
+        } catch (error) {
+            clearTimeout(timeout);
+            // A timeout aborts the controller — re-tag it so downstream
+            // classification reports `reason: timeout` rather than a bare abort.
+            if (timedOut) {
+                throw new RequestTimeoutError(this.timeoutMs, error);
+            }
+            throw error;
+        }
+    }
+}

package/src/vendor/protocol/index.ts

@@ -0,0 +1,391 @@
+/**
+ * @scalebun/protocol — Canonical wire-protocol schemas and types
+ *
+ * Single source of truth for all message schemas shared between the
+ * ScaleBun SDK and the ScaleBun Desktop debugger.
+ *
+ * Constraints:
+ *   - Pure TypeScript only — no external runtime deps (no zod), so the package
+ *     resolves cleanly under React Native / Metro.
+ *   - No React Native, no Electron, no Node-only APIs, no DOM globals.
+ *   - Consumable by any future binding (Expo, Flutter codegen, native wrappers).
+ *
+ * Protocol version: 1  (wire format is UNCHANGED by this refactor)
+ */
+
+import { z, type Infer } from './internal/validation';
+
+// Re-export the internal validator so other workspace packages (e.g. the React
+// Native SDK config schema) can share one zod-free implementation.
+export { z } from './internal/validation';
+export type { Infer, SafeParseResult, ValidationIssue, ValidationError } from './internal/validation';
+
+// ─── Protocol Version ────────────────────────────────────────────────────────
+
+export const PROTOCOL_VERSION = 1;
+
+/** Heartbeat interval sent in ACK; SDK uses this for its ping timer */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
+
+// ─── Base Fields (common to all messages) ────────────────────────────────────
+
+const BaseMessageSchema = z.object({
+    protocolVersion: z.number().int().min(1),
+    deviceId: z.string().min(1),
+    sessionId: z.string().min(1),
+    timestamp: z.number(),
+    sequence: z.number().int().min(0),
+});
+
+// ─── Hello / Handshake ──────────────────────────────────────────────────────
+
+export const HelloMessageSchema = BaseMessageSchema.extend({
+    type: z.literal('hello'),
+    payload: z.object({
+        appName: z.string().optional(),
+        appVersion: z.string().optional(),
+        bundleId: z.string().optional(),
+        platform: z.enum(['ios', 'android', 'web']).optional(),
+        osVersion: z.string().optional(),
+        deviceModel: z.string().optional(),
+        sdkVersion: z.string().optional(),
+        buildType: z.enum(['debug', 'release']).optional(),
+        capabilities: z.array(z.string()).optional(),
+        token: z.string().optional(),
+        /**
+         * Shared secret for desktop authentication.
+         *
+         * If the desktop has secret enforcement enabled, the SDK must provide
+         * this field and its value must match the desktop's configured secret.
+         * If enforcement is disabled on the desktop, this field is ignored.
+         *
+         * Optional for backward compatibility: old SDKs that don't send it
+         * will still parse correctly. The desktop decides whether to reject.
+         *
+         * SECURITY NOTE: This is local-network authentication only.
+         * The WS channel is unencrypted (ws://). The secret prevents
+         * unauthorized connections from same-network devices; it does NOT
+         * protect against packet sniffing. For transport encryption, use
+         * TLS (wss://), which is a separate concern.
+         *
+         * Migration path:
+         *   1. Desktop generates a secret on first launch (visible in Connection panel).
+         *   2. Copy the secret and add `secret: '<value>'` to your SDK debug config.
+         *   3. Desktop rejects connections with wrong/missing secret (close code 4401).
+         *   4. To allow old SDKs during migration, toggle "Allow unauthenticated
+         *      connections" ON in the Connection panel.
+         */
+        secret: z.string().optional(),
+        // NOTE: 'deviceName' is accepted by the desktop but absent in the SDK.
+        // Problem 06 tracks this divergence — it will become a one-line addition
+        // here once that task runs.
+
+        /**
+         * Transport-layer statistics reported by the SDK on each hello.
+         * Allows the desktop to surface data-loss warnings when the SDK
+         * buffer overflowed during a disconnect.
+         *
+         * Optional for backward compatibility: old SDKs that don't send it
+         * will still parse correctly.
+         */
+        transportStats: z.object({
+            /** Cumulative count of messages dropped due to buffer overflow. */
+            droppedMessages: z.number().int().min(0),
+        }).optional(),
+    }),
+});
+
+// ─── Event ──────────────────────────────────────────────────────────────────
+
+export const EventCategorySchema = z.enum([
+    'log',
+    'network',
+    'navigation',
+    'lifecycle',
+    'crash',
+    'breadcrumb',
+    'replay',
+    'journey',
+    'session',
+    'performance',
+    'profiler',
+    'export',   // present in SDK; desktop was missing this — Problem 06
+    'custom',
+]);
+
+export const LogLevelSchema = z.enum(['debug', 'info', 'warn', 'error']);
+
+/**
+ * ─── recordingSessionId Contract ────────────────────────────────────────────
+ *
+ * The wire envelope's top-level `sessionId` is the TRANSPORT session ID
+ * (`debug-xxx`), generated once in `DebugTransport.setIdentity()` when
+ * `enableDebug()` is called. It does NOT change between recordings.
+ *
+ * `payload.data.recordingSessionId` is the RECORDING session ID (`ses-xxx`),
+ * generated by `SessionManager.startSession()` each time the user presses
+ * "Record". It is null/absent when no recording is active.
+ *
+ * The desktop uses `recordingSessionId` to correctly correlate network and
+ * performance events to the active recording session without relying on the
+ * transport ID. When absent (legacy SDK), the desktop falls back to its
+ * existing time-bounded ingestion logic.
+ *
+ * Layers:
+ *   SDK Core     → stamps `recordingSessionId` via `DebugEventStream`
+ *   Desktop Core → reads it in `shouldIngest()` for precise session correlation
+ *
+ * Wire envelope is UNCHANGED. Only the event `data` payload gains this field.
+ * ────────────────────────────────────────────────────────────────────────────
+ */
+export const EventMessageSchema = BaseMessageSchema.extend({
+    type: z.literal('event'),
+    payload: z.object({
+        id: z.string().min(1),
+        category: EventCategorySchema,
+        name: z.string(),
+        data: z.record(z.unknown()).optional(),
+        level: LogLevelSchema.optional(),
+        tags: z.array(z.string()).optional(),
+    }),
+});
+
+// ─── Metric (perf / fps / memory) ───────────────────────────────────────────
+
+export const MetricMessageSchema = BaseMessageSchema.extend({
+    type: z.literal('metric'),
+    payload: z.object({
+        name: z.string(),
+        value: z.number(),
+        unit: z.string().optional(),
+        tags: z.record(z.string()).optional(),
+    }),
+});
+
+// ─── Command (desktop → app) ────────────────────────────────────────────────
+
+export const CommandNameSchema = z.enum([
+    'ping',
+    'setLogLevel',
+    'clearQueue',
+    'triggerFlush',
+    'addBreadcrumb',
+    'startReplay',
+    'stopReplay',
+    'snapshot',
+    'startSession',
+    'stopSession',
+    'captureFrame',
+    'perfCaptureScreen',
+    'journeyRecordToggle',
+    'journeyCaptureStep',
+    'journeySave',
+    'journeyRun',
+    'journeyStopRun',
+    'reloadApp',
+    'exportReportResult',  // present in SDK; desktop was missing this — Problem 06
+]);
+
+export const CommandMessageSchema = BaseMessageSchema.extend({
+    type: z.literal('command'),
+    payload: z.object({
+        commandId: z.string().min(1),
+        name: CommandNameSchema,
+        args: z.record(z.unknown()).optional(),
+    }),
+});
+
+// ─── Command Result (app → desktop) ─────────────────────────────────────────
+
+export const CommandResultMessageSchema = BaseMessageSchema.extend({
+    type: z.literal('command_result'),
+    payload: z.object({
+        commandId: z.string().min(1),
+        success: z.boolean(),
+        data: z.record(z.unknown()).optional(),
+        error: z.string().optional(),
+    }),
+});
+
+// ─── Error ──────────────────────────────────────────────────────────────────
+
+export const ErrorMessageSchema = BaseMessageSchema.extend({
+    type: z.literal('error'),
+    payload: z.object({
+        code: z.string(),
+        message: z.string(),
+        details: z.record(z.unknown()).optional(),
+    }),
+});
+
+// ─── Heartbeat (ping/pong — lightweight, no base fields needed) ─────────────
+
+export const PingMessageSchema = z.object({
+    type: z.literal('scalebun:ping'),
+    deviceId: z.string().min(1),
+    timestamp: z.number(),
+});
+
+export const PongMessageSchema = z.object({
+    type: z.literal('scalebun:pong'),
+    timestamp: z.number(),
+    echoTimestamp: z.number(),
+});
+
+// ─── Ack (server → client after hello) ──────────────────────────────────────
+
+export const AckMessageSchema = z.object({
+    type: z.literal('scalebun:ack'),
+    serverVersion: z.string(),
+    heartbeatIntervalMs: z.number().int().min(1000),
+    timestamp: z.number(),
+});
+
+// ─── Union ──────────────────────────────────────────────────────────────────
+
+export const DebugMessageSchema = z.discriminatedUnion('type', [
+    HelloMessageSchema,
+    EventMessageSchema,
+    MetricMessageSchema,
+    CommandMessageSchema,
+    CommandResultMessageSchema,
+    ErrorMessageSchema,
+]);
+
+// ─── TypeScript Types ────────────────────────────────────────────────────────
+
+export type HelloMessage = Infer<typeof HelloMessageSchema>;
+export type EventMessage = Infer<typeof EventMessageSchema>;
+export type MetricMessage = Infer<typeof MetricMessageSchema>;
+export type CommandMessage = Infer<typeof CommandMessageSchema>;
+export type CommandResultMessage = Infer<typeof CommandResultMessageSchema>;
+export type ErrorMessage = Infer<typeof ErrorMessageSchema>;
+export type PingMessage = Infer<typeof PingMessageSchema>;
+export type PongMessage = Infer<typeof PongMessageSchema>;
+export type AckMessage = Infer<typeof AckMessageSchema>;
+export type DebugMessage = Infer<typeof DebugMessageSchema>;
+
+/** Any message that can be received (including control messages) */
+export type AnyScaleBunMessage = DebugMessage | PingMessage | PongMessage | AckMessage;
+
+export type EventCategory = Infer<typeof EventCategorySchema>;
+export type LogLevel = Infer<typeof LogLevelSchema>;
+export type CommandName = Infer<typeof CommandNameSchema>;
+
+// ─── Desktop-layer Types ─────────────────────────────────────────────────────
+// These live here because they derive from HelloMessage and are consumed by
+// both the Electron main process and the React renderer. They carry no
+// runtime dependencies beyond plain TypeScript.
+
+export type DeviceStatus = 'connected' | 'reconnecting' | 'disconnected';
+
+export interface DeviceInfo {
+    deviceId: string;
+    sessionId: string;
+    appName?: string;
+    appVersion?: string;
+    bundleId?: string;
+    platform?: string;
+    osVersion?: string;
+    deviceModel?: string;
+    deviceName?: string;
+    sdkVersion?: string;
+    buildType?: string;
+    capabilities?: string[];
+    connectedAt: number;
+    lastSeen: number;
+    pingLatencyMs?: number;
+    status: DeviceStatus;
+    /** Cumulative messages dropped by the SDK transport due to buffer overflow. */
+    droppedMessages?: number;
+}
+
+// ─── Safe Parsers (no-throw) ─────────────────────────────────────────────────
+
+export type ParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+    raw: unknown;
+};
+
+/**
+ * Safely parse a raw message. Returns typed result or error description.
+ * Never throws.
+ */
+export function parseDebugMessage(raw: unknown): ParseResult<DebugMessage> {
+    try {
+        const result = DebugMessageSchema.safeParse(raw);
+        if (result.success) {
+            return { success: true, data: result.data };
+        }
+        return {
+            success: false,
+            error: result.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; '),
+            raw,
+        };
+    } catch (e) {
+        return {
+            success: false,
+            error: e instanceof Error ? e.message : 'Unknown parse error',
+            raw,
+        };
+    }
+}
+
+/**
+ * Parse any ScaleBun message including control messages (ping/pong/ack).
+ * Tries debug message first, then control messages. Never throws.
+ */
+export function parseAnyMessage(raw: unknown): ParseResult<AnyScaleBunMessage> {
+    // Try standard debug message first
+    const debugResult = parseDebugMessage(raw);
+    if (debugResult.success) return debugResult;
+
+    // Try control messages
+    try {
+        const obj = raw as Record<string, unknown>;
+        if (obj?.type === 'scalebun:ping') {
+            const r = PingMessageSchema.safeParse(raw);
+            if (r.success) return { success: true, data: r.data };
+        }
+        if (obj?.type === 'scalebun:pong') {
+            const r = PongMessageSchema.safeParse(raw);
+            if (r.success) return { success: true, data: r.data };
+        }
+        if (obj?.type === 'scalebun:ack') {
+            const r = AckMessageSchema.safeParse(raw);
+            if (r.success) return { success: true, data: r.data };
+        }
+    } catch { /* fall through */ }
+
+    return {
+        success: false,
+        error: debugResult.success === false ? debugResult.error : 'Unknown message type',
+        raw,
+    };
+}
+
+/**
+ * Safely serialize a message to JSON string. Never throws.
+ */
+export function serializeMessage(msg: DebugMessage | PingMessage): string | null {
+    try {
+        return JSON.stringify(msg);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Safely deserialize a JSON string to a raw object. Never throws.
+ */
+export function deserializeMessage(data: string): unknown | null {
+    try {
+        return JSON.parse(data);
+    } catch {
+        return null;
+    }
+}