Add Emulator Overlay

.changeset/three-singers-wonder.md

@@ -0,0 +1,10 @@
+---
+"@firebase/auth": patch
+"@firebase/firestore": patch
+"@firebase/util": patch
+"@firebase/database": patch
+"@firebase/storage": patch
+"@firebase/functions": patch
+---
+
+Add Emulator Overlay

common/api-review/util.api.md

@@ -482,6 +482,9 @@ export interface Subscribe<T> {
 // @public (undocumented)
 export type Unsubscribe = () => void;
 
+// @public
+export function updateEmulatorBanner(name: string, isRunningEmulator: boolean): void;
+
 // Warning: (ae-missing-release-tag) "validateArgCount" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public

packages/auth/src/api/index.ts

@@ -198,7 +198,8 @@ export async function _performFetchWithErrorHandling<V>(
   customErrorMap: Partial<ServerErrorMap<ServerError>>,
   fetchFn: () => Promise<Response>
 ): Promise<V> {
-  (auth as AuthInternal)._canInitEmulator = false;
+  const authInternal = auth as AuthInternal;
+  authInternal._canInitEmulator = false;
   const errorMap = { ...SERVER_ERROR_MAP, ...customErrorMap };
   try {
     const networkTimeout = new NetworkTimeout<Response>(auth);

packages/auth/src/core/auth/emulator.ts

@@ -18,7 +18,12 @@ import { Auth } from '../../model/public_types';
 import { AuthErrorCode } from '../errors';
 import { _assert } from '../util/assert';
 import { _castAuth } from './auth_impl';
-import { deepEqual, isCloudWorkstation, pingServer } from '@firebase/util';
+import {
+  deepEqual,
+  isCloudWorkstation,
+  pingServer,
+  updateEmulatorBanner
+} from '@firebase/util';
 
 /**
  * Changes the {@link Auth} instance to communicate with the Firebase Auth Emulator, instead of production
@@ -98,7 +103,11 @@ export function connectAuthEmulator(
   authInternal.settings.appVerificationDisabledForTesting = true;
 
   if (!disableWarnings) {
-    emitEmulatorWarning();
+    if (isCloudWorkstation(host)) {
+      updateEmulatorBanner('Auth', true);
+    } else {
+      emitEmulatorWarning();
+    }
   }
 
   // Workaround to get cookies in Firebase Studio

packages/auth/src/platform_browser/index.ts

@@ -30,7 +30,11 @@ import { browserSessionPersistence } from './persistence/session_storage';
 import { indexedDBLocalPersistence } from './persistence/indexed_db';
 import { browserPopupRedirectResolver } from './popup_redirect';
 import { Auth, User } from '../model/public_types';
-import { getDefaultEmulatorHost, getExperimentalSetting } from '@firebase/util';
+import {
+  getDefaultEmulatorHost,
+  getExperimentalSetting,
+  updateEmulatorBanner
+} from '@firebase/util';
 import { _setExternalJSProvider } from './load_js';
 import { _createError } from '../core/util/assert';
 import { AuthErrorCode } from '../core/errors';
@@ -107,6 +111,8 @@ export function getAuth(app: FirebaseApp = getApp()): Auth {
     }
   }
 
+  updateEmulatorBanner('Auth', false);
+
   const authEmulatorHost = getDefaultEmulatorHost('auth');
   if (authEmulatorHost) {
     connectAuthEmulator(auth, `http://${authEmulatorHost}`);

packages/database/src/api/Database.ts

@@ -31,7 +31,8 @@ import {
   EmulatorMockTokenOptions,
   getDefaultEmulatorHostnameAndPort,
   isCloudWorkstation,
-  pingServer
+  pingServer,
+  updateEmulatorBanner
 } from '@firebase/util';
 
 import { AppCheckTokenProvider } from '../core/AppCheckTokenProvider';
@@ -257,6 +258,10 @@ export class Database implements _FirebaseService {
         this.app.options['databaseAuthVariableOverride']
       );
       this._instanceStarted = true;
+      updateEmulatorBanner(
+        'Database',
+        this._repo.repoInfo_.emulatorOptions !== null
+      );
     }
     return this._repoInternal;
   }
@@ -328,6 +333,7 @@ export function getDatabase(
     identifier: url
   }) as Database;
   if (!db._instanceStarted) {
+    updateEmulatorBanner('Database', false);
     const emulator = getDefaultEmulatorHostnameAndPort('database');
     if (emulator) {
       connectDatabaseEmulator(db, ...emulator);
@@ -393,6 +399,7 @@ export function connectDatabaseEmulator(
   // Workaround to get cookies in Firebase Studio
   if (isCloudWorkstation(host)) {
     void pingServer(host);
+    updateEmulatorBanner('Database', true);
   }
 
   // Modify the repo to apply emulator settings

packages/firestore/src/lite-api/database.ts

@@ -28,6 +28,7 @@ import {
   EmulatorMockTokenOptions,
   getDefaultEmulatorHostnameAndPort,
   isCloudWorkstation,
+  updateEmulatorBanner,
   pingServer
 } from '@firebase/util';
 
@@ -142,6 +143,7 @@ export class Firestore implements FirestoreService {
 
   _freezeSettings(): FirestoreSettingsImpl {
     this._settingsFrozen = true;
+    updateEmulatorBanner('Firestore', this._settings.isUsingEmulator);
     return this._settings;
   }
 
@@ -334,9 +336,7 @@ export function connectFirestoreEmulator(
     emulatorOptions: firestore._getEmulatorOptions()
   };
   const newHostSetting = `${host}:${port}`;
-  if (useSsl) {
-    void pingServer(`https://${newHostSetting}`);
-  }
+
   if (settings.host !== DEFAULT_HOST && settings.host !== newHostSetting) {
     logWarn(
       'Host has been set in both settings() and connectFirestoreEmulator(), emulator host ' +
@@ -357,6 +357,11 @@ export function connectFirestoreEmulator(
 
   firestore._setSettings(newConfig);
 
+  if (useSsl) {
+    void pingServer(`https://${newHostSetting}`);
+    updateEmulatorBanner('Firestore', true);
+  }
+
   if (options.mockUserToken) {
     let token: string;
     let user: User;

packages/functions/src/api.ts

@@ -29,7 +29,8 @@ import {
 } from './service';
 import {
   getModularInstance,
-  getDefaultEmulatorHostnameAndPort
+  getDefaultEmulatorHostnameAndPort,
+  updateEmulatorBanner
 } from '@firebase/util';
 
 export { FunctionsError } from './error';
@@ -47,6 +48,7 @@ export function getFunctions(
   app: FirebaseApp = getApp(),
   regionOrCustomDomain: string = DEFAULT_REGION
 ): Functions {
+  updateEmulatorBanner('Functions', false);
   // Dependencies
   const functionsProvider: Provider<'functions'> = _getProvider(
     getModularInstance(app),

packages/functions/src/service.ts

@@ -30,7 +30,11 @@ import { Provider } from '@firebase/component';
 import { FirebaseAuthInternalName } from '@firebase/auth-interop-types';
 import { MessagingInternalComponentName } from '@firebase/messaging-interop-types';
 import { AppCheckInternalComponentName } from '@firebase/app-check-interop-types';
-import { isCloudWorkstation, pingServer } from '@firebase/util';
+import {
+  isCloudWorkstation,
+  pingServer,
+  updateEmulatorBanner
+} from '@firebase/util';
 
 export const DEFAULT_REGION = 'us-central1';
 
@@ -182,6 +186,7 @@ export function connectFunctionsEmulator(
   // Workaround to get cookies in Firebase Studio
   if (useSsl) {
     void pingServer(functionsInstance.emulatorOrigin);
+    updateEmulatorBanner('Functions', true);
   }
 }
 
@@ -195,6 +200,7 @@ export function httpsCallable<RequestData, ResponseData, StreamData = unknown>(
   name: string,
   options?: HttpsCallableOptions
 ): HttpsCallable<RequestData, ResponseData, StreamData> {
+  updateEmulatorBanner('Functions', functionsInstance.emulatorOrigin !== null);
   const callable = (
     data?: RequestData | null
   ): Promise<HttpsCallableResult> => {
@@ -225,6 +231,7 @@ export function httpsCallableFromURL<
   url: string,
   options?: HttpsCallableOptions
 ): HttpsCallable<RequestData, ResponseData, StreamData> {
+  updateEmulatorBanner('Functions', functionsInstance.emulatorOrigin !== null);
   const callable = (
     data?: RequestData | null
   ): Promise<HttpsCallableResult> => {

packages/storage/src/api.ts

@@ -53,7 +53,8 @@ import { STORAGE_TYPE } from './constants';
 import {
   EmulatorMockTokenOptions,
   getModularInstance,
-  getDefaultEmulatorHostnameAndPort
+  getDefaultEmulatorHostnameAndPort,
+  updateEmulatorBanner
 } from '@firebase/util';
 import { StringFormat } from './implementation/string';
 
@@ -332,6 +333,7 @@ export function getStorage(
   bucketUrl?: string
 ): FirebaseStorage {
   app = getModularInstance(app);
+  updateEmulatorBanner('Storage', false);
   const storageProvider: Provider<'storage'> = _getProvider(app, STORAGE_TYPE);
   const storageInstance = storageProvider.getImmediate({
     identifier: bucketUrl

packages/storage/src/service.ts

@@ -46,7 +46,8 @@ import {
   createMockUserToken,
   EmulatorMockTokenOptions,
   isCloudWorkstation,
-  pingServer
+  pingServer,
+  updateEmulatorBanner
 } from '@firebase/util';
 import { Connection, ConnectionType } from './implementation/connection';
 
@@ -150,6 +151,7 @@ export function connectStorageEmulator(
   // Workaround to get cookies in Firebase Studio
   if (useSsl) {
     void pingServer(`https://${storage.host}`);
+    updateEmulatorBanner('Storage', true);
   }
   storage._isUsingEmulator = true;
   storage._protocol = useSsl ? 'https' : 'http';
@@ -324,6 +326,7 @@ export class FirebaseStorageImpl implements FirebaseStorage {
     appCheckToken: string | null,
     retry = true
   ): Request<O> {
+    updateEmulatorBanner('Service', this._isUsingEmulator);
     if (!this._deleted) {
       const request = makeRequest(
         requestInfo,