RFC: Offline Exchange for Graphcache

Summary

The offlineExchange will build on Graphcache’s persistence support (see #674) to bring full offline capabilities to the library.

It will be a new exchange that wraps around the cacheExchange and looks identical in its API with extended functionality.

This extended functionality supplements the persistence support by being able to queue operations when the user went offline, preventing errors from surfacing in the UI when going back online, and also reexecuting operations as necessary.

It shouldn’t duplicate existing functionality, like the retryExchange, but may build on it.

Requirements

• Catch operation results with networkErrors and return their results if the user is online and they’re not exclusively optimistic mutations
  • this behaviour is compatible with retryExchange being added in parallel
• Optimistic mutations must be written to the persistence layer immediately and removed if they succeeded
• When coming back online (or on start) we flush the queued operations that have failed previously and empty the queue
• Prevent offline operations from calling the fetchExchange in the first place when offline by adding a grace period
  • maybe let the user decide whether to let them remain pending or whether to let them fail?

The storage adapter in Graphcache will need to be extended; this is our first draft:

export interface StorageAdapter {
  readMetadata(): Promise<string>;
  writeMetadata(json: string): any;
  readData(): Promise<SerializedEntries>;
  writeData(data: SerializedEntries): any;
  onNetworkChange(cb: () => void): void;
  isOnline(): boolean;
}

[kitten]

I forgot to leave a follow-up comment here, but v3 is now shipping Offline Support (experimental for now) with all the strategies we’ve mentioned across comments and PRs. https://formidable.com/open-source/urql/docs/graphcache/offline/

[kitten]

We are currently checking whether we can reuse some storage adaptor code you already have here.

That being said this is kind of besides the point of this RFC (luckily) 😅 We already have a solid caching and persistence system. The persistence is already able to persist server-accurate state accordingly. Optimistic updates to the cache are separate and always have been. They’re quickly and easily invalidated automatically at the first server result (as they should be). To this point of caching, we don’t need a layer for scheduling;

so to sum this up, here’s a list of what we already have (although some of this isn’t documented as we’re waiting for additional features from this RFC)

• the normalized caching: obviously this package is all about this and this is done. Furthermore we always reflect server-side state accurately in the cache. Our API discourages divergence from server-side state. Optimistic updates are always temporary, and custom updates aren’t ever reacting to queries. So we always prefer server-accurate state.
• buffering during rehydration: we already queue up operations while persistence is running and flush operations afterwards
• persistence: We already support full persistence of server-accurate state to any storage, although we ship no adapters (not sure if we even would) and haven’t documented this feature yet. We also never persist optimistic data
• Commutativity: We added strong guarantees recently that apply layered results from the server in a consistent FIFO order on the cache, even when results arrive in a mixed up order, making offline results a lot simpler. That being said we don’t have multiple clients intercommunicating on the same state and we don’t have clocks. So this strategy is sufficient to avoid conflicts.

So don’t worry about the basic persistence 😅 that’s off-topic here and basically done. We’re more interested in the hard part here of what we do in the face of network-errors.

Mutations can be partially optimistic, so part of the problem is that we’re defining what the user is likely to want to happen in the case of mutations failing, due to the client being offline. Apart from that our problems are mostly solved.

We’re mainly currently discussing what happens to the operation’s result when an optimistic mutation fails. One option is to deliver the optimistic result to the framework bindings immediately and rely on the user to only use optimistic results where it’s sensible.

The other option is to defer the result indefinitely for mutations during offline, or to even deliver the errored result itself. Which are not the favoured options right now 🙃

tl;dr: this is not about persistence of cache data and/or conflict resolution, but simply around the implementation of a full offline exchange 😇