@pnpm/pnpr.client 1.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2016 Rico Sta. Cruz and other contributors
+Copyright (c) 2016-2026 Zoltan Kochan and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @pnpm/pnpr.client
+
+Client library for the pnpr server. Reads the local store state, sends it to the server, and writes the received files into the content-addressable store.
+
+## How it works
+
+1. Reads integrity hashes from the local store index (`index.db`).
+2. Sends `POST /v1/install` to the pnpr server with the project's dependencies and the store integrities.
+3. Parses the NDJSON streaming response — `D`-lines (missing file digests) are dispatched to worker downloads against `/v1/files`, `I`-lines are buffered as raw store-index entries, and the final `L`-line yields the resolved lockfile and stats.
+4. File download workers write each received file directly to the local CAFS (`files/{hash[:2]}/{hash[2:]}`).
+5. Writes store index entries for all new packages in a single SQLite transaction.
+6. Returns the resolved lockfile for use with pnpm's headless install (linking phase).
+
+## Usage
+
+This package is used internally by pnpm when the `pnprServer` config option is set. It is not intended to be called directly, but can be used programmatically:
+
+```typescript
+import { fetchFromPnpmRegistry } from '@pnpm/pnpr.client'
+import { StoreIndex } from '@pnpm/store.index'
+
+const storeIndex = new StoreIndex('/path/to/store')
+
+const { lockfile, stats } = await fetchFromPnpmRegistry({
+  registryUrl: 'http://localhost:4000',
+  storeDir: '/path/to/store',
+  storeIndex,
+  dependencies: { react: '^19.0.0' },
+  devDependencies: { typescript: '^5.0.0' },
+})
+
+console.log(`Resolved ${stats.totalPackages} packages`)
+console.log(`${stats.alreadyInStore} cached, ${stats.filesToDownload} files downloaded`)
+// lockfile is ready for headless install
+```
+
+## Configuration
+
+Add to `pnpm-workspace.yaml` to enable automatically during `pnpm install`:
+
+```yaml
+pnprServer: http://localhost:4000
+```

package/lib/fetchFromPnpmRegistry.d.ts

