@avasapp/agent-bridge 0.5.0 → 0.6.0

package/dist/network/index.cjs

@@ -48,18 +48,23 @@ var signalMocksRemoved = (ids) => {
 // src/network/api.ts
 var escape = (s) => s.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
 var ROUTE = /^(?:([A-Za-z]+)\s+)?(\/\S*)$/;
-function compileRoute(baseUrl, route) {
+function compileRoute(baseUrl, route, { loose = false } = {}) {
   const parsed = ROUTE.exec(route.trim());
   if (!parsed)
     throw new Error(`Bad route "${route}": use "METHOD /path" or "/path"`);
-  const [, method, path] = parsed;
+  const [, method, rawPath] = parsed;
+  const path = loose && rawPath.length > 1 ? rawPath.replace(/\/+$/, "") : rawPath;
   const names = [];
-  const pattern = path.split(/(:[A-Za-z_][A-Za-z0-9_]*|\*)/).map((part) => {
+  const pattern = (path === "/" && loose ? "" : path).split(loose ? /(\/:[A-Za-z_][A-Za-z0-9_]*(?=\/|$)|\*)/ : /(:[A-Za-z_][A-Za-z0-9_]*|\*)/).map((part) => {
     if (part === "*") {
       names.push("*");
       return "([^?#]*)";
     }
-    if (part.startsWith(":")) {
+    if (loose && part.startsWith("/:")) {
+      names.push(part.slice(2));
+      return "/([^/?#]+)";
+    }
+    if (!loose && part.startsWith(":")) {
       names.push(part.slice(1));
       return "([^/?#]+)";
     }
@@ -68,7 +73,7 @@ function compileRoute(baseUrl, route) {
   const base = baseUrl ? escape(baseUrl.replace(/\/+$/, "")) : "(?:[a-z][a-z0-9+.-]*://[^/?#]*)?";
   return {
     method: method?.toUpperCase(),
-    regex: new RegExp(`^${base}${pattern}(?:[?#].*)?$`, "i"),
+    regex: new RegExp(`^${base}${pattern}${loose ? "/?" : ""}(?:[?#].*)?$`, "i"),
     names
   };
 }
@@ -147,6 +152,154 @@ function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+// src/network/headers.ts
+var SECRET = /auth|cookie|token|secret|session|password|passwd|signature|api-?key|credential|jwt/i;
+var lower = (headers) => Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]));
+function keepHeaders(headers) {
+  return headers && Object.keys(headers).length ? lower(headers) : void 0;
+}
+function redactHeaders(headers) {
+  const out = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (!SECRET.test(name)) {
+      out[name] = value;
+      continue;
+    }
+    const scheme = /^authorization$|^proxy-authorization$/i.test(name) ? /^[A-Za-z]+(?= \S)/.exec(value)?.[0] : void 0;
+    const keep = scheme ? scheme.length + 1 : Math.min(4, Math.floor(value.length / 4));
+    out[name] = `${value.slice(0, keep)}\u2026 (+${value.length - keep} chars)`;
+  }
+  return out;
+}
+function parseHeaderBlock(block) {
+  const out = {};
+  for (const line of (block ?? "").split(/\r?\n/)) {
+    const at = line.indexOf(":");
+    if (at <= 0) continue;
+    const name = line.slice(0, at).trim().toLowerCase();
+    const value = line.slice(at + 1).trim();
+    out[name] = name in out ? `${out[name]}, ${value}` : value;
+  }
+  return out;
+}
+
+// src/network/match.ts
+var KEYS = ["url", "path", "method", "body", "graphql"];
+var NEED = "A mock needs a match: a URL substring or { url?, path?, method?, body?, graphql? } with one of url, path, body or graphql";
+var own = (o, key) => Object.prototype.hasOwnProperty.call(o, key);
+function subset(spec, actual) {
+  if (spec === null || typeof spec !== "object") return spec === actual;
+  if (Array.isArray(spec))
+    return Array.isArray(actual) && actual.length === spec.length && spec.every((item, i) => subset(item, actual[i]));
+  if (actual === null || typeof actual !== "object" || Array.isArray(actual)) return false;
+  return Object.entries(spec).every(
+    ([key, value]) => own(actual, key) && subset(value, actual[key])
+  );
+}
+function operationName(probe) {
+  const json = probe.json();
+  if (json && typeof json === "object" && !Array.isArray(json)) {
+    const name = json.operationName;
+    if (typeof name === "string") return name;
+  }
+  return queryOf(probe.url).operationName;
+}
+function urlTest(url) {
+  if (typeof url === "string")
+    return { test: (u) => u.includes(url), shown: `URL containing ${JSON.stringify(url)}`, substring: url };
+  const isRegex = url instanceof RegExp;
+  if (!isRegex && !(url && typeof url === "object" && typeof url.regex === "string"))
+    throw new Error("url must be a string, or { regex, flags? }");
+  const regex = isRegex ? url : new RegExp(url.regex, url.flags);
+  return {
+    test: (u) => {
+      regex.lastIndex = 0;
+      return regex.test(u);
+    },
+    shown: `URL matching ${String(regex)}`
+  };
+}
+function compileMatch(match) {
+  const spec = typeof match === "string" ? { url: match } : match;
+  if (!spec || typeof spec !== "object" || Array.isArray(spec) || spec instanceof RegExp) throw new Error(NEED);
+  const unknown = Object.keys(spec).filter((k) => !KEYS.includes(k));
+  if (unknown.length)
+    throw new Error(`Unknown match key ${unknown.map((k) => `"${k}"`).join(", ")}; the keys are ${KEYS.join(", ")}`);
+  if (["url", "path", "body", "graphql"].every((k) => spec[k] === void 0)) throw new Error(NEED);
+  const parts = [];
+  const tests = [];
+  let method;
+  if (spec.method !== void 0) {
+    if (typeof spec.method !== "string") throw new Error('method must be a string such as "POST"');
+    method = spec.method.toUpperCase();
+  }
+  parts.push(method ?? "any method");
+  let substring;
+  if (spec.url !== void 0) {
+    const u = urlTest(spec.url);
+    substring = u.substring;
+    tests.push((_m, url) => u.test(url));
+    parts.push(u.shown);
+  }
+  if (spec.path !== void 0) {
+    const path = spec.path;
+    if (typeof path !== "string" || !path.startsWith("/"))
+      throw new Error('path is just the path, starting with "/", e.g. "/orders/:id"; use url to pin a host');
+    if (/[?#]/.test(path)) throw new Error("path has no query or hash; the query is ignored, use url to match it");
+    if (/\s/.test(path)) throw new Error("path has no spaces; write a space as %20");
+    const route = compileRoute("", path, { loose: true });
+    const decoded = (u) => {
+      try {
+        return decodeURI(u);
+      } catch {
+        return u;
+      }
+    };
+    tests.push((_m, url) => route.regex.test(url) || route.regex.test(decoded(url)));
+    parts.push(`path ${path} (whole path, any host)`);
+  }
+  const probeTests = [];
+  if (spec.body !== void 0) {
+    const body = spec.body;
+    const frozen = body && typeof body === "object" ? JSON.parse(JSON.stringify(body)) : void 0;
+    if (!frozen || typeof frozen !== "object" || !Array.isArray(frozen) && !Object.keys(frozen).length)
+      throw new Error("body must be a non-empty JSON object or an array to look for in the request body");
+    probeTests.push((p) => {
+      const json = p.json();
+      return json !== void 0 && subset(frozen, json);
+    });
+    parts.push(`JSON body containing ${truncateBody(JSON.stringify(frozen))}`);
+  }
+  if (spec.graphql !== void 0) {
+    const name = spec.graphql;
+    if (typeof name !== "string" || !name) throw new Error('graphql must be an operation name such as "GetUser"');
+    probeTests.push((p) => operationName(p) === name);
+    parts.push(`GraphQL operation ${JSON.stringify(name)}`);
+  }
+  return {
+    test: (m, u) => (!method || method === m) && tests.every((t) => t(m, u)),
+    needsBody: probeTests.length > 0,
+    testBody: (p) => {
+      try {
+        return probeTests.every((t) => t(p));
+      } catch {
+        return false;
+      }
+    },
+    matches: parts.join(", "),
+    key: JSON.stringify([
+      method,
+      spec.url instanceof RegExp ? String(spec.url) : spec.url,
+      spec.path,
+      spec.body,
+      spec.graphql
+    ]),
+    substring,
+    plain: substring !== void 0 && spec.path === void 0 && spec.body === void 0 && spec.graphql === void 0,
+    method
+  };
+}
+
 // src/network/state.ts
 var LOG_SIZE = 100;
 var KEY2 = /* @__PURE__ */ Symbol.for("@avasapp/agent-bridge/network");
@@ -156,6 +309,7 @@ function networkState() {
     installed: false,
     log: [],
     nextLogId: 1,
+    logSize: LOG_SIZE,
     mocks: [],
     nextSeq: 1,
     insideFetch: 0,
@@ -251,21 +405,25 @@ function startEntry(state, fields) {
     pending: true
   };
   keepRequestBody(entry, fields.requestBody);
+  const requestHeaders = keepHeaders(fields.requestHeaders);
+  if (requestHeaders) fullOf(entry).requestHeaders = requestHeaders;
   state.log.push(entry);
   signalRequestStarted(entry.id);
-  if (state.log.length > LOG_SIZE)
-    state.log.splice(0, state.log.length - LOG_SIZE);
+  if (state.log.length > state.logSize)
+    state.log.splice(0, state.log.length - state.logSize);
   return entry;
 }
 function finishEntry(entry, fields) {
   entry.ms = Date.now() - entry.startedAt;
   delete entry.pending;
-  const { responseBody, contentType, ...rest } = fields;
+  const { responseBody, contentType, responseHeaders, ...rest } = fields;
+  const kept = keepHeaders(responseHeaders);
+  if (kept) fullOf(entry).responseHeaders = kept;
   for (const [key, value] of Object.entries(rest))
     if (value !== void 0) entry[key] = value;
   if (responseBody !== void 0) setResponseBody(entry, responseBody, contentType);
 }
-function publicEntry(entry, full = false) {
+function publicEntry(entry, full = false, headers) {
   const out = entry.pending ? { ...entry, ms: Date.now() - entry.startedAt } : { ...entry };
   if (full) {
     const { requestBody, responseBody } = FULL.get(entry) ?? {};
@@ -275,13 +433,34 @@ function publicEntry(entry, full = false) {
     const cutRequest = entry.requestBody !== void 0 && requestBody === void 0;
     if (cut || cutRequest) out.truncated = true;
   }
+  if (headers) {
+    const { requestHeaders, responseHeaders } = FULL.get(entry) ?? {};
+    const shown = (h) => h && (headers === "full" ? { ...h } : redactHeaders(h));
+    if (requestHeaders) out.requestHeaders = shown(requestHeaders);
+    if (responseHeaders) out.responseHeaders = shown(responseHeaders);
+  }
   return out;
 }
+function setRequestBody(entry, text) {
+  if (entry.requestBody === void 0) keepRequestBody(entry, text);
+}
+function requestBodyForMatch(entry) {
+  const whole = FULL.get(entry)?.requestBody;
+  if (whole !== void 0) return whole;
+  const preview = entry.requestBody;
+  if (preview === void 0) return void 0;
+  try {
+    JSON.parse(preview);
+    return preview;
+  } catch {
+    return void 0;
+  }
+}
 function fullResponse(entry) {
   const full = FULL.get(entry);
   return { state: full?.response ?? "none", body: full?.responseBody, contentType: full?.contentType };
 }
-function urlTest(url) {
+function urlTest2(url) {
   if (typeof url === "string") return (u) => u.includes(url);
   const regex = url instanceof RegExp ? url : new RegExp(url.regex, url.flags);
   return (u) => {
@@ -289,19 +468,12 @@ function urlTest(url) {
     return regex.test(u);
   };
 }
-function compileMatch(match) {
-  const spec = typeof match === "string" ? { url: match } : match;
-  if (!spec || spec.url === void 0)
-    throw new Error("A mock needs a match: a URL substring or { url, method? }");
-  const testUrl = urlTest(spec.url);
-  const method = spec.method?.toUpperCase();
-  return (m, u) => (!method || method === m) && testUrl(u);
-}
 function addMock(state, source, match, response, options = {}) {
   if (!response || typeof response !== "object" && typeof response !== "function")
     throw new Error("A mock needs a response: { status?, json?, body?, headers? }, { offline: true } or a handler");
   if (options.priority !== void 0 && !Number.isFinite(options.priority))
     throw new Error("priority must be a finite number");
+  const compiled = compileMatch(match);
   const seq = state.nextSeq++;
   const id = options.id ?? `${source}-${seq}`;
   removeMocks(state, (m) => m.id === id);
@@ -315,7 +487,7 @@ function addMock(state, source, match, response, options = {}) {
     priority: options.priority ?? 0,
     hits: 0,
     seq,
-    test: compileMatch(match)
+    ...(({ key, ...rest }) => ({ ...rest, matchKey: key }))(compiled)
   };
   state.mocks.push(mock2);
   return mock2;
@@ -326,28 +498,27 @@ function removeMocks(state, which) {
   return before - state.mocks.length;
 }
 var mockOrder = (a, b) => Number(b.source === "agent") - Number(a.source === "agent") || b.priority - a.priority || b.seq - a.seq;
-var substringMatch = (match) => {
-  const spec = typeof match === "string" ? { url: match } : match;
-  return typeof spec.url === "string" ? { url: spec.url, method: spec.method?.toUpperCase() } : null;
-};
 function shadowedMocks(state, added) {
-  const next = substringMatch(added.match);
-  if (!next || typeof added.response === "function") return [];
+  if (typeof added.response === "function") return [];
   return state.mocks.filter((old) => {
-    if (old === added || old.source !== "agent" || mockOrder(added, old) >= 0)
+    if (old === added || old.source !== "agent" || mockOrder(added, old) >= 0 || added.times !== void 0)
       return false;
-    const prev = substringMatch(old.match);
-    return !!prev && prev.url.includes(next.url) && (!next.method || next.method === prev.method);
+    if (old.matchKey === added.matchKey) return true;
+    return added.plain && old.substring !== void 0 && old.substring.includes(added.substring) && (!added.method || added.method === old.method);
   });
 }
-function matchingMocks(state, method, url) {
-  return state.mocks.filter((m) => m.test(method, url)).sort(mockOrder);
+function matchingMocks(state, method, url, body) {
+  if (state.deviceOffline) return [];
+  const found = state.mocks.filter((m) => m.test(method, url));
+  const probe = body && found.some((m) => m.needsBody) ? mockRequest(method, url, {}, body.text) : null;
+  return found.filter((m) => !m.needsBody || !probe || m.testBody(probe)).sort(mockOrder);
 }
-async function answer(state, candidates, request) {
+async function answer(state, candidates, request, bodyKnown = true) {
   for (const mock2 of candidates) {
+    if (mock2.needsBody && !bodyKnown && !mock2.testBody(await request())) continue;
     if (!state.mocks.includes(mock2)) continue;
     const response = typeof mock2.response === "function" ? await mock2.response(await request()) : mock2.response;
-    if (!response) continue;
+    if (!response || !state.mocks.includes(mock2)) continue;
     mock2.hits += 1;
     if (mock2.times !== void 0 && mock2.hits >= mock2.times)
       removeMocks(state, (m) => m === mock2);
@@ -356,17 +527,21 @@ async function answer(state, candidates, request) {
   return null;
 }
 function mockRequest(method, url, headers, body) {
+  let parsed;
   return {
     method,
     url,
     headers,
     body,
     json: () => {
-      try {
-        return body === void 0 ? void 0 : JSON.parse(body);
-      } catch {
-        return void 0;
+      if (!parsed) {
+        try {
+          parsed = { value: body === void 0 ? void 0 : JSON.parse(body) };
+        } catch {
+          parsed = { value: void 0 };
+        }
       }
+      return parsed.value;
     }
   };
 }
@@ -387,7 +562,7 @@ function strictRule(options = {}) {
   if (!Array.isArray(allow))
     throw new Error("allow must be a list of URL substrings or regexes");
   return {
-    allow: allow.map((rule) => urlTest(rule)),
+    allow: allow.map((rule) => urlTest2(rule)),
     allowShown: allow.map(
       (rule) => typeof rule === "string" ? rule : String(rule instanceof RegExp ? rule : new RegExp(rule.regex, rule.flags))
     ),
@@ -400,15 +575,19 @@ function strictRules(state) {
   return state.strictAgent ? [state.strictAgent, ...state.strictApp] : state.strictApp;
 }
 var BLOCKED_HEADER = "x-agent-bridge";
-function blockedResponse(state, method, url) {
+function blockedResponse(state, method, url, body) {
+  if (state.deviceOffline) return { offline: true };
   const rules = strictRules(state);
   if (!rules.length || rules.some((r) => r.allow.some((test) => test(url))))
     return null;
-  const key = `${method} ${url}`;
+  const operation = operationName(mockRequest(method, url, {}, body));
+  const key = operation ? `${method} ${url} (${operation})` : `${method} ${url}`;
+  const probe = mockRequest(method, url, {}, body);
+  const near = state.mocks.filter((m) => m.needsBody && m.test(method, url) && !m.testBody(probe)).map((m) => m.id);
   const seen = state.blocked.get(key);
   if (seen) seen.count += 1;
-  else state.blocked.set(key, { method, url, count: 1 });
-  const error = `agent-bridge strict network: no mock for ${key}`;
+  else state.blocked.set(key, { method, url, count: 1, ...operation && { operation } });
+  const error = `agent-bridge strict network: no mock for ${key}${near.length ? ` (${near.join(", ")} matched the URL but not the body)` : ""}`;
   console.error(`${error}. Mock it, or allow it in strict mode.`);
   if (rules[0].offline) return { offline: true };
   return {
@@ -479,11 +658,12 @@ function patchFetch(state) {
     const url = typeof input === "string" ? input : req.url ?? String(input);
     if (isSkipped(state, url)) return callOriginal(input, init);
     const method = String(init?.method ?? req.method ?? "GET").toUpperCase();
-    const requestBody = bodyText(init?.body);
+    let requestBody = bodyText(init?.body);
     const entry = startEntry(state, {
       method,
       url,
-      requestBody
+      requestBody,
+      requestHeaders: headersRecord(init?.headers ?? req.headers)
     });
     const real = () => {
       let promise;
@@ -495,7 +675,7 @@ function patchFetch(state) {
       }
       return promise.then(
         (res) => {
-          finishEntry(entry, { status: res.status });
+          finishEntry(entry, { status: res.status, responseHeaders: headersRecord(res.headers) });
           const type = res.headers?.get?.("content-type") ?? void 0;
           if (isTextual(type) && typeof res.clone === "function") {
             markResponse(entry, "pending");
@@ -510,23 +690,27 @@ function patchFetch(state) {
       );
     };
     const passOn = () => {
-      const blocked = blockedResponse(state, method, url);
+      const blocked = blockedResponse(state, method, url, requestBody);
       if (!blocked) return real();
-      entry.blocked = true;
+      if (!state.deviceOffline) entry.blocked = true;
       if (isOffline(blocked)) {
-        finishEntry(entry, { error: `${OFFLINE_MESSAGE} (strict network)` });
+        finishEntry(entry, { error: `${OFFLINE_MESSAGE} (${state.deviceOffline ? "device offline" : "strict network"})` });
         return Promise.reject(new TypeError(OFFLINE_MESSAGE));
       }
       const { status, text, headers } = responseParts(blocked);
-      finishEntry(entry, { status, responseBody: text, contentType: contentTypeOf(headers) });
+      finishEntry(entry, { status, responseBody: text, contentType: contentTypeOf(headers), responseHeaders: headers });
       return Promise.resolve(mockedResponse(blocked));
     };
-    const candidates = matchingMocks(state, method, url);
+    const bodyKnown = init?.body !== void 0 || !req.clone || method === "GET" || method === "HEAD" || !isTextual(headersRecord(init?.headers ?? req.headers)["content-type"]);
+    const candidates = matchingMocks(state, method, url, bodyKnown ? { text: requestBody } : void 0);
     if (!candidates.length) return passOn();
-    const request = async () => {
+    let built;
+    const request = () => built ?? (built = (async () => {
       let body = requestBody;
-      if (body === void 0 && init?.body === void 0 && req.clone) {
-        body = await req.clone().text().catch(() => void 0);
+      if (body === void 0 && !bodyKnown) {
+        body = await Promise.resolve().then(() => req.clone().text()).catch(() => void 0);
+        setRequestBody(entry, body);
+        requestBody = body;
       }
       return mockRequest(
         method,
@@ -534,8 +718,8 @@ function patchFetch(state) {
         headersRecord(init?.headers ?? req.headers),
         body || void 0
       );
-    };
-    const answered = answer(state, candidates, request).catch((error) => {
+    })());
+    const answered = answer(state, candidates, request, bodyKnown).catch((error) => {
       entry.mocked = true;
       finishEntry(entry, { error: errorMessage(error) });
       throw error;
@@ -554,7 +738,7 @@ function patchFetch(state) {
         throw new TypeError(OFFLINE_MESSAGE);
       }
       const { status, text, headers } = responseParts(hit.response);
-      finishEntry(entry, { status, responseBody: text, contentType: contentTypeOf(headers) });
+      finishEntry(entry, { status, responseBody: text, contentType: contentTypeOf(headers), responseHeaders: headers });
       return mockedResponse(hit.response);
     });
   };
@@ -586,7 +770,8 @@ function track(xhr, entry) {
       status: error ? void 0 : xhr.status,
       error,
       responseBody: text,
-      contentType: xhr.getResponseHeader?.("content-type") ?? void 0
+      contentType: xhr.getResponseHeader?.("content-type") ?? void 0,
+      responseHeaders: error ? void 0 : parseHeaderBlock(xhr.getAllResponseHeaders?.())
     });
     if (!error && text === void 0) markResponse(entry, "none");
   });
@@ -615,7 +800,7 @@ function respond(xhr, mocked, url) {
     for (const [key, value] of Object.entries(values))
       Object.defineProperty(xhr, key, { value, configurable: true });
   };
-  const lower = Object.fromEntries(
+  const lower2 = Object.fromEntries(
     Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v])
   );
   let response = text;
@@ -633,9 +818,9 @@ function respond(xhr, mocked, url) {
     responseURL: url,
     responseText: offline ? "" : text,
     response: offline ? "" : response,
-    getAllResponseHeaders: () => offline ? "" : Object.entries(lower).map(([k, v]) => `${k}: ${v}\r
+    getAllResponseHeaders: () => offline ? "" : Object.entries(lower2).map(([k, v]) => `${k}: ${v}\r
 `).join(""),
-    getResponseHeader: (name) => lower[name.toLowerCase()] ?? null
+    getResponseHeader: (name) => lower2[name.toLowerCase()] ?? null
   });
   fire(xhr, "readystatechange");
   fire(xhr, offline ? "error" : "load");
@@ -670,30 +855,36 @@ function patchXhr(state) {
     const meta = this[META];
     if (!meta || meta.internal || isSkipped(state, meta.url))
       return send.call(this, body);
+    meta.aborted = false;
     const { method, url } = meta;
     const text = bodyText(body);
     const entry = startEntry(state, {
       method,
       url,
-      requestBody: text
+      requestBody: text,
+      requestHeaders: meta.headers
     });
     const passOn = () => {
-      const blocked = blockedResponse(state, method, url);
+      if (meta.aborted) {
+        finishEntry(entry, { error: "aborted" });
+        return;
+      }
+      const blocked = blockedResponse(state, method, url, text);
       if (!blocked) {
         track(this, entry);
         return send.call(this, body);
       }
       const { status, text: out, headers } = responseParts(blocked);
-      entry.blocked = true;
+      if (!state.deviceOffline) entry.blocked = true;
       finishEntry(
         entry,
-        isOffline(blocked) ? { error: `${OFFLINE_MESSAGE} (strict network)` } : { status, responseBody: out, contentType: contentTypeOf(headers) }
+        isOffline(blocked) ? { error: `${OFFLINE_MESSAGE} (${state.deviceOffline ? "device offline" : "strict network"})` } : { status, responseBody: out, contentType: contentTypeOf(headers), responseHeaders: headers }
       );
       void Promise.resolve().then(() => {
         if (!meta.aborted) respond(this, blocked, url);
       });
     };
-    const candidates = matchingMocks(state, method, url);
+    const candidates = matchingMocks(state, method, url, { text });
     if (!candidates.length) return passOn();
     const request = async () => mockRequest(method, url, meta.headers, text);
     answer(state, candidates, request).then(
@@ -710,7 +901,7 @@ function patchXhr(state) {
         const { status, text: out, headers } = responseParts(hit.response);
         finishEntry(
           entry,
-          offline ? { error: `${OFFLINE_MESSAGE} (mocked offline)` } : { status, responseBody: out, contentType: contentTypeOf(headers) }
+          offline ? { error: `${OFFLINE_MESSAGE} (mocked offline)` } : { status, responseBody: out, contentType: contentTypeOf(headers), responseHeaders: headers }
         );
         respond(this, hit.response, url);
       },
@@ -799,6 +990,7 @@ var describeMock = (m, full) => ({
   id: m.id,
   source: m.source,
   match: describeMatch(m.match),
+  matches: m.matches,
   ...describeResponse(m.response, full),
   times: m.times,
   hits: m.hits,
@@ -809,6 +1001,11 @@ function networkTools(options = {}) {
   installNetwork();
   const state = networkState();
   if (options.skip) state.skip = options.skip;
+  if (options.logSize !== void 0) {
+    if (!Number.isInteger(options.logSize) || options.logSize < 1)
+      throw new Error("logSize must be a whole number of at least 1");
+    state.logSize = options.logSize;
+  }
   const isAgent = (m) => m.source === "agent";
   const logged = (id) => {
     const entry = state.log.find((e) => e.id === id);
@@ -818,7 +1015,7 @@ function networkTools(options = {}) {
   const addAgentMock = (match, response, { times, delayMs, priority }) => {
     const added = addMock(state, "agent", match, response, { times, delayMs, priority });
     const shadows = shadowedMocks(state, added).map((m) => m.id);
-    return shadows.length ? { id: added.id, shadows } : { id: added.id };
+    return shadows.length ? { id: added.id, matches: added.matches, shadows } : { id: added.id, matches: added.matches };
   };
   return {
     "net.log": {
@@ -835,19 +1032,55 @@ function networkTools(options = {}) {
       }
     },
     "net.entry": {
-      description: "One logged request by id, with its request and response bodies whole (not cut at ~2 KB). Ids come from net.log.",
-      run: (id) => publicEntry(logged(id), true)
+      description: "One logged request by id, with its request and response bodies whole (not cut at ~2 KB) and its request and response headers (lower-case names). Authorization, Cookie, Set-Cookie, Proxy-Authorization and X-Api-Key values are cut to a short prefix; { full: true } as the second argument shows them whole. Ids come from net.log.",
+      run: (id, options2 = {}) => publicEntry(logged(id), true, options2?.full ? "full" : "cut")
     },
     "net.mock": {
-      description: 'Answer matching requests with a canned response until unmocked. match: "/path" or { url: string | { regex }, method? }. response: { status?, json?, body?, headers? } or { offline: true }. options: { times?, delayMs?, priority? }. The newest mock is tried first, so a later broad mock shadows an earlier specific one; give the specific one a higher priority (default 0, ties newest first; negative makes a fallback); agent mocks still come before the app mocks. The result lists `shadows` when the new mock will be tried before an agent mock it also matches.',
+      description: 'Answer matching requests with a canned response until unmocked. match: "/path" (any URL containing it) or { url?: string | { regex }, path?: "/orders/:id" (the whole path on any host, query ignored; :name is one segment, * the rest), method?, body?: JSON subset the JSON request body must contain (objects by key, arrays by length and position), graphql?: "OperationName" (operationName in the JSON body or ?operationName=) }; every key given must match and one of url, path, body, graphql is required. The result has `matches`, which says in words what the mock matches. response: { status?, json?, body?, headers? } or { offline: true }. options: { times?, delayMs?, priority? }. The newest mock is tried first, so a later broad mock shadows an earlier specific one; give the specific one a higher priority (default 0, ties newest first; negative makes a fallback); agent mocks still come before the app mocks. The result lists `shadows` when the new mock will be tried before an agent mock it also matches.',
       run: (match, response, mockOptions = {}) => {
         if (typeof response !== "object" || response === null)
           throw new Error("response must be an object, e.g. { status: 500 }");
         return addAgentMock(match, response, mockOptions);
       }
     },
+    "net.waitFor": {
+      description: 'Wait until a request matching `match` (as net.mock: "/path" or { url?, path?, method?, body?, graphql? }) has finished, and return its entry like net.entry. Finished requests already in the log count, so pass { sinceId } (a log id from net.log) to ignore older ones. [match, { timeoutMs?: 5000, status?, sinceId? }]. A request that failed, was mocked or blocked still counts; status narrows it. Body and graphql checks need the request body: JSON up to 1 MB, and a Request object\'s body only when a mock read it. Times out with an error saying what it looked at.',
+      run: (match, waitOptions = {}) => {
+        const compiled = compileMatch(match);
+        const { timeoutMs = 5e3, status, sinceId } = waitOptions ?? {};
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 12e4)
+          throw new Error("timeoutMs must be between 1 and 120000");
+        const deadline = Date.now() + timeoutMs;
+        let unreadable = 0;
+        const find = () => {
+          unreadable = 0;
+          for (const e of state.log) {
+            if (e.pending || fullResponse(e).state === "pending") continue;
+            if (sinceId !== void 0 && e.id <= sinceId) continue;
+            if (status !== void 0 && e.status !== status) continue;
+            if (!compiled.test(e.method, e.url)) continue;
+            if (!compiled.needsBody) return e;
+            const body = requestBodyForMatch(e);
+            if (body === void 0 && e.requestBody !== void 0) unreadable += 1;
+            else if (compiled.testBody(mockRequest(e.method, e.url, {}, body))) return e;
+          }
+          return void 0;
+        };
+        return (async () => {
+          for (; ; ) {
+            const found = find();
+            if (found) return publicEntry(found, true, "cut");
+            if (Date.now() >= deadline) break;
+            await new Promise((resolve) => setTimeout(resolve, 25));
+          }
+          throw new Error(
+            `Timed out after ${timeoutMs} ms waiting for a finished request matching ${compiled.matches}${status !== void 0 ? ` with status ${status}` : ""}${unreadable ? ` (${unreadable} matched the URL but their body was not kept)` : ""}; ${state.log.length} requests are logged`
+          );
+        })();
+      }
+    },
     "net.mockFromLog": {
-      description: "Mock the same method and URL as a logged request (id from net.log) with its status and whole response body, optionally changed by patch: JSON objects merge deeply, other values replace. [id, patch?, options?] options as net.mock. Returns { id, match, response }.",
+      description: "Mock the same method and URL as a logged request (id from net.log) with its status and whole response body, optionally changed by patch: JSON objects merge deeply, other values replace. [id, patch?, options?] options as net.mock. Returns { id, matches, match, response }; on a GraphQL request the mock only matches that operationName; `warning` appears when a POST body was not kept and the mock may answer other operations too.",
       run: (id, patch, mockOptions = {}) => {
         const entry = logged(id);
         if (entry.status === void 0)
@@ -876,12 +1109,26 @@ function networkTools(options = {}) {
           response.body = body;
           if (contentType) response.headers = { "content-type": contentType };
         }
-        const match = { url: { regex: `^${escapeRegex(entry.url)}$` }, method: entry.method };
-        return { ...addAgentMock(match, response, mockOptions), match: { url: entry.url, method: entry.method }, response };
+        const sent = requestBodyForMatch(entry);
+        let graphql = operationName(mockRequest(entry.method, entry.url, {}, sent));
+        if (!graphql && sent === void 0 && entry.requestBody !== void 0)
+          graphql = /"operationName":"((?:[^"\\]|\\.)*)"/.exec(entry.requestBody)?.[1];
+        const unread = !graphql && !["GET", "HEAD"].includes(entry.method) && sent === void 0 ? "This request's body was not kept, so the mock matches every request to that URL, whatever its GraphQL operation. Check it, or unmock and use net.mock with graphql." : void 0;
+        const match = {
+          url: { regex: `^${escapeRegex(entry.url)}$` },
+          method: entry.method,
+          ...graphql && { graphql }
+        };
+        return {
+          ...addAgentMock(match, response, mockOptions),
+          match: { url: entry.url, method: entry.method, ...graphql && { graphql } },
+          response,
+          ...unread && { warning: unread }
+        };
       }
     },
     "net.mocks": {
-      description: 'Active mocks, agent and app, in the order they are tried. Response json and body over ~2 KB are cut like net.log (json shown as its cut JSON text, "\u2026 (+N chars)"), with truncated: true; { full: true } returns them whole.',
+      description: 'Active mocks, agent and app, in the order they are tried, each with `matches` in words. Response json and body over ~2 KB are cut like net.log (json shown as its cut JSON text, "\u2026 (+N chars)"), with truncated: true; { full: true } returns them whole.',
       run: (options2 = {}) => [...state.mocks].sort(mockOrder).map((m) => describeMock(m, options2.full))
     },
     "net.unmock": {