@vltpkg/package-info 1.0.1 → 1.0.3

package/dist/index.d.ts

@@ -1,10 +1,9 @@
 import { PackageJson } from '@vltpkg/package-json';
 import type { PickManifestOptions } from '@vltpkg/pick-manifest';
-import type { RegistryClientOptions, RegistryClientRequestOptions } from '@vltpkg/registry-client';
-import { RegistryClient } from '@vltpkg/registry-client';
+import type { RegistryClient, RegistryClientOptions, RegistryClientRequestOptions } from '@vltpkg/registry-client';
 import type { SpecOptions } from '@vltpkg/spec';
 import { Spec } from '@vltpkg/spec';
-import { Pool } from '@vltpkg/tar';
+import type { Pool } from '@vltpkg/tar';
 import type { Integrity, Manifest, Packument } from '@vltpkg/types';
 import { Monorepo } from '@vltpkg/workspaces';
 export declare const delimiter = "~";
@@ -45,8 +44,8 @@ export declare class PackageInfoClient {
     options: PackageInfoClientOptions;
     packageJson: PackageJson;
     monorepo?: Monorepo;
-    get registryClient(): RegistryClient;
-    get tarPool(): Pool;
+    getRegistryClient(): Promise<RegistryClient>;
+    getTarPool(): Promise<Pool>;
     constructor(options?: PackageInfoClientOptions);
     extract(spec: Spec | string, target: string, options?: PackageInfoClientExtractOptions): Promise<Resolution>;
     /**

package/dist/index.js

@@ -2,9 +2,7 @@ import { error } from '@vltpkg/error-cause';
 import { clone, resolve as gitResolve, revs } from '@vltpkg/git';
 import { PackageJson } from '@vltpkg/package-json';
 import { pickManifest } from '@vltpkg/pick-manifest';
-import { RegistryClient } from '@vltpkg/registry-client';
 import { Spec } from '@vltpkg/spec';
-import { Pool } from '@vltpkg/tar';
 import { asPackument } from '@vltpkg/types';
 import ssri from 'ssri';
 import { Monorepo } from '@vltpkg/workspaces';
@@ -36,17 +34,39 @@ export class PackageInfoClient {
     #trustedIntegrities = new Map();
     #manifestCacheMinAge = Date.now() - manifestCacheMaxAge;
     #cachePath;
+    // In-flight coalescing key is `${registry}${name}` — no representation
+    // component. Safe only because every caller requests the same full
+    // packument (see #fetchPackument).
     #packumentPromises = new Map();
-    get registryClient() {
-        if (!this.#registryClient) {
-            this.#registryClient = new RegistryClient(this.options);
-        }
-        return this.#registryClient;
+    // unique temp file names for atomic manifest cache writes
+    #manifestWriteRandom = randomBytes(6).toString('hex');
+    #manifestWriteCount = 0;
+    // cache paths already written this run. manifest() is called many
+    // times for the same cache key per install and content for a given
+    // path is deterministic within a run, so only the first write is
+    // needed. entries are removed when the on-disk file is invalidated
+    // so the refreshed manifest can be written again.
+    #manifestWritePaths = new Set();
+    #registryClientPromise;
+    #tarPoolPromise;
+    async getRegistryClient() {
+        if (this.#registryClient)
+            return this.#registryClient;
+        this.#registryClientPromise ??=
+            import('@vltpkg/registry-client').then(({ RegistryClient }) => {
+                this.#registryClient = new RegistryClient(this.options);
+                return this.#registryClient;
+            });
+        return this.#registryClientPromise;
     }
-    get tarPool() {
-        if (!this.#tarPool)
+    async getTarPool() {
+        if (this.#tarPool)
+            return this.#tarPool;
+        this.#tarPoolPromise ??= import('@vltpkg/tar').then(({ Pool }) => {
             this.#tarPool = new Pool();
-        return this.#tarPool;
+            return this.#tarPool;
+        });
+        return this.#tarPoolPromise;
     }
     constructor(options = {}) {
         this.options = options;
@@ -111,7 +131,7 @@ export class PackageInfoClient {
             case 'registry': {
                 const fetchTarball = async (useCache) => {
                     const trustIntegrity = this.#trustedIntegrities.get(r.resolved) === r.integrity;
-                    const response = await this.registryClient.request(r.resolved, {
+                    const response = await (await this.getRegistryClient()).request(r.resolved, {
                         integrity: r.integrity,
                         trustIntegrity,
                         ...(useCache === false ? { useCache } : {}),
@@ -131,20 +151,17 @@ export class PackageInfoClient {
                         this.#trustedIntegrities.set(r.resolved, response.integrity);
                     }
                     const buf = response.buffer();
-                    // Verify tarball integrity against the manifest's
-                    // dist.integrity. This is a supply-chain security measure:
-                    // the registry may not validate integrity, so we do it
-                    // client-side on every fresh download. Skip when integrity
-                    // came from lockfile/cache (it was already verified on
-                    // first install).
-                    /* c8 ignore start - defense-in-depth: registry client's
-                     * checkIntegrity() usually catches mismatches first since
-                     * it checks the same gzip bytes. This fires only when the
-                     * registry client check is skipped (trustIntegrity=true). */
-                    if (r.integrity && !fromLockfile) {
+                    // Verify network-delivered tarball bytes against dist.integrity.
+                    // Skip cache-served bodies: they were verified on the fetch that
+                    // populated the cache, and cache-unzip rewrites them un-gzipped
+                    // so the gzip-hash can never match. Skip lockfile-sourced
+                    // integrity: it was verified on first install.
+                    if (r.integrity && !fromLockfile && !response.fromCache) {
                         const hash = createHash('sha512');
                         hash.update(buf);
                         const computed = `sha512-${hash.digest('base64')}`;
+                        /* c8 ignore start - defense-in-depth: registry client's
+                         * checkIntegrity() usually catches mismatches first. */
                         if (computed !== r.integrity) {
                             throw error('Tarball integrity check failed', {
                                 code: 'EINTEGRITY',
@@ -154,8 +171,8 @@ export class PackageInfoClient {
                                 found: computed,
                             });
                         }
+                        /* c8 ignore stop */
                     }
-                    /* c8 ignore stop */
                     return buf;
                 };
                 let buf;
@@ -178,7 +195,7 @@ export class PackageInfoClient {
                     }
                 }
                 try {
-                    await this.tarPool.unpack(buf, target);
+                    await (await this.getTarPool()).unpack(buf, target);
                 }
                 catch (er) {
                     throw this.#resolveError(spec, options, 'tar unpack failed', { cause: er });
@@ -186,7 +203,7 @@ export class PackageInfoClient {
                 return r;
             }
             case 'remote': {
-                const response = await this.registryClient.request(r.resolved);
+                const response = await (await this.getRegistryClient()).request(r.resolved);
                 if (response.statusCode !== 200) {
                     throw this.#resolveError(spec, options, 'failed to fetch remote tarball', {
                         url: r.resolved,
@@ -209,7 +226,7 @@ export class PackageInfoClient {
                 }
                 r.integrity = computed;
                 try {
-                    await this.tarPool.unpack(buf, target);
+                    await (await this.getTarPool()).unpack(buf, target);
                 }
                 catch (er) {
                     throw this.#resolveError(spec, options, 'remote tar unpack failed', { cause: er });
@@ -227,7 +244,7 @@ export class PackageInfoClient {
                 const st = await stat(path);
                 if (st.isFile()) {
                     try {
-                        await this.tarPool.unpack(await this.tarball(spec, options), target);
+                        await (await this.getTarPool()).unpack(await this.tarball(spec, options), target);
                     }
                     catch (er) {
                         throw this.#resolveError(spec, options, 'tar unpack failed', { cause: er });
@@ -304,6 +321,35 @@ export class PackageInfoClient {
         const key = this.#manifestCacheKey(f, options);
         return pathResolve(this.#cachePath, 'package-info', key);
     }
+    /**
+     * Write a manifest cache file atomically (write to a temp file in
+     * the same directory, then rename over the destination) so that
+     * concurrent readers never observe a partially written manifest.
+     * Freshness is tracked via the resulting file's mtime.
+     */
+    async #writeManifestCache(cachePath, json) {
+        const tmp = `${cachePath}.${this.#manifestWriteRandom}.${this.#manifestWriteCount++}`;
+        try {
+            try {
+                await writeFile(tmp, json, 'utf8');
+            }
+            catch (err) {
+                // in case the cache directory doesn't exist
+                // just create it and retry
+                if (!(err instanceof Error &&
+                    'code' in err &&
+                    err.code === 'ENOENT')) {
+                    throw err;
+                }
+                await mkdir(dirname(cachePath), { recursive: true });
+                await writeFile(tmp, json, 'utf8');
+            }
+            await rename(tmp, cachePath);
+        }
+        catch {
+            // failing to write the manifest cache is not an install failure
+        }
+    }
     async tarball(spec, options = {}) {
         if (typeof spec === 'string')
             spec = Spec.parse(spec, this.options);
@@ -323,7 +369,7 @@ export class PackageInfoClient {
                 }
                 const fetchTarball = async (useCache) => {
                     const trustIntegrity = this.#trustedIntegrities.get(tarball) === integrity;
-                    const response = await this.registryClient.request(tarball, {
+                    const response = await (await this.getRegistryClient()).request(tarball, {
                         ...options,
                         integrity,
                         trustIntegrity,
@@ -342,13 +388,12 @@ export class PackageInfoClient {
                         this.#trustedIntegrities.set(tarball, response.integrity);
                     }
                     const buf = response.buffer();
-                    // Verify tarball integrity against the manifest's
-                    // dist.integrity.
-                    /* c8 ignore start - defense-in-depth (see extract) */
-                    if (integrity) {
+                    // Same as extract(): only hash network-delivered bodies.
+                    if (integrity && !response.fromCache) {
                         const hash = createHash('sha512');
                         hash.update(buf);
                         const computed = `sha512-${hash.digest('base64')}`;
+                        /* c8 ignore start - defense-in-depth (see extract) */
                         if (computed !== integrity) {
                             throw error('Tarball integrity check failed', {
                                 code: 'EINTEGRITY',
@@ -358,8 +403,8 @@ export class PackageInfoClient {
                                 found: computed,
                             });
                         }
+                        /* c8 ignore stop */
                     }
-                    /* c8 ignore stop */
                     return buf;
                 };
                 try {
@@ -409,7 +454,7 @@ export class PackageInfoClient {
                 if (!remoteURL) {
                     throw this.#resolveError(spec, options);
                 }
-                const response = await this.registryClient.request(remoteURL);
+                const response = await (await this.getRegistryClient()).request(remoteURL);
                 if (response.statusCode !== 200) {
                     throw this.#resolveError(spec, options, 'failed to fetch URL', { response, url: remoteURL });
                 }
@@ -450,15 +495,21 @@ export class PackageInfoClient {
                 const cachePath = this._manifestCachePath(spec, options);
                 if (cachePath) {
                     try {
-                        // Cache file exists, read and return it
-                        const cached = await readFile(cachePath, 'utf8');
+                        // Cache file exists, read and return it. Freshness is
+                        // tracked via the file's mtime, so the file content is
+                        // exactly the manifest and can be returned as parsed.
+                        const [st, cached] = await Promise.all([
+                            stat(cachePath),
+                            readFile(cachePath, 'utf8'),
+                        ]);
                         const json = JSON.parse(cached);
-                        // retrieve timestamp to check if cache is still valid
-                        const timestamp = json.__VLT_MANIFEST_CACHE_TIMESTAMP;
-                        delete json.__VLT_MANIFEST_CACHE_TIMESTAMP;
-                        // removes the cache file if older than its maximum age
-                        if (timestamp != null &&
-                            timestamp < this.#manifestCacheMinAge) {
+                        // removes the cache file if older than its maximum age.
+                        // entries written by older clients embed a timestamp in
+                        // the manifest itself; treat those as expired so they get
+                        // rewritten in the mtime-tracked format.
+                        if (st.mtimeMs < this.#manifestCacheMinAge ||
+                            json.__VLT_MANIFEST_CACHE_TIMESTAMP !== undefined) {
+                            this.#manifestWritePaths.delete(cachePath);
                             void unlink(cachePath).catch(() => { });
                             throw new Error('manifest cache expired');
                         }
@@ -471,27 +522,12 @@ export class PackageInfoClient {
                 const mani = pickManifest(await this.packument(f, options), spec, options);
                 if (!mani)
                     throw this.#resolveError(spec, options);
-                // Cache the manifest data
-                if (cachePath) {
-                    const json = JSON.stringify({
-                        ...mani,
-                        // append a timestamp to the manifest so that we can quickly
-                        // check if the cache is still valid when loading it
-                        __VLT_MANIFEST_CACHE_TIMESTAMP: Date.now(),
-                    });
-                    void writeFile(cachePath, json, 'utf8').catch((err) => {
-                        // in case the cache directory doesn't exist
-                        // just create it and retry
-                        if (err instanceof Error &&
-                            'code' in err &&
-                            err.code === 'ENOENT') {
-                            void mkdir(dirname(cachePath), {
-                                recursive: true,
-                            }).then(() => {
-                                void writeFile(cachePath, json, 'utf8');
-                            });
-                        }
-                    });
+                // Cache the manifest data. Skip paths already written this
+                // run — first writer wins, avoiding duplicate serialization
+                // and racing writers for the same path.
+                if (cachePath && !this.#manifestWritePaths.has(cachePath)) {
+                    this.#manifestWritePaths.add(cachePath);
+                    void this.#writeManifestCache(cachePath, JSON.stringify(mani));
                 }
                 return mani;
             }
@@ -505,7 +541,7 @@ export class PackageInfoClient {
                         await clone(gitRemote, gitCommittish, dir, { spec: s });
                         const { path } = gitSelectorParsed ?? {};
                         const pkgDir = path !== undefined ? pathResolve(dir, path) : dir;
-                        return this.packageJson.read(pkgDir);
+                        return this.#readExtracted(pkgDir, s, options);
                     });
                 }
                 // fallthrough to remote
@@ -517,7 +553,7 @@ export class PackageInfoClient {
                 }
                 const s = spec;
                 return await this.#tmpdir(async (dir) => {
-                    const response = await this.registryClient.request(remoteURL);
+                    const response = await (await this.getRegistryClient()).request(remoteURL);
                     if (response.statusCode !== 200) {
                         throw this.#resolveError(s, options, 'failed to fetch URL', { response, url: remoteURL });
                     }
@@ -527,13 +563,13 @@ export class PackageInfoClient {
                         .fromData(buf, { algorithms: ['sha512'] })
                         .toString();
                     try {
-                        await this.tarPool.unpack(buf, dir);
+                        await (await this.getTarPool()).unpack(buf, dir);
                     }
                     catch (er) {
                         throw this.#resolveError(s, options, 'tar unpack failed', { cause: er });
                     }
                     // return manifest with computed integrity
-                    const mani = this.packageJson.read(dir);
+                    const mani = this.#readExtracted(dir, s, options);
                     mani.dist = { integrity: computed };
                     return mani;
                 });
@@ -550,12 +586,12 @@ export class PackageInfoClient {
                 const s = spec;
                 return await this.#tmpdir(async (dir) => {
                     try {
-                        await this.tarPool.unpack(await readFile(path), dir);
+                        await (await this.getTarPool()).unpack(await readFile(path), dir);
                     }
                     catch (er) {
                         throw this.#resolveError(s, options, 'tar unpack failed', { cause: er });
                     }
-                    return this.packageJson.read(dir);
+                    return this.#readExtracted(dir, s, options);
                 });
             }
             case 'workspace': {
@@ -600,6 +636,7 @@ export class PackageInfoClient {
                 const { registry, name } = f;
                 if (!registry)
                     throw noRegistryError(spec);
+                // Coalescing key has no representation component (see #fetchPackument).
                 const packumentKey = `${registry}${name}`;
                 const inflight = this.#packumentPromises.get(packumentKey);
                 if (inflight)
@@ -615,9 +652,35 @@ export class PackageInfoClient {
             }
         }
     }
-    async #fetchPackument(spec, options, pakuURL) {
-        const response = await this.registryClient.request(pakuURL, {
+    async #fetchPackument(spec, options, pakuURL, useCache) {
+        // Always request the full packument (`application/json`), never the
+        // abbreviated "corgi" form:
+        //   accept: application/vnd.npm.install-v1+json; q=1.0,
+        //           application/json; q=0.8, */*
+        //
+        // Corgi is smaller (~−41% packument bytes, est. 1–3s on clean installs)
+        // but is disabled for two load-bearing reasons:
+        //
+        // 1. Metadata loss reaches the lockfile. The version entry returned
+        //    here is `node.manifest` and is persisted to vlt-lock.json / the
+        //    hidden lockfile. Corgi drops `license` (also `time`, `readme`,
+        //    `maintainers`, `_rev`, `scripts`), so graph queries like
+        //    `[license=MPL-2.0]` cannot match a field that was never stored.
+        //    Shipped in 1.0.0-rc.33 via #1692 (8ba2b10c); 24 false-positive
+        //    edges in the dependency-check job on #1704
+        //    (`@resvg/resvg-wasm@2.6.2` MPL-2.0 in package.json, blank in the
+        //    stored graph); isolated in #1705; reverted in #1707.
+        //
+        // 2. The RegistryClient disk cache key is method + URL only — no
+        //    accept, no Vary — so a full-packument request can be served a
+        //    cached abbreviated body (and vice versa).
+        //
+        // To revisit: put the requested representation on both the disk-cache
+        // key and the in-flight coalescing key, and have the SWR child
+        // (cache-revalidate / revalidate) re-request the same representation.
+        const response = await (await this.getRegistryClient()).request(pakuURL, {
             headers: { accept: 'application/json' },
+            ...(useCache === false ? { useCache } : {}),
         });
         if (response.statusCode !== 200) {
             throw this.#resolveError(spec, options, 'failed to fetch packument', {
@@ -625,7 +688,15 @@ export class PackageInfoClient {
                 response,
             });
         }
-        return response.json();
+        try {
+            return response.json();
+        }
+        catch (er) {
+            if (useCache !== false) {
+                return this.#fetchPackument(spec, options, pakuURL, false);
+            }
+            throw er;
+        }
     }
     async resolve(spec, options = {}) {
         const memoKey = String(spec);
@@ -723,6 +794,19 @@ export class PackageInfoClient {
             }
         }
     }
+    /**
+     * Read the manifest out of a directory we cloned or unpacked. Failures are
+     * labeled with the spec, because the internal directory says nothing about
+     * which dependency is at fault.
+     */
+    #readExtracted(dir, spec, options) {
+        try {
+            return this.packageJson.read(dir);
+        }
+        catch (er) {
+            throw this.#resolveError(spec, options, 'invalid package manifest', { cause: er });
+        }
+    }
     async #tmpdir(fn) {
         const p = `package-info/${randomBytes(6).toString('hex')}`;
         const dir = xdg.runtime(p);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/package-info",
   "description": "Resolve and fetch package metadata and tarballs",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -13,16 +13,16 @@
     "url": "http://vlt.sh"
   },
   "dependencies": {
-    "@vltpkg/error-cause": "1.0.1",
-    "@vltpkg/git": "1.0.1",
-    "@vltpkg/package-json": "1.0.1",
-    "@vltpkg/pick-manifest": "1.0.1",
-    "@vltpkg/registry-client": "1.0.1",
-    "@vltpkg/spec": "1.0.1",
-    "@vltpkg/tar": "1.0.1",
-    "@vltpkg/types": "1.0.1",
-    "@vltpkg/workspaces": "1.0.1",
-    "@vltpkg/xdg": "1.0.1",
+    "@vltpkg/error-cause": "1.0.3",
+    "@vltpkg/git": "1.0.3",
+    "@vltpkg/package-json": "1.0.3",
+    "@vltpkg/pick-manifest": "1.0.3",
+    "@vltpkg/registry-client": "1.0.3",
+    "@vltpkg/spec": "1.0.3",
+    "@vltpkg/tar": "1.0.3",
+    "@vltpkg/types": "1.0.3",
+    "@vltpkg/workspaces": "1.0.3",
+    "@vltpkg/xdg": "1.0.3",
     "ssri": "^13.0.0",
     "tar": "^7.5.2"
   },
@@ -31,8 +31,8 @@
     "@types/node": "^22.19.2",
     "@types/pacote": "^11.1.8",
     "@vltpkg/benchmark": "0.0.0",
-    "@vltpkg/cache-unzip": "1.0.1",
-    "@vltpkg/vlt-json": "1.0.1",
+    "@vltpkg/cache-unzip": "1.0.3",
+    "@vltpkg/vlt-json": "1.0.3",
     "eslint": "^9.39.1",
     "pacote": "^21.0.4",
     "prettier": "^3.7.4",