New offline features (#185)

* [offline] Support bootstrapping mirrored indices with local data

This feature allows initializing a local mirror from local data (typically, prepackaged resources) without having to wait for the first sync.

* [offline] Expose `hasOfflineData()` at the index level

* [offline] Add a `buildOffline(…)` method on `MirroredIndex`

This unconditionally creates or replaces the local mirror with the specified data, regardless of whether local data already exists or not for the index. (In contrast to `boostrap(…)`, which only does so if no data exists.)

* [offline] Support offline fallback for getting objects (WIP)

The `Index.getObjects(…)` methods are overridden by `MirroredIndex`, providing the same offline fallback mechanism as search.

NOTE: Only supported for `getObjects` so far; getting a single object will follow later.

* [offline] Fix race condition in instantiation of local index

It turns out that [lazy variables are not thread-safe](http://stackoverflow.com/a/29761777). We therefore have to synchronize initialization manually.

* [offline] Refactor recent features

- Remove `bootstrap(…)`: it is superseded by `buildOffline(…)`
- Use a dynamic property instead of a function for `hasOfflineData`
- Rename notifications from `bootstrapDid*` to `buildDid*`
- Update reference documentation

* [offline] Leverage `buildOffline` inside sync

This allows to send build notifications also for a sync.

* [offline] Add unit test for `MirroredIndex.buildOffline(…)`

* Fix compilation warnings

The `syncErrorKey` notification key is now deprecated in favor of `errorKey`.

* [offline] Add utilities to tag content origin as local or remote

* [offline] Add offline support to `MirroredIndex.getObject(…)`

* [offline] Fix ambiguous overload

* [refact] Use utilities to tag content origin

* Ooops

* [offline] Add test cases for `MirroredIndex.getObject[s]`

* [offline] Fix compilation of unit tests

Xcode or Cocoapods (not sure which one) has trouble dealing with two distinct modules both named “AlgoliaSearch”. We therefore rename the offline flavor to “AlgoliaSearchOffline”.

NOTE: This is **not** what we want clients of the library to be using, but since the module name is overridden by Cocoapods, and the scheme is not shared with Carthage, this should impact only the unit tests, not the users of the module.

* [refact] Add completion handler to `MirroredIndex.buildOffline(…)`

* [refact] Use dynamic property instead of function for `OfflineIndex.hasOfflineData`

* [offline] Add manual build capability to `OfflineIndex`

* Fix some inconsistencies

* [doc][offline] Update reference documentation

[ci skip]

* [doc][offline] Fix generation of reference documentation

Changing the module name had unintended side effects on the documentation. This should fix it.

* [refact][offline] Return an operation from manual build methods

* [offline] Assert that mirroring is on before testing local data

* [offline][doc] Update reference documentation

[ci skip]

Author: Clément Le Provost

AlgoliaSearch.xcodeproj/project.pbxproj

@@ -139,14 +139,16 @@
 		BCD57D231D89947500C5DE68 /* DisjunctiveFaceting.swift in Sources */ = {isa = PBXBuildFile; fileRef = BCD57D1E1D89947500C5DE68 /* DisjunctiveFaceting.swift */; };
 		BCD57D261D89970D00C5DE68 /* MultipleQueryEmulator.swift in Sources */ = {isa = PBXBuildFile; fileRef = BCD57D241D89970D00C5DE68 /* MultipleQueryEmulator.swift */; };
 		BCD57D271D89970D00C5DE68 /* OfflineIndex.swift in Sources */ = {isa = PBXBuildFile; fileRef = BCD57D251D89970D00C5DE68 /* OfflineIndex.swift */; };
-		BCD57D311D89B12E00C5DE68 /* AlgoliaSearch.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = BC4BD2931D54E48900170ECC /* AlgoliaSearch.framework */; };
+		BCD57D311D89B12E00C5DE68 /* AlgoliaSearchOffline.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = BC4BD2931D54E48900170ECC /* AlgoliaSearchOffline.framework */; };
 		BCD57D3C1D89B1EA00C5DE68 /* OfflineClientTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = BCD57D391D89B1EA00C5DE68 /* OfflineClientTests.swift */; };
 		BCD57D3D1D89B1EA00C5DE68 /* OfflineIndexTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = BCD57D3A1D89B1EA00C5DE68 /* OfflineIndexTests.swift */; };
 		BCD57D3E1D89B1EA00C5DE68 /* OfflineTestCase.swift in Sources */ = {isa = PBXBuildFile; fileRef = BCD57D3B1D89B1EA00C5DE68 /* OfflineTestCase.swift */; };
 		BCDA73781CA546800082B197 /* NetworkTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = BCDA73771CA546800082B197 /* NetworkTests.swift */; };
 		BCDA73791CA546800082B197 /* NetworkTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = BCDA73771CA546800082B197 /* NetworkTests.swift */; };
 		BCDA737E1CA555070082B197 /* MockURLSession.swift in Sources */ = {isa = PBXBuildFile; fileRef = BCDA737D1CA555070082B197 /* MockURLSession.swift */; };
 		BCDA737F1CA555070082B197 /* MockURLSession.swift in Sources */ = {isa = PBXBuildFile; fileRef = BCDA737D1CA555070082B197 /* MockURLSession.swift */; };
