Add caching for Algolia calls (#77)

* Add caching for Algolia

* Add namespace id for staging

* Add tests for writing to and reading from KV

* 'shell script' code blocks -> 'sh'

* Readme copy tweaks

* Extract bufToHex method

* Add production KV namespace

Author: MattIPv4

README.md

@@ -16,20 +16,31 @@ Looking for the documentation on our API?
 
 This project uses [Node.js](https://nodejs.org) for development, and is deployed as a
 [Cloudflare Worker](https://workers.cloudflare.com/). Please make sure you have a Node.js version
-installed that matches our defined requirement in the [.nvmrc](.nvmrc) file for this project.
+installed that matches our defined requirement in the [`.nvmrc`](.nvmrc) file for this project.
 
 Included with this project is a dependency lock file. This is used to ensure that all installations
 of the project are using the same version of dependencies for consistency. You can install the
 dependencies following this lock file by running:
 
-```shell script
+```sh
 npm ci
 ```
 
-Once the dependencies are installed, which includes the Wrangler CLI for Cloudflare Workers, the API
-server is ready to run in development mode. To start the server in development mode, run:
+Once the dependencies are installed, which includes the Wrangler CLI for Cloudflare Workers, you
+need to create the KV namespace for data caching before the API can be run. This command will ask
+you to authenticate with a Cloudflare account, so that the Workers KV namespace can be created:
 
-```shell script
+```sh
+wrangler kv:namespace create CACHE --preview
+```
+
+Copy the new `preview_id` returned by the command and replace the existing `preview_id` in
+[`wrangler.toml`](wrangler.toml).
+
+With the KV namespace setup, the API server is now ready to run in development mode. To start the
+server in development mode, run:
+
+```sh
 npm run dev
 ```
 
@@ -41,7 +52,7 @@ deployed in a development context to Cloudflare's Workers runtime.
 Our full set of tests (linting & a mocha+chai test suite using Miniflare to run the worker locally)
 can be run at any time with:
 
-```shell script
+```sh
 npm test
 ```
 
@@ -54,20 +65,20 @@ API server.
 To help enforce this, we use both eslint and echint in our testing. To run eslint at any time, which
 checks the code style of any JavaScript, you can use:
 
-```shell script
+```sh
 npm run test:eslint
 ```
 
 eslint also provides automatic fixing capabilities, these can be run against the codebase with:
 
-```shell script
+```sh
 npm run test:eslint:fix
 ```
 
 The more generic rules defined in the [editorconfig file](.editorconfig) apply to all files in the
 repository and this is enforced by echint, which can be run at any time with:
 
-```shell script
+```sh
 npm run test:echint
 ```
 
@@ -81,7 +92,7 @@ this is perfect, a human should always review changes!
 The mocha test suite can be run at any time with the following command (it will build the worker
 using Wrangler, and then run it with Miniflare during the Mocha+Chai test suite):
 
-```shell script
+```sh
 npm run test:mocha
 ```
 
@@ -108,6 +119,15 @@ deploying to staging (api.cdnjs.dev) and production (api.cdnjs.com) based on com
 staging/production branches, automatically handling not only deploying the worker but also creating
 a Sentry release with full source maps.
 
+Before deploying, ensure that you generate the required KV namespace for the environment you are
+deploying to and update [`wrangler.toml`](wrangler.toml) to use the correct ID:
+
+```sh
+wrangler kv:namespace create CACHE --env=staging
+# or
+wrangler kv:namespace create CACHE --env=production
+```
+
 To deploy to staging (assuming you have write access to this repository), run `make deploy-staging`.
 This will force-push your latest local commit to the staging branch, which will trigger GitHub
 Actions to run and deploy your worker to Cloudflare Workers.

src/routes/libraries.js

@@ -1,3 +1,5 @@
+/* global CACHE */
+
 import algolia from '../utils/algolia.js';
 import cache from '../utils/cache.js';
 import filter from '../utils/filter.js';
@@ -9,6 +11,14 @@ const validSearchFields = [ 'name', 'alternativeNames', 'github.repo', 'descript
     'repositories.url', 'github.user', 'maintainers.name' ];
 const maxQueryLength = 512;
 
+/**
+ * Convert an ArrayBuffer to a hex string.
+ *
+ * @param {ArrayBuffer} buf Buffer to convert.
+ * @return {string}
+ */
+const bufToHex = buf => Array.from(new Uint8Array(buf)).map(b => b.toString(16).padStart(2, '0')).join('');
+
 /**
  * Browse an Algolia index to get all objects matching a query.
  *
@@ -17,10 +27,22 @@ const maxQueryLength = 512;
  * @return {Promise<Object[]>}
  */
 const browse = async (query, searchFields) => {
+    // Normalize the search fields
+    const fields = searchFields.filter(field => validSearchFields.includes(field)).sort();
+
+    // Check if there is a cached result for this query
+    const cacheKey = await crypto.subtle.digest(
+        { name: 'SHA-512' },
+        new TextEncoder().encode(`${query}:${fields.join(',')}`),
+    ).then(buf => `libraries:${bufToHex(buf)}`);
+    const cached = await CACHE.get(cacheKey, { type: 'json' });
+    if (cached) return cached;
+
+    // Fetch the results from Algolia
     const hits = [];
     await index.browseObjects({
         query,
-        restrictSearchableAttributes: searchFields.filter(field => validSearchFields.includes(field)),
+        restrictSearchableAttributes: fields,
         /**
          * Store an incoming batch of hits.
          *
@@ -32,6 +54,9 @@ const browse = async (query, searchFields) => {
     }).catch(err => {
         throw err instanceof Error ? err : new Error(`${err.name}: ${err.message}`);
     });
+
+    // Cache the results for 15 minutes
+    await CACHE.put(cacheKey, JSON.stringify(hits), { expirationTtl: 60 * 15 });
     return hits;
 };
 

src/routes/libraries.spec.js

@@ -1,3 +1,5 @@
+import { createHash } from 'crypto';
+
 import { expect } from 'chai';
 import { describe, it, before } from 'mocha';
 
@@ -597,4 +599,83 @@ describe('/libraries', () => {
             });
         });
     });
+
+    describe('Caching Algolia data with KV', () => {
+        it('writes the results from Algolia to KV', async () => {
+            await request('/libraries', {}, undefined, async mf => {
+                // Check that the results were stored under the `:` key (no query, no fields)
+                const cache = await mf.getKVNamespace('CACHE');
+                const key = `libraries:${createHash('sha512').update(':').digest('hex')}`;
+                const { keys } = await cache.list();
+                expect(keys).to.be.an('array');
+                expect(keys).to.have.lengthOf(1);
+                expect(keys[0].name).to.equal(key);
+                expect(await cache.get(key, { type: 'json' })).to.be.an('array');
+            });
+        });
+
+        it('reuses existing Algolia values from KV', async () => {
+            const response = await request('/libraries', {}, async mf => {
+                // Create a stub set of Algolia results under the `:` key (no query, no fields)
+                const cache = await mf.getKVNamespace('CACHE');
+                const key = `libraries:${createHash('sha512').update(':').digest('hex')}`;
+                await cache.put(key, JSON.stringify([ { name: 'testing' } ]));
+            });
+
+            // Check the response was generated from KV
+            expect(response).to.be.json;
+            expect(response.body).to.have.property('results').that.is.an('array');
+            expect(response.body.results).to.have.lengthOf(1);
+            expect(response.body.results[0]).to.have.property('name').that.is.a('string');
+            expect(response.body.results[0].name).to.equal('testing');
+        });
+
+        it('reuses the same KV cache no matter the query parameter order', async () => {
+            const key = `libraries:${createHash('sha512').update('test:name').digest('hex')}`;
+
+            // Run the request with the `name` parameter first, check consistent key was used
+            await request('/libraries?search=test&search_fields=name', {}, undefined, async mf => {
+                const cache = await mf.getKVNamespace('CACHE');
+                const { keys } = await cache.list();
+                expect(keys).to.be.an('array');
+                expect(keys).to.have.lengthOf(1);
+                expect(keys[0].name).to.equal(key);
+                expect(await cache.get(key, { type: 'json' })).to.be.an('array');
+            });
+
+            // Run the request with the `search_fields` parameter first, check consistent key was used
+            await request('/libraries?search_fields=name&search=test', {}, undefined, async mf => {
+                const cache = await mf.getKVNamespace('CACHE');
+                const { keys } = await cache.list();
+                expect(keys).to.be.an('array');
+                expect(keys).to.have.lengthOf(1);
+                expect(keys[0].name).to.equal(key);
+                expect(await cache.get(key, { type: 'json' })).to.be.an('array');
+            });
+        });
+
+        it('reuses the same KV cache no matter the search fields order', async () => {
+            const key = `libraries:${createHash('sha512').update('test:keywords,name').digest('hex')}`;
+
+            // Run the request with the `name` search field first, check consistent key was used
+            await request('/libraries?search=test&search_fields=name,keywords', {}, undefined, async mf => {
+                const cache = await mf.getKVNamespace('CACHE');
+                const { keys } = await cache.list();
+                expect(keys).to.be.an('array');
+                expect(keys).to.have.lengthOf(1);
+                expect(keys[0].name).to.equal(key);
+                expect(await cache.get(key, { type: 'json' })).to.be.an('array');
+            });
+
+            // Run the request with the `keywords` search field first, check consistent key was used
+            await request('/libraries?search=test&search_fields=keywords,name', {}, undefined, async mf => {
+                const cache = await mf.getKVNamespace('CACHE');
+                const { keys } = await cache.list();
+                expect(keys).to.be.an('array');
+                expect(keys).to.have.lengthOf(1);
+                expect(keys[0].name).to.equal(key);
+                expect(await cache.get(key, { type: 'json' })).to.be.an('array');
+            });
+        });
+    });
 });

src/utils/spec/request.js

@@ -15,9 +15,11 @@ import { Miniflare, Request } from 'miniflare';
  *
  * @param {string} route Route to request in API via Miniflare.
  * @param {RequestInit} [opts={}] Options to set for fetch request.
- * @return {ExtendedResponse}
+ * @param {function(Miniflare, Request): (Promise<void>|void)} [preHook] Hook to run before the request is sent.
+ * @param {function(Miniflare, Request, ExtendedResponse): (Promise<void>|void)} [postHook] Hook to run after the response is received.
+ * @return {Promise<ExtendedResponse>}
  */
-export default (route, opts = {}) => {
+export default async (route, opts = {}, preHook = undefined, postHook = undefined) => {
     // Create the Miniflare instance
     const mf = new Miniflare({
         scriptPath: fileURLToPath(new URL('../../../dist-worker/index.js', import.meta.url)),
@@ -29,6 +31,9 @@ export default (route, opts = {}) => {
     // Create a full request
     const req = new Request(`http://localhost:5050${route}`, opts);
 
+    // Run the pre-hook if defined
+    if (typeof preHook === 'function') await preHook(mf, req);
+
     // Send the request to Miniflare
     return mf.dispatchFetch(req).then(async resp => {
         // Patch in some extras for chai-http
@@ -55,6 +60,9 @@ export default (route, opts = {}) => {
         if (/[/+]json($|[^-\w])/i.test(resp.headers.get('content-type')?.toLowerCase()))
             Reflect.defineProperty(resp, 'body', { value: JSON.parse(text) });
 
+        // Run the post-hook if defined
+        if (typeof postHook === 'function') await postHook(mf, req, resp);
+
         return resp;
     });
 };

wrangler.toml

@@ -1,6 +1,9 @@
 name = "cdnjs-api-worker"
 main = "src/index.js"
 compatibility_date = "2022-05-20"
+kv_namespaces = [
+    { binding = "CACHE", id = "", preview_id = "845ae1599dcf4d75950b61201a951b73" }
+]
 
 [vars]
 DISABLE_CACHING = false
@@ -11,6 +14,9 @@ SENTRY_ENVIRONMENT = "development"
 
 [env.staging]
 route = "api.cdnjs.dev/*"
+kv_namespaces = [
+    { binding = "CACHE", id = "34b159dab6f840ce9c17e4d0730ead12" }
+]
 
 [env.staging.vars]
 DISABLE_CACHING = false
@@ -21,6 +27,9 @@ SENTRY_ENVIRONMENT = "staging"
 
 [env.production]
 route = "api.cdnjs.com/*"
+kv_namespaces = [
+    { binding = "CACHE", id = "c2922fcf1af643658d6769859b913134" }
+]
 
 [env.production.vars]
 DISABLE_CACHING = false