Implement Experiments feature

.github/workflows/node-test.yml

@@ -61,7 +61,6 @@ jobs:
     runs-on: ubuntu-latest
 
     env:
-      FIREBASE_CLI_PREVIEWS: none
       FIREBASE_EMULATORS_PATH: ${{ github.workspace }}/emulator-cache
       COMMIT_SHA: ${{ github.sha }}
       CI_JOB_ID: ${{ github.action }}
@@ -116,7 +115,6 @@ jobs:
     runs-on: windows-latest
 
     env:
-      FIREBASE_CLI_PREVIEWS: none
       FIREBASE_EMULATORS_PATH: ${{ github.workspace }}/emulator-cache
       COMMIT_SHA: ${{ github.sha }}
       CI_JOB_ID: ${{ github.action }}

src/commands/database-instances-list.ts

@@ -9,7 +9,7 @@ import { needProjectNumber } from "../projectUtils";
 import firedata = require("../gcp/firedata");
 import { Emulators } from "../emulator/types";
 import { warnEmulatorNotSupported } from "../emulator/commandUtils";
-import { previews } from "../previews";
+import * as experiments from "../experiments";
 import { needProjectId } from "../projectUtils";
 import {
   listDatabaseInstances,
@@ -52,7 +52,7 @@ export let command = new Command("database:instances:list")
     ).start();
     let instances;
 
