@buoy-gg/network 7.0.13 → 7.0.14

package/lib/module/network/overrides/resolveOverride.js

@@ -0,0 +1,152 @@
+"use strict";
+
+/**
+ * Decide whether a request is overridden — the whole decision, in one pure
+ * function.
+ *
+ * Pure on purpose: this is the piece worth unit-testing, and it runs inside the
+ * app's own `XMLHttpRequest.send()`, so it must be cheap, total, and incapable
+ * of throwing. Everything that could surprise (defaults, clamping, content-type
+ * inference) is resolved HERE, so `applyToXhr` never makes a decision — it just
+ * performs the outcome.
+ */
+
+import { ruleMatches } from "./matchRule";
+import { STATUS_MAX, STATUS_MIN } from "./types";
+
+/**
+ * Traffic that must never be overridden, whatever the user's rules say.
+ *
+ * A `*` pattern is a completely reasonable thing for a developer to write
+ * ("break everything and see what the app does"), and without this it would
+ * also break Buoy's own licence checks — turning "I tested an error state" into
+ * "the dev tools stopped working and I don't know why". Metro/debugger traffic
+ * is already excluded upstream by `networkListener.shouldIgnoreUrl`.
+ */
+const NEVER_OVERRIDE = [/(^|\.)keygen\.sh/i];
+function isProtectedUrl(url) {
+  return NEVER_OVERRIDE.some(pattern => pattern.test(url));
+}
+
+/**
+ * Guess a `content-type` when the rule didn't set one.
+ *
+ * Getting this wrong is not cosmetic: a client that trusts the header (axios's
+ * default transform, any `response.json()` wrapper) will hand the app a string
+ * where it expected an object, and the override looks broken rather than the
+ * header looking wrong.
+ */
+function inferContentType(body) {
+  const trimmed = body.trim();
+  if (trimmed === "") return "text/plain; charset=utf-8";
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      JSON.parse(trimmed);
+      return "application/json";
+    } catch {
+      // Looks like JSON, isn't. Fall through — mislabelling it would be worse.
+    }
+  }
+  return "text/plain; charset=utf-8";
+}
+function hasHeader(headers, name) {
+  const wanted = name.toLowerCase();
+  return Object.keys(headers).some(key => key.toLowerCase() === wanted);
+}
+
+/** Normalize a matched rule into the exact instructions the interceptor needs. */
+function toOutcome(rule) {
+  const delayMs = Math.max(0, rule.delayMs ?? 0);
+  if (rule.kind === "delay") {
+    return {
+      kind: "delay",
+      rule,
+      delayMs
+    };
+  }
+  if (rule.kind === "fail") {
+    return {
+      kind: "fail",
+      rule,
+      delayMs,
+      failKind: rule.failKind ?? "network"
+    };
+  }
+  const body = rule.body ?? "";
+  const headers = {
+    ...(rule.headers ?? {})
+  };
+  if (!hasHeader(headers, "content-type")) {
+    headers["content-type"] = inferContentType(body);
+  }
+  return {
+    kind: "respond",
+    rule,
+    delayMs,
+    // Clamped, not rejected: whatwg-fetch's Response constructor THROWS outside
+    // [200, 599], which would crash the app's own fetch instead of overriding
+    // it. The editor constrains the input; this guarantees it.
+    status: Math.min(STATUS_MAX, Math.max(STATUS_MIN, rule.status ?? 200)),
+    statusText: rule.statusText ?? "",
+    headers,
+    body
+  };
+}
+
+/** A rule that has burned through its `times` budget no longer applies. */
+export function isSpent(rule) {
+  return typeof rule.times === "number" && rule.hits >= rule.times;
+}
+
+/**
+ * Is this rule in a phase where it should actually fire?
+ *
+ * Only `alternate` can answer no. It reads the CURRENT `seen` count, before
+ * this match is recorded, so an untouched rule (`seen === 0`) lets the first
+ * request through and overrides the second.
+ */
+export function shouldApply(rule) {
+  if (!rule.alternate) return true;
+  return rule.seen % 2 === 1;
+}
+
+/**
+ * The first enabled rule whose pattern covers this request, phase ignored.
+ *
+ * Separate from `resolveOverride` because an alternating rule has to advance
+ * its phase on the requests it deliberately skips — the caller needs the rule
+ * back even when the answer is "not this time".
+ */
+export function findMatchingRule(url, method, rules) {
+  if (rules.length === 0) return null;
+  // Chrome skips OPTIONS too (`NetworkPersistenceManager.ts:953`). A faked
+  // preflight fails CORS in a way that looks nothing like the rule you wrote.
+  if (method.toUpperCase() === "OPTIONS") return null;
+  if (isProtectedUrl(url)) return null;
+  for (const rule of rules) {
+    if (!rule.enabled) continue;
+    if (isSpent(rule)) continue;
+    if (!ruleMatches(rule, url, method)) continue;
+    return rule;
+  }
+  return null;
+}
+
+/**
+ * First ENABLED matching rule wins outright — no merging across rules.
+ *
+ * Chrome cascades header overrides from the most general path segment to the
+ * most specific, but that only exists because its rules are directory-nested
+ * files. A flat list with a cascade would be a rule whose effect you cannot see
+ * by reading it, which is exactly the wrong trade on a phone screen.
+ *
+ * @param url    Full request URL, query string included.
+ * @param method HTTP method as the caller sent it (case-insensitive).
+ * @param rules  Ordered rule list; earlier entries win.
+ */
+export function resolveOverride(url, method, rules) {
+  const rule = findMatchingRule(url, method, rules);
+  if (!rule || !shouldApply(rule)) return null;
+  return toOutcome(rule);
+}
+export { toOutcome };

