feat(express): add key generator

should close #9

Author: ecyrbe

README.md

@@ -21,11 +21,12 @@
  </p>
 
 Stalier is cache strategy middleware controled by your frontend by using `x-stalier-cache-control` header.  
-It is an advanced middleware that can be used to cache your backend responses with support for stale-while-revalidate strategy.  
-Stalier will act as a proxy to your routes and cache the response if front-end asks for it.  
+This means that instead of your backend sending `Cache-Control` header to your browser for your browser to cache the returned data, your frontend will send the header `X-Stalier-Cache-Control` to your backend for it to cache the returned data from your source of truth.
+It is an advanced middleware that with support for stale-while-revalidate strategy.  
+Stalier will act as a proxy for your routes and cache the response if front-end asks for it.  
 Since it's embedded in your backend, it's much more efficient than using a separate proxy.  
-It implements part of RFC7234 and RFC5861 but on the backend. It does not use `cache-control` header to not allow the browser to interfere with it.  
-If you want both your browser to cache the response the response and if not present cache on the backend, you can use `x-stalier-cache-control` and `cache-control` headers at the same time.
+It implements part of RFC7234 and RFC5861 but on the backend. It does not use `cache-control` since the cache is controlled by the frontend.
+If you want both your browser and backend to cache the responses, you can use `x-stalier-cache-control` for requests and `cache-control` for responses at the same time.
 
 ## INSTALL
 
@@ -58,6 +59,34 @@ const app = express();
 app.use(stalier({ cachePrefix: 'test', cacheClient: redisCache }));
 ```
 
+## Stalier Options
+
+```typescript
+type StalierMiddlewareOptions = {
+  /**
+   * name of the upstream application
+   */
+  appName: string;
+  /**
+   * client to use for caching
+   * should have an async `get` method and `set` method
+   */
+  cacheClient: CacheClient;
+  /**
+   * function to generate a cache key per request
+   * Use a custom one to handle per user caching
+   * @default `<appName>-<HTTP Verb>-<path>`
+   */
+  cacheKeyGen?: (req: Request) => string;
+  /**
+   * logger to use for logging
+   * should have a log, warn and error method that takes a message parameter
+   * @default `console`
+   */
+  logger?: Logger;
+};
+```
+
 ## Header `x-stalier-cache-control` params
 
 Stalier is using the `x-stalier-cache-control` header to control the cache behaviour.

src/express.spec.ts

@@ -17,7 +17,7 @@ describe('stalier-express', () => {
 
   beforeAll(() => {
     app = express();
-    app.use(stalier({ cachePrefix: 'test', cacheClient: fakeCache }));
+    app.use(stalier({ appName: 'test', cacheClient: fakeCache }));
     app.get('/string', async (req, res) => {
       await new Promise(resolve => setTimeout(resolve, Math.floor(Math.random() * 100)));
       res.send('hello');

src/express.ts

@@ -1,4 +1,4 @@
-import type { RequestHandler } from 'express';
+import type { RequestHandler, Request } from 'express';
 import type { OutgoingHttpHeaders } from 'http';
 import { withStaleWhileRevalidate } from './stalier';
 import { StalierOptions } from './stalier.types';
@@ -8,71 +8,97 @@ export const STALIER_HEADER_KEY = 'X-Stalier-Cache-Control';
 const MATCH_HEADER = /s-maxage=([0-9]+)(\s*,\s*(stale-while-revalidate=([0-9]+)))?/;
 
 export type StalierMiddlewareOptions = {
-  cachePrefix: string;
+  /**
+   * name of the upstream application
+   */
+  appName: string;
+  /**
+   * client to use for caching
+   */
   cacheClient: StalierOptions['cacheClient'];
+  /**
+   * function to generate a cache key per request
+   * Use a custom one to handle per user caching
+   * @default `<appName>-<HTTP Verb>-<path>`
+   */
+  cacheKeyGen?: (req: Request) => string;
+  /**
+   * logger to use for logging
+   * @default `console`
+   */
   logger?: StalierOptions['logger'];
 };
 
-export const stalier: (options: StalierMiddlewareOptions) => RequestHandler =
-  ({ cachePrefix, cacheClient, logger = console }) =>
-  (req, res, next) => {
-    const options = req.get(STALIER_HEADER_KEY);
-    if (options) {
-      const matched = options.match(MATCH_HEADER);
-      if (matched) {
-        const maxAge = parseInt(matched[1]);
-        const staleWhileRevalidate = matched[4] ? parseInt(matched[4]) : 0;
-        const send = res.send.bind(res);
-        const freshResult = new Promise<{ data: Buffer | string; statusCode: number; headers: OutgoingHttpHeaders }>(
-          (resolve, reject) => {
-            res.send = function (data) {
-              if (this.statusCode >= 200 && this.statusCode <= 300) {
-                resolve({ data, statusCode: this.statusCode, headers: this.getHeaders() });
-              } else {
-                reject({ data, statusCode: this.statusCode, headers: this.getHeaders() });
-              }
-              return this;
-            };
-          },
-        );
-        const result = withStaleWhileRevalidate(
-          () => {
-            next();
-            return freshResult;
-          },
-          {
-            maxAge,
-            staleWhileRevalidate,
-            cacheKey: `${cachePrefix}-${req.method}-${req.originalUrl}`,
-            cacheClient,
-            logger,
-          },
-        );
-        return result
-          .then(({ data, status }) => {
-            res.status(data.statusCode);
-            if (data.headers) {
-              res.set(data.headers);
-            }
-            res.set('X-Cache-Status', status);
-            send(data.data);
-          })
-          .catch(reason => {
-            if (reason.data && reason.statusCode) {
-              res.status(reason.statusCode);
-              if (reason.headers) {
-                res.set(reason.headers);
-              }
-              res.set('X-Cache-Status', 'NO_CACHE');
-              send(reason.data);
+/**
+ * default cache key generator
+ */
+const defaultKeyGenerator = (name: string) => (req: Request) => {
+  return `${name}-${req.method}-${req.originalUrl}`;
+};
+
+/**
+ * middleware to cache responses
+ * @param options - options for stalier
+ */
+export const stalier: (options: StalierMiddlewareOptions) => RequestHandler = options => (req, res, next) => {
+  const { cacheClient, cacheKeyGen = defaultKeyGenerator(options.appName), logger = console } = options;
+  const cacheControl = req.get(STALIER_HEADER_KEY);
+  if (cacheControl) {
+    const matched = cacheControl.match(MATCH_HEADER);
+    if (matched) {
+      const maxAge = parseInt(matched[1]);
+      const staleWhileRevalidate = matched[4] ? parseInt(matched[4]) : 0;
+      const send = res.send.bind(res);
+      const freshResult = new Promise<{ data: Buffer | string; statusCode: number; headers: OutgoingHttpHeaders }>(
+        (resolve, reject) => {
+          res.send = function (data) {
+            if (this.statusCode >= 200 && this.statusCode <= 300) {
+              resolve({ data, statusCode: this.statusCode, headers: this.getHeaders() });
             } else {
-              res.status(500);
-              res.set('X-Cache-Status', 'NO_CACHE');
-              send(JSON.stringify({ error: 'Unexpected error' }));
+              reject({ data, statusCode: this.statusCode, headers: this.getHeaders() });
             }
-          });
-      }
+            return this;
+          };
+        },
+      );
+      const result = withStaleWhileRevalidate(
+        () => {
+          next();
+          return freshResult;
+        },
+        {
+          maxAge,
+          staleWhileRevalidate,
+          cacheKey: cacheKeyGen(req),
+          cacheClient,
+          logger,
+        },
+      );
+      return result
+        .then(({ data, status }) => {
+          res.status(data.statusCode);
+          if (data.headers) {
+            res.set(data.headers);
+          }
+          res.set('X-Cache-Status', status);
+          send(data.data);
+        })
+        .catch(reason => {
+          if (reason.data && reason.statusCode) {
+            res.status(reason.statusCode);
+            if (reason.headers) {
+              res.set(reason.headers);
+            }
+            res.set('X-Cache-Status', 'NO_CACHE');
+            send(reason.data);
+          } else {
+            res.status(500);
+            res.set('X-Cache-Status', 'NO_CACHE');
+            send(JSON.stringify({ error: 'unexpected error while processing cache' }));
+          }
+        });
     }
-    res.set('X-Cache-Status', 'NO_CACHE');
-    next();
-  };
+  }
+  res.set('X-Cache-Status', 'NO_CACHE');
+  next();
+};