Update documentation to show how to use new delegates and cache policy

Sources/Apollo/HTTPNetworkTransport.swift

@@ -82,8 +82,7 @@ public class HTTPNetworkTransport: NetworkTransport {
   ///   - configuration: A session configuration used to configure the session. Defaults to `URLSessionConfiguration.default`.
   ///   - sendOperationIdentifiers: Whether to send operation identifiers rather than full operation text, for use with servers that support query persistence. Defaults to false.
   ///   - useGETForQueries: If query operation should be sent using GET instead of POST. Defaults to false.
-  ///   - preflightDelegate: A delegate to check with before sending a request.
-  ///   - requestCompletionDelegate: A delegate to notify when the URLSessionTask has completed.
+  ///   - delegate: [Optional] A delegate which can conform to any or all of `HTTPNetworkTransportPreflightDelegate`, `HTTPNetworkTransportTaskCompletedDelegate`, and `HTTPNetworkTransportRetryDelegate`. Defaults to nil.
   public init(url: URL,
               configuration: URLSessionConfiguration = .default,
               sendOperationIdentifiers: Bool = false,

docs/source/api-reference.md

@@ -3,4 +3,4 @@ title: API Reference
 description: ''
 ---
 
-Please see [here](http://cocoadocs.org/docsets/Apollo/).
+[Coming soon!]

docs/source/fetching-queries.md

@@ -103,4 +103,19 @@ As explained in more detail in [the section on watching queries](/watching-queri
 
 `fetch(query:)` takes an optional `cachePolicy` that allows you to specify when results should be fetched from the server, and when data should be loaded from the local cache.
 
-The default cache policy is `.returnCacheDataElseFetch`, which means data will be loaded from the cache when available, and fetched from the server otherwise. You can specify `.fetchIgnoringCacheData` to always fetch from the server, or `.returnCacheDataDontFetch` to returns data from the cache and never fetch from the server (it returns `nil` when cached data is not available).
+The default cache policy is `.returnCacheDataElseFetch`, which means data will be loaded from the cache when available, and fetched from the server otherwise. 
+
+Other cache polices which you can specify are: 
+
+- **`.fetchIgnoringCacheData`** to always fetch from the server, but still store results to the cache.
+- **`.fetchIgnoringCacheCompletely`** to always fetch from the server and not store results from the cache. If you're not using the cache at all, this method is preferred to `fetchIgnoringCacheData` for performance reasons.
+- **`.returnCacheDataDontFetch`** to return data from the cache and never fetch from the server. This policy will return `nil` when cached data is not available.
+- **`.returnCacheDataAndFetch`** to return cached data immediately, then perform a fetch to see if there are any updates. This is mostly useful if you're watching queries, since those will be updated when the call to the server returns. 
+
+## Using `GET` instead of `POST` for queries
+
+By default, Apollo constructs queries and sends them to your graphql endpoint using `POST` with the JSON generated. 
+
+If you want Apollo to use `GET` instead, pass `true` to the optional `useGETForQueries` parameter when setting up your `HTTPNetworkTransport`. This will set up all queries conforming to `GraphQLQuery` sent through the HTTP transport to use `GET`. 
+
+>Please note that this is a toggle which affects all queries sent through that client, so if you need to have certain queries go as `POST` and certain ones go as `GET`, you will likely have to swap out the `HTTPNetworkTransport`. 

docs/source/initialization.md

@@ -2,26 +2,173 @@
 title: Creating a client
 ---
 
-In most cases, you'll want to create a single shared instance of `ApolloClient` and point it at your GraphQL server. The easiest way to do this is to define a global variable in `AppDelegate.swift`:
+## Basic Client Creation
+
+In most cases, you'll want to create a single shared instance of `ApolloClient` and point it at your GraphQL server. The easiest way to do this is to create a singleton:
 
 ```swift
-let apollo = ApolloClient(url: URL(string: "http://localhost:8080/graphql")!)
+class Apollo {
+  static let shared = Apollo() 
+
+  private(set) lazy var client = ApolloClient(url: URL(string: "http://localhost:8080/graphql")!)
+}
 ```
 
-## Adding additional headers
+Under the hood, this will create a client using `HTTPNetworkTransport` with a default configuration. You can then use this client from anywhere in your code with `Apollo.shared.client`. 
+
+## 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: 
+
+- **`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 {
 
-> 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.
+  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)
+    }
+  }
+}
+```

docs/source/installation.md

@@ -97,7 +97,7 @@ In this case, the `check-and-run-apollo-cli.sh` file is bundled into the framewo
 # Do some magic so we can make sure `FRAMEWORK_SEARCH_PATHS` works correctly when there's a space in the scheme or the folder name.
 QUOTED_FRAMEWORK_SEARCH_PATHS=\"$(echo $FRAMEWORK_SEARCH_PATHS | tr -d '"' | sed -e 's/ \//" "\//g')\"
 
-APOLLO_FRAMEWORK_PATH ="$(eval find ${QUOTED_FRAMEWORK_SEARCH_PATHS} -name "Apollo.framework" -maxdepth 1)"
+APOLLO_FRAMEWORK_PATH="$(eval find ${QUOTED_FRAMEWORK_SEARCH_PATHS} -name "Apollo.framework" -maxdepth 1)"
 
 if [ -z "${APOLLO_FRAMEWORK_PATH}" ]; then
     echo "error: Couldn't find Apollo.framework in FRAMEWORK_SEARCH_PATHS; make sure to add the framework to your project."