New Searchable protocol & static User-Agent header (#321)

* [refact] `User-Agent` header now a static property

This is required to abstract InstantSearch Core’s `Searcher` class from the `Index` class. Otherwise we cannot access the `Client` instance, therefore we cannot patch the user agent. By making it a global property, we allow patching from anywhere.

There is now an `addUserAgent(…)` method that takes care of deduplication.

Patching of headers is now done at the `Request` level, which means that users cannot accidentally erase the `User-Agent` header: they can only add to it.

WARNING: Small backward-compatibility break since the instance property is no longer writable. But it was documented as for “internal purposes only”, so nobody should use it.

* New `Searchable` protocol

This unites all indices (`Index`, `MirroredIndex` and `OfflineIndex`) under a common protocol, which can be leveraged in InstantSearch Core to support searching on an offline index.

Author: Clément Le Provost

AlgoliaSearch.xcodeproj/project.pbxproj

@@ -51,6 +51,11 @@
 		BC23A6FC1D63541500DF9034 /* Query.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5D7495A61A8E499B00B0263F /* Query.swift */; };
 		BC23A6FD1D63541500DF9034 /* Request.swift in Sources */ = {isa = PBXBuildFile; fileRef = BC01E66C1CA43CEE0067670B /* Request.swift */; };
 		BC23A6FE1D63541B00DF9034 /* BrowseIterator.swift in Sources */ = {isa = PBXBuildFile; fileRef = BC09F7761CAE743900ABB395 /* BrowseIterator.swift */; };
+		BC28C4D71E5B5A0E00EFC4A0 /* Searchable.swift in Sources */ = {isa = PBXBuildFile; fileRef = BC28C4D61E5B5A0E00EFC4A0 /* Searchable.swift */; };
+		BC28C4D81E5B5A0E00EFC4A0 /* Searchable.swift in Sources */ = {isa = PBXBuildFile; fileRef = BC28C4D61E5B5A0E00EFC4A0 /* Searchable.swift */; };
+		BC28C4D91E5B5A0E00EFC4A0 /* Searchable.swift in Sources */ = {isa = PBXBuildFile; fileRef = BC28C4D61E5B5A0E00EFC4A0 /* Searchable.swift */; };
+		BC28C4DA1E5B5A0E00EFC4A0 /* Searchable.swift in Sources */ = {isa = PBXBuildFile; fileRef = BC28C4D61E5B5A0E00EFC4A0 /* Searchable.swift */; };
+		BC28C4DB1E5B5A0E00EFC4A0 /* Searchable.swift in Sources */ = {isa = PBXBuildFile; fileRef = BC28C4D61E5B5A0E00EFC4A0 /* Searchable.swift */; };
 		BC3DC7521E02DD7900862F5B /* NetworkReachability.swift in Sources */ = {isa = PBXBuildFile; fileRef = BC15FAC01E01C041005E3B56 /* NetworkReachability.swift */; };
 		BC3DC7531E02DD7A00862F5B /* NetworkReachability.swift in Sources */ = {isa = PBXBuildFile; fileRef = BC15FAC01E01C041005E3B56 /* NetworkReachability.swift */; };
 		BC3DC7541E02DD7B00862F5B /* NetworkReachability.swift in Sources */ = {isa = PBXBuildFile; fileRef = BC15FAC01E01C041005E3B56 /* NetworkReachability.swift */; };
@@ -220,6 +225,7 @@
 		BC0A01631C9C19CD00CD4A7C /* QueryTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = QueryTests.swift; sourceTree = "<group>"; };
 		BC15FAC01E01C041005E3B56 /* NetworkReachability.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = NetworkReachability.swift; sourceTree = "<group>"; };
 		BC23A6EC1D63539A00DF9034 /* AlgoliaSearch.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = AlgoliaSearch.framework; sourceTree = BUILT_PRODUCTS_DIR; };
+		BC28C4D61E5B5A0E00EFC4A0 /* Searchable.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = Searchable.swift; sourceTree = "<group>"; };
 		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 /* AlgoliaSearchOffline.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = AlgoliaSearchOffline.framework; sourceTree = BUILT_PRODUCTS_DIR; };
@@ -381,6 +387,7 @@
 				BC4DDF071DD12BCC004D9A6E /* PlacesQuery.swift */,
 				5D7495A61A8E499B00B0263F /* Query.swift */,
 				BC01E66C1CA43CEE0067670B /* Request.swift */,