package/lib/module/network/overrides/types.js

@@ -0,0 +1,80 @@
+"use strict";
+
+/**
+ * Network response overrides — the rule model.
+ *
+ * This is Buoy's answer to Chrome DevTools' "Local Overrides", reshaped for
+ * mobile. Two deliberate differences from Chrome are worth knowing, because
+ * they explain the whole shape of this file:
+ *
+ * 1. Chrome's rules ARE a directory tree — a body override is a file at
+ *    `<host>/<path>`, header overrides live in per-directory `.headers` files,
+ *    and its general→specific header cascade exists only to hang off that
+ *    nesting. We have no filesystem, so rules are a flat ordered list and the
+ *    FIRST enabled match wins outright. That's what Charles/Proxyman/MSW do,
+ *    and it's what a developer can reason about on a phone screen.
+ *
+ * 2. Chrome CANNOT change a status code. `NetworkManager.ts` computes
+ *    `responseCode = isBodyOverridden ? 200 : (responseStatusCode || 200)`, so
+ *    overriding a body forces 200, and there is no latency or failure
+ *    simulation at all. Chrome's feature is "serve different bytes". Forcing a
+ *    500, a timeout or a 3s stall is the entire mobile use case, so `status`,
+ *    `delayMs` and `kind: "fail"` below are the point of the exercise.
+ */
+
+/**
+ * What a rule does when it matches.
+ *
+ * - `respond` — synthesize a response. The request never leaves the device.
+ * - `fail`    — synthesize a transport failure (offline / timeout). Also never
+ *               leaves the device.
+ * - `delay`   — let the real request run, just late. Pure latency injection.
+ */
+
+/**
+ * Which transport failure to fake.
+ *
+ * `network` surfaces the way a real offline request does — `fetch` rejects with
+ * `TypeError: Network request failed`. This is also how you simulate "status 0":
+ * you can't, via `respond`, because whatwg-fetch's `Response` constructor throws
+ * a RangeError outside 200–599 (see STATUS_MIN/STATUS_MAX).
+ */
+
+/**
+ * Status codes a synthesized response may use.
+ *
+ * NOT an arbitrary product decision: React Native's `fetch` is the whatwg-fetch
+ * polyfill, whose `Response` constructor throws
+ * `RangeError: The status provided is outside the range [200, 599]`. A rule set
+ * to 0 would therefore crash the app's own fetch call rather than override it.
+ * Use `kind: "fail"` for connection-level failures.
+ */
+export const STATUS_MIN = 200;
+export const STATUS_MAX = 599;
+
+/** Bounds the persisted list so a runaway UI can't fill storage. */
+export const MAX_RULES = 50;
+
+/** Free tier gets one active rule; Pro is unlimited (up to MAX_RULES). */
+export const FREE_TIER_RULE_LIMIT = 1;
+
+/**
+ * Stamped onto the `NetworkEvent` a rule affected, so the list can badge the
+ * row and the detail view can offer "edit / disable the rule that did this".
+ */
+
+/**
+ * A matched rule, normalized into exactly what the interceptor needs — defaults
+ * resolved, status clamped, content-type inferred. Keeping normalization in the
+ * resolver means `applyToXhr` never has to make a decision.
+ */
+
+/** The marker recorded for an outcome. */
+export function markForOutcome(outcome) {
+  return {
+    ruleId: outcome.rule.id,
+    ruleName: outcome.rule.name,
+    kind: outcome.kind,
+    delayMs: outcome.delayMs || undefined
+  };
+}

