vitecache 0.2.0 → 0.3.0

package/dist/storage.js

@@ -1,98 +1,93 @@
-import { createHash } from 'node:crypto';
-import { realpath } from 'node:fs/promises';
-import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as disk from './disk.js';
-import { equalHashes, hashes, resolvedDependencies } from './dependencies.js';
+import { ChangedDependenciesError, equalHashes, hashableDependencies, hashes, MissingDependencyError, resolvedDependencies } from './dependencies.js';
+import { contentHash, fileHash } from './hash.js';
 import { packageVersion } from './packages.js';
-function digest(bytes) {
-    return createHash('sha256').update(bytes).digest('hex');
-}
-export class ChangedDependenciesError extends Error {
-    constructor() {
-        super('vitecache dependencies changed during computation.');
-    }
-}
-function metadata(bytes) {
-    const value = JSON.parse(new TextDecoder().decode(bytes));
-    if (typeof value !== 'object' || value === null || !('contentHash' in value) || !('dependencies' in value)) {
-        throw new Error('Invalid vitecache metadata.');
+/** A metadata file vitecache wrote; any failure to read it names the file, since no request caused it. */
+function metadata(bytes, file) {
+    try {
+        const value = JSON.parse(new TextDecoder().decode(bytes));
+        if (typeof value !== 'object' || value === null || !('contentHash' in value) || !('dependencies' in value)) {
+            throw new Error('Expected contentHash and dependencies.');
+        }
+        const hash = value.contentHash;
+        if (typeof hash !== 'string' || !/^[a-f0-9]{64}$/.test(hash))
+            throw new Error('Expected a content hash.');
+        const validated = hashes(value.dependencies);
+        // Metadata without saved dependencies: all that vitecache 0.1 wrote, and what 0.2 wrote for entries that had none.
+        if (!('saved' in value))
+            return { contentHash: hash, dependencies: validated, saved: {}, savedHashes: {} };
+        // vitecache 0.2 kept each saved dependency with its hash in one record. Its entry misses until a save replaces it.
+        if (!('savedHashes' in value))
+            return undefined;
+        return { contentHash: hash, dependencies: validated, saved: hashableDependencies(value.saved), savedHashes: hashes(value.savedHashes) };
     }
-    const { contentHash, dependencies } = value;
-    if (typeof contentHash !== 'string' || !/^[a-f0-9]{64}$/.test(contentHash)) {
-        throw new Error('Invalid vitecache metadata.');
+    catch (cause) {
+        throw new Error(`Invalid vitecache metadata: ${file}`, { cause });
     }
-    return { contentHash, dependencies: hashes(dependencies) };
 }
 function matches(current, expected) {
-    return current !== null && equalHashes(current, expected);
+    return current.status === 'current' && equalHashes(current.hashes, expected);
 }
 export function createStorage(options) {
     const { root, directory } = disk.location(options);
     async function snapshot(dependencies) {
-        const entries = await Promise.all(Object.entries(dependencies).filter(([, dependency]) => !('value' in dependency)).map(async ([name, dependency]) => {
-            try {
-                if (dependency.package !== undefined) {
-                    const version = await packageVersion(root, dependency.package);
-                    return version === undefined ? null : [name, digest(new TextEncoder().encode(version))];
-                }
-                if (dependency.path === undefined)
-                    throw new TypeError('Expected a resolved dependency.');
-                const bytes = await disk.load(resolve(root, dependency.path));
-                return bytes === undefined ? null : [name, digest(bytes)];
-            }
-            catch (error) {
-                if (!disk.missingDependency(error))
-                    throw error;
-                return null;
-            }
+        const entries = await Promise.all(Object.entries(dependencies).map(async ([name, dependency]) => {
+            if (dependency.package === undefined)
+                return [name, await fileHash(resolve(root, dependency.path))];
+            const version = await packageVersion(root, dependency.package);
+            return [name, version === undefined ? undefined : contentHash(new TextEncoder().encode(version))];
         }));
         const present = [];
-        for (const entry of entries) {
-            if (entry === null)
-                return null;
-            present.push(entry);
+        for (const [name, hash] of entries) {
+            if (hash === undefined)
+                return { status: 'missing', message: `Missing file or package dependency: ${name}` };
+            present.push([name, hash]);
         }
-        return Object.fromEntries(present);
+        return { status: 'current', hashes: Object.fromEntries(present) };
+    }
+    async function load(key) {
+        const file = join(directory, `${key}.json`);
+        const raw = await disk.load(file);
+        if (raw === undefined)
+            return undefined;
+        const parsed = metadata(raw, file);
+        if (!parsed || !matches(await snapshot(parsed.saved), parsed.savedHashes))
+            return undefined;
+        const bytes = await disk.load(join(directory, `${key}.bin`));
+        if (bytes === undefined || contentHash(bytes) !== parsed.contentHash)
+            return undefined;
+        // The metadata file's modification time is the entry's last use. The bytes keep theirs, so static hosts keep their
+        // validators.
+        await disk.touch(file);
+        return { tag: contentHash(raw), hashes: parsed.dependencies, bytes };
     }
     return {
         async canSave() { return true; },
-        async resolve(files) {
-            return resolvedDependencies(Object.fromEntries(await Promise.all(Object.entries(files).map(async ([name, dependency]) => {
+        async resolve(declared) {
+            return resolvedDependencies(Object.fromEntries(await Promise.all(Object.entries(declared).map(async ([name, dependency]) => {
                 if (dependency.url === undefined)
                     return [name, dependency];
                 const url = new URL(dependency.url);
                 if (url.protocol !== 'file:') {
                     throw new Error('Node file dependency URLs must use file:. Use a project-root-relative path for Vite-served files.');
                 }
-                const file = fileURLToPath(url);
-                let path = relative(root, file);
-                if (path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path)) {
-                    path = relative(await realpath(root), await realpath(file));
-                }
-                return [name, { path: path.split(sep).join('/') }];
+                return [name, { path: await disk.rootRelative(root, fileURLToPath(url)) }];
             }))));
         },
         snapshot,
-        async load(key) {
-            const record = await disk.load(join(directory, `${key}.json`));
-            if (record === undefined)
-                return undefined;
-            const { contentHash, dependencies } = metadata(record);
-            const bytes = await disk.load(join(directory, `${key}.bin`));
-            if (bytes === undefined || digest(bytes) !== contentHash)
-                return undefined;
-            return { bytes, hashes: dependencies };
-        },
-        async save(key, value, files, expected) {
-            if (!matches(await snapshot(files), expected))
-                throw new ChangedDependenciesError();
+        load,
+        async save(key, value, { checked, expected, saved }) {
+            const current = await snapshot(saved);
+            if (current.status !== 'current')
+                throw new MissingDependencyError(`Cannot save a cache entry with a missing saved dependency. ${current.message}`);
             await disk.ignore(root, directory);
             await disk.save(join(directory, `${key}.bin`), value, async () => {
-                if (!matches(await snapshot(files), expected))
+                if (!matches(await snapshot(checked), expected))
                     throw new ChangedDependenciesError();
             });
-            const record = { contentHash: digest(value), dependencies: expected };
+            const record = { contentHash: contentHash(value), dependencies: expected, saved, savedHashes: current.hashes };
             await disk.save(join(directory, `${key}.json`), new TextEncoder().encode(JSON.stringify(record)));
         },
     };

package/dist/storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C,SAAS,MAAM,CAAC,KAAiB;IAC/B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAOD,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACjD;QACE,KAAK,CAAC,oDAAoD,CAAC,CAAC;IAC9D,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,KAAiB;IACjC,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACnE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,CAAC,aAAa,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,cAAc,IAAI,KAAK,CAAC,EAAE,CAAC;QAC3G,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,GAAG,KAAK,CAAC;IAC5C,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;AAC7D,CAAC;AAED,SAAS,OAAO,CAAC,OAAsB,EAAE,QAAgB;IACvD,OAAO,OAAO,KAAK,IAAI,IAAI,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAqD;IACjF,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAEnD,KAAK,UAAU,QAAQ,CAAC,YAAkC;QACxD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,EAAE;YACnJ,IAAI,CAAC;gBACH,IAAI,UAAU,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;oBACrC,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;oBAC/D,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAA4B,CAAC;gBACrH,CAAC;gBACD,IAAI,UAAU,CAAC,IAAI,KAAK,SAAS;oBAAE,MAAM,IAAI,SAAS,CAAC,iCAAiC,CAAC,CAAC;gBAC1F,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC9D,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAA4B,CAAC;YACvF,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC;oBAAE,MAAM,KAAK,CAAC;gBAChD,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC,CAAC,CAAC,CAAC;QACJ,MAAM,OAAO,GAAuB,EAAE,CAAC;QACvC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC;YAChC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IAED,OAAO;QACL,KAAK,CAAC,OAAO,KAAK,OAAO,IAAI,CAAC,CAAC,CAAC;QAChC,KAAK,CAAC,OAAO,CAAC,KAAmB;YAC/B,OAAO,oBAAoB,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,EAAE;gBACtH,IAAI,UAAU,CAAC,GAAG,KAAK,SAAS;oBAAE,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;gBAC5D,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;gBACpC,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;oBAC7B,MAAM,IAAI,KAAK,CAAC,mGAAmG,CAAC,CAAC;gBACvH,CAAC;gBACD,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;gBAChC,IAAI,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBAChC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;oBACrE,IAAI,GAAG,QAAQ,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC9D,CAAC;gBACD,OAAO,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACrD,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACR,CAAC;QACD,QAAQ;QACR,KAAK,CAAC,IAAI,CAAC,GAAG;YACZ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC;YAC/D,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAC3C,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;YACvD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC;YAC7D,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,WAAW;gBAAE,OAAO,SAAS,CAAC;YAC3E,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;QACzC,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ;YACpC,IAAI,CAAC,OAAO,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;gBAAE,MAAM,IAAI,wBAAwB,EAAE,CAAC;YACpF,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YACnC,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,GAAG,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE;gBAC/D,IAAI,CAAC,OAAO,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;oBAAE,MAAM,IAAI,wBAAwB,EAAE,CAAC;YACtF,CAAC,CAAC,CAAC;YACH,MAAM,MAAM,GAAa,EAAE,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;YAChF,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACpG,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import { createHash } from 'node:crypto';\nimport { realpath } from 'node:fs/promises';\nimport { isAbsolute, join, relative, resolve, sep } from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport * as disk from './disk.js';\nimport { equalHashes, hashes, resolvedDependencies } from './dependencies.js';\nimport { packageVersion } from './packages.js';\nimport type { Backend, CacheEntryOptions, Dependencies, Hashes, ResolvedDependencies } from './types.js';\n\nfunction digest(bytes: Uint8Array): string {\n  return createHash('sha256').update(bytes).digest('hex');\n}\n\ninterface Metadata {\n  contentHash: string;\n  dependencies: Hashes;\n}\n\nexport class ChangedDependenciesError extends Error {\n  constructor() {\n    super('vitecache dependencies changed during computation.');\n  }\n}\n\nfunction metadata(bytes: Uint8Array): Metadata {\n  const value: unknown = JSON.parse(new TextDecoder().decode(bytes));\n  if (typeof value !== 'object' || value === null || !('contentHash' in value) || !('dependencies' in value)) {\n    throw new Error('Invalid vitecache metadata.');\n  }\n  const { contentHash, dependencies } = value;\n  if (typeof contentHash !== 'string' || !/^[a-f0-9]{64}$/.test(contentHash)) {\n    throw new Error('Invalid vitecache metadata.');\n  }\n  return { contentHash, dependencies: hashes(dependencies) };\n}\n\nfunction matches(current: Hashes | null, expected: Hashes): boolean {\n  return current !== null && equalHashes(current, expected);\n}\n\nexport function createStorage(options: Pick<CacheEntryOptions, 'root' | 'basePath'>): Backend {\n  const { root, directory } = disk.location(options);\n\n  async function snapshot(dependencies: ResolvedDependencies): Promise<Hashes | null> {\n    const entries = await Promise.all(Object.entries(dependencies).filter(([, dependency]) => !('value' in dependency)).map(async ([name, dependency]) => {\n      try {\n        if (dependency.package !== undefined) {\n          const version = await packageVersion(root, dependency.package);\n          return version === undefined ? null : [name, digest(new TextEncoder().encode(version))] satisfies [string, string];\n        }\n        if (dependency.path === undefined) throw new TypeError('Expected a resolved dependency.');\n        const bytes = await disk.load(resolve(root, dependency.path));\n        return bytes === undefined ? null : [name, digest(bytes)] satisfies [string, string];\n      } catch (error) {\n        if (!disk.missingDependency(error)) throw error;\n        return null;\n      }\n    }));\n    const present: [string, string][] = [];\n    for (const entry of entries) {\n      if (entry === null) return null;\n      present.push(entry);\n    }\n    return Object.fromEntries(present);\n  }\n\n  return {\n    async canSave() { return true; },\n    async resolve(files: Dependencies) {\n      return resolvedDependencies(Object.fromEntries(await Promise.all(Object.entries(files).map(async ([name, dependency]) => {\n        if (dependency.url === undefined) return [name, dependency];\n        const url = new URL(dependency.url);\n        if (url.protocol !== 'file:') {\n          throw new Error('Node file dependency URLs must use file:. Use a project-root-relative path for Vite-served files.');\n        }\n        const file = fileURLToPath(url);\n        let path = relative(root, file);\n        if (path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path)) {\n          path = relative(await realpath(root), await realpath(file));\n        }\n        return [name, { path: path.split(sep).join('/') }];\n      }))));\n    },\n    snapshot,\n    async load(key) {\n      const record = await disk.load(join(directory, `${key}.json`));\n      if (record === undefined) return undefined;\n      const { contentHash, dependencies } = metadata(record);\n      const bytes = await disk.load(join(directory, `${key}.bin`));\n      if (bytes === undefined || digest(bytes) !== contentHash) return undefined;\n      return { bytes, hashes: dependencies };\n    },\n    async save(key, value, files, expected) {\n      if (!matches(await snapshot(files), expected)) throw new ChangedDependenciesError();\n      await disk.ignore(root, directory);\n      await disk.save(join(directory, `${key}.bin`), value, async () => {\n        if (!matches(await snapshot(files), expected)) throw new ChangedDependenciesError();\n      });\n      const record: Metadata = { contentHash: digest(value), dependencies: expected };\n      await disk.save(join(directory, `${key}.json`), new TextEncoder().encode(JSON.stringify(record)));\n    },\n  };\n}\n"]}
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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","sourcesContent":["import { join, resolve } from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport * as disk from './disk.js';\nimport { ChangedDependenciesError, equalHashes, hashableDependencies, hashes, MissingDependencyError, resolvedDependencies } from './dependencies.js';\nimport { contentHash, fileHash } from './hash.js';\nimport { packageVersion } from './packages.js';\nimport type { Backend, CacheEntryOptions, Dependencies, Hashable, Hashes, Snapshot, Stored } from './types.js';\n\ninterface Metadata {\n  contentHash: string;\n  dependencies: Hashes;\n  saved: Dependencies<Hashable>;\n  /** The saved dependencies' hashes when the entry was saved. */\n  savedHashes: Hashes;\n}\n\n/** A metadata file vitecache wrote; any failure to read it names the file, since no request caused it. */\nfunction metadata(bytes: Uint8Array, file: string): Metadata | undefined {\n  try {\n    const value: unknown = JSON.parse(new TextDecoder().decode(bytes));\n    if (typeof value !== 'object' || value === null || !('contentHash' in value) || !('dependencies' in value)) {\n      throw new Error('Expected contentHash and dependencies.');\n    }\n    const hash = value.contentHash;\n    if (typeof hash !== 'string' || !/^[a-f0-9]{64}$/.test(hash)) throw new Error('Expected a content hash.');\n    const validated = hashes(value.dependencies);\n    // Metadata without saved dependencies: all that vitecache 0.1 wrote, and what 0.2 wrote for entries that had none.\n    if (!('saved' in value)) return { contentHash: hash, dependencies: validated, saved: {}, savedHashes: {} };\n    // vitecache 0.2 kept each saved dependency with its hash in one record. Its entry misses until a save replaces it.\n    if (!('savedHashes' in value)) return undefined;\n    return { contentHash: hash, dependencies: validated, saved: hashableDependencies(value.saved), savedHashes: hashes(value.savedHashes) };\n  } catch (cause) {\n    throw new Error(`Invalid vitecache metadata: ${file}`, { cause });\n  }\n}\n\n/** A stored entry as storage reads it, its hashes always known. */\nexport interface Found extends Stored {\n  /** The entity tag's opaque value: it changes whenever the entry's bytes or dependency hashes do. */\n  tag: string;\n  hashes: Hashes;\n}\n\nexport interface Storage extends Backend {\n  /** Reads a valid entry and records its use for prune(). */\n  load(key: string): Promise<Found | undefined>;\n}\n\nfunction matches(current: Snapshot, expected: Hashes): boolean {\n  return current.status === 'current' && equalHashes(current.hashes, expected);\n}\n\nexport function createStorage(options: Pick<CacheEntryOptions, 'root' | 'basePath'>): Storage {\n  const { root, directory } = disk.location(options);\n\n  async function snapshot(dependencies: Dependencies<Hashable>): Promise<Exclude<Snapshot, { status: 'unchecked' }>> {\n    const entries = await Promise.all(Object.entries(dependencies).map(async ([name, dependency]) => {\n      if (dependency.package === undefined) return [name, await fileHash(resolve(root, dependency.path))] as const;\n      const version = await packageVersion(root, dependency.package);\n      return [name, version === undefined ? undefined : contentHash(new TextEncoder().encode(version))] as const;\n    }));\n    const present: [string, string][] = [];\n    for (const [name, hash] of entries) {\n      if (hash === undefined) return { status: 'missing', message: `Missing file or package dependency: ${name}` };\n      present.push([name, hash]);\n    }\n    return { status: 'current', hashes: Object.fromEntries(present) };\n  }\n\n  async function load(key: string): Promise<Found | undefined> {\n    const file = join(directory, `${key}.json`);\n    const raw = await disk.load(file);\n    if (raw === undefined) return undefined;\n    const parsed = metadata(raw, file);\n    if (!parsed || !matches(await snapshot(parsed.saved), parsed.savedHashes)) return undefined;\n    const bytes = await disk.load(join(directory, `${key}.bin`));\n    if (bytes === undefined || contentHash(bytes) !== parsed.contentHash) return undefined;\n    // The metadata file's modification time is the entry's last use. The bytes keep theirs, so static hosts keep their\n    // validators.\n    await disk.touch(file);\n    return { tag: contentHash(raw), hashes: parsed.dependencies, bytes };\n  }\n\n  return {\n    async canSave() { return true; },\n    async resolve(declared: Dependencies) {\n      return resolvedDependencies(Object.fromEntries(await Promise.all(Object.entries(declared).map(async ([name, dependency]) => {\n        if (dependency.url === undefined) return [name, dependency];\n        const url = new URL(dependency.url);\n        if (url.protocol !== 'file:') {\n          throw new Error('Node file dependency URLs must use file:. Use a project-root-relative path for Vite-served files.');\n        }\n        return [name, { path: await disk.rootRelative(root, fileURLToPath(url)) }];\n      }))));\n    },\n    snapshot,\n    load,\n    async save(key, value, { checked, expected, saved }) {\n      const current = await snapshot(saved);\n      if (current.status !== 'current') throw new MissingDependencyError(`Cannot save a cache entry with a missing saved dependency. ${current.message}`);\n      await disk.ignore(root, directory);\n      await disk.save(join(directory, `${key}.bin`), value, async () => {\n        if (!matches(await snapshot(checked), expected)) throw new ChangedDependenciesError();\n      });\n      const record: Metadata = { contentHash: contentHash(value), dependencies: expected, saved, savedHashes: current.hashes };\n      await disk.save(join(directory, `${key}.json`), new TextEncoder().encode(JSON.stringify(record)));\n    },\n  };\n}\n"]}

package/dist/types.d.ts

@@ -23,32 +23,67 @@ export type Dependency = {
     readonly path?: never;
     readonly url?: never;
 };
-export type Dependencies = Readonly<Record<string, Dependency>>;
-export type ResolvedDependency = Exclude<Dependency, {
+export type Dependencies<D extends Dependency = Dependency> = Readonly<Record<string, D>>;
+/** A dependency whose URL, if it had one, was resolved to a path. */
+export type Resolved<D extends Dependency = Dependency> = Exclude<D, {
     readonly url: string;
 }>;
-export type ResolvedDependencies = Readonly<Record<string, ResolvedDependency>>;
+/** A file, URL, or package dependency: unlike a value, one whose current state can be checked again later. */
+export type Checked<D extends Dependency = Dependency> = Exclude<D, {
+    readonly value: JsonValue;
+}>;
+/** A dependency passed to save(): only checked kinds, since values select the result. */
+export type SavedDependency = Checked;
+export type SavedDependencies = Dependencies<SavedDependency>;
+/** A resolved checked dependency, a file path or a package: one whose current state can be hashed. */
+export type Hashable = Resolved<Checked>;
 export type Paths = Readonly<Record<string, string>>;
+/** Dependency names mapped to file-content or installed-package-version hashes. */
 export type Hashes = Readonly<Record<string, string>>;
+/** Current dependency hashes, a missing dependency, or dependencies a browser without the plugin cannot check. */
+export type Snapshot = {
+    readonly status: 'current';
+    readonly hashes: Hashes;
+} | {
+    readonly status: 'missing';
+    readonly message: string;
+} | {
+    readonly status: 'unchecked';
+};
 export interface CacheEntryOptions {
     /** Identifies the computation and its implementation version, for example "simplify@2". */
     version: string;
-    /** Named dependencies sorted by name. JSON values affect the key; file contents and installed package versions are validated in Node or through the Vite plugin. Paths are always project-root-relative. URLs resolve to those paths through Vite, or from local file: URLs in Node. Packages track only the declared package's installed version, without importing it. */
+    /** Named dependencies. JSON values affect the key; file contents and installed package versions are validated in Node or through the Vite plugin. Paths are always project-root-relative. URLs resolve to those paths through Vite, or from local file: URLs in Node. Packages track only the declared package's installed version, without importing it. */
     dependencies?: Dependencies;
     /** Disk directory in Node (default public/_vitecache); URL prefix in browsers (default /_vitecache/). Excluded from the key. */
     basePath?: string;
     /** Node project root, default process.cwd(). Browser dependencies resolve against the Vite root. Excluded from the key. */
     root?: string;
 }
+export interface SaveOptions {
+    /**
+     * What the result was built from, when known only after computing it. They do not affect the key, so a save with
+     * different saved dependencies replaces the same entry. Rechecked by every load() where file contents are validated;
+     * a changed or missing one is a miss. Hashed when save() runs, so one that changed after the computation read it goes
+     * unnoticed until it changes again. One without a backing file makes save() throw MissingDependencyError. Values select
+     * the result, so they belong in the constructor.
+     */
+    dependencies?: SavedDependencies;
+}
 export interface Stored {
     bytes: Uint8Array;
     hashes?: Hashes;
 }
 export interface Backend {
     canSave(): Promise<boolean>;
-    resolve(dependencies: Dependencies): Promise<ResolvedDependencies>;
-    /** null means a missing dependency; undefined means validation is unavailable. Values need no fingerprint. */
-    snapshot(dependencies: ResolvedDependencies): Promise<Hashes | null | undefined>;
-    load(key: string, validate: boolean): Promise<Stored | undefined>;
-    save(key: string, value: Uint8Array, dependencies: ResolvedDependencies, expected: Hashes): Promise<void>;
+    resolve(dependencies: Dependencies): Promise<Dependencies<Resolved>>;
+    snapshot(dependencies: Dependencies<Hashable>): Promise<Snapshot>;
+    load(key: string): Promise<Stored | undefined>;
+    save(key: string, value: Uint8Array, check: {
+        /** Must still match `expected`. */
+        checked: Dependencies<Hashable>;
+        expected: Hashes;
+        /** Hashed now and rechecked on load. */
+        saved: Dependencies<Hashable>;
+    }): Promise<void>;
 }

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["export type JsonValue = null | boolean | number | string | readonly JsonValue[] | { readonly [key: string]: JsonValue };\n\n/** Exactly one source per dependency. Names and descriptors participate in cache identity. */\nexport type Dependency =\n  | { readonly value: JsonValue; readonly path?: never; readonly url?: never; readonly package?: never }\n  | { readonly path: string; readonly value?: never; readonly url?: never; readonly package?: never }\n  | { readonly url: string; readonly value?: never; readonly path?: never; readonly package?: never }\n  | { readonly package: string; readonly value?: never; readonly path?: never; readonly url?: never };\nexport type Dependencies = Readonly<Record<string, Dependency>>;\nexport type ResolvedDependency = Exclude<Dependency, { readonly url: string }>;\nexport type ResolvedDependencies = Readonly<Record<string, ResolvedDependency>>;\nexport type Paths = Readonly<Record<string, string>>;\nexport type Hashes = Readonly<Record<string, string>>;\n\nexport interface CacheEntryOptions {\n  /** Identifies the computation and its implementation version, for example \"simplify@2\". */\n  version: string;\n  /** Named dependencies sorted by name. JSON values affect the key; file contents and installed package versions are validated in Node or through the Vite plugin. Paths are always project-root-relative. URLs resolve to those paths through Vite, or from local file: URLs in Node. Packages track only the declared package's installed version, without importing it. */\n  dependencies?: Dependencies;\n  /** Disk directory in Node (default public/_vitecache); URL prefix in browsers (default /_vitecache/). Excluded from the key. */\n  basePath?: string;\n  /** Node project root, default process.cwd(). Browser dependencies resolve against the Vite root. Excluded from the key. */\n  root?: string;\n}\n\nexport interface Stored {\n  bytes: Uint8Array;\n  hashes?: Hashes;\n}\n\nexport interface Backend {\n  canSave(): Promise<boolean>;\n  resolve(dependencies: Dependencies): Promise<ResolvedDependencies>;\n  /** null means a missing dependency; undefined means validation is unavailable. Values need no fingerprint. */\n  snapshot(dependencies: ResolvedDependencies): Promise<Hashes | null | undefined>;\n  load(key: string, validate: boolean): Promise<Stored | undefined>;\n  save(key: string, value: Uint8Array, dependencies: ResolvedDependencies, expected: Hashes): Promise<void>;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["export type JsonValue = null | boolean | number | string | readonly JsonValue[] | { readonly [key: string]: JsonValue };\n\n/** Exactly one source per dependency. Names and descriptors participate in cache identity. */\nexport type Dependency =\n  | { readonly value: JsonValue; readonly path?: never; readonly url?: never; readonly package?: never }\n  | { readonly path: string; readonly value?: never; readonly url?: never; readonly package?: never }\n  | { readonly url: string; readonly value?: never; readonly path?: never; readonly package?: never }\n  | { readonly package: string; readonly value?: never; readonly path?: never; readonly url?: never };\nexport type Dependencies<D extends Dependency = Dependency> = Readonly<Record<string, D>>;\n/** A dependency whose URL, if it had one, was resolved to a path. */\nexport type Resolved<D extends Dependency = Dependency> = Exclude<D, { readonly url: string }>;\n/** A file, URL, or package dependency: unlike a value, one whose current state can be checked again later. */\nexport type Checked<D extends Dependency = Dependency> = Exclude<D, { readonly value: JsonValue }>;\n/** A dependency passed to save(): only checked kinds, since values select the result. */\nexport type SavedDependency = Checked;\nexport type SavedDependencies = Dependencies<SavedDependency>;\n/** A resolved checked dependency, a file path or a package: one whose current state can be hashed. */\nexport type Hashable = Resolved<Checked>;\nexport type Paths = Readonly<Record<string, string>>;\n/** Dependency names mapped to file-content or installed-package-version hashes. */\nexport type Hashes = Readonly<Record<string, string>>;\n/** Current dependency hashes, a missing dependency, or dependencies a browser without the plugin cannot check. */\nexport type Snapshot =\n  | { readonly status: 'current'; readonly hashes: Hashes }\n  | { readonly status: 'missing'; readonly message: string }\n  | { readonly status: 'unchecked' };\n\nexport interface CacheEntryOptions {\n  /** Identifies the computation and its implementation version, for example \"simplify@2\". */\n  version: string;\n  /** Named dependencies. JSON values affect the key; file contents and installed package versions are validated in Node or through the Vite plugin. Paths are always project-root-relative. URLs resolve to those paths through Vite, or from local file: URLs in Node. Packages track only the declared package's installed version, without importing it. */\n  dependencies?: Dependencies;\n  /** Disk directory in Node (default public/_vitecache); URL prefix in browsers (default /_vitecache/). Excluded from the key. */\n  basePath?: string;\n  /** Node project root, default process.cwd(). Browser dependencies resolve against the Vite root. Excluded from the key. */\n  root?: string;\n}\n\nexport interface SaveOptions {\n  /**\n   * What the result was built from, when known only after computing it. They do not affect the key, so a save with\n   * different saved dependencies replaces the same entry. Rechecked by every load() where file contents are validated;\n   * a changed or missing one is a miss. Hashed when save() runs, so one that changed after the computation read it goes\n   * unnoticed until it changes again. One without a backing file makes save() throw MissingDependencyError. Values select\n   * the result, so they belong in the constructor.\n   */\n  dependencies?: SavedDependencies;\n}\n\nexport interface Stored {\n  bytes: Uint8Array;\n  hashes?: Hashes;\n}\n\nexport interface Backend {\n  canSave(): Promise<boolean>;\n  resolve(dependencies: Dependencies): Promise<Dependencies<Resolved>>;\n  snapshot(dependencies: Dependencies<Hashable>): Promise<Snapshot>;\n  load(key: string): Promise<Stored | undefined>;\n  save(key: string, value: Uint8Array, check: {\n    /** Must still match `expected`. */\n    checked: Dependencies<Hashable>;\n    expected: Hashes;\n    /** Hashed now and rechecked on load. */\n    saved: Dependencies<Hashable>;\n  }): Promise<void>;\n}\n"]}

package/dist/vite/index.js

@@ -1,25 +1,14 @@
 import { relative, resolve, sep } from 'node:path';
 import * as disk from '../disk.js';
-import { ChangedDependenciesError, createStorage } from '../storage.js';
-import { dependencies, hashes, resolvedDependencies } from '../dependencies.js';
-import { confine, inside, OutsideRootError, resolveDependencies } from './resolve.js';
+import { createStorage } from '../storage.js';
+import { ChangedDependenciesError, dependencies, hashableDependencies, hashes, MissingDependencyError } from '../dependencies.js';
+import { confine, RequestError, resolveDependencies } from './resolve.js';
 import { assetUrl, publicPaths } from './manifest.js';
-class RequestError extends Error {
-    status;
-    constructor(status, message) {
-        super(message);
-        this.status = status;
-    }
-}
 function status(error) {
     if (error instanceof RequestError)
         return error.status;
     if (error instanceof ChangedDependenciesError)
         return 409;
-    if (error instanceof OutsideRootError)
-        return 403;
-    if (error instanceof TypeError || error instanceof URIError)
-        return 400;
     return 500;
 }
 function allowed(request) {
@@ -54,7 +43,7 @@ function parse(value) {
         throw new RequestError(400, 'Expected valid JSON');
     }
 }
-function validate(value, parser) {
+function parseRequest(value, parser) {
     try {
         return parser(value);
     }
@@ -64,20 +53,29 @@ function validate(value, parser) {
         throw new RequestError(400, error.message);
     }
 }
-function header(request, name) {
-    const value = request.headers[name];
-    if (typeof value !== 'string')
-        throw new RequestError(400, `Missing ${name} header`);
-    try {
-        return parse(decodeURIComponent(value));
-    }
-    catch (error) {
-        if (!(error instanceof URIError))
-            throw error;
-        throw new RequestError(400, 'Invalid encoded request header');
-    }
+/** A save body: a 4-byte big-endian metadata length, that much JSON metadata, then the cached bytes. */
+function upload(bytes) {
+    if (bytes.byteLength < 4)
+        throw new RequestError(400, 'Expected a metadata length');
+    const end = 4 + new DataView(bytes.buffer, bytes.byteOffset, 4).getUint32(0);
+    if (end > bytes.byteLength)
+        throw new RequestError(400, 'Truncated save metadata');
+    const metadata = parse(new TextDecoder().decode(bytes.subarray(4, end)));
+    if (typeof metadata !== 'object' || metadata === null || !('checked' in metadata) || !('expected' in metadata) || !('saved' in metadata)) {
+        throw new RequestError(400, 'Expected checked, expected, and saved');
+    }
+    return { metadata, value: bytes.subarray(end) };
+}
+/** The `dependencies` of a same-origin POST's JSON body. */
+async function posted(request) {
+    if (!allowed(request))
+        throw new RequestError(403, 'Cross-origin requests are forbidden');
+    const value = parse(new TextDecoder().decode(await body(request)));
+    if (typeof value !== 'object' || value === null || !('dependencies' in value))
+        throw new RequestError(400, 'Expected dependencies');
+    return value.dependencies;
 }
-function json(response, value) {
+function sendJson(response, value) {
     response.setHeader('Content-Type', 'application/json');
     response.end(JSON.stringify(value));
 }
@@ -85,25 +83,19 @@ async function respond(request, response, name, storage, server) {
     const root = server.config.root;
     response.setHeader('Cache-Control', 'no-store');
     if (name === '__vitecache' && request.method === 'GET') {
-        json(response, { vitecache: 1 });
+        sendJson(response, { vitecache: 1 });
         return;
     }
-    if ((name === '__vitecache/snapshot' || name === '__vitecache/resolve') && request.method === 'POST') {
-        if (!allowed(request))
-            throw new RequestError(403, 'Cross-origin requests are forbidden');
-        const value = parse(new TextDecoder().decode(await body(request)));
-        if (typeof value !== 'object' || value === null || !('dependencies' in value)) {
-            throw new RequestError(400, 'Expected dependencies');
-        }
-        if (name === '__vitecache/resolve') {
-            const deps = validate(value.dependencies, dependencies);
-            const origin = `${server.config.server.https ? 'https' : 'http'}://${request.headers.host}`;
-            json(response, { dependencies: await resolveDependencies(server, deps, origin) });
-            return;
-        }
-        const deps = validate(value.dependencies, resolvedDependencies);
+    if (name === '__vitecache/resolve' && request.method === 'POST') {
+        const deps = parseRequest(await posted(request), dependencies);
+        const origin = `${server.config.server.https ? 'https' : 'http'}://${request.headers.host}`;
+        sendJson(response, { dependencies: await resolveDependencies(server, deps, origin) });
+        return;
+    }
+    if (name === '__vitecache/snapshot' && request.method === 'POST') {
+        const deps = parseRequest(await posted(request), hashableDependencies);
         await confine(root, deps);
-        json(response, { hashes: await storage.snapshot(deps) });
+        sendJson(response, await storage.snapshot(deps));
         return;
     }
     if (!/^[a-f0-9]{64}\.bin$/.test(name)) {
@@ -115,34 +107,47 @@ async function respond(request, response, name, storage, server) {
     if (request.method === 'PUT') {
         if (!allowed(request))
             throw new RequestError(403, 'Cross-origin requests are forbidden');
-        const deps = validate(header(request, 'x-vitecache-dependencies'), resolvedDependencies);
-        const expected = validate(header(request, 'x-vitecache-hashes'), hashes);
-        await confine(root, deps);
-        await storage.save(key, await body(request), deps, expected);
+        const { metadata, value } = upload(await body(request));
+        const checked = parseRequest(metadata.checked, hashableDependencies);
+        const expected = parseRequest(metadata.expected, hashes);
+        const saved = parseRequest(metadata.saved, hashableDependencies);
+        await confine(root, checked);
+        await confine(root, saved);
+        await storage.save(key, value, { checked, expected, saved });
         response.statusCode = 204;
         response.end();
         return;
     }
-    if (request.method !== 'GET' && request.method !== 'HEAD') {
+    if (request.method !== 'GET') {
         response.statusCode = 405;
-        response.setHeader('Allow', 'GET, HEAD, PUT');
+        response.setHeader('Allow', 'GET, PUT');
         response.end();
         return;
     }
-    const stored = await storage.load(key, true);
+    const stored = await storage.load(key);
     if (stored === undefined) {
-        response.statusCode = 404;
+        // Browsers log every 404 fetch as an error, and a miss is an expected answer.
+        response.statusCode = 204;
+        response.end();
+        return;
+    }
+    // Browsers keep the bytes and revalidate them on every load, so an unchanged entry costs a 304 rather than a download.
+    response.setHeader('Cache-Control', 'no-cache');
+    const tag = `"${stored.tag}"`;
+    response.setHeader('ETag', tag);
+    response.setHeader('X-Vitecache-Dependencies', encodeURIComponent(JSON.stringify(stored.hashes)));
+    if (request.headers['if-none-match'] === tag) {
+        response.statusCode = 304;
         response.end();
         return;
     }
     response.setHeader('Content-Type', 'application/octet-stream');
     response.setHeader('Content-Length', stored.bytes.byteLength);
-    response.setHeader('X-Vitecache-Dependencies', encodeURIComponent(JSON.stringify(stored.hashes)));
-    response.end(request.method === 'HEAD' ? undefined : stored.bytes);
+    response.end(stored.bytes);
 }
 /** Persist and validate entries in development; preserve asset URL mappings in production builds. */
 export function vitecache(options = {}) {
-    let resolved;
+    let state;
     return {
         name: 'vitecache',
         enforce: 'post',
@@ -151,12 +156,12 @@ export function vitecache(options = {}) {
                 throw new Error('vitecache requires Vite publicDir');
             const { root, directory } = disk.location({ root: config.root, ...options });
             const path = relative(config.publicDir, directory);
-            if (!path || !inside(config.publicDir, directory)) {
+            if (!path || !disk.inside(config.publicDir, directory)) {
                 throw new Error('vitecache basePath must be a directory inside Vite publicDir');
             }
             const base = new URL(config.base, 'http://vitecache').pathname.replace(/\/$/, '');
-            resolved = {
-                backend: createStorage({ root, ...options }),
+            state = {
+                storage: createStorage({ root, ...options }),
                 root,
                 directory,
                 config,
@@ -166,10 +171,10 @@ export function vitecache(options = {}) {
             await disk.ignore(root, directory);
         },
         async generateBundle(_options, bundle) {
-            const storage = resolved;
-            if (!storage)
+            const resolved = state;
+            if (!resolved)
                 throw new Error('vitecache configuration was not resolved');
-            const paths = new Map(Object.entries(await publicPaths(storage.config, storage.directory)));
+            const paths = new Map(Object.entries(await publicPaths(resolved.config, resolved.directory)));
             for (const asset of Object.values(bundle)) {
                 if (asset.type !== 'asset')
                     continue;
@@ -179,25 +184,30 @@ export function vitecache(options = {}) {
                 const original = originals[0];
                 if (!original)
                     continue;
-                const file = relative(storage.root, resolve(storage.root, original));
-                if (!inside(storage.root, resolve(storage.root, original)))
+                const file = resolve(resolved.root, original);
+                if (!disk.inside(resolved.root, file))
                     continue;
-                paths.set(assetUrl(asset.fileName), file.split(sep).join('/'));
+                paths.set(assetUrl(asset.fileName), relative(resolved.root, file).split(sep).join('/'));
             }
-            const manifest = { paths: Object.fromEntries(paths), root: '../'.repeat(storage.cachePath.split('/').length + 1) };
-            this.emitFile({ type: 'asset', fileName: `${storage.cachePath}/__vitecache/paths.json`, source: JSON.stringify(manifest) });
+            const manifest = { paths: Object.fromEntries(paths), root: '../'.repeat(resolved.cachePath.split('/').length + 1) };
+            this.emitFile({ type: 'asset', fileName: `${resolved.cachePath}/__vitecache/paths.json`, source: JSON.stringify(manifest) });
         },
         configureServer(server) {
-            const storage = resolved;
-            if (!storage)
+            const resolved = state;
+            if (!resolved)
                 throw new Error('vitecache configuration was not resolved');
             server.middlewares.use((request, response, next) => {
                 const path = new URL(request.url ?? '/', 'http://vitecache').pathname;
-                if (!path.startsWith(storage.prefix)) {
+                if (!path.startsWith(resolved.prefix)) {
                     next();
                     return;
                 }
-                void respond(request, response, path.slice(storage.prefix.length), storage.backend, server).catch((error) => {
+                void respond(request, response, path.slice(resolved.prefix.length), resolved.storage, server).catch((error) => {
+                    // A missing dependency is an expected answer, as in a snapshot: a body, and no error status for browsers to log.
+                    if (error instanceof MissingDependencyError) {
+                        sendJson(response, { status: 'missing', message: error.message });
+                        return;
+                    }
                     response.statusCode = status(error);
                     response.setHeader('Content-Type', 'text/plain');
                     response.end(error instanceof Error ? error.message : 'vitecache request failed');