Interceptors · Apollo iOS · apollographql/skills · Skills Docs

Interceptors · Apollo iOS · apollographql/skills · Skills Docs

Protocol	Sees	Use for
`GraphQLInterceptor`	`GraphQLRequest` (mutable, including `additionalHeaders`) and the parsed `ParsedResult` stream	Auth (attach + refresh + retry), general retry, operation-level logging, APQ. Default choice for most cross-cutting concerns.
`HTTPInterceptor`	`URLRequest` and `HTTPResponse`	Genuinely HTTP-scoped concerns — static headers unrelated to the operation (`User-Agent`, `Accept-Encoding`), raw-bytes logging, mTLS wiring, response-code instrumentation.
`CacheInterceptor`	Pre-flight cache lookup, post-flight cache write	Custom caching strategies (rare)
`ResponseParsingInterceptor`	Raw response → `ParsedResult`	Custom wire formats (very rare)

import Apollo
import Foundation

final class AppInterceptorProvider: InterceptorProvider, Sendable {
  private let tokenManager: AuthTokenManager

  init(tokenManager: AuthTokenManager) {
    self.tokenManager = tokenManager
  }

  func graphQLInterceptors<Operation: GraphQLOperation>(
    for operation: Operation
  ) -> [any GraphQLInterceptor] {
    [
      MaxRetryInterceptor(maxRetriesAllowed: 3),               // safety-net retry cap (must be first)
      AuthInterceptor(tokenManager: tokenManager),             // attach + refresh + retry-on-401
      AutomaticPersistedQueryInterceptor(),
    ]
  }

  // Most apps don't need custom HTTPInterceptors beyond the default ResponseCodeInterceptor
  // (provided automatically via the protocol extension). Override only when adding
  // static HTTP-scoped headers like User-Agent.

  // `cacheInterceptor` and `responseParser` fall back to the DefaultInterceptorProvider
  // implementations from an extension on InterceptorProvider.
}

let provider = AppInterceptorProvider(tokenManager: tokenManager)
let transport = RequestChainNetworkTransport(
  urlSession: URLSession(configuration: .default),
  interceptorProvider: provider,
  store: store,
  endpointURL: URL(string: "https://api.example.com/graphql")!
)

import Apollo
import ApolloAPI
import Foundation

/// App-owned actor that holds the current access token and can refresh it.
/// Replace the body of `refreshToken()` with your real auth flow — exchanging a
/// stored refresh token at `/oauth/refresh`, prompting Sign in with Apple, etc.
actor AuthTokenManager {
  private(set) var token: String?

  init(initialToken: String? = nil) { self.token = initialToken }

  func currentToken() -> String? { token }

  func refreshToken() async throws -> String {
    let newToken = try await performServerRefresh()
    self.token = newToken
    return newToken
  }

  private func performServerRefresh() async throws -> String {
    // TODO: replace with your app's refresh call.
    fatalError("Implement performServerRefresh() against your auth service")
  }
}

struct AuthInterceptor: GraphQLInterceptor {
  let tokenManager: AuthTokenManager

  func intercept<Request: GraphQLRequest>(
    request: Request,
    next: NextInterceptorFunction<Request>
  ) async throws -> InterceptorResultStream<Request> {
    // Pre-flight: attach the current token.
    var request = request
    if let token = await tokenManager.currentToken() {
      request.additionalHeaders["Authorization"] = "Bearer \(token)"
    }

    // Post-flight: observe 401, refresh, and trigger a retry.
    let originalRequest = request
    return await next(request).mapErrors { [tokenManager] error in
      guard let codeError = error as? ResponseCodeInterceptor.ResponseCodeError,
            codeError.response.statusCode == 401 else {
        throw error
      }
      _ = try await tokenManager.refreshToken()

      // Hand RequestChain the request to retry with. On the next pass through
      // the chain, this same interceptor will re-attach the freshly-rotated
      // token from the manager.
      throw RequestChain.Retry(request: originalRequest)
    }
  }
}

struct StaticAuthInterceptor: GraphQLInterceptor {
  let token: String

  func intercept<Request: GraphQLRequest>(
    request: Request,
    next: NextInterceptorFunction<Request>
  ) async throws -> InterceptorResultStream<Request> {
    var request = request
    request.additionalHeaders["Authorization"] = "Bearer \(token)"
    return await next(request)
  }
}

import Apollo
import os

struct LoggingInterceptor: GraphQLInterceptor {
  let logger: Logger

  func intercept<Request: GraphQLRequest>(
    request: Request,
    next: NextInterceptorFunction<Request>
  ) async throws -> InterceptorResultStream<Request> {
    logger.debug("→ \(Request.Operation.operationName)")
    return await next(request)
      .map { result in
        logger.debug("← \(Request.Operation.operationName) ok")
        return result
      }
      .mapErrors { error in
        logger.error("✕ \(Request.Operation.operationName): \(error)")
        throw error
      }
  }
}

func graphQLInterceptors<Operation: GraphQLOperation>(
  for operation: Operation
) -> [any GraphQLInterceptor] {
  var interceptors: [any GraphQLInterceptor] = [MaxRetryInterceptor()]
  #if DEBUG
  interceptors.append(LoggingInterceptor(logger: Logger(subsystem: "MyApp", category: "Apollo")))
  #endif
  interceptors.append(AutomaticPersistedQueryInterceptor())
  return interceptors
}

struct FallbackToCacheOnFailure: GraphQLInterceptor {
  func intercept<Request: GraphQLRequest>(
    request: Request,
    next: NextInterceptorFunction<Request>
  ) async throws -> InterceptorResultStream<Request> {
    return await next(request).mapErrors { error in
      guard error is ResponseCodeInterceptor.ResponseCodeError else { throw error }
      var request = request
      request.fetchBehavior = FetchBehavior.CacheOnly
      throw RequestChain.Retry(request: request)
    }
  }
}