@stim-cli/cache 1.20.1 → 1.21.0

package/README.md

@@ -6,8 +6,8 @@ front of it.
 
 The local filesystem is always the first tier. A project can add one optional
 second tier by pointing `cache.provider` at a module that implements this
-contract. Stim ships no network provider; writing one is an addition, not a
-change to Stim.
+contract. `@stim-cli/cache-s3` provides an S3-compatible second tier, including
+Cloudflare R2.
 
 If Stim is not installed globally, replace `stim` with `npx stim`.
 
@@ -30,6 +30,12 @@ provider, and lower-precedence layers that name the same provider resolved from
 the same directory; options written for another provider are ignored. Keep secrets out of
 committed settings; read them from the environment or from machine settings.
 
+## S3-compatible storage
+
+Install the separate [`@stim-cli/cache-s3`](../cache-s3/README.md) provider and
+select it through `cache.provider`. The AWS SDK and archive dependencies belong
+to that opt-in package; `@stim-cli/cache` has no runtime dependencies.
+
 ## Writing a provider
 
 ```js
@@ -53,10 +59,22 @@ export async function createCacheProvider({ projectRoot, options }) {
 }
 ```
 
-A provider implements one or both capabilities. It owns transport,
+A provider implements one or more capabilities. It owns transport,
 serialization, archive format, authentication, and remote retention. Stim owns
 fingerprints, cache keys, and local artifact paths.
 
+The optional `files` capability stores opaque complete files with
+`store({ key, sourcePath, overwrite, signal })` and downloads them with
+`resolve({ key, destinationDir, signal })`. A hit returns a path inside
+`destinationDir`; a miss returns `null` and leaves it empty. The CLI consumes
+the `metro` and `builds` adapters. Native Gradle APK caching consumes `files`
+directly to share the APK together with its verification receipt; a files-only
+provider can support this flow. An optional
+`stat({ key, signal })` returns `{ size }` or `null` without downloading;
+consumers still verify downloaded bytes. `createFilesystemFileCache(directory)`
+implements the same contract in an owned local directory without dependencies.
+It publishes atomically and materializes downloads in the requested scratch directory.
+
 `metro.get` returns the stored value or `null`.
 
 `builds.resolve` returns an existing path to the artifact, or `null` for a
