Apollo Server 2:Automatic Persisted Queries + KeyValueCache Interface #1149

evans · 2018-06-07T06:48:16Z

This adds support and tests for automatic persisted queries into Apollo Server 2. The cache interface contains get, set, and invalidate and uses strings. A cache can be passed into the ApolloServer constructor or added by the registerServer call. It is currently accessible to runHttpQuery.

The current implementation caches query strings over parsed ASTs. Currently, the graphql-js parser is quite optimized, so the overhead is negligible. If in the future, this overhead becomes significant, then we can address it.

@glasser and I had chatted about an implementation as an extension by adding in another method that could modify the arguments to runQuery, similar to formatParams. This is possible. It would change the error behavior and expectations around having a queryString or parsedQuery, probably to include extensions.persistedQuery. It would also need to have some way of short circuiting the response to include an error, which makes ordering/execution state of extensions much more complicated.

the similarity to formatParams to APQ's does argue in favor of extensions

KeyValueCache is chosen over another name, such as KeyValueStore or ApolloCache, since the cache is generally in-memory and not persisted to disk. Prepending Apollo would suggest that the cache is GraphQL specific like the clients, however the server cache does no normalization, so a more generic name is appropriate.

CHANGELOG
needs docs

…ported

martijnwalraven · 2018-06-08T14:39:22Z

packages/apollo-server-core/src/caching.ts

+    },
+  ): Promise<void>;
+  get(key: string): Promise<string>;
+  invalidate(tags: string[]): Promise<void>;


Should we call this invalidateTags to avoid confusion with key-based invalidation?

I like it! Let's do that

glasser · 2018-06-08T20:33:08Z

docs/source/features/apq.md

+
+The size of individual GraphQL query strings can be a major pain point. Apollo Server allows implements Automatic Persisted Queries (APQ), a technique that greatly improves network performance for GraphQL with zero build-time configuration. A persisted query is a ID or hash that can be sent to the server instead of the entire GraphQL query string. This smaller signature reduces bandwidth utilization and speeds up client loading times.
+
+To accommodate this new query representation, Apollo Server contains a cache that stores the mapping between hash and query string, efficiently retrieving the corresponding query. Previously, the generation of mapping would require a complex build step. Paired with Apollo Client, Apollo Server provides the ability to generate this mapping automatically.


generation of "the" or "this" mapping?

glasser · 2018-06-08T20:33:56Z

docs/source/features/apq.md

+description: Reduce the size of GraphQL requests over the wire
+---
+
+The size of individual GraphQL query strings can be a major pain point. Apollo Server allows implements Automatic Persisted Queries (APQ), a technique that greatly improves network performance for GraphQL with zero build-time configuration. A persisted query is a ID or hash that can be sent to the server instead of the entire GraphQL query string. This smaller signature reduces bandwidth utilization and speeds up client loading times.


maybe worth mentioning it is especially nice for GETs

glasser · 2018-06-08T20:42:29Z

docs/source/features/apq.md

+
+> Note: using `apollo-link-persisted-query` requires migrating from [apollo-boost](https://www.apollographql.com/docs/react/advanced/boost-migration.html):
+
+Inside Apollo Server, the query registry is stored in a user-configurable cache. By default, Apollo Server uses a in-memory cache (shared with other caching features). Read more here about [how to configure caching](caching.html).


There doesn't actually seem to be a default cache.

I would lean towards the default cache being LRU instead of unbounded FWIW.

Also this link doesn't work.

This link still is dead?

glasser · 2018-06-08T20:45:13Z

docs/source/features/apq.md

+curl "http://localhost:4000/?extensions=\{\"persistedQuery\":\{\"version\":1,\"sha256Hash\":\"ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38\"\}\}"
+```
+
+   Expect a response of: `{"errors": [{"message": "PersistedQueryNotFound"}]}`.


My response includes a stacktrace, etc.

Also unrelatedly, it would be nice if runHttpQuery added a newline to the end of its return values! Would make using curl less ugly. (This is for all calls to JSON.stringify in runHttpQuery; probably add a helper.)

glasser · 2018-06-08T20:46:59Z

docs/source/features/apq.md

+1. Request a persisted query:
+
+```bash
+curl "http://localhost:4000/?extensions=\{\"persistedQuery\":\{\"version\":1,\"sha256Hash\":\"ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38\"\}\}"


I think these look a little nicer without the escaping (though then you have to pass -g):

curl -g 'http://localhost:4000/?extensions={"persistedQuery":{"version":1,"sha256Hash":"ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38"}}'

glasser · 2018-06-08T21:04:52Z

packages/apollo-server-core/src/caching.ts

+    },
+  ): Promise<void>;
+  get(key: string): Promise<string>;
+  invalidateTags(tags: string[]): Promise<void>;