-    if (previews.rtdbmanagement) {
+    if (experiments.isEnabled("rtdbmanagement")) {
       const projectId = needProjectId(options);
       try {
         instances = await listDatabaseInstances(projectId, location);
@@ -80,7 +80,7 @@ export let command = new Command("database:instances:list")
     return instances;
   });
 
-if (previews.rtdbmanagement) {
+if (experiments.isEnabled("rtdbmanagement")) {
   command = command.option(
     "-l, --location <location>",
     "(optional) location for the database instance, defaults to us-central1"

src/commands/ext-install.ts

@@ -30,7 +30,7 @@ import { getRandomString } from "../extensions/utils";
 import { requirePermissions } from "../requirePermissions";
 import * as utils from "../utils";
 import { track } from "../track";
-import { previews } from "../previews";
+import * as experiments from "../experiments";
 import { Options } from "../options";
 import * as manifest from "../extensions/manifest";
 
@@ -44,7 +44,7 @@ marked.setOptions({
 export const command = new Command("ext:install [extensionName]")
   .description(
     "install an official extension if [extensionName] or [extensionName@version] is provided; " +
-      (previews.extdev
+      (experiments.isEnabled("extdev")
         ? "install a local extension if [localPathOrUrl] or [url#root] is provided; install a published extension (not authored by Firebase) if [publisherId/extensionId] is provided "
         : "") +
       "or run with `-i` to see all available extensions."

src/commands/ext-update.ts

@@ -22,7 +22,7 @@ import * as refs from "../extensions/refs";
 import { getProjectId } from "../projectUtils";
 import { requirePermissions } from "../requirePermissions";
 import * as utils from "../utils";
-import { previews } from "../previews";
+import * as experiments from "../experiments";
 import * as manifest from "../extensions/manifest";
 import { Options } from "../options";
 import * as askUserForEventsConfig from "../extensions/askUserForEventsConfig";
@@ -36,7 +36,7 @@ marked.setOptions({
  */
 export const command = new Command("ext:update <extensionInstanceId> [updateSource]")
   .description(
-    previews.extdev
+    experiments.isEnabled("extdev")
       ? "update an existing extension instance to the latest version or from a local or URL source"
       : "update an existing extension instance to the latest version"
   )

src/commands/index.ts

@@ -1,5 +1,8 @@
-import { previews } from "../previews";
+import * as experiments from "../experiments";
 
+/**
+ * Loads all commands for our parser.
+ */
 export function load(client: any): any {
   function loadCommand(name: string) {
     const t0 = process.hrtime.bigint();
@@ -48,7 +51,7 @@ export function load(client: any): any {
   client.database.profile = loadCommand("database-profile");
   client.database.push = loadCommand("database-push");
   client.database.remove = loadCommand("database-remove");
-  if (previews.rtdbrules) {
+  if (experiments.isEnabled("rtdbrules")) {
     client.database.rules = {};
     client.database.rules.get = loadCommand("database-rules-get");
     client.database.rules.list = loadCommand("database-rules-list");
@@ -77,11 +80,11 @@ export function load(client: any): any {
   client.ext.list = loadCommand("ext-list");
   client.ext.uninstall = loadCommand("ext-uninstall");
   client.ext.update = loadCommand("ext-update");
-  if (previews.ext) {
+  if (experiments.isEnabled("ext")) {
     client.ext.sources = {};
     client.ext.sources.create = loadCommand("ext-sources-create");
   }
-  if (previews.extdev) {
+  if (experiments.isEnabled("extdev")) {
     client.ext.dev = {};
     client.ext.dev.init = loadCommand("ext-dev-init");
     client.ext.dev.list = loadCommand("ext-dev-list");
@@ -110,7 +113,7 @@ export function load(client: any): any {
   client.functions.log = loadCommand("functions-log");
   client.functions.shell = loadCommand("functions-shell");
   client.functions.list = loadCommand("functions-list");
-  if (previews.deletegcfartifacts) {
+  if (experiments.isEnabled("deletegcfartifacts")) {
     client.functions.deletegcfartifacts = loadCommand("functions-deletegcfartifacts");
   }
   client.functions.secrets = {};

src/deploy/functions/build.ts

@@ -2,7 +2,7 @@ import * as backend from "./backend";
 import * as proto from "../../gcp/proto";
 import * as api from "../../.../../api";
 import * as params from "./params";
-import { previews } from "../../previews";
+import * as experiments from "../../experiments";
 import { FirebaseError } from "../../error";
 import { assertExhaustive, mapObject, nullsafeVisitor } from "../../functional";
 import { UserEnvsOpts, writeUserEnvs } from "../../functions/env";
@@ -281,7 +281,7 @@ export async function resolveBackend(
   nonInteractive?: boolean
 ): Promise<{ backend: backend.Backend; envs: Record<string, params.ParamValue> }> {
   let paramValues: Record<string, params.ParamValue> = {};
-  if (previews.functionsparams) {
+  if (experiments.isEnabled("functionsparams")) {
     paramValues = await params.resolveParams(
       build.params,
       firebaseConfig,

src/deploy/functions/prepare.ts

@@ -29,7 +29,7 @@ import { FirebaseError } from "../../error";
 import { configForCodebase, normalizeAndValidate } from "../../functions/projectConfig";
 import { AUTH_BLOCKING_EVENTS } from "../../functions/events/v1";
 import { generateServiceIdentity } from "../../gcp/serviceusage";
-import { previews } from "../../previews";
+import * as experiments from "../../experiments";
 import { applyBackendHashToBackends } from "./cache/applyHash";
 import { allEndpoints, Backend } from "./backend";
 
@@ -272,7 +272,7 @@ export async function prepare(
    * This must be called after `await validate.secretsAreValid`.
    */
   updateEndpointTargetedStatus(wantBackends, context.filters || []);
-  if (previews.skipdeployingnoopfunctions) {
+  if (experiments.isEnabled("skipdeployingnoopfunctions")) {
     applyBackendHashToBackends(wantBackends, context);
   }
 }
@@ -346,6 +346,9 @@ function maybeCopyTriggerRegion(wantE: backend.Endpoint, haveE: backend.Endpoint
   wantE.eventTrigger.region = haveE.eventTrigger.region;
 }
 
+/**
+ * Determines whether endpoints are targeted by an --only flag.
+ */
 export function updateEndpointTargetedStatus(
   wantBackends: Record<string, Backend>,
   endpointFilters: EndpointFilter[]

src/deploy/functions/release/planner.ts

@@ -1,3 +1,5 @@
+import * as clc from "colorette";
+
 import {
   EndpointFilter,
   endpointMatchesAnyFilter,
@@ -8,7 +10,7 @@ import { FirebaseError } from "../../../error";
 import * as utils from "../../../utils";
 import * as backend from "../backend";
 import * as v2events from "../../../functions/events/v2";
-import { previews } from "../../../previews";
+import * as experiments from "../../../experiments";
 
 export interface EndpointUpdate {
   endpoint: backend.Endpoint;
@@ -54,7 +56,7 @@ export function calculateChangesets(
     keyFn
   );
 
-  const { skipdeployingnoopfunctions } = previews;
+  const skipdeployingnoopfunctions = experiments.isEnabled("skipdeployingnoopfunctions");
 
   // If the hashes are matching, that means the local function is the same as the server copy.
   const toSkipPredicate = (id: string): boolean =>
@@ -75,6 +77,14 @@ export function calculateChangesets(
     }, {});
 
   const toSkip = utils.groupBy(Object.values(toSkipEndpointsMap), keyFn);
+  if (Object.keys(toSkip).length) {
+    utils.logLabeledBullet(
+      "functions",
+      `Skipping the deploy of unchanged functions with ${clc.bold(
+        "experimental"
+      )} support for skipdeployingnoopfunctions`
+    );
+  }
 
   const toUpdate = utils.groupBy(
     Object.keys(want)

src/deploy/index.ts

@@ -7,7 +7,7 @@ import { logBullet, logSuccess, consoleUrl, addSubdomain } from "../utils";
 import { FirebaseError } from "../error";
 import { track } from "../track";
 import { lifecycleHooks } from "./lifecycleHooks";
-import { previews } from "../previews";
+import * as experiments from "../experiments";
 import * as HostingTarget from "./hosting";
 import * as DatabaseTarget from "./database";
 import * as FirestoreTarget from "./firestore";
@@ -56,9 +56,10 @@ export const deploy = async function (
   const postdeploys: Chain = [];
   const startTime = Date.now();
 
-  if (previews.frameworkawareness && targetNames.includes("hosting")) {
+  if (targetNames.includes("hosting")) {
     const config = options.config.get("hosting");
     if (Array.isArray(config) ? config.some((it) => it.source) : config.source) {
+      experiments.assertEnabled("frameworkawareness", "deploy a web framework to hosting");
       await prepareFrameworks(targetNames, context, options);
     }
   }

src/emulator/controller.ts

@@ -51,7 +51,7 @@ import { ExtensionsEmulator } from "./extensionsEmulator";
 import { normalizeAndValidate } from "../functions/projectConfig";
 import { requiresJava } from "./downloadableEmulators";
 import { prepareFrameworks } from "../frameworks";
-import { previews } from "../previews";
+import * as experiments from "../experiments";
 
 const START_LOGGING_EMULATOR = utils.envOverride(
   "START_LOGGING_EMULATOR",
@@ -323,6 +323,9 @@ interface EmulatorOptions extends Options {
   extDevEnv?: Record<string, string>;
 }
 
+/**
+ * Start all emulators.
+ */
 export async function startAll(
   options: EmulatorOptions,
   showUI = true
@@ -395,11 +398,10 @@ export async function startAll(
     }
   }
 
-  if (previews.frameworkawareness) {
-    const config = options.config.get("hosting");
-    if (Array.isArray(config) ? config.some((it) => it.source) : config?.source) {
-      await prepareFrameworks(targets, options, options);
-    }
+  const config = options.config.get("hosting");
+  if (Array.isArray(config) ? config.some((it) => it.source) : config?.source) {
+    experiments.assertEnabled("frameworkawareness", "emulate a web framework with hosting");
+    await prepareFrameworks(targets, options, options);
   }
 
   function startEmulator(instance: EmulatorInstance): Promise<void> {

src/emulator/downloadableEmulators.ts

@@ -18,7 +18,7 @@ import * as path from "path";
 import * as os from "os";
 import { EmulatorRegistry } from "./registry";
 import { downloadEmulator } from "../emulator/download";
-import { previews } from "../previews";
+import * as experiments from "../experiments";
 
 const EMULATOR_INSTANCE_KILL_TIMEOUT = 4000; /* ms */
 
@@ -62,7 +62,7 @@ export const DownloadDetails: { [s in DownloadableEmulators]: EmulatorDownloadDe
       namePrefix: "cloud-storage-rules-emulator",
     },
   },
-  ui: previews.emulatoruisnapshot
+  ui: experiments.isEnabled("emulatoruisnapshot")
     ? {
         version: "SNAPSHOT",
         downloadPath: path.join(CACHE_DIR, "ui-vSNAPSHOT.zip"),
@@ -286,6 +286,9 @@ async function _fatal(emulator: Emulators, errorMsg: string): Promise<void> {
   }
 }
 
+/**
+ * Handle errors in an emulator process.
+ */
 export async function handleEmulatorProcessError(emulator: Emulators, err: any): Promise<void> {
   const description = Constants.description(emulator);
   if (err.path === "java" && err.code === "ENOENT") {
@@ -298,6 +301,9 @@ export async function handleEmulatorProcessError(emulator: Emulators, err: any):
   }
 }
 
+/**
+ * Do the selected list of emulators depend on the JRE.
+ */
 export function requiresJava(emulator: Emulators): boolean {
   if (emulator in Commands) {
     return Commands[emulator as keyof typeof Commands].binary === "java";

src/emulator/storage/rules/runtime.ts

@@ -32,10 +32,10 @@ import {
 } from "../../downloadableEmulators";
 import { EmulatorRegistry } from "../../registry";
 import { Client } from "../../../apiv2";
-import { previews } from "../../../previews";
+import * as experiments from "../../../experiments";
 
 const lock = new AsyncLock();
-const synchonizationKey: string = "key";
+const synchonizationKey = "key";
 
 export interface RulesetVerificationOpts {
   file: {
@@ -443,8 +443,9 @@ async function fetchFirestoreDocument(
   projectId: string,
   request: RuntimeActionFirestoreDataRequest
 ): Promise<RuntimeActionFirestoreDataResponse> {
-  // If preview not enabled, just throw an error
-  if (!previews.crossservicerules) {
+  // If experiment is not enabled, just throw an error
+  // TODO: should this be an assertEnabled instead?
+  if (!experiments.isEnabled("crossservicerules")) {
     return { status: DataLoadStatus.INVALID_STATE, warnings: [], errors: [] };
   }