package/lib/module/network/sync/networkSyncAdapter.js

@@ -2,6 +2,10 @@
 
 import { networkEventStore } from "../utils/networkEventStore";
 import { flagsForEventId, networkSavedStore } from "../utils/networkSavedStore";
+import { overrideRulesStore } from "../overrides/overrideRulesStore";
+import { draftFromEvent } from "../overrides/presets";
+import { inspectEngine } from "../overrides/engine";
+import { getNetworkListenerCount, isNetworkListening } from "../utils/networkListener";
 /**
  * Request/response bodies larger than this (using the cached size proxy already
  * on the event — no per-snapshot stringify) are NOT streamed in the list
@@ -27,9 +31,116 @@ const stripLargeBodies = event => {
   if (stripResponse) stripped.responseData = undefined;
   return stripped;
 };
+
+/**
+ * Drop oversized rule bodies from the snapshot, flagging what was dropped.
+ *
+ * Same limit and same reasoning as `stripLargeBodies` above — and the same
+ * hazard, only worse: an override body is authored once and then rides EVERY
+ * snapshot for as long as the rule exists, whereas an event ages out of the
+ * list. `draftFromEvent` seeds a rule with the real response, so 500KB is an
+ * ordinary size here, not a pathological one.
+ */
+const stripLargeRuleBodies = state => {
+  let changed = false;
+  const rules = state.rules.map(rule => {
+    if (!rule.body || rule.body.length <= SNAPSHOT_BODY_INLINE_LIMIT) {
+      return rule;
+    }
+    changed = true;
+    return {
+      ...rule,
+      body: undefined,
+      bodyOmitted: true
+    };
+  });
+  // Identity is preserved when nothing was stripped: the desktop mirror feeds
+  // this straight into a `useEffect` dependency, and a fresh object every
+  // snapshot would re-run it several times a second.
+  return changed ? {
+    ...state,
+    rules
+  } : state;
+};
 const resolveEvent = id => networkEventStore.getEventById(id) ?? networkSavedStore.getEventById(id);
 const readId = params => params && typeof params === "object" ? params.id : undefined;
 const readBool = (params, key) => !!(params && typeof params === "object" && params[key]);
