[v2] [12/X] ApolloClient Fetch APIs #684

AnthonyMDev · 2025-06-27T02:44:07Z

This pull request introduces the new public facing APIs for the fetch methods of ApolloClient. A few other changes were made to enable these new APIs.

Cache Policies

Depending on a combination of the CachePolicy and the OperationResponseFormat, ApolloClient fetch functions will either return async throws -> GraphQLResult<Query.Data> or throws -> AsyncThrowingStream<GraphQLResult<Query.Data>, any Error> . In order to enable this, the CachePolicy`` now consists of multiple enums that can be used with different ApolloClient` functions.

All of the functions have the same calling signature (fetch(query: cachePolicy: requestConfiguration:)), with only differing return types. This allows the user to call the function passing any value for any of the nested cache policy enums and Swift will automatically infer the correct return type at the call site.

NetworkTransport & RequestChain always return a stream of results, the ApolloClient functions know if they expect that stream to return multiple results or only a single result. For the single result cases, the client awaits the stream and just returns the first emitted value.

This PR also introduces FetchBehavior. This is a new struct that encapsulates the behaviors described by any of the cache policies. For ease of use, the NetworkTransport, RequestChain, and GraphQLRequest operate on the FetchBehavior. The client converts the passed cache policy into a FetchBehavior and passes it to the NetworkTransport.

Additionally a new .networkElseCache cache policy was introduced. While other cache policies have had their names changed and been restructured, no equivalent behavior previously existed.

Request Configuration

This PR also introduces the RequestConfiguration struct. This encapsulates request-specific settings such as requestTimeout and writeResultsToCache. The RequestConfiguration is passed along to the NetworkTransport, which is responsible for respecting the configuration values (typically by passing them to a constructed GraphQLRequest instance).

ApolloClient is initialized with a defaultRequestConfiguration, allowing the requestConfiguration parameter on all fetch functions to be optional with a default nil value. When no configuration is passed, the defaultRequestConfiguration is passed to the NetworkTransport.

RequestChain Behavior

The RequestChain previously would attempt a cache read (if required by the CachePolicy) before any GraphQLInterceptors were called. Meaning for a .cacheOnly request, the interceptors were never called at all. This PR changes that so that GraphQLInterceptors are called first, allowing them to mutate the request before the cache read. The cache response is now also passed back up through the interceptors prior to be emitted out of the result stream.

RequestChain was also modified to support the new .networkElseCache cache policy.

New Utility Extensions

This PR adds utility methods to AsyncThrowingStream for executing tasks and passing through results, improving asynchronous programming support.

For retrying a failed request, allowing interceptor to inspect & change the fetch behavior is useful.

calvincestari · 2025-06-27T23:24:42Z

apollo-ios/Sources/Apollo/ApolloClient.swift

@@ -76,25 +52,31 @@ public final class ApolloClient: ApolloClientProtocol, Sendable {
  ///   - networkTransport: A network transport used to send operations to a server.
  ///   - store: A store used as a local cache. Note that if the `NetworkTransport` or any of its dependencies takes
  ///   a store, you should make sure the same store is passed here so that it can be cleared properly.
-  ///   - defaultCachePolicy: TODO
+  ///   - clientAwarenessMetadata: Metadata used by the


Needing documentation for the new defaultRequestConfiguration parameter.

Yes, I've been changing some of the docs as I go, but we'll need to do a full documentation audit prior to public release.

calvincestari · 2025-06-27T23:25:10Z

apollo-ios/Sources/Apollo/ApolloClient.swift

-  /// - Parameter url: The URL of a GraphQL server to connect to.
+  /// - Parameters:
+  ///   - url: The URL of a GraphQL server to connect to.
+  ///   - clientAwarenessMetadata: Metadata used by the


Needing documentation for the new defaultRequestConfiguration parameter.

Same here..

calvincestari · 2025-06-27T23:48:29Z

apollo-ios/Sources/Apollo/AutoPersistedQueryConfiguration.swift

@@ -26,6 +26,7 @@ public struct AutoPersistedQueryConfiguration: Sendable, Hashable {

 public protocol AutoPersistedQueryCompatibleRequest: GraphQLRequest {

+#warning("Consider moving this to ClientContext or RequestConfiguration?")


RequestConfiguration seems like a good home for this based on the scope/behaviour we discussed yesterday.

The way RequestConfiguration works, the values are just passed to the NetworkTransport which then uses them when constructing the GraphQLRequest. So if we added them there, they would still need to be here also. And I actually think it's vary unlikely right now that you would want a different apq config per request.

Probably, you want the same apq config for all requests on the same NetworkTransport. So I actually think the current setup is correct. RequestChainNetworkTransport is initialized with an apqConfig, and it passes that to each request if constructs. But having it here allows the interceptors to modify the APQ behavior of requests. I think that's what we want.

calvincestari · 2025-06-27T23:50:54Z

apollo-ios/Sources/Apollo/FetchBehavior.swift

+
+// MARK: -
+
+/// Describes the cache/networking behaviors that should be usedfor the execution of a GraphQL


Suggested change

/// Describes the cache/networking behaviors that should be usedfor the execution of a GraphQL

/// Describes the cache/networking behaviors that should be used for the execution of a GraphQL

calvincestari · 2025-06-27T23:56:19Z

apollo-ios/Sources/Apollo/NetworkTransport.swift

@@ -30,8 +32,8 @@ public protocol NetworkTransport: AnyObject, Sendable {
 public protocol SubscriptionNetworkTransport: NetworkTransport {

  func send<Subscription: GraphQLSubscription>(
-    subscription: Subscription,
-    cachePolicy: CachePolicy
+    subscription: Subscription,    


Suggested change

subscription: Subscription,

subscription: Subscription,

calvincestari · 2025-06-27T23:56:45Z

apollo-ios/Sources/Apollo/RequestChain.swift

    public let request: Request

    public init(request: Request) {
-      self.request = request
+      self.request = request      


Suggested change

self.request = request

self.request = request

calvincestari · 2025-06-27T23:58:58Z

apollo-ios/Sources/Apollo/RequestChain.swift

+          } catch {
+            #warning(
+              """
+              TODO: If we are making cache miss return nil (instead of throwing error), then should


Does this reflect the thinking at the end of our conversation yesterday, or an evolution of that?

calvincestari · 2025-06-28T00:00:03Z

apollo-ios/Sources/Apollo/RequestChainNetworkTransport.swift

@@ -19,7 +19,7 @@ public final class RequestChainNetworkTransport: NetworkTransport, Sendable {
  ///
  /// Defaults to an empty dictionary.
  public let additionalHeaders: [String: String]
-
+  


Suggested change

Not sure why there is whitespace being added in places like this?

AnthonyMDev added 3 commits June 26, 2025 17:24

WIP: Setting up FetchBehavior and RequestConfiguration

4794b49

Add FetchBehavior back to GraphQLRequest

a3d8114

For retrying a failed request, allowing interceptor to inspect & change the fetch behavior is useful.

Define new CachePolicy API

311bcf9

This was referenced Jun 27, 2025

[v2] [9/X] Interceptor/RequestChain improvements #678

Open

[v2] [8/X] Add OperationResponseFormat #677

Open

calvincestari reviewed Jun 28, 2025

View reviewed changes

AnthonyMDev mentioned this pull request Jun 28, 2025

[v2] [11/X] Create ClientContext for ClientAwareness #681

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[v2] [12/X] ApolloClient Fetch APIs #684

[v2] [12/X] ApolloClient Fetch APIs #684

Uh oh!

AnthonyMDev commented Jun 27, 2025

Uh oh!

calvincestari Jun 27, 2025

Uh oh!

AnthonyMDev Jun 28, 2025

Uh oh!

calvincestari Jun 27, 2025

Uh oh!

calvincestari Jun 27, 2025

Uh oh!

AnthonyMDev Jun 28, 2025

Uh oh!

calvincestari Jun 27, 2025

Uh oh!

calvincestari Jun 27, 2025

Uh oh!

calvincestari Jun 27, 2025

Uh oh!

calvincestari Jun 27, 2025

Uh oh!

calvincestari Jun 28, 2025

Uh oh!

calvincestari Jun 28, 2025

Uh oh!

Uh oh!

		@@ -26,6 +26,7 @@ public struct AutoPersistedQueryConfiguration: Sendable, Hashable {

		public protocol AutoPersistedQueryCompatibleRequest: GraphQLRequest {

		#warning("Consider moving this to ClientContext or RequestConfiguration?")


		// MARK: -

		/// Describes the cache/networking behaviors that should be usedfor the execution of a GraphQL

[v2] [12/X] ApolloClient Fetch APIs #684

Are you sure you want to change the base?

[v2] [12/X] ApolloClient Fetch APIs #684

Uh oh!

Conversation

AnthonyMDev commented Jun 27, 2025

Cache Policies

Request Configuration

RequestChain Behavior

New Utility Extensions

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!