firebase-functions 3.21.1 → 3.23.0

package/lib/utilities/path-pattern.js

@@ -0,0 +1,142 @@
+"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.PathPattern = exports.trimParam = void 0;
+const path_1 = require("./path");
+/** https://cloud.google.com/eventarc/docs/path-patterns */
+/** @hidden */
+const WILDCARD_CAPTURE_REGEX = new RegExp('{[^/{}]+}', 'g');
+/** @internal */
+function trimParam(param) {
+    const paramNoBraces = param.slice(1, -1);
+    if (paramNoBraces.includes('=')) {
+        return paramNoBraces.slice(0, paramNoBraces.indexOf('='));
+    }
+    return paramNoBraces;
+}
+exports.trimParam = trimParam;
+/** @hidden */
+class Segment {
+    constructor(value) {
+        this.value = value;
+        this.name = 'segment';
+        this.trimmed = value;
+    }
+    isSingleSegmentWildcard() {
+        return this.value.includes('*') && !this.isMultiSegmentWildcard();
+    }
+    isMultiSegmentWildcard() {
+        return this.value.includes('**');
+    }
+}
+/** @hidden */
+class SingleCaptureSegment {
+    constructor(value) {
+        this.value = value;
+        this.name = 'single-capture';
+        this.trimmed = trimParam(value);
+    }
+    isSingleSegmentWildcard() {
+        return true;
+    }
+    isMultiSegmentWildcard() {
+        return false;
+    }
+}
+/** @hidden */
+class MultiCaptureSegment {
+    constructor(value) {
+        this.value = value;
+        this.name = 'multi-capture';
+        this.trimmed = trimParam(value);
+    }
+    isSingleSegmentWildcard() {
+        return false;
+    }
+    isMultiSegmentWildcard() {
+        return true;
+    }
+}
+/**
+ * Implements Eventarc's path pattern from the spec https://cloud.google.com/eventarc/docs/path-patterns
+ * @internal
+ */
+class PathPattern {
+    constructor(raw) {
+        this.raw = raw;
+        this.segments = [];
+        this.initPathSegments(raw);
+    }
+    /** @throws on validation error */
+    static compile(rawPath) { }
+    getValue() {
+        return this.raw;
+    }
+    // If false, we don't need to use pathPattern as our eventarc match type.
+    hasWildcards() {
+        return this.segments.some((segment) => segment.isSingleSegmentWildcard() || segment.isMultiSegmentWildcard());
+    }
+    hasCaptures() {
+        return this.segments.some((segment) => segment.name == 'single-capture' || segment.name === 'multi-capture');
+    }
+    extractMatches(path) {
+        const matches = {};
+        if (!this.hasCaptures()) {
+            return matches;
+        }
+        const pathSegments = (0, path_1.pathParts)(path);
+        let pathNdx = 0;
+        for (let segmentNdx = 0; segmentNdx < this.segments.length && pathNdx < pathSegments.length; segmentNdx++) {
+            const segment = this.segments[segmentNdx];
+            const remainingSegments = this.segments.length - 1 - segmentNdx;
+            const nextPathNdx = pathSegments.length - remainingSegments;
+            if (segment.name === 'single-capture') {
+                matches[segment.trimmed] = pathSegments[pathNdx];
+            }
+            else if (segment.name === 'multi-capture') {
+                matches[segment.trimmed] = pathSegments
+                    .slice(pathNdx, nextPathNdx)
+                    .join('/');
+            }
+            pathNdx = segment.isMultiSegmentWildcard() ? nextPathNdx : pathNdx + 1;
+        }
+        return matches;
+    }
+    initPathSegments(raw) {
+        const parts = (0, path_1.pathParts)(raw);
+        for (const part of parts) {
+            let segment;
+            const capture = part.match(WILDCARD_CAPTURE_REGEX);
+            if (capture && capture.length === 1) {
+                segment = part.includes('**')
+                    ? new MultiCaptureSegment(part)
+                    : new SingleCaptureSegment(part);
+            }
+            else {
+                segment = new Segment(part);
+            }
+            this.segments.push(segment);
+        }
+    }
+}
+exports.PathPattern = PathPattern;

