feat: add warnings when using experimental triggers in Dart runtime

Lyokone · Lyokone · commit 72cf15bc34ab · 2026-04-14T09:45:03.000+02:00
diff --git a/src/deploy/functions/prepare.ts b/src/deploy/functions/prepare.ts
@@ -30,7 +30,8 @@ import {
   groupEndpointsByCodebase,
   targetCodebases,
 } from "./functionsDeployHelper";
-import { logLabeledBullet } from "../../utils";
+import { logLabeledBullet, logLabeledWarning } from "../../utils";
+import { isDartEndpoint, classifyEndpoints } from "./runtimes/dart/triggerSupport";
 import { getFunctionsConfig, prepareFunctionsUpload } from "./prepareFunctionsUpload";
 import { promptForFailurePolicies, promptForMinInstances } from "./prompts";
 import { needProjectId, needProjectNumber } from "../../projectUtils";
@@ -292,6 +293,7 @@ export async function prepare(
 
   await ensureAllRequiredAPIsEnabled(projectNumber, wantBackend);
   await warnIfNewGenkitFunctionIsMissingSecrets(wantBackend, haveBackend, options);
+  warnIfDartBackendHasUnsupportedTriggers(wantBackend);
 
   // ===Phase 6. Ask for user prompts for things might warrant user attentions.
   // We limit the scope endpoints being deployed.
@@ -541,6 +543,29 @@ export async function loadCodebases(
   return wantBuilds;
 }
 
+/**
+ * Warns when a Dart backend contains triggers that are not yet
+ * production-ready. Classification is owned by the shared
+ * `dart/triggerSupport` module.
+ */
+function warnIfDartBackendHasUnsupportedTriggers(want: backend.Backend): void {
+  const dartEndpoints = backend.allEndpoints(want).filter(isDartEndpoint);
+  if (dartEndpoints.length === 0) {
+    return;
+  }
+
+  const { emulatorOnly, experimental } = classifyEndpoints(dartEndpoints);
+  const unsupported = [...emulatorOnly, ...experimental];
+  if (unsupported.length > 0) {
+    logLabeledWarning(
+      "functions",
+      `The following Dart functions use triggers that are not yet supported for production deployment: ${unsupported.map((ep) => ep.id).join(", ")}. ` +
+        "They will be deployed but may not work as expected. " +
+        "See https://github.com/firebase/firebase-functions-dart#status-alpha-v010 for current trigger support.",
+    );
+  }
+}
+
 // Genkit almost always requires an API key, so warn if the customer is about to deploy
 // a function and doesn't have one. To avoid repetitive nagging, only warn on the first
 // deploy of the function.
diff --git a/src/deploy/functions/runtimes/dart/triggerSupport.ts b/src/deploy/functions/runtimes/dart/triggerSupport.ts
@@ -0,0 +1,198 @@
+/**
+ * Dart trigger support classification.
+ *
+ * Firebase Functions for Dart is in alpha. Only HTTPS triggers are
+ * production-ready today. Other trigger types have varying levels of
+ * support as documented in the firebase-functions-dart README.
+ *
+ * This module is the single source of truth for that classification and
+ * is consumed by both the emulator and the deploy pipeline so warnings
+ * stay consistent.
+ */
+
+import * as backend from "../../backend";
+import * as supported from "../supported";
+import { Constants } from "../../../../emulator/constants";
+
+// ---------------------------------------------------------------------------
+// Support levels
+// ---------------------------------------------------------------------------
+
+/**
+ * How well a Dart trigger type is supported today.
+ *
+ * - `production`    – works in both the emulator and production deployments.
+ * - `emulatorOnly`  – works in the Firebase emulator but cannot be deployed
+ *                     to production yet.
+ * - `experimental`  – implemented in the Dart SDK but not yet supported by
+ *                     the emulator or production. APIs may change.
+ */
+export type DartTriggerSupportLevel = "production" | "emulatorOnly" | "experimental";
+
+// ---------------------------------------------------------------------------
+// Service → support-level maps
+// ---------------------------------------------------------------------------
+
+/** Event-trigger services that work in the emulator only. */
+const EMULATOR_ONLY_SERVICES: ReadonlySet<string> = new Set([
+  Constants.SERVICE_FIRESTORE,
+  Constants.SERVICE_REALTIME_DATABASE,
+  Constants.SERVICE_STORAGE,
+]);
+
+/** Event-trigger services that are experimental. */
+const EXPERIMENTAL_SERVICES: ReadonlySet<string> = new Set([
+  Constants.SERVICE_PUBSUB,
+  Constants.SERVICE_EVENTARC,
+  Constants.SERVICE_AUTH,
+  Constants.SERVICE_FIREALERTS,
+  Constants.SERVICE_REMOTE_CONFIG,
+  Constants.SERVICE_TEST_LAB,
+  Constants.SERVICE_CLOUD_TASKS,
+]);
+
+// ---------------------------------------------------------------------------
+// Public helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the support level for a Dart endpoint's trigger type.
+ *
+ * The classification intentionally matches the status table in the
+ * firebase-functions-dart README:
+ * | Status            | Triggers                                           |
+ * |-------------------|----------------------------------------------------|
+ * | ✅ Production     | HTTPS (`onRequest`, `onCall`, `onCallWithData`)    |
+ * | ⚠️ Emulator only  | Firestore, Realtime Database, Storage              |
+ * | 🚧 Experimental   | Pub/Sub, Scheduler, Alerts, Eventarc, Identity,    |
+ * |                   | Remote Config, Test Lab, Tasks                     |
+ */
+export function endpointSupportLevel(ep: backend.Endpoint): DartTriggerSupportLevel {
+  // HTTPS and callable triggers are production-ready.
+  if (backend.isHttpsTriggered(ep) || backend.isCallableTriggered(ep)) {
+    // Task-queue functions look like HTTPS but are experimental.
+    if (backend.isTaskQueueTriggered(ep)) {
+      return "experimental";
+    }
+    return "production";
+  }
+
+  // Scheduled triggers are experimental (emulator converts them to pubsub).
+  if (backend.isScheduleTriggered(ep)) {
+    return "experimental";
+  }
+
+  // Blocking triggers (Identity Platform) are experimental.
+  if (backend.isBlockingTriggered(ep)) {
+    return "experimental";
+  }
+
+  // Remaining event triggers — classify by service.
+  if (backend.isEventTriggered(ep)) {
+    const service = ep.eventTrigger.eventType
+      ? serviceFromEventType(ep.eventTrigger.eventType)
+      : undefined;
+    if (service && EMULATOR_ONLY_SERVICES.has(service)) {
+      return "emulatorOnly";
+    }
+    if (service && EXPERIMENTAL_SERVICES.has(service)) {
+      return "experimental";
+    }
+  }
+
+  // Unknown trigger.
+  return "experimental";
+}
+
+/**
+ * Returns `true` when the given endpoint belongs to a Dart runtime.
+ */
+export function isDartEndpoint(ep: backend.Endpoint): boolean {
+  return supported.runtimeIsLanguage(ep.runtime, "dart");
+}
+
+/**
+ * Partitions a list of Dart endpoints by their support level.
+ *
+ * Only non-production endpoints are returned — callers never need to
+ * enumerate production-ready functions.
+ */
+export function classifyEndpoints(endpoints: backend.Endpoint[]): {
+  emulatorOnly: backend.Endpoint[];
+  experimental: backend.Endpoint[];
+} {
+  const emulatorOnly: backend.Endpoint[] = [];
+  const experimental: backend.Endpoint[] = [];
+
+  for (const ep of endpoints) {
+    switch (endpointSupportLevel(ep)) {
+      case "production":
+        break;
+      case "emulatorOnly":
+        emulatorOnly.push(ep);
+        break;
+      case "experimental":
+        experimental.push(ep);
+        break;
+    }
+  }
+
+  return { emulatorOnly, experimental };
+}
+
+/**
+ * Returns a human-readable trigger-type label for a Dart endpoint.
+ *
+ * Used to produce grouped warning messages like
+ * `Dart **firestore** triggers work in the emulator but …`
+ */
+export function triggerTypeLabel(ep: backend.Endpoint): string {
+  if (backend.isScheduleTriggered(ep)) return "scheduler";
+  if (backend.isTaskQueueTriggered(ep)) return "tasks";
+  if (backend.isBlockingTriggered(ep)) return "identity";
+  if (backend.isCallableTriggered(ep)) return "callable";
+  if (backend.isHttpsTriggered(ep)) return "https";
+  if (backend.isEventTriggered(ep)) {
+    const svc = serviceFromEventType(ep.eventTrigger.eventType);
+    return svc ? Constants.getServiceName(svc) : ep.eventTrigger.eventType;
+  }
+  return "unknown";
+}
+
+/**
+ * Groups endpoints by their {@link triggerTypeLabel} and returns a
+ * `Map<label, endpointIds[]>` suitable for building warning messages.
+ */
+export function groupByTriggerLabel(endpoints: backend.Endpoint[]): Map<string, string[]> {
+  const groups = new Map<string, string[]>();
+  for (const ep of endpoints) {
+    const label = triggerTypeLabel(ep);
+    const ids = groups.get(label) ?? [];
+    ids.push(ep.id);
+    groups.set(label, ids);
+  }
+  return groups;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Rough mapping from a CloudEvent `eventType` string to a service constant.
+ *
+ * This mirrors the logic in `functionsEmulatorShared.getServiceFromEventType`
+ * but is kept local so the module stays self-contained.
+ */
+function serviceFromEventType(eventType: string): string | undefined {
+  if (eventType.includes("firestore")) return Constants.SERVICE_FIRESTORE;
+  if (eventType.includes("database")) return Constants.SERVICE_REALTIME_DATABASE;
+  if (eventType.includes("pubsub")) return Constants.SERVICE_PUBSUB;
+  if (eventType.includes("storage")) return Constants.SERVICE_STORAGE;
+  if (eventType.includes("firebasealerts")) return Constants.SERVICE_FIREALERTS;
+  if (eventType.includes("auth")) return Constants.SERVICE_AUTH;
+  if (eventType.includes("remoteconfig")) return Constants.SERVICE_REMOTE_CONFIG;
+  if (eventType.includes("testlab") || eventType.includes("testing"))
+    return Constants.SERVICE_TEST_LAB;
+  return undefined;
+}
diff --git a/src/emulator/functionsEmulator.ts b/src/emulator/functionsEmulator.ts
@@ -62,6 +62,11 @@ import { getCredentialsEnvironment, setEnvVarsForEmulators } from "./env";
 import { runWithVirtualEnv } from "../functions/python";
 import { runtimeIsLanguage, Runtime } from "../deploy/functions/runtimes/supported";
 import { DART_ENTRY_POINT } from "../deploy/functions/runtimes/dart";
+import {
+  isDartEndpoint,
+  classifyEndpoints,
+  groupByTriggerLabel,
+} from "../deploy/functions/runtimes/dart/triggerSupport";
 import { ExtensionsEmulator } from "./extensionsEmulator";
 
 const EVENT_INVOKE_GA4 = "functions_invoke"; // event name GA4 (alphanumertic)
@@ -634,6 +639,10 @@ export class FunctionsEmulator implements EmulatorInstance {
       for (const e of endpoints) {
         e.codebase = emulatableBackend.codebase;
       }
+
+      // Warn about Dart triggers with limited support.
+      this.logDartTriggerSupportWarnings(endpoints);
+
       return emulatedFunctionsFromEndpoints(endpoints);
     }
   }
@@ -867,6 +876,36 @@ export class FunctionsEmulator implements EmulatorInstance {
     }
   }
 
+  /**
+   * Logs warnings for Dart endpoints whose trigger types are not yet
+   * production-ready.  Classification is owned by the shared
+   * `dart/triggerSupport` module.
+   */
+  private logDartTriggerSupportWarnings(endpoints: backend.Endpoint[]): void {
+    const dartEndpoints = endpoints.filter(isDartEndpoint);
+    if (dartEndpoints.length === 0) {
+      return;
+    }
+
+    const { emulatorOnly, experimental } = classifyEndpoints(dartEndpoints);
+
+    groupByTriggerLabel(emulatorOnly).forEach((ids, label) => {
+      this.logger.logLabeled(
+        "WARN",
+        "functions",
+        `Dart ${clc.bold(label)} triggers work in the emulator but cannot be deployed to production yet: ${ids.join(", ")}`,
+      );
+    });
+
+    groupByTriggerLabel(experimental).forEach((ids, label) => {
+      this.logger.logLabeled(
+        "WARN",
+        "functions",
+        `Dart ${clc.bold(label)} triggers are experimental and not yet fully supported: ${ids.join(", ")}`,
+      );
+    });
+  }
+
   // Currently only cleans up eventarc and firealerts triggers
   async removeTriggers(toRemove: string[]) {
     for (const triggerKey of toRemove) {