@@ -0,0 +1,89 @@
+import type { LockfileFile, LockfileObject } from '@pnpm/lockfile.types';
+import { StoreIndex } from '@pnpm/store.index';
+import type { ResponseMetadata } from './protocol.js';
+export interface PnprProject {
+    /** Relative dir within the workspace (e.g. "." or "packages/foo") */
+    dir: string;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+}
+export interface FetchFromPnpmRegistryOptions {
+    /** URL of the pnpr server */
+    registryUrl: string;
+    /** Client's store directory */
+    storeDir: string;
+    /** Client's store index */
+    storeIndex: StoreIndex;
+    /** Dependencies to resolve (single project) */
+    dependencies?: Record<string, string>;
+    /** Dev dependencies to resolve (single project) */
+    devDependencies?: Record<string, string>;
+    /** Optional dependencies to resolve (single project) */
+    optionalDependencies?: Record<string, string>;
+    /** Multiple projects in a workspace */
+    projects?: PnprProject[];
+    /**
+     * The client's default registry. The server resolves against this
+     * (and `namedRegistries`) rather than its own configuration.
+     */
+    registry?: string;
+    /** The client's named-registry aliases (`namedRegistries`). */
+    namedRegistries?: Record<string, string>;
+    /**
+     * The caller's forwarded upstream credentials, keyed by nerf-darted
+     * registry URI, so the server resolves/fetches private content as the
+     * caller. Distinct from `authorization` (pnpr identity).
+     */
+    authHeaders?: Record<string, string>;
+    /**
+     * `Authorization` for the pnpr server's own URL (`undefined` if none):
+     * identifies the caller to pnpr's gate and keys the grant table.
+     */
+    authorization?: string;
+    /** Overrides */
+    overrides?: Record<string, string>;
+    /** Node.js version for resolution */
+    nodeVersion?: string;
+    /** Minimum release age in minutes */
+    minimumReleaseAge?: number;
+    /**
+     * Existing lockfile for incremental resolution, in the on-disk format
+     * the wire protocol carries. The caller reads it with
+     * `readWantedLockfileFile` so no in-memory→on-disk round-trip is needed.
+     */
+    lockfile?: LockfileFile;
+    /**
+     * `--lockfile-only`: resolve and return only the lockfile — fetch no
+     * files into the local store. Forwarded to the server (which skips the
+     * file diff); the client ignores the (empty) file payload so the store
+     * stays untouched. Mirrors pnpm's resolve + write, fetch nothing, link
+     * nothing. See https://github.com/pnpm/pnpm/issues/12146.
+     */
+    lockfileOnly?: boolean;
+}
+export interface FetchFromPnpmRegistryResult {
+    lockfile: LockfileObject;
+    stats: ResponseMetadata['stats'];
+    /** Promise that resolves when all file downloads are written to CAFS */
+    fileDownloads: Promise<void>;
+    /** Pre-packed store index entries to write to SQLite */
+    indexEntries: Array<{
+        key: string;
+        buffer: Uint8Array;
+    }>;
+}
+/**
+ * Fetch resolved dependencies from a pnpr server in a single round trip.
+ *
+ * `POST /v1/install` (with `inlineFiles`) answers with one gzipped binary
+ * body: a length-prefixed JSON header (lockfile, stats, store-index
+ * entries, or verification violations) followed by the missing files'
+ * contents as binary frames. We parse the header here and hand the file
+ * frames to a worker that writes them straight into the CAFS.
+ */
+export declare function fetchFromPnpmRegistry(opts: FetchFromPnpmRegistryOptions): Promise<FetchFromPnpmRegistryResult>;
+export declare function writeRawIndexEntries(indexEntries: Array<{
+    key: string;
+    buffer: Uint8Array;
+}>, storeIndex: StoreIndex): void;

package/lib/fetchFromPnpmRegistry.js