@@ -112,8 +130,8 @@ const results = await runCacheProviderContract({
 ```
 
 `cacheProviderContractChecks()` returns the same checks as individual cases for
-a test runner that reports each one separately. Both helpers only check the
-capabilities a provider advertises, bound every check with a deadline, and
+a test runner that reports each one separately. Both helpers check advertised
+Metro and build capabilities, bound every check with a deadline, and
 verify that a call settles once its `AbortSignal` aborts.
 
 ## Budgets

package/dist/index.d.mts

@@ -76,7 +76,28 @@ interface BuildCacheCapability {
   resolve(input: BuildResolveInput): string | null | Promise<string | null>;
   store(input: BuildStoreInput): string | null | void | Promise<string | null | void>;
 }
+interface FileCacheResolveInput {
+  key: string;
+  destinationDir: string;
+  signal: AbortSignal;
+}
+interface FileCacheStoreInput {
+  key: string;
+  sourcePath: string;
+  overwrite: boolean;
+  signal: AbortSignal;
+}
+/** Opaque, complete files. Downloads are materialized inside destinationDir; a miss leaves it empty. */
+interface FileCacheCapability {
+  resolve(input: FileCacheResolveInput): Promise<string | null>;
+  store(input: FileCacheStoreInput): Promise<void>;
+  /** Checks presence without downloading; the bytes still need verification when fetched. */
+  stat?(input: Pick<FileCacheResolveInput, "key" | "signal">): Promise<{
+    size: number;
+  } | null>;
+}
 interface CacheProvider {
+  files?: FileCacheCapability;
   metro?: MetroCacheCapability;
   builds?: BuildCacheCapability;
 }
@@ -108,7 +129,7 @@ declare function loadCacheProvider({ projectRoot, config, timeoutMs }: {
   config?: CacheProviderConfig | null;
   timeoutMs?: number;
 }): Promise<LoadCacheProviderResult>;
-declare function callWithTimeout<T>(call: (signal: AbortSignal) => T | Promise<T>, timeoutMs: number): Promise<ProviderCallResult<T>>;
+declare function callWithTimeout<T>(call: (signal: AbortSignal) => T | Promise<T>, timeoutMs: number, signal?: AbortSignal): Promise<ProviderCallResult<T>>;
 declare function createWarnOnce(emit: (message: string) => void): WarnOnce;
 declare function cacheProviderEnv(config: CacheProviderConfig | null): string;
 /**
@@ -196,6 +217,7 @@ interface ResolveTieredBuildOptions {
   skipRead?: boolean;
   warn?: WarnOnce;
   timeoutMs?: number;
+  signal?: AbortSignal;
 }
 interface StoreTieredBuildOptions {
   local: BuildCacheCapability;
@@ -205,14 +227,15 @@ interface StoreTieredBuildOptions {
   overwrite: boolean;
   warn?: WarnOnce;
   timeoutMs?: number;
+  signal?: AbortSignal;
 }
 interface TieredBuildStoreResult {
   localPath: string | null;
   providerUpload: Promise<ProviderCallResult<void>> | null;
   providerName: string | null;
 }
-declare function resolveTieredBuild({ local, loadProvider, target, destinationDir, ensureDestination, skipRead, warn, timeoutMs }: ResolveTieredBuildOptions): Promise<TieredBuildResolution | null>;
-declare function storeTieredBuild({ local, loadProvider, target, sourcePath, overwrite, warn, timeoutMs }: StoreTieredBuildOptions): Promise<TieredBuildStoreResult>;
+declare function resolveTieredBuild({ local, loadProvider, target, destinationDir, ensureDestination, skipRead, warn, timeoutMs, signal }: ResolveTieredBuildOptions): Promise<TieredBuildResolution | null>;
+declare function storeTieredBuild({ local, loadProvider, target, sourcePath, overwrite, warn, timeoutMs, signal }: StoreTieredBuildOptions): Promise<TieredBuildStoreResult>;
 //#endregion
 //#region contract.d.ts
 interface CacheContractCheck {
@@ -249,4 +272,8 @@ declare const CACHE_CONTRACT_CHECK_TIMEOUT_MS = 3e4;
 declare function cacheProviderContractChecks(options: CacheContractOptions): CacheContractCheck[];
 declare function runCacheProviderContract(options: CacheContractOptions | CacheContractModuleOptions): Promise<CacheContractResult[]>;
 //#endregion
-export { BUILD_RESOLVE_TIMEOUT_ENV, BUILD_RESOLVE_TIMEOUT_MS, BUILD_UPLOAD_TIMEOUT_ENV, BUILD_UPLOAD_TIMEOUT_MS, BuildCacheCapability, BuildCacheContext, BuildCacheTarget, BuildResolveInput, BuildStoreInput, CACHE_CONTRACT_CHECK_TIMEOUT_MS, CACHE_PROVIDER_API_VERSION, CACHE_PROVIDER_ENV, CACHE_PROVIDER_ENV_NONE, CacheContractCheck, CacheContractModuleOptions, CacheContractOptions, CacheContractResult, CacheProvider, CacheProviderConfig, CacheProviderModule, LoadBuildProvider, LoadCacheProviderResult, METRO_READ_CONCURRENCY, METRO_READ_FAILURE_LIMIT, METRO_READ_TIMEOUT_ENV, METRO_READ_TIMEOUT_MS, METRO_UPLOAD_CONCURRENCY, METRO_UPLOAD_MAX_BYTES, METRO_UPLOAD_MAX_ITEMS, METRO_WRITE_TIMEOUT_ENV, METRO_WRITE_TIMEOUT_MS, MetroCacheCapability, MetroCacheContext, MetroCacheGetInput, MetroCacheSetInput, MetroCacheStore, MetroTierLimits, MetroTierTimeouts, PROVIDER_LOAD_TIMEOUT_ENV, PROVIDER_LOAD_TIMEOUT_MS, ProviderCallResult, ResolveTieredBuildOptions, StoreTieredBuildOptions, TieredBuildResolution, TieredBuildStoreResult, TieredMetroStore, TieredMetroStoreOptions, WarnOnce, buildResolveTimeoutMs, buildUploadTimeoutMs, cacheProviderConfigFromEnv, cacheProviderContractChecks, cacheProviderEnv, cacheProviderEnvIsSet, callWithTimeout, createTieredMetroStore, createWarnOnce, loadCacheProvider, metroCapabilityFromStore, resolveTieredBuild, runCacheProviderContract, storeTieredBuild, timeoutFromEnv };
+//#region files.d.ts
+/** Opaque immutable files in a caller-owned directory, with atomic publication and cancellable downloads. */
+declare function createFilesystemFileCache(directory: string): FileCacheCapability & Required<Pick<FileCacheCapability, "stat">>;
+//#endregion
+export { BUILD_RESOLVE_TIMEOUT_ENV, BUILD_RESOLVE_TIMEOUT_MS, BUILD_UPLOAD_TIMEOUT_ENV, BUILD_UPLOAD_TIMEOUT_MS, BuildCacheCapability, BuildCacheContext, BuildCacheTarget, BuildResolveInput, BuildStoreInput, CACHE_CONTRACT_CHECK_TIMEOUT_MS, CACHE_PROVIDER_API_VERSION, CACHE_PROVIDER_ENV, CACHE_PROVIDER_ENV_NONE, CacheContractCheck, CacheContractModuleOptions, CacheContractOptions, CacheContractResult, CacheProvider, CacheProviderConfig, CacheProviderModule, FileCacheCapability, FileCacheResolveInput, FileCacheStoreInput, LoadBuildProvider, LoadCacheProviderResult, METRO_READ_CONCURRENCY, METRO_READ_FAILURE_LIMIT, METRO_READ_TIMEOUT_ENV, METRO_READ_TIMEOUT_MS, METRO_UPLOAD_CONCURRENCY, METRO_UPLOAD_MAX_BYTES, METRO_UPLOAD_MAX_ITEMS, METRO_WRITE_TIMEOUT_ENV, METRO_WRITE_TIMEOUT_MS, MetroCacheCapability, MetroCacheContext, MetroCacheGetInput, MetroCacheSetInput, MetroCacheStore, MetroTierLimits, MetroTierTimeouts, PROVIDER_LOAD_TIMEOUT_ENV, PROVIDER_LOAD_TIMEOUT_MS, ProviderCallResult, ResolveTieredBuildOptions, StoreTieredBuildOptions, TieredBuildResolution, TieredBuildStoreResult, TieredMetroStore, TieredMetroStoreOptions, WarnOnce, buildResolveTimeoutMs, buildUploadTimeoutMs, cacheProviderConfigFromEnv, cacheProviderContractChecks, cacheProviderEnv, cacheProviderEnvIsSet, callWithTimeout, createFilesystemFileCache, createTieredMetroStore, createWarnOnce, loadCacheProvider, metroCapabilityFromStore, resolveTieredBuild, runCacheProviderContract, storeTieredBuild, timeoutFromEnv };

package/dist/index.mjs

@@ -1,8 +1,10 @@
 import { createRequire } from "node:module";
 import { join, relative, sep } from "node:path";
 import { pathToFileURL } from "node:url";
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { randomBytes, randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { link, lstat, mkdir, rename, rm } from "node:fs/promises";
+import { pipeline } from "node:stream/promises";
 //#region provider.ts
 const CACHE_PROVIDER_API_VERSION = 1;
 const CACHE_PROVIDER_ENV = "STIM_CACHE_PROVIDER_CONFIG";
@@ -31,11 +33,13 @@ function moduleCandidate(namespace) {
 	return "default" in namespace ? namespace.default : namespace;
 }
 function capabilityError(provider) {
+	const files = provider.files;
+	if (files !== void 0 && (typeof files?.resolve !== "function" || typeof files?.store !== "function")) return "the files capability must implement resolve() and store()";
 	const metro = provider.metro;
 	if (metro !== void 0 && (typeof metro?.get !== "function" || typeof metro?.set !== "function")) return "the metro capability must implement get() and set()";
 	const builds = provider.builds;
 	if (builds !== void 0 && (typeof builds?.resolve !== "function" || typeof builds?.store !== "function")) return "the builds capability must implement resolve() and store()";
-	if (metro === void 0 && builds === void 0) return "the provider advertises neither a metro nor a builds capability";
+	if (metro === void 0 && builds === void 0 && files === void 0) return "the provider advertises no files, metro or builds capability";
 	return null;
 }
 async function loadCacheProvider({ projectRoot, config, timeoutMs = timeoutFromEnv(PROVIDER_LOAD_TIMEOUT_ENV, PROVIDER_LOAD_TIMEOUT_MS) }) {
@@ -107,8 +111,11 @@ async function importCacheProvider({ projectRoot, config, reference }) {
 		provider
 	};
 }
-async function callWithTimeout(call, timeoutMs) {
+async function callWithTimeout(call, timeoutMs, signal) {
+	signal?.throwIfAborted();
 	const controller = new AbortController();
+	const abort = () => controller.abort(signal?.reason);
+	signal?.addEventListener("abort", abort, { once: true });
 	let timer = null;
 	const expired = new Promise((resolve) => {
 		timer = setTimeout(() => {
@@ -117,9 +124,14 @@ async function callWithTimeout(call, timeoutMs) {
 		}, timeoutMs);
 	});
 	try {
-		const outcome = await Promise.race([Promise.resolve().then(() => call(controller.signal)).then((value) => ({ value }), (error) => ({ failed: reason(error) })), expired]);
+		const outcome = await Promise.race([Promise.resolve().then(() => {
+			signal?.throwIfAborted();
+			return call(controller.signal);
+		}).then((value) => ({ value }), (error) => ({ failed: reason(error) })), expired]);
+		signal?.throwIfAborted();
 		return outcome === "timeout" ? { timedOut: true } : outcome;
 	} finally {
+		signal?.removeEventListener("abort", abort);
 		if (timer) clearTimeout(timer);
 	}
 }
@@ -386,9 +398,10 @@ function buildResolveTimeoutMs(env) {
 function buildUploadTimeoutMs(env) {
 	return timeoutFromEnv(BUILD_UPLOAD_TIMEOUT_ENV, BUILD_UPLOAD_TIMEOUT_MS, env);
 }
-async function providerTier(loadProvider, warn) {
+async function providerTier(loadProvider, warn, signal) {
 	if (!loadProvider) return null;
 	const loaded = await loadProvider();
+	signal?.throwIfAborted();
 	if (loaded?.unavailable) {
 		warn("provider-load", `provider not usable (${loaded.name ?? "the cache provider"}): ${loaded.unavailable}; using local cache`);
 		return null;
@@ -404,26 +417,29 @@ function neverAborted$1() {
 	return new AbortController().signal;
 }
 function ignore() {}
-async function resolveTieredBuild({ local, loadProvider = null, target, destinationDir, ensureDestination, skipRead = false, warn = ignore, timeoutMs = buildResolveTimeoutMs() }) {
+async function resolveTieredBuild({ local, loadProvider = null, target, destinationDir, ensureDestination, skipRead = false, warn = ignore, timeoutMs = buildResolveTimeoutMs(), signal = neverAborted$1() }) {
+	signal.throwIfAborted();
 	if (skipRead) return null;
 	const hit = await local.resolve({
 		...target,
 		destinationDir,
-		signal: neverAborted$1()
+		signal
 	});
+	signal.throwIfAborted();
 	if (hit) return {
 		path: hit,
 		tier: "local"
 	};
-	const tier = await providerTier(loadProvider, warn);
+	const tier = await providerTier(loadProvider, warn, signal);
+	signal.throwIfAborted();
 	if (!tier) return null;
 	const { capability: provider, name: label } = tier;
 	ensureDestination?.(destinationDir);
-	const outcome = await callWithTimeout((signal) => provider.resolve({
+	const outcome = await callWithTimeout((childSignal) => provider.resolve({
 		...target,
 		destinationDir,
-		signal
-	}), timeoutMs);
+		signal: childSignal
+	}), timeoutMs, signal);
 	if (outcome.timedOut) {
 		warn("provider-resolve", `${label} did not answer within ${timeoutMs}ms; building instead`);
 		return null;
@@ -444,11 +460,13 @@ async function resolveTieredBuild({ local, loadProvider = null, target, destinat
 			...target,
 			sourcePath: path,
 			overwrite: false,
-			signal: neverAborted$1()
+			signal
 		}) || null;
 	} catch (error) {
+		signal.throwIfAborted();
 		warn("provider-backfill", `a ${label} hit could not be stored locally: ${String(error?.message || error)}`);
 	}
+	signal.throwIfAborted();
 	return {
 		path: stored || path,
 		tier: "provider",
@@ -456,29 +474,34 @@ async function resolveTieredBuild({ local, loadProvider = null, target, destinat
 		storedLocally: Boolean(stored)
 	};
 }
-async function storeTieredBuild({ local, loadProvider = null, target, sourcePath, overwrite, warn = ignore, timeoutMs = buildUploadTimeoutMs() }) {
+async function storeTieredBuild({ local, loadProvider = null, target, sourcePath, overwrite, warn = ignore, timeoutMs = buildUploadTimeoutMs(), signal = neverAborted$1() }) {
+	signal.throwIfAborted();
 	const localPath = await local.store({
 		...target,
 		sourcePath,
 		overwrite,
-		signal: neverAborted$1()
+		signal
 	}) || null;
-	const tier = await providerTier(loadProvider, warn);
+	signal.throwIfAborted();
+	const tier = await providerTier(loadProvider, warn, signal);
+	signal.throwIfAborted();
 	if (!tier) return {
 		localPath,
 		providerUpload: null,
 		providerName: null
 	};
+	const providerUpload = callWithTimeout(async (childSignal) => {
+		await tier.capability.store({
+			...target,
+			sourcePath,
+			overwrite,
+			signal: childSignal
+		});
+	}, timeoutMs, signal);
+	providerUpload.catch(() => {});
 	return {
 		localPath,
-		providerUpload: callWithTimeout(async (signal) => {
-			await tier.capability.store({
-				...target,
-				sourcePath,
-				overwrite,
-				signal
-			});
-		}, timeoutMs),
+		providerUpload,
 		providerName: tier.name
 	};
 }
@@ -886,4 +909,74 @@ async function withDeadline(work, timeoutMs) {
 	}
 }
 //#endregion
-export { BUILD_RESOLVE_TIMEOUT_ENV, BUILD_RESOLVE_TIMEOUT_MS, BUILD_UPLOAD_TIMEOUT_ENV, BUILD_UPLOAD_TIMEOUT_MS, CACHE_CONTRACT_CHECK_TIMEOUT_MS, CACHE_PROVIDER_API_VERSION, CACHE_PROVIDER_ENV, CACHE_PROVIDER_ENV_NONE, METRO_READ_CONCURRENCY, METRO_READ_FAILURE_LIMIT, METRO_READ_TIMEOUT_ENV, METRO_READ_TIMEOUT_MS, METRO_UPLOAD_CONCURRENCY, METRO_UPLOAD_MAX_BYTES, METRO_UPLOAD_MAX_ITEMS, METRO_WRITE_TIMEOUT_ENV, METRO_WRITE_TIMEOUT_MS, PROVIDER_LOAD_TIMEOUT_ENV, PROVIDER_LOAD_TIMEOUT_MS, buildResolveTimeoutMs, buildUploadTimeoutMs, cacheProviderConfigFromEnv, cacheProviderContractChecks, cacheProviderEnv, cacheProviderEnvIsSet, callWithTimeout, createTieredMetroStore, createWarnOnce, loadCacheProvider, metroCapabilityFromStore, resolveTieredBuild, runCacheProviderContract, storeTieredBuild, timeoutFromEnv };
+//#region files.ts
+/** Opaque immutable files in a caller-owned directory, with atomic publication and cancellable downloads. */
+function createFilesystemFileCache(directory) {
+	const entry = (key) => join(directory, createHash("sha256").update(key).digest("hex"));
+	const present = async ({ key, signal }) => {
+		signal.throwIfAborted();
+		try {
+			const info = await lstat(entry(key));
+			signal.throwIfAborted();
+			return info.isFile() ? { size: info.size } : null;
+		} catch (error) {
+			if ((error instanceof Error && "code" in error ? error.code : void 0) === "ENOENT") return null;
+			throw error;
+		}
+	};
+	return {
+		stat: present,
+		async resolve({ key, destinationDir, signal }) {
+			if (!await present({
+				key,
+				signal
+			})) return null;
+			const temporary = join(destinationDir, `${randomUUID()}.partial`);
+			const complete = join(destinationDir, `${randomUUID()}.cache`);
+			try {
+				await mkdir(destinationDir, {
+					recursive: true,
+					mode: 448
+				});
+				await pipeline(createReadStream(entry(key)), createWriteStream(temporary, {
+					flags: "wx",
+					mode: 384
+				}), { signal });
+				signal.throwIfAborted();
+				await rename(temporary, complete);
+				return complete;
+			} catch (error) {
+				signal.throwIfAborted();
+				if ((error instanceof Error && "code" in error ? error.code : void 0) === "ENOENT") return null;
+				throw error;
+			} finally {
+				await rm(temporary, { force: true });
+			}
+		},
+		async store({ key, sourcePath, overwrite, signal }) {
+			signal.throwIfAborted();
+			await mkdir(directory, {
+				recursive: true,
+				mode: 448
+			});
+			const temporary = join(directory, `${randomUUID()}.partial`);
+			try {
+				await pipeline(createReadStream(sourcePath), createWriteStream(temporary, {
+					flags: "wx",
+					mode: 384
+				}), { signal });
+				signal.throwIfAborted();
+				if (overwrite) await rename(temporary, entry(key));
+				else try {
+					await link(temporary, entry(key));
+				} catch (error) {
+					if ((error instanceof Error && "code" in error ? error.code : void 0) !== "EEXIST") throw error;
+				}
+			} finally {
+				await rm(temporary, { force: true });
+			}
+		}
+	};
+}
+//#endregion
+export { BUILD_RESOLVE_TIMEOUT_ENV, BUILD_RESOLVE_TIMEOUT_MS, BUILD_UPLOAD_TIMEOUT_ENV, BUILD_UPLOAD_TIMEOUT_MS, CACHE_CONTRACT_CHECK_TIMEOUT_MS, CACHE_PROVIDER_API_VERSION, CACHE_PROVIDER_ENV, CACHE_PROVIDER_ENV_NONE, METRO_READ_CONCURRENCY, METRO_READ_FAILURE_LIMIT, METRO_READ_TIMEOUT_ENV, METRO_READ_TIMEOUT_MS, METRO_UPLOAD_CONCURRENCY, METRO_UPLOAD_MAX_BYTES, METRO_UPLOAD_MAX_ITEMS, METRO_WRITE_TIMEOUT_ENV, METRO_WRITE_TIMEOUT_MS, PROVIDER_LOAD_TIMEOUT_ENV, PROVIDER_LOAD_TIMEOUT_MS, buildResolveTimeoutMs, buildUploadTimeoutMs, cacheProviderConfigFromEnv, cacheProviderContractChecks, cacheProviderEnv, cacheProviderEnvIsSet, callWithTimeout, createFilesystemFileCache, createTieredMetroStore, createWarnOnce, loadCacheProvider, metroCapabilityFromStore, resolveTieredBuild, runCacheProviderContract, storeTieredBuild, timeoutFromEnv };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stim-cli/cache",
-  "version": "1.20.1",
+  "version": "1.21.0",
   "description": "Cache provider contract and tier coordination for Stim.",
   "license": "MIT",
   "repository": {