package
Rush plugin for generic HTTP cloud build cache
npm install @rushstack/rush-http-build-cache-pluginGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
A Rush plugin that uses HTTP/HTTPS to manage cache objects.
Authentication is provided via standard Authorization HTTP headers, with the value (a Bearer or Basic token) configured using a custom node script. Your "tokenHandler" node script is automatically called when the user updates their cloud credentials.
To use the HTTP build cache plugin, enable it in common/config/rush/build-cache.json:
{
"buildCacheEnabled": true,
"cacheProvider": "http"
}Then customize the httpConfiguration block. For typical use cases, where you'll use a remote HTTP URL with authentication, you'll need to provide at least the url and tokenHandler options:
{
"httpConfiguration": {
"url": "https://build-cache.example.com",
"tokenHandler": {
"exec": "node",
"args": ["common/scripts/custom-script-that-returns-an-authentication-header.js"]
},
"isCacheWriteAllowed": false
}
}(For more detail on the above properties and additional optional properties, consult the default build-cache.json file.)
Cache requests make up to three attempts for transient network failures and HTTP 408, 429, 500, 502, 503, 504, and 520-524 responses. Buffered and file-stream uploads use the same retry policy; each file upload attempt opens a fresh stream. Authentication failures, cache misses, and other permanent failures are not retried, apart from the existing credential challenge flow.
Retries use exponential backoff with jitter, starting at 2.5-5 seconds, with a
maximum delay of 60 seconds. A valid Retry-After header can increase the delay.
If the server requests a delay longer than 60 seconds, Rush reports the failure
instead of retrying early or stalling the build. Retry settings are not configurable.
Run Rush with --verbose to see retry attempts, delays, and the cf-ray response
header when present. Exhausted retries preserve the existing failure reporting.
Cache writes must be idempotent for a given cache key, including when a custom
uploadMethod of POST or PATCH is used: a server may store an upload even if its
response is lost.
The HTTP build cache plugin offloads authorization to an external executable script that you define. A typical use case would be to create a simple script, for example common/scripts/cache-auth.js, that prints an Authorization header value when executed.
For example:
node common/scripts/cache-auth.js
# => Bearer 0284357923592790DDb979dBcd2zzHow the script generates authorization values is up to you, and depends on the configuration of your remote cache server.
Possible implementations:
CACHE_USER and CACHE_TOKEN) defined by the developerThe HTTP build cache plugin can use almost any HTTP/HTTPS backend for remote caching, as long as it honors the following rules:
Authorization: Bearer xxx or Authorization: Basic xxx headers for authentication.form/multipart MIME types).The Gradle Build Cache Server (typically used to support Gradle Remote Build Cache) meets all of the requirements above, so if you don't have another server in mind, you can use it as your remote backend.
First, start up and configure your build cache node locally:
java -jar build-cache-node-14.0.jar startSecond, configure your build-cache.json file as described in the Configuration section:
url must end with /cache/, for example, http://localhost:5071/cache/.isCacheWriteAllowed: true.tokenHandler to point to a script that prints a Basic or Bearer Authorization value (this can be a dummy string if you granted Read and Write to Anonymous in your build cache node configuration).Note that the Gradle Build Cache Server has a stricter format for its cache keys (they should be a simple hexadecimal hash with no non-alphanumeric characters). Configure this setting in your build-cache.json file:
{
"cacheEntryNamePattern": "[hash]"
}Last, initialize your cache credentials using Rush:
rush update-cloud-credentials --interactiveTo test out your remote build cache with full debugging output (for spotting any errors reading or writing the cache), run with the --debug flag:
rush --debug build --verboseIf you go on to deploy Rush remote build caching to your developers using the Gradle Build Cache, update your
tokenHandlerscript to reflect your use case -- for example, you could require each developer to have a designated username/token configured via environment variables, and configure Cache Access Control with the corresponding entries. In this case thetokenHandlerscript should read the environment variables and print out an Authorization header, for example:// common/scripts/build-cache-auth.js const credentials = `${process.env.CACHE_USER}:${process.env.CACHE_TOKEN}`; console.log('Basic ' + Buffer.from(credentials).toString('base64'));
odspnpm
odspnpm@microsoft.com
Estimated unpacked size across 35 packages.
10.7 MB
Includes dependencies.
4 direct · 1 outdated