@avivbenhamo/polly-kit 0.6.0 → 0.8.0

package/README.md

@@ -244,6 +244,24 @@ import {mountPollyStudio} from '@avivbenhamo/polly-kit/studio/browser';
 mountPollyStudio(document.getElementById('polly')!);
 ```
 
+### Importing a HAR
+
+The editor takes a HAR downloaded from the
+[swagger-recorder](../swagger-recorder/README.md) extension — the plain flavour, not the
+zip — and turns it into a recording. Give it the recording name your app's Polly config
+uses; it creates the recording if there is none, and merges into it if there is. It
+reports what it did: **added 3, replaced 2, skipped 1**.
+
+**Where a request is in both, the imported one wins.** That is usually what you want —
+you re-recorded because the response changed — but it means an import can overwrite a
+response you edited here. The `replaced` count is there so that is never silent.
+
+**Only HARs from that extension can be imported**, and the reason is not caution. Polly
+finds a recorded response by an `_id` that hashes the request body, and a multipart body
+is not in a HAR at all — an upload records with no `postData`. So no importer can derive
+an id; it can only read one that was written at capture time, and that extension is the
+only thing that writes one.
+
 ## API
 
 | Export | From | What |
@@ -259,6 +277,8 @@ mountPollyStudio(document.getElementById('polly')!);
 | `parseHar` / `findEntry` | `./studio` | Reading a HAR, with the Polly-specific quirks handled. |
 | `applyResponsePatch` / `deleteEntry` | `./studio` | Editing an entry, returning a typed `EditError` rather than throwing. |
 | `mountPollyStudio(root)` | `./studio/browser` | The editor with no server at all, against Polly's `persister-local-storage`. |
+| `mergeEntries` / `rejectImport` | `./studio` | The import rules, as pure functions. |
+| `guidForRecording(name)` | `./studio` | The directory Polly looks a recording up in. |
 
 `startPolly` options beyond the policy config: `mode` (required), `alwaysPassthrough`,
 `apiNamespace`, `saveDebounceMs`; on `./node`, `recordingsDir` and `logLevel` instead of

package/dist/studio/client.bundle.js

@@ -47,6 +47,15 @@ function renderRecordingList(recordings) {
   }).join("");
   return `<ul class="recordings">${rows}</ul>`;
 }
+function renderImportResult(result) {
+  const verb = result.created ? "Created" : "Updated";
+  const counts = [`added ${result.added}`, `replaced ${result.replaced}`];
+  if (result.skipped.length > 0)
+    counts.push(`skipped ${result.skipped.length}`);
+  const skips = result.skipped.length === 0 ? "" : `<ul class="ps-import-skips">${result.skipped.map((skip) => `<li><code>${escapeHtml(skip.url)}</code> \u2014 ${escapeHtml(skip.reason)}</li>`).join("")}</ul>`;
+  const rejectWarning = result.pollyWillReject === null ? "" : `<p class="ps-notice warn">Polly will reject this: ${escapeHtml(result.pollyWillReject)}</p>`;
+  return `<p class="ps-import-result">${verb} <code>${escapeHtml(result.id)}</code> \u2014 ${escapeHtml(counts.join(", "))}.</p>${skips}${rejectWarning}`;
+}
 function unrenderable(err) {
   return escapeHtml(err instanceof Error ? err.message : String(err));
 }
@@ -102,8 +111,13 @@ function entryDetail(entry) {
 
     <div class="actions">
       <button name="save">Save response</button>
+      <button name="duplicate" title="Append a copy to this request's group, replayed the next time the same request is made">Duplicate for next call</button>
       <button name="delete" class="danger">Delete entry</button>
     </div>
+    <p class="note">Duplicating adds a second answer to the <em>same</em> request:
+    Polly replays <code>_order 0</code> on the first call, this copy on the second.
+    It cannot become a different request \u2014 the <code>_id</code> is a hash of the
+    request, and an edited URL under the old hash would match nothing.</p>
   </div>
 </section>`;
 }
