Merge branch 'main' into je-ref-docs

Author: jonathanedey

etc/firebase-admin.functions.api.md

@@ -37,9 +37,21 @@ export class Functions {
     //
     // (undocumented)
     readonly app: App;
-    taskQueue<Args = Record<string, any>>(functionName: string, extensionId?: string): TaskQueue<Args>;
+    taskQueue<Args = Record<string, any>>(functionName: string, scope?: FunctionScope): TaskQueue<Args>;
+    // @deprecated
+    taskQueue<Args = Record<string, any>>(functionName: string, deprecatedExtensionId: string): TaskQueue<Args>;
 }
 
+// @public
+export type FunctionScope = {
+    scope: 'current';
+} | {
+    scope: 'global';
+} | {
+    scope: 'extension';
+    instance: string;
+};
+
 // @public
 export const FunctionsErrorCode: {
     readonly ABORTED: "aborted";

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "firebase-admin",
-  "version": "14.1.0",
+  "version": "14.3.0",
   "description": "Firebase admin SDK for Node.js",
   "author": "Firebase <firebase-support@google.com> (https://firebase.google.com/)",
   "license": "Apache-2.0",
@@ -215,8 +215,8 @@
     "jwks-rsa": "^4.0.1"
   },
   "optionalDependencies": {
-    "@google-cloud/firestore": "^8.6.0",
-    "@google-cloud/storage": "^7.19.0"
+    "@google-cloud/firestore": "^8.7.1",
+    "@google-cloud/storage": "^7.22.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -237,8 +237,8 @@
     "@types/node": "^26.0.0",
     "@types/sinon": "^21.0.1",
     "@types/sinon-chai": "^3.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.62.0",
-    "@typescript-eslint/parser": "^8.62.0",
+    "@typescript-eslint/eslint-plugin": "^8.67.0",
+    "@typescript-eslint/parser": "^8.67.0",
     "bcrypt": "^6.0.0",
     "chai": "^4.2.0",
     "chai-as-promised": "^7.0.0",
@@ -266,7 +266,7 @@
     "sinon-chai": "^3.0.0",
     "ts-node": "^10.2.0",
     "typescript": "^5.7.3",
-    "typescript-eslint": "^8.62.0",
+    "typescript-eslint": "^8.67.0",
     "yargs": "^17.0.1"
   }
 }

package.json

@@ -70,10 +70,19 @@ const IMPERSONATE_MUTATION_ENDPOINT = 'impersonateMutation';
 /** @internal The maximum number of items allowed in the @allow directive's maxCount argument. */
 export const ALLOW_DIRECTIVE_MAX_COUNT = 10_000;
 
