feat: Add usage of the axios cache adapter as a means to have client caching (#119)

Co-authored-by: Kellie Selinka <> and Adam Stankiewicz <astankiewicz@edx.org>

Author: kellmarie

docs/how_tos/caching.rst

@@ -0,0 +1,74 @@
+############################
+How to: Caching API Requests
+############################
+
+.. contents:: Table of Contents
+
+Introduction
+************
+
+Often, a web application needs to make the same repeated API calls, where the data returned is mostly static (i.e., does not change often). In such situations, caching is a viable solution to prevent unnecessary and potentially expensive operations, resulting in increased performance and a better user experience.
+
+When considering caching options, there's a few approaches to consider:
+
+Server caching
+==============
+
+Server caching helps to limit the cost of an API request on the server and its dependent systems. When a client makes a request to the API, the server will check for a local copy of the requested resource. If the local resource exists, the server will respond with it; otherwise, the request is processed normally (e.g., performing database lookups). With this approach, the cost savings to the server may be significant, utilizing less resources.
+
+Client caching
+==============
+
+Client caching helps to limit the cost of an API request incurred by the user. Rather than relying on a API implementing server caching, commonly referenced data may be cached locally within the client (i.e., browser). Similar to server caching, on the first request of an API, the request will occur as usual but the response data will be stored in the client.
+
+However, on subsequent requests (within a given timeframe), the client will check if a copy of the requested resource exists. If it does, it will read from the client cache rather than making a network request to the API. This has the benefit of freeing up resources on the server as it no longer needs to handle repeat queries within a given timeframe.
+
+Typically, client caching stores data for a given time (e.g., 5 minutes) since it was last requested. This allows the client cache to be dynamic in the sense that data will be eventually consistent and unneeded local data can be cleared once it is no longer relevant.
+
+Hybrid caching
+==============
+
+Both server and client caching can be combined to provide best of both worlds. Regardless of how an API request is made, utilizing a hybrid approach will ensure data is read from a local cache first, whether that be on the server or the client.
+
+How do I use client caching with ``@edx/frontend-platform?``
+************************************************************
+
+The ``@edx/frontend-platform`` package supports an Axios HTTP client that uses client caching under the hood through the use of `axios-cache-adapter <https://www.npmjs.com/package/axios-cache-adapter>`_. 
+
+``axios-cache-adapter`` is configured to use `localForage <https://www.npmjs.com/package/localforage>`_ as its store; ``localForage`` is a package that provides a similar API to browser's localStorage, except is asynchronous (non-blocking). ``localForage`` is configured to prefer using IndexedDB, falling back to localStorage if browser support for IndexedDB is lacking. If all else fails, an in-memory store is used instead. IndexedDB is more performant and may contain a broader range (and volume) of data in comparison to localStorage (see `browser support <https://caniuse.com/indexeddb>`_ for IndexedDB).
+
+When importing an HTTP client from ``@edx/frontend-platform``, you may specify options for how you wish to configure the HTTP client::
+
+  import { getAuthenticatedHttpClient } from '@edx/frontend-platform';
+  
+  // ``cachedHttpClient`` is configured to use client caching under the hood.
+  const cachedHttpClient = getAuthenticatedHttpClient({ useCache: true });
+  
+The examples below demonstrate how to configure the caching behavior on a per-request basis. For more details about how to configure the caching behavior, you may refer to the `axios-cache-adapter documentation <https://www.npmjs.com/package/axios-cache-adapter>`_.
+  
+Modify expiry behavior for a single request
+===========================================
+
+By default, API requests using the cached HTTP client will be cached for 5 minutes. However, cache options may be configured on a per-request basis::
+
+  cachedHttpClient.get('/courses/', {
+    cache: {
+      maxAge: 15 * 60 * 1000, // 15 minutes instead of the default 5.
+    },
+  });
+  
+Invalidate cache for a single request
+=====================================
+
+In certain situations, it may be necessary to invalidate cached data to force a true network request to the server::
+
+  cachedHttpClient.get('/courses/', { clearCacheEntry: true });
+  
+Check if response is served from network or from cache
+======================================================
+
+If there is a need to know whether a response was served from the network (i.e., server) or from the local client cache, you may refer to the ``response.request`` object::
+
+  cachedHttpClient.get('/courses/').then((response) => {
+    console.log(response.request.fromCache); // will be true if served from the client cache
+  });

package-lock.json

@@ -35,7 +35,7 @@
     "@commitlint/config-angular": "8.2.0",
     "@edx/frontend-build": "5.3.2",
     "@edx/paragon": "7.1.5",
-    "axios-mock-adapter": "1.17.0",
+    "axios-mock-adapter": "1.19.0",
     "babel-polyfill": "6.26.0",
     "codecov": "3.7.2",
     "enzyme": "3.10.0",
@@ -53,11 +53,14 @@
   "dependencies": {
     "@cospired/i18n-iso-languages": "2.1.2",
     "axios": "0.18.1",
+    "axios-cache-adapter": "^2.5.0",
     "form-urlencoded": "4.1.4",
     "glob": "7.1.6",
     "history": "4.10.1",
     "i18n-iso-countries": "4.3.1",
     "jwt-decode": "2.2.0",
+    "localforage": "^1.9.0",
+    "localforage-memoryStorageDriver": "^0.9.2",
     "lodash.camelcase": "4.3.0",
     "lodash.memoize": "4.1.2",
     "lodash.merge": "4.6.2",

package.json

@@ -7,6 +7,7 @@ import createCsrfTokenProviderInterceptor from './interceptors/createCsrfTokenPr
 import createProcessAxiosRequestErrorInterceptor from './interceptors/createProcessAxiosRequestErrorInterceptor';
 import AxiosJwtTokenService from './AxiosJwtTokenService';
 import AxiosCsrfTokenService from './AxiosCsrfTokenService';
+import configureCache from './LocalForageCache';
 
 const optionsPropTypes = {
   config: PropTypes.shape({
@@ -44,6 +45,8 @@ class AxiosJwtAuthService {
   constructor(options) {
     this.authenticatedHttpClient = null;
     this.httpClient = null;
+    this.cachedAuthenticatedHttpClient = null;
+    this.cachedHttpClient = null;
     this.authenticatedUser = null;
 
     ensureDefinedConfig(options, 'AuthService');
@@ -59,24 +62,48 @@ class AxiosJwtAuthService {
     this.csrfTokenService = new AxiosCsrfTokenService(this.config.CSRF_TOKEN_API_PATH);
     this.authenticatedHttpClient = this.addAuthenticationToHttpClient(axios.create());
     this.httpClient = axios.create();
+    configureCache()
+      .then((cachedAxiosClient) => {
+        this.cachedAuthenticatedHttpClient = this.addAuthenticationToHttpClient(cachedAxiosClient);
+        this.cachedHttpClient = cachedAxiosClient;
+      })
+      .catch((e) => {
+        // fallback to non-cached HTTP clients and log error
+        this.cachedAuthenticatedHttpClient = this.authenticatedHttpClient;
+        this.cachedHttpClient = this.httpClient;
+        logFrontendAuthError(this.loggingService, `configureCache failed with error: ${e.message}`);
+      });
   }
 
   /**
    * Gets the authenticated HTTP client for the service.  This is an axios instance.
    *
+   * @param {Object} [options] Optional options for how the HTTP client should be configured.
+   * @param {boolean} [options.useCache] Whether to use front end caching for all requests made
+   * with the returned client.
+   *
    * @returns {HttpClient} A configured axios http client which can be used for authenticated
    * requests.
    */
-  getAuthenticatedHttpClient() {
+  getAuthenticatedHttpClient(options = {}) {
+    if (options.useCache) {
+      return this.cachedAuthenticatedHttpClient;
+    }
     return this.authenticatedHttpClient;
   }
 
   /**
    * Gets the unauthenticated HTTP client for the service.  This is an axios instance.
    *
+   * @param {Object} [options] Optional options for how the HTTP client should be configured.
+   * @param {boolean} [options.useCache] Whether to use front end caching for all requests made
+   * with the returned client.
    * @returns {HttpClient} A configured axios http client.
    */
-  getHttpClient() {
+  getHttpClient(options = {}) {
+    if (options.useCache) {
+      return this.cachedHttpClient;
+    }
     return this.httpClient;
   }