@@ -122,6 +136,35 @@ function mountStudio(root, store) {
   const recordings = required(root, "#recordings");
   const entries = required(root, "#entries");
   const detail = required(root, "#detail");
+  const importForm = root.querySelector("#import");
+  const importReport = root.querySelector("#import-report");
+  importForm?.addEventListener("submit", (event) => {
+    event.preventDefault();
+    void runImport();
+  });
+  async function runImport() {
+    if (importForm === null || importReport === null)
+      return;
+    importReport.textContent = "";
+    try {
+      const name = importForm.querySelector("#import-name").value;
+      const file = importForm.querySelector("#import-file").files?.[0];
+      if (file === void 0) {
+        throw new Error("choose a .har file to import");
+      }
+      const har = JSON.parse(await file.text());
+      const result = await store.importHar(name, har);
+      importReport.innerHTML = renderImportResult(result);
+      try {
+        await refreshRecordings();
+        await openRecording(result.id);
+      } catch (err) {
+        report(err);
+      }
+    } catch (err) {
+      importReport.textContent = errorMessage(err);
+    }
+  }
   let currentId = null;
   let current = null;
   refreshRecordings().catch(report);
@@ -134,6 +177,11 @@ function mountStudio(root, store) {
     current = { har: read.har, etag: read.etag };
     entries.innerHTML = `<ul>${read.har.log.entries.map(renderEntryRow).join("")}</ul>`;
     detail.innerHTML = "";
+    const recordingName = read.har.log._recordingName;
+    const nameField = importForm === null ? null : importForm.querySelector("#import-name");
+    if (nameField !== null && typeof recordingName === "string" && recordingName !== "") {
+      nameField.value = recordingName;
+    }
   }
   function openEntry(entryId, order) {
     const entry = current?.har.log.entries.find((e) => String(e._id) === entryId && e._order === order);
@@ -156,6 +204,18 @@ function mountStudio(root, store) {
       report(err);
     }
   }
+  async function duplicate(entryId, order) {
+    if (currentId === null || current === null)
+      return;
+    try {
+      const { har } = await store.duplicateEntry(currentId, entryId, order, current.etag);
+      const added = har.log.entries.filter((entry) => String(entry._id) === entryId).length - 1;
+      await openRecording(currentId);
+      openEntry(entryId, added);
+    } catch (err) {
+      report(err);
+    }
+  }
   async function remove(entryId, order) {
     if (currentId === null || current === null)
       return;
@@ -166,8 +226,11 @@ function mountStudio(root, store) {
       report(err);
     }
   }
+  function errorMessage(err) {
+    return err instanceof StoreError && err.code === "conflict" ? "the recording changed underneath \u2014 reload and retry" : err instanceof Error ? err.message : String(err);
+  }
   function report(err) {
-    const message = err instanceof StoreError && err.code === "conflict" ? "the recording changed underneath \u2014 reload and retry" : err instanceof Error ? err.message : String(err);
+    const message = errorMessage(err);
     const banner = detail.ownerDocument.createElement("p");
     banner.className = "problem";
     banner.textContent = message;
@@ -196,6 +259,8 @@ function mountStudio(root, store) {
     const order = Number(section.dataset["order"]);
     if (target.getAttribute("name") === "save")
       void save(entryId, order);
+    if (target.getAttribute("name") === "duplicate")
+      void duplicate(entryId, order);
     if (target.getAttribute("name") === "delete")
       void remove(entryId, order);
   });
@@ -263,9 +328,24 @@ var HttpStore = class {
   async patchEntry(id, entryId, order, etag, patch) {
     return await this.json("PATCH", `/api/recordings/${encodeURIComponent(id)}/entries/${encodeURIComponent(entryId)}/${order}`, { etag, patch });
   }
+  /** POST to the entry being copied: this adds a member to its group. */
+  async duplicateEntry(id, entryId, order, etag) {
+    return await this.json("POST", `/api/recordings/${encodeURIComponent(id)}/entries/${encodeURIComponent(entryId)}/${order}?etag=${encodeURIComponent(etag)}`);
+  }
   async deleteEntry(id, entryId, order, etag) {
     return await this.json("DELETE", `/api/recordings/${encodeURIComponent(id)}/entries/${encodeURIComponent(entryId)}/${order}?etag=${encodeURIComponent(etag)}`);
   }
+  /**
+   * Not on the wire protocol: creation happens inside `/api/import`, server-side,
+   * the same way `write` happens inside PATCH. Declared so a caller holding a
+   * concrete HttpStore still type-checks against the interface's arity.
+   */
+  async create(id, har) {
+    throw new StoreError("forbidden", "the HTTP API creates recordings through import \u2014 use importHar");
+  }
+  async importHar(recordingName, incoming) {
+    return await this.json("POST", "/api/import", { recordingName, har: incoming });
+  }
   async json(method, path, body) {
     const res = await fetch(`${this.basePath}${path}`, {
       method,

package/dist/studio/edit.d.ts

@@ -29,6 +29,28 @@ export type EditResult = {
  * wrong rather than merely stale.
  */
 export declare function applyResponsePatch(har: Har, id: string, order: number, patch: ResponsePatch): EditResult;
+/**
+ * Copies an entry to the end of its own `_id` group — "the *next* time this same
+ * request happens, reply with this".
+ *
+ * `_order` is a position within a group of identical requests, not a label:
+ * Polly derives it at replay by counting how many earlier requests produced the
+ * same `_id`, starting at 0. So a recording with two members of a group answers
+ * the first call with `_order: 0` and the second with `_order: 1`. Duplicating
+ * appends a member, which is the only honest meaning "duplicate" can have here.
+ *
+ * What it deliberately is **not** is a way to make a *different* request. The
+ * `_id` is an md5 over the request that this package never recomputes — see
+ * `import.ts` — so a copy with an edited URL would carry the original's id,
+ * match nothing at replay, and fail silently. The copy keeps the id, and the
+ * caller edits the response.
+ *
+ * The clone is inserted directly after the last member of its group rather than
+ * appended to the file, because the list is shown in file order and a copy that
+ * appeared at the bottom, pages away from its original, reads as a new request
+ * somebody else recorded.
+ */
+export declare function duplicateEntry(har: Har, id: string, order: number): EditResult;
 export declare function notFound(id: string, order: number): string;
 /**
  * Removes one entry and closes the gap it leaves in its `_id` group.

package/dist/studio/edit.js

@@ -62,6 +62,41 @@ export function applyResponsePatch(har, id, order, patch) {
     }
     return { ok: true, har: next };
 }
+/**
+ * Copies an entry to the end of its own `_id` group — "the *next* time this same
+ * request happens, reply with this".
+ *
+ * `_order` is a position within a group of identical requests, not a label:
+ * Polly derives it at replay by counting how many earlier requests produced the
+ * same `_id`, starting at 0. So a recording with two members of a group answers
+ * the first call with `_order: 0` and the second with `_order: 1`. Duplicating
+ * appends a member, which is the only honest meaning "duplicate" can have here.
+ *
+ * What it deliberately is **not** is a way to make a *different* request. The
+ * `_id` is an md5 over the request that this package never recomputes — see
+ * `import.ts` — so a copy with an edited URL would carry the original's id,
+ * match nothing at replay, and fail silently. The copy keeps the id, and the
+ * caller edits the response.
+ *
+ * The clone is inserted directly after the last member of its group rather than
+ * appended to the file, because the list is shown in file order and a copy that
+ * appeared at the bottom, pages away from its original, reads as a new request
+ * somebody else recorded.
+ */
+export function duplicateEntry(har, id, order) {
+    const source = findEntry(har, id, order);
+    if (source === undefined) {
+        return { ok: false, error: { code: 'entry-not-found', message: notFound(id, order) } };
+    }
+    const next = structuredClone(har);
+    const entries = next.log.entries;
+    const group = entries.filter((entry) => entry._id === id);
+    const last = group.reduce((at, entry) => Math.max(at, entries.indexOf(entry)), -1);
+    const copy = structuredClone(findEntry(next, id, order));
+    copy._order = group.length;
+    entries.splice(last + 1, 0, copy);
+    return { ok: true, har: next };
+}
 export function notFound(id, order) {
     return `no entry with _id ${id} and _order ${order} — it may have been deleted since the page loaded`;
 }

package/dist/studio/import.d.ts

@@ -0,0 +1,34 @@
+import type { Har, HarEntry } from './types.js';
+/** The creator name the extension writes. Nothing else may be imported — see spec §3. */
+export declare const IMPORTABLE_CREATOR_NAME = "swagger-recorder";
+export interface ImportSkip {
+    url: string;
+    reason: string;
+}
+export interface ImportOutcome {
+    entries: HarEntry[];
+    added: number;
+    replaced: number;
+    skipped: ImportSkip[];
+}
+/**
+ * Whole-file rejection, null when the file is importable.
+ *
+ * The creator check is not caution, it is a correctness limit. An entry's `_id`
+ * is an md5 over method, url and body, and a multipart body is not in a HAR at
+ * all — so no importer can derive an id, and only this extension writes one.
+ * Accepting a DevTools export would mean writing entries with no id, or guessing.
+ */
+export declare function rejectImport(har: Har): string | null;
+/**
+ * Incoming entries folded into existing ones, keyed on `_id`.
+ *
+ * New wins, and a replacement keeps its position: the UI lists entries in file
+ * order, so a merge that moved them would read as the recording having changed
+ * more than it did.
+ *
+ * Duplicates inside the incoming file collapse rather than appending twice.
+ * Polly's `findEntry` stops at the first `_id` match, so a second copy is an
+ * entry nothing can reach, and re-importing would grow the file without bound.
+ */
+export declare function mergeEntries(existing: HarEntry[], incoming: HarEntry[]): ImportOutcome;

package/dist/studio/import.js

@@ -0,0 +1,93 @@
+/** The creator name the extension writes. Nothing else may be imported — see spec §3. */
+export const IMPORTABLE_CREATOR_NAME = 'swagger-recorder';
+/**
+ * Whole-file rejection, null when the file is importable.
+ *
+ * The creator check is not caution, it is a correctness limit. An entry's `_id`
+ * is an md5 over method, url and body, and a multipart body is not in a HAR at
+ * all — so no importer can derive an id, and only this extension writes one.
+ * Accepting a DevTools export would mean writing entries with no id, or guessing.
+ */
+export function rejectImport(har) {
+    const creator = har.log?.creator?.name;
+    if (creator !== IMPORTABLE_CREATOR_NAME) {
+        return `this HAR's creator is ${JSON.stringify(creator ?? null)} — only HARs downloaded from the swagger-recorder extension can be imported, because only they carry the Polly ids replay needs`;
+    }
+    if (!Array.isArray(har.log.entries) || har.log.entries.length === 0) {
+        return 'this HAR has no entries';
+    }
+    return null;
+}
+/**
+ * Incoming entries folded into existing ones, keyed on `_id`.
+ *
+ * New wins, and a replacement keeps its position: the UI lists entries in file
+ * order, so a merge that moved them would read as the recording having changed
+ * more than it did.
+ *
+ * Duplicates inside the incoming file collapse rather than appending twice.
+ * Polly's `findEntry` stops at the first `_id` match, so a second copy is an
+ * entry nothing can reach, and re-importing would grow the file without bound.
+ */
+export function mergeEntries(existing, incoming) {
+    const entries = [...existing];
+    const positions = new Map();
+    // First-wins, not last-wins: `buildPollyHar` stamps `_order: 0` on every entry
+    // without deduping, so an existing recording can legitimately hold the same
+    // `_id` twice. Polly's `findEntry` (har.ts) resolves an id to the FIRST match,
+    // so that is the index a replacement has to target — overwriting the later
+    // occurrence would report success while changing a slot Polly never reads.
+    entries.forEach((entry, index) => {
+        if (typeof entry?._id === 'string' && !positions.has(entry._id))
+            positions.set(entry._id, index);
+    });
+    const skipped = [];
+    let added = 0;
+    let replaced = 0;
+    for (const candidate of incoming) {
+        const problem = unusable(candidate);
+        if (problem !== null) {
+            skipped.push({ url: urlOf(candidate), reason: problem });
+            continue;
+        }
+        // `_order` is stamped rather than carried: polly-kit sets
+        // `matchRequestsBy.order: false`, so Polly computes 0 for every request.
+        const entry = { ...candidate, _order: 0 };
+        const at = positions.get(entry._id);
+        if (at === undefined) {
+            positions.set(entry._id, entries.length);
+            entries.push(entry);
+            added++;
+            continue;
+        }
+        // A collision with an entry this same import just added counts as neither:
+        // it was already reported as `added`, and reporting it as `replaced` too
+        // would describe one incoming entry twice.
+        const wasJustAdded = at >= existing.length;
+        entries[at] = entry;
+        if (!wasJustAdded)
+            replaced++;
+    }
+    return { entries, added, replaced, skipped };
+}
+/** Null when the entry can be written. A reason naming the cause otherwise. */
+function unusable(entry) {
+    if (entry === null || typeof entry !== 'object') {
+        return 'not an object — this is not a HAR entry';
+    }
+    if (typeof entry._id !== 'string' || entry._id === '') {
+        return 'no _id: recorded by an extension version that did not write one, so Polly could never find it. Record again with the current extension.';
+    }
+    if (entry.request === null || typeof entry.request !== 'object') {
+        return 'no request — this is not a HAR entry';
+    }
+    if (entry.response === null || typeof entry.response !== 'object') {
+        return 'no response, so there is nothing to replay';
+    }
+    return null;
+}
+/** Best-effort label for the skip report. Never throws on a malformed entry. */
+function urlOf(entry) {
+    const url = entry?.request?.url;
+    return typeof url === 'string' ? url : '(unknown url)';
+}

package/dist/studio/index.d.ts

@@ -7,3 +7,7 @@ export { parseHar, findEntry, POLLY_CREATOR_NAME } from './har.js';
 export { applyResponsePatch, deleteEntry } from './edit.js';
 export type { EditError, EditResult } from './edit.js';
 export type { Har, HarEntry, HarLog, HarRequest, HarResponse, HarContent, NvPair, ResponsePatch, } from './types.js';
+export { mergeEntries, rejectImport, IMPORTABLE_CREATOR_NAME } from './import.js';
+export type { ImportOutcome, ImportSkip } from './import.js';
+export { guidForRecording, rejectRecordingName } from './recording-id.js';
+export type { ImportResult } from './stores/types.js';

package/dist/studio/index.js

@@ -3,3 +3,5 @@ export { FsStore, serializeHar } from './stores/fs-store.js';
 export { StoreError } from './stores/types.js';
 export { parseHar, findEntry, POLLY_CREATOR_NAME } from './har.js';
 export { applyResponsePatch, deleteEntry } from './edit.js';
+export { mergeEntries, rejectImport, IMPORTABLE_CREATOR_NAME } from './import.js';
+export { guidForRecording, rejectRecordingName } from './recording-id.js';

package/dist/studio/recording-id.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Trimmed before it reaches Polly's hashing, not just checked: `' my-app '` and
+ * `'my-app'` hash to `my-app_4097172865` and `my-app_4014489609` — the slug half
+ * is identical, so the wrong directory looks right in a listing. Trimming here
+ * rather than in `rejectRecordingName` (a guard, not a transform) means every
+ * caller gets it whether or not they remembered to trim first.
+ */
+export declare function guidForRecording(recordingName: string): string;
+/**
+ * Why an empty name is refused rather than hashed.
+ *
+ * `guidForRecording('')` is `_2166136261` — a valid directory name that would be
+ * created happily and then never read, because no app configures an empty
+ * `recordingName`. Refusing names the mistake at the point it is made.
+ */
+export declare function rejectRecordingName(name: string): string | null;

package/dist/studio/recording-id.js

@@ -0,0 +1,35 @@
+/**
+ * The directory Polly looks a recording up in.
+ *
+ * Taken from Polly's own module rather than copied. The ten lines are easy to
+ * reproduce and easy to reproduce *wrongly*: `@sindresorhus/fnv1a@2`'s default
+ * export is the legacy 32-bit number implementation, which is the one Polly
+ * calls, while its named size exports return BigInt and would yield a different
+ * directory. A copy that drifted would send every recording somewhere nothing
+ * reads — silently, since a missing directory is a normal state.
+ *
+ * `@pollyjs/core` declares no `exports` map, so the deep path resolves.
+ * `test/studio/recording-id.test.ts` pins the result, so a core that moves the
+ * file fails a test rather than changing where recordings go.
+ */
+import guidFor from '@pollyjs/core/src/utils/guid-for-recording.js';
+/**
+ * Trimmed before it reaches Polly's hashing, not just checked: `' my-app '` and
+ * `'my-app'` hash to `my-app_4097172865` and `my-app_4014489609` — the slug half
+ * is identical, so the wrong directory looks right in a listing. Trimming here
+ * rather than in `rejectRecordingName` (a guard, not a transform) means every
+ * caller gets it whether or not they remembered to trim first.
+ */
+export function guidForRecording(recordingName) {
+    return guidFor(recordingName.trim());
+}
+/**
+ * Why an empty name is refused rather than hashed.
+ *
+ * `guidForRecording('')` is `_2166136261` — a valid directory name that would be
+ * created happily and then never read, because no app configures an empty
+ * `recordingName`. Refusing names the mistake at the point it is made.
+ */
+export function rejectRecordingName(name) {
+    return name.trim() === '' ? 'a recording name is required' : null;
+}

package/dist/studio/server.js

@@ -3,7 +3,7 @@ import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { FsStore } from './stores/fs-store.js';
 import { StoreError } from './stores/types.js';
-import { applyResponsePatch, deleteEntry } from './edit.js';
+import { applyResponsePatch, deleteEntry, duplicateEntry } from './edit.js';
 import { renderPage } from './ui/page.js';
 /**
  * A mountable editor for Polly recordings, in the style of swagger-ui: the app serves
@@ -66,6 +66,30 @@ async function handle(req, res, ctx) {
             sendJson(res, 200, { recordings: await ctx.store.list() });
             return;
         }
+        if (path === '/api/import' && req.method === 'POST') {
+            const body = await readJson(req, MAX_IMPORT_BYTES);
+            if (!body.ok) {
+                if (body.status === 413)
+                    res.setHeader('connection', 'close');
+                sendJson(res, body.status, { error: body.error });
+                return;
+            }
+            // A body of `null`, `[]` or `"x"` is valid JSON with no fields. Coercing to
+            // `{}` keeps the destructuring off a non-object, which would throw into the 500.
+            const fields = (typeof body.value === 'object' && body.value !== null ? body.value : {});
+            if (typeof fields.recordingName !== 'string') {
+                sendJson(res, 400, { error: 'recordingName must be a string' });
+                return;
+            }
+            if (fields.har === null || typeof fields.har !== 'object') {
+                sendJson(res, 400, { error: 'har must be a HAR object' });
+                return;
+            }
+            // StoreError from here — a rejected creator, an empty name, a corrupt
+            // target — lands in the catch-all below, which maps `unprocessable` to 422.
+            sendJson(res, 200, await ctx.store.importHar(fields.recordingName, fields.har));
+            return;
+        }
         // /api/recordings/:id  and  /api/recordings/:id/entries/:_id/:_order
         const segments = path.split('/').filter((segment) => segment !== '');
         const rawId = segments[2];
@@ -89,7 +113,7 @@ async function handle(req, res, ctx) {
                 }
                 const order = Number(segments[5]);
                 if (req.method === 'PATCH') {
-                    const body = await readJson(req);
+                    const body = await readJson(req, MAX_EDIT_BYTES);
                     if (!body.ok) {
                         if (body.status === 413)
                             res.setHeader('connection', 'close');
@@ -107,15 +131,23 @@ async function handle(req, res, ctx) {
                     await mutate(ctx, res, id, etag, (har) => deleteEntry(har, entryId, order));
                     return;
                 }
+                // POST, not PUT: this creates a member of the group rather than
+                // replacing one, and the URL it is posted to is the entry being copied.
+                if (req.method === 'POST') {
+                    const etag = url.searchParams.get('etag') ?? '';
+                    await mutate(ctx, res, id, etag, (har) => duplicateEntry(har, entryId, order));
+                    return;
+                }
             }
         }
         sendJson(res, 404, { error: 'not found' });
     }
     catch (err) {
         if (err instanceof StoreError) {
-            // `unprocessable` is unreachable while this handler calls only list/read/write, but
-            // Task 11's HttpStore and any switch to `store.patchEntry` make it reachable — and
-            // it would arrive as a binary-body refusal, which is a 422, not a 403.
+            // `unprocessable` is reachable: `/api/import` calls `store.importHar`, which raises
+            // it for a rejected creator, an empty recording name, or a corrupt target recording.
+            // Each of those — like a binary-body refusal elsewhere on the interface — is a 422,
+            // not a 403.
             const status = err.code === 'not-found'
                 ? 404
                 : err.code === 'conflict'
@@ -196,7 +228,14 @@ function decodeSegment(segment) {
  * The cap on a PATCH body. Generous for the JSON around one edited HAR entry, and far
  * below what it takes to hurt the host process.
  */
-const MAX_BODY_BYTES = 4 * 1024 * 1024;
+const MAX_EDIT_BYTES = 4 * 1024 * 1024;
+/**
+ * The cap on an imported HAR, which is a whole recording rather than one entry.
+ * Matched to the recording store's own 50 MB limit (`src/store.ts`): a file the
+ * store will happily persist must not be refused on the way in, or the feature
+ * fails on exactly the recordings worth importing — the ones with image bodies.
+ */
+const MAX_IMPORT_BYTES = 50 * 1024 * 1024;
 /**
  * The request body, bounded and parsed.
  *
@@ -206,7 +245,7 @@ const MAX_BODY_BYTES = 4 * 1024 * 1024;
  * A `SyntaxError` from `JSON.parse` is the same failure class as the malformed
  * percent-encoding handled in `decodeSegment`: a malformed request, not a server fault.
  */
-async function readJson(req) {
+async function readJson(req, limit) {
     const chunks = [];
     let bytes = 0;
     let overflowed = false;
@@ -215,7 +254,7 @@ async function readJson(req) {
         bytes += buffer.length;
         if (overflowed)
             continue;
-        if (bytes > MAX_BODY_BYTES) {
+        if (bytes > limit) {
             // Drop what was accumulated and stop accumulating, but keep draining. The cap is
             // about retained memory, and this bounds it. Neither `req.destroy()` nor
             // `req.pause()` works here: destroying resets the socket so a client still
@@ -228,7 +267,7 @@ async function readJson(req) {
         chunks.push(buffer);
     }
     if (overflowed) {
-        return { ok: false, status: 413, error: `request body exceeds ${MAX_BODY_BYTES} bytes` };
+        return { ok: false, status: 413, error: `request body exceeds ${limit} bytes` };
     }
     const raw = Buffer.concat(chunks).toString('utf8');
     if (raw === '')

package/dist/studio/stores/apply.d.ts

@@ -1,6 +1,17 @@
-import type { ReadResult, RecordingStore } from './types.js';
-import type { ResponsePatch } from '../types.js';
+import type { ReadResult, RecordingStore, ImportResult } from './types.js';
+import type { Har, ResponsePatch } from '../types.js';
 type Local = Pick<RecordingStore, 'read' | 'write'>;
 export declare function patchEntryVia(store: Local, id: string, entryId: string, order: number, etag: string, patch: ResponsePatch): Promise<ReadResult>;
 export declare function deleteEntryVia(store: Local, id: string, entryId: string, order: number, etag: string): Promise<ReadResult>;
+export declare function duplicateEntryVia(store: Local, id: string, entryId: string, order: number, etag: string): Promise<ReadResult>;
+type Importable = Pick<RecordingStore, 'read' | 'write' | 'create'>;
+/**
+ * The read-merge-write cycle, shared by every store that owns its own storage.
+ *
+ * A corrupt existing file is refused rather than overwritten. `read` reports
+ * unparseable JSON as `not-found`, which is indistinguishable from "absent" at
+ * this layer, so absence is established by `list` instead — the one call that
+ * tells a recording that cannot be parsed apart from one that was never written.
+ */
+export declare function importHarVia(store: Importable & Pick<RecordingStore, 'list'>, recordingName: string, incoming: Har): Promise<ImportResult>;
 export {};