smokeTest.koaMiddleware: Add function (#33)

Author: 72636c

.changeset/warm-keys-fold.md

@@ -0,0 +1,5 @@
+---
+'@seek/aws-codedeploy-hooks': minor
+---
+
+smokeTest.koaMiddleware: Add function

packages/hooks/README.md

@@ -64,3 +64,32 @@ Checks for:
 
 - An empty event object
 - A custom `user-agent` in context that starts with `aws-codedeploy-hook-`
+
+### `smokeTest.koaMiddleware`
+
+A Koa middleware that executes a smoke test function to check whether the application is broadly operational and ready to serve requests.
+
+The `skipHook` option skips synchronous validation of the smoke test function during pre-deployment checks from an AWS CodeDeploy hook.
+This may be used when a build needs to be expedited in a disaster recovery scenario or when a dependency is known to be unhealthy.
+
+```typescript
+import { Env } from 'skuba-dive';
+import Router from '@koa/router';
+import logger from '@seek/logger';
+
+const config = {
+  skipHook: Env.boolean('SKIP_SMOKE', { default: false }),
+};
+
+const logger = createLogger();
+
+export const router = new Router().get(
+  '/smoke',
+  smokeTest.koaMiddleware({ logger, skipHook: config.skipHook }, async () => {
+    // Run dependency checks.
+    await checkDependencies();
+  }),
+);
+```
+
+Uses [`isHttpHook`](#ishttphook) under the hood.

packages/hooks/package.json

@@ -28,6 +28,7 @@
   "dependencies": {},
   "devDependencies": {
     "@aws-sdk/client-lambda": "3.485.0",
+    "@seek/logger": "^6.2.0",
     "@types/aws-lambda": "^8.10.130",
     "@types/koa": "^2.13.6",
     "@types/supertest": "^6.0.2",

packages/hooks/src/http.ts

@@ -4,7 +4,7 @@ type HeadersClass = { get: (name: string) => string | null };
 
 type HeadersRecord = Record<string, null | string | string[] | undefined>;
 
-type HttpRequest = {
+export type HttpRequest = {
   headers: HeadersClass | HeadersRecord;
 };
 

packages/hooks/src/index.test.ts

@@ -6,6 +6,9 @@ describe('rootModule', () => {
       {
         "isHttpHook": [Function],
         "isLambdaHook": [Function],
+        "smokeTest": {
+          "koaMiddleware": [Function],
+        },
       }
     `));
 });

packages/hooks/src/index.ts

@@ -1,2 +1,3 @@
 export { isHttpHook } from './http';
 export { isLambdaHook } from './lambda';
+export { smokeTest } from './smokeTest';

packages/hooks/src/smokeTest/index.ts

@@ -0,0 +1,5 @@
+import { koaMiddleware } from './koa';
+
+export const smokeTest = {
+  koaMiddleware,
+};

packages/hooks/src/smokeTest/koa.test.ts

@@ -0,0 +1,194 @@
+import createLogger from '@seek/logger';
+import Koa from 'koa';
+import { agent } from 'supertest';
+
+import { koaMiddleware } from './koa';
+
+const onError = jest.fn();
+const write = jest.fn();
+
+const stdout = () => write.mock.calls.flat().join('').trim();
+
+afterEach(jest.clearAllMocks);
+
+const logger = createLogger(
+  { serializers: { err: (err) => String(err) }, timestamp: false },
+  { write: (msg) => write(msg) },
+);
+
+type Options = {
+  skipHook: Parameters<typeof koaMiddleware>[0]['skipHook'];
+  smokeTest: Parameters<typeof koaMiddleware>[1];
+  userAgent: string;
+};
+
+const run = ({ skipHook, smokeTest, userAgent }: Options) => {
+  const app = new Koa()
+    .use(koaMiddleware({ logger, skipHook }, smokeTest))
+    .on('error', onError);
+
+  return agent(
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises
+    app.callback(),
+  )
+    .get('/')
+    .set('User-Agent', userAgent);
+};
+
+it.each`
+  skipHook | userAgent
+  ${true}  | ${'Mozilla/5.0'}
+  ${false} | ${'aws-codedeploy-hook-BeforeAllowTraffic/1.2.3'}
+  ${false} | ${'gantry-codedeploy-hook-BeforeAllowTraffic-dev/1.2.3'}
+  ${false} | ${'Mozilla/5.0'}
+`(
+  'handles a foreground smoke test with skipHook: $skipHook and userAgent: $userAgent',
+  async ({ skipHook, userAgent }) => {
+    await run({
+      skipHook,
+      smokeTest: () => undefined,
+      userAgent,
+    }).expect(200, 'Smoke test succeeded');
+
+    expect(onError).not.toHaveBeenCalled();
+    expect(stdout()).toBeFalsy();
+  },
+);
+
+it.each`
+  skipHook | userAgent
+  ${true}  | ${'aws-codedeploy-hook-BeforeAllowTraffic/1.2.3'}
+  ${true}  | ${'gantry-codedeploy-hook-BeforeAllowTraffic-dev/1.2.3'}
+`(
+  'handles a background smoke test with skipHook: $skipHook and userAgent: $userAgent',
+  async ({ skipHook, userAgent }) => {
+    await run({
+      skipHook,
+      smokeTest: () => undefined,
+      userAgent,
+    }).expect(200, 'Smoke test skipped');
+
+    expect(onError).not.toHaveBeenCalled();
+    expect(stdout()).toBe(
+      '{"level":30,"msg":"Smoke test succeeded in background"}',
+    );
+  },
+);
+
+it.each`
+  userAgent
+  ${'aws-codedeploy-hook-BeforeAllowTraffic/123'}
+  ${'gantry-codedeploy-hook-BeforeAllowTraffic-dev/1.2.3'}
+`(
+  'skips a synchronous error with skipHook: true and userAgent: $userAgent',
+  async ({ userAgent }) => {
+    await run({
+      skipHook: true,
+      smokeTest: () => {
+        throw new Error('Badness!');
+      },
+      userAgent,
+    }).expect(200, 'Smoke test skipped');
+
+    expect(onError).not.toHaveBeenCalled();
+    expect(stdout()).toBe(
+      '{"level":40,"err":"Error: Badness!","msg":"Smoke test failed in background"}',
+    );
+  },
+);
+
+it.each`
+  userAgent
+  ${'aws-codedeploy-hook-BeforeAllowTraffic/123'}
+  ${'gantry-codedeploy-hook-BeforeAllowTraffic-dev/1.2.3'}
+`(
+  'skips an asynchronous error with skipHook: true and userAgent: $userAgent',
+  async ({ userAgent }) => {
+    await run({
+      skipHook: true,
+      smokeTest: () => Promise.reject(new Error('Badness!')),
+      userAgent,
+    }).expect(200, 'Smoke test skipped');
+
+    expect(onError).not.toHaveBeenCalled();
+    expect(stdout()).toBe(
+      '{"level":40,"err":"Error: Badness!","msg":"Smoke test failed in background"}',
+    );
+  },
+);
+
+it.each`
+  skipHook | userAgent
+  ${true}  | ${'Mozilla/5.0'}
+  ${false} | ${'aws-codedeploy-hook-BeforeAllowTraffic/123'}
+  ${false} | ${'gantry-codedeploy-hook-BeforeAllowTraffic-dev/1.2.3'}
+  ${false} | ${'Mozilla/5.0'}
+`(
+  'throws a synchronous error with skipHook: $skipHook and userAgent: $userAgent',
+  async ({ skipHook, userAgent }) => {
+    await run({
+      skipHook,
+      smokeTest: () => {
+        throw new Error('Badness!');
+      },
+      userAgent,
+    }).expect(500, 'Internal Server Error');
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(stdout()).toBeFalsy();
+  },
+);
+
+it.each`
+  skipHook | userAgent
+  ${true}  | ${'Mozilla/5.0'}
+  ${false} | ${'aws-codedeploy-hook-BeforeAllowTraffic/123'}
+  ${false} | ${'gantry-codedeploy-hook-BeforeAllowTraffic-dev/1.2.3'}
+  ${false} | ${'Mozilla/5.0'}
+`(
+  'throws an asynchronous error with skipHook: $skipHook and userAgent: $userAgent',
+  async ({ skipHook, userAgent }) => {
+    await run({
+      skipHook,
+      smokeTest: () => Promise.reject(new Error('Badness!')),
+      userAgent,
+    }).expect(500, 'Internal Server Error');
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(stdout()).toBeFalsy();
+  },
+);
+
+it('passes no arguments to the smoke test function asynchronously', async () => {
+  const smokeTest = jest.fn();
+
+  await run({
+    skipHook: true,
+    smokeTest,
+    userAgent: 'aws-codedeploy-hook-BeforeAllowTraffic/123',
+  }).expect(200, 'Smoke test skipped');
+
+  expect(onError).not.toHaveBeenCalled();
+  expect(stdout()).toBe(
+    '{"level":30,"msg":"Smoke test succeeded in background"}',
+  );
+
+  expect(smokeTest).toHaveBeenCalledTimes(1);
+  expect(smokeTest).toHaveBeenLastCalledWith();
+});
+
+it('passes no arguments to the smoke test function synchronously', async () => {
+  const smokeTest = jest.fn();
+
+  await run({
+    skipHook: false,
+    smokeTest,
+    userAgent: 'Mozilla/5.0',
+  }).expect(200, 'Smoke test succeeded');
+
+  expect(onError).not.toHaveBeenCalled();
+  expect(stdout()).toBe('');
+
+  expect(smokeTest).toHaveBeenCalledTimes(1);
+  expect(smokeTest).toHaveBeenLastCalledWith();
+});

packages/hooks/src/smokeTest/koa.ts

@@ -0,0 +1,87 @@
+import { type HttpRequest, isHttpHook } from '../http';
+
+type Context = { body: unknown; req: Readonly<HttpRequest>; status: number };
+
+type Logger = {
+  info: (message: string) => unknown;
+  warn: (props: { err: unknown }, message: string) => unknown;
+};
+
+type Options = {
+  /**
+   * An instance of the application logger.
+   *
+   * When `skipHook` takes effect, the smoke test function is not entirely
+   * skipped but is rather invoked in the background. Its execution does not
+   * hold up or otherwise affect the HTTP response to the client, but its result
+   * is still logged as a data point for future reference.
+   */
+  logger: Logger;
+
+  /**
+   * Whether to skip synchronous validation of the smoke test function during
+   * pre-deployment checks from an AWS CodeDeploy hook.
+   *
+   * - Set to `false` in general operation to exercise the smoke test before
+   *   accepting production traffic.
+   * - Set to `true` when a build needs to be expedited in a disaster recovery
+   *   scenario or when a dependency is known to be unhealthy.
+   *
+   * This option is ignored and synchronous validation of the `smokeTest`
+   * function proceeds if the request does not originate from an AWS CodeDeploy
+   * or Gantry hook user agent. For example, a regular health check poll from a
+   * CloudWatch or Datadog synthetic will continue to exercise the smoke test.
+   */
+  skipHook: boolean;
+};
+
+/**
+ * A Koa middleware that executes a smoke test function to check whether the
+ * application is broadly operational and ready to serve requests.
+ *
+ * The `skipHook` option skips synchronous validation of the smoke test function
+ * during pre-deployment checks from an AWS CodeDeploy hook. This may be used
+ * when a build needs to be expedited in a disaster recovery scenario or when a
+ * dependency is known to be unhealthy.
+ */
+export const koaMiddleware =
+  (
+    { logger, skipHook }: Options,
+
+    /**
+     * A function that checks whether the application is broadly operational and
+     * ready to serve requests.
+     *
+     * A typical smoke test execution may validate that the application container
+     * has started, its server process is accepting requests, its core application
+     * logic is intact, and its dependencies are reachable.
+     *
+     * This function should `throw` an error upon failure; all other return values
+     * will be treated as a success.
+     */
+    smokeTest: () => unknown,
+  ) =>
+  async (ctx: Context) => {
+    if (isHttpHook(ctx.req) && skipHook) {
+      // Run in the background. This avoids holding up the deployment while the
+      // result is still logged as a data point for future reference.
+      Promise.resolve()
+        .then(() => smokeTest())
+        .then(() => logger.info('Smoke test succeeded in background'))
+        .catch((err: unknown) =>
+          logger.warn({ err }, 'Smoke test failed in background'),
+        );
+
+      ctx.status = 200;
+      ctx.body = 'Smoke test skipped';
+
+      return;
+    }
+
+    await smokeTest();
+
+    ctx.status = 200;
+    ctx.body = 'Smoke test succeeded';
+
+    return;
+  };