What is this? It doesn't seem useful for PQ caches (which are hash-based), so it just seems like it might create a larger requirement for implementing an appropriate cache. Same with TTL.

glasser · 2018-06-08T21:08:25Z

packages/apollo-server-core/src/graphqlOptions.ts

@@ -41,6 +42,7 @@ export interface GraphQLServerOptions<
  // cacheControl?: boolean | CacheControlExtensionOptions;
  cacheControl?: boolean | any;
  extensions?: Array<() => GraphQLExtension>;
+  cache?: KeyValueCache;


As mentioned on slack I think this should explicitly be persistedQueries: { cache } since you may want a different implementation for other caching solutions. Plus it is surprising that passing something to top level "cache" doesn't actually give you a GraphQL cache.

glasser · 2018-06-08T21:09:15Z

packages/apollo-server-core/src/runHttpQuery.ts

+        // It looks like we've received an Apollo Persisted Query.
+        const sha = extensions.persistedQuery.sha256Hash;
+
+        queryString = await optionsObject.cache.get(sha);


Guard against cache not existing (you should be allowed to explicitly disable PQ), send the PersistedQueryNotSupported error in that case.

If you really are encouraging people to pass literally the same cache to multiple features, we should prefix cache keys with some identifier character so that different features don't interact. On the other hand probably there's no good reason to pass the same in-memory hash to multiple features, and for memcache maybe it's just the job of the person building the memcache object to specify a per-feature prefix?

The Engine trace proto has persisted_query_hit and persisted_query_register bools (we don't track PQ misses since there's no trace, and also neither of these are currently shown in the UI). It would be great to get equivalent bools into, say, requestDidStart.

glasser · 2018-06-08T21:10:07Z

packages/apollo-server-core/src/caching.ts

+      tags?: string[];
+    },
+  ): Promise<void>;
+  get(key: string): Promise<string>;


What does this API do if the item is not found in the cache? Is that trivially distinguishable from "error talking to the cache" and "cache value is the empty string"? Promise<string | null> would be one way to do this.

glasser · 2018-06-08T21:13:00Z

packages/apollo-server-core/src/runHttpQuery.ts

+        if (sha !== calculatedSha) {
+          throw new HttpQueryError(400, `provided sha does not match query`);
+        }
+        await optionsObject.cache.set(sha, queryString);


Ditto for guard.

In engineproxy we explicitly did this write asynchronously and logged errors but didn't wait on the result. Might be a good idea here too, as long as we're comfortable logging errors (or doing something else with them)!

martijnwalraven · 2018-06-09T04:03:02Z

