Add GetOptions for controlling offline get behaviour (firebase#655)

Add option to allow the user to control where DocumentReference.getDocument() and CollectionReference.getDocuments() fetches from. By default, it fetches from the server (if possible) and falls back to the local cache. It's now possible to alternatively fetch from the local cache only, or to fetch from the server only (though in the server only case, latency compensation is still enabled).

Author: rsgowman

Firestore/CHANGELOG.md

@@ -24,6 +24,10 @@
   `FIRServerTimestampBehavior` on `DocumentSnapshot`. Instead of calling
   `data(SnapshotOptions.serverTimestampBehavior(.estimate))` call
   `data(serverTimestampBehavior: .estimate)`. Changed `get` similarly.
+- [changed] Added ability to control whether DocumentReference.getDocument() and
+  Query.getDocuments() should fetch from server only, cache only, or attempt
+  server and fall back to the cache (which was the only option previously, and
+  is now the default.)
 
 # v0.11.0
 - [fixed] Fixed a regression in the Firebase iOS SDK release 4.11.0 that could

Firestore/Example/Firestore.xcodeproj/project.pbxproj

@@ -131,6 +131,7 @@
 		6003F5B1195388D20070C39A /* Foundation.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 6003F58D195388D20070C39A /* Foundation.framework */; };
 		6003F5B2195388D20070C39A /* UIKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 6003F591195388D20070C39A /* UIKit.framework */; };
 		6003F5BA195388D20070C39A /* InfoPlist.strings in Resources */ = {isa = PBXBuildFile; fileRef = 6003F5B8195388D20070C39A /* InfoPlist.strings */; };
+		6161B5032047140C00A99DBB /* FIRFirestoreSourceTests.mm in Sources */ = {isa = PBXBuildFile; fileRef = 6161B5012047140400A99DBB /* FIRFirestoreSourceTests.mm */; };
 		6ED54761B845349D43DB6B78 /* Pods_Firestore_Example.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 75A6FE51C1A02DF38F62FAAD /* Pods_Firestore_Example.framework */; };
 		71719F9F1E33DC2100824A3D /* LaunchScreen.storyboard in Resources */ = {isa = PBXBuildFile; fileRef = 71719F9D1E33DC2100824A3D /* LaunchScreen.storyboard */; };
 		7346E61D20325C6900FD6CEF /* FSTDispatchQueueTests.mm in Sources */ = {isa = PBXBuildFile; fileRef = 7346E61C20325C6900FD6CEF /* FSTDispatchQueueTests.mm */; };
@@ -356,6 +357,7 @@
 		6003F5AF195388D20070C39A /* XCTest.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = XCTest.framework; path = Library/Frameworks/XCTest.framework; sourceTree = DEVELOPER_DIR; };
 		6003F5B7195388D20070C39A /* Tests-Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; path = "Tests-Info.plist"; sourceTree = "<group>"; };
 		6003F5B9195388D20070C39A /* en */ = {isa = PBXFileReference; lastKnownFileType = text.plist.strings; name = en; path = en.lproj/InfoPlist.strings; sourceTree = "<group>"; };
+		6161B5012047140400A99DBB /* FIRFirestoreSourceTests.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; path = FIRFirestoreSourceTests.mm; sourceTree = "<group>"; };
 		69F6A10DBD6187489481CD76 /* Pods_Firestore_Tests.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = Pods_Firestore_Tests.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		71719F9E1E33DC2100824A3D /* Base */ = {isa = PBXFileReference; lastKnownFileType = file.storyboard; name = Base; path = Base.lproj/LaunchScreen.storyboard; sourceTree = "<group>"; };
 		7346E61C20325C6900FD6CEF /* FSTDispatchQueueTests.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; path = FSTDispatchQueueTests.mm; sourceTree = "<group>"; };
@@ -885,6 +887,7 @@
 			isa = PBXGroup;
 			children = (
 				73866A9F2082B069009BB4FF /* FIRArrayTransformTests.mm */,
+				6161B5012047140400A99DBB /* FIRFirestoreSourceTests.mm */,
 				5492E070202154D600B64F25 /* FIRCursorTests.mm */,
 				5492E06C202154D500B64F25 /* FIRDatabaseTests.mm */,
 				5492E06A202154D500B64F25 /* FIRFieldsTests.mm */,
@@ -1559,6 +1562,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				73866AA12082B0A5009BB4FF /* FIRArrayTransformTests.mm in Sources */,
+				6161B5032047140C00A99DBB /* FIRFirestoreSourceTests.mm in Sources */,
 				5492E076202154D600B64F25 /* FIRValidationTests.mm in Sources */,
 				5492E072202154D600B64F25 /* FIRQueryTests.mm in Sources */,
 				5491BC731FB44593008B3588 /* FSTIntegrationTestCase.mm in Sources */,

Firestore/Example/SwiftBuildTest/main.swift

@@ -32,8 +32,10 @@ func main() {
   addDocument(to: collectionRef)
 
   readDocument(at: documentRef)
+  readDocumentWithSource(at: documentRef)
 
   readDocuments(matching: query)
+  readDocumentsWithSource(matching: query)
 
   listenToDocument(at: documentRef)
 
@@ -230,6 +232,15 @@ func readDocument(at docRef: DocumentReference) {
   }
 }
 
+func readDocumentWithSource(at docRef: DocumentReference) {
+  docRef.getDocument(source: FirestoreSource.default) { document, error in
+  }
+  docRef.getDocument(source: .server) { document, error in
+  }
+  docRef.getDocument(source: FirestoreSource.cache) { document, error in
+  }
+}
+
 func readDocuments(matching query: Query) {
   query.getDocuments { querySnapshot, error in
     // TODO(mikelehen): Figure out how to make "for..in" syntax work
@@ -240,6 +251,15 @@ func readDocuments(matching query: Query) {
   }
 }
 
+func readDocumentsWithSource(matching query: Query) {
+  query.getDocuments(source: FirestoreSource.default) { querySnapshot, error in
+  }
+  query.getDocuments(source: .server) { querySnapshot, error in
+  }
+  query.getDocuments(source: FirestoreSource.cache) { querySnapshot, error in
+  }
+}
+
 func listenToDocument(at docRef: DocumentReference) {
   let listener = docRef.addSnapshotListener { document, error in
     if let error = error {