@avivbenhamo/polly-kit 0.1.0 → 0.3.0

package/dist/studio/edit.js

@@ -0,0 +1,90 @@
+import { findEntry } from './har.js';
+import { bodyByteLength, decodeContent, encodeContent } from './body.js';
+import { getHeader, hasHeader, responseHeadersSize, setHeader } from './headers.js';
+/**
+ * Applies a response edit and re-derives everything that described the old response.
+ *
+ * Five fields are read at replay (`adapter/src/utils/normalize-recorded-response.js`):
+ * `status`, `statusText`, `headers`, `content.text` and `content.encoding`. Those must
+ * be right. `Content-Length` counts as one of them, because headers are handed to the
+ * app verbatim — a stale length contradicts the body beside it.
+ *
+ * The rest — `content.size`, `bodySize`, `headersSize`, `content.mimeType`,
+ * `redirectURL` — are HAR metadata Polly never reads. They are maintained anyway,
+ * because these are HAR files and other tools do read them.
+ *
+ * `cookies` is the exception. Polly builds it with `set-cookie-parser`, keeping
+ * attributes this package has no dependency to reproduce, so a regenerated list would
+ * be strictly worse than the recorded one. It is left alone, except that removing the
+ * last `Set-Cookie` header clears it — the one case where leaving it would be plainly
+ * wrong rather than merely stale.
+ */
+export function applyResponsePatch(har, id, order, patch) {
+    const existing = findEntry(har, id, order);
+    if (existing === undefined) {
+        return { ok: false, error: { code: 'entry-not-found', message: notFound(id, order) } };
+    }
+    if (patch.bodyText !== undefined && decodeContent(existing.response.content).kind === 'binary') {
+        return {
+            ok: false,
+            error: {
+                code: 'binary-body',
+                message: 'this response body is binary — editing it as text would replace the recorded bytes with a UTF-8 rendering of them',
+            },
+        };
+    }
+    const next = structuredClone(har);
+    const entry = findEntry(next, id, order);
+    const response = entry.response;
+    if (patch.status !== undefined)
+        response.status = patch.status;
+    if (patch.statusText !== undefined)
+        response.statusText = patch.statusText;
+    const hadSetCookie = hasHeader(response.headers, 'set-cookie');
+    if (patch.headers !== undefined)
+        response.headers = patch.headers;
+    if (patch.bodyText !== undefined) {
+        response.content.text = encodeContent(patch.bodyText, response.content.encoding);
+    }
+    const bytes = bodyByteLength(response.content.text ?? '', response.content.encoding);
+    response.content.size = bytes;
+    response.bodySize = bytes;
+    // Set it only where the recording had one: adding a Content-Length to a response
+    // that was chunked would describe the transfer differently than it was recorded.
+    if (hasHeader(response.headers, 'content-length')) {
+        response.headers = setHeader(response.headers, 'content-length', String(bytes));
+    }
+    response.content.mimeType = getHeader(response.headers, 'content-type') ?? 'text/plain';
+    response.redirectURL = getHeader(response.headers, 'location') ?? '';
+    response.headersSize = responseHeadersSize(response.headers);
+    if (hadSetCookie && !hasHeader(response.headers, 'set-cookie')) {
+        response.cookies = [];
+    }
+    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`;
+}
+/**
+ * Removes one entry and closes the gap it leaves in its `_id` group.
+ *
+ * `_order` is not a label, it is a position. Polly derives a request's order at replay
+ * by counting how many earlier requests in the recording produced the same `_id`,
+ * starting at 0 — so after deleting the `_order: 0` member of a pair, the survivor
+ * sitting at `_order: 1` is asked for as order 0 and never found again. It stays in the
+ * file, looks correct, and is dead. Renumbering the group from 0 is the whole fix.
+ */
+export function deleteEntry(har, id, order) {
+    if (findEntry(har, id, order) === undefined) {
+        return { ok: false, error: { code: 'entry-not-found', message: notFound(id, order) } };
+    }
+    const next = structuredClone(har);
+    next.log.entries = next.log.entries.filter((entry) => !(entry._id === id && entry._order === order));
+    const group = next.log.entries
+        .filter((entry) => entry._id === id)
+        .sort((a, b) => a._order - b._order);
+    group.forEach((entry, index) => {
+        entry._order = index;
+    });
+    return { ok: true, har: next };
+}

package/dist/studio/etag.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A content hash for optimistic concurrency, not for security. FNV-1a keeps this
+ * dependency-free and identical in Node and the browser, which matters because the
+ * page compares an etag it was given against one the store computed.
+ */
+export declare function etagFor(serialized: string): string;

package/dist/studio/etag.js

@@ -0,0 +1,14 @@
+/**
+ * A content hash for optimistic concurrency, not for security. FNV-1a keeps this
+ * dependency-free and identical in Node and the browser, which matters because the
+ * page compares an etag it was given against one the store computed.
+ */
+export function etagFor(serialized) {
+    const bytes = new TextEncoder().encode(serialized);
+    let hash = 0x811c9dc5;
+    for (const byte of bytes) {
+        hash ^= byte;
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return `${hash.toString(16).padStart(8, '0')}-${bytes.length.toString(16)}`;
+}

package/dist/studio/har.d.ts

@@ -0,0 +1,19 @@
+import type { Har, HarEntry } from './types.js';
+/** `Persister.findRecording` asserts on this exact string. */
+export declare const POLLY_CREATOR_NAME = "Polly.JS";
+export type ParseResult = {
+    ok: true;
+    har: Har;
+    /**
+     * Non-null when the file is readable but Polly itself will refuse it. The UI
+     * shows this rather than pretending the recording is fine; the alternative is
+     * a user editing a file that their app has already given up on.
+     */
+    pollyWillReject: string | null;
+} | {
+    ok: false;
+    problem: string;
+};
+export declare function parseHar(raw: string): ParseResult;
+/** Replay's own lookup, reproduced: `entry._id === id && entry._order === order`. */
+export declare function findEntry(har: Har, id: string, order: number): HarEntry | undefined;

package/dist/studio/har.js

@@ -0,0 +1,36 @@
+/** `Persister.findRecording` asserts on this exact string. */
+export const POLLY_CREATOR_NAME = 'Polly.JS';
+export function parseHar(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return { ok: false, problem: err instanceof Error ? err.message : String(err) };
+    }
+    if (!isHarShaped(parsed)) {
+        return { ok: false, problem: 'valid JSON, but not a HAR log with an entries array' };
+    }
+    const creator = parsed.log.creator?.name;
+    const pollyWillReject = creator === POLLY_CREATOR_NAME
+        ? null
+        : `log.creator.name is ${JSON.stringify(creator ?? null)}, but Polly only reads recordings whose creator is "${POLLY_CREATOR_NAME}" — it will ask you to delete this file`;
+    return { ok: true, har: parsed, pollyWillReject };
+}
+/**
+ * A shape check, not a schema validator. It exists to tell a HAR apart from some other
+ * JSON that landed in the directory — enough for a listing to say something true,
+ * without restating the types as runtime assertions.
+ */
+function isHarShaped(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const log = value.log;
+    if (log === null || typeof log !== 'object')
+        return false;
+    return Array.isArray(log.entries);
+}
+/** Replay's own lookup, reproduced: `entry._id === id && entry._order === order`. */
+export function findEntry(har, id, order) {
+    return har.log.entries.find((entry) => entry._id === id && entry._order === order);
+}

package/dist/studio/headers.d.ts

@@ -0,0 +1,31 @@
+import type { NvPair } from './types.js';
+/**
+ * HAR headers are an ordered list, not a map. Repeats carry meaning — two `Set-Cookie`
+ * values are two cookies — and Polly's `normalizeHeaders` folds repeats into an array
+ * on replay, so collapsing them here would change what the app receives.
+ *
+ * Everything below returns a new array. The store writes what it is given, so a helper
+ * that mutated its input would edit a recording the caller had not decided to save.
+ */
+export declare function getHeader(headers: NvPair[], name: string): string | undefined;
+export declare function hasHeader(headers: NvPair[], name: string): boolean;
+/**
+ * Replaces every occurrence of `name` with a single pair holding `value`, at the
+ * position of the first occurrence, or appends when there was none.
+ *
+ * Collapsing repeats is deliberate: this is only ever called with a single value, and
+ * leaving the other occurrences in place would mean setting `Content-Length` to 12
+ * while a second `Content-Length: 7` still followed it. The recorded spelling of the
+ * name and its `_fromType` marker are kept, since replay reads the latter.
+ */
+export declare function setHeader(headers: NvPair[], name: string, value: string): NvPair[];
+/**
+ * `persister/src/har/response.js`, reproduced:
+ *
+ *     getByteLength(keys.join() + values.join()) + keys.length * 2 + 2 + 2
+ *
+ * Nothing at replay reads this — it is HAR metadata for other tools — but leaving it
+ * describing the previous headers is the kind of inconsistency that makes a file look
+ * hand-mangled.
+ */
+export declare function responseHeadersSize(headers: NvPair[]): number;

package/dist/studio/headers.js

@@ -0,0 +1,59 @@
+import { utf8ByteLength } from './body.js';
+/**
+ * HAR headers are an ordered list, not a map. Repeats carry meaning — two `Set-Cookie`
+ * values are two cookies — and Polly's `normalizeHeaders` folds repeats into an array
+ * on replay, so collapsing them here would change what the app receives.
+ *
+ * Everything below returns a new array. The store writes what it is given, so a helper
+ * that mutated its input would edit a recording the caller had not decided to save.
+ */
+export function getHeader(headers, name) {
+    const wanted = name.toLowerCase();
+    return headers.find((header) => header.name.toLowerCase() === wanted)?.value;
+}
+export function hasHeader(headers, name) {
+    return getHeader(headers, name) !== undefined;
+}
+/**
+ * Replaces every occurrence of `name` with a single pair holding `value`, at the
+ * position of the first occurrence, or appends when there was none.
+ *
+ * Collapsing repeats is deliberate: this is only ever called with a single value, and
+ * leaving the other occurrences in place would mean setting `Content-Length` to 12
+ * while a second `Content-Length: 7` still followed it. The recorded spelling of the
+ * name and its `_fromType` marker are kept, since replay reads the latter.
+ */
+export function setHeader(headers, name, value) {
+    const wanted = name.toLowerCase();
+    const first = headers.find((header) => header.name.toLowerCase() === wanted);
+    if (first === undefined)
+        return [...headers, { name, value }];
+    const replacement = { ...first, value };
+    const result = [];
+    let placed = false;
+    for (const header of headers) {
+        if (header.name.toLowerCase() !== wanted) {
+            result.push(header);
+            continue;
+        }
+        if (!placed) {
+            result.push(replacement);
+            placed = true;
+        }
+    }
+    return result;
+}
+/**
+ * `persister/src/har/response.js`, reproduced:
+ *
+ *     getByteLength(keys.join() + values.join()) + keys.length * 2 + 2 + 2
+ *
+ * Nothing at replay reads this — it is HAR metadata for other tools — but leaving it
+ * describing the previous headers is the kind of inconsistency that makes a file look
+ * hand-mangled.
+ */
+export function responseHeadersSize(headers) {
+    const names = headers.map((header) => header.name);
+    const values = headers.map((header) => header.value);
+    return utf8ByteLength(names.join(',') + values.join(',')) + names.length * 2 + 2 + 2;
+}

package/dist/studio/index.d.ts

@@ -0,0 +1,9 @@
+export { pollyUi } from './server.js';
+export type { UiOptions } from './server.js';
+export { FsStore, serializeHar } from './stores/fs-store.js';
+export { StoreError } from './stores/types.js';
+export type { RecordingStore, RecordingSummary, ReadResult } from './stores/types.js';
+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';

package/dist/studio/index.js

@@ -0,0 +1,5 @@
+export { pollyUi } from './server.js';
+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';

package/dist/studio/server.d.ts

@@ -0,0 +1,35 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export interface UiOptions {
+    /** Where Polly's recordings live. Relative paths resolve against `cwd`. */
+    recordingsDir: string;
+    /**
+     * Path the handler is mounted at, stripped from the URL before routing.
+     *
+     * Express strips the mount path itself, so `app.use('/__polly', pollyUi(...))` needs
+     * nothing here. A raw `http.createServer` does not, so pass the prefix you route on.
+     */
+    basePath?: string;
+    /**
+     * Defaults to `process.env.NODE_ENV !== 'production'`.
+     *
+     * Recordings hold recorded request and response bodies. A handler that served them
+     * regardless of environment would turn "someone mounted this and shipped it" into a
+     * data leak, so when disabled it answers 404 — the same answer an unmounted path
+     * gives, rather than a 403 that confirms something is there.
+     */
+    enabled?: boolean;
+    cwd?: string;
+}
+/**
+ * A mountable editor for Polly recordings, in the style of swagger-ui: the app serves
+ * it, so there is no second process and no extra port.
+ *
+ * ```ts
+ * app.use('/__polly', pollyUi({ recordingsDir: './recordings' }))
+ * ```
+ *
+ * Returns a bare `(req, res)` handler rather than an Express router so the package
+ * takes no framework dependency — this signature is what Express, Fastify's compat
+ * layer and `http.createServer` all accept.
+ */
+export declare function pollyUi(options: UiOptions): (req: IncomingMessage, res: ServerResponse) => void;

package/dist/studio/server.js

@@ -0,0 +1,262 @@
+import { isAbsolute, join } from 'node:path';
+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 { renderPage } from './ui/page.js';
+/**
+ * A mountable editor for Polly recordings, in the style of swagger-ui: the app serves
+ * it, so there is no second process and no extra port.
+ *
+ * ```ts
+ * app.use('/__polly', pollyUi({ recordingsDir: './recordings' }))
+ * ```
+ *
+ * Returns a bare `(req, res)` handler rather than an Express router so the package
+ * takes no framework dependency — this signature is what Express, Fastify's compat
+ * layer and `http.createServer` all accept.
+ */
+export function pollyUi(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const root = isAbsolute(options.recordingsDir)
+        ? options.recordingsDir
+        : join(cwd, options.recordingsDir);
+    const store = new FsStore(root);
+    const basePath = trimTrailingSlash(options.basePath ?? '');
+    const enabled = options.enabled ?? process.env['NODE_ENV'] !== 'production';
+    return (req, res) => {
+        handle(req, res, { store, basePath, enabled }).catch((err) => {
+            sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+        });
+    };
+}
+async function handle(req, res, ctx) {
+    if (!ctx.enabled) {
+        // Bare: no body, no content-type. A JSON `{"error":"not found"}` would fingerprint the
+        // handler as mounted-and-disabled against a framework's own HTML 404, which is the
+        // opposite of what "indistinguishable from an unmounted path" asks for.
+        res.writeHead(404);
+        res.end();
+        return;
+    }
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    let path = url.pathname;
+    // The prefix must end at a segment boundary. A bare `startsWith` also matches
+    // `/__pollyapi/recordings/x`, which slices to `api/recordings/x` — byte-identical to
+    // what the legitimate `/__polly/api/recordings/x` produces, so it would serve the
+    // recording from a URL outside the mount.
+    if (ctx.basePath !== '' && (path === ctx.basePath || path.startsWith(`${ctx.basePath}/`))) {
+        path = path.slice(ctx.basePath.length);
+    }
+    if (path === '')
+        path = '/';
+    try {
+        if (path === '/' && (req.method === 'GET' || req.method === 'HEAD')) {
+            // Rendered before a single header is written. `renderPage` is a placeholder that
+            // cannot throw today, but Task 10 replaces its body — and a throw after `writeHead`
+            // would make the catch-all's own `writeHead(500)` raise ERR_HTTP_HEADERS_SENT inside
+            // a `.catch()`, i.e. an unhandled rejection that takes the host app down with it.
+            const html = req.method === 'HEAD' ? '' : renderPage(await clientScript());
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+            res.end(html);
+            return;
+        }
+        if (path === '/api/recordings' && req.method === 'GET') {
+            sendJson(res, 200, { recordings: await ctx.store.list() });
+            return;
+        }
+        // /api/recordings/:id  and  /api/recordings/:id/entries/:_id/:_order
+        const segments = path.split('/').filter((segment) => segment !== '');
+        const rawId = segments[2];
+        if (segments[0] === 'api' && segments[1] === 'recordings' && rawId !== undefined) {
+            const id = decodeSegment(rawId);
+            if (id === undefined) {
+                sendJson(res, 400, { error: `recording id ${rawId} is not valid percent-encoding` });
+                return;
+            }
+            if (segments.length === 3 && req.method === 'GET') {
+                const { har, etag, pollyWillReject } = await ctx.store.read(id);
+                sendJson(res, 200, { har, etag, pollyWillReject });
+                return;
+            }
+            const rawEntryId = segments[4];
+            if (segments.length === 6 && segments[3] === 'entries' && rawEntryId !== undefined) {
+                const entryId = decodeSegment(rawEntryId);
+                if (entryId === undefined) {
+                    sendJson(res, 400, { error: `entry id ${rawEntryId} is not valid percent-encoding` });
+                    return;
+                }
+                const order = Number(segments[5]);
+                if (req.method === 'PATCH') {
+                    const body = await readJson(req);
+                    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 but has no fields. Coercing to
+                    // `{}` keeps destructuring off a non-object, which would throw into the 500.
+                    const fields = (typeof body.value === 'object' && body.value !== null ? body.value : {});
+                    await mutate(ctx, res, id, fields.etag ?? '', (har) => applyResponsePatch(har, entryId, order, fields.patch ?? {}));
+                    return;
+                }
+                if (req.method === 'DELETE') {
+                    const etag = url.searchParams.get('etag') ?? '';
+                    await mutate(ctx, res, id, etag, (har) => deleteEntry(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.
+            const status = err.code === 'not-found'
+                ? 404
+                : err.code === 'conflict'
+                    ? 409
+                    : err.code === 'unprocessable'
+                        ? 422
+                        : 403;
+            sendJson(res, status, { error: err.message, code: err.code });
+            return;
+        }
+        throw err;
+    }
+}
+/** Read, apply, write — with the etag the page was holding, so a clash is a 409. */
+async function mutate(ctx, res, id, etag, apply) {
+    const read = await ctx.store.read(id);
+    if (read.etag !== etag) {
+        sendJson(res, 409, {
+            error: `recording ${id} changed since it was read — reload before saving`,
+            code: 'conflict',
+        });
+        return;
+    }
+    const result = apply(read.har);
+    if (!result.ok) {
+        sendJson(res, result.error.code === 'entry-not-found' ? 404 : 422, {
+            error: result.error.message,
+            code: result.error.code,
+        });
+        return;
+    }
+    await ctx.store.write(id, result.har, read.etag);
+    const after = await ctx.store.read(id);
+    sendJson(res, 200, { har: after.har, etag: after.etag, pollyWillReject: after.pollyWillReject });
+}
+let cachedScript = null;
+/**
+ * The page's script, inlined rather than fetched.
+ *
+ * A second route would need a URL, and the handler cannot know one: under
+ * `app.use('/__polly', pollyUi(...))` Express strips the mount path before this code
+ * runs, so `basePath` is `''` and a `<script src>` the page emitted would point at
+ * `/client.js` — a path that never reaches this handler. Inlining removes the question.
+ * The script derives its own API base from `location.pathname` at run time, which is
+ * the only place the mount path is still visible.
+ */
+async function clientScript() {
+    if (cachedScript !== null)
+        return cachedScript;
+    try {
+        cachedScript = await readFile(fileURLToPath(new URL('./client.bundle.js', import.meta.url)), 'utf8');
+    }
+    catch {
+        // Running from source: `npm test` and `--experimental-strip-types` never build.
+        // Self-executing, not an exported `start()`: nothing imports this string, so an
+        // export would define a function no one calls and ship a blank page instead of the
+        // explanation. Module scripts are deferred, so `document.body` exists by now.
+        cachedScript =
+            'document.body.innerHTML = "<p>polly-studio was not built — run <code>npm run build</code>.</p>"';
+    }
+    return cachedScript;
+}
+/**
+ * `decodeURIComponent` throws `URIError` on a malformed sequence — `%zz`, a lone `%` —
+ * and WHATWG URL parsing leaves both intact in `pathname`, so they reach this code. Left
+ * to propagate, the throw lands in `pollyUi`'s catch-all and reports a 500: a server
+ * fault for what is a malformed request. `undefined` becomes a 400 at the call site.
+ */
+function decodeSegment(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 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;
+/**
+ * The request body, bounded and parsed.
+ *
+ * Both failures are the client's, so neither may reach the catch-all as a 500. An
+ * unbounded read would let one PATCH drive the host process to OOM — and requirement 1's
+ * own threat model assumes `enabled` can be true in production, so that surface is real.
+ * 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) {
+    const chunks = [];
+    let bytes = 0;
+    let overflowed = false;
+    for await (const chunk of req) {
+        const buffer = chunk;
+        bytes += buffer.length;
+        if (overflowed)
+            continue;
+        if (bytes > MAX_BODY_BYTES) {
+            // 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
+            // uploading sees ECONNRESET rather than the 413, and pausing stalls the upload so
+            // the response is never read — measured, the request simply hung.
+            overflowed = true;
+            chunks.length = 0;
+            continue;
+        }
+        chunks.push(buffer);
+    }
+    if (overflowed) {
+        return { ok: false, status: 413, error: `request body exceeds ${MAX_BODY_BYTES} bytes` };
+    }
+    const raw = Buffer.concat(chunks).toString('utf8');
+    if (raw === '')
+        return { ok: true, value: {} };
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            status: 400,
+            error: `request body is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+function sendJson(res, status, body) {
+    // The catch-all calls this after a route may already have started responding. Writing
+    // a second set of headers throws ERR_HTTP_HEADERS_SENT from inside a `.catch()`, which
+    // is an unhandled rejection and fatal by default on Node >= 15.
+    if (res.writableEnded)
+        return;
+    if (res.headersSent) {
+        res.end();
+        return;
+    }
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(body));
+}
+function trimTrailingSlash(value) {
+    return value.endsWith('/') ? value.slice(0, -1) : value;
+}

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

@@ -0,0 +1,6 @@
+import type { ReadResult, RecordingStore } from './types.js';
+import type { 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 {};

package/dist/studio/stores/apply.js

@@ -0,0 +1,20 @@
+import { applyResponsePatch, deleteEntry as deleteEntryIn } from '../edit.js';
+import { StoreError } from './types.js';
+export function patchEntryVia(store, id, entryId, order, etag, patch) {
+    return applyEntryEdit(store, id, etag, (har) => applyResponsePatch(har, entryId, order, patch));
+}
+export function deleteEntryVia(store, id, entryId, order, etag) {
+    return applyEntryEdit(store, id, etag, (har) => deleteEntryIn(har, entryId, order));
+}
+async function applyEntryEdit(store, id, etag, apply) {
+    const read = await store.read(id);
+    if (read.etag !== etag) {
+        throw new StoreError('conflict', `recording ${id} changed since it was read — reload before saving`);
+    }
+    const result = apply(read.har);
+    if (!result.ok) {
+        throw new StoreError(result.error.code === 'entry-not-found' ? 'not-found' : 'unprocessable', result.error.message);
+    }
+    await store.write(id, result.har, read.etag);
+    return store.read(id);
+}