+		BCEE36811E0830810091D113 /* settings.json in Resources */ = {isa = PBXBuildFile; fileRef = BCEE36801E0830810091D113 /* settings.json */; };
+		BCEE36831E08309F0091D113 /* objects.json in Resources */ = {isa = PBXBuildFile; fileRef = BCEE36821E08309F0091D113 /* objects.json */; };
 		BCFC281C1D92660C00BFE0A0 /* MirroredIndexTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = BCFC281B1D92660C00BFE0A0 /* MirroredIndexTests.swift */; };
 		BCFC281D1D92670100BFE0A0 /* Helpers.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5D44D0261B362648008369AC /* Helpers.swift */; };
 /* End PBXBuildFile section */
@@ -215,7 +217,7 @@
 		BC23A6EC1D63539A00DF9034 /* AlgoliaSearch.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = AlgoliaSearch.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		BC4A7F381CB5308100AF1DCB /* AsyncOperation.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = AsyncOperation.swift; sourceTree = "<group>"; };
 		BC4A7F3B1CB5373E00AF1DCB /* CancelTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = CancelTests.swift; sourceTree = "<group>"; };
-		BC4BD2931D54E48900170ECC /* AlgoliaSearch.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = AlgoliaSearch.framework; sourceTree = BUILT_PRODUCTS_DIR; };
+		BC4BD2931D54E48900170ECC /* AlgoliaSearchOffline.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = AlgoliaSearchOffline.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		BC4DDEEF1DD10E8B004D9A6E /* AbstractClient.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = AbstractClient.swift; sourceTree = "<group>"; };
 		BC4DDEF51DD10EBA004D9A6E /* Types.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = Types.swift; sourceTree = "<group>"; };
 		BC4DDEFB1DD11527004D9A6E /* PlacesClient.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = PlacesClient.swift; sourceTree = "<group>"; };
@@ -239,6 +241,8 @@
 		BCD57D3B1D89B1EA00C5DE68 /* OfflineTestCase.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = OfflineTestCase.swift; sourceTree = "<group>"; };
 		BCDA73771CA546800082B197 /* NetworkTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = NetworkTests.swift; sourceTree = "<group>"; };
 		BCDA737D1CA555070082B197 /* MockURLSession.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = MockURLSession.swift; sourceTree = "<group>"; };
+		BCEE36801E0830810091D113 /* settings.json */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.json; path = settings.json; sourceTree = "<group>"; };
+		BCEE36821E08309F0091D113 /* objects.json */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.json; path = objects.json; sourceTree = "<group>"; };
 		BCFC281B1D92660C00BFE0A0 /* MirroredIndexTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = MirroredIndexTests.swift; sourceTree = "<group>"; };
 		F52EEAD0E1031BA77193C0AF /* Pods_AlgoliaSearch_Offline_iOS_Tests.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = Pods_AlgoliaSearch_Offline_iOS_Tests.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 /* End PBXFileReference section */
