Reuse the toolchain manifest for 12 hours so offline compiles exit

Offline on a network without internet, the manifest request timed out and
the compile used the cache, but the aborted request's DNS lookup stayed
pending and the CLI could not exit after "Saved firmware". A cached manifest
younger than 12 h (Workbench's TTL) is now used with no request; a 304 renews
it, and a platform or --target the cached copy does not know fetches anyway.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: hugomontero

src/lib/toolchain/local-compiler.js

@@ -40,7 +40,11 @@ class LocalCompiler {
 	 * @returns {Promise<{ toolchain: object, dependencies: object[], platform: object }>}
 	 */
 	async resolve({ version, platformId, platformName }) {
-		const manifest = await this.fetchManifest();
+		let manifest = await this.fetchManifest();
+		if (!this._knows(manifest, { version, platformId, platformName })) {
+			// the cached copy may predate a new Device OS release or platform
+			manifest = await this.fetchManifest({ maxAgeMs: 0 });
+		}
 		const platform = manifest.platform(platformId);
 		if (!platform) {
 			throw new Error(`The local toolchain does not support ${platformName}; use --compiler cloud`);
@@ -230,6 +234,18 @@ class LocalCompiler {
 		return path.join(this.installer.rootFor(tools), declared || 'bin/bash.exe');
 	}
 
+	_knows(manifest, { version, platformId, platformName }) {
+		if (!manifest.platform(platformId)) {
+			return false;
+		}
+		try {
+			manifest.resolveToolchain({ version, platformId, platformName });
+			return true;
+		} catch (_error) {
+			return false;
+		}
+	}
+
 	_write(message) {
 		if (!this.ui.quiet) {
 			this.ui.write(message);

src/lib/toolchain/local-compiler.test.js

@@ -80,6 +80,25 @@ describe('Local compiler', () => {
 			expect(installer.ensureInstalled).to.have.been.calledWith(dependencies, { label: 'Local toolchain for Device OS 6.4.1 (argon)' });
 		});
 
+		it('trusts the cached manifest when it knows the requested version', async () => {
+			const fetchManifest = sinon.stub().resolves(manifest);
+			compiler.fetchManifest = fetchManifest;
+			await compiler.resolve({ version: '6.4.1', platformId: 12, platformName: 'argon' });
+			expect(fetchManifest).to.have.been.calledOnceWithExactly();
+		});
+
+		it('asks the server again when the cached manifest predates the requested version', async () => {
+			const data = await fs.readJson(path.join(PATH_FIXTURES_DIR, 'toolchain', 'manifest.json'));
+			const stale = new ToolchainManifest({ ...data, toolchains: data.toolchains.filter(t => t.version !== '6.4.1') });
+			const fetchManifest = sinon.stub();
+			fetchManifest.onFirstCall().resolves(stale);
+			fetchManifest.onSecondCall().resolves(manifest);
+			compiler.fetchManifest = fetchManifest;
+			const { toolchain } = await compiler.resolve({ version: '6.4.1', platformId: 12, platformName: 'argon' });
+			expect(toolchain.version).to.equal('6.4.1');
+			expect(fetchManifest.secondCall).to.have.been.calledWithExactly({ maxAgeMs: 0 });
+		});
+
 		it('rejects a platform the manifest does not know', async () => {
 			await expect(compiler.resolve({ platformId: 42, platformName: 'tachyon' }))
 				.to.be.rejectedWith('The local toolchain does not support tachyon; use --compiler cloud');

src/lib/toolchain/manifest.js

@@ -8,6 +8,9 @@ const ParticleCache = require('../particle-cache');
 const MANIFEST_URL = 'https://binaries.particle.io/toolchain-manager/manifest.json';
 const MANIFEST_CACHE_KEY = 'toolchain-manifest';
 const MANIFEST_TIMEOUT_MS = 4000;
+// Workbench's TTL. Within it a local compile makes no network request: offline, an aborted
+// request would still leave its DNS lookup pending and keep the CLI from exiting.
+const MANIFEST_MAX_AGE_MS = 12 * 60 * 60 * 1000;
 
 // The dependency kinds a local compile needs, in the order the environment is
 // built from them. `debuggers` (openocd) is deliberately left out.
@@ -116,22 +119,27 @@ class ToolchainManifest {
 }
 
 /**
- * Fetches the manifest, using the cached copy when the server says it is
- * unchanged or cannot be reached. Throws only when there is neither.
+ * Fetches the manifest, using the cached copy when it is younger than `maxAgeMs`,
+ * or when the server says it is unchanged or cannot be reached. Throws only when there is neither.
  * @param {object} [opts]
  * @param {ParticleCache} [opts.cache]
  * @param {string} [opts.url]
  * @param {number} [opts.timeoutMs]
+ * @param {number} [opts.maxAgeMs] 0 always asks the server
  * @returns {Promise<ToolchainManifest>}
  */
-async function fetchManifest({ cache = new ParticleCache(), url = MANIFEST_URL, timeoutMs = MANIFEST_TIMEOUT_MS } = {}) {
+async function fetchManifest({ cache = new ParticleCache(), url = MANIFEST_URL, timeoutMs = MANIFEST_TIMEOUT_MS, maxAgeMs = MANIFEST_MAX_AGE_MS } = {}) {
 	const cached = cache.get(MANIFEST_CACHE_KEY);
+	if (cached && cached.fetchedAt && Date.now() - cached.fetchedAt < maxAgeMs) {
+		return new ToolchainManifest(cached.data);
+	}
 	const headers = cached && cached.etag ? { 'If-None-Match': cached.etag } : {};
 	const controller = new AbortController();
 	const timeout = setTimeout(() => controller.abort(), timeoutMs);
 	try {
 		const response = await fetch(url, { headers, signal: controller.signal });
 		if (response.status === 304 && cached) {
+			cache.set(MANIFEST_CACHE_KEY, { ...cached, fetchedAt: Date.now() });
 			return new ToolchainManifest(cached.data);
 		}
 		if (!response.ok) {
@@ -154,6 +162,7 @@ async function fetchManifest({ cache = new ParticleCache(), url = MANIFEST_URL,
 module.exports = {
 	MANIFEST_URL,
 	MANIFEST_CACHE_KEY,
+	MANIFEST_MAX_AGE_MS,
 	DEPENDENCY_KINDS,
 	ToolchainManifest,
 	fetchManifest,

src/lib/toolchain/manifest.test.js

@@ -11,7 +11,8 @@ const {
 	hostFor,
 	displayName,
 	MANIFEST_URL,
-	MANIFEST_CACHE_KEY
+	MANIFEST_CACHE_KEY,
+	MANIFEST_MAX_AGE_MS
 } = require('./manifest');
 
 const FIXTURE = path.join(PATH_FIXTURES_DIR, 'toolchain', 'manifest.json');
@@ -143,6 +144,28 @@ describe('Toolchain manifest', () => {
 			expect(manifest.toolchainForVersion('2.3.1')).to.be.an('object');
 		});
 
+		it('uses a cache younger than 12 hours without a request', async () => {
+			cache.set(MANIFEST_CACHE_KEY, { etag: '"abc"', data: json, fetchedAt: Date.now() - MANIFEST_MAX_AGE_MS + 60000 });
+			const manifest = await fetchManifest({ cache });
+			expect(manifest.toolchainForVersion('6.4.1')).to.be.an('object');
+			expect(nock.isDone()).to.equal(true);
+		});
+
+		it('asks the server once the cache is older than 12 hours, and a 304 renews it', async () => {
+			cache.set(MANIFEST_CACHE_KEY, { etag: '"abc"', data: json, fetchedAt: Date.now() - MANIFEST_MAX_AGE_MS - 1 });
+			const scope = nock('https://binaries.particle.io').get('/toolchain-manager/manifest.json').reply(304);
+			await fetchManifest({ cache });
+			expect(scope.isDone()).to.equal(true);
+			expect(Date.now() - cache.get(MANIFEST_CACHE_KEY).fetchedAt).to.be.below(5000);
+		});
+
+		it('asks the server despite a fresh cache when maxAgeMs is 0', async () => {
+			cache.set(MANIFEST_CACHE_KEY, { etag: '"abc"', data: json, fetchedAt: Date.now() });
+			const scope = nock('https://binaries.particle.io').get('/toolchain-manager/manifest.json').reply(304);
+			await fetchManifest({ cache, maxAgeMs: 0 });
+			expect(scope.isDone()).to.equal(true);
+		});
+
 		it('falls back to the cache when offline', async () => {
 			cache.set(MANIFEST_CACHE_KEY, { etag: '"abc"', data: json });
 			nock('https://binaries.particle.io').get('/toolchain-manager/manifest.json').replyWithError('ENOTFOUND');