HTTP Transport Cache

A HTTP spec compliant caching layer for http-transport.

Installation

pnpm install --save http-transport-cache

Usage

Configure response caching based on max-age:

const cache = require('@bbc/http-transport-cache');
const Catbox = require('@hapi/catbox');
const HttpTransport = require('@bbc/http-transport');

const catbox = new Catbox.Client(new Memory());

const url = 'http://example.com/';

const client = HttpTransport.createBuilder()
      .use(cache.maxAge(catbox))
      .createClient();

      const body = await client.get(url)
        .asBody();

      console.log(body);

Configure stale-if-error:

const cache = require('@bbc/http-transport-cache');
const Catbox = require('catbox');
const HttpTransport = require('@bbc/http-transport');

const catbox = new Catbox.Client(new Memory());

const url = 'http://example.com/';

const client = HttpTransport.createClient()
      .use(cache.staleIfError(catbox))
      .createClient();

      const body = await client.get(url)
        .asBody();

      console.log(body);

Listening to Events:

const { events, maxAge } = require('@bbc/http-transport-cache');

const stats = require('@ibl/stats');
const Catbox = require('catbox');
const HttpTransport = require('@bbc/http-transport');

const catbox = new Catbox.Client(new Memory());

const url = 'http://example.com/';

const client = HttpTransport.createBuilder()
  .use(cache.maxAge(catbox, {
    name: `theservice`,
  }))
  .createClient();

events.on(`cache.theservice.read_time`, (ctx) => {
  stats.timing(`timingstat.read_time`, ctx.duration);
});

Features

Events

• hit
• miss
• error
• timeout
• stale
• read_time
• write_time
• connection_error

Middleware Options

Both maxage and staleIfError accept an options object.

Cache version

The cache verison is stored in the config.json, this is distinct from the library version in the package.json. The cache version is used in the cache key and is intended to reduce cache fragmentation in a scenario where multiple different versions of this library might be in use across a single estate.

The cache version must be incremented if a change is made to the data stored in the cache that would be incompatible with the existing version. Otherwise it should not be changed.

Cache Key Structure

The cache uses catbox to provide a simple pluggable interface, this supports segmenting the cache as well as IDs, thus the following segments are used:

• http-transport:{version}:response - Basic response from a call cached for the duration of the max-age value key on just the URL of the response.
• http-transport:{version}:staleResponse - Stale response from a called cached for the stale-if-error value keyed on just the URL of the response.

Additionally, cache keys can be configured by passing a varyOn option. varyOn should contain an array of request header names which the cache should additionally vary on; for some use-cases, requests made to the same endpoint but with differing values for certain headers elicit different responses - and therefore cannot share the same cached response e.g.accept-language. By letting http-transport-cache know which headers to vary on, a unique cache key will be constructed which also contains said headers and their values.

Example:

We make a GET request to the following URL: www.example.com/some-cacheable-path.

We vary on accept-language and accept. These headers will exist in the request. We pass in varyOn (an array of request headers we vary on) together with other options to configure the plugin.

const opts = {
  timeout: 2000,
  varyOn: [
    'accept-language',
    'accept'
  ]
};

On the first request, the value of accept-language is en and accept is application/json. The resulting key will be:

• GET:www.example.com/some-cacheable-path:accept-language=en,accept=application/json

On the second request, the value of accept-language is fr and accept is text/html. The resulting key will be:

• GET:www.example.com/some-cacheable-path:accept-language=fr,accept=text/html

This way we avoid overwritting data in the store.

Test

pnpm test

To generate a test coverage report:

pnpm run coverage