package/lib/v2/core.d.ts

@@ -2,7 +2,9 @@
  * Core functionality of the Firebase Functions v2 SDK.
  * @packageDocumentation
  */
+import { Change } from '../common/change';
 import { ManifestEndpoint } from '../runtime/manifest';
+export { Change };
 /**
  * A CloudEventBase is the base of a cross-platform format for encoding a serverless event.
  * More information can be found in https://github.com/cloudevents/spec

package/lib/v2/core.js

@@ -21,3 +21,10 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Change = void 0;
+/**
+ * Core functionality of the Firebase Functions v2 SDK.
+ * @packageDocumentation
+ */
+const change_1 = require("../common/change");
+Object.defineProperty(exports, "Change", { enumerable: true, get: function () { return change_1.Change; } });

package/lib/v2/index.d.ts

@@ -7,12 +7,15 @@
  */
 import * as logger from '../logger';
 import * as alerts from './providers/alerts';
+import * as database from './providers/database';
 import * as eventarc from './providers/eventarc';
 import * as https from './providers/https';
 import * as identity from './providers/identity';
 import * as pubsub from './providers/pubsub';
+import * as scheduler from './providers/scheduler';
 import * as storage from './providers/storage';
 import * as tasks from './providers/tasks';
-export { alerts, storage, https, identity, pubsub, logger, tasks, eventarc };
+export { alerts, database, storage, https, identity, pubsub, logger, tasks, eventarc, scheduler, };
 export { setGlobalOptions, GlobalOptions, SupportedRegion, MemoryOption, VpcEgressSetting, IngressSetting, EventHandlerOptions, } from './options';
+export { Change } from '../common/change';
 export { CloudFunction, CloudEvent } from './core';

package/lib/v2/index.js

@@ -21,7 +21,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setGlobalOptions = exports.eventarc = exports.tasks = exports.logger = exports.pubsub = exports.identity = exports.https = exports.storage = exports.alerts = void 0;
+exports.Change = exports.setGlobalOptions = exports.scheduler = exports.eventarc = exports.tasks = exports.logger = exports.pubsub = exports.identity = exports.https = exports.storage = exports.database = exports.alerts = void 0;
 /**
  * The V2 API for Cloud Functions for Firebase.
  * This SDK also supports deep imports. For example, the namespace
@@ -33,6 +33,8 @@ const logger = require("../logger");
 exports.logger = logger;
 const alerts = require("./providers/alerts");
 exports.alerts = alerts;
+const database = require("./providers/database");
+exports.database = database;
 const eventarc = require("./providers/eventarc");
 exports.eventarc = eventarc;
 const https = require("./providers/https");
@@ -41,9 +43,13 @@ const identity = require("./providers/identity");
 exports.identity = identity;
 const pubsub = require("./providers/pubsub");
 exports.pubsub = pubsub;
+const scheduler = require("./providers/scheduler");
+exports.scheduler = scheduler;
 const storage = require("./providers/storage");
 exports.storage = storage;
 const tasks = require("./providers/tasks");
 exports.tasks = tasks;
 var options_1 = require("./options");
 Object.defineProperty(exports, "setGlobalOptions", { enumerable: true, get: function () { return options_1.setGlobalOptions; } });
+var change_1 = require("../common/change");
+Object.defineProperty(exports, "Change", { enumerable: true, get: function () { return change_1.Change; } });

package/lib/v2/options.d.ts

@@ -1,3 +1,4 @@
+import { Expression } from './params';
 import { ParamSpec } from './params/types';
 /**
  * List of all regions supported by Cloud Functions v2
@@ -29,7 +30,7 @@ export interface GlobalOptions {
      * Amount of memory to allocate to a function.
      * A value of null restores the defaults of 256MB.
      */