+				BC28C4D61E5B5A0E00EFC4A0 /* Searchable.swift */,
 				BC4DDEF51DD10EBA004D9A6E /* Types.swift */,
 				BC09F7751CAE742800ABB395 /* Helpers */,
 				BC0A015F1C9BEDE000CD4A7C /* Offline */,
@@ -906,6 +913,7 @@
 				BC4DDEFC1DD11527004D9A6E /* PlacesClient.swift in Sources */,
 				BCD57D1F1D89947500C5DE68 /* DisjunctiveFaceting.swift in Sources */,
 				BC4DDF021DD11697004D9A6E /* AbstractQuery.swift in Sources */,
+				BC28C4D71E5B5A0E00EFC4A0 /* Searchable.swift in Sources */,
 				BC4DDEF01DD10E8B004D9A6E /* AbstractClient.swift in Sources */,
 				5D09E1DC1AC0773A00B799A6 /* Network.swift in Sources */,
 				5D7495A21A8E277400B0263F /* Client.swift in Sources */,
@@ -951,6 +959,7 @@
 				BC4DDEFD1DD11527004D9A6E /* PlacesClient.swift in Sources */,
 				BCD57D201D89947500C5DE68 /* DisjunctiveFaceting.swift in Sources */,
 				BC4DDF031DD11697004D9A6E /* AbstractQuery.swift in Sources */,
+				BC28C4D81E5B5A0E00EFC4A0 /* Searchable.swift in Sources */,
 				BC4DDEF11DD10E8B004D9A6E /* AbstractClient.swift in Sources */,
 				5DB251591AAD9F2A00945339 /* Query.swift in Sources */,
 				5D09E1DD1AC0773A00B799A6 /* Network.swift in Sources */,
@@ -996,6 +1005,7 @@
 				BC4DDF001DD11527004D9A6E /* PlacesClient.swift in Sources */,
 				BCD57D231D89947500C5DE68 /* DisjunctiveFaceting.swift in Sources */,
 				BC4DDF061DD11697004D9A6E /* AbstractQuery.swift in Sources */,
+				BC28C4DB1E5B5A0E00EFC4A0 /* Searchable.swift in Sources */,
 				BC4DDEF41DD10E8B004D9A6E /* AbstractClient.swift in Sources */,
 				BC23A6F41D63541500DF9034 /* AsyncOperation.swift in Sources */,
 				BC23A6F81D63541500DF9034 /* Helpers.swift in Sources */,
@@ -1023,6 +1033,7 @@
 				BC4BD2881D54E48900170ECC /* Network.swift in Sources */,
 				BC4DDF051DD11697004D9A6E /* AbstractQuery.swift in Sources */,
 				BCD57D271D89970D00C5DE68 /* OfflineIndex.swift in Sources */,
+				BC28C4DA1E5B5A0E00EFC4A0 /* Searchable.swift in Sources */,
 				BCD57D221D89947500C5DE68 /* DisjunctiveFaceting.swift in Sources */,
 				BC4BD2891D54E48900170ECC /* Client.swift in Sources */,
 				BC4BD2961D54E50000170ECC /* MirrorSettings.swift in Sources */,
@@ -1051,6 +1062,7 @@
 				BC4DDEFE1DD11527004D9A6E /* PlacesClient.swift in Sources */,
 				BCD57D211D89947500C5DE68 /* DisjunctiveFaceting.swift in Sources */,
 				BC4DDF041DD11697004D9A6E /* AbstractQuery.swift in Sources */,
+				BC28C4D91E5B5A0E00EFC4A0 /* Searchable.swift in Sources */,
 				BC4DDEF21DD10E8B004D9A6E /* AbstractClient.swift in Sources */,
 				BCD1F5661CC61D100006E227 /* Index.swift in Sources */,
 				BCD1F5611CC61CFE0006E227 /* AsyncOperation.swift in Sources */,

Source/AbstractClient.swift

@@ -102,19 +102,33 @@ internal struct HostStatus {
         headers["X-Algolia-API-Key"] = _apiKey
     }
 
