fix(emulator): add notice on localhost URL remapping for android

For developer experience, we remap localhost / 127.0.0.1 on android to the
canonical android emulator IP address for the host machine. This is best most
of the time but is quite unexpected if you run on a real device and try to do
adb reverse port mapping for the emulator port and use localhost, only to find
that you can't connect to the emulator because of this remapping

This PR adds a note to the docs and a console.log so developers are aware of
the behavior

Fixes #4810

packages/auth/__tests__/auth.test.ts

@@ -27,11 +27,11 @@ describe('Auth', function () {
     it('useEmulator requires a well-formed url', function () {
       // No http://
       expect(() => auth().useEmulator('localhost:9099')).toThrow(
-        'firebase.auth().useEmulator() unable to parse host and port from url',
+        'firebase.auth().useEmulator() takes a non-empty string URL',
       );
       // No port
       expect(() => auth().useEmulator('http://localhost')).toThrow(
-        'firebase.auth().useEmulator() unable to parse host and port from url',
+        'firebase.auth().useEmulator() unable to parse host and port from URL',
       );
     });
 

packages/auth/lib/index.d.ts

@@ -1646,6 +1646,11 @@ export namespace FirebaseAuthTypes {
      * This must be called synchronously immediately following the first call to firebase.auth().
      * Do not use with production credentials as emulator traffic is not encrypted.
      *
+     * Note: on android, hosts 'localhost' and '127.0.0.1' are automatically remapped to '10.0.2.2' (the
+     * "host" computer IP address for android emulators) to make the standard development experience easy.
+     * If you want to use the emulator on a real android device, you will need to specify the actual host
+     * computer IP address.
+     *
      * @param url: emulator URL, must have host and port (eg, 'http://localhost:9099')
      */
     useEmulator(url: string): void;

packages/auth/lib/index.js

@@ -15,7 +15,13 @@
  *
  */
 
-import { isAndroid, isBoolean, isString, isNull } from '@react-native-firebase/app/lib/common';
+import {
+  isAndroid,
+  isBoolean,
+  isString,
+  isNull,
+  isValidUrl,
+} from '@react-native-firebase/app/lib/common';
 import {
   createModuleNamespace,
   FirebaseModule,
@@ -336,25 +342,33 @@ class FirebaseAuthModule extends FirebaseModule {
   }
 
   useEmulator(url) {
-    if (!url || !isString(url) || url === '') {
-      throw new Error('firebase.auth().useEmulator() takes a non-empty string');
+    if (!url || !isString(url) || !isValidUrl(url)) {
+      throw new Error('firebase.auth().useEmulator() takes a non-empty string URL');
     }
 
     let _url = url;
     if (isAndroid && _url) {
       if (_url.startsWith('http://localhost')) {
         _url = _url.replace('http://localhost', 'http://10.0.2.2');
+        // eslint-disable-next-line no-console
+        console.log(
+          'Mapping auth host "localhost" to "10.0.2.2" for android emulators. Use real IP on real devices.',
+        );
       }
       if (_url.startsWith('http://127.0.0.1')) {
         _url = _url.replace('http://127.0.0.1', 'http://10.0.2.2');
+        // eslint-disable-next-line no-console
+        console.log(
+          'Mapping auth host "127.0.0.1" to "10.0.2.2" for android emulators. Use real IP on real devices.',
+        );
       }
     }
 
     // Native calls take the host and port split out
     const hostPortRegex = /^http:\/\/([\w\d.]+):(\d+)$/;
     const urlMatches = _url.match(hostPortRegex);
     if (!urlMatches) {
-      throw new Error('firebase.auth().useEmulator() unable to parse host and port from url');
+      throw new Error('firebase.auth().useEmulator() unable to parse host and port from URL');
     }
     const host = urlMatches[1];
     const port = parseInt(urlMatches[2], 10);

packages/firestore/lib/index.d.ts

@@ -1407,6 +1407,11 @@ export namespace FirebaseFirestoreTypes {
 
     /**
      * The hostname to connect to.
+     *
+     * Note: on android, hosts 'localhost' and '127.0.0.1' are automatically remapped to '10.0.2.2' (the
+     * "host" computer IP address for android emulators) to make the standard development experience easy.
+     * If you want to use the emulator on a real android device, you will need to specify the actual host
+     * computer IP address.
      */
     host: string;
 

packages/firestore/lib/index.js

@@ -227,9 +227,17 @@ class FirebaseFirestoreModule extends FirebaseModule {
       if (isAndroid) {
         if (settings.host.startsWith('localhost')) {
           settings.host = settings.host.replace('localhost', '10.0.2.2');
+          // eslint-disable-next-line no-console
+          console.log(
+            'Mapping firestore host "localhost" to "10.0.2.2" for android emulators. Use real IP on real devices.',
+          );
         }
         if (settings.host.startsWith('127.0.0.1')) {
           settings.host = settings.host.replace('127.0.0.1', '10.0.2.2');
+          // eslint-disable-next-line no-console
+          console.log(
+            'Mapping firestore host "127.0.0.1" to "10.0.2.2" for android emulators. Use real IP on real devices.',
+          );
         }
       }
     }

packages/functions/lib/index.d.ts

@@ -339,21 +339,24 @@ export namespace FirebaseFunctionsTypes {
     httpsCallable(name: string, options?: HttpsCallableOptions): HttpsCallable;
 
     /**
-     * Changes this instance to point to a Cloud Functions emulator running
-     * locally.
+     * Changes this instance to point to a Cloud Functions emulator running locally.
      *
      * See https://firebase.google.com/docs/functions/local-emulator
      *
      * #### Example
      *
      * ```js
      * if (__DEV__) {
-     *   firebase.functions().useFunctionsEmulator('http://10.0.0.8:1337');
+     *   firebase.functions().useFunctionsEmulator('http://localhost:5001');
      * }
      * ```
      *
-     * @param origin The origin string of the local emulator started via firebase tools
-     * "http://10.0.0.8:1337".
+     * Note: on android, hosts 'localhost' and '127.0.0.1' are automatically remapped to '10.0.2.2' (the
+     * "host" computer IP address for android emulators) to make the standard development experience easy.
+     * If you want to use the emulator on a real android device, you will need to specify the actual host
+     * computer IP address.
+     *
+     * @param origin url of the local emulator started via firebase tools "http://localhost:5001"
      */
     useFunctionsEmulator(origin: string): void;
   }

packages/functions/lib/index.js

@@ -96,9 +96,17 @@ class FirebaseFunctionsModule extends FirebaseModule {
     if (isAndroid && _origin) {
       if (_origin.startsWith('http://localhost')) {
         _origin = _origin.replace('http://localhost', 'http://10.0.2.2');
+        // eslint-disable-next-line no-console
+        console.log(
+          'Mapping functions host "localhost" to "10.0.2.2" for android emulators. Use real IP on real devices.',
+        );
       }
       if (_origin.startsWith('http://127.0.0.1')) {
         _origin = _origin.replace('http://127.0.0.1', 'http://10.0.2.2');
+        // eslint-disable-next-line no-console
+        console.log(
+          'Mapping functions host "127.0.0.1" to "10.0.2.2" for android emulators. Use real IP on real devices.',
+        );
       }
     }
     this._useFunctionsEmulatorOrigin = _origin || null;