Support granular caching through smart proxies

[chillu]

Overview

Our GraphQL approach is quite slow, because we create an in-memory representation of the entire schema on each execution, and as usual, caching is hard. While we should generally improve the performance of our module, we also need to allow faster layers outside of SilverStripe to be used effectively.

Due to the nature of GraphQL, this is not (easily) achieved through standard framework features like setting HTTP caching headers and using intermediary caches like CDNs. There's too many permutations of requests.

Acceptance Criteria

• Cache info can be controlled via YAML config alongside GraphQL scaffolding
• Cache info can be controlled via resolvers
• I can define a cache age per path
• I can opt-out of caching ("private scope")
• The same model/type can have different cache settings for different paths
• The cache metadata is optionally output in the Apollo Cache Control standard
• Relevant cache metadata is available to each resolver (for custom implementations)
• The HTTP caching API in 4.2 sets noCache in Apollo Cache Control metadata as required
• There is a PoC of caching (e.g. through Apollo Engine)

Notes

• Related discussion on graphql caching middleware by @tractorcow and @chillu
• See Apollo Caching Feature Configuration
• An alternative approach would be to statically publish representations through persisted query identifiers, and/or hashing the query and params into the filename, combined with some lightweight routing.

[chillu]

Looking at this again. Since I've wrote the initial post, Apollo Engine introduced Automated Persisted Queries. In short, it means if you proxy your GraphQL endpoint through Apollo Engine, front it with your own CDN, and use Apollo Client with this setting, most of the traffic will terminate at your CDN. And you don't need to configure or support persisted queries in your GraphQL endpoint, that's handled transparently.

Unfortunately it doesn't look like the Apollo Cache Standard is getting a lot of adoption. But fortunately, we need to add cache signals to our API surface regardless, even if it only computes a single cache signal for the entire response (via HTTP headers).

There's other GraphQL caching engines, approaches and services popping up:

• FastQL uses a different invalidation approach, relying on an invalidation API and query aliasing, as well as the usual Cache-Control signals from your own GraphQL endpoint (not very granular)
• CloudFlare supports service workers for custom cache behaviour now, which allows per response caching and supports POST requests
• Akamai API Gateway has GraphQL aware per response caching
• AWS AppSync for GraphQL doesn't deal with server-side caching
• DIY caching through Firebase CDN

[chillu]

Proposed scaffolding syntax:

SilverStripe\GraphQL\Controller:
  schema:
    scaffolding:
      types:
        MyProject\Post:
          fields: 
            ID: true
            IsFeatured: true
            Comments:
              cacheControl:
                maxAge: 10
          cacheControl:
            maxAge: 60
        MyProject\Comment:
          fields: [Comment, Author]
          cacheControl:
            maxAge: 60

• It complicates the fields definition. We've gotten away with key or key/value YAML notation (where values are used for descriptions) so far, this would introduce a more verbose way
• The Apolllo Cache Control Standard does not define how cache values are applied or take priority. The Apollo Engine implementation of that is a bit vague about it as well. My current take is that field-based cache control overrides type-based cache control (e.g. in the example above, the Comments field would have maxAge: 10 even though the Comment type has maxAge: 60
• Draft content would be uncached by default. This would be implemented by removing all cache hints from the response
• In order to apply cache control in custom resolver implementations, we need to wrap each resolver with a generic implementation. @unclecheese is already working on that as part of the schema serialisation efforts
• Cache hints in resolvers would be collected via writing to the $context provided to each resolver
• This doesn't rely on anything specific in webonyx/graphql-php, it's just setting $response['extensions'] after the schema has been queried (based on the collected $context values)

[maxime-rainville]

Should we ping OPS about this? Presumably, they'll need to do some updates for CWP/SSP customers to fully benefit from this feature/

[chillu]

Kicking this out of the epic. The Terraformers have proven in their PWA build that persisted queries are possible without too much faff, and those should be cacheable by a CDN. Anything more granular will have to wait.