@@ -308,7 +312,7 @@
 			isa = PBXFrameworksBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
-				BCD57D311D89B12E00C5DE68 /* AlgoliaSearch.framework in Frameworks */,
+				BCD57D311D89B12E00C5DE68 /* AlgoliaSearchOffline.framework in Frameworks */,
 				3A11AC4EE771A46C306173F7 /* Pods_AlgoliaSearch_Offline_iOS_Tests.framework in Frameworks */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
@@ -345,7 +349,7 @@
 				5DB251471AAD9EE400945339 /* AlgoliaSearch iOS Tests.xctest */,
 				BCD1F54A1CC61C8D0006E227 /* AlgoliaSearch.framework */,
 				BCD1F5531CC61C8D0006E227 /* AlgoliaSearch tvOS Tests.xctest */,
-				BC4BD2931D54E48900170ECC /* AlgoliaSearch.framework */,
+				BC4BD2931D54E48900170ECC /* AlgoliaSearchOffline.framework */,
 				BC23A6EC1D63539A00DF9034 /* AlgoliaSearch.framework */,
 				BCD57D2C1D89B12E00C5DE68 /* AlgoliaSearch-Offline-iOS-Tests.xctest */,
 			);
@@ -456,6 +460,8 @@
 				BCD57D3A1D89B1EA00C5DE68 /* OfflineIndexTests.swift */,
 				BCD57D3B1D89B1EA00C5DE68 /* OfflineTestCase.swift */,
 				BC6267ED1D8FE4180014C767 /* OfflineObjcBridging.m */,
+				BCEE36801E0830810091D113 /* settings.json */,
+				BCEE36821E08309F0091D113 /* objects.json */,
 			);
 			path = Offline;
 			sourceTree = "<group>";
@@ -607,7 +613,7 @@
 			);
 			name = "AlgoliaSearch-Offline-iOS";
 			productName = AlgoliaSarch;
