Add RESET_VALUE configuration value as sentinel value to reset a config option. (#1250)

Instead of allowing `null`s to reset a configuration value, we are introducing a new sentinel value, `RESET_VALUE` to make it clear the intention of resetting the config value to platform default:

```js
import * as functions from "firebase-functions/v1";
import { onRequest } from "firebase-functions/v2/https";
import { RESET_VALUE } from "firebase-functions/v2/options";

export const v1Req = functions
  .runWith({
    minInstances: functions.RESET_VALUE,
    memory: functions.RESET_VALUE,
    serviceAccount: RESET_VALUE
  }).https.onRequest(
    (req, res) => {
      res.sendStatus(200)
    },
);

export const v2Req = onRequest(
  {
   memory: RESET_VALUE,
   minInstances: RESET_VALUE,
  },
  (req, res) => {
    res.sendStatus(200)
  },
);
```

Majority of this PR concerns fixing/updating typings on various configuration options.

Recall that in v2, we inlined/repeat all function options in each respective providers to make reference doc more clear. This unfortunately bloated up this PR since I had to repeat the changes in each and every provider.

Author: taeold

spec/runtime/manifest.spec.ts

@@ -1,13 +1,15 @@
 import { expect } from "chai";
 import { stackToWire, ManifestStack } from "../../src/runtime/manifest";
 import * as params from "../../src/params";
+import * as optsv2 from "../../src/v2/options";
+import * as v1 from "../../src/v1";
 
 describe("stackToWire", () => {
   afterEach(() => {
     params.clearParams();
   });
 
-  it("converts stack with null values values", () => {
+  it("converts stack with null values", () => {
     const stack: ManifestStack = {
       endpoints: {
         v2http: {
@@ -37,6 +39,50 @@ describe("stackToWire", () => {
     expect(stackToWire(stack)).to.deep.equal(expected);
   });
 
+  it("converts stack with RESET_VALUES", () => {
+    const stack: ManifestStack = {
+      endpoints: {
+        v1http: {
+          platform: "gcfv1",
+          entryPoint: "v1http",
+          labels: {},
+          httpsTrigger: {},
+          maxInstances: v1.RESET_VALUE,
+        },
+        v2http: {
+          platform: "gcfv2",
+          entryPoint: "v2http",
+          labels: {},
+          httpsTrigger: {},
+          maxInstances: optsv2.RESET_VALUE,
+        },
+      },
+      requiredAPIs: [],
+      specVersion: "v1alpha1",
+    };
+    const expected = {
+      endpoints: {
+        v1http: {
+          platform: "gcfv1",
+          entryPoint: "v1http",
+          labels: {},
+          httpsTrigger: {},
+          maxInstances: null,
+        },
+        v2http: {
+          platform: "gcfv2",
+          entryPoint: "v2http",
+          labels: {},
+          httpsTrigger: {},
+          maxInstances: null,
+        },
+      },
+      requiredAPIs: [],
+      specVersion: "v1alpha1",
+    };
+    expect(stackToWire(stack)).to.deep.equal(expected);
+  });
+
   it("converts Expression types in endpoint options to CEL", () => {
     const intParam = params.defineInt("foo", { default: 11 });
     const stringParam = params.defineString("bar", {

src/common/options.ts

@@ -0,0 +1,42 @@
+// 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.
+
+/**
+ * Special configuration type to reset configuration to platform default.
+ *
+ * @alpha
+ */
+export class ResetValue {
+  toJSON(): null {
+    return null;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  private constructor() {}
+  public static getInstance() {
+    return new ResetValue();
+  }
+}
+
+/**
+ * Special configuration value to reset configuration to platform default.
+ */
+export const RESET_VALUE = ResetValue.getInstance();

src/common/providers/tasks.ts

@@ -26,38 +26,39 @@ import { DecodedIdToken } from "firebase-admin/auth";
 import * as logger from "../../logger";
 import * as https from "./https";
 import { Expression } from "../../params";
+import { ResetValue } from "../options";
 
 /** How a task should be retried in the event of a non-2xx return. */
 export interface RetryConfig {
   /**
    * Maximum number of times a request should be attempted.
    * If left unspecified, will default to 3.
    */
-  maxAttempts?: number | Expression<number> | null;
+  maxAttempts?: number | Expression<number> | ResetValue;
 
   /**
    * Maximum amount of time for retrying failed task.
    * If left unspecified will retry indefinitely.
    */
-  maxRetrySeconds?: number | Expression<number> | null;
+  maxRetrySeconds?: number | Expression<number> | ResetValue;
 
   /**
    * The maximum amount of time to wait between attempts.
    * If left unspecified will default to 1hr.
    */
-  maxBackoffSeconds?: number | Expression<number> | null;
+  maxBackoffSeconds?: number | Expression<number> | ResetValue;
 
   /**
    * The maximum number of times to double the backoff between
    * retries. If left unspecified will default to 16.
    */
-  maxDoublings?: number | Expression<number> | null;
+  maxDoublings?: number | Expression<number> | ResetValue;
 
   /**
    * The minimum time to wait between attempts. If left unspecified
    * will default to 100ms.
    */
-  minBackoffSeconds?: number | Expression<number> | null;
+  minBackoffSeconds?: number | Expression<number> | ResetValue;
 }
 
 /** How congestion control should be applied to the function. */
@@ -66,13 +67,13 @@ export interface RateLimits {
    * The maximum number of requests that can be outstanding at a time.
    * If left unspecified, will default to 1000.
    */
-  maxConcurrentDispatches?: number | Expression<number> | null;
+  maxConcurrentDispatches?: number | Expression<number> | ResetValue;
 
   /**
    * The maximum number of requests that can be invoked per second.
    * If left unspecified, will default to 500.
    */
-  maxDispatchesPerSecond?: number | Expression<number> | null;
+  maxDispatchesPerSecond?: number | Expression<number> | ResetValue;
 }
 
 /** Metadata about the authorization used to invoke a function. */

src/runtime/manifest.ts

@@ -20,6 +20,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
+import { ResetValue } from "../common/options";
 import { Expression } from "../params";
 import { WireParamSpec } from "../params/types";
 
@@ -30,19 +31,19 @@ export interface ManifestEndpoint {
   entryPoint?: string;
   region?: string[];
   platform?: string;
-  availableMemoryMb?: number | Expression<number>;
-  maxInstances?: number | Expression<number>;
-  minInstances?: number | Expression<number>;
-  concurrency?: number | Expression<number>;
-  serviceAccountEmail?: string;
-  timeoutSeconds?: number | Expression<number>;
-  cpu?: number | "gcf_gen1";
+  availableMemoryMb?: number | Expression<number> | ResetValue;
+  maxInstances?: number | Expression<number> | ResetValue;
+  minInstances?: number | Expression<number> | ResetValue;
+  concurrency?: number | Expression<number> | ResetValue;
+  timeoutSeconds?: number | Expression<number> | ResetValue;
   vpc?: {
-    connector: string | Expression<string>;
-    egressSettings?: string;
+    connector: string | Expression<string> | ResetValue;
+    egressSettings?: string | Expression<string> | ResetValue;
   };
+  serviceAccountEmail?: string | Expression<string> | ResetValue;
+  cpu?: number | "gcf_gen1";
   labels?: Record<string, string>;
-  ingressSettings?: string;
+  ingressSettings?: string | Expression<string> | ResetValue;
   environmentVariables?: Record<string, string>;
   secretEnvironmentVariables?: Array<{ key: string; secret?: string }>;
 
@@ -57,20 +58,38 @@ export interface ManifestEndpoint {
     eventFilterPathPatterns?: Record<string, string | Expression<string>>;
     channel?: string;
     eventType: string;
-    retry: boolean | Expression<boolean>;
+    retry: boolean | Expression<boolean> | ResetValue;
     region?: string;
-    serviceAccountEmail?: string;
+    serviceAccountEmail?: string | ResetValue;
+  };
+
+  taskQueueTrigger?: {
+    retryConfig?: {
+      maxAttempts?: number | Expression<number> | ResetValue;
+      maxRetrySeconds?: number | Expression<number> | ResetValue;
+      maxBackoffSeconds?: number | Expression<number> | ResetValue;
+      maxDoublings?: number | Expression<number> | ResetValue;
+      minBackoffSeconds?: number | Expression<number> | ResetValue;
+    };
+    rateLimits?: {
+      maxConcurrentDispatches?: number | Expression<number> | ResetValue;
+      maxDispatchesPerSecond?: number | Expression<number> | ResetValue;
+    };
   };
 
   scheduleTrigger?: {
-    schedule?: string | Expression<string>;
-    timeZone?: string | Expression<string>;
+    schedule: string | Expression<string>;
+    timeZone?: string | Expression<string> | ResetValue;
     retryConfig?: {
-      retryCount?: number | Expression<number>;
-      maxRetrySeconds?: string | Expression<string>;
-      minBackoffSeconds?: string | Expression<string>;
-      maxBackoffSeconds?: string | Expression<string>;
-      maxDoublings?: number | Expression<number>;
+      retryCount?: number | Expression<number> | ResetValue;
+      maxRetrySeconds?: string | Expression<string> | ResetValue;
+      minBackoffSeconds?: string | Expression<string> | ResetValue;
+      maxBackoffSeconds?: string | Expression<string> | ResetValue;
+      maxDoublings?: number | Expression<number> | ResetValue;
+      // Note: v1 schedule functions use *Duration instead of *Seconds
+      maxRetryDuration?: string | Expression<string> | ResetValue;
+      minBackoffDuration?: string | Expression<string> | ResetValue;
+      maxBackoffDuration?: string | Expression<string> | ResetValue;
     };
   };
 
@@ -107,6 +126,8 @@ export function stackToWire(stack: ManifestStack): Record<string, unknown> {
     for (const [key, val] of Object.entries(obj)) {
       if (val instanceof Expression) {
         obj[key] = val.toCEL();
+      } else if (val instanceof ResetValue) {
+        obj[key] = val.toJSON();
       } else if (typeof val === "object" && val !== null) {
         // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
         traverse(val as any);

src/v1/cloud-functions.ts

@@ -22,10 +22,11 @@
 
 import { Request, Response } from "express";
 import { warn } from "../logger";
-import { DeploymentOptions } from "./function-configuration";
+import { DeploymentOptions, RESET_VALUE } from "./function-configuration";
 export { Request, Response };
 import { convertIfPresent, copyIfPresent } from "../common/encoding";
 import { ManifestEndpoint, ManifestRequiredAPI } from "../runtime/manifest";
+import { ResetValue } from "../common/options";
 
 export { Change } from "../common/change";
 
@@ -372,7 +373,7 @@ export function makeCloudFunction<EventData>({
       };
 
       if (options.schedule) {
-        endpoint.scheduleTrigger = options.schedule;
+        endpoint.scheduleTrigger = options.schedule as any;
       } else {
         endpoint.eventTrigger = {
           eventType: legacyEventType || provider + "." + eventType,
@@ -471,9 +472,14 @@ export function optionsToEndpoint(options: DeploymentOptions): ManifestEndpoint
   convertIfPresent(endpoint, options, "secretEnvironmentVariables", "secrets", (secrets) =>
     secrets.map((secret) => ({ key: secret }))
   );
-  if (options?.vpcConnector) {
-    endpoint.vpc = { connector: options.vpcConnector };
-    convertIfPresent(endpoint.vpc, options, "egressSettings", "vpcConnectorEgressSettings");
+  if (options?.vpcConnector !== undefined) {
+    if (options.vpcConnector === null || options.vpcConnector instanceof ResetValue) {
+      endpoint.vpc = { connector: RESET_VALUE, egressSettings: RESET_VALUE };
+    } else {
+      const vpc: ManifestEndpoint["vpc"] = { connector: options.vpcConnector };
+      convertIfPresent(vpc, options, "egressSettings", "vpcConnectorEgressSettings");
+      endpoint.vpc = vpc;
+    }
   }
   convertIfPresent(endpoint, options, "availableMemoryMb", "memory", (mem) => {
     const memoryLookup = {
@@ -485,7 +491,7 @@ export function optionsToEndpoint(options: DeploymentOptions): ManifestEndpoint
       "4GB": 4096,
       "8GB": 8192,
     };
-    return memoryLookup[mem];
+    return typeof mem === "object" ? mem : memoryLookup[mem];
   });
   return endpoint;
 }

src/v1/function-builder.ts

@@ -22,6 +22,7 @@
 
 import * as express from "express";
 
+import { ResetValue } from "../common/options";
 import { EventContext } from "./cloud-functions";
 import {
   DeploymentOptions,
@@ -50,7 +51,8 @@ import * as testLab from "./providers/testLab";
  * @throws { Error } Memory and TimeoutSeconds values must be valid.
  */
 function assertRuntimeOptionsValid(runtimeOptions: RuntimeOptions): boolean {
-  if (runtimeOptions.memory && !VALID_MEMORY_OPTIONS.includes(runtimeOptions.memory)) {
+  const mem = runtimeOptions.memory;
+  if (mem && !(mem instanceof ResetValue) && !VALID_MEMORY_OPTIONS.includes(mem)) {
     throw new Error(
       `The only valid memory allocation values are: ${VALID_MEMORY_OPTIONS.join(", ")}`
     );
@@ -61,6 +63,7 @@ function assertRuntimeOptionsValid(runtimeOptions: RuntimeOptions): boolean {
 
   if (
     runtimeOptions.ingressSettings &&
+    !(runtimeOptions.ingressSettings instanceof ResetValue) &&
     !INGRESS_SETTINGS_OPTIONS.includes(runtimeOptions.ingressSettings)
   ) {
     throw new Error(
@@ -70,6 +73,7 @@ function assertRuntimeOptionsValid(runtimeOptions: RuntimeOptions): boolean {
 
   if (
     runtimeOptions.vpcConnectorEgressSettings &&
+    !(runtimeOptions.vpcConnectorEgressSettings instanceof ResetValue) &&
     !VPC_EGRESS_SETTINGS_OPTIONS.includes(runtimeOptions.vpcConnectorEgressSettings)
   ) {
     throw new Error(
@@ -80,10 +84,12 @@ function assertRuntimeOptionsValid(runtimeOptions: RuntimeOptions): boolean {
   }
 
   validateFailurePolicy(runtimeOptions.failurePolicy);
+  const serviceAccount = runtimeOptions.serviceAccount;
   if (
-    runtimeOptions.serviceAccount &&
-    runtimeOptions.serviceAccount !== "default" &&
-    !runtimeOptions.serviceAccount.includes("@")
+    serviceAccount &&
+    serviceAccount !== "default" &&
+    !(serviceAccount instanceof ResetValue) &&
+    !serviceAccount.includes("@")
   ) {
     throw new Error(
       `serviceAccount must be set to 'default', a service account email, or '{serviceAccountName}@'`