feat: Support multi-instance function deployments

This change introduces the ability to deploy multiple instances of the same function source, each with its own configuration.

This is achieved by allowing multiple function configurations in `firebase.json`. If multiple configurations are present, each must have a unique `codebase` identifier.

This change is the first step towards implementing "Function Kits", which will allow developers to easily add pre-built backend functionality to their Firebase projects.

This change is backward-compatible. Existing `firebase.json` configurations will continue to work as before.

Author: google-labs-jules[bot]

schema/firebase-config.json

@@ -276,6 +276,9 @@
                         }
                     ]
                 },
+                "prefix": {
+                    "type": "string"
+                },
                 "runtime": {
                     "enum": [
                         "nodejs18",

scripts/emulator-tests/functionsEmulator.spec.ts

@@ -760,6 +760,48 @@ describe("FunctionsEmulator", function () {
       }).timeout(TIMEOUT_MED);
     });
 
+    it("should support multiple codebases with the same source and apply prefixes", async () => {
+      const backend1: EmulatableBackend = {
+        ...TEST_BACKEND,
+        codebase: "one",
+        prefix: "prefix-one",
+      };
+      const backend2: EmulatableBackend = {
+        ...TEST_BACKEND,
+        codebase: "two",
+        prefix: "prefix-two",
+      };
+
+      emu = new FunctionsEmulator({
+        projectId: TEST_PROJECT_ID,
+        projectDir: MODULE_ROOT,
+        emulatableBackends: [backend1, backend2],
+        verbosity: "QUIET",
+        debugPort: false,
+      });
+
+      await writeSource(() => {
+        return {
+          functionId: require("firebase-functions").https.onRequest(
+            (req: express.Request, res: express.Response) => {
+              res.json({ path: req.path });
+            },
+          ),
+        };
+      });
+
+      await emu.start();
+      await emu.connect();
+
+      await supertest(emu.createHubServer())
+        .get(`/${TEST_PROJECT_ID}/us-central1/prefix-one-functionId`)
+        .expect(200);
+
+      await supertest(emu.createHubServer())
+        .get(`/${TEST_PROJECT_ID}/us-central1/prefix-two-functionId`)
+        .expect(200);
+    });
+
     describe("user-defined environment variables", () => {
       let cleanup: (() => Promise<void>) | undefined;
 

src/deploy/functions/build.spec.ts

@@ -224,6 +224,27 @@ describe("toBackend", () => {
       expect(endpointDef.func.serviceAccount).to.equal("service-account-1@");
     }
   });
+
+  it("should apply the prefix to the function name", () => {
+    const desiredBuild: build.Build = build.of({
+      func: {
+        platform: "gcfv1",
+        region: ["us-central1"],
+        project: "project",
+        runtime: "nodejs16",
+        entryPoint: "func",
+        httpsTrigger: {},
+      },
+    });
+    const backend = build.toBackend(desiredBuild, {}, "my-prefix");
+    expect(Object.keys(backend.endpoints).length).to.equal(1);
+    const regionalEndpoints = Object.values(backend.endpoints)[0];
+    const endpoint = Object.values(regionalEndpoints)[0];
+    expect(endpoint).to.not.equal(undefined);
+    if (endpoint) {
+      expect(endpoint.id).to.equal("my-prefix-func");
+    }
+  });
 });
 
 describe("envWithType", () => {

src/deploy/functions/build.ts

@@ -287,6 +287,7 @@ interface ResolveBackendOpts {
   userEnvs: Record<string, string>;
   nonInteractive?: boolean;
   isEmulator?: boolean;
+  prefix?: string;
 }
 
 /**
@@ -316,7 +317,7 @@ export async function resolveBackend(
   }
   writeUserEnvs(toWrite, opts.userEnvOpt);
 
-  return { backend: toBackend(opts.build, paramValues), envs: paramValues };
+  return { backend: toBackend(opts.build, paramValues, opts.prefix), envs: paramValues };
 }
 
 // Exported for testing
@@ -446,6 +447,7 @@ class Resolver {
 export function toBackend(
   build: Build,
   paramValues: Record<string, params.ParamValue>,
+  prefix?: string,
 ): backend.Backend {
   const r = new Resolver(paramValues);
   const bkEndpoints: Array<backend.Endpoint> = [];
@@ -481,7 +483,7 @@ export function toBackend(
         throw new FirebaseError("platform can't be undefined");
       }
       const bkEndpoint: backend.Endpoint = {
-        id: endpointId,
+        id: prefix ? `${prefix}-${endpointId}` : endpointId,
         project: bdEndpoint.project,
         region: region,
         entryPoint: bdEndpoint.entryPoint,

src/deploy/functions/prepare.ts

@@ -135,6 +135,7 @@ export async function prepare(
       userEnvs,
       nonInteractive: options.nonInteractive,
       isEmulator: false,
+      prefix: config.prefix,
     });
 
     let hasEnvsFromParams = false;

src/emulator/controller.ts

@@ -544,6 +544,7 @@ export async function startAll(
         functionsDir,
         runtime,
         codebase: cfg.codebase,
+        prefix: cfg.prefix,
         env: {
           ...options.extDevEnv,
         },

src/emulator/functionsEmulator.ts

@@ -87,6 +87,7 @@ export interface EmulatableBackend {
   env: Record<string, string>;
   secretEnv: backend.SecretEnvVar[];
   codebase: string;
+  prefix?: string;
   predefinedTriggers?: ParsedTriggerDefinition[];
   runtime?: Runtime;
   bin?: string;
@@ -570,6 +571,7 @@ export class FunctionsEmulator implements EmulatorInstance {
         userEnvs,
         nonInteractive: false,
         isEmulator: true,
+        prefix: emulatableBackend.prefix,
       });
       const discoveredBackend = resolution.backend;
       const endpoints = backend.allEndpoints(discoveredBackend);

src/firebaseConfig.ts

@@ -170,6 +170,7 @@ export type FunctionConfig = {
   ignore?: string[];
   runtime?: ActiveRuntime;
   codebase?: string;
+  prefix?: string;
 } & Deployable;
 
 export type FunctionsConfig = FunctionConfig | FunctionConfig[];

src/functions/projectConfig.spec.ts

@@ -42,10 +42,22 @@ describe("projectConfig", () => {
       );
     });
 
-    it("fails validation given config w/ duplicate source", () => {
-      expect(() =>
-        projectConfig.validate([TEST_CONFIG_0, { ...TEST_CONFIG_0, codebase: "unique-codebase" }]),
-      ).to.throw(FirebaseError, /source must be unique/);
+    it("passes validation for multi-instance config with same source", () => {
+      const config = [
+        { source: "foo", codebase: "bar" },
+        { source: "foo", codebase: "baz" },
+      ];
+      expect(projectConfig.validate(config as projectConfig.NormalizedConfig)).to.deep.equal(
+        config,
+      );
+    });
+
+    it("fails validation for multi-instance config with missing codebase", () => {
+      const config = [{ source: "foo", codebase: "bar" }, { source: "foo" }];
+      expect(() => projectConfig.validate(config as projectConfig.NormalizedConfig)).to.throw(
+        FirebaseError,
+        /Each functions config must have a unique 'codebase' field/,
+      );
     });
 
     it("fails validation given codebase name with capital letters", () => {
@@ -72,6 +84,14 @@ describe("projectConfig", () => {
         ]),
       ).to.throw(FirebaseError, /Invalid codebase name/);
     });
+
+    it("should allow a single function in an array to have a default codebase", () => {
+      const config = [{ source: "foo" }];
+      const expected = [{ source: "foo", codebase: "default" }];
+      expect(projectConfig.validate(config as projectConfig.NormalizedConfig)).to.deep.equal(
+        expected,
+      );
+    });
   });
 
   describe("normalizeAndValidate", () => {
@@ -104,13 +124,6 @@ describe("projectConfig", () => {
       );
     });
 
-    it("fails validation given config w/ duplicate source", () => {
-      expect(() => projectConfig.normalizeAndValidate([TEST_CONFIG_0, TEST_CONFIG_0])).to.throw(
-        FirebaseError,
-        /functions.source must be unique/,
-      );
-    });
-
     it("fails validation given config w/ duplicate codebase", () => {
       expect(() =>
         projectConfig.normalizeAndValidate([

src/functions/projectConfig.ts

@@ -76,8 +76,16 @@ export function assertUnique(
  * Validate functions config.
  */
 export function validate(config: NormalizedConfig): ValidatedConfig {
+  if (config.length > 1) {
+    for (const c of config) {
+      if (!c.codebase) {
+        throw new FirebaseError(
+          "Each functions config must have a unique 'codebase' field when defining multiple functions.",
+        );
+      }
+    }
+  }
   const validated = config.map((cfg) => validateSingle(cfg)) as ValidatedConfig;
-  assertUnique(validated, "source");
   assertUnique(validated, "codebase");
   return validated;
 }