@buoy-gg/network 7.0.13 → 7.0.14

package/lib/commonjs/network/overrides/overrideRulesStore.js

@@ -0,0 +1,550 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.overrideRulesStore = void 0;
+var _sharedUi = require("@buoy-gg/shared-ui");
+var _networkListener = require("../utils/networkListener");
+var _engine = require("./engine");
+var _resolveOverride = require("./resolveOverride");
+var _types = require("./types");
+/**
+ * The override rule list — persisted, and the source of truth for the engine.
+ *
+ * Shape and persistence follow `networkSavedStore` / `ignoredPatternsStore`:
+ * lazy hydrate on first use, a `dirty` flag so a slow read can't clobber a
+ * mutation the user just made, and commit = set + emit + persist.
+ *
+ * Two things here are specific to overrides and worth reading:
+ *
+ *  - `getRules()` is on the HOT PATH. It is called inside the app's own
+ *    `XMLHttpRequest.send()`, for every request, so it does no work: the master
+ *    switch collapses to returning a frozen empty array.
+ *
+ *  - `syncKeepAlive()` keeps the interceptor installed while any rule is
+ *    active. Without it a rule would stop firing the moment the Network tool
+ *    closed, because the swizzle is reference-counted off capture subscribers.
+ */
+
+/**
+ * A rule as authored. `id`/`createdAt` and the runtime counters (`hits`,
+ * `seen`) are the store's business, never the caller's.
+ */
+
+/**
+ * Handlers the desktop dashboard installs to forward mutations to the device.
+ *
+ * Rules only DO anything on the device — a rule is applied inside the app's own
+ * `fetch`/`XMLHttpRequest`, which the dashboard doesn't have. So in remote mode
+ * this store becomes a MIRROR: it renders the device's rules and forwards every
+ * edit, writing nothing to this machine's storage. Same seam
+ * `networkSavedStore` uses for pins.
+ */
+
+/**
+ * How long a local optimistic write suppresses incoming mirrors.
+ *
+ * An edit is applied locally AND forwarded; the device echoes it back on its
+ * next snapshot. Without this window the in-flight snapshot — the one already
+ * on the wire when the user tapped — would land first and visibly revert the
+ * edit for a frame.
+ */
+const REMOTE_ECHO_GRACE_MS = 800;
+
+/**
+ * Launches-with-rules-on before overrides pause themselves.
+ *
+ * Persisting rules is the point ("force a 500, restart, watch the boot path"),
+ * but a body the app can't render turns that into a brick: the rule reinstates
+ * itself on every launch and the controls to remove it live inside an app that
+ * no longer draws. Verified in testing — the only exit was deleting the file
+ * off the simulator.
+ *
+ * Three is chosen so the intended workflow survives (force, relaunch, look,
+ * relaunch, look) while a wedge cannot outlive the second relaunch. The streak
+ * resets whenever a rule is created or edited, so an actively-used rule set
+ * never pauses.
+ */
+const MAX_UNTOUCHED_LAUNCHES = 3;
+const EMPTY_RULES = Object.freeze([]);
+
+/** Hit counts change per request; the UI shouldn't re-render per request. */
+const HIT_EMIT_COALESCE_MS = 250;
+const VALID_KINDS = ["respond", "fail", "delay"];
+
+/**
+ * Tolerate junk and older shapes rather than throwing the list away.
+ *
+ * Storage is forever: a shape that throws on parse would take the whole feature
+ * down on every launch until the user cleared app data.
+ */
+function parseRules(raw) {
+  if (!Array.isArray(raw)) return [];
+  const parsed = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object") continue;
+    const rule = entry;
+    if (typeof rule.id !== "string" || typeof rule.urlPattern !== "string") {
+      continue;
+    }
+    if (!rule.urlPattern) continue;
+    const kind = VALID_KINDS.includes(rule.kind) ? rule.kind : "respond";
+    parsed.push({
+      id: rule.id,
+      enabled: rule.enabled !== false,
+      name: typeof rule.name === "string" ? rule.name : undefined,
+      urlPattern: rule.urlPattern,
+      methods: Array.isArray(rule.methods) ? rule.methods.filter(m => typeof m === "string") : undefined,
+      kind,
+      status: typeof rule.status === "number" ? Math.min(_types.STATUS_MAX, Math.max(_types.STATUS_MIN, rule.status)) : undefined,
+      statusText: typeof rule.statusText === "string" ? rule.statusText : undefined,
+      headers: rule.headers && typeof rule.headers === "object" ? rule.headers : undefined,
+      body: typeof rule.body === "string" ? rule.body : undefined,
+      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,
+      // Runtime-only: a rule that fired 3 times last launch has fired 0 times
+      // this one, and a persisted count would make `times` mean "ever" instead
+      // of "this session".
+      hits: 0,
+      seen: 0,
+      createdAt: typeof rule.createdAt === "number" ? rule.createdAt : 0
+    });
+  }
+  return parsed.slice(0, _types.MAX_RULES);
+}
+class OverrideRulesStore {
+  rules = [];
+  enabled = true;
+  listeners = new Set();
+  loaded = false;
+  loadPromise = null;
+  /** Set once a mutation happens so a slow initial load can't clobber it. */
+  dirty = false;
+  idCounter = 0;
+  state = {
+    enabled: true,
+    rules: [],
+    autoPaused: false
+  };
+  /** Consecutive launches that began with rules armed and nobody touching them. */
+  launchStreak = 0;
+  autoPaused = false;
+  /** Held while any rule is active — see `syncKeepAlive`. */
+  keepAlive = null;
+  hitEmitTimer = null;
+  /** Set on the desktop dashboard — see `disableEngine`. */
+  engineDisabled = false;
+  /** Set on the desktop dashboard — see `OverrideRulesRemote`. */
+  remote = null;
+  remoteEchoUntil = 0;
+
+  // ===========================================================================
+  // REMOTE MIRROR (desktop dashboard)
+  // ===========================================================================
+
+  /**
+   * Turn this store into a mirror of a connected device's rules. Edits are
+   * applied locally for immediate feedback AND forwarded to the device, which
+   * is the source of truth; nothing is persisted to this machine.
+   */
+  enableRemoteMode(remote) {
+    this.remote = remote;
+    // A dashboard must never run rules against its own traffic.
+    this.disableEngine();
+  }
+  disableRemoteMode() {
+    this.remote = null;
+  }
+
+  /**
+   * Feed the device's rules in (mirror mode only). `force` bypasses the echo
+   * guard — used when tearing the mirror down, where there is no later snapshot
+   * to converge on.
+   */
+  replaceRules(state, force = false) {
+    if (!this.remote) return;
+    // A local edit is still in flight — the snapshot on the wire predates it
+    // and would flicker the change away. Drop this one; the next carries the
+    // device's real answer.
+    if (!force && Date.now() < this.remoteEchoUntil) return;
+    this.enabled = state.enabled;
+    this.rules = state.rules;
+    this.rebuild();
+    this.emit();
+  }
+
+  /** Mark a local optimistic write so the next in-flight mirror is ignored. */
+  markLocalEdit() {
+    if (this.remote) this.remoteEchoUntil = Date.now() + REMOTE_ECHO_GRACE_MS;
+  }
+
+  /**
+   * Never intercept traffic in this runtime.
+   *
+   * The desktop dashboard renders the real tool (`NetworkToolView`), so this
+   * module is imported there too — but the dashboard is a VIEWER. Its job is to
+   * drive rules on the connected device, never to swizzle its own `fetch` and
+   * override its own requests. The same seam `networkEventStore.disableCapture()`
+   * uses, for the same reason.
+   */
+  disableEngine() {
+    this.engineDisabled = true;
+    if (this.keepAlive) {
+      this.keepAlive();
+      this.keepAlive = null;
+      if ((0, _networkListener.getNetworkListenerCount)() === 0) (0, _networkListener.stopNetworkListener)();
+    }
+  }
+  getState() {
+    return this.state;
+  }
+
+  /**
+   * The hot path — called inside `send()` for every request the app makes.
+   * Returns a frozen empty array when the master switch is off so the caller
+   * needs no second check.
+   */
+  getRules() {
+    if (this.engineDisabled || !this.enabled) return EMPTY_RULES;
+    return this.rules;
+  }
+
+  /**
+   * The rule's real body, fetching it from the device when this surface only
+   * has the stripped copy (see `OverrideRule.bodyOmitted`).
+   *
+   * On the device itself every body is already here, so this resolves
+   * immediately and the editor never notices the difference.
+   */
+  async fetchRuleBody(id) {
+    const rule = this.rules.find(candidate => candidate.id === id);
+    if (!rule) return null;
+    if (!rule.bodyOmitted) return rule.body ?? null;
+    if (!this.remote?.getRuleBody) return null;
+    try {
+      return await this.remote.getRuleBody(id);
+    } catch {
+      // The editor keeps the empty body and the developer can retype it —
+      // better than an error state over a payload they can still replace.
+      return null;
+    }
+  }
+
+  /** Rules that would actually fire — drives the "overrides active" banner. */
+  activeCount() {
+    if (!this.enabled) return 0;
+    return this.rules.filter(rule => rule.enabled && !(0, _resolveOverride.isSpent)(rule)).length;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    void this.ensureLoaded();
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  // ===========================================================================
+  // MUTATIONS
+  // ===========================================================================
+
+  setEnabled(enabled) {
+    if (this.enabled === enabled) return;
+    this.remote?.setEnabled(enabled);
+    this.markLocalEdit();
+    this.markTouched();
+    this.enabled = enabled;
+    this.commit(this.rules);
+  }
+  addRule(draft) {
+    if (this.rules.length >= _types.MAX_RULES) return null;
+    const rule = {
+      ...draft,
+      id: `ovr_${Date.now().toString(36)}_${++this.idCounter}`,
+      hits: 0,
+      seen: 0,
+      createdAt: Date.now()
+    };
+    // Newest first: a rule you just made should win over an older, broader one,
+    // because first-match wins and you almost certainly meant the new one.
+    this.commit([rule, ...this.rules]);
+    return rule;
+  }
+
+  /**
+   * Create or replace a rule in one call.
+   *
+   * THE ONLY WRITE PATH THE UI SHOULD USE. `addRule`/`updateRule` are the
+   * primitives underneath and deliberately do NOT forward to the device — if
+   * the UI called them directly, an edit made on the dashboard would apply to
+   * the mirror and never reach the phone, which looks exactly like it worked.
+   *
+   * Returns the rule, or null when the list is full.
+   */
+  upsertRule(draft) {
+    this.remote?.upsertRule(draft);
+    this.markLocalEdit();
+    this.markTouched();
+    const {
+      id,
+      ...rest
+    } = draft;
+    if (id && this.rules.some(rule => rule.id === id)) {
+      this.updateRule(id, rest);
+      return this.rules.find(rule => rule.id === id) ?? null;
+    }
+    return this.addRule(rest);
+  }
+  updateRule(id, patch) {
+    const index = this.rules.findIndex(rule => rule.id === id);
+    if (index === -1) return;
+    const next = [...this.rules];
+    // Editing a rule resets its budget — otherwise a spent "fail once" rule
+    // stays silently dead after you change it and looks broken.
+    next[index] = {
+      ...next[index],
+      ...patch,
+      hits: 0,
+      seen: 0
+    };
+    this.commit(next);
+  }
+  setRuleEnabled(id, enabled) {
+    const index = this.rules.findIndex(rule => rule.id === id);
+    if (index === -1 || this.rules[index].enabled === enabled) return;
+    this.remote?.setRuleEnabled(id, enabled);
+    this.markLocalEdit();
+    this.markTouched();
+    const next = [...this.rules];
+    // Re-enabling a spent rule has to clear its budget too, or the toggle
+    // appears to do nothing.
+    next[index] = {
+      ...next[index],
+      enabled,
+      hits: enabled ? 0 : next[index].hits,
+      seen: enabled ? 0 : next[index].seen
+    };
+    this.commit(next);
+  }
+  removeRule(id) {
+    const next = this.rules.filter(rule => rule.id !== id);
+    if (next.length === this.rules.length) return;
+    this.remote?.removeRule(id);
+    this.markLocalEdit();
+    this.markTouched();
+    this.commit(next);
+  }
+  clearRules() {
+    if (this.rules.length === 0) return;
+    this.remote?.clearRules();
+    this.markLocalEdit();
+    this.markTouched();
+    this.commit([]);
+  }
+
+  /**
+   * One rule matched one request.
+   *
+   * Replaces the rule object rather than mutating it so memoized rows actually
+   * re-render, and coalesces the notification — this runs at request rate.
+   */
+  /**
+   * One rule matched one request, applied or not.
+   *
+   * Deliberately silent — this fires on requests an alternating rule lets
+   * through, where nothing visible changed. `recordHit` owns the notification.
+   */
+  recordMatch(ruleId) {
+    const index = this.rules.findIndex(rule => rule.id === ruleId);
+    if (index === -1) return;
+    const next = [...this.rules];
+    next[index] = {
+      ...next[index],
+      seen: next[index].seen + 1
+    };
+    this.rules = next;
+    this.rebuild();
+  }
+  recordHit(ruleId) {
+    const index = this.rules.findIndex(rule => rule.id === ruleId);
+    if (index === -1) return;
+    const rule = this.rules[index];
+    const hits = rule.hits + 1;
+    const spent = typeof rule.times === "number" && hits >= rule.times;
+    const next = [...this.rules];
+    next[index] = {
+      ...rule,
+      hits,
+      enabled: spent ? false : rule.enabled
+    };
+    if (spent) {
+      // Auto-expiry is a real state change (and releases the keep-alive), so it
+      // commits immediately instead of waiting on the coalesce window.
+      this.commit(next);
+      return;
+    }
+    this.rules = next;
+    this.rebuild();
+    this.scheduleHitEmit();
+  }
+
+  // ===========================================================================
+  // LIFECYCLE
+  // ===========================================================================
+
+  /**
+   * Hydrate from storage. Safe to call repeatedly; only the first call reads.
+   *
+   * Called at package import (see `preset.tsx`) rather than on first subscribe,
+   * because a rule has to fire from app boot — with the Network tool closed and
+   * nothing capturing.
+   */
+  ensureLoaded() {
+    // Mirror mode reads the device's rules, never this machine's storage.
+    if (this.remote) return Promise.resolve();
+    if (this.loaded) return Promise.resolve();
+    if (this.loadPromise) return this.loadPromise;
+    this.loadPromise = (async () => {
+      try {
+        const stored = await _sharedUi.persistentStorage.getItem(_sharedUi.devToolsStorageKeys.network.overrides());
+        // A rule may have been created while this read was in flight — never
+        // overwrite user intent with older disk state.
+        if (stored && !this.dirty) {
+          const parsed = JSON.parse(stored);
+          this.enabled = parsed?.enabled !== false;
+          this.rules = parseRules(parsed?.rules);
+          this.launchStreak = typeof parsed?.launchStreak === "number" ? parsed.launchStreak : 0;
+          this.applyLaunchGuard();
+          this.rebuild();
+        }
+      } catch {
+        // Corrupt or unreadable — start empty rather than taking the tool down.
+      } finally {
+        this.loaded = true;
+        this.syncKeepAlive();
+        this.emit();
+      }
+    })();
+    return this.loadPromise;
+  }
+
+  /**
+   * Count this launch, and pause overrides if they've been armed and untouched
+   * for too many in a row. See MAX_UNTOUCHED_LAUNCHES for why.
+   */
+  applyLaunchGuard() {
+    if (!this.enabled || this.activeCount() === 0) {
+      this.launchStreak = 0;
+      return;
+    }
+    this.launchStreak += 1;
+    if (this.launchStreak >= MAX_UNTOUCHED_LAUNCHES) {
+      this.enabled = false;
+      this.autoPaused = true;
+      this.launchStreak = 0;
+    }
+    this.persist();
+  }
+
+  /**
+   * Keep the interceptor installed for as long as a rule could fire.
+   *
+   * The swizzle is reference-counted off `networkListener`'s listener count
+   * (the event store adds one while capturing). Holding a no-op listener reuses
+   * that existing lifecycle instead of inventing a second one.
+   */
+  syncKeepAlive() {
+    const needed = !this.engineDisabled && this.activeCount() > 0;
+    if (needed && !this.keepAlive) {
+      (0, _networkListener.startNetworkListener)();
+      this.keepAlive = (0, _networkListener.addNetworkListener)(() => {});
+      return;
+    }
+    if (!needed && this.keepAlive) {
+      this.keepAlive();
+      this.keepAlive = null;
+      // Only tear the swizzle down if nothing else wants it — the Network tool
+      // may well still be open and capturing.
+      if ((0, _networkListener.getNetworkListenerCount)() === 0) (0, _networkListener.stopNetworkListener)();
+    }
+  }
+  scheduleHitEmit() {
+    if (this.hitEmitTimer !== null) return;
+    this.hitEmitTimer = setTimeout(() => {
+      this.hitEmitTimer = null;
+      this.emit();
+    }, HIT_EMIT_COALESCE_MS);
+  }
+  commit(next) {
+    this.dirty = true;
+    this.rules = next.slice(0, _types.MAX_RULES);
+    this.rebuild();
+    this.syncKeepAlive();
+    this.emit();
+    this.persist();
+  }
+
+  /** Rebuild the derived view once per mutation so renders get stable refs. */
+  rebuild() {
+    this.state = {
+      enabled: this.enabled,
+      rules: this.rules,
+      autoPaused: this.autoPaused
+    };
+  }
+
+  /**
+   * The developer is actively working with the rules, so the launch guard has
+   * nothing to protect them from — reset it and clear any auto-pause notice.
+   */
+  markTouched() {
+    this.launchStreak = 0;
+    this.autoPaused = false;
+  }
+
+  /**
+   * The developer reached the override UI, which is proof the app still runs.
+   *
+   * The launch guard exists to escape a WEDGE — a body the app can't render,
+   * where the controls are unreachable because nothing draws. If this call
+   * happens, that isn't the situation, so the streak has nothing to protect
+   * against. Without it the guard nags anyone who legitimately keeps a rule
+   * armed for days, which is a real workflow ("force /checkout to 500 every
+   * morning") and not the failure mode it was built for.
+   */
+  noteHealthyLaunch() {
+    if (this.launchStreak === 0 && !this.autoPaused) return;
+    this.markTouched();
+    this.persist();
+    this.rebuild();
+    this.emit();
+  }
+  persist() {
+    // The dashboard must not write the device's rules into its own storage —
+    // they'd outlive the connection and shadow the next device.
+    if (this.remote) return;
+    _sharedUi.persistentStorage.setItem(_sharedUi.devToolsStorageKeys.network.overrides(), JSON.stringify({
+      enabled: this.enabled,
+      rules: this.rules,
+      launchStreak: this.launchStreak
+    })).catch(() => {
+      // Silently fail — rules remain in memory for this session.
+    });
+  }
+  emit() {
+    this.listeners.forEach(listener => listener());
+  }
+}
+
+/** Singleton — one rule list per JS runtime. */
+const overrideRulesStore = exports.overrideRulesStore = new OverrideRulesStore();
+
+// Register with the engine so `networkListener` can reach the rules without
+// importing this module (which imports the listener — see engine.ts).
+(0, _engine.setOverrideHooks)({
+  getRules: () => overrideRulesStore.getRules(),
+  recordHit: ruleId => overrideRulesStore.recordHit(ruleId),
+  recordMatch: ruleId => overrideRulesStore.recordMatch(ruleId)
+});

package/lib/commonjs/network/overrides/presets.js

@@ -0,0 +1,70 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.draftFromEvent = draftFromEvent;
+exports.patternForUrl = patternForUrl;
+/**
+ * Turning a captured request into a rule draft.
+ *
+ * Chrome's flow assumes a keyboard, a file tree and a second monitor. On a
+ * phone the equivalent has to start from the request you're already looking at,
+ * which is what this file is for — the editor never opens on a blank field.
+ *
+ * There used to be a list of one-tap presets here (Force 500, Empty list,
+ * Offline…) rendered as chips. They're gone: the editor's outcome grid says the
+ * same things in the same words, so keeping both meant two lists to maintain
+ * and two places to look for the same choice.
+ */
+
+/**
+ * Turn a captured URL into a pattern that will match the request AGAIN.
+ *
+ * The query string is dropped and replaced with `*`, which is not a
+ * simplification — it's the difference between a rule that works and one that
+ * silently never fires. Plenty of clients cache-bust
+ * (`?timestamp=1785783081234`), carry a request id, or page; pinning the exact
+ * URL means the next call to the same endpoint doesn't match. Found exactly
+ * that way: an "Offline" preset on a Pokémon request sat at 0 hits because the
+ * app appends a timestamp to every call.
+ *
+ * The path stays exact, so this still means "this endpoint" and not "this
+ * host" — and the editor shows the pattern, so narrowing it back down is one
+ * edit away.
+ */
+function patternForUrl(url) {
+  const query = url.indexOf("?");
+  return query === -1 ? url : `${url.slice(0, query)}*`;
+}
+
+/** Render a captured body as editable text. */
+function bodyToText(data) {
+  if (data == null) return "";
+  if (typeof data === "string") return data;
+  try {
+    return JSON.stringify(data, null, 2);
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Prefill the rule editor from a captured request.
+ *
+ * Seeds the REAL response as the body so the common edit — change two fields of
+ * a payload you just saw — starts from something true rather than from nothing.
+ */
+function draftFromEvent(event) {
+  return {
+    enabled: true,
+    name: undefined,
+    urlPattern: patternForUrl(event.url),
+    methods: [String(event.method || "GET").toUpperCase()],
+    kind: "respond",
+    status: event.status && event.status >= 200 ? event.status : 200,
+    statusText: event.statusText,
+    body: bodyToText(event.responseData),
+    times: null
+  };
+}