-			productReference = BC4BD2931D54E48900170ECC /* AlgoliaSearch.framework */;
+			productReference = BC4BD2931D54E48900170ECC /* AlgoliaSearchOffline.framework */;
 			productType = "com.apple.product-type.framework";
 		};
 		BCD1F5491CC61C8D0006E227 /* AlgoliaSearch tvOS */ = {
@@ -790,6 +796,8 @@
 			isa = PBXResourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				BCEE36831E08309F0091D113 /* objects.json in Resources */,
+				BCEE36811E0830810091D113 /* settings.json in Resources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
@@ -1422,7 +1430,7 @@
 				INSTALL_PATH = "$(LOCAL_LIBRARY_DIR)/Frameworks";
 				LD_RUNPATH_SEARCH_PATHS = "$(inherited) @executable_path/Frameworks @loader_path/Frameworks";
 				PRODUCT_BUNDLE_IDENTIFIER = "com.algolia.$(PRODUCT_NAME:rfc1034identifier)";
-				PRODUCT_NAME = AlgoliaSearch;
+				PRODUCT_NAME = AlgoliaSearchOffline;
 				SDKROOT = iphoneos;
 				SKIP_INSTALL = YES;
 				TARGETED_DEVICE_FAMILY = "1,2";
@@ -1444,7 +1452,7 @@
 				INSTALL_PATH = "$(LOCAL_LIBRARY_DIR)/Frameworks";
 				LD_RUNPATH_SEARCH_PATHS = "$(inherited) @executable_path/Frameworks @loader_path/Frameworks";
 				PRODUCT_BUNDLE_IDENTIFIER = "com.algolia.$(PRODUCT_NAME:rfc1034identifier)";
-				PRODUCT_NAME = AlgoliaSearch;
+				PRODUCT_NAME = AlgoliaSearchOffline;
 				SDKROOT = iphoneos;
 				SKIP_INSTALL = YES;
 				TARGETED_DEVICE_FAMILY = "1,2";

Source/Index.swift

@@ -143,19 +143,19 @@ import Foundation
     ///
     @objc
     @discardableResult public func getObject(withID objectID: String, completionHandler: @escaping CompletionHandler) -> Operation {
-        let path = "1/indexes/\(urlEncodedName)/\(objectID.urlEncodedPathComponent())"
-        return client.performHTTPQuery(path: path, method: .GET, body: nil, hostnames: client.readHosts, completionHandler: completionHandler)
+        return getObject(withID: objectID, attributesToRetrieve: nil, completionHandler: completionHandler)
     }
 
     /// Get an object from this index, optionally restricting the retrieved content.
     ///
     /// - parameter objectID: Identifier of the object to retrieve.
-    /// - parameter attributesToRetrieve: List of attributes to retrieve.
+    /// - parameter attributesToRetrieve: List of attributes to retrieve. If `nil`, all attributes are retrieved.
+    ///                                   If one of the elements is `"*"`, all attributes are retrieved.
     /// - parameter completionHandler: Completion handler to be notified of the request's outcome.
     /// - returns: A cancellable operation.
     ///
     @objc
-    @discardableResult public func getObject(withID objectID: String, attributesToRetrieve: [String], completionHandler: @escaping CompletionHandler) -> Operation {
+    @discardableResult public func getObject(withID objectID: String, attributesToRetrieve: [String]?, completionHandler: @escaping CompletionHandler) -> Operation {
         let query = Query()
         query.attributesToRetrieve = attributesToRetrieve
         let path = "1/indexes/\(urlEncodedName)/\(objectID.urlEncodedPathComponent())?\(query.build())"
@@ -170,16 +170,7 @@ import Foundation
     ///
     @objc
     @discardableResult public func getObjects(withIDs objectIDs: [String], completionHandler: @escaping CompletionHandler) -> Operation {
-        let path = "1/indexes/*/objects"
-        
-        var requests = [Any]()
-        requests.reserveCapacity(objectIDs.count)
-        for id in objectIDs {
-            requests.append(["indexName": self.name, "objectID": id])
-        }
-        let request = ["requests": requests]
-        
-        return client.performHTTPQuery(path: path, method: .POST, body: request, hostnames: client.readHosts, completionHandler: completionHandler)
+        return getObjects(withIDs: objectIDs, attributesToRetrieve: nil, completionHandler: completionHandler)
     }
 
     /// Get several objects from this index, optionally restricting the retrieved content.
@@ -191,16 +182,16 @@ import Foundation
     /// - returns: A cancellable operation.
     ///
     @objc
-    @discardableResult public func getObjects(withIDs objectIDs: [String], attributesToRetrieve: [String], completionHandler: @escaping CompletionHandler) -> Operation {
+    @discardableResult public func getObjects(withIDs objectIDs: [String], attributesToRetrieve: [String]?, completionHandler: @escaping CompletionHandler) -> Operation {
         let path = "1/indexes/*/objects"
         var requests = [Any]()
         requests.reserveCapacity(objectIDs.count)
         for id in objectIDs {
-            let request = [
+            var request = [
                 "indexName": self.name,
                 "objectID": id,
-                "attributesToRetrieve": attributesToRetrieve.joined(separator: ",")
             ]
+            request["attributesToRetrieve"] = attributesToRetrieve?.joined(separator: ",")
             requests.append(request as Any)
         }
         return client.performHTTPQuery(path: path, method: .POST, body: ["requests": requests], hostnames: client.readHosts, completionHandler: completionHandler)