feat(npm): rebuild a missing packument and serve the abbreviated form to installers by devitway · Pull Request #958 · getnora-io/nora

devitway · 2026-09-05T08:00:38Z

Closes #956. Closes #957.

Two npm packument fixes. #959 was stacked on this branch and has already merged into it, so this PR now carries both.

Housekeeping: this PR was auto-closed for a moment when I force-pushed the branch to correct a Co-authored-by address. Reopened; the branch was never lost.

1. A missing packument is rebuilt instead of 404'd (#956)

GET /npm/<pkg> answered 404 for a hosted package whose derived metadata.json was missing, while every published version was still sitting in storage.

The reassembly already existed — regenerate_packument() lists versions/, dist-tags/ and pkg.json — but only the publish path called it. A read fell through to the upstream proxy, which then 404'd for a package that exists only in this registry.

The read path now rebuilds when versions/ is non-empty, serves the result, and re-materializes metadata.json so the cost is paid once.

Before the namespace guard, on purpose: serving locally-owned bytes is always allowed, and that guard exists to stop the upstream fetch below it.
Under the same publish_lock the publish path takes, so a fleet stampeding one package rebuilds it once rather than once per request.
A name with nothing behind it still returns 404 — the rebuild must not invent a package out of an empty prefix.

Measured on a polygon: real S3 (MinIO), real npm publish, 500 versions, metadata.json deleted from the bucket.

	result
`main`	404, 0 B, 0.93 ms — 500 version objects still in the bucket
this branch	200, 234 186 B, 185 ms
second request	200, 2.8 ms — plain cache hit, packument re-materialized
package never published	404, 1.2 ms — unchanged

Adds nora_packument_rebuilt_total{registry}. A non-zero rate means storage was written or restored outside NORA — worth an alert rather than a silent repair.

2. The abbreviated packument for install-v1 clients (#957)

npm install asks for application/vnd.npm.install-v1+json and NORA ignored it, serving the full document to everyone. The fields it carries are exactly the ones an installer never reads.

The per-version field list is an allowlist, in one place. Dropping a field an installer consults — os, cpu, engines, peerDependenciesMeta — silently changes what gets resolved.
Vary: Accept is load-bearing. The body now depends on a request header while metadata stays Cache-Control: public; without it a shared cache can hand the short document to a client that wanted the full one.
Derived locally, never requested upstream, so the cache keeps one canonical object per package and a short document can never displace the full one.

package	full	install-v1		versions
`lodash`	247 652 B	71 989 B	−70.9%	117 → 117
`express`	804 975 B	344 703 B	−57.2%	288 → 288

The polygon caught a real bug mid-flight: the first pass abbreviated the body on the stale-serve path but left Content-Type: application/json on it — a short document announced as the full one. Fixed by routing that branch through the same helper, and a test now asserts the x-nora-stale precondition together with the content type, so the degraded path cannot drift from the normal one again.

Validation

Seven tests across both changes, flip-verified — with the rebuild disabled two go red while the "absent package stays 404" guard stays green, which is what it is for.

End-to-end on the polygon with the same binary: publish 200 versions, read the packument, npm install from the registry (hosted and proxied), Maven proxy fetch — all unchanged, and the storage layout is identical to main: same keys, same object count.

Full suite: 63 lib + 1788 bin + 6 doc, zero failures. cargo fmt --check and cargo clippy -p nora-registry --all-targets -- -D warnings clean.

Credit

Both were surfaced while validating #889 on a polygon; the defects are ours. Both commits carry Co-authored-by: ivaseeq.

github-actions · 2026-09-05T08:12:07Z