-function getHeaders(isUsingGen: boolean): { [key: string]: string } {
+interface GetHeadersParameters {
+  projectId: string;
+  serviceId: string;
+  isUsingGen: boolean;
+}
+
+function getHeaders(parameters: GetHeadersParameters): { [key: string]: string } {
+  const { projectId, serviceId, isUsingGen } = parameters;
   const headerValue = {
     'X-Firebase-Client': `fire-admin-node/${utils.getSdkVersion()}`,
     'X-Goog-Api-Client': utils.getMetricsHeader(),
+    'X-Client-Version': `Node/Admin/${utils.getSdkVersion()}`,
+    'X-Firebase-Sqlconnect-Affinity': `${projectId}${serviceId}`,
   };
   if (isUsingGen) {
     headerValue['X-Goog-Api-Client'] += ' admin-js/gen';
@@ -385,10 +394,15 @@ export class DataConnectApiClient {
    */
   private async makeGqlRequest<GraphqlResponse>(url: string, data: object): 
   Promise<ExecuteGraphqlResponse<GraphqlResponse>> {
+    const projectId = await this.getProjectId();
     const request: HttpRequestConfig = {
       method: 'POST',
       url,
-      headers: getHeaders(this.isUsingGen),
+      headers: getHeaders({
+        projectId,
+        serviceId: this.connectorConfig.serviceId,
+        isUsingGen: this.isUsingGen,
+      }),
       data,
     };
     const resp = await this.httpClient.send(request);

src/data-connect/data-connect-api-client-internal.ts

@@ -24,9 +24,17 @@ import { FirebaseError, toHttpResponse } from '../utils/error';
 import { FirebaseFunctionsError, FunctionsErrorCode, FUNCTIONS_ERROR_CODE_MAPPING } from './error';
 import * as utils from '../utils/index';
 import * as validator from '../utils/validator';
-import { TaskOptions } from './functions-api';
+import { TaskOptions, FunctionScope } from './functions-api';
 import { ApplicationDefaultCredential } from '../app/credential-internal';
 
+export type InternalFunctionScope = FunctionScope | {
+  scope: 'kit';
+  instance: string;
+} | {
+  scope: 'extensionOrKit';
+  instance: string;
+};
+
 const CLOUD_TASKS_API_RESOURCE_PATH = 'projects/{projectId}/locations/{locationId}/queues/{resourceId}/tasks';
 const CLOUD_TASKS_API_URL_FORMAT = 'https://cloudtasks.googleapis.com/v2/' + CLOUD_TASKS_API_RESOURCE_PATH;
 const FIREBASE_FUNCTION_URL_FORMAT = 'https://{locationId}-{projectId}.cloudfunctions.net/{resourceId}';
@@ -65,10 +73,14 @@ export class FunctionsApiClient {
    * Deletes a task from a queue.
    *
    * @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 functionName - The name of the function associated with the queue.
+   * @param scope - Optional `FunctionScope` configuration.
    */
-  public async delete(id: string, functionName: string, extensionId?: string): Promise<void> {
+  public async delete(
+    id: string,
+    functionName: string,
+    scope?: InternalFunctionScope
+  ): Promise<void> {
     if (!validator.isNonEmptyString(functionName)) {
       throw new FirebaseFunctionsError({
         code: 'invalid-argument',
@@ -101,13 +113,13 @@ export class FunctionsApiClient {
         message: 'No valid function name specified to enqueue tasks for.'
       });
     }
-    if (typeof extensionId !== 'undefined' && validator.isNonEmptyString(extensionId)) {
-      resources.resourceId = `ext-${extensionId}-${resources.resourceId}`;
-    }
+
+    const { resourceId } = this.resolveResourceId(resources.resourceId, scope);
+    const targetResources = { ...resources, resourceId };
 
     try {
-      const serviceUrl = tasksEmulatorUrl(resources, this.emulatorHost)?.concat('/', id)
-        ?? await this.getUrl(resources, CLOUD_TASKS_API_URL_FORMAT.concat('/', id));
+      const serviceUrl = tasksEmulatorUrl(targetResources, this.emulatorHost)?.concat('/', id)
+        ?? await this.getUrl(targetResources, CLOUD_TASKS_API_URL_FORMAT.concat('/', id));
       const request: HttpRequestConfig = {
         method: 'DELETE',
         url: serviceUrl,
@@ -116,10 +128,6 @@ export class FunctionsApiClient {
       await this.httpClient.send(request);
     } catch (err: unknown) {
       if (err instanceof RequestResponseError) {
-        if (err.response.status === 404) {
-          // if no task with the provided ID exists, then ignore the delete.
-          return;
-        }
         throw this.toFirebaseError(err);
       } else {
         throw err;
@@ -131,11 +139,16 @@ export class FunctionsApiClient {
    * Creates a task and adds it to a queue.
    *
    * @param data - The data payload of the task.
-   * @param functionName - The functionName of the queue.
-   * @param extensionId - Optional canonical ID of the extension.
+   * @param functionName - The name of the function associated with the queue.
+   * @param scope - Optional `FunctionScope` configuration.
    * @param opts - Optional options when enqueuing a new task.
    */
-  public async enqueue(data: any, functionName: string, extensionId?: string, opts?: TaskOptions): Promise<void> {
+  public async enqueue(
+    data: any,
+    functionName: string,
+    scope?: InternalFunctionScope,
+    opts?: TaskOptions
+  ): Promise<void> {
     if (!validator.isNonEmptyString(functionName)) {
       throw new FirebaseFunctionsError({
         code: 'invalid-argument',
@@ -161,17 +174,17 @@ export class FunctionsApiClient {
         message: 'No valid function name specified to enqueue tasks for.'
       });
     }
-    if (typeof extensionId !== 'undefined' && validator.isNonEmptyString(extensionId)) {
-      resources.resourceId = `ext-${extensionId}-${resources.resourceId}`;
-    }
 
-    const task = this.validateTaskOptions(data, resources, opts);
+    const { resourceId, extensionOrKitId } = this.resolveResourceId(resources.resourceId, scope);
+    const targetResources = { ...resources, resourceId };
+
     try {
+      const task = this.validateTaskOptions(data, targetResources, opts);
       const serviceUrl =
-        tasksEmulatorUrl(resources, this.emulatorHost) ??
-        await this.getUrl(resources, CLOUD_TASKS_API_URL_FORMAT);
+        tasksEmulatorUrl(targetResources, this.emulatorHost) ??
+        await this.getUrl(targetResources, CLOUD_TASKS_API_URL_FORMAT);
 
-      const taskPayload = await this.updateTaskPayload(task, resources, extensionId);
+      const taskPayload = await this.updateTaskPayload(task, targetResources, extensionOrKitId);
       const request: HttpRequestConfig = {
         method: 'POST',
         url: serviceUrl,
@@ -199,6 +212,51 @@ export class FunctionsApiClient {
     }
   }
 
+  private resolveResourceId(
+    resourceId: string,
+    scope: InternalFunctionScope = { scope: 'current' }
+  ): { resourceId: string; extensionOrKitId?: string } {
+
+    switch (scope.scope) {
+    case 'current': {
+      const extInstanceId = process.env.EXT_INSTANCE_ID;
+      if (validator.isNonEmptyString(extInstanceId)) {
+        return {
+          resourceId: `ext-${extInstanceId}-${resourceId}`,
+          extensionOrKitId: extInstanceId,
+        };
+      }
+      const kitInstanceId = process.env.FIREBASE_KIT_INSTANCE_ID;
+      if (validator.isNonEmptyString(kitInstanceId)) {
+        return {
+          resourceId: `kit-${kitInstanceId}-${resourceId}`,
+          extensionOrKitId: kitInstanceId,
+        };
+      }
+      return { resourceId };
+    }
+    case 'global':
+      return { resourceId };
+    case 'extension':
+      return {
+        resourceId: `ext-${scope.instance}-${resourceId}`,
+        extensionOrKitId: scope.instance,
+      };
+    case 'kit': // kit scope is secretly accepted for forward compatibility
+      return {
+        resourceId: `kit-${scope.instance}-${resourceId}`,
+        extensionOrKitId: scope.instance,
+      };
+    case 'extensionOrKit':
+      return {
+        resourceId: `ext-${scope.instance}-${resourceId}`,
+        extensionOrKitId: scope.instance,
+      };
+    default:
+      return { resourceId };
+    }
+  }
+
   private getUrl(resourceName: utils.ParsedResource, urlFormat: string): Promise<string> {
     let { locationId } = resourceName;
     const { projectId, resourceId } = resourceName;
@@ -349,7 +407,11 @@ export class FunctionsApiClient {
     return task;
   }
 
-  private async updateTaskPayload(task: Task, resources: utils.ParsedResource, extensionId?: string): Promise<Task> {
+  private async updateTaskPayload(
+    task: Task,
+    resources: utils.ParsedResource,
+    extensionOrKitId?: string
+  ): Promise<Task> {
     const defaultUrl = this.emulatorHost ?
       ''
       : await this.getUrl(resources, FIREBASE_FUNCTION_URL_FORMAT);
@@ -360,7 +422,7 @@ export class FunctionsApiClient {
 
     task.httpRequest.url = functionUrl;
     // When run from a deployed extension, we should be using ComputeEngineCredentials
-    if (validator.isNonEmptyString(extensionId) && this.app.options.credential
+    if (validator.isNonEmptyString(extensionOrKitId) && this.app.options.credential
     instanceof ApplicationDefaultCredential && await this.app.options.credential.isComputeEngineCredential()) {
       const idToken = await this.app.options.credential.getIDToken(functionUrl);
       task.httpRequest.headers = { ...task.httpRequest.headers, 'Authorization': `Bearer ${idToken}` };

src/functions/functions-api-client-internal.ts

@@ -108,3 +108,16 @@ export interface TaskOptionsExperimental {
  */
   uri?: string;
 }
+
+/**
+ * Type representing the scope of a function in a task queue.
+ */
+export type FunctionScope = {
+  scope: 'current';
+} | {
+  scope: 'global';
+} | {
+  scope: 'extension';
+  instance: string;
+};
+