@@ -0,0 +1,179 @@
+import http from 'node:http';
+import https from 'node:https';
+import { URL } from 'node:url';
+import { gunzip } from 'node:zlib';
+import { convertToLockfileObject } from '@pnpm/lockfile.fs';
+import { StoreIndex } from '@pnpm/store.index';
+import { writeCafsFiles } from '@pnpm/worker';
+/**
+ * Fetch resolved dependencies from a pnpr server in a single round trip.
+ *
+ * `POST /v1/install` (with `inlineFiles`) answers with one gzipped binary
+ * body: a length-prefixed JSON header (lockfile, stats, store-index
+ * entries, or verification violations) followed by the missing files'
+ * contents as binary frames. We parse the header here and hand the file
+ * frames to a worker that writes them straight into the CAFS.
+ */
+export async function fetchFromPnpmRegistry(opts) {
+    const storeIntegrities = readStoreIntegrities(opts.storeIndex);
+    const projects = opts.projects ?? [{
+            dir: '.',
+            dependencies: opts.dependencies,
+            devDependencies: opts.devDependencies,
+            optionalDependencies: opts.optionalDependencies,
+        }];
+    const requestBody = JSON.stringify({
+        projects,
+        registry: opts.registry,
+        namedRegistries: opts.namedRegistries,
+        authHeaders: opts.authHeaders,
+        overrides: opts.overrides,
+        nodeVersion: opts.nodeVersion ?? process.version.slice(1),
+        os: process.platform,
+        arch: process.arch,
+        minimumReleaseAge: opts.minimumReleaseAge,
+        // Sent as-is: `opts.lockfile` is already the on-disk format the wire
+        // protocol carries (split `packages`/`snapshots`, `{ specifier, version }`
+        // importer deps).
+        lockfile: opts.lockfile,
+        lockfileOnly: opts.lockfileOnly,
+        storeIntegrities,
+        inlineFiles: true,
+    });
+    const body = await postInstall(opts.registryUrl, requestBody, opts.authorization);
+    // The combined response is `[u32 header length][header JSON][file frames]`.
+    if (body.length < 4) {
+        throw new Error('pnpr server returned a truncated /v1/install response');
+    }
+    const headerLength = body.readUInt32BE(0);
+    const header = JSON.parse(body.subarray(4, 4 + headerLength).toString('utf-8'));
+    if (header.violations != null && header.violations.length > 0) {
+        const rendered = header.violations
+            .map((violation) => `  ${violation.name}@${violation.version}: ${violation.reason}`)
+            .join('\n');
+        throw new Error(`pnpr server rejected the lockfile under the verification policy:\n${rendered}`);
+    }
+    const indexEntries = (header.indexEntries ?? []).map(({ key, b64 }) => ({
+        key,
+        buffer: new Uint8Array(Buffer.from(b64, 'base64')),
+    }));
+    // `--lockfile-only` fetches nothing: there are no file frames to write
+    // (the server sends only the end-of-stream marker), so leave the store
+    // untouched.
+    const fileDownloads = opts.lockfileOnly
+        ? Promise.resolve()
+        : writeCafsFiles({
+            storeDir: opts.storeDir,
+            payload: body.subarray(4 + headerLength),
+        }).then(() => { });
+    return {
+        // The server speaks the on-disk lockfile format; convert it to the
+        // in-memory `LockfileObject` the rest of pnpm consumes.
+        lockfile: convertToLockfileObject(header.lockfile),
+        stats: header.stats,
+        fileDownloads,
+        indexEntries,
+    };
+}
+function readStoreIntegrities(storeIndex) {
+    const seen = new Set();
+    for (const key of storeIndex.keys()) {
+        const tabIdx = key.indexOf('\t');
+        if (tabIdx === -1)
+            continue;
+        const integrity = key.slice(0, tabIdx);
+        // StoreIndex also stores non-integrity keys (e.g. git-hosted entries
+        // keyed by URL). Filter to actual SRI hashes — sending those over to
+        // the pnpr server would just bloat the request without ever matching.
+        if (!isIntegrityLike(integrity))
+            continue;
+        seen.add(integrity);
+    }
+    return [...seen];
+}
+function isIntegrityLike(value) {
+    return value.startsWith('sha512-') ||
+        value.startsWith('sha256-') ||
+        value.startsWith('sha1-');
+}
+const REQUEST_TIMEOUT = 600_000; // 10 minutes — server-side resolution can be slow on first run
+/**
+ * `POST /v1/install` and return the full response body, decompressed.
+ *
+ * `urlPath` resolution normalizes the base to end with "/" so a path
+ * prefix configured on the pnpr server URL (e.g. https://host/pnpr/) is
+ * preserved.
+ */
+async function postInstall(registryUrl, body, authorization) {
+    const base = registryUrl.endsWith('/') ? registryUrl : `${registryUrl}/`;
+    const url = new URL('v1/install', base);
+    const requestFn = url.protocol === 'https:' ? https.request : http.request;
+    const headers = {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+        'Accept-Encoding': 'gzip',
+    };
+    // Identify the caller to the pnpr server's access gate so protected
+    // packages resolve and the per-user grant table keys on the right user.
+    if (authorization != null) {
+        headers.Authorization = authorization;
+    }
+    return new Promise((resolve, reject) => {
+        const req = requestFn(url, {
+            method: 'POST',
+            timeout: REQUEST_TIMEOUT,
+            headers,
+        }, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => {
+                const raw = Buffer.concat(chunks);
+                // The server gzips both the install body and its JSON error bodies
+                // (e.g. a 401/403 access denial), so decompress *before* branching
+                // on the status code — otherwise an error surfaces as binary
+                // garbage instead of the server's message. Skip it only when the
+                // HTTP stack already decompressed (no gzip magic bytes).
+                const finish = (body) => {
+                    if (res.statusCode !== 200) {
+                        reject(new Error(`pnpr server responded with ${res.statusCode}: ${body.toString('utf-8')}`));
+                    }
+                    else {
+                        resolve(body);
+                    }
+                };
+                if (res.headers['content-encoding'] === 'gzip' || (raw[0] === 0x1f && raw[1] === 0x8b)) {
+                    gunzip(raw, (err, decompressed) => {
+                        if (err)
+                            reject(err);
+                        else
+                            finish(decompressed);
+                    });
+                }
+                else {
+                    finish(raw);
+                }
+            });
+            res.on('error', reject);
+        });
+        req.on('timeout', () => {
+            req.destroy(new Error(`pnpr server request timed out after ${REQUEST_TIMEOUT / 1000}s (${registryUrl})`));
+        });
+        req.on('error', (err) => {
+            if (err.code === 'ECONNREFUSED') {
+                reject(new Error(`Could not connect to pnpr server at ${registryUrl}. Is the server running?`));
+            }
+            else {
+                reject(err);
+            }
+        });
+        req.write(body);
+        req.end();
+    });
+}
+export function writeRawIndexEntries(indexEntries, storeIndex) {
+    const writes = indexEntries.filter(({ key }) => !storeIndex.has(key));
+    if (writes.length > 0) {
+        storeIndex.setRawMany(writes);
+    }
+}
+//# sourceMappingURL=fetchFromPnpmRegistry.js.map

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export { fetchFromPnpmRegistry, type FetchFromPnpmRegistryOptions, type FetchFromPnpmRegistryResult, writeRawIndexEntries } from './fetchFromPnpmRegistry.js';
+export { type ResponseMetadata } from './protocol.js';