packages/apollo-server-core/src/ApolloServer.ts

        requestOptions.persistedQueries = {
-          cache: new Keyv(),
+          cache: new Keyv({ store: lru }),


Do we need Keyv here? I think we could just use QuickLru as the cache implementation directly.

Keyv adds the ability to have the same Promise based interface

glasser · 2018-06-09T17:59:33Z

packages/apollo-server-core/src/ApolloServer.ts

+        //https://github.com/withspectrum/spectrum has about 200 instances of gql`
+        //300 queries seems reasonable
+        const lru = new QuickLru({ maxSize: 300 });
+        requestOptions.persistedQueries = {


maybe clone requestOptions if we're going to mutate it?

requestOptions is a clone of config, set in the destructuring. Are you thinking that we need to deep clone as opposed to the just having an internal reference

oops, missed that.

glasser · 2018-06-09T18:00:20Z

packages/apollo-server-core/src/ApolloServer.ts

-          ? await this.context({ req: request })
+          ? await this.context({
+              req: request,
+              //This cache should be the full response cache


clean this up

glasser · 2018-06-09T18:03:00Z

packages/apollo-server-core/src/runHttpQuery.ts

+            optionsObject,
+          );
+        } else if (extensions.persistedQuery.version !== 1) {
+          throw new HttpQueryError(400, 'Unsuported persited query version');


the first two words both have typos

glasser · 2018-06-09T18:03:52Z

packages/apollo-server-core/src/runHttpQuery.ts

+          optionsObject.persistedQueries.cache
+            .set(sha, queryString)
+            .catch(error => {
+              optionsObject.logFunction({


isn't logFunction optional?

glasser · 2018-06-09T18:04:31Z

packages/apollo-server-core/src/runHttpQuery.ts

+            throw new HttpQueryError(400, 'provided sha does not match query');
+          }
+
+          optionsObject.persistedQueries.cache


worth having a comment explicitly saying we're purposefully not waiting here.

also you could do the whole operation async by starting with Promise.resolve().then, but maybe this is fine.

glasser · 2018-06-09T18:05:19Z

packages/apollo-server-core/src/ApolloServer.ts

+        //300 queries seems reasonable
+        const lru = new QuickLru({ maxSize: 300 });
+        requestOptions.persistedQueries = {
+          cache: new Keyv({ store: lru }),


nice find with keyv. odd that they don't have a memcached.

glasser

almost ready, a few tweaks

glasser · 2018-06-11T22:30:28Z

packages/apollo-server-core/src/runHttpQuery.ts

+              return optionsObject.persistedQueries.cache.set(sha, queryString);
+            })
+            .catch(error => {
+              console.log(error);


I think this should only happen if you don't provide logFunction.

glasser · 2018-06-11T22:32:26Z

docs/source/features/apq.md

+
+The size of individual GraphQL query strings can be a major pain point. Apollo Server allows implements Automatic Persisted Queries (APQ), a technique that greatly improves network performance for GraphQL with zero build-time configuration. A persisted query is a ID or hash that can be sent to the server instead of the entire GraphQL query string. This smaller signature reduces bandwidth utilization and speeds up client loading times. Persisted queries are especially nice paired with GET requests, enabling the browser cache and [integration with a CDN](#get).
+
+To accommodate the new query representation, Apollo Server contains a cache that stores the mapping between hash and query string. Previously, the generation of mapping would require a complex build step. Apollo Server paired with Apollo Client provides the ability to generate the mapping automatically.


"previously" isn't really a thing that actually happened though

With Apollo Persisted Queries, the ID is a deterministic hash of the input query, so you don't need a complex build step to share the ID between clients and servers. If a server doesn't know about a given hash, the client can expand the query for it; Apollo Server caches that mapping.

perhaps?

glasser · 2018-06-11T22:32:50Z

docs/source/features/apq.md

+
+> Note: using `apollo-link-persisted-query` requires migrating from [apollo-boost](https://www.apollographql.com/docs/react/advanced/boost-migration.html):
+
+Inside Apollo Server, the query registry is stored in a user-configurable cache. By default, Apollo Server uses a in-memory cache (shared with other caching features). Read more here about [how to configure caching](caching.html).


This link still is dead?

glasser · 2018-06-11T22:34:25Z

packages/apollo-server-core/src/caching.ts

+      tags?: string[];
+    },
+  ): Promise<void>;
+  get(key: string): Promise<string> | Promise<null | undefined>;


Not sure how this differs from Promise<string |null | undefined>

glasser · 2018-06-11T22:34:44Z

packages/apollo-server-core/src/caching.ts

+  get(key: string): Promise<string | null>;
+}
+
+export interface KeyValueCache extends PersistedQueryCache {


This doesn't seem to be used, so let's hold off on it until we're using it?

evans added 6 commits June 6, 2018 17:58

core: add cache interface

719fa93

core: initial implementation of APQ

bba1902

core: initial tests for persisted queries

fc788d0

core: add explicit reference to ApolloCache for tsc

53e25b6

core: format persisted query Error and correct sha import

2268c7b

core: tests for persisted queries and remove old persistedQuery unsup…

681a99a

…ported

ghost added the ⛲️ feature New addition or enhancement to existing solutions label Jun 7, 2018

evans added this to the Release 2.0 milestone Jun 7, 2018

core: change ApolloCache to KeyValueCache

6e463c7

evans changed the title ~~Apollo Server 2:Automatic Persisted Queries + ApolloCache Interface~~ Apollo Server 2:Automatic Persisted Queries + KeyValueCache Interface Jun 7, 2018

ghost added the ⛲️ feature New addition or enhancement to existing solutions label Jun 7, 2018

evans added 4 commits June 7, 2018 21:12

docs: add documentation for automatic persisted queries

45ca6d7

core: add test for GET request with persisted query hashes

2a85be9

core: add APQ to changelog

81431d2

integration-testsuite: add apq tests

c961b43

martijnwalraven reviewed Jun 8, 2018

View reviewed changes

core: KeyValueCache change invalidate to invalidateTags

085b71d

glasser reviewed Jun 8, 2018

View reviewed changes

evans added 6 commits June 8, 2018 17:19

docs: update curls to use -g and add note about using GET

11a005e

core: move APQ tests out of subscription describe block

d480191

core: separate persisted query cache and have a default impl

1481c7e

core: middleware throw NotSupported if no cache impl passed in

87cbe51

core: make default cache an lru implementation

317cf0d

core: prettify all JSON.stringify with helper method

b130457

martijnwalraven reviewed Jun 9, 2018

View reviewed changes

glasser reviewed Jun 9, 2018

View reviewed changes

evans added 2 commits June 11, 2018 13:15

core: remove commented out cache from context args

1ae8e32

core: make persisted query write completely asynchronous

8cba571

evans force-pushed the server-2.0/apq branch 2 times, most recently from cb13f4d to ae8ef9a Compare June 11, 2018 21:27

evans added 2 commits June 11, 2018 14:30

Merge branch 'version-2' into server-2.0/apq

0f46177

core: fix sha import and fix persisted query cache test

fd27bc8

evans force-pushed the server-2.0/apq branch from ae8ef9a to fd27bc8 Compare June 11, 2018 21:30

glasser reviewed Jun 11, 2018

View reviewed changes

A few tweaks from code review pairing

dfde27c

glasser merged commit a7cd3a4 into version-2 Jun 11, 2018

glasser deleted the server-2.0/apq branch June 11, 2018 22:44

github-actions bot locked as resolved and limited conversation to collaborators Apr 23, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Apollo Server 2:Automatic Persisted Queries + KeyValueCache Interface #1149

Apollo Server 2:Automatic Persisted Queries + KeyValueCache Interface #1149

evans commented Jun 7, 2018 •

edited

Loading

martijnwalraven Jun 8, 2018

evans Jun 8, 2018

glasser Jun 8, 2018

glasser Jun 8, 2018

glasser Jun 8, 2018

glasser Jun 9, 2018

glasser Jun 11, 2018

glasser Jun 8, 2018

glasser Jun 8, 2018

glasser Jun 8, 2018

glasser Jun 8, 2018

glasser Jun 8, 2018

glasser Jun 8, 2018

glasser Jun 8, 2018

glasser Jun 8, 2018

martijnwalraven Jun 9, 2018

evans Jun 11, 2018

glasser Jun 9, 2018

evans Jun 11, 2018

glasser Jun 11, 2018

glasser Jun 9, 2018

glasser Jun 9, 2018

glasser Jun 9, 2018

glasser Jun 9, 2018

glasser Jun 9, 2018

glasser left a comment

glasser Jun 11, 2018

glasser Jun 11, 2018

glasser Jun 11, 2018

glasser Jun 11, 2018

glasser Jun 11, 2018


		The size of individual GraphQL query strings can be a major pain point. Apollo Server allows implements Automatic Persisted Queries (APQ), a technique that greatly improves network performance for GraphQL with zero build-time configuration. A persisted query is a ID or hash that can be sent to the server instead of the entire GraphQL query string. This smaller signature reduces bandwidth utilization and speeds up client loading times.

		To accommodate this new query representation, Apollo Server contains a cache that stores the mapping between hash and query string, efficiently retrieving the corresponding query. Previously, the generation of mapping would require a complex build step. Paired with Apollo Client, Apollo Server provides the ability to generate this mapping automatically.


		> Note: using `apollo-link-persisted-query` requires migrating from [apollo-boost](https://www.apollographql.com/docs/react/advanced/boost-migration.html):

		Inside Apollo Server, the query registry is stored in a user-configurable cache. By default, Apollo Server uses a in-memory cache (shared with other caching features). Read more here about [how to configure caching](caching.html).


		The size of individual GraphQL query strings can be a major pain point. Apollo Server allows implements Automatic Persisted Queries (APQ), a technique that greatly improves network performance for GraphQL with zero build-time configuration. A persisted query is a ID or hash that can be sent to the server instead of the entire GraphQL query string. This smaller signature reduces bandwidth utilization and speeds up client loading times. Persisted queries are especially nice paired with GET requests, enabling the browser cache and [integration with a CDN](#get).

		To accommodate the new query representation, Apollo Server contains a cache that stores the mapping between hash and query string. Previously, the generation of mapping would require a complex build step. Apollo Server paired with Apollo Client provides the ability to generate the mapping automatically.

Apollo Server 2:Automatic Persisted Queries + KeyValueCache Interface #1149

Apollo Server 2:Automatic Persisted Queries + KeyValueCache Interface #1149

Conversation

evans commented Jun 7, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

glasser left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

evans commented Jun 7, 2018 •

edited

Loading