@buoy-gg/network 7.0.4 → 7.0.6

package/lib/commonjs/network/utils/networkSavedStore.js

@@ -0,0 +1,575 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SESSION_ID = exports.MAX_SAVED = exports.MAX_PINNED = exports.FREE_TIER_SAVED_LIMIT = void 0;
+exports.flagsForEventId = flagsForEventId;
+exports.networkSavedStore = void 0;
+var _sharedUi = require("@buoy-gg/shared-ui");
+/**
+ * Pinned + saved network requests.
+ *
+ * The live `networkEventStore` is volatile by design: it caps at 500 events
+ * and `clearEvents()` wipes it. So "pin this failure so I don't lose it"
+ * cannot be an ID pointing into that store — it has to be a SNAPSHOT that
+ * outlives the stream. This store owns those snapshots and persists them.
+ *
+ * Two independent flags per record:
+ *   - `pinned` — hoisted into the PINNED section at the top of the list,
+ *     unaffected by search/filters.
+ *   - `saved`  — kept in the Saved (favorites) screen, out of the live stream.
+ * A record exists while either flag is true and is dropped when both go false,
+ * so all four states fall out without special cases.
+ *
+ * IDENTITY WARNING: `networkListener` mints request IDs from a per-runtime
+ * counter (`fetch_1`, `xhr_2`), so after an app reload `fetch_1` is a
+ * DIFFERENT request. Records are therefore keyed on a generated `key`, carry
+ * the `sessionId` that captured them, and only trust `liveId` while that
+ * session is the current one. Snapshots restored from an earlier session get
+ * their event `id` rewritten to `saved:<key>` so a restored pin can never
+ * resolve to (or dedupe against) an unrelated live request.
+ *
+ * Shape/persistence follows `ignoredPatternsStore` in @buoy-gg/shared-ui:
+ * lazy hydrate on first subscribe, a `dirty` flag so a slow read can't clobber
+ * a mutation, and commit = set + emit + persist.
+ */
+
+/** Identifies THIS runtime. Records from other sessions can't trust `liveId`. */
+const SESSION_ID = exports.SESSION_ID = `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+
+/** Pins render un-virtualized in the list header, so the count stays bounded. */
+const MAX_PINNED = exports.MAX_PINNED = 25;
+/** Upper bound on the persisted favorites list (oldest unpinned evicted). */
+const MAX_SAVED = exports.MAX_SAVED = 50;
+/** Free tier keeps a handful of favorites; Pro is unlimited (up to MAX_SAVED). */
+const FREE_TIER_SAVED_LIMIT = exports.FREE_TIER_SAVED_LIMIT = 5;
+/** Per-body cap on a snapshot. */
+const BODY_LIMIT = 16 * 1024;
+/**
+ * Total body bytes kept across ALL records. `persistentStorage` falls back to
+ * AsyncStorage on RN CLI (no expo-file-system), which has real per-key size
+ * limits, so the blob is budgeted rather than left to grow. Bodies are dropped
+ * oldest-first, pins last.
+ */
+const TOTAL_BODY_BUDGET = 512 * 1024;
+
+/** Why a toggle didn't take effect, so the UI can explain itself. */
+
+/**
+ * Is this actually a network event we can store and re-render later?
+ *
+ * This store WRITES TO DISK, which turns "accept whatever you're handed" into a
+ * permanent failure: a bad value becomes a record, the record is persisted, and
+ * every subsequent render of the pinned strip throws on it — a crash loop that
+ * survives restarts. Found exactly that way, by an automation harness invoking
+ * a row's `onLongPress` with a gesture object instead of the row's event
+ * (`TypeError: Cannot read property 'replace' of undefined` in the row, from
+ * `event.url.replace(...)`).
+ *
+ * `id` and `url` are the two fields the row and detail views dereference
+ * without guarding, so they are the bar for admission — both here, where
+ * records are created, and in `parseRecords`, so anything already on disk is
+ * dropped at hydration instead of crashing forever.
+ */
+function isStorableEvent(value) {
+  if (!value || typeof value !== "object") return false;
+  const event = value;
+  return typeof event.id === "string" && typeof event.url === "string";
+}
+
+/**
+ * Handlers the desktop dashboard installs to forward mutations to the device.
+ *
+ * The dashboard must not keep its own copy of the device's pins: the device is
+ * the only place the snapshots can stay in sync with the traffic that produced
+ * them (and the only place a >16KB body still exists). So in remote mode this
+ * store becomes a MIRROR — same seam `networkEventStore.disableCapture()` +
+ * `replaceEvents()` uses for the event list.
+ */
+
+/**
+ * How long a local optimistic write suppresses incoming mirrors.
+ *
+ * A toggle is applied locally AND forwarded; the device echoes the new state
+ * 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 toggle for a frame.
+ */
+const REMOTE_ECHO_GRACE_MS = 800;
+
+/**
+ * Read an event's flags out of a state snapshot.
+ *
+ * Two lookups because an event ID means two different things: a live request
+ * matches by `liveId` (the fast Set path), while a snapshot restored from an
+ * earlier session carries the namespaced `saved:<key>` id and has to be found
+ * among the records.
+ */
+function flagsForEventId(state, eventId) {
+  if (!eventId) return {
+    pinned: false,
+    saved: false
+  };
+  const pinned = state.pinnedLiveIds.has(eventId);
+  const saved = state.savedLiveIds.has(eventId);
+  if (pinned || saved) return {
+    pinned,
+    saved
+  };
+  const record = state.records.find(entry => entry.event.id === eventId);
+  return record ? {
+    pinned: record.pinned,
+    saved: record.saved
+  } : {
+    pinned: false,
+    saved: false
+  };
+}
+const EMPTY_STATE = {
+  records: [],
+  pinnedEvents: [],
+  savedRecords: [],
+  pinnedLiveIds: new Set(),
+  savedLiveIds: new Set()
+};
+function truncateBody(data) {
+  if (data === undefined || data === null) return {
+    value: data,
+    truncated: false
+  };
+  if (typeof data === "string") {
+    if (data.length <= BODY_LIMIT) return {
+      value: data,
+      truncated: false
+    };
+    return {
+      value: `${data.slice(0, BODY_LIMIT)}\n\n… truncated by Buoy (body exceeded ${BODY_LIMIT} bytes)`,
+      truncated: true
+    };
+  }
+  try {
+    const serialized = JSON.stringify(data);
+    if (serialized === undefined) return {
+      value: undefined,
+      truncated: false
+    };
+    if (serialized.length <= BODY_LIMIT) return {
+      value: data,
+      truncated: false
+    };
+    return {
+      value: `${serialized.slice(0, BODY_LIMIT)}\n\n… truncated by Buoy (body exceeded ${BODY_LIMIT} bytes)`,
+      truncated: true
+    };
+  } catch {
+    // Circular or otherwise unserializable — it can't be persisted anyway.
+    return {
+      value: "[unserializable body]",
+      truncated: true
+    };
+  }
+}
+
+/** Freeze an event into a persistable snapshot with capped bodies. */
+function snapshot(event) {
+  const request = truncateBody(event.requestData);
+  const response = truncateBody(event.responseData);
+  if (!request.truncated && !response.truncated) {
+    return {
+      event: {
+        ...event
+      },
+      bodyTruncated: false
+    };
+  }
+  return {
+    event: {
+      ...event,
+      requestData: request.value,
+      responseData: response.value
+    },
+    bodyTruncated: true
+  };
+}
+
+/**
+ * Bytes a snapshot's bodies actually occupy. Sizes are clamped to BODY_LIMIT
+ * because `snapshot()` already truncated anything larger, and a stripped body
+ * counts as zero — otherwise the budget would never converge.
+ */
+function bodyBytes(event) {
+  let total = 0;
+  if (event.requestData != null) {
+    total += Math.min(event.requestSize ?? 0, BODY_LIMIT);
+  }
+  if (event.responseData != null) {
+    total += Math.min(event.responseSize ?? 0, BODY_LIMIT);
+  }
+  return total;
+}
+
+/**
+ * Enforce TOTAL_BODY_BUDGET by stripping bodies from the least important
+ * records first (oldest, unpinned). The record itself — URL, status, headers,
+ * timings, the error — always survives; only the payload goes.
+ */
+function applyBodyBudget(records) {
+  let total = 0;
+  for (const record of records) total += bodyBytes(record.event);
+  if (total <= TOTAL_BODY_BUDGET) return records;
+
+  // Keep bodies for pins first, then newest saves.
+  const priority = [...records].sort((a, b) => {
+    if (a.pinned !== b.pinned) return a.pinned ? -1 : 1;
+    return b.savedAt - a.savedAt;
+  });
+  const stripped = new Set();
+  let kept = 0;
+  for (const record of priority) {
+    const size = bodyBytes(record.event);
+    if (kept + size <= TOTAL_BODY_BUDGET) {
+      kept += size;
+    } else {
+      stripped.add(record.key);
+    }
+  }
+  if (stripped.size === 0) return records;
+  return records.map(record => stripped.has(record.key) ? {
+    ...record,
+    event: {
+      ...record.event,
+      requestData: undefined,
+      responseData: undefined
+    },
+    bodyTruncated: true
+  } : record);
+}
+
+/** Tolerate junk/older shapes in storage rather than throwing away the list. */
+function parseRecords(raw) {
+  if (!Array.isArray(raw)) return [];
+  const parsed = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object") continue;
+    const record = entry;
+    if (typeof record.key !== "string") continue;
+    // Not just "is an object" — a record whose event can't be rendered would
+    // crash the list on every launch, and storage is forever. Drop it instead.
+    if (!isStorableEvent(record.event)) continue;
+    if (!record.pinned && !record.saved) continue;
+    parsed.push({
+      key: record.key,
+      // A restored snapshot's `event.id` is a stale per-runtime counter, so it
+      // is rewritten to a namespaced id that can never collide with a live one.
+      event: {
+        ...record.event,
+        id: `saved:${record.key}`
+      },
+      pinned: !!record.pinned,
+      saved: !!record.saved,
+      savedAt: typeof record.savedAt === "number" ? record.savedAt : 0,
+      sessionId: typeof record.sessionId === "string" ? record.sessionId : "unknown",
+      liveId: typeof record.liveId === "string" ? record.liveId : "",
+      bodyTruncated: !!record.bodyTruncated
+    });
+  }
+  return parsed;
+}
+class NetworkSavedStore {
+  records = [];
+  listeners = new Set();
+  loaded = false;
+  loadPromise = null;
+  /** Set once a mutation happens so a slow initial load can't clobber it. */
+  dirty = false;
+  keyCounter = 0;
+  /**
+   * Live IDs tracked in THIS session. `syncFromLive` runs on every captured
+   * response, so the hot path has to be a Set membership test.
+   */
+  trackedLiveIds = new Set();
+  /** Derived view, rebuilt on commit so consumers get stable references. */
+  state = EMPTY_STATE;
+  /** Set on the desktop dashboard — see NetworkSavedRemote. */
+  remote = null;
+  remoteEchoUntil = 0;
+  getState() {
+    return this.state;
+  }
+
+  // ===========================================================================
+  // REMOTE MIRROR (desktop dashboard)
+  // ===========================================================================
+
+  /**
+   * Turn this store into a mirror of a connected device's records. Mutations
+   * 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;
+  }
+  disableRemoteMode() {
+    this.remote = null;
+  }
+
+  /**
+   * Feed the device's records in (mirror mode only). `force` bypasses the
+   * echo guard — used when tearing the mirror down, where there is no later
+   * snapshot to converge on.
+   */
+  replaceRecords(records, force = false) {
+    if (!this.remote) return;
+    // A local toggle is still in flight — the snapshot on the wire predates it
+    // and would flicker the button back. Drop this one; the next carries the
+    // device's real answer.
+    if (!force && Date.now() < this.remoteEchoUntil) return;
+    this.records = records;
+    this.rebuild();
+    this.emit();
+  }
+
+  /**
+   * Whether a record's `liveId` can be trusted against the current event
+   * stream. Locally that means "captured in this runtime"; mirrored, the ids
+   * belong to the device whose events we are also mirroring, so they line up
+   * by construction.
+   */
+  sessionMatches(record) {
+    return this.remote !== null || record.sessionId === SESSION_ID;
+  }
+  getRecords() {
+    return this.records;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    void this.ensureLoaded();
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /**
+   * Resolve an event the live store no longer has — a pin whose request was
+   * cleared or aged out, or a snapshot restored from an earlier session.
+   */
+  getEventById(id) {
+    for (const record of this.records) {
+      if (record.event.id === id) return record.event;
+    }
+    return null;
+  }
+  isPinned(liveId) {
+    return this.state.pinnedLiveIds.has(liveId);
+  }
+  isSaved(liveId) {
+    return this.state.savedLiveIds.has(liveId);
+  }
+
+  /**
+   * Keep a tracked snapshot current while its request is still in flight —
+   * pinning a pending request would otherwise freeze it as "Pending" forever.
+   * Called from `networkEventStore` for every response/error, so the no-op
+   * path (nothing pinned) is a single empty-Set check.
+   */
+  syncFromLive(event) {
+    if (this.trackedLiveIds.size === 0) return;
+    if (!this.trackedLiveIds.has(event.id)) return;
+    const index = this.records.findIndex(record => this.sessionMatches(record) && record.liveId === event.id);
+    if (index === -1) return;
+    const next = snapshot(event);
+    this.commit(this.records.map((record, i) => i === index ? {
+      ...record,
+      event: next.event,
+      bodyTruncated: next.bodyTruncated
+    } : record));
+  }
+  togglePin(event) {
+    return this.setFlag(event, "pinned");
+  }
+  toggleSave(event) {
+    return this.setFlag(event, "saved");
+  }
+
+  /** Drop a record outright, whatever its flags. */
+  remove(key) {
+    if (!this.records.some(record => record.key === key)) return;
+    this.remote?.removeRecord(key);
+    this.commit(this.records.filter(record => record.key !== key));
+  }
+
+  /** Empty the favorites list; pinned-only records stay pinned. */
+  clearSaved() {
+    if (!this.records.some(record => record.saved)) return;
+    this.remote?.clearSaved();
+    this.commit(this.records.filter(record => record.pinned).map(record => ({
+      ...record,
+      saved: false
+    })));
+  }
+
+  /** Unpin everything; saved-only records stay saved. */
+  clearPinned() {
+    if (!this.records.some(record => record.pinned)) return;
+    this.remote?.clearPinned();
+    this.commit(this.records.filter(record => record.saved).map(record => ({
+      ...record,
+      pinned: false
+    })));
+  }
+  setFlag(event, flag) {
+    // Gate every write on a real event — see isStorableEvent. Rejecting here is
+    // what keeps a bad caller from turning into persisted, crash-looping state.
+    if (!isStorableEvent(event)) return {
+      ok: false,
+      reason: "invalid-event"
+    };
+    const existing = this.findRecordFor(event);
+
+    // Mirror mode: tell the device first, then apply the same change locally so
+    // the button responds now instead of a snapshot later.
+    if (this.remote) {
+      const next = existing ? !existing[flag] : true;
+      if (flag === "pinned") this.remote.setPinned(event.id, next);else this.remote.setSaved(event.id, next);
+      this.remoteEchoUntil = Date.now() + REMOTE_ECHO_GRACE_MS;
+    }
+    if (existing) {
+      const next = !existing[flag];
+      if (next && !this.hasRoomFor(flag, existing.key)) {
+        return {
+          ok: false,
+          reason: flag === "pinned" ? "pin-cap" : "saved-cap"
+        };
+      }
+      const updated = {
+        ...existing,
+        [flag]: next
+      };
+      this.commit(updated.pinned || updated.saved ? this.records.map(record => record.key === existing.key ? updated : record) : this.records.filter(record => record.key !== existing.key));
+      return {
+        ok: true,
+        active: next
+      };
+    }
+    if (!this.hasRoomFor(flag, null)) {
+      return {
+        ok: false,
+        reason: flag === "pinned" ? "pin-cap" : "saved-cap"
+      };
+    }
+    const savedAt = Date.now();
+    const frozen = snapshot(event);
+    const record = {
+      key: `${SESSION_ID}_${++this.keyCounter}`,
+      event: frozen.event,
+      pinned: flag === "pinned",
+      saved: flag === "saved",
+      savedAt,
+      sessionId: SESSION_ID,
+      liveId: event.id,
+      bodyTruncated: frozen.bodyTruncated
+    };
+    this.commit(this.evictIfNeeded([record, ...this.records]));
+    return {
+      ok: true,
+      active: true
+    };
+  }
+
+  /**
+   * Match an event to its record: by live ID within this session, or by the
+   * namespaced snapshot ID when the row being toggled IS a restored snapshot.
+   */
+  findRecordFor(event) {
+    return this.records.find(record => record.event.id === event.id || this.sessionMatches(record) && record.liveId === event.id);
+  }
+  hasRoomFor(flag, exceptKey) {
+    const limit = flag === "pinned" ? MAX_PINNED : MAX_SAVED;
+    const count = this.records.filter(record => record[flag] && record.key !== exceptKey).length;
+    return count < limit;
+  }
+
+  /** Trim the oldest UNPINNED saves once the list outgrows MAX_SAVED. */
+  evictIfNeeded(records) {
+    const saved = records.filter(record => record.saved);
+    if (saved.length <= MAX_SAVED) return records;
+    const evictable = saved.filter(record => !record.pinned).sort((a, b) => a.savedAt - b.savedAt).slice(0, saved.length - MAX_SAVED);
+    if (evictable.length === 0) return records;
+    const evicted = new Set(evictable.map(record => record.key));
+    return records.filter(record => !evicted.has(record.key));
+  }
+  ensureLoaded() {
+    // Mirror mode reads the device's records, 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.saved());
+        // A pin may have raced this read — never overwrite user intent.
+        if (stored && !this.dirty) {
+          this.records = parseRecords(JSON.parse(stored));
+          this.rebuild();
+        }
+      } catch {
+        // Corrupt or unreadable — start empty rather than crashing the tool.
+      } finally {
+        this.loaded = true;
+        this.emit();
+      }
+    })();
+    return this.loadPromise;
+  }
+  persist() {
+    // The dashboard must not write the device's pins into its own storage —
+    // they'd outlive the connection and shadow the next device.
+    if (this.remote) return;
+    _sharedUi.persistentStorage.setItem(_sharedUi.devToolsStorageKeys.network.saved(), JSON.stringify(this.records)).catch(() => {
+      // Silently fail — records remain in memory for this session.
+    });
+  }
+  commit(next) {
+    this.dirty = true;
+    // The budget is applied at COMMIT, not at persist, so what the UI shows is
+    // exactly what survives a reload — no silently-vanishing bodies.
+    this.records = applyBodyBudget(next);
+    this.rebuild();
+    this.emit();
+    this.persist();
+  }
+
+  /** Rebuild the derived view once per mutation so renders get stable refs. */
+  rebuild() {
+    const pinnedRecords = [];
+    const savedRecords = [];
+    const pinnedLiveIds = new Set();
+    const savedLiveIds = new Set();
+    const tracked = new Set();
+    for (const record of this.records) {
+      if (record.pinned) pinnedRecords.push(record);
+      if (record.saved) savedRecords.push(record);
+      if (!this.sessionMatches(record) || !record.liveId) continue;
+      tracked.add(record.liveId);
+      if (record.pinned) pinnedLiveIds.add(record.liveId);
+      if (record.saved) savedLiveIds.add(record.liveId);
+    }
+    this.trackedLiveIds = tracked;
+    this.state = {
+      records: this.records,
+      pinnedEvents: pinnedRecords.map(record => record.event),
+      savedRecords,
+      pinnedLiveIds,
+      savedLiveIds
+    };
+  }
+  emit() {
+    this.listeners.forEach(listener => listener());
+  }
+}
+
+/**
+ * Singleton — one instance per JS runtime, shared by the mobile modal, the
+ * desktop inline port and the sync adapter.
+ */
+const networkSavedStore = exports.networkSavedStore = new NetworkSavedStore();

package/lib/commonjs/network/utils/withPinnedFirst.js

@@ -0,0 +1,32 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.splitPinned = splitPinned;
+/**
+ * Split a filtered event list into its PINNED section and the rest.
+ *
+ * Lives as a pure function because there are TWO list implementations — the
+ * mobile modal's `NetworkListScreen` and the desktop dashboard's hand-mirrored
+ * `NetworkInline` — and pin ordering silently diverging between them is
+ * exactly the drift `buoy.tools.json` exists to prevent.
+ *
+ * Pins are deliberately NOT filtered: they come straight from the saved store,
+ * so a pinned request stays visible no matter what the search box or the
+ * status chips say. The only thing the filtered list contributes is the
+ * dedupe — a pinned request that is still live must not render twice.
+ */
+
+const EMPTY = [];
+function splitPinned(filtered, pinnedEvents, /** Live IDs pinned in THIS session — from `networkSavedStore.getState()`. */
+pinnedLiveIds) {
+  if (pinnedEvents.length === 0) return {
+    pinned: EMPTY,
+    rest: filtered
+  };
+  return {
+    pinned: pinnedEvents,
+    rest: pinnedLiveIds.size === 0 ? filtered : filtered.filter(event => !pinnedLiveIds.has(event.id))
+  };
+}

package/lib/module/index.js

@@ -18,9 +18,13 @@ export { networkToolPreset, createNetworkTool } from "./preset";
 // =============================================================================
 // COMPONENTS (For custom UI implementations)
 // =============================================================================
-export { NetworkModal } from "./network/components/NetworkModal";
+// `NetworkToolView` is the same tool rendered inline (header bar + body)
+// instead of inside a JsModal — for hosts that show tools in a panel.
+export { NetworkModal, NetworkToolView } from "./network/components/NetworkModal";
 export { NetworkEventDetailView } from "./network/components/NetworkEventDetailView";
 export { NetworkEventItemCompact } from "./network/components/NetworkEventItemCompact";
+export { NetworkSavedScreen } from "./network/components/NetworkSavedScreen";
+export { NetworkSavedButton, NetworkDetailPinActions } from "./network/components/NetworkHeaderLive";
 
 // =============================================================================
 // HOOKS (For consuming network data in custom components)
@@ -30,7 +34,13 @@ export { useNetworkEvents } from "./network/hooks/useNetworkEvents";
 // list and the header counters subscribe independently so a host UI never
 // re-renders wholesale per network event.
 export { useNetworkEventList } from "./network/hooks/useNetworkEventList";
+export { useLiveNetworkEvent } from "./network/hooks/useLiveNetworkEvent";
 export { useNetworkBadgeCounts } from "./network/hooks/useNetworkBadgeCounts";
+// Pinned/saved requests. `splitPinned` is the shared pin-ordering util — the
+// desktop dashboard's hand-mirrored list calls it too, so the two list
+// implementations can't disagree about where a pin goes.
+export { useNetworkSaved } from "./network/hooks/useNetworkSaved";
+export { splitPinned } from "./network/utils/withPinnedFirst";
 export { TickProvider, useTickEveryMinute } from "./network/hooks/useTickEveryMinute";
 
 // =============================================================================
@@ -63,5 +73,11 @@ export { NetworkBodyResolverProvider } from "./network/sync/networkBodyResolver"
 // =============================================================================
 /** @internal */
 export { networkEventStore } from "./network/utils/networkEventStore";
+/**
+ * @internal — the desktop dashboard puts this in remote-mirror mode so pins
+ * made there are forwarded to the device instead of stored locally.
+ */
+export { networkSavedStore, flagsForEventId, FREE_TIER_SAVED_LIMIT, MAX_PINNED, MAX_SAVED } from "./network/utils/networkSavedStore";
+export { generateCurl } from "./network/utils/generateCurl";
 /** @internal */
 export { networkListener, addNetworkListener, removeAllNetworkListeners } from "./network/utils/networkListener";