Add new option to preserveExternalChanges.

Author: taeold

spec/common/options.ts

@@ -0,0 +1,36 @@
+// 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 ignoreUnusedWarning OR OTHER DEALINGS IN THE
+// SOFTWARE.
+import { ResettableKeys, ResetValue } from "../../src/common/options";
+import { expectNever, expectType } from "./metaprogramming";
+
+describe("ResettableKeys", () => {
+  it("should pick out keys with a type that includes ResetValue", () => {
+    type A = { a: number; b: ResetValue; c: number | boolean | ResetValue };
+    expectType<keyof ResettableKeys<A>>("b");
+    expectType<keyof ResettableKeys<A>>("c");
+  });
+
+  it("should return an empty type if no keys are resettable", () => {
+    type A = { a: number };
+    expectNever<keyof ResettableKeys<A>>();
+  });
+});

src/common/options.ts

@@ -40,3 +40,10 @@ export class ResetValue {
  * Special configuration value to reset configuration to platform default.
  */
 export const RESET_VALUE = ResetValue.getInstance();
+
+/**
+ * @internal
+ */
+export type ResettableKeys<T> = Required<{
+  [K in keyof T as [ResetValue] extends [T[K]] ? K : never]: null;
+}>;

src/common/providers/tasks.ts

@@ -26,7 +26,7 @@ import { DecodedIdToken } from "firebase-admin/auth";
 import * as logger from "../../logger";
 import * as https from "./https";
 import { Expression } from "../../params";
-import { ResetValue } from "../options";
+import { ResettableKeys, ResetValue } from "../options";
 
 /** How a task should be retried in the event of a non-2xx return. */
 export interface RetryConfig {
@@ -108,6 +108,21 @@ export interface Request<T = any> {
 type v1TaskHandler = (data: any, context: TaskContext) => void | Promise<void>;
 type v2TaskHandler<Req> = (request: Request<Req>) => void | Promise<void>;
 
+/** @internal */
+export const RESETTABLE_RETRY_CONFIG_OPTIONS: ResettableKeys<RetryConfig> = {
+  maxAttempts: null,
+  maxDoublings: null,
+  maxBackoffSeconds: null,
+  maxRetrySeconds: null,
+  minBackoffSeconds: null,
+};
+
+/** @internal */
+export const RESETTABLE_RATE_LIMITS_OPTIONS: ResettableKeys<RateLimits> = {
+  maxConcurrentDispatches: null,
+  maxDispatchesPerSecond: null,
+};
+
 /** @internal */
 export function onDispatchHandler<Req = any>(
   handler: v1TaskHandler | v2TaskHandler<Req>

src/runtime/manifest.ts

@@ -63,15 +63,33 @@ export interface ManifestEndpoint {
     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>;
+    schedule: string | Expression<string>;
     timeZone?: string | Expression<string> | ResetValue;
     retryConfig?: {
       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;
     };
   };
 

src/v1/cloud-functions.ts

@@ -22,11 +22,15 @@
 
 import { Request, Response } from "express";
 import { warn } from "../logger";
-import { DeploymentOptions } from "./function-configuration";
+import {
+  DeploymentOptions,
+  RESET_VALUE,
+  RESETTABLE_SCHEDULE_OPTIONS,
+} from "./function-configuration";
 export { Request, Response };
 import { convertIfPresent, copyIfPresent } from "../common/encoding";
 import { ManifestEndpoint, ManifestRequiredAPI } from "../runtime/manifest";
-import { ResetValue } from "../common/options";
+import { ResettableKeys, ResetValue } from "../common/options";
 
 export { Change } from "../common/change";
 
@@ -373,7 +377,28 @@ export function makeCloudFunction<EventData>({
       };
 
       if (options.schedule) {
-        endpoint.scheduleTrigger = options.schedule as any;
+        let scheduleTrigger: ManifestEndpoint["scheduleTrigger"] = {
+          schedule: options.schedule.schedule,
+        };
+        if (!options.preserveExternalChanges) {
+          const retryConfig = {};
+          for (const key of Object.keys(RESETTABLE_SCHEDULE_OPTIONS)) {
+            retryConfig[key] = RESET_VALUE;
+          }
+          scheduleTrigger = { ...scheduleTrigger, timeZone: RESET_VALUE, retryConfig };
+        }
+        endpoint.scheduleTrigger = scheduleTrigger;
+        copyIfPresent(endpoint.scheduleTrigger, options.schedule, "timeZone");
+        copyIfPresent(
+          endpoint.scheduleTrigger.retryConfig,
+          options.schedule.retryConfig,
+          "retryCount",
+          "maxDoublings",
+          "maxBackoffDuration",
+          "maxRetryDuration",
+          "minBackoffDuration"
+        );
+        endpoint.scheduleTrigger = scheduleTrigger;
       } else {
         endpoint.eventTrigger = {
           eventType: legacyEventType || provider + "." + eventType,
@@ -455,9 +480,23 @@ function _detectAuthType(event: Event) {
   return "UNAUTHENTICATED";
 }
 
+const RESETTABLE_OPTIONS: ResettableKeys<DeploymentOptions> = {
+  memory: null,
+  timeoutSeconds: null,
+  minInstances: null,
+  maxInstances: null,
+  vpcConnector: null,
+  serviceAccount: null,
+};
+
 /** @internal */
 export function optionsToEndpoint(options: DeploymentOptions): ManifestEndpoint {
   const endpoint: ManifestEndpoint = {};
+  if (!options.preserveExternalChanges) {
+    for (const key of Object.keys(RESETTABLE_OPTIONS)) {
+      endpoint[key] = RESET_VALUE;
+    }
+  }
   copyIfPresent(
     endpoint,
     options,

src/v1/function-configuration.ts

@@ -1,5 +1,5 @@
 import { Expression } from "../params";
-import { ResetValue } from "../common/options";
+import { ResettableKeys, ResetValue } from "../common/options";
 
 export { RESET_VALUE } from "../common/options";
 
@@ -255,4 +255,23 @@ export interface DeploymentOptions extends RuntimeOptions {
    * Schedule for the scheduled function.
    */
   schedule?: Schedule;
+  /**
+   * Controls whether function configuration modified outside of function source is preserved. Defaults to false.
+   *
+   * @remarks
+   * When setting configuration available in the underlying platform that is not yet available in the Firebase Functions
+   * SDK, we highly recommend setting preserveExternalChanges to true. Otherwise, when Firebase Functions SDK releases
+   * a new version of the SDK with the support for the missing configuration, your functions manually configured setting
+   * may inadvertently be wiped out.
+   */
+  preserveExternalChanges?: boolean;
 }
+
+/** @internal */
+export const RESETTABLE_SCHEDULE_OPTIONS: ResettableKeys<ScheduleRetryConfig> = {
+  retryCount: null,
+  maxBackoffDuration: null,
+  maxDoublings: null,
+  maxRetryDuration: null,
+  minBackoffDuration: null,
+};

src/v1/providers/tasks.ts

@@ -27,12 +27,14 @@ import { Request } from "../../common/providers/https";
 import {
   onDispatchHandler,
   RateLimits,
+  RESETTABLE_RATE_LIMITS_OPTIONS,
+  RESETTABLE_RETRY_CONFIG_OPTIONS,
   RetryConfig,
   TaskContext,
 } from "../../common/providers/tasks";
 import { ManifestEndpoint, ManifestRequiredAPI } from "../../runtime/manifest";
 import { optionsToEndpoint } from "../cloud-functions";
-import { DeploymentOptions } from "../function-configuration";
+import { DeploymentOptions, RESET_VALUE } from "../function-configuration";
 
 export { RetryConfig, RateLimits, TaskContext };
 
@@ -101,10 +103,23 @@ export class TaskQueueBuilder {
     const fixedLen = (data: any, context: TaskContext) => handler(data, context);
     const func: any = onDispatchHandler(fixedLen);
 
+    let taskQueueTrigger = {};
+    if (!this.depOpts?.preserveExternalChanges) {
+      const retryConfig = {};
+      for (const key of Object.keys(RESETTABLE_RETRY_CONFIG_OPTIONS)) {
+        retryConfig[key] = RESET_VALUE;
+      }
+      const rateLimits = {};
+      for (const key of Object.keys(RESETTABLE_RATE_LIMITS_OPTIONS)) {
+        rateLimits[key] = RESET_VALUE;
+      }
+      taskQueueTrigger = { retryConfig, rateLimits };
+    }
+
     func.__endpoint = {
       platform: "gcfv1",
       ...optionsToEndpoint(this.depOpts),
-      taskQueueTrigger: {},
+      taskQueueTrigger,
     };
     copyIfPresent(func.__endpoint.taskQueueTrigger, this.tqOpts, "retryConfig");
     copyIfPresent(func.__endpoint.taskQueueTrigger, this.tqOpts, "rateLimits");

src/v2/options.ts

@@ -26,7 +26,7 @@
  */
 
 import { convertIfPresent, copyIfPresent } from "../common/encoding";
-import { ResetValue } from "../common/options";
+import { RESET_VALUE, ResettableKeys, ResetValue } from "../common/options";
 import { ManifestEndpoint } from "../runtime/manifest";
 import { declaredParams, Expression } from "../params";
 import { ParamSpec } from "../params/types";
@@ -184,12 +184,25 @@ export interface GlobalOptions {
   secrets?: string[];
 
   /**
-   * Determines whether Firebase AppCheck is enforced.
+   * Determines whether Firebase AppCheck is enforced. Defaults to false.
+   *
+   * @remarks
    * When true, requests with invalid tokens autorespond with a 401
    * (Unauthorized) error.
    * When false, requests with invalid tokens set event.app to undefiend.
    */
   enforceAppCheck?: boolean;
+
+  /**
+   * Controls whether function configuration modified outside of function source is preserved. Defaults to false.
+   *
+   * @remarks
+   * When setting configuration available in the underlying platform that is not yet available in the Firebase Functions
+   * SDK, we highly recommend setting preserveExternalChanges to true. Otherwise, when Firebase Functions SDK releases
+   * a new version of the SDK with the support for the missing configuration, your functions manually configured setting
+   * may inadvertently be wiped out.
+   */
+  preserveExternalChanges?: boolean;
 }
 
 let globalOptions: GlobalOptions | undefined;
@@ -237,14 +250,36 @@ export interface EventHandlerOptions extends Omit<GlobalOptions, "enforceAppChec
   channel?: string;
 }
 
+const RESETTABLE_CONFIGS: ResettableKeys<GlobalOptions> = {
+  memory: null,
+  timeoutSeconds: null,
+  minInstances: null,
+  maxInstances: null,
+  ingressSettings: null,
+  vpcConnector: null,
+  vpcConnectorEgressSettings: null,
+  serviceAccount: null,
+  concurrency: null,
+};
+
+function initEndpoint(opts: GlobalOptions | EventHandlerOptions | HttpsOptions): ManifestEndpoint {
+  const endpoint: ManifestEndpoint = {};
+  if (!opts.preserveExternalChanges) {
+    for (const k of Object.keys(RESETTABLE_CONFIGS)) {
+      endpoint[k] = RESET_VALUE;
+    }
+  }
+  return endpoint;
+}
+
 /**
  * Apply GlobalOptions to endpoint manifest.
  * @internal
  */
 export function optionsToEndpoint(
   opts: GlobalOptions | EventHandlerOptions | HttpsOptions
 ): ManifestEndpoint {
-  const endpoint: ManifestEndpoint = {};
+  const endpoint = initEndpoint(opts);
   copyIfPresent(
     endpoint,
     opts,