@emdzej/bimmerz-vfs 0.1.0 → 0.2.0

package/dist/cached-http.js

@@ -0,0 +1,271 @@
+/**
+ * `CachedHttpDirectory` — drop-in replacement for `HttpDirectory`
+ * that persists fetched bytes (index + files) in OPFS (preferred)
+ * or IndexedDB.
+ *
+ * Why a wrapper, not changes to `HttpDirectory`: the base class is
+ * the right minimum surface for read-only HTTP. Caching is an
+ * orthogonal concern that some consumers don't want (development,
+ * one-shot CLI tools). Keeping the two separate also means a bug in
+ * the cache layer can't poison the simple path.
+ *
+ * What gets cached:
+ *
+ *   • The `index.json` per directory.
+ *   • The body of every `file(name).arrayBuffer()` call.
+ *
+ * Staleness policy: **stale-while-revalidate.**
+ *
+ *   • First read of any URL: do a normal fetch, store body + ETag +
+ *     Last-Modified + the `Content-Type`, return.
+ *   • Subsequent reads inside `maxAgeMs` (default 5 min): serve
+ *     cached bytes immediately, no network at all.
+ *   • Subsequent reads OUTSIDE `maxAgeMs`: serve cached bytes
+ *     immediately AND kick off a background conditional GET (`If-
+ *     None-Match` / `If-Modified-Since`). When the server replies:
+ *       - `304 Not Modified` → bump `validatedAt`. Body untouched.
+ *       - `200 OK` → write the new body to cache. The next call
+ *         then sees the fresh bytes.
+ *   • Explicit `revalidate(file)` forces an immediate conditional
+ *     fetch and returns once the network response settles.
+ *
+ * The first-after-update read returns the OLD bytes. That's the
+ * standard SWR tradeoff — favours latency over freshness, lets
+ * the dashboard render instantly on every load.
+ */
+import { openCacheBackend, } from './cache.js';
+/* ── Module-level cached backends ──────────────────────────────── */
+/* When the user doesn't pass `backend`, we share one across all
+   `CachedHttpDirectory` instances per namespace. Saves opening
+   multiple OPFS handles to the same directory. */
+const backendCache = new Map();
+function getBackend(namespace, prefer) {
+    const key = `${prefer ?? 'auto'}:${namespace}`;
+    let p = backendCache.get(key);
+    if (!p) {
+        p = openCacheBackend({ namespace, prefer });
+        backendCache.set(key, p);
+    }
+    return p;
+}
+/* ── CachedHttpFile ────────────────────────────────────────────── */
+/** `VirtualFile` backed by a cache lookup + conditional fetch. */
+export class CachedHttpFile {
+    name;
+    size;
+    #url;
+    #fetch;
+    #backend;
+    #cacheKey;
+    #maxAgeMs;
+    constructor(args) {
+        this.name = args.name;
+        this.size = args.size;
+        this.#url = args.url;
+        this.#fetch = args.fetch;
+        this.#backend = args.backend;
+        this.#cacheKey = args.cacheKey;
+        this.#maxAgeMs = args.maxAgeMs;
+    }
+    async arrayBuffer() {
+        const backend = await this.#backend;
+        const cached = await backend.get(this.#cacheKey);
+        const now = Date.now();
+        if (cached) {
+            /* Fresh enough — serve directly. */
+            if (now - cached.meta.validatedAt < this.#maxAgeMs) {
+                return cached.bytes;
+            }
+            /* Stale — kick off a conditional fetch in the background and
+               return the cached bytes immediately. The next call will see
+               the result. */
+            void this.#revalidateInBackground(cached);
+            return cached.bytes;
+        }
+        /* Cold miss. Network fetch and store. */
+        const fresh = await this.#fetchAndStore();
+        return fresh.bytes;
+    }
+    async #fetchAndStore(prev) {
+        const headers = {};
+        if (prev?.meta.etag)
+            headers['If-None-Match'] = prev.meta.etag;
+        if (prev?.meta.lastModified)
+            headers['If-Modified-Since'] = prev.meta.lastModified;
+        const res = await this.#fetch(this.#url, { headers });
+        const now = Date.now();
+        if (res.status === 304 && prev) {
+            /* Server says cached body is still fresh. Update timestamp,
+               leave the bytes alone. */
+            const updatedMeta = { ...prev.meta, validatedAt: now };
+            const entry = { bytes: prev.bytes, meta: updatedMeta };
+            const backend = await this.#backend;
+            await backend.put(this.#cacheKey, entry);
+            return entry;
+        }
+        if (!res.ok) {
+            /* Treat any non-success as "keep the cached entry, surface the
+               error". When we have no cached entry, throw. */
+            if (prev)
+                return prev;
+            throw new Error(`HTTP ${res.status} ${res.statusText}: ${this.#url}`);
+        }
+        const bytes = await res.arrayBuffer();
+        const meta = {
+            url: this.#url,
+            etag: res.headers.get('etag') ?? undefined,
+            lastModified: res.headers.get('last-modified') ?? undefined,
+            contentType: res.headers.get('content-type') ?? undefined,
+            size: bytes.byteLength,
+            storedAt: now,
+            validatedAt: now,
+        };
+        const entry = { bytes, meta };
+        const backend = await this.#backend;
+        await backend.put(this.#cacheKey, entry);
+        return entry;
+    }
+    async #revalidateInBackground(prev) {
+        try {
+            await this.#fetchAndStore(prev);
+        }
+        catch {
+            /* Background failures don't bubble — the cached entry stays
+               valid until the next attempt. */
+        }
+    }
+    /** Force a fresh conditional fetch and resolve once the cache is
+     *  consistent with the server. */
+    async revalidate() {
+        const backend = await this.#backend;
+        const cached = await backend.get(this.#cacheKey);
+        await this.#fetchAndStore(cached ?? undefined);
+    }
+}
+/* ── CachedHttpDirectory ───────────────────────────────────────── */
+export class CachedHttpDirectory {
+    name;
+    #baseUrl;
+    #indexFile;
+    #fetch;
+    #backend;
+    #namespace;
+    #cacheKey;
+    #maxAgeMs;
+    /** Lazily populated on first access. Unlike `HttpDirectory`,
+     *  we DON'T memo the parsed index — we re-read from the cache so
+     *  background-revalidation updates take effect immediately. */
+    #indexUrl;
+    constructor(baseUrl, options = {}) {
+        this.#baseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+        this.#indexFile = options.indexFile ?? 'index.json';
+        this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.name = this.#baseUrl.split('/').filter(Boolean).at(-1) ?? '';
+        this.#namespace = options.namespace ?? defaultNamespace(this.#baseUrl);
+        this.#cacheKey = options.cacheKey ?? ((url) => url);
+        this.#maxAgeMs = options.maxAgeMs ?? 5 * 60 * 1000;
+        this.#backend = options.backend
+            ? Promise.resolve(options.backend)
+            : getBackend(this.#namespace, options.preferBackend);
+        this.#indexUrl = `${this.#baseUrl}/${this.#indexFile}`;
+    }
+    async #loadIndex() {
+        const indexFile = new CachedHttpFile({
+            name: this.#indexFile,
+            size: 0,
+            url: this.#indexUrl,
+            fetch: this.#fetch,
+            backend: this.#backend,
+            cacheKey: this.#cacheKey(this.#indexUrl),
+            maxAgeMs: this.#maxAgeMs,
+        });
+        const bytes = await indexFile.arrayBuffer();
+        const text = new TextDecoder('utf-8').decode(bytes);
+        return JSON.parse(text);
+    }
+    async file(name) {
+        const index = await this.#loadIndex();
+        const target = name.toLowerCase();
+        const entry = index.find((e) => (e.type === 'file' || e.type === 'link') && e.fullName === target);
+        if (!entry)
+            return null;
+        const url = `${this.#baseUrl}/${entry.originalFullName}`;
+        return new CachedHttpFile({
+            name: entry.originalFullName,
+            size: entry.size,
+            url,
+            fetch: this.#fetch,
+            backend: this.#backend,
+            cacheKey: this.#cacheKey(url),
+            maxAgeMs: this.#maxAgeMs,
+        });
+    }
+    async dir(name) {
+        const index = await this.#loadIndex();
+        const target = name.toLowerCase();
+        const entry = index.find((e) => e.type === 'dir' && e.fullName === target);
+        if (!entry)
+            return null;
+        /* Pass the SAME backend down — nested directories share one
+           namespace. Their cache keys still distinguish entries via the
+           full URL. */
+        return new CachedHttpDirectory(`${this.#baseUrl}/${entry.originalFullName}`, {
+            indexFile: this.#indexFile,
+            fetch: this.#fetch,
+            backend: await this.#backend,
+            namespace: this.#namespace,
+            cacheKey: this.#cacheKey,
+            maxAgeMs: this.#maxAgeMs,
+        });
+    }
+    async entries() {
+        const index = await this.#loadIndex();
+        const result = [];
+        for (const entry of index) {
+            if (entry.type === 'file' || entry.type === 'link') {
+                result.push({ kind: 'file', name: entry.originalFullName, size: entry.size });
+            }
+            else if (entry.type === 'dir') {
+                result.push({ kind: 'dir', name: entry.originalFullName });
+            }
+        }
+        return result;
+    }
+    /* ── CacheControl ───────────────────────────────────────── */
+    async stats() {
+        const backend = await this.#backend;
+        const sz = await backend.size();
+        return { backend: backend.kind, entries: sz.entries, totalBytes: sz.totalBytes };
+    }
+    async clear() {
+        const backend = await this.#backend;
+        await backend.clear();
+    }
+    async revalidate(path) {
+        /* `path` is interpreted relative to baseUrl. Normalises leading
+           slashes so callers can pass `"foo.bin"` or `"/foo.bin"`. */
+        const trimmed = path.replace(/^\/+/, '');
+        const url = `${this.#baseUrl}/${trimmed}`;
+        const file = new CachedHttpFile({
+            name: trimmed,
+            size: 0,
+            url,
+            fetch: this.#fetch,
+            backend: this.#backend,
+            cacheKey: this.#cacheKey(url),
+            maxAgeMs: this.#maxAgeMs,
+        });
+        await file.revalidate();
+    }
+    async revalidateIndex() {
+        return this.revalidate(this.#indexFile);
+    }
+}
+function defaultNamespace(baseUrl) {
+    /* Strip scheme + double slashes so two URLs that differ only in
+       `http://` vs `https://` still share a namespace — same content
+       under two ingress paths is the common case for embedded
+       dongles served over both ports. */
+    return baseUrl.replace(/^https?:\/\//, '');
+}
+//# sourceMappingURL=cached-http.js.map

package/dist/cached-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached-http.js","sourceRoot":"","sources":["../src/cached-http.ts"],"names":[],"mappings":"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"}

package/dist/cached-http.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tests for `CachedHttpDirectory` + `CachedHttpFile` against the
+ * in-memory cache backend. OPFS and IDB live behind their own
+ * abstraction (`CacheBackend`) — once those persist, the
+ * directory's behaviour is the same.
+ *
+ * Each test wires a mock `fetch` that records calls + responds with
+ * controllable status / headers / body, so we can simulate 200, 304,
+ * 404, and stale-while-revalidate cycles deterministically.
+ */
+export {};
+//# sourceMappingURL=cached-http.test.d.ts.map

package/dist/cached-http.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached-http.test.d.ts","sourceRoot":"","sources":["../src/cached-http.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/cached-http.test.js

@@ -0,0 +1,348 @@
+/**
+ * Tests for `CachedHttpDirectory` + `CachedHttpFile` against the
+ * in-memory cache backend. OPFS and IDB live behind their own
+ * abstraction (`CacheBackend`) — once those persist, the
+ * directory's behaviour is the same.
+ *
+ * Each test wires a mock `fetch` that records calls + responds with
+ * controllable status / headers / body, so we can simulate 200, 304,
+ * 404, and stale-while-revalidate cycles deterministically.
+ */
+import { describe, expect, it } from 'vitest';
+import { CachedHttpDirectory, CachedHttpFile } from './cached-http.js';
+import { MemoryCacheBackend } from './cache.js';
+function bytes(values) {
+    return new Uint8Array(values).buffer;
+}
+function makeFetch(routes, spy) {
+    return async (input, init) => {
+        const url = input.toString();
+        const headers = {};
+        if (init?.headers) {
+            for (const [k, v] of Object.entries(init.headers)) {
+                headers[k.toLowerCase()] = v;
+            }
+        }
+        spy?.calls.push({ url, headers: { ...headers } });
+        const route = routes.get(url);
+        if (!route || route.status === 404) {
+            return new Response(null, { status: 404, statusText: 'Not Found' });
+        }
+        /* If the caller set conditional + an If-None-Match that matches
+           our etag, return 304. */
+        if (route.conditional && route.etag && headers['if-none-match'] === route.etag) {
+            return new Response(null, { status: 304, statusText: 'Not Modified' });
+        }
+        const responseHeaders = { 'Content-Type': 'application/octet-stream' };
+        if (route.etag)
+            responseHeaders['ETag'] = route.etag;
+        if (route.lastModified)
+            responseHeaders['Last-Modified'] = route.lastModified;
+        return new Response(route.body ?? '', {
+            status: route.status ?? 200,
+            headers: responseHeaders,
+        });
+    };
+}
+/* Index fixture used across tests. */
+const BASE = 'http://test.local/install';
+function buildIndex() {
+    return JSON.stringify([
+        { type: 'file', name: 'ms43', fullName: 'ms43.ipo', originalName: 'MS43', originalFullName: 'MS43.IPO', size: 512 },
+        { type: 'file', name: 'readme', fullName: 'readme.txt', originalName: 'README', originalFullName: 'README.TXT', size: 64 },
+        { type: 'dir', name: 'sub', fullName: 'sub', originalName: 'SUB', originalFullName: 'SUB', size: 0 },
+    ]);
+}
+function makeBackend() {
+    return new MemoryCacheBackend('test-ns');
+}
+/* ── CachedHttpFile ─────────────────────────────────────────────── */
+describe('CachedHttpFile', () => {
+    it('fetches once and serves the cached bytes thereafter', async () => {
+        const routes = new Map([
+            [`${BASE}/MS43.IPO`, { body: bytes([1, 2, 3, 4]), etag: '"a1"' }],
+        ]);
+        const spy = { calls: [] };
+        const backend = makeBackend();
+        const f = new CachedHttpFile({
+            name: 'MS43.IPO', size: 4,
+            url: `${BASE}/MS43.IPO`,
+            fetch: makeFetch(routes, spy),
+            backend: Promise.resolve(backend),
+            cacheKey: `${BASE}/MS43.IPO`,
+            maxAgeMs: 60_000,
+        });
+        const first = new Uint8Array(await f.arrayBuffer());
+        expect(Array.from(first)).toEqual([1, 2, 3, 4]);
+        expect(spy.calls.length).toBe(1);
+        const second = new Uint8Array(await f.arrayBuffer());
+        expect(Array.from(second)).toEqual([1, 2, 3, 4]);
+        /* Still one fetch — second read came from the cache. */
+        expect(spy.calls.length).toBe(1);
+    });
+    it('revalidates against the server with If-None-Match and accepts 304', async () => {
+        const routes = new Map([
+            [`${BASE}/MS43.IPO`, { body: bytes([1, 2, 3, 4]), etag: '"a1"', conditional: true }],
+        ]);
+        const spy = { calls: [] };
+        const backend = makeBackend();
+        const f = new CachedHttpFile({
+            name: 'MS43.IPO', size: 4,
+            url: `${BASE}/MS43.IPO`,
+            fetch: makeFetch(routes, spy),
+            backend: Promise.resolve(backend),
+            cacheKey: `${BASE}/MS43.IPO`,
+            maxAgeMs: 60_000,
+        });
+        await f.arrayBuffer();
+        await f.revalidate();
+        /* Second call should be a conditional GET that the mock returns
+           304 to — body unchanged. */
+        expect(spy.calls.length).toBe(2);
+        expect(spy.calls[1].headers['if-none-match']).toBe('"a1"');
+        /* The cache entry still holds the original bytes. */
+        const cached = await backend.get(`${BASE}/MS43.IPO`);
+        expect(cached?.bytes.byteLength).toBe(4);
+    });
+    it('replaces cached bytes when the server returns 200 with new content', async () => {
+        const routes = new Map([
+            [`${BASE}/MS43.IPO`, { body: bytes([1, 2]), etag: '"a1"' }],
+        ]);
+        const spy = { calls: [] };
+        const backend = makeBackend();
+        const f = new CachedHttpFile({
+            name: 'MS43.IPO', size: 2,
+            url: `${BASE}/MS43.IPO`,
+            fetch: makeFetch(routes, spy),
+            backend: Promise.resolve(backend),
+            cacheKey: `${BASE}/MS43.IPO`,
+            maxAgeMs: 60_000,
+        });
+        await f.arrayBuffer();
+        /* Mutate the route — new content + new etag, NOT conditional. */
+        routes.set(`${BASE}/MS43.IPO`, { body: bytes([9, 9, 9]), etag: '"a2"' });
+        await f.revalidate();
+        const cached = await backend.get(`${BASE}/MS43.IPO`);
+        expect(Array.from(new Uint8Array(cached.bytes))).toEqual([9, 9, 9]);
+        expect(cached.meta.etag).toBe('"a2"');
+    });
+    it('serves cached bytes immediately when over maxAgeMs and revalidates in background', async () => {
+        const routes = new Map([
+            [`${BASE}/MS43.IPO`, { body: bytes([1, 2, 3]), etag: '"a1"', conditional: true }],
+        ]);
+        const spy = { calls: [] };
+        const backend = makeBackend();
+        const f = new CachedHttpFile({
+            name: 'MS43.IPO', size: 3,
+            url: `${BASE}/MS43.IPO`,
+            fetch: makeFetch(routes, spy),
+            backend: Promise.resolve(backend),
+            cacheKey: `${BASE}/MS43.IPO`,
+            maxAgeMs: 0, // always stale
+        });
+        /* Cold miss → 1 fetch. */
+        await f.arrayBuffer();
+        expect(spy.calls.length).toBe(1);
+        /* Next call: cached bytes are returned synchronously, but the
+           maxAge=0 policy schedules a background revalidate. */
+        const buf = new Uint8Array(await f.arrayBuffer());
+        expect(Array.from(buf)).toEqual([1, 2, 3]);
+        /* Flush microtasks. */
+        await new Promise((r) => setTimeout(r, 0));
+        /* Background fetch went out — total 2 calls. */
+        expect(spy.calls.length).toBe(2);
+        expect(spy.calls[1].headers['if-none-match']).toBe('"a1"');
+    });
+    it('throws on cold-miss 404 with no cache entry', async () => {
+        const routes = new Map();
+        const backend = makeBackend();
+        const f = new CachedHttpFile({
+            name: 'X', size: 0,
+            url: `${BASE}/missing`,
+            fetch: makeFetch(routes),
+            backend: Promise.resolve(backend),
+            cacheKey: `${BASE}/missing`,
+            maxAgeMs: 60_000,
+        });
+        await expect(f.arrayBuffer()).rejects.toThrow(/404/);
+    });
+    it('keeps cached bytes when revalidation returns an error', async () => {
+        const routes = new Map([
+            [`${BASE}/MS43.IPO`, { body: bytes([1, 2, 3, 4]), etag: '"a1"' }],
+        ]);
+        const backend = makeBackend();
+        const f = new CachedHttpFile({
+            name: 'MS43.IPO', size: 4,
+            url: `${BASE}/MS43.IPO`,
+            fetch: makeFetch(routes),
+            backend: Promise.resolve(backend),
+            cacheKey: `${BASE}/MS43.IPO`,
+            maxAgeMs: 60_000,
+        });
+        await f.arrayBuffer();
+        /* Mutate the route to return 500. revalidate() should NOT throw
+           (we have a cached entry) and the cache should be intact. */
+        routes.set(`${BASE}/MS43.IPO`, { status: 500 });
+        await f.revalidate();
+        const cached = await backend.get(`${BASE}/MS43.IPO`);
+        expect(cached).not.toBeNull();
+        expect(Array.from(new Uint8Array(cached.bytes))).toEqual([1, 2, 3, 4]);
+    });
+});
+/* ── CachedHttpDirectory ──────────────────────────────────────── */
+describe('CachedHttpDirectory', () => {
+    it('caches the index and reuses it across file/dir lookups', async () => {
+        const routes = new Map([
+            [`${BASE}/index.json`, { body: buildIndex(), etag: '"i1"' }],
+            [`${BASE}/MS43.IPO`, { body: bytes([0xAA]) }],
+        ]);
+        const spy = { calls: [] };
+        const dir = new CachedHttpDirectory(BASE, {
+            fetch: makeFetch(routes, spy),
+            backend: makeBackend(),
+        });
+        await dir.entries();
+        await dir.file('MS43.IPO');
+        await dir.entries();
+        /* Index fetched once; MS43.IPO not yet fetched (file() only
+           returns a CachedHttpFile, doesn't read bytes). */
+        const indexCalls = spy.calls.filter((c) => c.url.endsWith('/index.json')).length;
+        expect(indexCalls).toBe(1);
+    });
+    it('clear() wipes the namespace', async () => {
+        const routes = new Map([
+            [`${BASE}/index.json`, { body: buildIndex() }],
+            [`${BASE}/MS43.IPO`, { body: bytes([0xAA, 0xBB]) }],
+        ]);
+        const backend = makeBackend();
+        const dir = new CachedHttpDirectory(BASE, {
+            fetch: makeFetch(routes),
+            backend,
+        });
+        const f = await dir.file('MS43.IPO');
+        await f.arrayBuffer();
+        let stats = await dir.stats();
+        expect(stats.entries).toBeGreaterThan(0);
+        await dir.clear();
+        stats = await dir.stats();
+        expect(stats.entries).toBe(0);
+    });
+    it('stats() reports backend kind + total bytes', async () => {
+        const routes = new Map([
+            [`${BASE}/index.json`, { body: buildIndex() }],
+            [`${BASE}/MS43.IPO`, { body: new ArrayBuffer(1000) }],
+        ]);
+        const dir = new CachedHttpDirectory(BASE, {
+            fetch: makeFetch(routes),
+            backend: makeBackend(),
+        });
+        const f = await dir.file('MS43.IPO');
+        await f.arrayBuffer();
+        const stats = await dir.stats();
+        expect(stats.backend).toBe('memory');
+        expect(stats.entries).toBe(2); // index + MS43.IPO
+        expect(stats.totalBytes).toBeGreaterThanOrEqual(1000);
+    });
+    it('cacheKey hook canonicalises URLs with query strings', async () => {
+        /* Same content under two URLs that differ only by a signed-token
+           query string. With the cacheKey hook stripping the query,
+           both should hit the same cache entry. */
+        const body = bytes([1, 2, 3]);
+        const routes = new Map([
+            [`${BASE}/MS43.IPO?t=abc`, { body }],
+            [`${BASE}/MS43.IPO?t=def`, { body }],
+        ]);
+        const spy = { calls: [] };
+        const backend = makeBackend();
+        const fetchFn = makeFetch(routes, spy);
+        const cacheKey = (url) => url.replace(/\?.*$/, '');
+        const a = new CachedHttpFile({
+            name: 'a', size: 3,
+            url: `${BASE}/MS43.IPO?t=abc`,
+            fetch: fetchFn,
+            backend: Promise.resolve(backend),
+            cacheKey: cacheKey(`${BASE}/MS43.IPO?t=abc`),
+            maxAgeMs: 60_000,
+        });
+        const b = new CachedHttpFile({
+            name: 'b', size: 3,
+            url: `${BASE}/MS43.IPO?t=def`,
+            fetch: fetchFn,
+            backend: Promise.resolve(backend),
+            cacheKey: cacheKey(`${BASE}/MS43.IPO?t=def`),
+            maxAgeMs: 60_000,
+        });
+        await a.arrayBuffer();
+        await b.arrayBuffer();
+        /* Only one fetch — the second resolved from cache because the
+           cache keys are equal after the hook normalised away the token. */
+        expect(spy.calls.length).toBe(1);
+    });
+    it('revalidate(path) updates a cached entry on demand', async () => {
+        const routes = new Map([
+            [`${BASE}/index.json`, { body: buildIndex() }],
+            [`${BASE}/MS43.IPO`, { body: bytes([1]), etag: '"a1"' }],
+        ]);
+        const backend = makeBackend();
+        const dir = new CachedHttpDirectory(BASE, {
+            fetch: makeFetch(routes),
+            backend,
+        });
+        const f = await dir.file('MS43.IPO');
+        await f.arrayBuffer();
+        /* Server-side update. */
+        routes.set(`${BASE}/MS43.IPO`, { body: bytes([2, 2]), etag: '"a2"' });
+        await dir.revalidate('MS43.IPO');
+        const cached = await backend.get(`${BASE}/MS43.IPO`);
+        expect(Array.from(new Uint8Array(cached.bytes))).toEqual([2, 2]);
+        expect(cached.meta.etag).toBe('"a2"');
+    });
+    it('revalidateIndex() refetches the index', async () => {
+        const routes = new Map([
+            [`${BASE}/index.json`, { body: buildIndex(), etag: '"i1"' }],
+        ]);
+        const spy = { calls: [] };
+        const dir = new CachedHttpDirectory(BASE, {
+            fetch: makeFetch(routes, spy),
+            backend: makeBackend(),
+        });
+        await dir.entries();
+        await dir.revalidateIndex();
+        const indexCalls = spy.calls.filter((c) => c.url.endsWith('/index.json')).length;
+        expect(indexCalls).toBe(2);
+    });
+});
+/* ── MemoryCacheBackend (used to back the tests; sanity-check it
+ *  separately so failures here don't masquerade as CachedHttpFile
+ *  bugs). ─────────────────────────────────────────────────────── */
+describe('MemoryCacheBackend', () => {
+    it('round-trips put + get', async () => {
+        const b = makeBackend();
+        await b.put('k', {
+            bytes: bytes([1, 2, 3]),
+            meta: { url: 'http://x', size: 3, storedAt: 1, validatedAt: 1 },
+        });
+        const e = await b.get('k');
+        expect(e).not.toBeNull();
+        expect(Array.from(new Uint8Array(e.bytes))).toEqual([1, 2, 3]);
+    });
+    it('isolates namespaces', async () => {
+        const a = new MemoryCacheBackend('a');
+        const b = new MemoryCacheBackend('b');
+        await a.put('k', {
+            bytes: new ArrayBuffer(0),
+            meta: { url: 'u', size: 0, storedAt: 0, validatedAt: 0 },
+        });
+        expect((await b.get('k'))).toBeNull();
+    });
+    it('clear(prefix) only removes matching keys', async () => {
+        const b = makeBackend();
+        await b.put('foo/a', { bytes: new ArrayBuffer(0), meta: { url: 'u', size: 0, storedAt: 0, validatedAt: 0 } });
+        await b.put('foo/b', { bytes: new ArrayBuffer(0), meta: { url: 'u', size: 0, storedAt: 0, validatedAt: 0 } });
+        await b.put('bar/c', { bytes: new ArrayBuffer(0), meta: { url: 'u', size: 0, storedAt: 0, validatedAt: 0 } });
+        await b.clear('foo/');
+        const keys = await b.keys();
+        expect(keys).toEqual(['bar/c']);
+    });
+});
+//# sourceMappingURL=cached-http.test.js.map