docs: update pnpr docs for registry mounts and the authorization-aware resolver#832
Conversation
…e resolver Reflects the pnpr redesign in pnpm/pnpm#12700 (authorization-aware resolver cache, default-deny fetch allowlist, no forwarded upstream credentials) and pnpm/pnpm#12747 (registry mounts as the only routing model): mounts:/defaultTarget: replace uplinks: and packages: proxy:, packages: is ACL-only, and every mount is served at /~<mount>/.
|
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughDocumentation across the pnpr docs set (cli, configuration, endpoints, install-acceleration, introduction, quick-start, storage) is rewritten to replace the prior verdaccio-shaped uplinks/packages configuration model with a mounts/defaultTarget routing model, clarifying auth defaults, a new secret key, resolver fetch allowlisting, and endpoint routing semantics. Changespnpr mounts documentation rewrite
Estimated code review effort: 2 (Simple) | ~15 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
PR Summary by QodoDocs: align pnpr docs with mounts routing and auth-aware resolver cache
AI Description
Diagram
High-Level Assessment
Files changed (7)
|
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@pnpr-docs/configuration.md`:
- Around line 103-106: Clarify the hosted mount collision rule in the
configuration docs by updating the `org`/storage namespace description in the
mount configuration section: explain whether hosted mounts that omit `org` are
rejected or allowed to share the flat `storage` root, since the current text
only covers explicit namespace conflicts. Refer to the `org` and `access` option
descriptions in the mount config table and the note about hosted mount
uniqueness so the wording clearly states the expected behavior for
`name@version` collisions.
In `@pnpr-docs/endpoints.md`:
- Around line 45-47: The documentation claim in the `dist.tarball` section is
too broad because private resolutions can still include `/~<mount>/` tarball
URLs in lockfiles. Reword the text in `endpoints.md` to describe base
canonicalization via `public_url` for the client-addressed base, and avoid
stating that lockfiles never bake in a mount name; keep the wording aligned with
the `dist.tarball` rewrite behavior and the `/~<mount>/` path handling.
In `@pnpr-docs/install-acceleration.md`:
- Around line 99-103: The paragraph in the install acceleration docs uses
“integrity-only” too broadly and conflicts with the public/private lockfile
split described in configuration.md. Update the wording to reflect that public
packages keep upstream tarball URLs, while private packages are rewritten to the
mount URL, and keep the explanation aligned with the behavior described around
the lockfile and mount endpoint in this section.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 00915171-44f0-4a77-a1a9-1c0c2b8166bd
📒 Files selected for processing (7)
pnpr-docs/cli.mdpnpr-docs/configuration.mdpnpr-docs/endpoints.mdpnpr-docs/install-acceleration.mdpnpr-docs/introduction.mdpnpr-docs/quick-start.mdpnpr-docs/storage.md
📜 Review details
⚠️ CI failures not shown inline (1)
Commit Status: Vercel: Vercel
Conclusion: failure
Deployment has failed — run this Vercel CLI command: npx vercel inspect dpl_FV4jdc5S6N9in8VHhY6irLVZcwJB --logs
🧰 Additional context used
🪛 LanguageTool
pnpr-docs/quick-start.md
[style] ~48-~48: Consider an alternative for the overused word “exactly”.
Context: ...04, never a request to npmjs — which is exactly what closes dependency confusion. ## S...
(EXACTLY_PRECISELY)
pnpr-docs/configuration.md
[grammar] ~6-~6: Ensure spelling is correct
Context: ... YAML config. When you don't pass -c, pnpr looks for a global config.yaml in its...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~204-~204: You can shorten this phrase to improve clarity and avoid wordiness.
Context: ...ute's pattern; - a duplicate pattern; - a source that is undefined, the router itself, or another router (...
(NNS_THAT_ARE_JJ)
🔇 Additional comments (7)
pnpr-docs/introduction.md (1)
9-16: LGTM!Also applies to: 34-36
pnpr-docs/cli.md (1)
14-14: LGTM!pnpr-docs/configuration.md (1)
6-34: LGTM!Also applies to: 63-102, 107-253, 272-292, 307-334
pnpr-docs/quick-start.md (1)
6-59: LGTM!Also applies to: 72-91
pnpr-docs/storage.md (1)
64-81: LGTM!pnpr-docs/endpoints.md (1)
23-44: LGTM!Also applies to: 49-50, 63-78, 103-106, 117-118, 134-136
pnpr-docs/install-acceleration.md (1)
44-52: LGTM!Also applies to: 65-67, 68-79, 80-98, 105-111
| | `org` | Storage namespace for this mount's packages, so two hosted mounts can hold the same `name@version` without colliding. Omitted means the flat `storage` root. Must be a single path-safe segment. | | ||
| | `access` | Who may read this mount's packages. Defaults to `$all`. | | ||
|
|
||
| Two hosted mounts cannot share an `org` namespace — that's rejected at config |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Clarify the collision rule for hosted mounts without org.
org is optional here, but the uniqueness check only forbids sharing an explicit namespace. As written, two hosted mounts that omit org would both use the flat storage root and could collide on disk. Please state whether that configuration is rejected or make org mandatory for hosted mounts.
💡 Suggested wording
-| `org` | Storage namespace for this mount's packages, so two hosted mounts can hold the same `name@version` without colliding. Omitted means the flat `storage` root. Must be a single path-safe segment. |
+| `org` | Storage namespace for this mount's packages, so two hosted mounts can hold the same `name@version` without colliding. Omitted means the flat `storage` root; only one hosted mount may use that default. Must be a single path-safe segment. |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | `org` | Storage namespace for this mount's packages, so two hosted mounts can hold the same `name@version` without colliding. Omitted means the flat `storage` root. Must be a single path-safe segment. | | |
| | `access` | Who may read this mount's packages. Defaults to `$all`. | | |
| Two hosted mounts cannot share an `org` namespace — that's rejected at config | |
| | `org` | Storage namespace for this mount's packages, so two hosted mounts can hold the same `name@version` without colliding. Omitted means the flat `storage` root; only one hosted mount may use that default. Must be a single path-safe segment. | | |
| | `access` | Who may read this mount's packages. Defaults to `$all`. | | |
| Two hosted mounts cannot share an `org` namespace — that's rejected at config |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@pnpr-docs/configuration.md` around lines 103 - 106, Clarify the hosted mount
collision rule in the configuration docs by updating the `org`/storage namespace
description in the mount configuration section: explain whether hosted mounts
that omit `org` are rejected or allowed to share the flat `storage` root, since
the current text only covers explicit namespace conflicts. Refer to the `org`
and `access` option descriptions in the mount config table and the note about
hosted mount uniqueness so the wording clearly states the expected behavior for
`name@version` collisions.
| - Served `dist.tarball` URLs are rewritten onto the configured `public_url` | ||
| and stay canonical for the base the client addressed (path-less or | ||
| `/~<mount>/`), so lockfiles don't bake in a mount name. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Narrow the lockfile claim.
The last clause is too broad: private resolutions intentionally emit /~<mount>/ tarball URLs, so lockfiles can still carry a mount name. Please reword this as base canonicalization, not a blanket “no mount name” guarantee.
Suggested rewording
- so lockfiles don't bake in a mount name.
+ so the tarball URL stays canonical for the base the client addressed.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Served `dist.tarball` URLs are rewritten onto the configured `public_url` | |
| and stay canonical for the base the client addressed (path-less or | |
| `/~<mount>/`), so lockfiles don't bake in a mount name. | |
| - Served `dist.tarball` URLs are rewritten onto the configured `public_url` | |
| and stay canonical for the base the client addressed (path-less or | |
| `/~<mount>/`), so the tarball URL stays canonical for the base the client addressed. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@pnpr-docs/endpoints.md` around lines 45 - 47, The documentation claim in the
`dist.tarball` section is too broad because private resolutions can still
include `/~<mount>/` tarball URLs in lockfiles. Reword the text in
`endpoints.md` to describe base canonicalization via `public_url` for the
client-addressed base, and avoid stating that lockfiles never bake in a mount
name; keep the wording aligned with the `dist.tarball` rewrite behavior and the
`/~<mount>/` path handling.
| Because a mount endpoint URL is canonical for a client whose registry | ||
| configuration points at it, lockfile entries stay integrity-only — the | ||
| registry host lives in the client's `.npmrc`, not in the lockfile — and a | ||
| project resolves to the same lockfile whether it installs through `/resolve` | ||
| or directly against the registry. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Replace the “integrity-only” wording.
This paragraph conflicts with the split described just above and in configuration.md: public packages keep upstream tarball URLs, while private packages are rewritten to the mount URL. “Integrity-only” is too broad here; please describe the public/private URL split explicitly.
Suggested rewording
- lockfile entries stay integrity-only — the registry host lives in the client's `.npmrc`, not in the lockfile —
- and a project resolves to the same lockfile whether it installs through `/resolve` or directly against the registry.
+ public packages keep their upstream tarball URL, while private packages are rewritten to the mount endpoint.
+ That keeps the lockfile consistent for a given client-facing base.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Because a mount endpoint URL is canonical for a client whose registry | |
| configuration points at it, lockfile entries stay integrity-only — the | |
| registry host lives in the client's `.npmrc`, not in the lockfile — and a | |
| project resolves to the same lockfile whether it installs through `/resolve` | |
| or directly against the registry. | |
| Because a mount endpoint URL is canonical for a client whose registry | |
| configuration points at it, public packages keep their upstream tarball URL, | |
| while private packages are rewritten to the mount endpoint. That keeps the | |
| lockfile consistent for a given client-facing base. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@pnpr-docs/install-acceleration.md` around lines 99 - 103, The paragraph in
the install acceleration docs uses “integrity-only” too broadly and conflicts
with the public/private lockfile split described in configuration.md. Update the
wording to reflect that public packages keep upstream tarball URLs, while
private packages are rewritten to the mount URL, and keep the explanation
aligned with the behavior described around the lockfile and mount endpoint in
this section.
Updates the pnpr docs to the post-redesign state from pnpm/pnpm#12700 (authorization-aware resolver cache) and pnpm/pnpm#12747 (registry mounts as the only routing model). No legacy info or migration guides are kept — pnpr is still under active development and can change in breaking ways.
What changed
configuration.md —
uplinks:andpackages: proxy:are gone. Documentsmounts:/defaultTarget:as the only routing surface (provenance is declared, never inferred; no cross-origin fall-through), the three mount kinds with key tables — hosted (orgnamespaces, 404 on unauthorized private reads), upstream (publicvsauth+access, per-mount cache namespaces, credential-rotation re-keying), router (the four-shape pattern language and every validation error pnpr refuses to start on) — pluspackages:as a pure ACL layer and newgroups:,secret:, androutes: public:sections.install-acceleration.md — drops the forwarded-upstream-credentials claim (the server ignores
authHeadersnow); adds the default-deny fetch allowlist section and a "Private registries" section covering server-owned credentials, public tarballs staying on the CDN vs private ones routed through/~<mount>/, integrity-only lockfile entries, and the authorization-aware resolution cache.endpoints.md — new "Registry bases:
/and/~<mount>/" section (every registry endpoint works under a mount prefix, router no-match is a definitive 404, writes must land on a hosted mount);authHeadersremoved from the resolve field list; search corrected to local-only.quick-start.md — leads with writing a mount-shaped config and notes the bundled default is shaped for pnpm's own test registry.
storage.md, introduction.md, cli.md — R2 example converted to mounts, intro updated with the declared-provenance model, "verdaccio-shaped" dropped.
Everything was verified against the pnpr source at pnpm/pnpm
main(config.rs,mount.rs,route.rs,resolver.rs,server.rs, and the bundledconfig.yaml), not just the PR descriptions.Summary by CodeRabbit