@vltpkg/package-info 1.0.9 → 1.1.0

package/dist/index.d.ts

@@ -7,6 +7,20 @@ import type { Pool } from '@vltpkg/tar';
 import type { Integrity, Manifest, Packument } from '@vltpkg/types';
 import { Monorepo } from '@vltpkg/workspaces';
 export declare const delimiter = "~";
+/**
+ * Accept header for packument requests. Prefers vlt's abbreviated
+ * packument and falls back to the full one on registries that do not
+ * know the type. See `PackageInfoClient.#fetchPackument`.
+ *
+ * The trailing wildcard range carries an explicit `q=0.1` so that it stays
+ * below `application/json`. A media range with no `q` defaults to `q=1.0`
+ * (RFC 9110 12.5.1), which on a registry that negotiates strictly by
+ * quality would let an unrelated representation — npm's corgi among them
+ * — outrank the full packument and drop `license`. The wildcard is kept
+ * only so a registry that rejects what it cannot satisfy exactly still
+ * has something to match.
+ */
+export declare const PACKUMENT_ACCEPT = "application/vnd.vlt.packument-v1+json; q=1.0, application/json; q=0.8, */*; q=0.1";
 export type Resolution = {
     resolved: string;
     integrity?: Integrity;

package/dist/index.js

@@ -3,6 +3,9 @@ import { clone, resolve as gitResolve, revs } from '@vltpkg/git';
 import { logRequest } from '@vltpkg/output';
 import { PackageJson } from '@vltpkg/package-json';
 import { pickManifest } from '@vltpkg/pick-manifest';
+// subpath import: keeps the lazy `import('@vltpkg/registry-client')`
+// below from becoming an eager dependency on the whole client.
+import { registryErrorMessage } from '@vltpkg/registry-client/registry-error';
 import { Spec } from '@vltpkg/spec';
 import { asPackument } from '@vltpkg/types';
 import ssri from 'ssri';
@@ -17,6 +20,20 @@ import { rename } from "./rename.js";
 const debug = debuglog('vlt');
 const xdg = new XDG('vlt');
 export const delimiter = '~';
+/**
+ * Accept header for packument requests. Prefers vlt's abbreviated
+ * packument and falls back to the full one on registries that do not
+ * know the type. See `PackageInfoClient.#fetchPackument`.
+ *
+ * The trailing wildcard range carries an explicit `q=0.1` so that it stays
+ * below `application/json`. A media range with no `q` defaults to `q=1.0`
+ * (RFC 9110 12.5.1), which on a registry that negotiates strictly by
+ * quality would let an unrelated representation — npm's corgi among them
+ * — outrank the full packument and drop `license`. The wildcard is kept
+ * only so a registry that rejects what it cannot satisfy exactly still
+ * has something to match.
+ */
+export const PACKUMENT_ACCEPT = 'application/vnd.vlt.packument-v1+json; q=1.0, application/json; q=0.8, */*; q=0.1';
 // the maximum duration of a manifest cache file
 const manifestCacheMaxAge = 5 * 60 * 1000;
 /**
@@ -26,6 +43,15 @@ const manifestCacheMaxAge = 5 * 60 * 1000;
 const noRegistryError = (spec) => error('No registry configured to resolve this spec. Set "registry" in ' +
     'vlt.json, pass --registry, or run `vlt login --registry=<url>`. ' +
     'See https://docs.vlt.sh/cli', { code: 'ECONFIG', spec });
+/**
+ * A selector that can point at a different version tomorrow: a dist tag,
+ * or a range matching anything (`*`, empty string). Manifest results for
+ * these are not cached to disk, and packument requests for them force a
+ * revalidation of the registry client's cache entry.
+ *
+ * Takes a *final* spec (`spec.final`), same as `pickManifest` sees.
+ */
+const isMovingSelector = (f) => !!(f.distTag || f.range?.isAny);
 export class PackageInfoClient {
     #registryClient;
     #projectRoot;
@@ -39,7 +65,9 @@ export class PackageInfoClient {
     #cachePath;
     // In-flight coalescing key is `${registry}${name}` — no representation
     // component. Safe only because every caller requests the same full
-    // packument (see #fetchPackument).
+    // packument (see #fetchPackument). The one thing that does vary per
+    // caller is forceRevalidate, so record it and let a moving selector
+    // reuse a forced promise but never a non-forced one (see packument()).
     #packumentPromises = new Map();
     // unique temp file names for atomic manifest cache writes
     #manifestWriteRandom = randomBytes(6).toString('hex');
@@ -159,7 +187,7 @@ export class PackageInfoClient {
                         ...(useCache === false ? { useCache } : {}),
                     });
                     if (response.statusCode !== 200) {
-                        throw this.#resolveError(spec, options, `Registry returned HTTP ${response.statusCode} when ` +
+                        throw this.#resolveError(spec, options, `${registryErrorMessage(response)} when ` +
                             `fetching the tarball for ${spec}. The resolved version ` +
                             `may have been unpublished, or the registry may be ` +
                             `misconfigured or unreachable.`, {
@@ -227,7 +255,7 @@ export class PackageInfoClient {
             case 'remote': {
                 const response = await (await this.getRegistryClient()).request(r.resolved);
                 if (response.statusCode !== 200) {
-                    throw this.#resolveError(spec, options, 'failed to fetch remote tarball', {
+                    throw this.#resolveError(spec, options, `failed to fetch remote tarball: ${registryErrorMessage(response)}`, {
                         url: r.resolved,
                         response,
                     });
@@ -333,11 +361,9 @@ export class PackageInfoClient {
         if (options.before) {
             return;
         }
-        // if the final resolved spec is either a dist tag or something that
-        // matches any range (such as a semver range of `*` or empty string)
-        // then we skip caching
+        // a moving selector's result is variable, so don't cache it
         const f = spec.final;
-        if (f.distTag || f.range?.isAny) {
+        if (isMovingSelector(f)) {
             return;
         }
         const key = this.#manifestCacheKey(f, options);
@@ -398,7 +424,7 @@ export class PackageInfoClient {
                         ...(useCache === false ? { useCache } : {}),
                     });
                     if (response.statusCode !== 200) {
-                        throw this.#resolveError(spec, options, `Registry returned HTTP ${response.statusCode} when ` +
+                        throw this.#resolveError(spec, options, `${registryErrorMessage(response)} when ` +
                             `fetching the tarball for ${spec} at ${tarball}. The ` +
                             `version may have been unpublished, or the registry may ` +
                             `be misconfigured or unreachable.`, { response, url: tarball });
@@ -478,7 +504,7 @@ export class PackageInfoClient {
                 }
                 const response = await (await this.getRegistryClient()).request(remoteURL);
                 if (response.statusCode !== 200) {
-                    throw this.#resolveError(spec, options, 'failed to fetch URL', { response, url: remoteURL });
+                    throw this.#resolveError(spec, options, `failed to fetch URL: ${registryErrorMessage(response)}`, { response, url: remoteURL });
                 }
                 return response.buffer();
             }
@@ -577,7 +603,7 @@ export class PackageInfoClient {
                 return await this.#tmpdir(async (dir) => {
                     const response = await (await this.getRegistryClient()).request(remoteURL);
                     if (response.statusCode !== 200) {
-                        throw this.#resolveError(s, options, 'failed to fetch URL', { response, url: remoteURL });
+                        throw this.#resolveError(s, options, `failed to fetch URL: ${registryErrorMessage(response)}`, { response, url: remoteURL });
                     }
                     const buf = response.buffer();
                     // Compute integrity for remote/git-with-tarball deps
@@ -660,52 +686,66 @@ export class PackageInfoClient {
                     throw noRegistryError(spec);
                 // Coalescing key has no representation component (see #fetchPackument).
                 const packumentKey = `${registry}${name}`;
+                const forced = isMovingSelector(f);
                 const inflight = this.#packumentPromises.get(packumentKey);
-                if (inflight)
-                    return inflight;
+                // a moving selector must not ride along on a non-forced request:
+                // that one can settle to a fresh-but-stale cache hit, which is
+                // exactly what forceRevalidate exists to avoid. the other
+                // direction is fine -- a forced result is never staler.
+                // costs at most one extra concurrent GET for the same packument
+                // when both shapes are asked for at once.
+                if (inflight && (!forced || inflight.forced))
+                    return inflight.promise;
                 const pakuURL = new URL(name, registry);
                 const promise = this.#fetchPackument(spec, options, pakuURL);
-                this.#packumentPromises.set(packumentKey, promise);
-                // Clean up once settled so we don't leak memory.
+                const record = { promise, forced };
+                this.#packumentPromises.set(packumentKey, record);
+                // Clean up once settled so we don't leak memory, unless a forced
+                // request has since taken the slot over.
                 // Use .then/.catch instead of .finally to avoid creating
                 // an unhandled rejection from the derived promise.
-                promise.then(() => this.#packumentPromises.delete(packumentKey), () => this.#packumentPromises.delete(packumentKey));
+                const clear = () => {
+                    if (this.#packumentPromises.get(packumentKey) === record) {
+                        this.#packumentPromises.delete(packumentKey);
+                    }
+                };
+                promise.then(clear, clear);
                 return promise;
             }
         }
     }
     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.
+        // Request vlt's abbreviated packument, falling back to the full one:
+        //   accept: application/vnd.vlt.packument-v1+json; q=1.0,
+        //           application/json; q=0.8, */*; q=0.1
         //
-        // 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).
+        // npm's corgi (`application/vnd.npm.install-v1+json`) is never
+        // requested. The version entry returned here becomes `node.manifest`
+        // and is persisted to the hidden lockfile, and corgi drops `license`
+        // and `time`, so graph queries like `[license=MPL-2.0]` could not
+        // match a field that was never stored (shipped in 1.0.0-rc.33 via
+        // #1692, reverted in #1707). The vlt type guarantees both, and a
+        // registry that does not know it ignores it and serves the full
+        // packument, so the graph gets every field it relies on either way.
+        // The one shape difference is `scripts`, which the vlt type replaces
+        // with `hasInstallScript`; reify reads the extracted package.json in
+        // that case.
         //
-        // 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.
+        // The RegistryClient disk cache key is method + URL only, so every
+        // packument request must use this same accept header, and the SWR
+        // revalidation child re-requests the representation it was given.
         const response = await (await this.getRegistryClient()).request(pakuURL, {
-            headers: { accept: 'application/json' },
+            headers: { accept: PACKUMENT_ACCEPT },
             ...(useCache === false ? { useCache } : {}),
+            // costs a conditional GET per moving selector on an otherwise warm
+            // cache, install included. 304s are cheap but not free; the
+            // alternative is serving a dist tag that moved (#1656).
+            ...(isMovingSelector(spec.final) ?
+                { forceRevalidate: true }
+                : {}),
         });
         if (response.statusCode !== 200) {
-            throw this.#resolveError(spec, options, 'failed to fetch packument', {
+            throw this.#resolveError(spec, options, `failed to fetch packument: ${registryErrorMessage(response)}`, {
                 url: pakuURL,
                 response,
             });

package/package.json

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