@openstax/ts-utils 1.33.1 → 1.34.0

package/packages/utils/src/middleware/apiSlowResponseMiddleware.spec.ts

@@ -0,0 +1,184 @@
+import { NotFoundError } from '../errors';
+import { ApiResponse, apiTextResponse } from '../routing';
+import { createCoreLogger, Level, LogEvent, Logger } from '../services/logger';
+import { createSlowResponseMiddleware } from './apiSlowResponseMiddleware';
+
+const insideOutPromise = <T>() => {
+  let resolve: (value: T | PromiseLike<T>) => void = () => null;
+  let reject: (reason?: any) => void = () => null;
+
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+
+  return {resolve, reject, promise};
+};
+
+describe('createSlowResponseMiddleware', () => {
+  let logger: Logger;
+  let logFn: jest.SpyInstance;
+  let timeoutSpy: jest.SpyInstance;
+  let clearTimeoutSpy: jest.SpyInstance;
+  let nowSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    logFn = jest.fn();
+    logger = createCoreLogger(logFn as any as LogEvent);
+    timeoutSpy = jest.spyOn(global, 'setTimeout').mockImplementation(() => 7 as any);
+    clearTimeoutSpy = jest.spyOn(global, 'clearTimeout').mockImplementation(() => null);
+    nowSpy = jest.spyOn(Date, 'now');
+  });
+
+  afterEach(() => {
+    timeoutSpy.mockReset();
+    clearTimeoutSpy.mockReset();
+    nowSpy.mockReset();
+  });
+
+  it('does nothing when response is undefined', () => {
+    expect(createSlowResponseMiddleware({
+      logResponseSlowerThan: '1000',
+      timeoutResponseAfter: '5000'
+    })()(undefined, {logger})).toBeUndefined();
+    expect(logFn).not.toHaveBeenCalled();
+    expect(timeoutSpy).not.toHaveBeenCalled();
+    expect(clearTimeoutSpy).not.toHaveBeenCalled();
+  });
+
+  it('works without a timeout', () => {
+    expect(createSlowResponseMiddleware({
+      logResponseSlowerThan: '1000',
+      timeoutResponseAfter: ''
+    })()(undefined, {logger})).toBeUndefined();
+    expect(logFn).not.toHaveBeenCalled();
+    expect(timeoutSpy).not.toHaveBeenCalled();
+    expect(clearTimeoutSpy).not.toHaveBeenCalled();
+  });
+
+  it('returns response with no timeout', async() => {
+    const {resolve, promise} = insideOutPromise<ApiResponse<number, string>>();
+
+    const result = createSlowResponseMiddleware({
+      logResponseSlowerThan: '1000',
+      timeoutResponseAfter: ''
+    })()(promise, {logger});
+
+    const response = apiTextResponse(200, 'done');
+    resolve(response);
+
+    expect(await result).toBe(response);
+    expect(logFn).not.toHaveBeenCalled();
+    expect(timeoutSpy).not.toHaveBeenCalled();
+    expect(clearTimeoutSpy).not.toHaveBeenCalled();
+  });
+
+  it('logs slow response with no timeout', async() => {
+    const {resolve, promise} = insideOutPromise<ApiResponse<number, string>>();
+    nowSpy.mockReturnValue(10000);
+
+    const result = createSlowResponseMiddleware({
+      logResponseSlowerThan: '1000',
+      timeoutResponseAfter: ''
+    })()(promise, {logger});
+
+    nowSpy.mockReturnValue(12000);
+    const response = apiTextResponse(200, 'done');
+    resolve(response);
+
+    expect(await result).toBe(response);
+    expect(logFn).toHaveBeenCalledWith(Level.Warn, {context: {}, message: 'slow response', time: 2000});
+    expect(timeoutSpy).not.toHaveBeenCalled();
+    expect(clearTimeoutSpy).not.toHaveBeenCalled();
+  });
+
+  it('logs slow response with timeout', async() => {
+    const {resolve, promise} = insideOutPromise<ApiResponse<number, string>>();
+    nowSpy.mockReturnValue(10000);
+    timeoutSpy.mockReturnValue(10);
+
+    const result = createSlowResponseMiddleware({
+      logResponseSlowerThan: '1000',
+      timeoutResponseAfter: '5000'
+    })()(promise, {logger});
+
+    nowSpy.mockReturnValue(12000);
+    const response = apiTextResponse(200, 'done');
+    resolve(response);
+
+    expect(await result).toBe(response);
+    expect(logFn).toHaveBeenCalledWith(Level.Warn, {context: {}, message: 'slow response', time: 2000});
+    expect(timeoutSpy).toHaveBeenCalledTimes(1);
+    expect(timeoutSpy).toHaveBeenCalledWith(expect.anything(), 5000);
+    expect(clearTimeoutSpy).toHaveBeenCalledTimes(1);
+    expect(clearTimeoutSpy).toHaveBeenCalledWith(10);
+  });
+
+  it('returns timeout', async() => {
+    const {promise} = insideOutPromise<ApiResponse<number, string>>();
+
+    const result = createSlowResponseMiddleware({
+      logResponseSlowerThan: '1000',
+      timeoutResponseAfter: '5000'
+    })()(promise, {logger});
+
+
+    // clear config loading
+    await new Promise(setImmediate);
+
+    expect(timeoutSpy).toHaveBeenCalledTimes(1);
+    expect(timeoutSpy).toHaveBeenCalledWith(expect.anything(), 5000);
+
+    expect(clearTimeoutSpy).not.toHaveBeenCalled();
+    timeoutSpy.mock.calls[0][0]();
+
+    expect(await result).toEqual(apiTextResponse(504, '504 Gateway Timeout'));
+    expect(logFn).toHaveBeenCalledWith(Level.Error, {context: {}, message: 'request processing timed out'});
+  });
+
+  it('does not log a timeout when the response promise resolves in time', async() => {
+    const {resolve, promise} = insideOutPromise<ApiResponse<number, string>>();
+
+    const result = createSlowResponseMiddleware({
+      logResponseSlowerThan: '1000',
+      timeoutResponseAfter: '5000'
+    })()(promise, {logger});
+
+    // clear config loading
+    await new Promise(setImmediate);
+
+    const response = apiTextResponse(200, 'done');
+    resolve(response);
+
+    expect(timeoutSpy).toHaveBeenCalledTimes(1);
+    expect(timeoutSpy).toHaveBeenCalledWith(expect.anything(), 5000);
+
+    expect(await result).toEqual(response);
+
+    expect(clearTimeoutSpy).toHaveBeenCalledWith(7);
+    expect(logFn).not.toHaveBeenCalled();
+  });
+
+  it('does not log a timeout when the response promise rejects in time', async() => {
+    const {reject, promise} = insideOutPromise<ApiResponse<number, string>>();
+
+    const result = createSlowResponseMiddleware({
+      logResponseSlowerThan: '1000',
+      timeoutResponseAfter: '5000'
+    })()(promise, {logger});
+
+    // clear config loading
+    await new Promise(setImmediate);
+
+    const error = new NotFoundError();
+    reject(error);
+
+    expect(timeoutSpy).toHaveBeenCalledTimes(1);
+    expect(timeoutSpy).toHaveBeenCalledWith(expect.anything(), 5000);
+
+    await expect(result).rejects.toThrow(error);
+
+    expect(clearTimeoutSpy).toHaveBeenCalledWith(7);
+    expect(logFn).not.toHaveBeenCalled();
+  });
+});

package/packages/utils/src/middleware/apiSlowResponseMiddleware.ts

@@ -0,0 +1,71 @@
+import type { ConfigProviderForConfig } from '../config';
+import { resolveConfigValue } from '../config/resolveConfigValue';
+import { once } from '../misc/helpers';
+import type { ApiResponse } from '../routing';
+import { apiTextResponse } from '../routing';
+import type { Logger } from '../services/logger';
+import { Level } from '../services/logger';
+
+type Config = {
+  logResponseSlowerThan: string;
+  timeoutResponseAfter: string;
+};
+
+/**
+ * Creates response middleware that logs slow responses and times out responses that take too long. lambda functions have a timeout setting, but when a lambda times out there is no way to log anything helpful before it exists. this middleware allows the logger context to show up for timeout requests. just make sure that the `timeoutResponseAfter` is set to something slightly shorter than the lambda timeout so that it has time to run.
+ *
+ * @param config
+ * @param config.logResponseSlowerThan the config that specifies the threshold for a slow response
+ * @param config.timeoutResponseAfter the config that specifies the timeout for a response
+ * @example
+ * createSlowResponseMiddleware({
+ *   logResponseSlowerThan: envConfig('LOG_SLOW_RESPONSE', 'runtime', '1000'),
+ *   timeoutResponseAfter: envConfig('RESPONSE_TIMEOUT', 'runtime', '28000'),
+ * });
+ */
+export const createSlowResponseMiddleware = (config: ConfigProviderForConfig<Config>) => {
+  const getSlowThreshold = once(() => resolveConfigValue(config.logResponseSlowerThan).then(result => parseInt(result, 10)));
+  const getTimeoutAfter = once(() => resolveConfigValue(config.timeoutResponseAfter).then(result => parseInt(result, 10)));
+
+  return () => (
+    response: Promise<ApiResponse<number, any>> | undefined, {logger}: {logger: Logger}
+  ): Promise<ApiResponse<number, string>> | undefined => {
+    const start = Date.now();
+
+    if (!response) {
+      return response;
+    }
+
+    return Promise.all([getSlowThreshold(), getTimeoutAfter()]).then(([slowThreshold, timeoutAfter]) => {
+
+      let timeout: ReturnType<typeof setTimeout> | undefined = undefined;
+
+      const timeoutPromise = isNaN(timeoutAfter)
+        ? undefined
+        : new Promise<ApiResponse<number, string>>(resolve => timeout = setTimeout(() => {
+          logger.logEvent(Level.Error, {
+            message: 'request processing timed out',
+          });
+          resolve(apiTextResponse(504, '504 Gateway Timeout'));
+        }, timeoutAfter))
+      ;
+
+      const requestPromise = response.finally(() => {
+        const time = Date.now() - start;
+
+        if (timeout !== undefined) {
+          clearTimeout(timeout);
+        }
+
+        if (time > slowThreshold) {
+          logger.logEvent(Level.Warn, {
+            message: 'slow response',
+            time,
+          });
+        }
+      });
+
+      return timeoutPromise ? Promise.race([timeoutPromise, requestPromise]) : requestPromise;
+    });
+  };
+};

package/packages/utils/src/middleware/index.spec.ts

@@ -0,0 +1,99 @@
+import { makeComposeMiddleware } from '.';
+
+describe('composeMiddleware', () => {
+  it('composes middleware', () => {
+    const provider1 = () => <M extends {thing1: string}>(middleware: M) => ({...middleware, thing2: `${middleware.thing1}-copy`});
+    const provider2 = () => <M extends {thing2: string}>({thing2, ...middleware}: M) => ({...middleware, thing2: thing2.length, thing3: `${thing2}-copy`});
+
+    const composeMiddleware = makeComposeMiddleware<{}, {thing1: string; thing7: string}>();
+
+    const middleware = composeMiddleware(
+      provider1,
+      provider2
+    );
+
+    const result = middleware({})({thing1: 'first', thing7: 'seven'});
+
+    // just trying to make TS complain if these are the wrong type or result is never
+    result.thing1.length;
+    result.thing2.toFixed;
+    result.thing3.length;
+    result.thing7.length;
+
+    expect(result).toEqual({
+      thing1: 'first',
+      thing2: 10,
+      thing3: 'first-copy-copy',
+      thing7: 'seven',
+    });
+  });
+
+  it('composes middleware arguments', () => {
+    const provider1 = () => <M extends {thing1: string}>(middleware: M, argument: string) => ({...middleware, thing2: `${middleware.thing1}-${argument}`});
+    const provider2 = () => <M extends {thing2: string}>(middleware: M) => ({...middleware, thing3: `${middleware.thing2}-copy`});
+
+    const composeMiddleware = makeComposeMiddleware<{}, {thing1: string; thing7: string}>();
+
+    const middleware = composeMiddleware(
+      provider1,
+      provider2
+    );
+
+    const result = middleware({})({thing1: 'first', thing7: 'seven'}, 'extra value');
+
+    // just trying to make TS complain if these are the wrong type or result is never
+    result.thing1.length;
+    result.thing2.length;
+    result.thing3.length;
+    result.thing7.length;
+
+
+    expect(result).toEqual({
+      thing1: 'first',
+      thing2: 'first-extra value',
+      thing3: 'first-extra value-copy',
+      thing7: 'seven',
+    });
+  });
+
+  it('transforms optional data', () => {
+    const provider1 = () => (middleware: {thing: string} | undefined) => middleware || {thing: 'default'};
+    const provider2 = () => (middleware: {thing: string}) => middleware;
+
+    const composeMiddleware = makeComposeMiddleware<{}, {thing: string} | undefined>();
+
+    const middleware = composeMiddleware(
+      provider1,
+      provider2,
+    );
+
+    // just trying to make TS complain if these are the wrong type or result is never
+    middleware({})(undefined).thing.length;
+    middleware({})({thing: 'first'}).thing.length;
+
+    expect(middleware({})(undefined).thing).toBe('default');
+    expect(middleware({})({thing: 'first'}).thing).toBe('first');
+  });
+
+  it('transforms non-hash data', () => {
+    const default0 = () => (middleware: number | undefined) => middleware || 0;
+    const add2 = () => (middleware: number) => middleware + 2;
+    const doubleIt = () => (middleware: number) => middleware * 2;
+
+    const composeMiddleware = makeComposeMiddleware<{}, number | undefined>();
+
+    const middleware = composeMiddleware(
+      default0,
+      add2,
+      doubleIt,
+      add2
+    );
+
+    // just trying to make TS complain if these are the wrong type or result is never
+    middleware({})(undefined).toFixed;
+    middleware({})(2).toFixed;
+
+    expect(middleware({})(undefined)).toBe(6);
+    expect(middleware({})(2)).toBe(10);
+  });
+});

package/{dist/cjs/middleware/index.d.ts → packages/utils/src/middleware/index.ts}

@@ -1,11 +1,51 @@
 import { TupleZip } from '../types';
-export type MiddlewareProvider<Sa, M, A extends any[], R> = (app: Sa, appBinder?: ((app: Sa, provider: MiddlewareProvider<Sa, M, A, R>) => (middleware: M, ...args: A) => R)) => (middleware: M, ...args: A) => R;
+
+// this is a more standard flow provider that takes input and produces an unrelated output
+export type MiddlewareProvider<Sa, M, A extends any[], R> = (
+  app: Sa,
+  appBinder?: ((app: Sa, provider: MiddlewareProvider<Sa, M, A, R>) => (middleware: M, ...args: A) => R)
+) => (middleware: M, ...args: A) => R;
+
+// this detects generics that forward the input to the output while modifying or adding properties
 export type MiddlewareTransformProvider<Sa, M, A extends any[], R> = (app: Sa) => (middleware: M, ...args: A) => Omit<M, keyof R> & R;
+
 export type MiddlewareInput<S> = S extends MiddlewareProvider<any, infer M, any, any> ? M : never;
-export type ServiceMiddlewareProviderResult<M, S> = [M] extends [never] ? never : [M] extends [MiddlewareInput<S>] ? S extends MiddlewareTransformProvider<any, M, any, infer R> ? (Omit<R, keyof M> & M) extends R ? Omit<R, keyof M> & M : R extends M ? R : Omit<M, keyof R> & R : S extends MiddlewareProvider<any, M, any, infer R> ? R : never : never;
+
+export type ServiceMiddlewareProviderResult<M, S> = [M] extends [never]
+  ? never
+  : [M] extends [MiddlewareInput<S>]
+    ? S extends MiddlewareTransformProvider<any, M, any, infer R>
+      ? (Omit<R, keyof M> & M) extends R
+        ? Omit<R, keyof M> & M // if R includes any keys from M, the M keys are more specific, use M
+        : R extends M
+          ? R // R is a more specific version of M, use R
+          : Omit<M, keyof R> & R // R overwrites some type from M, use R
+      : S extends MiddlewareProvider<any, M, any, infer R>
+        ? R
+        : never
+      : never;
+
 export type ServiceMiddlewareProviderArgs<S> = S extends MiddlewareProvider<any, any, infer A, any> ? A : never;
-export type ServiceMiddlewareProviderChainResult<C, M> = C extends [infer S1, ...infer S] ? S extends never[] ? ServiceMiddlewareProviderResult<M, S1> : ServiceMiddlewareProviderChainResult<S, ServiceMiddlewareProviderResult<M, S1>> : C extends unknown ? M : never;
-export type ServiceMiddlewareProviderChainArgs<C> = C extends [infer S1, ...infer S] ? S extends never[] ? ServiceMiddlewareProviderArgs<S1> : TupleZip<ServiceMiddlewareProviderChainArgs<S>, ServiceMiddlewareProviderArgs<S1>> : C extends unknown ? [] : never;
+
+export type ServiceMiddlewareProviderChainResult<C, M> = C extends [infer S1, ...infer S]
+  ? S extends never[]
+    ? ServiceMiddlewareProviderResult<M, S1>
+    : ServiceMiddlewareProviderChainResult<S,
+        ServiceMiddlewareProviderResult<M, S1>
+      >
+  : C extends unknown
+    ? M
+    : never
+;
+export type ServiceMiddlewareProviderChainArgs<C> = C extends [infer S1, ...infer S]
+  ? S extends never[]
+    ? ServiceMiddlewareProviderArgs<S1>
+    : TupleZip<ServiceMiddlewareProviderChainArgs<S>, ServiceMiddlewareProviderArgs<S1>>
+  : C extends unknown
+    ? []
+    : never
+;
+
 /**
  * Creates a middleware composer for given AppServices and input value types. The composer accepts a list of middleware
  * that it assembles into a chain. The function returned by the composer takes a value of the given input value type,
@@ -44,4 +84,12 @@ export type ServiceMiddlewareProviderChainArgs<C> = C extends [infer S1, ...infe
  * eg: const myThing: myType = makeComposeMiddleware()(...);
  * ```
  */
-export declare const makeComposeMiddleware: <Sa, M>() => <C extends any[]>(...chain: C) => MiddlewareProvider<Sa, M, ServiceMiddlewareProviderChainArgs<C>, ServiceMiddlewareProviderChainResult<C, M>>;
+export const makeComposeMiddleware = <Sa, M>() => <C extends any[]>(
+  ...chain: C
+): MiddlewareProvider<Sa, M, ServiceMiddlewareProviderChainArgs<C>, ServiceMiddlewareProviderChainResult<C, M>> => (app, appBinder) => {
+  const boundChain = chain.map(provider => appBinder ? appBinder(app, provider) : provider(app));
+
+  return (middleware: M, ...args) => {
+    return boundChain.reduce((result, provider) => provider(result, ...args), middleware);
+  };
+};

package/packages/utils/src/middleware/lambdaCorsResponseMiddleware.spec.ts

@@ -0,0 +1,103 @@
+import { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { apiJsonResponse } from '../routing';
+import { createLambdaCorsResponseMiddleware } from './lambdaCorsResponseMiddleware';
+
+describe('createLambdaCorsResponseMiddleware', () => {
+  it('adds cors headers for openstax subdomains', async() => {
+    const request = {
+      cookies: [],
+      headers: {
+        origin: 'https://neato.openstax.org'
+      },
+      requestContext: {
+        http: {
+          method: 'GET'
+        }
+      }
+    } as unknown as APIGatewayProxyEventV2;
+
+    const response = await createLambdaCorsResponseMiddleware({corsAllowedHostRegex: '(openstax.org|herokuapp.com)$'})()(
+      Promise.resolve(apiJsonResponse(200, {})), {request}
+    );
+
+    expect(response?.headers?.['Access-Control-Allow-Origin']).toBe('https://neato.openstax.org');
+    expect(response?.headers?.['Access-Control-Allow-Methods']).toBe('POST, GET, PUT, PATCH, DELETE, OPTIONS');
+  });
+
+  it('adds cors headers for openstax apex', async() => {
+    const request = {
+      cookies: [],
+      headers: {
+        origin: 'https://openstax.org'
+      },
+      requestContext: {
+        http: {
+          method: 'GET'
+        }
+      }
+    } as unknown as APIGatewayProxyEventV2;
+
+    const response = await createLambdaCorsResponseMiddleware({corsAllowedHostRegex: '(openstax.org|herokuapp.com)$'})()(
+      Promise.resolve(apiJsonResponse(200, {})), {request}
+    );
+
+    expect(response?.headers?.['Access-Control-Allow-Origin']).toBe('https://openstax.org');
+    expect(response?.headers?.['Access-Control-Allow-Methods']).toBe('POST, GET, PUT, PATCH, DELETE, OPTIONS');
+  });
+
+  it('omits headers without origin', async() => {
+    const request = {
+      cookies: [],
+      headers: {
+      },
+      requestContext: {
+        http: {
+          method: 'GET'
+        }
+      }
+    } as unknown as APIGatewayProxyEventV2;
+
+    const response = await createLambdaCorsResponseMiddleware({corsAllowedHostRegex: '(openstax.org|herokuapp.com)$'})()(
+      Promise.resolve(apiJsonResponse(200, {})), {request}
+    );
+
+    expect(response?.headers?.['Access-Control-Allow-Origin']).toBeUndefined();
+    expect(response?.headers?.['Access-Control-Allow-Methods']).toBeUndefined();
+  });
+
+  it('forwards undefined response if its not options', async() => {
+    const request = {
+      cookies: [],
+      headers: {
+      },
+      requestContext: {
+        http: {
+          method: 'GET'
+        }
+      }
+    } as unknown as APIGatewayProxyEventV2;
+
+    const response = await createLambdaCorsResponseMiddleware({corsAllowedHostRegex: '(openstax.org|herokuapp.com)$'})()(undefined, {request});
+
+    expect(response).toBeUndefined();
+  });
+
+  it('responds to options', async() => {
+    const request = {
+      cookies: [],
+      headers: {
+        origin: 'https://openstax.org'
+      },
+      requestContext: {
+        http: {
+          method: 'OPTIONS'
+        }
+      }
+    } as unknown as APIGatewayProxyEventV2;
+
+    const response = await createLambdaCorsResponseMiddleware({corsAllowedHostRegex: '(openstax.org|herokuapp.com)$'})()(undefined, {request});
+
+    expect(response?.headers?.['Access-Control-Allow-Origin']).toBe('https://openstax.org');
+    expect(response?.headers?.['Access-Control-Allow-Methods']).toBe('POST, GET, PUT, PATCH, DELETE, OPTIONS');
+  });
+});

package/packages/utils/src/middleware/lambdaCorsResponseMiddleware.ts

@@ -0,0 +1,52 @@
+import { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { ConfigProviderForConfig } from '../config';
+import { resolveConfigValue } from '../config/resolveConfigValue';
+import { once } from '../misc/helpers';
+import { ApiResponse, apiTextResponse } from '../routing';
+
+type Config = {
+  corsAllowedHostRegex: string;
+};
+
+/**
+ * Creates response middleware that adds CORS headers to responses from approved hosts.
+ *
+ * @param config the config object
+ * @param config.corsAllowedHostRegex the config that specifies the regex for allowed hosts
+ * @example
+ * createLambdaCorsResponseMiddleware({
+ *   corsAllowedHostRegex: '(openstax.org|herokuapp.com)$'
+ * }),
+ */
+export const createLambdaCorsResponseMiddleware = (config: ConfigProviderForConfig<Config>) => () => (responsePromise: Promise<ApiResponse<number, any>> | undefined, {request}: {request: APIGatewayProxyEventV2}): Promise<ApiResponse<number, any>> | undefined => {
+  const getAllowedHostRegex = once(() => resolveConfigValue(config.corsAllowedHostRegex));
+
+  const cors = async () => {
+    const allowedHost = await getAllowedHostRegex();
+
+    if (request.headers.origin && request.headers.origin !== 'null' && new URL(request.headers.origin).hostname.match(new RegExp(allowedHost))) {
+      return {
+        'Access-Control-Allow-Origin': request.headers.origin,
+        'Access-Control-Allow-Credentials': 'true',
+        'Access-Control-Allow-Headers': 'content-type, x-request-id',
+        'Access-Control-Allow-Methods': 'POST, GET, PUT, PATCH, DELETE, OPTIONS',
+      };
+    }
+  };
+
+  if (responsePromise) {
+    return responsePromise.then(async response => {
+      response.headers = {
+        ...await cors(),
+        ...response.headers
+      };
+      return response;
+    });
+  }
+
+  if (request.requestContext.http.method === 'OPTIONS') {
+    return cors().then(headers => apiTextResponse(200, '', headers));
+  }
+
+  return responsePromise;
+};

package/packages/utils/src/middleware/throwNotFoundMiddleware.spec.ts

@@ -0,0 +1,20 @@
+import { NotFoundError } from '../errors';
+import { createThrowNotFoundMiddleware } from './throwNotFoundMiddleware';
+
+
+describe('throwNotFoundMiddleware', () => {
+  it('defaults to 404', async() => {
+    const default404MiddlewareNoResponse = () => createThrowNotFoundMiddleware<any>()()(undefined);
+
+    // Normally caught by the default errorHandler
+    expect(default404MiddlewareNoResponse).toThrow(NotFoundError);
+    expect(default404MiddlewareNoResponse).toThrow('not found');
+  });
+
+  it('keeps response', async() => {
+    const initial = {};
+    const response = await createThrowNotFoundMiddleware<any>()()(Promise.resolve(initial));
+
+    expect(response).toBe(initial);
+  });
+});

package/packages/utils/src/middleware/throwNotFoundMiddleware.ts

@@ -0,0 +1,11 @@
+import { NotFoundError } from '../errors';
+
+/**
+ * Creates response middleware that throws a `NotFoundError` if the response is undefined.
+ */
+export const createThrowNotFoundMiddleware = <Ro>() => () => (response: Promise<Ro> | undefined): Promise<Ro> => {
+  if (!response) {
+    throw new NotFoundError('not found');
+  }
+  return response;
+};

package/packages/utils/src/misc/hashValue.ts

@@ -0,0 +1,18 @@
+import { createHash } from 'crypto';
+
+export type HashValue = string | number | boolean | null | HashCompoundValue;
+export type HashCompoundValue = Array<HashValue> | {[key: string]: HashValue};
+
+/**
+ * creates a string hash of lots of different kinds of things.
+ *
+ * @example hashValue({someKey: 'someValue'})
+ */
+export const hashValue = (value: HashValue) => {
+  // hack for sorting keys https://stackoverflow.com/a/53593328/14809536
+  const allKeys = new Set<string>();
+  JSON.stringify(value, (k, v) => (allKeys.add(k), v));
+  const strValue = JSON.stringify(value, Array.from(allKeys).sort());
+
+  return createHash('sha1').update(strValue).digest('hex');
+};