feat: Add support for function prefixes (#8911)

This change adds a new `prefix` property to firebase functions configuration in firebase.json. The new property can be used to prepend function name with the given prefix for all functions in the codebase.

Note that prefix is also used for all secret associated with the codebase to allow different codebases to refer to different configuration value.

The new feature also requires two new validation rules for function configurations in `firebase.json`:

1.  The `prefix` property, if specified, must only contain lowercase letters, numbers, and hyphens.
2.  The combination of `source` and `prefix` must be unique across all function configurations.

These changes ensure that function deployments with prefixes are valid and that there are no conflicts when deploying multiple functions from the same source directory.

Author: taeold

.gitignore

@@ -15,6 +15,8 @@ firebase-debug.log
 firebase-debug.*.log
 npm-debug.log
 ui-debug.log
+test_output.log
+scripts/emulator-tests/functions/index.js
 yarn.lock
 .npmrc
 

CHANGELOG.md

@@ -1 +1,2 @@
+- Added prefix support for multi-instance Cloud Functions extension parameters. (#8911)
 - Fixed a bug when `firebase deploy --only dataconnect` doesn't include GQL in nested folders (#8981)

schema/firebase-config.json

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

scripts/emulator-tests/functionsEmulator.spec.ts

@@ -760,6 +760,52 @@ 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",
+      };
+
+      const prefixEmu = 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 });
+            },
+          ),
+        };
+      });
+
+      try {
+        await registry.EmulatorRegistry.start(prefixEmu);
+        await prefixEmu.connect();
+
+        await supertest(prefixEmu.createHubServer())
+          .get(`/${TEST_PROJECT_ID}/us-central1/prefix-one-functionId`)
+          .expect(200);
+
+        await supertest(prefixEmu.createHubServer())
+          .get(`/${TEST_PROJECT_ID}/us-central1/prefix-two-functionId`)
+          .expect(200);
+      } finally {
+        await registry.EmulatorRegistry.stop(Emulators.FUNCTIONS);
+      }
+    });
+
     describe("user-defined environment variables", () => {
       let cleanup: (() => Promise<void>) | undefined;
 

src/deploy/functions/build.spec.ts

@@ -293,3 +293,120 @@ describe("envWithType", () => {
     expect(out.WHOOPS_SECRET.asString()).to.equal("super-secret");
   });
 });