-    /// The list of libraries used by this client, passed in the `User-Agent` HTTP header of every request.
-    /// It is initially set to contain only this API Client, but may be overridden to include other libraries.
+    /// The list of libraries used by this client.
+    ///
+    /// + Warning: Deprecated. Now a static property of the `Client` class. The instance properties are just an alias
+    ///   for the static property.
+    ///
+    @available(*, deprecated: 4.8)
+    @objc public var userAgents: [LibraryVersion] {
+        get { return AbstractClient.userAgents }
+    }
+
+    /// The list of libraries used by instances of this class.
+    /// They are passed in the `User-Agent` HTTP header of every request.
+    /// It is initially set to contain only this library and the OS, but may be overridden to include other libraries.
     ///
     /// + WARNING: The user agent is crucial to proper statistics in your Algolia dashboard. Please leave it as is.
-    /// This field is publicly exposed only for the sake of other Algolia libraries.
+    ///   This field is publicly exposed only for the sake of other Algolia libraries.
     ///
-    @objc public var userAgents: [LibraryVersion] = [] {
+    @objc public private(set) static var userAgents: [LibraryVersion] = defaultUserAgents() {
         didSet {
-            updateHeadersFromUserAgents()
+            userAgentHeader = computeUserAgentHeader()
         }
     }
-    private func updateHeadersFromUserAgents() {
-        headers["User-Agent"] = userAgents.map({ return "\($0.name) (\($0.version))"}).joined(separator: "; ")
+    /// Precomputed `User-Agent` header (cached for improved performance).
+    internal private(set) static var userAgentHeader: String? = computeUserAgentHeader()
+    
+    private static func computeUserAgentHeader() -> String {
+        return userAgents.map({ return "\($0.name) (\($0.version))"}).joined(separator: "; ")
     }
 
     /// Default timeout for network requests. Default: 30 seconds.
@@ -225,25 +239,8 @@ internal struct HostStatus {
 
         super.init()
 
-        // Add this library's version to the user agents.
-        let version = Bundle(for: type(of: self)).infoDictionary!["CFBundleShortVersionString"] as! String
-        self.userAgents = [ LibraryVersion(name: "Algolia for Swift", version: version) ]
-        
-        // Add the operating system's version to the user agents.
-        if #available(iOS 8.0, OSX 10.0, tvOS 9.0, *) {
-            let osVersion = ProcessInfo.processInfo.operatingSystemVersion
-            var osVersionString = "\(osVersion.majorVersion).\(osVersion.minorVersion)"
-            if osVersion.patchVersion != 0 {
-                osVersionString += ".\(osVersion.patchVersion)"
-            }
-            if let osName = osName {
-                self.userAgents.append(LibraryVersion(name: osName, version: osVersionString))
-            }
-        }
-        
         // WARNING: `didSet` not called during initialization => we need to update the headers manually here.
         updateHeadersFromAPIKey()
-        updateHeadersFromUserAgents()
     }
 
     /// Set read and write hosts to the same value (convenience method).
@@ -281,6 +278,41 @@ internal struct HostStatus {
         return headers[name]
     }
 
+    /// Compute the default user agents for this library.
+    ///
+    /// - returns: Default user agents for this library.
+    ///
+    private static func defaultUserAgents() -> [LibraryVersion] {
+        // Add this library's version to the user agents.
+        let version = Bundle(for: Client.self).infoDictionary!["CFBundleShortVersionString"] as! String
+        var userAgents = [ LibraryVersion(name: "Algolia for Swift", version: version) ]
+        
+        // Add the operating system's version to the user agents.
+        if #available(iOS 8.0, OSX 10.0, tvOS 9.0, *) {
+            let osVersion = ProcessInfo.processInfo.operatingSystemVersion
+            var osVersionString = "\(osVersion.majorVersion).\(osVersion.minorVersion)"
+            if osVersion.patchVersion != 0 {
+                osVersionString += ".\(osVersion.patchVersion)"
+            }
+            if let osName = osName {
+                userAgents.append(LibraryVersion(name: osName, version: osVersionString))
+            }
+        }
+        return userAgents
+    }
+    
+    /// Add a library version to the global list of user agents.
+    ///
+    /// + Note: It is safe to call this function multiple times. Adding an already existing library is a no-op.
+    ///
+    /// - parameter libraryVersion: Library version to add.
+    ///
+    @objc public static func addUserAgent(_ libraryVersion: LibraryVersion) {
+        if userAgents.index(where: { $0 == libraryVersion }) == nil {
+            userAgents.append(libraryVersion)
+        }
+    }
+    
     // MARK: - Operations
 
     /// Ping the server.

