Clarify API health checks and smoke tests (#332)

Resolves #116.

.changeset/gorgeous-dancers-buy.md

@@ -0,0 +1,5 @@
+---
+'skuba': patch
+---
+
+**template/\*-rest-api:** Explicitly register `listen.ts`

.changeset/pink-bikes-roll.md

@@ -0,0 +1,5 @@
+---
+'skuba': patch
+---
+
+**template/\*-rest-api:** Clarify health checks and smoke tests

template/express-rest-api/gantry.apply.yml

@@ -31,7 +31,7 @@ pagerDutyEndpoint: '{{values "pagerDutyEndpoint"}}'
 authentication:
   ignoreRoutes:
     - /health
-    - /
+    - /smoke
 
 autoScaling:
   maxCount: {{values "maxInstanceCount"}}
@@ -112,7 +112,7 @@ deployment:
   # Ignore alarms otherwise we can't deploy to a failed environment (SEEK-Jobs/gantry#488)
   ignoreAlarms: true
   smokeTest:
-    path: /health
+    path: /smoke
     useExternalDns: true
 
 tags:

template/express-rest-api/src/api/healthCheck.ts

@@ -0,0 +1,11 @@
+import { Handler } from 'express';
+
+/**
+ * Signifies that the API is available to serve requests.
+ *
+ * The deployment environment calls this endpoint to see if the container is
+ * unhealthy and needs to be recycled.
+ */
+export const healthCheckHandler: Handler = (_req, res) => {
+  res.send('');
+};

template/express-rest-api/src/api/smokeTest.ts

@@ -0,0 +1,10 @@
+import { Handler } from 'express';
+
+/**
+ * Tests connectivity to ensure appropriate access and network configuration.
+ */
+export const smokeTestHandler: Handler = async (_req, res) => {
+  await Promise.all([]);
+
+  res.send('');
+};

template/express-rest-api/src/app.test.ts

@@ -5,7 +5,5 @@ import app from './app';
 const agent = request.agent(app);
 
 describe('app', () => {
-  it('Hello World!', () => agent.get('/').expect(200, 'Hello World!'));
-
   it('has a happy health check', () => agent.get('/health').expect(200, ''));
 });

template/express-rest-api/src/app.ts

@@ -1,21 +1,14 @@
-import 'skuba-dive/register';
+import './register';
 
-import express, { Application, Request, Response } from 'express';
+import express from 'express';
 
+import { healthCheckHandler } from './api/healthCheck';
+import { smokeTestHandler } from './api/smokeTest';
 import { config } from './config';
-import { rootLogger } from './framework/logging';
 
-const app: Application = express();
-
-app.get('/', (_req: Request, res: Response) => {
-  rootLogger.debug('greeting...');
-
-  res.send('Hello World!');
-});
-
-app.get('/health', (_req: Request, res: Response) => {
-  res.send('');
-});
+const app = express()
+  .get('/health', healthCheckHandler)
+  .get('/smoke', smokeTestHandler);
 
 export default Object.assign(app, {
   port: config.port,

template/express-rest-api/src/listen.ts

@@ -1,3 +1,5 @@
+import './register';
+
 import app from './app';
 import { rootLogger } from './framework/logging';
 

template/express-rest-api/src/register.ts

@@ -0,0 +1 @@
+import 'skuba-dive/register';

template/koa-rest-api/gantry.apply.yml

@@ -32,7 +32,6 @@ authentication:
   ignoreRoutes:
     - /health
     - /smoke
-    - /jobs{/**}
 
 autoScaling:
   maxCount: {{values "maxInstanceCount"}}

template/koa-rest-api/src/api/healthCheck.ts

@@ -1,5 +1,11 @@
 import { Middleware } from 'src/types/koa';
 
+/**
+ * Signifies that the API is available to serve requests.
+ *
+ * The deployment environment calls this endpoint to see if the container is
+ * unhealthy and needs to be recycled.
+ */
 export const healthCheckHandler: Middleware = (ctx) => {
   ctx.state.skipRequestLogging = true;
 

template/koa-rest-api/src/api/smokeTest.ts

@@ -1,3 +1,11 @@
+import { smokeTestJobStorage } from 'src/storage/jobs';
 import { Middleware } from 'src/types/koa';
 
-export const smokeTestHandler: Middleware = (ctx) => (ctx.body = '');
+/**
+ * Tests connectivity to ensure appropriate access and network configuration.
+ */
+export const smokeTestHandler: Middleware = async (ctx) => {
+  await Promise.all([smokeTestJobStorage]);
+
+  ctx.body = '';
+};

template/koa-rest-api/src/app.ts

@@ -1,9 +1,11 @@
-import 'skuba-dive/register';
+import './register';
 
-import { router } from 'src/api';
-import { config } from 'src/config';
-import { createApp } from 'src/framework/server';
+import { router } from './api';
+import { config } from './config';
+import { createApp } from './framework/server';
 
 const app = createApp(router.allowedMethods(), router.routes());
 
-export default Object.assign(app, { port: config.port });
+export default Object.assign(app, {
+  port: config.port,
+});

template/koa-rest-api/src/listen.ts

@@ -1,3 +1,5 @@
+import './register';
+
 import app from './app';
 import { rootLogger } from './framework/logging';
 

template/koa-rest-api/src/register.ts

@@ -0,0 +1 @@
+import 'skuba-dive/register';

template/koa-rest-api/src/storage/jobs.ts

@@ -19,3 +19,10 @@ export const readJobs = (): Promise<Job[]> => {
 
   return Promise.resolve(jobs);
 };
+
+/**
+ * Tests that we have access to read from and write to our storage.
+ */
+export const smokeTestJobStorage = async (): Promise<void> => {
+  await Promise.resolve();
+};