firebase-functions 3.22.0 → 3.23.0

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

@@ -3,9 +3,10 @@
  * @packageDocumentation
  */
 import { BlockingFunction } from '../../cloud-functions';
-import { AuthBlockingEvent, AuthBlockingEventType, BeforeCreateResponse, BeforeSignInResponse, HttpsError } from '../../common/providers/identity';
+import { AuthBlockingEvent, AuthBlockingEventType, AuthUserRecord, BeforeCreateResponse, BeforeSignInResponse, HttpsError } from '../../common/providers/identity';
 import * as options from '../options';
-export { HttpsError };
+import { Expression } from '../params';
+export { AuthUserRecord, AuthBlockingEvent, HttpsError };
 /** @hidden Internally used when parsing the options. */
 interface InternalOptions {
     opts: options.GlobalOptions;
@@ -31,7 +32,7 @@ export interface BlockingOptions {
      * Amount of memory to allocate to a function.
      * A value of null restores the defaults of 256MB.
      */
-    memory?: options.MemoryOption | null;
+    memory?: options.MemoryOption | Expression<number> | null;
     /**
      * Timeout for the function in sections, possible values are 0 to 540.
      * HTTPS functions can specify a higher timeout.
@@ -42,19 +43,19 @@ export interface BlockingOptions {
      * maximum timeout of 36,00s (1 hour). Task queue functions have a maximum
      * timeout of 1,800s (30 minutes)
      */
-    timeoutSeconds?: number | null;
+    timeoutSeconds?: number | Expression<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;
+    minInstances?: number | Expression<number> | null;
     /**
      * Max number of instances to be running in parallel.
      * A value of null restores the default max instances.
      */
-    maxInstances?: number | null;
+    maxInstances?: number | Expression<number> | null;
     /**
      * Number of requests a function can serve at once.
      * Can only be applied to functions running on Cloud Functions v2.
@@ -62,7 +63,7 @@ export interface BlockingOptions {
      * 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;
+    concurrency?: number | Expression<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.

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

@@ -1,5 +1,6 @@
 import { CloudEvent, CloudFunction } from '../core';
 import * as options from '../options';
+import { Expression } from '../params';
 /**
  * Google Cloud Pub/Sub is a globally distributed message bus that automatically scales as you need it.
  * You can create a function ({@link onMessagePublished}) that handles pub/sub events by using functions.pubsub.
@@ -89,7 +90,7 @@ export interface PubSubOptions extends options.EventHandlerOptions {
      * Amount of memory to allocate to a function.
      * A value of null restores the defaults of 256MB.
      */
-    memory?: options.MemoryOption | null;
+    memory?: options.MemoryOption | Expression<number> | null;
     /**
      * Timeout for the function in sections, possible values are 0 to 540.
      * HTTPS functions can specify a higher timeout.
@@ -100,19 +101,19 @@ export interface PubSubOptions extends options.EventHandlerOptions {
      * maximum timeout of 36,00s (1 hour). Task queue functions have a maximum
      * timeout of 1,800s (30 minutes)
      */
-    timeoutSeconds?: number | null;
+    timeoutSeconds?: number | Expression<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;
+    minInstances?: number | Expression<number> | null;
     /**
      * Max number of instances to be running in parallel.
      * A value of null restores the default max instances.
      */
-    maxInstances?: number | null;
+    maxInstances?: number | Expression<number> | null;
     /**
      * Number of requests a function can serve at once.
      * Can only be applied to functions running on Cloud Functions v2.
@@ -120,7 +121,7 @@ export interface PubSubOptions extends options.EventHandlerOptions {
      * 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;
+    concurrency?: number | Expression<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.

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

@@ -0,0 +1,63 @@
+import { timezone } from '../../common/timezone';
+import { ManifestRequiredAPI } from '../../runtime/manifest';
+import * as options from '../options';
+import { HttpsFunction } from './https';
+/**
+ * Interface representing a ScheduleEvent that is passed to the function handler.
+ */
+export interface ScheduledEvent {
+    /**
+     * The Cloud Scheduler job name.
+     * Populated via the X-CloudScheduler-JobName header.
+     *
+     * If invoked manually, this field is undefined.
+     */
+    jobName?: string;
+    /**
+     * For Cloud Scheduler jobs specified in the unix-cron format,
+     * this is the job schedule time in RFC3339 UTC "Zulu" format.
+     * Populated via the X-CloudScheduler-ScheduleTime header.
+     *
+     * If the schedule is manually triggered, this field will be
+     * the function execution time.
+     */
+    scheduleTime: string;
+}
+/** The Cloud Function type for Schedule triggers. */
+export interface ScheduleFunction extends HttpsFunction {
+    __requiredAPIs?: ManifestRequiredAPI[];
+    run(data: ScheduledEvent): void | Promise<void>;
+}
+/** Options that can be set on a Schedule trigger. */
+export interface ScheduleOptions extends options.GlobalOptions {
+    /** The schedule, in Unix Crontab or AppEngine syntax. */
+    schedule: string;
+    /** The timezone that the schedule executes in. */
+    timeZone?: timezone;
+    /** The number of retry attempts for a failed run. */
+    retryCount?: number;
+    /** The time limit for retrying. */
+    maxRetrySeconds?: number;
+    /** The minimum time to wait before retying. */
+    minBackoffSeconds?: number;
+    /** The maximum time to wait before retrying. */
+    maxBackoffSeconds?: number;
+    /** The time between will double max doublings times. */
+    maxDoublings?: number;
+}
+/**
+ * Handler for scheduled functions. Triggered whenever the associated
+ * scheduler job sends a http request.
+ * @param schedule - The schedule, in Unix Crontab or AppEngine syntax.
+ * @param handler - A function to execute when triggered.
+ * @returns A function that you can export and deploy.
+ */
+export declare function onSchedule(schedule: string, handler: (req: ScheduledEvent) => void | Promise<void>): ScheduleFunction;
+/**
+ * Handler for scheduled functions. Triggered whenever the associated
+ * scheduler job sends a http request.
+ * @param options - Options to set on scheduled functions.
+ * @param handler - A function to execute when triggered.
+ * @returns A function that you can export and deploy.
+ */
+export declare function onSchedule(options: ScheduleOptions, handler: (req: ScheduledEvent) => void | Promise<void>): ScheduleFunction;

package/lib/v2/providers/scheduler.js

@@ -0,0 +1,98 @@
+"use strict";
+// The MIT License (MIT)
+//
+// Copyright (c) 2022 Firebase
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.onSchedule = exports.getOpts = void 0;
+const encoding_1 = require("../../common/encoding");
+const logger = require("../../logger");
+const options = require("../options");
+/** @internal */
+function getOpts(args) {
+    if (typeof args === 'string') {
+        return {
+            schedule: args,
+            opts: {},
+        };
+    }
+    return {
+        schedule: args.schedule,
+        timeZone: args.timeZone,
+        retryCount: args.retryCount,
+        maxRetrySeconds: args.maxRetrySeconds,
+        minBackoffSeconds: args.minBackoffSeconds,
+        maxBackoffSeconds: args.maxBackoffSeconds,
+        maxDoublings: args.maxDoublings,
+        opts: args,
+    };
+}
+exports.getOpts = getOpts;
+/**
+ * Handler for scheduled functions. Triggered whenever the associated
+ * scheduler job sends a http request.
+ * @param args - Either a schedule or an object containing function options.
+ * @param handler - A function to execute when triggered.
+ * @returns A function that you can export and deploy.
+ */
+function onSchedule(args, handler) {
+    const separatedOpts = getOpts(args);
+    const func = async (req, res) => {
+        const event = {
+            jobName: req.header('X-CloudScheduler-JobName') || undefined,
+            scheduleTime: req.header('X-CloudScheduler-ScheduleTime') || new Date().toISOString(),
+        };
+        try {
+            await handler(event);
+            res.status(200).send();
+        }
+        catch (err) {
+            logger.error(err.message);
+            res.status(500).send();
+        }
+    };
+    func.run = handler;
+    const baseOptsEndpoint = options.optionsToEndpoint(options.getGlobalOptions());
+    const specificOptsEndpoint = options.optionsToEndpoint(separatedOpts.opts);
+    const ep = {
+        platform: 'gcfv2',
+        ...baseOptsEndpoint,
+        ...specificOptsEndpoint,
+        labels: {
+            ...baseOptsEndpoint === null || baseOptsEndpoint === void 0 ? void 0 : baseOptsEndpoint.labels,
+            ...specificOptsEndpoint === null || specificOptsEndpoint === void 0 ? void 0 : specificOptsEndpoint.labels,
+        },
+        scheduleTrigger: {
+            schedule: separatedOpts.schedule,
+            retryConfig: {},
+        },
+    };
+    (0, encoding_1.copyIfPresent)(ep.scheduleTrigger, separatedOpts, 'timeZone');
+    (0, encoding_1.copyIfPresent)(ep.scheduleTrigger.retryConfig, separatedOpts, 'retryCount', 'maxRetrySeconds', 'minBackoffSeconds', 'maxBackoffSeconds', 'maxDoublings');
+    func.__endpoint = ep;
+    func.__requiredAPIs = [
+        {
+            api: 'cloudscheduler.googleapis.com',
+            reason: 'Needed for scheduled functions.',
+        },
+    ];
+    return func;
+}
+exports.onSchedule = onSchedule;

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

@@ -1,5 +1,6 @@
 import { CloudEvent, CloudFunction } from '../core';
 import * as options from '../options';
+import { Expression } from '../params';
 /**
  * An object within Google Cloud Storage.
  * Ref: https://github.com/googleapis/google-cloudevents-nodejs/blob/main/cloud/storage/v1/StorageObjectData.ts
@@ -165,7 +166,7 @@ export interface StorageOptions extends options.EventHandlerOptions {
      * Amount of memory to allocate to a function.
      * A value of null restores the defaults of 256MB.
      */
-    memory?: options.MemoryOption | null;
+    memory?: options.MemoryOption | Expression<number> | null;
     /**
      * Timeout for the function in sections, possible values are 0 to 540.
      * HTTPS functions can specify a higher timeout.
@@ -176,19 +177,19 @@ export interface StorageOptions extends options.EventHandlerOptions {
      * maximum timeout of 36,00s (1 hour). Task queue functions have a maximum
      * timeout of 1,800s (30 minutes)
      */
-    timeoutSeconds?: number | null;
+    timeoutSeconds?: number | Expression<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;
+    minInstances?: number | Expression<number> | null;
     /**
      * Max number of instances to be running in parallel.
      * A value of null restores the default max instances.
      */
-    maxInstances?: number | null;
+    maxInstances?: number | Expression<number> | null;
     /**
      * Number of requests a function can serve at once.
      * Can only be applied to functions running on Cloud Functions v2.
@@ -196,7 +197,7 @@ export interface StorageOptions extends options.EventHandlerOptions {
      * 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;
+    concurrency?: number | Expression<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.

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

@@ -1,7 +1,8 @@
 import { AuthData, RateLimits, Request, RetryConfig } from '../../common/providers/tasks';
 import * as options from '../options';
 import { HttpsFunction } from './https';
-export { AuthData, RateLimits, Request, RetryConfig };
+import { Expression } from '../params';
+export { AuthData, Request };
 export interface TaskQueueOptions extends options.EventHandlerOptions {
     /** How a task should be retried in the event of a non-2xx return. */
     retryConfig?: RetryConfig;
@@ -22,7 +23,7 @@ export interface TaskQueueOptions extends options.EventHandlerOptions {
      * Amount of memory to allocate to a function.
      * A value of null restores the defaults of 256MB.
      */
-    memory?: options.MemoryOption | null;
+    memory?: options.MemoryOption | Expression<number> | null;
     /**
      * Timeout for the function in sections, possible values are 0 to 540.
      * HTTPS functions can specify a higher timeout.
@@ -33,19 +34,19 @@ export interface TaskQueueOptions extends options.EventHandlerOptions {
      * maximum timeout of 36,00s (1 hour). Task queue functions have a maximum
      * timeout of 1,800s (30 minutes)
      */
-    timeoutSeconds?: number | null;
+    timeoutSeconds?: number | Expression<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;
+    minInstances?: number | Expression<number> | null;
     /**
      * Max number of instances to be running in parallel.
      * A value of null restores the default max instances.
      */
-    maxInstances?: number | null;
+    maxInstances?: number | Expression<number> | null;
     /**
      * Number of requests a function can serve at once.
      * Can only be applied to functions running on Cloud Functions v2.
@@ -53,7 +54,7 @@ export interface TaskQueueOptions extends options.EventHandlerOptions {
      * 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;
+    concurrency?: number | Expression<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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firebase-functions",
-  "version": "3.22.0",
+  "version": "3.23.0",
   "description": "Firebase SDK for Cloud Functions",
   "keywords": [
     "firebase",
@@ -66,7 +66,8 @@
     "./v2/alerts/crashlytics": "./lib/v2/providers/alerts/crashlytics.js",
     "./v2/eventarc": "./lib/v2/providers/eventarc.js",
     "./v2/identity": "./lib/v2/providers/identity.js",
-    "./v2/database": "./lib/v2/providers/database.js"
+    "./v2/database": "./lib/v2/providers/database.js",
+    "./v2/scheduler": "./lib/v2/providers/scheduler.js"
   },
   "typesVersions": {
     "*": {
@@ -153,6 +154,9 @@
       ],
       "v2/tasks": [
         "lib/v2/providers/tasks"
+      ],
+      "v2/scheduler": [
+        "lib/v2/providers/scheduler"
       ]
     }
   },
@@ -162,7 +166,8 @@
   "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:toc": "ts-node docgen/toc.ts --input docgen/v1/markdown --output docgen/v1/markdown/toc --path /docs/reference/functions",
+    "docgen:v1:gen": "api-documenter-fire markdown -i docgen/v1 -o docgen/v1/markdown --project functions && npm run docgen:v1:toc",
     "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",
@@ -177,7 +182,8 @@
     "lint": "tslint --config tslint.json --project tsconfig.json ",
     "lint:fix": "tslint --config tslint.json --fix --project tsconfig.json",
     "test": "mocha --file ./mocha/setup.ts \"spec/**/*.spec.ts\"",
-    "test:bin": "./scripts/bin-test/run.sh"
+    "test:bin": "./scripts/bin-test/run.sh",
+    "test:postmerge": "./integration_test/run_tests.sh"
   },
   "dependencies": {
     "@types/cors": "^2.8.5",
@@ -188,7 +194,7 @@
     "node-fetch": "^2.6.7"
   },
   "devDependencies": {
-    "@firebase/api-documenter": "^0.1.2",
+    "@firebase/api-documenter": "^0.2.0",
     "@microsoft/api-documenter": "^7.13.45",
     "@microsoft/api-extractor": "^7.18.7",
     "@types/chai": "^4.1.7",
@@ -205,7 +211,7 @@
     "chai": "^4.2.0",
     "chai-as-promised": "^7.1.1",
     "child-process-promise": "^2.2.1",
-    "firebase-admin": "^10.1.0",
+    "firebase-admin": "^10.3.0",
     "js-yaml": "^3.13.1",
     "jsdom": "^16.2.1",
     "jsonwebtoken": "^8.5.1",
@@ -224,7 +230,7 @@
     "tslint-config-prettier": "^1.18.0",
     "tslint-no-unused-expression-chai": "^0.1.4",
     "tslint-plugin-prettier": "^2.0.1",
-    "typedoc": "0.21.2",
+    "typedoc": "0.23.7",
     "typescript": "^4.3.5",
     "yargs": "^15.3.1"
   },