NpmRegistry
API reference › Foxy › Native › NpmRegistry
Provides the npm registry access of the native manager: abbreviated metadata, integrity-verified tarballs, and bulk security advisories.
Requests answered with HTTP 429 are retried up to three times, waiting the Retry-After seconds (capped at 60)
or 1, 2, and 4 seconds. Tarballs are cached and verified against their Subresource Integrity value on every cache
hit and every download; a prefetch fills the cache with parallel downloads and no retry. Every metadata request,
tarball download, prefetch, and cache hit is written at very verbose level (-vv).
URLs written to the output or put in an exception message are masked with Url::sanitize(): an
access_token query value and a userinfo password become ***, and a long or token-like user name keeps its first
three characters.
Methods
Section titled “Methods”| Method | Description | Defined by |
|---|---|---|
__construct() | Creates an npm registry client with cache and retry support. | NpmRegistry |
fetchTarball() | Returns the path of a verified .tgz written inside the directory, from the cache when possible. | NpmRegistry |
getAdvisories() | Returns the registry’s bulk advisories document for the given versions, as the registry wrote it. | NpmRegistry |
getMetadata() | Returns the abbreviated metadata of a package. | NpmRegistry |
prefetchTarballs() | Downloads the tarballs missing from the cache in parallel, verifying each before it is cached. | NpmRegistry |
Constants
Section titled “Constants”| Constant | Value | Description | Defined by |
|---|---|---|---|
DEFAULT_URL | 'https://registry.npmjs.org' | NpmRegistry |
Method details
Section titled “Method details”__construct()
Section titled “__construct() ”public function __construct(Composer\Util\HttpDownloader $httpDownloader, Composer\Cache $cache, Composer\IO\IOInterface $io, string $url = \self::DEFAULT_URL, Closure(int): void|null $delay = null)Creates an npm registry client with cache and retry support.
Parameters
| Parameter | Type | Description |
|---|---|---|
$httpDownloader | Composer\ | Downloader that performs the requests; prefetchTarballs() needs the async-enabled instance returned by Composer::getLoop()->getHttpDownloader(). |
$cache | Composer\ | Tarball cache. |
$io | Composer\ | Output for the retry and failed prefetch notices and the very verbose registry traffic. |
$url | string | Registry base URL; a trailing slash is ignored. |
$delay | Closure(int): void| | Replacement for sleep() during the 429 back-off, or null to sleep. |
fetchTarball()
Section titled “fetchTarball() ”public function fetchTarball(Foxy\Native\ResolvedPackage $package, string $directory): stringReturns the path of a verified .tgz written inside the directory, from the cache when possible.
A cached tarball that fails its integrity check is removed and downloaded again.
Parameters
| Parameter | Type | Description |
|---|---|---|
$package | ResolvedPackage | Registry package; its resolved and integrity values must be set. |
$directory | string | Existing directory that receives the tarball. |
Returns
string
Throws
Foxy\Exception\RuntimeException: if the request fails or the tarball does not match its integrity value.
getAdvisories()
Section titled “getAdvisories() ”public function getAdvisories(array<string, non-empty-list<string>> $versions): stringReturns the registry’s bulk advisories document for the given versions, as the registry wrote it.
Sends one POST to npm’s bulk advisories endpoint with a JSON object body; an empty response body is returned
as an empty string.
Parameters
| Parameter | Type | Description |
|---|---|---|
$versions | array<string, | Locked versions keyed by package name. |
Returns
string
Throws
Foxy\Exception\RuntimeException: if the request fails, including a registry that does not implement the endpoint.
getMetadata()
Section titled “getMetadata() ”public function getMetadata(string $name): Foxy\Native\PackageMetadataReturns the abbreviated metadata of a package.
Parameters
| Parameter | Type | Description |
|---|---|---|
$name | string | Package name, scoped names included (@scope/name). |
Returns
Throws
Foxy\Exception\RuntimeException: if the package is unknown, the request fails, or the metadata is malformed.
prefetchTarballs()
Section titled “prefetchTarballs() ”public function prefetchTarballs(list<Foxy\Native\ResolvedPackage> $packages, string $directory): voidDownloads the tarballs missing from the cache in parallel, verifying each before it is cached.
Nothing is downloaded when the cache is disabled or read-only, since the downloads could not be kept. A package
without a tarball URL is skipped. A download that fails, does not match its integrity value, or cannot be
cached is discarded with a verbose notice; fetchTarball() downloads it again and reports the error.
Each download is written into the given directory, as fetchTarball() does, and removed before the
method returns.
Parameters
| Parameter | Type | Description |
|---|---|---|
$packages | list<ResolvedPackage> | Registry packages whose tarballs are wanted. |
$directory | string | Existing directory that holds each tarball while it is verified. |