Implement unified emulator settings API proposal

FirebaseDatabase/CHANGELOG.md

@@ -1,3 +1,6 @@
+# Unreleased
+- [added] Made emulator connection API consistent between Auth, Database, Firestore, and Functions (#5916).
+
 # v7.0.0
 - [fixed] Disabled a deprecation warning. (#6502)
 

FirebaseDatabase/Sources/Api/FIRDatabase.m

@@ -153,13 +153,15 @@ - (FIRDatabaseReference *)referenceFromURL:(NSString *)databaseUrl {
     }
     FParsedUrl *parsedUrl = [FUtilities parseUrl:databaseUrl];
     [FValidation validateFrom:@"referenceFromURL:" validURL:parsedUrl];
-    if (![parsedUrl.repoInfo.host isEqualToString:_repoInfo.host]) {
-        [NSException
-             raise:@"InvalidDatabaseURL"
-            format:
-                @"Invalid URL (%@) passed to getReference(). URL was expected "
-                 "to match configured Database URL: %@",
-                databaseUrl, [self reference].URL];
+
+    BOOL isInvalidHost =
+        !parsedUrl.repoInfo.isCustomHost &&
+        ![_repoInfo.host isEqualToString:parsedUrl.repoInfo.host];
+    if (isInvalidHost) {
+        [NSException raise:@"InvalidDatabaseURL"
+                    format:@"Invalid URL (%@) passed to getReference(). URL "
+                           @"was expected to match configured Database URL: %@",
+                           databaseUrl, _repoInfo.host];
     }
     return [[FIRDatabaseReference alloc] initWithRepo:self.repo
                                                  path:parsedUrl.path];
@@ -173,6 +175,25 @@ - (void)purgeOutstandingWrites {
     });
 }
 
+- (void)useEmulatorWithHost:(NSString *)host port:(NSInteger)port {
+    if (host.length == 0) {
+        [NSException raise:NSInvalidArgumentException
+                    format:@"Cannot connect to nil or empty host."];
+    }
+    if (self.repo != nil) {
+        [NSException
+             raise:NSInternalInconsistencyException
+            format:@"Cannot connect to emulator after database initialization. "
+                   @"Call useEmulator(host:port:) before creating a database "
+                   @"reference or trying to load data."];
+    }
+    NSString *fullHost =
+        [NSString stringWithFormat:@"%@:%li", host, (long)port];
+    FRepoInfo *emulatorInfo = [[FRepoInfo alloc] initWithInfo:self.repoInfo
+                                                 emulatedHost:fullHost];
+    self->_repoInfo = emulatorInfo;
+}
+
 - (void)goOnline {
     [self ensureRepo];
 

FirebaseDatabase/Sources/Api/FIRDatabaseComponent.m

@@ -115,7 +115,7 @@ - (FIRDatabase *)databaseForApp:(FIRApp *)app URL:(NSString *)url {
                     format:@"The Database URL '%@' cannot be parsed. "
                             "Specify a valid DatabaseURL within FIRApp or from "
                             "your databaseForApp:URL: call.",
-                           databaseUrl];
+                           url];
     } else if (![databaseUrl.path isEqualToString:@""] &&
                ![databaseUrl.path isEqualToString:@"/"]) {
         [NSException

FirebaseDatabase/Sources/Core/FRepoInfo.h

@@ -16,25 +16,38 @@
 
 #import <Foundation/Foundation.h>
 
+NS_ASSUME_NONNULL_BEGIN
+
 @interface FRepoInfo : NSObject <NSCopying>
 
-@property(nonatomic, readonly, strong) NSString *host;
-@property(nonatomic, readonly, strong) NSString *namespace;
-@property(nonatomic, strong) NSString *internalHost;
-@property(nonatomic, readonly) bool secure;
+/// The host that the database should connect to.
+@property(nonatomic, readonly, copy) NSString *host;
+
+@property(nonatomic, readonly, copy) NSString *namespace;
+@property(nonatomic, readwrite, copy) NSString *internalHost;
+@property(nonatomic, readonly, assign) BOOL secure;
+
+/// Returns YES if the host is not a *.firebaseio.com host.
+@property(nonatomic, readonly) BOOL isCustomHost;
 
-- (id)initWithHost:(NSString *)host
-          isSecure:(bool)secure
-     withNamespace:(NSString *)namespace;
+- (instancetype)initWithHost:(NSString *)host
+                    isSecure:(BOOL)secure
+               withNamespace:(NSString *)namespace NS_DESIGNATED_INITIALIZER;
 
-- (NSString *)connectionURLWithLastSessionID:(NSString *)lastSessionID;
+- (instancetype)initWithInfo:(FRepoInfo *)info emulatedHost:(NSString *)host;
+
+- (NSString *)connectionURLWithLastSessionID:(NSString *_Nullable)lastSessionID;
 - (NSString *)connectionURL;
 - (void)clearInternalHostCache;
 - (BOOL)isDemoHost;
 - (BOOL)isCustomHost;
 
-- (id)copyWithZone:(NSZone *)zone;
+- (id)copyWithZone:(NSZone *_Nullable)zone;
 - (NSUInteger)hash;
 - (BOOL)isEqual:(id)anObject;
 
+- (instancetype)init NS_UNAVAILABLE;
+
 @end
+
+NS_ASSUME_NONNULL_END

FirebaseDatabase/Sources/Core/FRepoInfo.m

@@ -25,61 +25,68 @@ @interface FRepoInfo ()
 
 @implementation FRepoInfo
 
-@synthesize namespace;
-@synthesize host;
-@synthesize internalHost;
-@synthesize secure;
-@synthesize domain;
-
-- (id)initWithHost:(NSString *)aHost
-          isSecure:(bool)isSecure
-     withNamespace:(NSString *)aNamespace {
+- (instancetype)init {
+    [NSException
+         raise:@"FIRDatabaseInvalidInitializer"
+        format:@"Invalid initializer invoked. This is probably a bug in RTDB."];
+    abort();
+}
+
+- (instancetype)initWithHost:(NSString *)aHost
+                    isSecure:(BOOL)isSecure
+               withNamespace:(NSString *)aNamespace {
     self = [super init];
     if (self) {
-        host = aHost;
-        domain =
-            [host containsString:@"."]
-                ? [host
-                      substringFromIndex:[host rangeOfString:@"."].location + 1]
-                : host;
-        secure = isSecure;
-        namespace = aNamespace;
+        _host = [aHost copy];
+        _domain =
+            [_host containsString:@"."]
+                ? [_host
+                      substringFromIndex:[_host rangeOfString:@"."].location +
+                                         1]
+                : _host;
+        _secure = isSecure;
+        _namespace = aNamespace;
 
         // Get cached internal host if it exists
         NSString *internalHostKey =
-            [NSString stringWithFormat:@"firebase:host:%@", self.host];
+            [NSString stringWithFormat:@"firebase:host:%@", _host];
         NSString *cachedInternalHost = [[NSUserDefaults standardUserDefaults]
             stringForKey:internalHostKey];
         if (cachedInternalHost != nil) {
-            internalHost = cachedInternalHost;
+            _internalHost = cachedInternalHost;
         } else {
-            internalHost = self.host;
+            _internalHost = [_host copy];
         }
     }
     return self;
 }
 
+- (instancetype)initWithInfo:(FRepoInfo *)info emulatedHost:(NSString *)host {
+    self = [self initWithHost:host isSecure:NO withNamespace:info.namespace];
+    return self;
+}
+
 - (NSString *)description {
     // The namespace is encoded in the hostname, so we can just return this.
     return [NSString
-        stringWithFormat:@"http%@://%@", (self.secure ? @"s" : @""), self.host];
+        stringWithFormat:@"http%@://%@", (_secure ? @"s" : @""), _host];
 }
 
 - (void)setInternalHost:(NSString *)newHost {
-    if (![internalHost isEqualToString:newHost]) {
-        internalHost = newHost;
+    if (![self.internalHost isEqualToString:newHost]) {
+        self.internalHost = [newHost copy];
 
         // Cache the internal host so we don't need to redirect later on
         NSString *internalHostKey =
             [NSString stringWithFormat:@"firebase:host:%@", self.host];
         NSUserDefaults *cache = [NSUserDefaults standardUserDefaults];
-        [cache setObject:internalHost forKey:internalHostKey];
+        [cache setObject:_internalHost forKey:internalHostKey];
         [cache synchronize];
     }
 }
 
 - (void)clearInternalHostCache {
-    internalHost = self.host;
+    self.internalHost = self.host;
 
     // Remove the cached entry
     NSString *internalHostKey =
@@ -120,25 +127,25 @@ - (NSString *)connectionURLWithLastSessionID:(NSString *)lastSessionID {
     return url;
 }
 
-- (id)copyWithZone:(NSZone *)zone;
-{
+- (id)copyWithZone:(NSZone *)zone {
     return self; // Immutable
 }
 
 - (NSUInteger)hash {
-    NSUInteger result = host.hash;
-    result = 31 * result + (secure ? 1 : 0);
-    result = 31 * result + namespace.hash;
-    result = 31 * result + host.hash;
+    NSUInteger result = _host.hash;
+    result = 31 * result + (_secure ? 1 : 0);
+    result = 31 * result + _namespace.hash;
+    result = 31 * result + _host.hash;
     return result;
 }
 
 - (BOOL)isEqual:(id)anObject {
-    if (![anObject isKindOfClass:[FRepoInfo class]])
+    if (![anObject isKindOfClass:[FRepoInfo class]]) {
         return NO;
+    }
     FRepoInfo *other = (FRepoInfo *)anObject;
-    return secure == other.secure && [host isEqualToString:other.host] &&
-           [namespace isEqualToString:other.namespace];
+    return _secure == other.secure && [_host isEqualToString:other.host] &&
+           [_namespace isEqualToString:other.namespace];
 }
 
 @end

FirebaseDatabase/Sources/Public/FirebaseDatabase/FIRDatabase.h

@@ -31,9 +31,7 @@ NS_SWIFT_NAME(Database)
 
 /**
  * The NSObject initializer that has been marked as unavailable. Use the
- * `database` method instead
- *
- * @return An instancetype instance
+ * `database` class method instead.
  */
 - (instancetype)init
     __attribute__((unavailable("use the database method instead")));
@@ -93,7 +91,7 @@ NS_SWIFT_NAME(Database)
 /**
  * Gets a FIRDatabaseReference for the provided URL.  The URL must be a URL to a
  * path within this Firebase Database.  To create a FIRDatabaseReference to a
- * different database, create a FIRApp} with a FIROptions object configured with
+ * different database, create a FIRApp with a FIROptions object configured with
  * the appropriate database URL.
  *
  * @param databaseUrl A URL to a path within your database.
@@ -177,6 +175,12 @@ NS_SWIFT_NAME(Database)
 /** Retrieve the Firebase Database SDK version. */
 + (NSString *)sdkVersion;
 
+/**
+ * Configures the database to use an emulated backend instead of the default
+ * remote backend.
+ */
+- (void)useEmulatorWithHost:(NSString *)host port:(NSInteger)port;
+
 @end
 
 NS_ASSUME_NONNULL_END

FirebaseDatabase/Tests/Integration/FIRDatabaseTests.m

@@ -37,10 +37,8 @@ @interface FIRDatabaseTests : FTestBase
 @implementation FIRDatabaseTests
 
 - (void)testFIRDatabaseForNilApp {
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wnonnull"
-  XCTAssertThrowsSpecificNamed([FIRDatabase databaseForApp:nil], NSException, @"InvalidFIRApp");
-#pragma clang diagnostic pop
+  XCTAssertThrowsSpecificNamed([FIRDatabase databaseForApp:(FIRApp * _Nonnull) nil], NSException,
+                               @"InvalidFIRApp");
 }
 
 - (void)testDatabaseForApp {
@@ -94,10 +92,7 @@ - (void)testDifferentInstanceForAppWithURL {
 - (void)testDatabaseForAppWithInvalidCustomURLs {
   id app = [[FIRFakeApp alloc] initWithName:@"testDatabaseForAppWithInvalidCustomURLs"
                                         URL:kFirebaseTestAltNamespace];
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wnonnull"
-  XCTAssertThrows([FIRDatabase databaseForApp:app URL:nil]);
-#pragma clang diagnostic pop
+  XCTAssertThrows([FIRDatabase databaseForApp:app URL:(NSString * _Nonnull) nil]);
   XCTAssertThrows([FIRDatabase databaseForApp:app URL:@"not-a-url"]);
   XCTAssertThrows([FIRDatabase databaseForApp:app URL:@"http://x.fblocal.com:9000/paths/are/bad"]);
 }
@@ -469,6 +464,65 @@ - (void)testCallbackQueue {
   [database goOffline];
 }
 
+- (void)testSetEmulatorSettingsCreatesEmulatedReferences {
+  id app = [[FIRFakeApp alloc] initWithName:@"testSetEmulatorSettingsCreatesEmulatedReferences"
+                                        URL:self.databaseURL];
+  FIRDatabase *database = [FIRDatabase databaseForApp:app];
+
+  [database useEmulatorWithHost:@"localhost" port:1111];
+  NSString *concatenatedHost = @"localhost:1111";
+
+  FIRDatabaseReference *reference = [database reference];
+
+  NSString *referenceURLString = reference.URL;
+
+  XCTAssert([referenceURLString containsString:concatenatedHost]);
+}
+
+- (void)testSetEmulatorSettingsThrowsAfterRepoInit {
+  id app = [[FIRFakeApp alloc] initWithName:@"testSetEmulatorSettingsThrowsAfterRepoInit"
+                                        URL:self.databaseURL];
+  FIRDatabase *database = [FIRDatabase databaseForApp:app];
+
+  [database reference];  // initialize database repo
+
+  // Emulator can't be set after initialization of the database's repo.
+  XCTAssertThrows([database useEmulatorWithHost:@"a" port:1]);
+}
+
+- (void)testEmulatedDatabaseValidatesOnlyNonCustomURLs {
+  // Set a non-custom databaseURL
+  NSString *databaseURL = @"https://test.example.com";
+  id app = [[FIRFakeApp alloc] initWithName:@"testEmulatedDatabaseValidatesNonCustomURLs0"
+                                        URL:databaseURL];
+  FIRDatabase *database = [FIRDatabase databaseForApp:app];
+
+  // Reference should be retrievable without an exception being raised
+  NSString *referenceURLString = [databaseURL stringByAppendingString:@"/path"];
+  FIRDatabaseReference *reference = [database referenceFromURL:referenceURLString];
+  XCTAssertNotNil(reference);
+
+  app = [[FIRFakeApp alloc] initWithName:@"testEmulatedDatabaseValidatesNonCustomURLs1"
+                                     URL:databaseURL];
+  database = [FIRDatabase databaseForApp:app];
+  [database useEmulatorWithHost:@"localhost" port:1111];
+
+  // Expect production url creates a valid (emulated) reference.
+  reference = [database referenceFromURL:referenceURLString];
+  XCTAssertNotNil(reference);
+  XCTAssert([reference.URL containsString:@"localhost:1111"]);
+
+  // Test emulated url
+  referenceURLString = @"http://localhost:1111/path";
+  reference = [database referenceFromURL:referenceURLString];
+  XCTAssertNotNil(reference);
+  XCTAssert([reference.URL containsString:@"localhost:1111"]);
+
+  // Test non-custom url with different host throws exception
+  referenceURLString = @"https://test.firebaseio.com/path";
+  XCTAssertThrows([database referenceFromURL:referenceURLString]);
+}
+
 - (FIRDatabase *)defaultDatabase {
   return [self databaseForURL:self.databaseURL];
 }

Firestore/CHANGELOG.md

@@ -1,4 +1,5 @@
 # Unreleased
+- [added] Made emulator connection API consistent between Auth, Database, Firestore, and Functions (#5916).
 
 # v7.0.0
 - [changed] **Breaking change:** Removed the `areTimestampsInSnapshotsEnabled`

Firestore/Example/Tests/API/FIRFirestoreTests.mm

@@ -15,6 +15,7 @@
  */
 
 #import <FirebaseFirestore/FIRFirestore.h>
+#import <FirebaseFirestore/FIRFirestoreSettings.h>
 
 #import <XCTest/XCTest.h>
 
@@ -63,4 +64,16 @@ - (void)testDeleteApp {
                                }];
 }
 
+- (void)testSetEmulatorSettingsSetsHost {
+  // Ensure the app is set appropriately.
+  FIRApp *app = testutil::AppForUnitTesting();
+
+  FIRFirestore *firestore = [FIRFirestore firestoreForApp:app];
+
+  [firestore useEmulatorWithHost:@"localhost" port:1000];
+
+  NSString *host = firestore.settings.host;
+  XCTAssertEqualObjects(host, @"localhost:1000");
+}
+
 @end