-    memory?: MemoryOption | null;
+    memory?: MemoryOption | Expression<number> | null;
     /**
      * Timeout for the function in sections, possible values are 0 to 540.
      * HTTPS functions can specify a higher timeout.
@@ -40,19 +41,19 @@ export interface GlobalOptions {
      * 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.
@@ -60,7 +61,7 @@ export interface GlobalOptions {
      * 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.
@@ -109,8 +110,17 @@ export declare function setGlobalOptions(options: GlobalOptions): void;
  * Additional fields that can be set on any event-handling Cloud Function.
  */
 export interface EventHandlerOptions extends GlobalOptions {
+    eventType?: string;
+    eventFilters?: Record<string, string | Expression<string>>;
+    eventFilterPathPatterns?: Record<string, string | Expression<string>>;
     /** Whether failed executions should be delivered again. */
-    retry?: boolean;
+    retry?: boolean | Expression<boolean> | null;
+    /** Region of the EventArc trigger. */
+    region?: string;
+    /** The service account that EventArc should use to invoke this function. Requires the P4SA to have ActAs permission on this service account. */
+    serviceAccount?: string | null;
+    /** The name of the channel where the function receives events. */
+    channel?: string;
 }
 /**
  * @hidden

package/lib/v2/options.js

@@ -69,7 +69,7 @@ function optionsToTriggerAnnotations(opts) {
     const annotation = {};
     (0, encoding_1.copyIfPresent)(annotation, opts, 'concurrency', 'minInstances', 'maxInstances', 'ingressSettings', 'labels', 'vpcConnector', 'vpcConnectorEgressSettings', 'secrets');
     (0, encoding_1.convertIfPresent)(annotation, opts, 'availableMemoryMb', 'memory', (mem) => {
-        return MemoryOptionToMB[mem];
+        return typeof mem === 'object' ? mem : MemoryOptionToMB[mem];
     });
     (0, encoding_1.convertIfPresent)(annotation, opts, 'regions', 'region', (region) => {
         if (typeof region === 'string') {
@@ -99,7 +99,7 @@ function optionsToEndpoint(opts) {
         endpoint.vpc = vpc;
     }
     (0, encoding_1.convertIfPresent)(endpoint, opts, 'availableMemoryMb', 'memory', (mem) => {
-        return MemoryOptionToMB[mem];
+        return typeof mem === 'object' ? mem : MemoryOptionToMB[mem];
     });
     (0, encoding_1.convertIfPresent)(endpoint, opts, 'region', 'region', (region) => {
         if (typeof region === 'string') {

package/lib/v2/params/index.d.ts

@@ -2,9 +2,20 @@
  * @hidden
  * @alpha
  */
-import { BooleanParam, FloatParam, IntParam, JSONParam, ListParam, Param, ParamOptions, StringParam } from './types';
-export { ParamOptions };
-export declare const declaredParams: Param[];
+import { BooleanParam, FloatParam, IntParam, ListParam, Param, ParamOptions, StringParam, SecretParam, Expression } from './types';
+export { ParamOptions, Expression };
+declare type SecretOrExpr = Param<any> | SecretParam;
+export declare const declaredParams: SecretOrExpr[];
+/**
+ * Declares a secret param, that will persist values only in Cloud Secret Manager.
+ * Secrets are stored interally as bytestrings. Use ParamOptions.`as` to provide type
+ * hinting during parameter resolution.
+ *
+ * @param name The name of the environment variable to use to load the param.
+ * @param options Configuration options for the param.
+ * @returns A Param with a `string` return type for `.value`.
+ */
+export declare function defineSecret(name: string): SecretParam;
 /**
  * Declare a string param.
  *
@@ -45,12 +56,3 @@ export declare function defineFloat(name: string, options?: ParamOptions<number>
  * @returns A Param with a `string[]` return type for `.value`.
  */
 export declare function defineList(name: string, options?: ParamOptions<string[]>): ListParam;