Source/Index.swift

@@ -27,7 +27,7 @@ import Foundation
 ///
 /// + Note: You cannot construct this class directly. Please use `Client.index(withName:)` to obtain an instance.
 ///
-@objc public class Index : NSObject {
+@objc public class Index : NSObject, Searchable {
     // MARK: Properties
 
     /// This index's name.

Source/Offline/OfflineClient.swift

@@ -73,6 +73,12 @@ typealias APIResponse = (content: JSONObject?, error: Error?)
 
     // MARK: Initialization
 
+    // Fake global property to act as static initializer. This is the recommended (and only, AFAIK) way, as per the doc.
+    // See <http://stackoverflow.com/a/37887068/5838753>
+    private static let _initUserAgent: Void = {
+        addUserAgent(LibraryVersion(name: "AlgoliaSearchOfflineCore-iOS", version: Sdk.shared.versionString))
+    }()
+    
     /// Create a new offline-capable Algolia Search client.
     ///
     /// + Note: Offline mode is disabled by default, until you call `enableOfflineMode(...)`.
@@ -90,7 +96,8 @@ typealias APIResponse = (content: JSONObject?, error: Error?)
         tmpDir = URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent("algolia").path
         super.init(appID: appID, apiKey: apiKey)
         mixedRequestQueue.maxConcurrentOperationCount = super.requestQueue.maxConcurrentOperationCount
-        userAgents.append(LibraryVersion(name: "AlgoliaSearchOfflineCore-iOS", version: sdk.versionString))
+        // IMPORTANT: Update user agent. This will only be invoked once (static property).
+        OfflineClient._initUserAgent
     }
 
     /// Enable the offline mode.

Source/Offline/OfflineIndex.swift

@@ -130,7 +130,7 @@ public struct IOError: CustomNSError {
 /// - You cannot batch arbitrary write operations in a single method call (as you would do with `Index.batch(...)`).
 ///   However, all write operations are *de facto* batches, since they must be wrapped inside a transaction (see below).
 ///
-@objc public class OfflineIndex : NSObject {
+@objc public class OfflineIndex : NSObject, Searchable {
     // TODO: Expose common behavior through a protocol.
     // TODO: Factorize common behavior in a base class.
 

Source/Request.swift

@@ -74,7 +74,10 @@ internal class Request: AsyncOperationWithCompletion {
         self.nextHostIndex = firstHostIndex
         assert(firstHostIndex < hosts.count)
         self.path = path
-        self.headers = headers
+        // IMPORTANT: Enforce the `User-Agent` header on all requests.
+        var patchedHeaders = headers ?? [:]
+        patchedHeaders["User-Agent"] = AbstractClient.userAgentHeader
+        self.headers = patchedHeaders
         self.jsonBody = jsonBody
         assert(jsonBody == nil || (method == .POST || method == .PUT))
         self.timeout = timeout

Source/Searchable.swift

@@ -0,0 +1,68 @@
+//
+//  Copyright (c) 2016 Algolia
+//  http://www.algolia.com/
+//
+//  Permission is hereby granted, free of charge, to any person obtaining a copy
+//  of this software and associated documentation files (the "Software"), to deal
+//  in the Software without restriction, including without limitation the rights
+//  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+//  copies of the Software, and to permit persons to whom the Software is
+//  furnished to do so, subject to the following conditions:
+//
+//  The above copyright notice and this permission notice shall be included in
+//  all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+//  THE SOFTWARE.
+//
+
+import Foundation
+
+
+/// A searchable source of data.
+///
+@objc public protocol Searchable: class {
+    
+    /// Perform a search.
+    ///
+    /// - parameter query: Search parameters.
+    /// - parameter completionHandler: Completion handler to be notified of the request's outcome.
+    /// - returns: A cancellable operation.
+    ///
+    @objc
+    @discardableResult func search(_ query: Query, completionHandler: @escaping CompletionHandler) -> Operation
+    
+    /// Perform a search with disjunctive facets, generating as many queries as number of disjunctive facets (helper).
+    ///
+    /// - parameter query: The query.
+    /// - parameter disjunctiveFacets: List of disjunctive facets.
+    /// - parameter refinements: The current refinements, mapping facet names to a list of values.
+    /// - parameter completionHandler: Completion handler to be notified of the request's outcome.
+    /// - returns: A cancellable operation.
+    ///
+    @objc
+    @discardableResult func searchDisjunctiveFaceting(_ query: Query, disjunctiveFacets: [String], refinements: [String: [String]], completionHandler: @escaping CompletionHandler) -> Operation
+
+
+    /// Search for facet values.
+    /// This searches inside a facet's values, optionally restricting the returned values to those contained in objects
+    /// matching other (regular) search criteria.
+    ///
+    /// - parameter facetName: Name of the facet to search. It must have been declared in the index's
+    ///       `attributesForFaceting` setting with the `searchable()` modifier.
+    /// - parameter text: Text to search for in the facet's values.
+    /// - parameter query: An optional query to take extra search parameters into account. These parameters apply to
+    ///       index objects like in a regular search query. Only facet values contained in the matched objects will be
+    ///       returned.
+    /// - parameter completionHandler: Completion handler to be notified of the request's outcome.
+    /// - returns: A cancellable operation.
+    ///
+    @discardableResult
+    @objc(searchForFacetValuesOf:matching:query:completionHandler:)
+    func searchForFacetValues(of facetName: String, matching text: String, query: Query?, completionHandler: @escaping CompletionHandler) -> Operation
+}

Tests/ClientTests.swift

@@ -374,18 +374,21 @@ class ClientTests: OnlineTestCase {
 
     func testUserAgentHeader() {
         // Test that the initial value of the header is correct.
-        XCTAssert(client.headers["User-Agent"]?.range(of: "^Algolia for Swift \\([0-9.]+\\); (iOS|macOS|tvOS) \\([0-9.]+\\)$", options: .regularExpression) != nil)
+        NSLog("User-Agent 1: \(Client.userAgentHeader!)")
+        XCTAssert(Client.userAgentHeader!.range(of: "^Algolia for Swift \\([0-9.]+\\); (iOS|macOS|tvOS) \\([0-9.]+\\)$", options: .regularExpression) != nil)
 
         // Test equality comparison on the `LibraryVersion` class.
         XCTAssertEqual(LibraryVersion(name: "XYZ", version: "7.8.9"), LibraryVersion(name: "XYZ", version: "7.8.9"))
         XCTAssertNotEqual(LibraryVersion(name: "XYZ", version: "7.8.9"), LibraryVersion(name: "XXX", version: "6.6.6"))
 
-        // Test that changing the user agents results in a proper format.
-        client.userAgents = [
-            LibraryVersion(name: "ABC", version: "1.2.3"),
-            LibraryVersion(name: "DEF", version: "4.5.6")
-        ]
-        XCTAssertEqual(client.headers["User-Agent"], "ABC (1.2.3); DEF (4.5.6)")
+        // Test adding a user agent.
+        Client.addUserAgent(LibraryVersion(name: "ABC", version: "1.2.3"))
+        let userAgentHeader = Client.userAgentHeader!
+        NSLog("User-Agent 2: \(Client.userAgentHeader!)")
+        XCTAssert(Client.userAgentHeader!.range(of: "^Algolia for Swift \\([0-9.]+\\); (iOS|macOS|tvOS) \\([0-9.]+\\); ABC \\(1.2.3\\)$", options: .regularExpression) != nil)
+        // Test that adding the same user agent a second time is a no-op.
+        Client.addUserAgent(LibraryVersion(name: "ABC", version: "1.2.3"))
+        XCTAssert(Client.userAgentHeader! == userAgentHeader)
     }
 
     func testReusingIndices() {

Tests/ObjectiveCBridging.m

@@ -141,9 +141,6 @@ - (void)testClient {
     [headers setValue:@"baz" forKey:@"Foo-Bar"];
     client.headers = headers;
 
-    // User agents.
-    client.userAgents = [client.userAgents arrayByAddingObject:[[LibraryVersion alloc] initWithName:@"FooBar" version:@"1.2.3"]];
-
     // Timeouts.
     client.timeout = client.timeout + 10;
     client.searchTimeout = client.searchTimeout + 5;