+const VALID_KINDS = ["respond", "fail", "delay"];
+
+/**
+ * Turn an override rule sent over the wire into a draft the store will accept.
+ *
+ * Validated rather than trusted: these params arrive from the dashboard and
+ * from MCP clients, and a malformed rule doesn't just fail — it gets PERSISTED
+ * and then re-applied to real traffic on every launch. `urlPattern` is the one
+ * field with no sane default, so its absence rejects the whole call.
+ */
+function readRuleDraft(params,
+/**
+ * Prefill from a captured request, as the UI's Override button does. Any
+ * field the caller sent explicitly still wins over it.
+ */
+base) {
+  if (!params || typeof params !== "object") return null;
+  const raw = params.rule ?? params;
+  if (!raw || typeof raw !== "object") return null;
+  const rule = raw;
+  const urlPattern = typeof rule.urlPattern === "string" && rule.urlPattern.trim() ? rule.urlPattern.trim() : base?.urlPattern ?? "";
+  if (!urlPattern) return null;
+  const kind = VALID_KINDS.includes(rule.kind) ? rule.kind : base?.kind ?? "respond";
+  return {
+    id: typeof rule.id === "string" ? rule.id : undefined,
+    enabled: rule.enabled !== false,
+    name: typeof rule.name === "string" ? rule.name : base?.name,
+    urlPattern,
+    methods: Array.isArray(rule.methods) ? rule.methods.filter(m => typeof m === "string").map(m => m.toUpperCase()) : base?.methods,
+    kind,
+    status: typeof rule.status === "number" ? rule.status : base?.status,
+    statusText: typeof rule.statusText === "string" ? rule.statusText : base?.statusText,
+    headers: rule.headers && typeof rule.headers === "object" ? rule.headers : base?.headers,
+    // Objects are accepted and serialized so a caller can send JSON directly
+    // instead of pre-stringifying it, which is the mistake everyone makes once.
+    body: typeof rule.body === "string" ? rule.body : rule.body != null ? JSON.stringify(rule.body, null, 2) : base?.body,
+    failKind: rule.failKind === "timeout" ? "timeout" : undefined,
+    delayMs: typeof rule.delayMs === "number" ? rule.delayMs : undefined,
+    times: typeof rule.times === "number" ? rule.times : null,
+    alternate: rule.alternate === true
+  };
+}
+
+/**
+ * The body a remote surface never received, when it says so.
+ *
+ * A dashboard editing a rule whose body was stripped from the snapshot has
+ * nothing to send back for it. Without this the save would write `body:
+ * undefined` and silently destroy the payload — the one field a rule exists for.
+ */
+function preservedBody(params) {
+  if (!params || typeof params !== "object") return null;
+  const raw = params.rule ?? params;
+  if (!raw || typeof raw !== "object") return null;
+  const rule = raw;
+  if (rule.bodyOmitted !== true || typeof rule.id !== "string") return null;
+  const existing = overrideRulesStore.getState().rules.find(candidate => candidate.id === rule.id);
+  return existing ? {
+    body: existing.body
+  } : null;
+}
+
+/**
+ * Resolve `fromRequestId` into the same draft the UI's Override button builds.
+ *
+ * Worth routing through `draftFromEvent` rather than letting a caller paste the
+ * URL: it drops the query string to `*`, which is the difference between a rule
+ * that fires and one that sits at 0 hits against a cache-busting client.
+ */
+function baseFromRequest(params) {
+  if (!params || typeof params !== "object") return null;
+  const id = params.fromRequestId;
+  if (typeof id !== "string" || !id) return null;
+  const event = resolveEvent(id);
+  return event ? draftFromEvent(event) : null;
+}
 
 /**
  * Sync adapter for the network tool, consumed by @buoy-gg/external-sync's
@@ -49,9 +160,15 @@ const readBool = (params, key) => !!(params && typeof params === "object" && par
  * `NetworkPanel`/`NetworkInline` accept either shape.
  */
 export const networkSyncAdapter = {
-  version: 3,
+  version: 4,
   getSnapshot: () => ({
     events: networkEventStore.getEvents().map(stripLargeBodies),
+    /**
+     * Response-override rules live on the DEVICE — that's the only place they
+     * can run, since a rule is applied inside the app's own XMLHttpRequest.
+     * Remote surfaces mirror this and forward their edits back as actions.
+     */
+    overrides: stripLargeRuleBodies(overrideRulesStore.getState()),
     // Saved snapshots go through the same body strip. They are few (capped in
     // the store) but they ride on EVERY snapshot, so a fat one would land in
     // the same 200ms loop that the body-stripping exists to protect.
@@ -65,9 +182,13 @@ export const networkSyncAdapter = {
     // both stores drive the snapshot.
     const unsubscribeEvents = networkEventStore.subscribeToEvents(onChange);
     const unsubscribeSaved = networkSavedStore.subscribe(onChange);
+    // Same reasoning for rules: editing one with no traffic in flight must
+    // still reach the dashboard. Subscribing also hydrates the rule list.
+    const unsubscribeOverrides = overrideRulesStore.subscribe(onChange);
     return () => {
       unsubscribeEvents();
       unsubscribeSaved();
+      unsubscribeOverrides();
     };
   },
   actions: {
@@ -138,6 +259,114 @@ export const networkSyncAdapter = {
       return {
         ok: true
       };
+    },
+    // =========================================================================
+    // RESPONSE OVERRIDES
+    // =========================================================================
+
+    /** Master switch — turns every rule off without losing any of them. */
+    setOverridesEnabled: params => {
+      overrideRulesStore.setEnabled(readBool(params, "enabled"));
+      return {
+        ok: true,
+        enabled: overrideRulesStore.getState().enabled
+      };
+    },
+    /** Create a rule, or replace one by id. */
+    upsertOverrideRule: params => {
+      const base = baseFromRequest(params) ?? preservedBody(params);
+      const draft = readRuleDraft(params, base);
+      if (!draft) {
+        const wanted = params?.fromRequestId;
+        return {
+          ok: false,
+          error: wanted ? `No captured request \`${wanted}\` — it may have been cleared. Send a urlPattern instead.` : "A rule needs a non-empty urlPattern."
+        };
+      }
+      const rule = overrideRulesStore.upsertRule(draft);
+      if (!rule) return {
+        ok: false,
+        error: "Override rule limit reached."
+      };
+      // A rule pushed from a remote surface is meant to take effect now;
+      // leaving it dark under an OFF master switch reads as a silent failure.
+      if (rule.enabled) overrideRulesStore.setEnabled(true);
+      // A RECEIPT, not the rule. `fromRequestId` seeds the real response as the
+      // body, so echoing the whole rule sent 380KB back down the socket for a
+      // Pokémon payload — and no caller reads it: the desktop mirror gets the
+      // rule from the next snapshot, and MCP only needs the id to report and
+      // remove it.
+      return {
+        ok: true,
+        rule: {
+          id: rule.id,
+          urlPattern: rule.urlPattern,
+          enabled: rule.enabled,
+          kind: rule.kind,
+          status: rule.status,
+          bodySize: rule.body ? rule.body.length : 0
+        }
+      };
+    },
+    setOverrideRuleEnabled: params => {
+      const id = readId(params);
+      if (!id) return {
+        ok: false,
+        error: "Missing rule id."
+      };
+      overrideRulesStore.setRuleEnabled(id, readBool(params, "enabled"));
+      return {
+        ok: true
+      };
+    },
+    deleteOverrideRule: params => {
+      const id = readId(params);
+      if (!id) return {
+        ok: false,
+        error: "Missing rule id."
+      };
+      overrideRulesStore.removeRule(id);
+      return {
+        ok: true
+      };
+    },
+    clearOverrideRules: () => {
+      overrideRulesStore.clearRules();
+      return {
+        ok: true
+      };
+    },
+    /** Read the rules back — hit counts included, which the snapshot coalesces. */
+    listOverrideRules: () => overrideRulesStore.getState(),
+    /**
+     * The full body of one rule, for the surfaces the snapshot withheld it from
+     * (see `stripLargeRuleBodies`). Fetched when the user opens the rule, which
+     * is the only moment it's needed.
+     */
+    getOverrideRuleBody: params => {
+      const id = readId(params);
+      if (!id) return null;
+      // `getState().rules`, not `getRules()` — the latter reports nothing while
+      // the master switch is off, and a rule is perfectly editable then.
+      const rule = overrideRulesStore.getState().rules.find(candidate => candidate.id === id);
+      if (!rule) return null;
+      return {
+        body: rule.body ?? null
+      };
+    },
+    /** Why isn't my rule firing? Reports the engine's own view of the world. */
+    debugOverrides: params => {
+      const url = (params && typeof params === "object" ? params.url : undefined) ?? "https://example.com/";
+      return {
+        interceptorInstalled: isNetworkListening(),
+        listenerCount: getNetworkListenerCount(),
+        engine: inspectEngine(url, "GET"),
+        store: {
+          enabled: overrideRulesStore.getState().enabled,
+          ruleCount: overrideRulesStore.getState().rules.length,
+          rulesVisibleToEngine: overrideRulesStore.getRules().length
+        }
+      };
     }
   }
 };

package/lib/module/network/types/index.js

@@ -1 +1,3 @@
-"use strict";
+"use strict";
+
+export {};

package/lib/module/network/utils/networkEventStore.js

@@ -36,6 +36,13 @@ import { networkSavedStore } from "./networkSavedStore";
 
 class NetworkEventStore extends BaseEventStore {
   pendingRequests = new Map();
+  /**
+   * Recently seen `METHOD:url` keys → when, and which event id we kept.
+   *
+   * The timestamp powers the dual-interception dedup below. The id is what lets
+   * a DROPPED duplicate still contribute something the kept event doesn't know
+   * — see `applyOverrideMark`.
+   */
   recentRequests = new Map();
   rawListenerUnsubscribe = null;
   constructor() {
@@ -99,19 +106,31 @@ class NetworkEventStore extends BaseEventStore {
       // Check for duplicate request based on URL, method, and timing
       const requestKey = `${request.method}:${request.url}`;
       const now = Date.now();
-      const lastRequestTime = this.recentRequests.get(requestKey);
+      const recent = this.recentRequests.get(requestKey);
 
       // If same request within 50ms, likely a duplicate from XHR/fetch dual interception
-      if (lastRequestTime && now - lastRequestTime < 50) {
+      if (recent && now - recent.at < 50) {
+        // …but the duplicate is not always redundant. On React Native a
+        // `fetch()` is seen twice: once by the fetch wrapper, which is what
+        // creates this event, and again by the XHR wrapper underneath it —
+        // and ONLY the XHR layer resolves overrides, because that's where the
+        // request can actually be intercepted. So the mark arrives on the copy
+        // we're about to throw away. Move it across before dropping.
+        if (event.override) {
+          this.applyOverrideMark(recent.id, event.override);
+        }
         return;
       }
-      this.recentRequests.set(requestKey, now);
+      this.recentRequests.set(requestKey, {
+        at: now,
+        id: request.id
+      });
 
       // Clean up old entries to prevent memory leak
       if (this.recentRequests.size > 100) {
         const cutoff = now - 5000;
-        for (const [key, time] of this.recentRequests.entries()) {
-          if (time < cutoff) {
+        for (const [key, entry] of this.recentRequests.entries()) {
+          if (entry.at < cutoff) {
             this.recentRequests.delete(key);
           }
         }
@@ -145,7 +164,10 @@ class NetworkEventStore extends BaseEventStore {
         responseHeaders: {},
         requestClient: request.client,
         operationName,
-        graphqlVariables
+        graphqlVariables,
+        // Present when this request came straight through the XHR wrapper
+        // (axios, raw XHR). For `fetch` it arrives later — see the dedup branch.
+        override: event.override
       };
       this.pendingRequests.set(request.id, networkEvent);
       this.events = [networkEvent, ...this.events].slice(0, this.maxEvents);
@@ -174,6 +196,10 @@ class NetworkEventStore extends BaseEventStore {
           updatedEvent.error = event.error.message;
           updatedEvent.status = updatedEvent.status || 0;
         }
+
+        // A pure-XHR request carries its mark all the way through; a `fetch`
+        // one was marked at request time and is preserved by the spread above.
+        if (event.override) updatedEvent.override = event.override;
         this.events = this.events.map((e, i) => i === index ? updatedEvent : e);
         this.pendingRequests.delete(request.id);
         // Refresh any pinned/saved snapshot of this request — a request pinned
@@ -185,6 +211,26 @@ class NetworkEventStore extends BaseEventStore {
       }
     }
   }
+
+  /**
+   * Stamp an override mark onto an already-recorded event.
+   *
+   * Only ever moves a mark from a dropped duplicate onto the event that was
+   * kept, so it never overwrites one that is already there.
+   */
+  applyOverrideMark(id, override) {
+    const index = this.events.findIndex(e => e.id === id);
+    if (index === -1 || this.events[index].override) return;
+    const updatedEvent = {
+      ...this.events[index],
+      override
+    };
+    this.events = this.events.map((e, i) => i === index ? updatedEvent : e);
+    const pending = this.pendingRequests.get(id);
+    if (pending) this.pendingRequests.set(id, updatedEvent);
+    this.notify(updatedEvent);
+    this.notifyArrayListeners();
+  }
   extractHost(url) {
     try {
       const urlObj = new URL(url);