-/**
- * Declare a JSON param. The associated environment variable will be treated
- * as a JSON string when loading its value.
- *
- * @param name The name of the environment variable to use to load the param.
- * @param options Configuration options for the param.
- * @returns A Param with a specifiable return type for `.value`.
- */
-export declare function defineJSON<T = any>(name: string, options?: ParamOptions<T>): JSONParam;

package/lib/v2/params/index.js

@@ -21,12 +21,13 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineJSON = exports.defineList = exports.defineFloat = exports.defineInt = exports.defineBoolean = exports.defineString = exports.declaredParams = void 0;
+exports.defineList = exports.defineFloat = exports.defineInt = exports.defineBoolean = exports.defineString = exports.defineSecret = exports.clearParams = exports.declaredParams = exports.Expression = void 0;
 /**
  * @hidden
  * @alpha
  */
 const types_1 = require("./types");
+Object.defineProperty(exports, "Expression", { enumerable: true, get: function () { return types_1.Expression; } });
 exports.declaredParams = [];
 /**
  * Use a helper to manage the list such that params are uniquely
@@ -41,6 +42,29 @@ function registerParam(param) {
     }
     exports.declaredParams.push(param);
 }
+/**
+ * For testing.
+ * @internal
+ */
+function clearParams() {
+    exports.declaredParams.splice(0, exports.declaredParams.length);
+}
+exports.clearParams = clearParams;
+/**
+ * Declares a secret param, that will persist values only in Cloud Secret Manager.
+ * Secrets are stored interally as bytestrings. Use ParamOptions.`as` to provide type
+ * hinting during parameter resolution.
+ *
+ * @param name The name of the environment variable to use to load the param.
+ * @param options Configuration options for the param.
+ * @returns A Param with a `string` return type for `.value`.
+ */
+function defineSecret(name) {
+    const param = new types_1.SecretParam(name);
+    registerParam(param);
+    return param;
+}
+exports.defineSecret = defineSecret;
 /**
  * Declare a string param.
  *
@@ -106,17 +130,3 @@ function defineList(name, options = {}) {
     return param;
 }
 exports.defineList = defineList;
-/**
- * Declare a JSON param. The associated environment variable will be treated
- * as a JSON string when loading its value.
- *
- * @param name The name of the environment variable to use to load the param.
- * @param options Configuration options for the param.
- * @returns A Param with a specifiable return type for `.value`.
- */
-function defineJSON(name, options = {}) {
-    const param = new types_1.JSONParam(name, options);
-    registerParam(param);
-    return param;
-}
-exports.defineJSON = defineJSON;

package/lib/v2/params/types.d.ts

@@ -1,45 +1,118 @@
+export declare abstract class Expression<T extends string | number | boolean | string[]> {
+    value(): T;
+    toCEL(): string;
+    toJSON(): string;
+}
+/**
+ * A CEL expression corresponding to a ternary operator, e.g {{ cond ? ifTrue : ifFalse }}
+ */
+export declare class TernaryExpression<T extends string | number | boolean | string[]> extends Expression<T> {
+    private readonly test;
+    private readonly ifTrue;
+    private readonly ifFalse;
+    constructor(test: Expression<boolean>, ifTrue: T, ifFalse: T);
+    value(): T;
+    toString(): string;
+}
+/**
+ * A CEL expression that evaluates to boolean true or false based on a comparison
+ * between the value of another expression and a literal of that same type.
+ */
+export declare class CompareExpression<T extends string | number | boolean | string[]> extends Expression<boolean> {
+    cmp: '==' | '>' | '>=' | '<' | '<=';
+    lhs: Expression<T>;
+    rhs: T;
+    constructor(cmp: '==' | '>' | '>=' | '<' | '<=', lhs: Expression<T>, rhs: T);
+    value(): boolean;
+    toString(): string;
+    then(ifTrue: T, ifFalse: T): TernaryExpression<T>;
+}
 /** @hidden */
