LibWorld
← All ecosystems

npm

/npm/

Node packages, and the document that points at them

How it works

  • Tarballs are checked against dist.integrity from the packument — the sha512 npm publishes — before they are stored. Packages published before integrity existed carry only a sha1 shasum; that is recorded AS sha1 rather than promoted, because a weak check that happened is worth more than a strong one that did not, as long as nothing calls it strong.

  • npm asks the registry for one JSON document per package — a packument — listing every published version and where to download each one. LibWorld revalidates that document and rewrites dist.tarball in it to point at itself.

  • Tarballs never change once published, so they are cached permanently on first fetch.

  • Rewriting inside the packument is what makes this a one-line change for you: npm reads the download URL out of the document it was already going to fetch, so there is no client to patch and no .npmrc gymnastics beyond the registry URL.

Things that have cost real time

Written down because they were paid for once already.

The packument is rewritten on every serve, not once when it is cached, so every version's dist.tarball points back at this mirror even after the mirror's own base URL changes. Rewriting at cache time would have baked yesterday's hostname into today's answer.

It is parsed with a JSON parser rather than a regex, and that is a scar: big packages produce multi-megabyte documents, and std::regex hits its recursion limits on input that size long before correctness is the problem.

A packument that will not parse is served as-is and attests nothing, rather than failing the install. Degrading to "works, unverified" is the right failure for a cache — refusing to answer would take the registry down for a package npm itself serves fine.