package/lib/index.js

@@ -0,0 +1,3 @@
+export { fetchFromPnpmRegistry, writeRawIndexEntries } from './fetchFromPnpmRegistry.js';
+export {} from './protocol.js';
+//# sourceMappingURL=index.js.map

package/lib/protocol.d.ts

@@ -0,0 +1,13 @@
+import type { LockfileObject } from '@pnpm/lockfile.types';
+export interface ResponseMetadata {
+    lockfile: LockfileObject;
+    stats: {
+        totalPackages: number;
+        alreadyInStore: number;
+        packagesToFetch: number;
+        filesInNewPackages: number;
+        filesAlreadyInCafs: number;
+        filesToDownload: number;
+        downloadBytes: number;
+    };
+}

package/lib/protocol.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=protocol.js.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@pnpm/pnpr.client",
+  "version": "1.1.0",
+  "description": "Client for the pnpr server — sends store state, receives resolved lockfile and missing files",
+  "keywords": [
+    "pnpm",
+    "pnpm11"
+  ],
+  "license": "MIT",
+  "funding": "https://opencollective.com/pnpm",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pnpm/pnpm/tree/main/pnpr/client"
+  },
+  "homepage": "https://github.com/pnpm/pnpm/tree/main/pnpr/client#readme",
+  "bugs": {
+    "url": "https://github.com/pnpm/pnpm/issues"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib",
+    "!*.map"
+  ],
+  "dependencies": {
+    "@pnpm/store.index": "1100.1.0",
+    "@pnpm/lockfile.fs": "1100.1.3",
+    "@pnpm/store.cafs": "1100.1.8",
+    "@pnpm/lockfile.types": "1100.0.9"
+  },
+  "peerDependencies": {
+    "@pnpm/logger": "^1001.0.1",
+    "@pnpm/worker": "^1100.1.9"
+  },
+  "devDependencies": {
+    "@pnpm/types": "1101.3.0",
+    "@pnpm/pnpr.client": "1.1.0"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "jest": {
+    "preset": "@pnpm/jest-config"
+  },
+  "scripts": {
+    "start": "tsgo --watch",
+    "lint": "eslint \"src/**/*.ts\"",
+    "test": "pn compile",
+    "compile": "tsgo --build && pn lint --fix"
+  }
+}