-declare type ParamValueType = 'string' | 'list' | 'boolean' | 'int' | 'float' | 'json';
-export interface ParamSpec<T = unknown> {
+declare type ParamValueType = 'string' | 'list' | 'boolean' | 'int' | 'float' | 'secret';
+declare type ParamInput<T> = {
+    text: TextInput<T>;
+} | {
+    select: SelectInput<T>;
+} | {
+    resource: ResourceInput;
+};
+/**
+ * Specifies that a Param's value should be determined by prompting the user
+ * to type it in interactively at deploy-time. Input that does not match the
+ * provided validationRegex, if present, will be retried.
+ */
+export interface TextInput<T = unknown> {
+    example?: string;
+    validationRegex?: string;
+    validationErrorMessage?: string;
+}
+/**
+ * Specifies that a Param's value should be determined by having the user
+ * select from a list containing all the project's resources of a certain
+ * type. Currently, only type:"storage.googleapis.com/Bucket" is supported.
+ */
+export interface ResourceInput {
+    resource: {
+        type: string;
+    };
+}
+/**
+ * Specifies that a Param's value should be determined by having the user select
+ * from a list of pre-canned options interactively at deploy-time.
+ */
+export interface SelectInput<T = unknown> {
+    options: Array<SelectOptions<T>>;
+}
+export interface SelectOptions<T = unknown> {
+    label?: string;
+    value: T;
+}
+export declare type ParamSpec<T = unknown> = {
     name: string;
     default?: T;
     label?: string;
     description?: string;
-    valueType?: ParamValueType;
-}
-export declare type ParamOptions<T = unknown> = Omit<ParamSpec<T>, 'name' | 'valueType'>;
-export declare class Param<T = unknown> {
+    type: ParamValueType;
+    input?: ParamInput<T>;
+};
+export declare type ParamOptions<T = unknown> = Omit<ParamSpec<T>, 'name' | 'type'>;
+export declare abstract class Param<T extends string | number | boolean | string[]> extends Expression<T> {
     readonly name: string;
     readonly options: ParamOptions<T>;
-    static valueType: ParamValueType;
+    static type: ParamValueType;
     constructor(name: string, options?: ParamOptions<T>);
-    get rawValue(): string | undefined;
-    get value(): any;
+    value(): T;
+    cmp(cmp: '==' | '>' | '>=' | '<' | '<=', rhs: T): CompareExpression<T>;
+    equals(rhs: T): CompareExpression<T>;
     toString(): string;
-    toJSON(): string;
+    toSpec(): ParamSpec<T>;
+}
+export declare class SecretParam {
+    name: string;
+    static type: ParamValueType;
+    constructor(name: string);
+    value(): string;
     toSpec(): ParamSpec<string>;
 }
 export declare class StringParam extends Param<string> {
+    value(): string;
 }
 export declare class IntParam extends Param<number> {
-    static valueType: ParamValueType;
-    get value(): number;
+    static type: ParamValueType;
+    value(): number;
 }
 export declare class FloatParam extends Param<number> {
-    static valueType: ParamValueType;
-    get value(): number;
+    static type: ParamValueType;
+    value(): number;
 }
-export declare class BooleanParam extends Param {
-    static valueType: ParamValueType;
-    get value(): boolean;
+export declare class BooleanParam extends Param<boolean> {
+    static type: ParamValueType;
+    value(): boolean;
+    then<T extends string | number | boolean>(ifTrue: T, ifFalse: T): TernaryExpression<T>;
 }
 export declare class ListParam extends Param<string[]> {
-    static valueType: ParamValueType;
-    get value(): string[];
-    toSpec(): ParamSpec<string>;
-}
-export declare class JSONParam<T = any> extends Param<T> {
-    static valueType: ParamValueType;
-    get value(): T;
+    static type: ParamValueType;
+    value(): string[];
+    toSpec(): ParamSpec<string[]>;
 }
 export {};