+
+describe("applyPrefix", () => {
+  const createTestBuild = (): build.Build => ({
+    endpoints: {
+      func1: {
+        region: "us-central1",
+        project: "test-project",
+        platform: "gcfv2",
+        runtime: "nodejs18",
+        entryPoint: "func1",
+        httpsTrigger: {},
+      },
+      func2: {
+        region: "us-west1",
+        project: "test-project",
+        platform: "gcfv1",
+        runtime: "nodejs16",
+        entryPoint: "func2",
+        httpsTrigger: {},
+      },
+    },
+    params: [],
+    requiredAPIs: [],
+  });
+
+  it("should update endpoint keys with prefix", () => {
+    const testBuild = createTestBuild();
+    build.applyPrefix(testBuild, "test");
+    expect(Object.keys(testBuild.endpoints).sort()).to.deep.equal(["test-func1", "test-func2"]);
+    expect(testBuild.endpoints["test-func1"].entryPoint).to.equal("func1");
+    expect(testBuild.endpoints["test-func2"].entryPoint).to.equal("func2");
+  });
+
+  it("should do nothing for an empty prefix", () => {
+    const testBuild = createTestBuild();
+    build.applyPrefix(testBuild, "");
+    expect(Object.keys(testBuild.endpoints).sort()).to.deep.equal(["func1", "func2"]);
+  });
+
+  it("should prefix secret names in secretEnvironmentVariables", () => {
+    const testBuild: build.Build = {
+      endpoints: {
+        func1: {
+          region: "us-central1",
+          project: "test-project",
+          platform: "gcfv2",
+          runtime: "nodejs18",
+          entryPoint: "func1",
+          httpsTrigger: {},
+          secretEnvironmentVariables: [
+            { key: "API_KEY", secret: "api-secret", projectId: "test-project" },
+            { key: "DB_PASSWORD", secret: "db-secret", projectId: "test-project" },
+          ],
+        },
+        func2: {
+          region: "us-west1",
+          project: "test-project",
+          platform: "gcfv1",
+          runtime: "nodejs16",
+          entryPoint: "func2",
+          httpsTrigger: {},
+          secretEnvironmentVariables: [
+            { key: "SERVICE_TOKEN", secret: "service-secret", projectId: "test-project" },
+          ],
+        },
+      },
+      params: [],
+      requiredAPIs: [],
+    };
+
+    build.applyPrefix(testBuild, "staging");
+
+    expect(Object.keys(testBuild.endpoints).sort()).to.deep.equal([
+      "staging-func1",
+      "staging-func2",
+    ]);
+    expect(testBuild.endpoints["staging-func1"].secretEnvironmentVariables).to.deep.equal([
+      { key: "API_KEY", secret: "staging-api-secret", projectId: "test-project" },
+      { key: "DB_PASSWORD", secret: "staging-db-secret", projectId: "test-project" },
+    ]);
+    expect(testBuild.endpoints["staging-func2"].secretEnvironmentVariables).to.deep.equal([
+      { key: "SERVICE_TOKEN", secret: "staging-service-secret", projectId: "test-project" },
+    ]);
+  });
+
+  it("throws if combined function id exceeds 63 characters", () => {
+    const longId = "a".repeat(34); // with 30-char prefix + dash = 65 total
+    const testBuild: build.Build = build.of({
+      [longId]: {
+        region: "us-central1",
+        project: "test-project",
+        platform: "gcfv2",
+        runtime: "nodejs18",
+        entryPoint: longId,
+        httpsTrigger: {},
+      },
+    });
+    const longPrefix = "p".repeat(30);
+    expect(() => build.applyPrefix(testBuild, longPrefix)).to.throw(/exceeds 63 characters/);
+  });
+
+  it("throws if prefix makes function id invalid (must start with a letter)", () => {
+    const testBuild: build.Build = build.of({
+      func: {
+        region: "us-central1",
+        project: "test-project",
+        platform: "gcfv2",
+        runtime: "nodejs18",
+        entryPoint: "func",
+        httpsTrigger: {},
+      },
+    });
+    expect(() => build.applyPrefix(testBuild, "1abc")).to.throw(
+      /Function names must start with a letter/,
+    );
+  });
+});

src/deploy/functions/build.ts

@@ -321,6 +321,9 @@ export async function resolveBackend(
 }
 
 // Exported for testing
+/**
+ *
+ */
 export function envWithTypes(
   definedParams: params.Param[],
   rawEnvs: Record<string, string>,
@@ -651,3 +654,41 @@ function discoverTrigger(endpoint: Endpoint, region: string, r: Resolver): backe
   }
   assertExhaustive(endpoint);
 }
+
+/**
+ * Prefixes all endpoint IDs and secret names in a build with a given prefix.
+ * This ensures that functions and their associated secrets from different codebases
+ * remain isolated and don't conflict when deployed to the same project.
+ */
+export function applyPrefix(build: Build, prefix: string): void {
+  if (!prefix) {
+    return;
+  }
+  const newEndpoints: Record<string, Endpoint> = {};
+  for (const [id, endpoint] of Object.entries(build.endpoints)) {
+    const newId = `${prefix}-${id}`;
+
+    // Enforce function id constraints early for clearer errors.
+    if (newId.length > 63) {
+      throw new FirebaseError(
+        `Function id '${newId}' exceeds 63 characters after applying prefix '${prefix}'. Please shorten the prefix or function name.`,
+      );
+    }
+    const fnIdRegex = /^[a-zA-Z][a-zA-Z0-9_-]{0,62}$/;
+    if (!fnIdRegex.test(newId)) {
+      throw new FirebaseError(
+        `Function id '${newId}' is invalid after applying prefix '${prefix}'. Function names must start with a letter and can contain letters, numbers, underscores, and hyphens, with a maximum length of 63 characters.`,
+      );
+    }
+
+    newEndpoints[newId] = endpoint;
+
+    if (endpoint.secretEnvironmentVariables) {
+      endpoint.secretEnvironmentVariables = endpoint.secretEnvironmentVariables.map((secret) => ({
+        ...secret,
+        secret: `${prefix}-${secret.secret}`,
+      }));
+    }
+  }
+  build.endpoints = newEndpoints;
+}