firebase-functions 3.20.0 → 3.21.1

package/lib/v2/providers/tasks.d.ts

@@ -1,22 +1,122 @@
+import { AuthData, RateLimits, Request, RetryConfig } from '../../common/providers/tasks';
 import * as options from '../options';
 import { HttpsFunction } from './https';
-import { AuthData, RateLimits, Request, RetryConfig } from '../../common/providers/tasks';
-export { AuthData, RateLimits, Request, RetryConfig as RetryPolicy };
-export interface TaskQueueOptions extends options.GlobalOptions {
+export { AuthData, RateLimits, Request, RetryConfig };
+export interface TaskQueueOptions extends options.EventHandlerOptions {
+    /** How a task should be retried in the event of a non-2xx return. */
     retryConfig?: RetryConfig;
+    /** How congestion control should be applied to the function. */
     rateLimits?: RateLimits;
     /**
      * Who can enqueue tasks for this function.
      * If left unspecified, only service accounts which have
-     * roles/cloudtasks.enqueuer and roles/cloudfunctions.invoker
+     * `roles/cloudtasks.enqueuer` and `roles/cloudfunctions.invoker`
      * will have permissions.
      */
     invoker?: 'private' | string | string[];
+    /**
+     * Region where functions should be deployed.
+     */
+    region?: options.SupportedRegion | string;
+    /**
+     * Amount of memory to allocate to a function.
+     * A value of null restores the defaults of 256MB.
+     */
+    memory?: options.MemoryOption | null;
+    /**
+     * Timeout for the function in sections, possible values are 0 to 540.
+     * HTTPS functions can specify a higher timeout.
+     * A value of null restores the default of 60s
+     * The minimum timeout for a gen 2 function is 1s. The maximum timeout for a
+     * function depends on the type of function: Event handling functions have a
+     * maximum timeout of 540s (9 minutes). HTTPS and callable functions have a
+     * maximum timeout of 36,00s (1 hour). Task queue functions have a maximum
+     * timeout of 1,800s (30 minutes)
+     */
+    timeoutSeconds?: number | null;
+    /**
+     * Min number of actual instances to be running at a given time.
+     * Instances will be billed for memory allocation and 10% of CPU allocation
+     * while idle.
+     * A value of null restores the default min instances.
+     */
+    minInstances?: number | null;
+    /**
+     * Max number of instances to be running in parallel.
+     * A value of null restores the default max instances.
+     */
+    maxInstances?: number | null;
+    /**
+     * Number of requests a function can serve at once.
+     * Can only be applied to functions running on Cloud Functions v2.
+     * A value of null restores the default concurrency (80 when CPU >= 1, 1 otherwise).
+     * Concurrency cannot be set to any value other than 1 if `cpu` is less than 1.
+     * The maximum value for concurrency is 1,000.
+     */
+    concurrency?: number | null;
+    /**
+     * Fractional number of CPUs to allocate to a function.
+     * Defaults to 1 for functions with <= 2GB RAM and increases for larger memory sizes.
+     * This is different from the defaults when using the gcloud utility and is different from
+     * the fixed amount assigned in Google Cloud Functions generation 1.
+     * To revert to the CPU amounts used in gcloud or in Cloud Functions generation 1, set this
+     * to the value "gcf_gen1"
+     */
+    cpu?: number | 'gcf_gen1';
+    /**
+     * Connect cloud function to specified VPC connector.
+     * A value of null removes the VPC connector
+     */
+    vpcConnector?: string | null;
+    /**
+     * Egress settings for VPC connector.
+     * A value of null turns off VPC connector egress settings
+     */
+    vpcConnectorEgressSettings?: options.VpcEgressSetting | null;
+    /**
+     * Specific service account for the function to run as.
+     * A value of null restores the default service account.
+     */
+    serviceAccount?: string | null;
+    /**
+     * Ingress settings which control where this function can be called from.
+     * A value of null turns off ingress settings.
+     */
+    ingressSettings?: options.IngressSetting | null;
+    /**
+     * User labels to set on the function.
+     */
+    labels?: Record<string, string>;
+    secrets?: string[];
+    /** Whether failed executions should be delivered again. */
+    retry?: boolean;
 }
+/**
+ * A handler for tasks.
+ * @typeParam T - The task data interface. Task data is unmarshaled from JSON.
+ */
 export interface TaskQueueFunction<T = any> extends HttpsFunction {
-    run(data: Request<T>): void | Promise<void>;
+    /**
+     * The callback passed to the `TaskQueueFunction` constructor.
+     * @param request - A TaskRequest containing data and auth information.
+     * @returns Any return value. Google Cloud Functions will await any promise
+     *          before shutting down your function. Resolved return values
+     *          are only used for unit testing purposes.
+     */
+    run(request: Request<T>): void | Promise<void>;
 }
-/** Handle a request sent to a Cloud Tasks queue. */
+/**
+ * Creates a handler for tasks sent to a Google Cloud Tasks queue.
+ * @param handler - A callback to handle task requests.
+ * @typeParam Args - The interface for the request's `data` field.
+ * @returns A Cloud Function you can export and deploy.
+ */
 export declare function onTaskDispatched<Args = any>(handler: (request: Request<Args>) => void | Promise<void>): TaskQueueFunction<Args>;
-/** Handle a request sent to a Cloud Tasks queue. */
+/**
+ * Creates a handler for tasks sent to a Google Cloud Tasks queue.
+ * @param options - Configuration for the task queue or Cloud Function.
+ * @param handler - A callback to handle task requests.
+ * @typeParam Args - The interface for the request's `data` field.
+ * @returns A Cloud Function you can export and deploy.
+ */
 export declare function onTaskDispatched<Args = any>(options: TaskQueueOptions, handler: (request: Request<Args>) => void | Promise<void>): TaskQueueFunction<Args>;

package/lib/v2/providers/tasks.js

@@ -22,9 +22,13 @@
 // SOFTWARE.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.onTaskDispatched = void 0;
-const options = require("../options");
+/**
+ * Cloud functions to handle Tasks enqueued with Google Cloud Tasks.
+ * @packageDocumentation
+ */
 const encoding_1 = require("../../common/encoding");
 const tasks_1 = require("../../common/providers/tasks");
+const options = require("../options");
 function onTaskDispatched(optsOrHandler, handler) {
     let opts;
     if (arguments.length == 1) {
@@ -37,7 +41,7 @@ function onTaskDispatched(optsOrHandler, handler) {
     // onDispatchHandler sniffs the function length to determine which API to present.
     // fix the length to prevent api versions from being mismatched.
     const fixedLen = (req) => handler(req);
-    const func = tasks_1.onDispatchHandler(fixedLen);
+    const func = (0, tasks_1.onDispatchHandler)(fixedLen);
     Object.defineProperty(func, '__trigger', {
         get: () => {
             const baseOpts = options.optionsToTriggerAnnotations(options.getGlobalOptions());
@@ -45,10 +49,9 @@ function onTaskDispatched(optsOrHandler, handler) {
             // but optionsToTriggerAnnotations handles both cases.
             const specificOpts = options.optionsToTriggerAnnotations(opts);
             const taskQueueTrigger = {};
-            encoding_1.copyIfPresent(taskQueueTrigger, opts, 'retryConfig', 'rateLimits');
-            encoding_1.convertIfPresent(taskQueueTrigger, opts, 'invoker', 'invoker', encoding_1.convertInvoker);
+            (0, encoding_1.copyIfPresent)(taskQueueTrigger, opts, 'retryConfig', 'rateLimits');
+            (0, encoding_1.convertIfPresent)(taskQueueTrigger, opts, 'invoker', 'invoker', encoding_1.convertInvoker);
             return {
-                apiVersion: 2,
                 platform: 'gcfv2',
                 ...baseOpts,
                 ...specificOpts,
@@ -74,9 +77,9 @@ function onTaskDispatched(optsOrHandler, handler) {
         },
         taskQueueTrigger: {},
     };
-    encoding_1.copyIfPresent(func.__endpoint.taskQueueTrigger, opts, 'retryConfig');
-    encoding_1.copyIfPresent(func.__endpoint.taskQueueTrigger, opts, 'rateLimits');
-    encoding_1.convertIfPresent(func.__endpoint.taskQueueTrigger, opts, 'invoker', 'invoker', encoding_1.convertInvoker);
+    (0, encoding_1.copyIfPresent)(func.__endpoint.taskQueueTrigger, opts, 'retryConfig');
+    (0, encoding_1.copyIfPresent)(func.__endpoint.taskQueueTrigger, opts, 'rateLimits');
+    (0, encoding_1.convertIfPresent)(func.__endpoint.taskQueueTrigger, opts, 'invoker', 'invoker', encoding_1.convertInvoker);
     func.__requiredAPIs = [
         {
             api: 'cloudtasks.googleapis.com',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firebase-functions",
-  "version": "3.20.0",
+  "version": "3.21.1",
   "description": "Firebase SDK for Cloud Functions",
   "keywords": [
     "firebase",
@@ -63,7 +63,9 @@
     "./v2/alerts": "./lib/v2/providers/alerts/index.js",
     "./v2/alerts/appDistribution": "./lib/v2/providers/alerts/appDistribution.js",
     "./v2/alerts/billing": "./lib/v2/providers/alerts/billing.js",
-    "./v2/alerts/crashlytics": "./lib/v2/providers/alerts/crashlytics.js"
+    "./v2/alerts/crashlytics": "./lib/v2/providers/alerts/crashlytics.js",
+    "./v2/eventarc": "./lib/v2/providers/eventarc.js",
+    "./v2/identity": "./lib/v2/providers/identity.js"
   },
   "typesVersions": {
     "*": {
@@ -124,6 +126,12 @@
       "v2/base": [
         "lib/v2/base"
       ],
+      "v2/eventarc": [
+        "lib/v2/providers/eventarc"
+      ],
+      "v2/identity": [
+        "lib/v2/providers/identity"
+      ],
       "v2/options": [
         "lib/v2/options"
       ],
@@ -149,6 +157,13 @@
   },
   "scripts": {
     "apidocs": "node docgen/generate-docs.js",
+    "docgen:v1:extract": "api-extractor run -c docgen/api-extractor.v1.json --local",
+    "docgen:v1:gen": "api-documenter-fire markdown -i docgen/v1 -o docgen/v1/markdown && api-documenter-fire toc -i docgen/v1 -o docgen/v1/markdown/toc -p /docs/reference/functions",
+    "docgen:v1": "npm run build && npm run docgen:v1:extract && npm run docgen:v1:gen",
+    "docgen:v2:extract": "api-extractor run -c docgen/api-extractor.v2.json --local",
+    "docgen:v2:toc": "ts-node docgen/toc.ts --input docgen/v2/markdown --output docgen/v2/markdown/toc --path /docs/functions/beta/reference",
+    "docgen:v2:gen": "api-documenter-fire markdown -i docgen/v2 -o docgen/v2/markdown && npm run docgen:v2:toc",
+    "docgen:v2": "npm run build && npm run docgen:v2:extract && npm run docgen:v2:gen",
     "build:pack": "rm -rf lib && npm install && tsc -p tsconfig.release.json && npm pack",
     "build:release": "npm ci --production && npm install --no-save typescript firebase-admin && tsc -p tsconfig.release.json",
     "build": "tsc -p tsconfig.release.json",
@@ -169,6 +184,9 @@
     "node-fetch": "^2.6.7"
   },
   "devDependencies": {
+    "@firebase/api-documenter": "^0.1.2",
+    "@microsoft/api-documenter": "^7.13.45",
+    "@microsoft/api-extractor": "^7.18.7",
     "@types/chai": "^4.1.7",
     "@types/chai-as-promised": "^7.1.0",
     "@types/jsonwebtoken": "^8.3.2",
@@ -179,10 +197,11 @@
     "@types/node": "^8.10.50",
     "@types/node-fetch": "^3.0.3",
     "@types/sinon": "^7.0.13",
+    "api-extractor-model-me": "^0.1.1",
     "chai": "^4.2.0",
     "chai-as-promised": "^7.1.1",
     "child-process-promise": "^2.2.1",
-    "firebase-admin": "10.0.0",
+    "firebase-admin": "^10.1.0",
     "js-yaml": "^3.13.1",
     "jsdom": "^16.2.1",
     "jsonwebtoken": "^8.5.1",