RFC: GraphQL @defer

Design/3093-graphql-defer.md

@@ -0,0 +1,356 @@
+* Feature Name: GraphQL `@defer`
+* Start Date: 2023-06-26
+* RFC PR: [3093](https://github.com/apollographql/apollo-ios/pull/3093)
+
+# Summary
+
+The specification for `@defer`/`@stream` is slowly making it's way through the GraphQL Foundation approval process and once formally merged into the GraphQL specification Apollo iOS will need to support it. However, Apollo already has a public implementation of `@defer` in the other OSS offerings, namely Apollo Server, Apollo Client, and Apollo Kotlin. The goal of this project is to implement support for `@defer` that matches the other Apollo OSS clients. This project will not include support for the `@stream` directive.
+
+Based on the progress of `@defer`/`@stream` through the approval process there may be some differences in the final specification vs. what is currently implemented in Apollo's OSS. This project does not attempt to preemptively anticipate those changes nor comply with the potentially merged specification. Any client affecting-changes in the merged specification will be implemented into Apollo iOS.
+
+# Proposed Changes
+
+## Update graphql-js dependency
+
+Apollo iOS uses [graphql-js](https://github.com/graphql/graphql-js) for validation of the GraphQL schema and operation documents as the first step in the code generation workflow. The version of this [dependency](https://github.com/apollographql/apollo-ios/blob/spike/defer/Sources/ApolloCodegenLib/Frontend/JavaScript/package.json#L16) is fixed at [`16.3.0-canary.pr.3510.5099f4491dc2a35a3e4a0270a55e2a228c15f13b`](https://www.npmjs.com/package/graphql/v/16.3.0-canary.pr.3510.5099f4491dc2a35a3e4a0270a55e2a228c15f13b?activeTab=versions). This is a version of graphql-js that supports the experimental [Client Controlled Nullability](https://github.com/graphql/graphql-wg/blob/main/rfcs/ClientControlledNullability.md) feature but does not support the `@defer` directive.
+
+The latest `16.x` release of graphql-js with support for the `@defer` directive is [`16.1.0-experimental-stream-defer.6`](https://www.npmjs.com/package/graphql/v/16.1.0-experimental-stream-defer.6) but it looks like the 'experimental' named releases for `@defer` have been discontinued and the recommendation is to use [`17.0.0-alpha.2`](https://www.npmjs.com/package/graphql/v/17.0.0-alpha.2). This is further validated by the fact that [`16.7.0` does not](https://github.com/graphql/graphql-js/blob/v16.7.0/src/type/directives.ts#L167) include the @defer directive whereas [`17.0.0-alpha.2` does](https://github.com/graphql/graphql-js/blob/v17.0.0-alpha.2/src/type/directives.ts#L159).
+
+Potential solutions:
+1. Add support for Client Controlled Nullability to `17.0.0-alpha.2`, or the latest 17.0.0 alpha release, and publish that to NPM. The level of effort for this is unknown but it would allow us to maintain support for CCN.
+2. Use `17.0.0-alpha.2`, or the latest 17.0.0 alpha release, as-is and remove the experimental Client Controlled Nullability feature. We do not know how many users rely on the CCN functionality so this may be a controversial decision. This path doesn’t necessarily imply an easier dependency update because there will be changes needed to our frontend javascript to adapt to the changes in graphql-js.
+3. Another option is a staggered approach where we adopt `17.0.0-alpha.2`, or the latest 17.0.0 alpha release, limiting the changes to our frontend javascript only and at a later stage bring the CCN changes from [PR `#3510`](https://github.com/graphql/graphql-js/pull/3510) to the `17.x` release path and reintroduce support for CCN to Apollo iOS. This would also require the experiemental CCN feature to be removed, with no committment to when it would be reintroduced.
+
+## Rename `PossiblyDeferred` types/functions
+
+Adding support for `@defer` brings new meaning of the word 'deferred' to the codebase. There is an enum type named [`PossiblyDeferred`](https://github.com/apollographql/apollo-ios/blob/spike/defer/Sources/Apollo/PossiblyDeferred.swift#L47) which would cause confusion when trying to understand it’s intent. This type and its related functions should be renamed to disambiguate it from the incoming `@defer` related types and functions.
+
+`PossiblyDeferred` is an internal type so this should have no adverse effect to users’ code.
+
+## Generated models
+
+Generated models will definitely be affected by `@defer` statements in the operation. Ideally there is easy-to-read annotation indicating something is deferred by simply reading the generated model code but more importantly it must be easy when using the generated models in code to detect whether something is deferred or not.
+
+Potential fragment/field solutions:
+1. Property wrappers - I explored Swift's property wrappers but they suffer from the limitation of not being able to be applied to a computed property. All GraphQL fields in the generated models are computed properties because they simply route access to the value in the underlying data dictionary storage. It would be nice to be able to simply annotate fragments and fields with something like `@Deferred` but unfortunately that is not possible.
+2. Optional types - this solution would change the deferred property type to an optional version of that type. This may not seem necessary when considering that only fragments can be marked as deferred but it would be required to cater for the way that Apollo iOS does field merging in the generated model fragments. Field merging is non-optional at the moment but there is an issue ([#2560](https://github.com/apollographql/apollo-ios/issues/2560)) that would make this a configuration option. This solution hides detail though because you wouldn't be able to tell whether the field value is `nil` because the response data hasn't been received yet (i.e.: deferred) or whether the data was returned and it was explicitly `null`. It also gets more complicated when a field type is already optional; would that result in a Swift double-optional type? As we learnt with the legacy implementation of GraphQL nullability, double-optionals are difficult to interpret and easily lead to mistakes.
+3. `Enum` wrapper - an idea that was suggested by [`@Iron-Ham`](https://github.com/apollographql/apollo-ios/issues/2395#issuecomment-1433628466) is to wrap the type in a Swift enum that can expose the deferred state as well as the underlying value once it has been received. This is an improvement to option 2 where the state of the deferred value can be determined.
+
+```swift
+// Sample enum to wrap deferred properties
+enum DeferredValue<T> {
+    case loading
+    case result(Result<T, Error>)
+}
+
+// Sample model with a deferred property
+public struct ModelSelectionSet: GraphAPI.SelectionSet {
+  // other properties not shown
+
+  public var name: DeferredValue<String?> { __data["name"] }
+}
+```
+
+4. Optional fragments (disabling field merging) - optional types are only needed when fragment fields are merged into entity selection sets. If field merging were disabled automatically for deferred fragments then the solution is simplified and we only need to alter the deferred fragments to be optional. Consuming the result data is intuitive too where a `nil` fragment value would indicate that the fragment data has not yet been received (i.e.: deferred) and when the complete response is received the fragment value is populated and the result sent to the client. This seems a more elegant and ergonimic way to indicate the status of deferred data but complicates the understanding of field merging.
+
+```swift
+// Sample usage in a generated model
+public class ExampleQuery: GraphQLQuery {
+  // other properties and types not shown
+
+  public struct Data: ExampleSchema.SelectionSet {
+    public static var __selections: [ApolloAPI.Selection] { [
+      .fragment(EntityFragment?.self)
+    ] }
+  }
+}
+
+// Sample usage in an app completion block
+client.fetch(query: ExampleQuery()) { result in
+  switch (result) {
+  case let .success(data):
+    client.fetch(query: ExampleQuery()) { result in
+      switch (result) {
+      case let .success(data):
+        guard let fragment = data.data?.item.fragments.entityFragment else {
+          // partial result
+        }
+
+        // complete result
+      case let .failure(error):
+        print("Query Failure! \(error)")
+      }
+    }
+  case let .failure(error):
+  }
+}
+
+```
+
+Regardless of the fragment/field solution chosen all deferred fragment definitions in generated models `__selections` will get an additional property to indicate they are deferred. This helps to understand the models when reading them as well as being used by internal code.
+
+```swift
+// Updated Selection enum
+public enum Selection {
+  // other cases not shown
+  case fragment(any Fragment.Type, deferred: Bool)
+  case inlineFragment(any InlineFragment.Type, deferred: Bool)
+
+  // other properties and types not shown
+}
+
+// Sample usage in a generated model
+public class ExampleQuery: GraphQLQuery {
+  // other properties and types not shown
+
+  public struct Data: ExampleSchema.SelectionSet {
+    public static var __selections: [ApolloAPI.Selection] { [
+      .fragment(EntityFragment.self, deferred: true),
+      .inlineFragment(AsEntity.self, deferred: true),
+    ] }
+  }
+}
+```
+
+## Networking 
+
+### Request header
+
+If an operation can support an incremental delivery response it must add an `Accept` header to the HTTP request specifying the protocol version that can be parsed. An [example](https://github.com/apollographql/apollo-ios/blob/spike/defer/Sources/Apollo/RequestChainNetworkTransport.swift#L115) is HTTP subscription requests that include the `subscriptionSpec=1.0` specification. `@defer` would introduce another operation feature that would request an incremental delivery response.
+
+This should not be sent with all requests though so operations will need to be identifiable as having deferred fragments to signal inclusion of the request header.
+
+```swift
+// Sample code for RequestChainNetworkTransport
+public func send<Operation: GraphQLOperation>(
+  operation: Operation,
+  cachePolicy: CachePolicy = .default,
+  contextIdentifier: UUID? = nil,
+  callbackQueue: DispatchQueue = .main,
+  completionHandler: @escaping (Result<GraphQLResult<Operation.Data>, Error>) -> Void
+) -> Cancellable {
+  // request chain and request are built
+
+  if Operation.hasDeferredFragments {
+    request.addHeader(
+      name: "Accept",
+      value: "multipart/mixed;deferSpec=20220824,application/json"
+    )
+  }
+
+  // request chain kickoff
+}
+
+// Sample of new property on GraphQLOperation
+public protocol GraphQLOperation: AnyObject, Hashable {
+  // other properties not shown
+
+  static var hasDeferredFragments: Bool { get } // computed for each operation during codegen
+}
+```
+
+### Response parsing
+
+Apollo iOS already has support for parsing incremental delivery responses. That provides a great foundation to build on however there are some changes needed.
+
+#### Multipart parsing protocol
+
+The current `MultipartResponseParsingInterceptor` implementation is specific to the `subscriptionSpec` version `1.0` specification. Adopting a protocol with implementations for each of the supported specifications will enable us to support any number of incremental delivery specifications in the future.
+
+These would be registered with the `MultipartResponseParsingInterceptor` each with a unique specification string, to be used as a lookup key. When a response is received the specification string is extracted from the response `content-type` header, and the correct specification parser can be used to parse the response data.
+
+```swift
+// Sample code in MultipartResponseParsingInterceptor
+public struct MultipartResponseParsingInterceptor: ApolloInterceptor {
+  private static let multipartParsers: [String: MultipartResponseSpecificationParser.Type] = [
+    SubscriptionResponseParser.protocolSpec: SubscriptionResponseParser.self,
+    DeferResponseParser.protocolSpec: DeferResponseParser.self
+  ]
+
+  public func interceptAsync<Operation>(
+    chain: RequestChain,
+    request: HTTPRequest<Operation>,
+    response: HTTPResponse<Operation>?,
+    completion: @escaping (Result<GraphQLResult<Operation.Data>, Error>) -> Void
+  ) where Operation : GraphQLOperation {
+    // response validators not shown
+
+    guard
+      let multipartBoundary = response.httpResponse.multipartBoundary,
+      let protocolSpec = response.httpResponse.multipartProtocolSpec,
+      let protocolParser = Self.multipartParsers[protocolSpec]
+    else {
+      // call request chain error handler
+
+      return
+    }
+
+    let dataHandler: ((Data) -> Void) = { data in
+      // proceed ahead on the request chain
+    }
+
+    let errorHandler: (() -> Void) = {
+      // call request chain error handler
+    }
+
+    protocolParser.parse(
+      data: response.rawData,
+      boundary: multipartBoundary,
+      dataHandler: dataHandler,
+      errorHandler: errorHandler
+    )
+  }
+}
+
+// Sample protocol for multipart specification parsing
+protocol MultipartResponseSpecificationParser {
+  static var protocolSpec: String { get }
+
+  static func parse(
+    data: Data,
+    boundary: String,
+    dataHandler: ((Data) -> Void),
+    errorHandler: (() -> Void)
+  )
+}
+
+// Sample implementations of multipart specification parsers
+
+struct SubscriptionResponseParser: MultipartResponseSpecificationParser {
+  static let protocolSpec: String = "subscriptionSpec=1.0"
+
+  static func parse(
+    data: Data,
+    boundary: String,
+    dataHandler: ((Data) -> Void),
+    errorHandler: (() -> Void)
+  ) {
+    // parsing code currently in MultipartResponseParsingInterceptor
+  }
+}
+
+struct DeferResponseParser: MultipartResponseSpecificationParser {
+  static let protocolSpec: String = "deferSpec=20220824"
+
+  static func parse(
+    data: Data,
+    boundary: String,
+    dataHandler: ((Data) -> Void),
+    errorHandler: (() -> Void)
+  ) {
+    // new code to parse the defer specification
+  }
+}
+```
+
+#### Response data
+
+The initial response data and data received in each incremental response will need to be retained and combined so that each incremental response can insert the latest received incremental response data at the correct path and return an up-to-date response to the request callback.
+
+The data being retained and combined should not require another pass through the GraphQL executor though.
+
+### Completion handler
+
+`GraphQLResult` should be modified to provide query completion blocks with a high-level abstraction of whether the request has been fulfilled or is still in progress. This prevents clients from having to dig into the deferred fragments to identify the state of the overall request.
+
+Potential solutions:
+1. Introduce a new property on the `GraphQLResult` type that can be used to express the state of the request.
+
+```swift
+// New Response type and property
+public struct GraphQLResult<Data: RootSelectionSet> {
+  // other properties and types not shown
+
+  public enum Response {
+    case partial
+    case complete
+  }
+
+  public let response: Response
+}
+
+// Sample usage in an app completion block
+client.fetch(query: ExampleQuery()) { result in
+  switch (result) {
+  case let .success(data):
+    switch (data.response) {
+    case .complete:
+    case .partial:
+    }
+  case let .failure(error):
+  }
+}
+```
+
+2. Another way which may be a bit more intuitive is to make the `server` case on `Source` have an associated value since `cache` sources will always be complete. The cache could return partial responses for deferred operations but for the initial implementation we will probably only write the cache record once all deferred fragments have been received. This solution becomes invalid though once the cache can return partial responses, with that in mind maybe option 1 is better.
+
+```swift
+// Updated server case on Source with associated value of Response type
+public struct GraphQLResult<Data: RootSelectionSet> {
+  // other properties and types not shown
+
+  public enum Response {
+    case partial
+    case complete
+  }
+
+  public enum Source: Hashable {
+    case cache
+    case server(_ response: Response)
+  }
+}
+
+// Sample usage in an app
+client.fetch(query: ExampleQuery()) { result in
+  switch (result) {
+  case let .success(data):
+    switch (data.source) {
+    case .server(.complete):
+    case .server(.partial):
+    case .cache:
+    }
+  case let .failure(error):
+  }
+}
+```
+
+## GraphQL execution
+
+The executor currently executes on an entire operation selection set. It will need to be adapted to be able to execute on a partial response when deferred fragments have not been received and on an isolated fragment selection set so that incremental responses can be parsed alone instead of needing to execute on the whole operation’s selection set.
+
+An alternative to parsing isolated fragment selection sets would be to execute on all the data currently received. The inefficiency with this is executing on data that would have already been executed on during prior responses.
+
+## Caching
+
+Similarly to GraphQL execution the cache write interceptor is designed to work holistically on the operation and write cache records for a single response. This approach still works for HTTP-based subscriptions because each incremental response contains a selection set for the entire operation.
+
+This approach is not going to work for the incremental responses of `@defer` though and partial responses cannot be written to the cache for the operation. Instead all deferred responses will need to be fulfilled before the record is written to the cache.
+
+```swift
+// Only write cache records for complete responses
+public struct CacheWriteInterceptor: ApolloInterceptor {
+  // other code not shown
+
+  public func interceptAsync<Operation: GraphQLOperation>(
+    chain: RequestChain,
+    request: HTTPRequest<Operation>,
+    response: HTTPResponse<Operation>?,
+    completion: @escaping (Result<GraphQLResult<Operation.Data>, Error>) -> Void
+  ) {
+    // response validators not shown
+
+    guard
+      let createdResponse = response,
+      let parsedResponse = createdResponse.parsedResponse,
+      parsedResponse.source == .server(.complete)
+    else {
+      // a partial response must have been received and should not be written to the cache
+      return
+    }
+
+    // cache write code not shown
+  }
+}
+```
+
+There is a bunch of complexity in writing partial records to the cache such as: query watchers without deferred fragments; how would we handle failed requests; race conditions to fulfil deferred data; amongst others. These problems need careful, thoughtful solutions and this project will not include them in the scope for initial implementation.