feat(functions): Implement TaskQueue Scopes by inlined · Pull Request #3210 · firebase/firebase-admin-node

inlined · 2026-07-09T19:51:20Z

Description

This PR introduces Task Queue Scopes to the Firebase Admin SDK functions module. It decouples the legacy backward-compatible string-to-scope migration logic from the stateless client and isolates it inside the API wrapper layer (TaskQueue).

Key Changes

API Wrapper Retry & Upgrade (TaskQueue):
- TaskQueue.enqueue() and delete() now capture 404 errors for legacy string parameters ('extensionOrKit' scope).
- On a 404 error, they automatically retry using a temporary kit scope.
- If the retry succeeds, the wrapper mutates the stateful scope to 'kit' and logs a legacy targeting warning.
Immediate Self-Targeting Warning:
- Matches targeting parameters against process.env.EXT_INSTANCE_ID and process.env.KIT_INSTANCE_ID at construction time.
- If self-targeting is detected, it logs an immediate deprecation/performance warning and mutates the scope immediately to 'extension' or 'kit', bypassing unnecessary 404 fallback call roundtrips.
Design style: chose to make the migration logic part of the API type and not the API internals type to more obviously collect what is transitionary/migration logic that can be removed later
Unit Tests:
- Added unit tests verifying scope resolves to global if no environment variables are set.
- Added unit tests verifying self-targeting warnings and direct namespaced resolution for both extensions and kits.

gemini-code-assist

Code Review

This pull request introduces a new FunctionScope type to represent the scope of a function in a task queue, deprecating the legacy extensionId string parameter. It updates FunctionsApiClient, Functions, and TaskQueue to support these scopes (including current, global, extension, and internal kit scopes) with fallback logic for migration, and adds comprehensive unit tests. The review feedback highlights a few issues and improvement opportunities: correcting a typo ('peformance') and an invalid scope value ({ scope: "self" } instead of { scope: "current" }) in warning messages (and their corresponding tests), removing a redundant type check in TaskQueue, and improving type safety in FunctionsApiClient by avoiding an as any cast through discriminated union narrowing.

lahirumaramba

Thank you for submitting this!
LGTM! Added a couple of comments.

lahirumaramba · 2026-07-10T18:12:40Z

   * @param id - The ID of the task to delete.
   * @param functionName - The function name of the queue.
-   * @param extensionId - Optional canonical ID of the extension.
+   * @param scope - Optional FunctionScope configuration.


Could we get a TW review on these new docstrings, please?

This looks like a literal, FunctionScope. Though, would just "function scope" work as a common noun/general term?

See bottom note here: https://docs.google.com/presentation/d/1Ezb4sp4XD6ItHISccnME-EVH_oJj59R5Naq0IskLrAo/edit?slide=id.g1cd7eabb964_0_10#slide=id.g1cd7eabb964_0_10

…fety and signature simplification

egilmorez

Thanks, I do have some nits! :)

egilmorez · 2026-07-14T18:19:27Z

   * @param id - The ID of the task to delete.
   * @param functionName - The function name of the queue.
-   * @param extensionId - Optional canonical ID of the extension.
+   * @param scope - Optional FunctionScope configuration.


This looks like a literal, FunctionScope. Though, would just "function scope" work as a common noun/general term?

See bottom note here: https://docs.google.com/presentation/d/1Ezb4sp4XD6ItHISccnME-EVH_oJj59R5Naq0IskLrAo/edit?slide=id.g1cd7eabb964_0_10#slide=id.g1cd7eabb964_0_10

egilmorez · 2026-07-14T18:20:05Z

   * @param data - The data payload of the task.
   * @param functionName - The functionName of the queue.
-   * @param extensionId - Optional canonical ID of the extension.
+   * @param scope - Optional FunctionScope configuration.


Same as above; literal?

egilmorez · 2026-07-14T18:21:29Z

@@ -132,10 +140,15 @@ export class FunctionsApiClient {
   *
   * @param data - The data payload of the task.
   * @param functionName - The functionName of the queue.


Should be either functionName or just "function name."

Better yet, more words might make it all more clear. Is it the name of the function associated with the queue, or some even better verb than "associate?"

egilmorez · 2026-07-14T18:22:31Z

   * 
   * @param functionName - The name of the function.
-   * @param extensionId - Optional Firebase extension ID.
+   * @param scope - Optional FunctionScope configuration. Only needed if targeting a scope other than the current one.


I think this should be FunctionScope with code font for the literal.

egilmorez · 2026-07-14T18:23:05Z

   * @param functionName - The name of the function.
   * @param client - The `FunctionsApiClient` instance.
-   * @param extensionId - Optional canonical ID of the extension.
+   * @param scope - Optional FunctionScope configuration. Only needed if targeting a scope other than the current one.


Same as above RE literal.

egilmorez · 2026-07-14T18:23:33Z

+  /**
+   * @param functionName - The name of the function.
+   * @param client - The `FunctionsApiClient` instance.
+   * @param extensionIdOrScope - Optional canonical ID of the extension or FunctionScope.


Probably FunctionScope

egilmorez · 2026-07-14T18:26:24Z

      }).not.to.throw();
    });
+
+    it('should not throw given a valid scope object: current', () => {


LMK if these "it('...." comments are public. I think they are not.

inlined added 3 commits June 23, 2026 15:54

Security audit: update send-email action dependencies

3f12b70

Security audit: rebuild send-email action dist

8387aad

feat(functions): Implement TaskQueue Scopes

e7f717b

gemini-code-assist Bot reviewed Jul 9, 2026

View reviewed changes

Comment thread src/functions/functions.ts

Comment thread src/functions/functions.ts

Comment thread src/functions/functions.ts Outdated

Comment thread test/unit/functions/functions-api-client-internal.spec.ts Outdated

Comment thread src/functions/functions-api-client-internal.ts Outdated

inlined added 2 commits July 9, 2026 13:10

chore: address pull request review comments

fa363cc

Merge remote-tracking branch 'origin/main' into feat/task-queue-scopes

d36ba25

inlined mentioned this pull request Jul 10, 2026

feat(functions): Implement Task Queue Scopes firebase/firebase-admin-dart#302

Open

chore(functions): Rename KIT_INSTANCE_ID to FIREBASE_KIT_INSTANCE_ID

94f6d08

lahirumaramba approved these changes Jul 10, 2026

View reviewed changes

lahirumaramba added the release-note label Jul 10, 2026

chore(functions): address second round of review comments for type sa…

fb67f7f

…fety and signature simplification

lahirumaramba added release:stage Stage a release candidate and removed release:stage Stage a release candidate labels Jul 14, 2026

inlined requested a review from egilmorez July 14, 2026 16:59

egilmorez reviewed Jul 14, 2026

View reviewed changes

Uh oh!

Conversation

inlined commented Jul 9, 2026

Description

Key Changes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lahirumaramba left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

egilmorez left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants