ApolloCall execute / toFlow / exception handling improvements

[BoD]

Current situation

ApolloCall exposes 2 APIs:

• suspend execute(): ApolloResponse
• toFlow(): Flow<ApolloResponse>

execute() will throw an ApolloException in case of a network, http, or cache error (can also be ApolloCompositeException in case of network and cache errors)

It will also throw an exception if the underlying Flow contains more than 1 element (ex: CacheAndNetwork or with @defer)

Users need to handle 2 kinds of errors:

• network/http errors with a try catch
• GraphQL errors by looking at .errors

(With ApolloResponse.dataAssertNoErrors this can be centralized in one try catch)

toFlow() will throw an exception either as soon as it is encountered, or assembled in ApolloCompositeException after some responses have been emitted, depending on the case.

Cache misses are either emitted with a null data or not emitted at all (configurable with emitCacheMisses).

Suggested change

• Add an exception: ApolloException? field to ApolloResponse
• Never throw ApolloException in toFlow() : instead, ApolloResponse are emitted with a null data and non-null exception
• To be discussed: should we also not throw in execute()? Not sure of the most logical behavior to adopt with CacheFirst and a cache miss + network error for instance. No exception thrown but return an ApolloResponse with a null data and an ApolloCompositeException in exception?

Benefits:

• Handling network/http errors and GraphQL errors is done in a similar way: look at exception or errors
• More predictable behavior of toFlow(): cache misses / network errors can always be emitted, the caller can decide to ignore them or not by looking at exception, depending on the need
• This can potentially simplify our code in some places

More info

• This would be a breaking change.
• A comment that prompted this idea is here.

[martinbonnin]

This is now merged in main. It's still time to make adjustments if needed though. Please go to the RFC for comments