add env variable to specify which downloadable emulator version to use

CHANGELOG.md

@@ -1,2 +1,3 @@
+- Added `*_EMULATOR_VERSION` env variables to allow overriding specific versions of downloadable emulators
 - Updated the functions.config deprecation notice from March 2026 to March 2027 (#9941)
 - Detects when App Hosting fails to deploy, returning an error. (#8866)

src/downloadUtils.ts

@@ -12,7 +12,7 @@
  * @param remoteUrl URL to download.
  * @param auth Whether to include an access token in the download request. Defaults to false.
  */
 export async function downloadToTmp(remoteUrl: string, auth: boolean = false): Promise<string> {
   const u = new URL(remoteUrl);
   const c = new Client({ urlPrefix: u.origin, auth });
   const tmpfile = tmp.fileSync();
@@ -27,7 +27,9 @@
     resolveOnHTTPError: true,
   });
   if (res.status !== 200) {
-    throw new FirebaseError(`download failed, status ${res.status}: ${await res.response.text()}`);
+    throw new FirebaseError(`download failed, status ${res.status}: ${await res.response.text()}`, {
+      status: res.status,
+    });
   }
 
   const total = parseInt(res.response.headers.get("content-length") || "0", 10);

src/emulator/download.ts

@@ -12,24 +12,43 @@
 
 tmp.setGracefulCleanup();
 
 export async function downloadEmulator(name: DownloadableEmulators): Promise<void> {
   const emulator = downloadableEmulators.getDownloadDetails(name);
   if (emulator.localOnly) {
     EmulatorLogger.forEmulator(name).logLabeled(
       "WARN",
       name,
       `Env variable override detected, skipping download. Using ${emulator} emulator at ${emulator.binaryPath}`,
     );
     return;
   }
+  const overrideVersion = downloadableEmulators.emulatorVersionOverride(name);
+  if (overrideVersion) {
+    EmulatorLogger.forEmulator(name).logLabeled(
+      "WARN",
+      name,
+      `Env variable override detected. Using custom ${name} emulator version ${overrideVersion}.`,
+    );
+  }
   EmulatorLogger.forEmulator(name).logLabeled(
     "BULLET",
     name,
     `downloading ${path.basename(emulator.downloadPath)}...`,
   );
   fs.ensureDirSync(emulator.opts.cacheDir);
 
-  const tmpfile = await downloadUtils.downloadToTmp(emulator.opts.remoteUrl, !!emulator.opts.auth);
+  let tmpfile: string;
+  try {
+    tmpfile = await downloadUtils.downloadToTmp(emulator.opts.remoteUrl, !!emulator.opts.auth);
+  } catch (err: any) {
+    if (overrideVersion && err instanceof FirebaseError && err.status === 404) {
+      throw new FirebaseError(
+        `env variable ${name.toUpperCase()}_EMULATOR_VERSION set to ${overrideVersion}, 
+        but no such version of ${name} was found. Please double check the version number, or unset this environment variable to use the latest default.`,
+      );
+    }
+    throw err;
+  }
 
   if (!emulator.opts.skipChecksumAndSize) {
     await validateSize(tmpfile, emulator.opts.expectedSize);
@@ -51,7 +70,7 @@
   removeOldFiles(name, emulator);
 }
 
 export async function downloadExtensionVersion(
   extensionVersionRef: string,
   sourceDownloadUri: string,
   targetDir: string,
@@ -94,7 +113,7 @@
   for (const file of files) {
     const fullFilePath = path.join(emulator.opts.cacheDir, file);
 
     if (file.indexOf(emulator.opts.namePrefix) < 0) {
       // This file is not related to this emulator, could be a JAR
       // from a different emulator or just a random file.
       continue;
@@ -138,7 +157,7 @@
   return new Promise((resolve, reject) => {
     const hash = crypto.createHash("md5");
     const stream = fs.createReadStream(filepath);
     stream.on("data", (data: any) => hash.update(data));
     stream.on("end", () => {
       const checksum = hash.digest("hex");
       return checksum === expectedChecksum

src/emulator/downloadableEmulators.spec.ts

@@ -83,4 +83,22 @@ describe("downloadDetails", () => {
       emulatorUpdateDetails.dataconnect.darwin_arm64.remoteUrl,
     );
   });
+
+  it("should override emulator version when PUBSUB_EMULATOR_VERSION is set", () => {
+    const fakeVersion = "1.2.3";
+    sandbox.stub(process, "env").value({
+      ...process.env,
+      PUBSUB_EMULATOR_VERSION: fakeVersion,
+    });
+
+    const pubsubEmulatorDetails = downloadableEmulators.getDownloadDetails(Emulators.PUBSUB);
+    expect(pubsubEmulatorDetails.version).to.equal(fakeVersion);
+    expect(pubsubEmulatorDetails.downloadPath).to.contain(fakeVersion);
+    expect(pubsubEmulatorDetails.opts.remoteUrl).to.contain(fakeVersion);
+    expect(pubsubEmulatorDetails.opts.skipChecksumAndSize).to.be.true;
+
+    expect(downloadableEmulators.emulatorVersionOverride(Emulators.FIRESTORE)).to.be.undefined;
+    expect(downloadableEmulators.emulatorVersionOverride(Emulators.DATABASE)).to.be.undefined;
+    expect(downloadableEmulators.emulatorVersionOverride(Emulators.PUBSUB)).to.equal(fakeVersion);
+  });
 });

src/emulator/downloadableEmulators.ts

@@ -1,4 +1,4 @@
 const lsofi = require("lsofi");
 import {
   Emulators,
   DownloadableEmulators,
@@ -66,9 +66,11 @@
         ? EMULATOR_UPDATE_DETAILS.dataconnect.win32
         : EMULATOR_UPDATE_DETAILS.dataconnect.linux;
 
+  let details: EmulatorDownloadDetails;
+  const overrideVersion = emulatorVersionOverride(emulator);
   switch (emulator) {
     case "database":
-      return {
+      details = {
         downloadPath: path.join(
           CACHE_DIR,
           EMULATOR_UPDATE_DETAILS.database.downloadPathRelativeToCacheDir,
@@ -80,8 +82,9 @@
           namePrefix: "firebase-database-emulator",
         },
       };
+      break;
     case "firestore":
-      return {
+      details = {
         downloadPath: path.join(
           CACHE_DIR,
           EMULATOR_UPDATE_DETAILS.firestore.downloadPathRelativeToCacheDir,
@@ -93,8 +96,9 @@
           namePrefix: "cloud-firestore-emulator",
         },
       };
+      break;
     case "storage":
-      return {
+      details = {
         downloadPath: path.join(
           CACHE_DIR,
           EMULATOR_UPDATE_DETAILS.storage.downloadPathRelativeToCacheDir,
@@ -106,8 +110,9 @@
           namePrefix: "cloud-storage-rules-emulator",
         },
       };
+      break;
     case "ui":
-      return {
+      details = {
         version: emulatorUiDetails.version,
         downloadPath: path.join(CACHE_DIR, emulatorUiDetails.downloadPathRelativeToCacheDir),
         unzipDir: path.join(CACHE_DIR, `ui-v${emulatorUiDetails.version}`),
@@ -120,8 +125,9 @@
           namePrefix: "ui",
         },
       };
+      break;
     case "pubsub":
-      return {
+      details = {
         downloadPath: path.join(
           CACHE_DIR,
           EMULATOR_UPDATE_DETAILS.pubsub.downloadPathRelativeToCacheDir,
@@ -138,8 +144,9 @@
           namePrefix: "pubsub-emulator",
         },
       };
+      break;
     case "dataconnect":
-      return {
+      details = {
         downloadPath: path.join(CACHE_DIR, dataconnectDetails.downloadPathRelativeToCacheDir),
         version: dataconnectDetails.version,
         binaryPath: path.join(CACHE_DIR, dataconnectDetails.downloadPathRelativeToCacheDir),
@@ -151,9 +158,29 @@
           auth: false,
         },
       };
+      break;
     default:
       throw new Error(`Invalid downloadable emulator: ${emulator}`);
   }
+
+  if (overrideVersion && overrideVersion !== details.version) {
+    const oldVersion = details.version;
+    const replaceVersion = (s: string) => s.split(oldVersion).join(overrideVersion);
+
+    details.version = overrideVersion;
+    details.downloadPath = replaceVersion(details.downloadPath);
+    if (details.unzipDir) {
+      details.unzipDir = replaceVersion(details.unzipDir);
+    }
+    if (details.binaryPath) {
+      details.binaryPath = replaceVersion(details.binaryPath);
+    }
+
+    details.opts.remoteUrl = replaceVersion(details.opts.remoteUrl);
+    details.opts.skipChecksumAndSize = true;
+  }
+
+  return details;
 }
 
 const EmulatorDetails: { [s in DownloadableEmulators]: DownloadableEmulatorDetails } = {
@@ -631,3 +658,7 @@
     process.platform === "darwin"
   );
 }
+
+export function emulatorVersionOverride(emulator: DownloadableEmulators) {
+  return process.env[`${emulator.toUpperCase()}_EMULATOR_VERSION`];
+}