Update advanced section to include info on how to use the HTTPNetworkTransportDelegate and other advanced usages.

Author: designatednerd

docs/source/initialization.md

@@ -18,18 +18,157 @@ Under the hood, this will create a client using `HTTPNetworkTransport` with a de
 
 ## Advanced Client Creation
 
-If you need to add additional headers to requests, to include authentication details for example, you can create your own `URLSessionConfiguration` and use this to configure an `HTTPNetworkTransport`. If you want to define the client as a global variable, you can use an immediately invoked closure here:
+For more advanced usage of the client, you can use this initializer which allows you to pass in an object conforming to the `NetworkTransport` protocol, as well as a store if you wish: 
 
 ```swift
-let apollo: ApolloClient = {
-  let configuration = URLSessionConfiguration.default
-  // Add additional headers as needed
-  configuration.httpAdditionalHeaders = ["Authorization": "Bearer <token>"] // Replace `<token>`
+public init(networkTransport: NetworkTransport, 
+            store: ApolloStore = ApolloStore(cache: InMemoryNormalizedCache()))
+```
 
-  let url = URL(string: "http://localhost:8080/graphql")!
+The available implementations are: 
 
-  return ApolloClient(networkTransport: HTTPNetworkTransport(url: url, configuration: configuration))
-}()
-```
+- **`HTTPNetworkTransport`**, which has a number of configurable options and uses standard HTTP requests to communicate with the server
+- **`WebSocketTransport`**, which will send everything using a web socket. If you're using CocoaPods, make sure to install the `Apollo/WebSocket` sub-spec to access this. 
+- **`SplitNetworkTransport`**, which will send subscription operations via a web socket and all other operations via HTTP. If you're using CocoaPods, make sure to install the `Apollo/WebSocket` sub-spec to access this. 
+
+### Using `HTTPNetworkTransport`
+
+The initializer for `HTTPNetworkTransport` has several properties which can allow you to get better information and finer-grained control of your HTTP requests and responses:
+
+- `configuration` allows you to pass in a custom `URLSessionConfiguration` to set up anything which needs to be done for every single request without alteration. This defaults to `URLSessionConfiguration.default`. 
+- `sendOperationIdentifiers` allows you send operation identifiers along with your requests. **NOTE:** To send operation identifiers, Apollo types must be generated with `operationIdentifier`s or sending data will crash. Due to this restriction, this option defaults to `false`.
+- `useGETForQueries` sends all requests of `query` type using `GET` instead of `POST`. This defaults to `false` to preserve existing behavior in older versions of the client. 
+- `delegate` Can conform to one or many of several sub-protocols for `HTTPNetworkTransportDelegate`, detailed below.
+
+### Using `HTTPNetworkTransportDelegate`
+
+This delegate includes several sub-protocols so that a single parameter can be passed no matter how many sub-protocols it conforms to. 
+
+If you conform to a particular sub-protocol, you must implement all the methods in that sub-protocol, but we've tried to break things out in a sensible fashion. The sub-protocols are: 
+
+#### `HTTPNetworkTransportPreflightDelegate`
+
+This protocol allows pre-flight validation of requests, the ability to bail out before modifying the request, and the ability to modify the `URLRequest` with things like additional headers.
+
+The `shouldSend` method is called before any modifications are made by `willSend`. This allows you do things like check that you have an authentication token in your keychain, and if not, prevent the request from hitting the network. When you cancel a request in `shouldSend`, you will receive an error indicating the request was cancelled. 
+
+The `willSend` method is called with an `inout` parameter for the `URLRequest` which is about to be sent. There are several uses for this functionality. 
+
+The first is simple logging of the request that's about to go out. You could theoretically do this in `shouldSend`, but particularly if you're making any changes to the request, you'd probably want to do your logging after you've finished those changes. 
+
+The most common usage is to modify the request headers. Note that when modifying request headers, you'll need to make a copy of any pre-existing headers before adding new ones. See the [Example Advanced Client Setup](#example-advanced-client-setup) for details. 
+
+You can also make any other changes you need to the request, but be aware that going too crazy with this may lead to Unexpected Behavior™. 
+
+#### `HTTPNetworkTransportTaskCompletedDelegate`
+
+This delegate allows you to peer in to the raw data returned to the `URLSession`. This is helpful both for logging what you're getting directly from your server and for grabbing any information out of the raw response, such as updated authentication tokens, which would be removed before parsing is completed.
+
+#### `HTTPNetworkTransportRetryDelegate`
+
+This delegate allows you to asynchronously determine whether to retry your request. This is asynchronous to allow for things like re-authenticating your user. 
+
+When you decide to retry, the `send` operation for your `GraphQLOperation` will be retried. This means you'll get brand new callbacks from `HTTPNetworkTransportPreflightDelegate` to update your headers again as if it was a totally new request. Therefore, the parameter for the completion closure is a simple `true`/`false` option: Pass `true` to retry, pass `false` to error out. 
+
+**IMPORTANT**: Do not call `true` blindly in the completion closure. If your server is returning 500s or if the user has no internet, this will create an infinite loop of requests that are retrying. This **will** kill your user's battery, and might also run up the bill on their data plan. Make sure to only request a retry when there's something your code can actually do about the problem!
+
+### Example Advanced Client Setup
+
+Here's a sample of a singleton using an advanced client which handles all three sub-protocols. This code assumes you've got the following external classes: 
 
-> Right now, additional headers can only be specified when creating a client. We're working on a better solution for dynamic configuration of the network transport, including the ability to retry requests that failed after refreshing an access token. Please chime in on https://github.com/apollographql/apollo-ios/issues/37 to help shape the design of this feature or to contribute to it.
+- **`UserManager`** to check whether the user is logged in, perform associated checks on errors and responses to see if they need to reauthenticate, and perform reauthentication
+- **`Logger`** to handle printing logs based on their level, and which supports `.debug`, `.error`, or `.always` log levels.
+
+```swift
+// MARK: - Singleton Wrapper
+
+class Apollo {
+  static let shared = Apollo() 
+  
+  // Configure the network transport to use the singleton as the delegate. 
+  private lazy var networkTransport = HTTPNetworkTransport(
+    url: URL(string: "http://localhost:8080/graphql")!,
+    delegate: self
+  )
+    
+  // Use the configured network transport in your client.
+  private(set) lazy var client = ApolloClient(networkTransport: self.networkTransport)
+}
+
+// MARK: - Pre-flight delegate 
+
+extension Apollo: HTTPNetworkTransportPreflightDelegate {
+
+  func networkTransport(_ networkTransport: HTTPNetworkTransport, 
+                          shouldSend request: URLRequest) -> Bool {
+    // If there's an authenticated user, send the request. If not, don't.                        
+    return UserManager.shared.hasAuthenticatedUser
+  }
+  
+  func networkTransport(_ networkTransport: HTTPNetworkTransport, 
+                        willSend request: inout URLRequest) {
+                        
+    // Get the existing headers, or create new ones if they're nil
+    var headers = request.allHTTPHeaders ?? [String: String]()
+
+    // Add any new headers you need
+    headers["Authentication"] = "Bearer \(UserManager.shared.currentAuthToken)"
+  
+    // Re-assign the updated headers to the request.
+    request.headers = headers
+    
+    Logger.log(.debug, "Outgoing request: \(request)")
+  }
+}
+
+// MARK: - Task Completed Delegate
+
+extension Apollo: HTTPNetworkTransportTaskCompletedDelegate {
+  func networkTransport(_ networkTransport: HTTPNetworkTransport,
+                        didCompleteRawTaskForRequest request: URLRequest,
+                        withData data: Data?,
+                        response: URLResponse?,
+                        error: Error?) {
+    Logger.log(.debug, "Raw task completed for request: \(request)")
+                        
+    if let error = error {
+      Logger.log(.error, "Error: \(error)")
+    }
+    
+    if let response = response {
+      Logger.log(.debug, "Response: \(response)")
+    } else {
+      Logger.log(.error, "No URL Response received!")
+    }
+    
+    if let data = data {
+      Logger.log(.debug, "Data: \(String(describing: String(bytes: data, encoding: .utf8)))")
+    } else {
+      Logger.log(.error, "No data received!")
+    }
+  }
+}
+
+// MARK: - Retry Delegate
+
+extension Apollo: HTTPNetworkTransportRetryDelegate {
+
+  func networkTransport(_ networkTransport: HTTPNetworkTransport,
+                        receivedError error: Error,
+                        for request: URLRequest,
+                        response: URLResponse?,
+                        retryHandler: @escaping (_ shouldRetry: Bool) -> Void) {
+    // Check if the error and/or response you've received are something that requires authentication
+    guard UserManager.shared.requiresReAuthentication(basedOn: error, response: response) else {
+      // This is not something this application can handle, do not retry.
+      shouldRetry(false)
+    }
+    
+    // Attempt to re-authenticate asynchronously
+    UserManager.shared.reAuthenticate { success in 
+      // If re-authentication succeeded, try again. If it didn't, don't.
+      shouldRetry(success)
+    }
+  }
+}
+```