skuba 0.0.0-beta-20231002015947

package/template/koa-rest-api/src/api/jobs/getJobs.ts

@@ -0,0 +1,15 @@
+import { logger } from 'src/framework/logging';
+import { metricsClient } from 'src/framework/metrics';
+import * as storage from 'src/storage/jobs';
+import type { Middleware } from 'src/types/koa';
+
+export const getJobsHandler: Middleware = async (ctx) => {
+  const jobs = await storage.readJobs();
+
+  // no PII in these jobs
+  logger.debug({ jobs }, 'read jobs');
+
+  metricsClient.increment('job.reads', jobs.length);
+
+  ctx.body = jobs;
+};

package/template/koa-rest-api/src/api/jobs/index.ts

@@ -0,0 +1,10 @@
+import Router from '@koa/router';
+
+import { jsonBodyParser } from 'src/framework/middleware';
+
+import { getJobsHandler } from './getJobs';
+import { postJobHandler } from './postJob';
+
+export const jobRouter = new Router()
+  .get('/', getJobsHandler)
+  .post('/', jsonBodyParser, postJobHandler);

package/template/koa-rest-api/src/api/jobs/postJob.test.ts

@@ -0,0 +1,34 @@
+import { agentFromRouter } from 'src/testing/server';
+import { mockJobInput } from 'src/testing/types';
+
+import { jobRouter } from '.';
+
+const agent = agentFromRouter(jobRouter);
+
+describe('postJobHandler', () => {
+  it('200s and allocates an ID on valid input', () => {
+    const jobInput = mockJobInput();
+
+    return agent
+      .post('/')
+      .send(jobInput)
+      .expect(200)
+      .expect(({ body }) =>
+        expect(body).toStrictEqual({ ...jobInput, id: expect.any(String) }),
+      );
+  });
+
+  it('422s on invalid input', () => {
+    const jobInput = {};
+
+    return agent
+      .post('/')
+      .send(jobInput)
+      .expect(422)
+      .expect(({ text }) =>
+        expect(text).toMatchInlineSnapshot(
+          `"{"message":"Input validation failed","invalidFields":{"/hirer":"Required"}}"`,
+        ),
+      );
+  });
+});

package/template/koa-rest-api/src/api/jobs/postJob.ts

@@ -0,0 +1,19 @@
+import { logger } from 'src/framework/logging';
+import { metricsClient } from 'src/framework/metrics';
+import { validateRequestBody } from 'src/framework/validation';
+import * as storage from 'src/storage/jobs';
+import { JobInputSchema } from 'src/types/jobs';
+import type { Middleware } from 'src/types/koa';
+
+export const postJobHandler: Middleware = async (ctx) => {
+  const jobInput = validateRequestBody(ctx, JobInputSchema);
+
+  const job = await storage.createJob(jobInput);
+
+  // no PII in these jobs
+  logger.debug({ job }, 'created job');
+
+  metricsClient.increment('job.creations');
+
+  ctx.body = job;
+};

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

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

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

@@ -0,0 +1,21 @@
+import { agentFromApp } from 'src/testing/server';
+
+import app from './app';
+
+const agent = agentFromApp(app);
+
+describe('app', () => {
+  it('exports callback for skuba start', () =>
+    expect(app).toHaveProperty('callback'));
+
+  it('has a happy health check', () => agent.get('/health').expect(200, ''));
+
+  it('has a reachable smoke test', () =>
+    agent.get('/smoke').expect(({ status }) => status !== 404));
+
+  it('has a reachable nested route', () =>
+    agent.get('/jobs').expect(({ status }) => status !== 404));
+
+  it('has OPTIONS for a nested route', () =>
+    agent.options('/jobs').expect(200).expect('allow', /HEAD/));
+});

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

@@ -0,0 +1,8 @@
+import './register';
+
+import { router } from './api';
+import { createApp } from './framework/server';
+
+const app = createApp(router.allowedMethods(), router.routes());
+
+export default app;

package/template/koa-rest-api/src/config.ts

@@ -0,0 +1,57 @@
+import { Env } from 'skuba-dive';
+
+interface Config {
+  environment: Environment;
+
+  logLevel: string;
+  name: string;
+  version: string;
+
+  metricsServer?: string;
+  port?: number;
+}
+
+type Environment = (typeof environments)[number];
+
+const dev = '<%- devGantryEnvironmentName %>';
+const prod = '<%- prodGantryEnvironmentName %>';
+
+const environments = ['local', 'test', dev, prod] as const;
+
+const environment = Env.oneOf(environments)('ENVIRONMENT');
+
+/* istanbul ignore next: config verification makes more sense in a smoke test */
+const configs: Record<Environment, () => Omit<Config, 'environment'>> = {
+  local: () => ({
+    logLevel: 'debug',
+    name: '<%- serviceName %>',
+    version: 'local',
+  }),
+
+  test: () => ({
+    ...configs.local(),
+
+    logLevel: Env.string('LOG_LEVEL', { default: 'silent' }),
+    version: 'test',
+  }),
+
+  [dev]: () => ({
+    ...configs[prod](),
+
+    logLevel: 'debug',
+  }),
+
+  [prod]: () => ({
+    logLevel: 'info',
+    name: Env.string('SERVICE'),
+    version: Env.string('VERSION'),
+
+    metricsServer: 'localhost',
+    port: Env.nonNegativeInteger('PORT'),
+  }),
+};
+
+export const config: Config = {
+  ...configs[environment](),
+  environment,
+};

package/template/koa-rest-api/src/framework/logging.ts

@@ -0,0 +1,25 @@
+import createLogger from '@seek/logger';
+import { RequestLogging } from 'seek-koala';
+
+import { config } from 'src/config';
+
+const { createContextMiddleware, mixin } =
+  RequestLogging.createContextStorage();
+
+export const contextMiddleware = createContextMiddleware();
+
+export const logger = createLogger({
+  base: {
+    environment: config.environment,
+    version: config.version,
+  },
+
+  mixin,
+
+  level: config.logLevel,
+
+  name: config.name,
+
+  transport:
+    config.environment === 'local' ? { target: 'pino-pretty' } : undefined,
+});

package/template/koa-rest-api/src/framework/metrics.ts

@@ -0,0 +1,11 @@
+import { StatsD } from 'hot-shots';
+import { createStatsDClient } from 'seek-datadog-custom-metrics';
+
+import { config } from 'src/config';
+
+import { logger } from './logging';
+
+/* istanbul ignore next: StatsD client is not our responsibility */
+export const metricsClient = createStatsDClient(StatsD, config, (err) =>
+  logger.error({ err }, 'StatsD error'),
+);

package/template/koa-rest-api/src/framework/middleware.ts

@@ -0,0 +1,3 @@
+import bodyParser from 'koa-bodyparser';
+
+export const jsonBodyParser = bodyParser({ enableTypes: ['json'] });

package/template/koa-rest-api/src/framework/server.test.ts

@@ -0,0 +1,260 @@
+import Router from '@koa/router';
+
+import { logger } from 'src/testing/logging';
+import { metricsClient } from 'src/testing/metrics';
+import { agentFromRouter } from 'src/testing/server';
+import { chance } from 'src/testing/types';
+import type { Middleware } from 'src/types/koa';
+
+const middleware = jest.fn<void, Parameters<Middleware>>();
+
+const router = new Router()
+  .use('/nested', new Router().put('/:param', middleware).routes())
+  .get('/', middleware);
+
+const agent = agentFromRouter(router);
+
+describe('createApp', () => {
+  beforeAll(logger.spy);
+
+  afterEach(metricsClient.clear);
+  afterEach(logger.clear);
+
+  it('handles root route', async () => {
+    middleware.mockImplementation((ctx) => (ctx.body = ''));
+
+    await agent
+      .get('/')
+      .expect(200, '')
+      .expect('server', /.+/)
+      .expect('x-api-version', /.+/);
+
+    expect(logger.error).not.toHaveBeenCalled();
+
+    expect(logger.info).not.toHaveBeenCalled();
+
+    metricsClient.expectTagSubset(['env:test', 'version:test']);
+    metricsClient.expectTagSubset([
+      'http_method:get',
+      'http_status:200',
+      'http_status_family:2xx',
+      'route:/',
+    ]);
+  });
+
+  it('handles nested route', async () => {
+    middleware.mockImplementation((ctx) => (ctx.body = ''));
+
+    await agent
+      .put('/nested/123')
+      .expect(200, '')
+      .expect('server', /.+/)
+      .expect('x-api-version', /.+/);
+
+    expect(logger.error).not.toHaveBeenCalled();
+
+    expect(logger.info).not.toHaveBeenCalled();
+
+    metricsClient.expectTagSubset([
+      'http_method:put',
+      'http_status:200',
+      'http_status_family:2xx',
+      'route:/nested/_param',
+    ]);
+  });
+
+  it('handles unknown route', async () => {
+    middleware.mockImplementation((ctx) => (ctx.body = ''));
+
+    await agent
+      .get('/unknown')
+      .expect(404, 'Not Found')
+      .expect('server', /.+/)
+      .expect('x-api-version', /.+/);
+
+    expect(logger.error).not.toHaveBeenCalled();
+
+    expect(logger.info).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ status: 404 }),
+      'Client error',
+    );
+
+    metricsClient.expectTagSubset([
+      'http_method:get',
+      'http_status:404',
+      'http_status_family:4xx',
+      'route:unspecified',
+    ]);
+  });
+
+  it('handles returned client error', async () => {
+    const message = chance.sentence();
+
+    middleware.mockImplementation((ctx) => {
+      ctx.body = message;
+      ctx.status = 400;
+    });
+
+    await agent
+      .get('/')
+      .expect(400, message)
+      .expect('server', /.+/)
+      .expect('x-api-version', /.+/);
+
+    expect(logger.error).not.toHaveBeenCalled();
+
+    expect(logger.info).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ status: 400 }),
+      'Client error',
+    );
+
+    metricsClient.expectTagSubset([
+      'http_method:get',
+      'http_status:400',
+      'http_status_family:4xx',
+      'route:/',
+    ]);
+  });
+
+  it('handles client error thrown from context', async () => {
+    const message = chance.sentence();
+
+    middleware.mockImplementation((ctx) => ctx.throw(400, message));
+
+    await agent
+      .get('/')
+      .expect(400, message)
+      .expect('server', /.+/)
+      .expect('x-api-version', /.+/);
+
+    expect(logger.error).not.toHaveBeenCalled();
+
+    expect(logger.info).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ err: expect.any(Error), status: 400 }),
+      'Client error',
+    );
+
+    metricsClient.expectTagSubset([
+      'http_method:get',
+      'http_status:400',
+      'http_status_family:4xx',
+      'route:/',
+    ]);
+  });
+
+  it('handles server error thrown from context', async () => {
+    const message = chance.sentence();
+
+    middleware.mockImplementation((ctx) => ctx.throw(500, message));
+
+    await agent
+      .get('/')
+      .expect(500, '')
+      .expect('server', /.+/)
+      .expect('x-api-version', /.+/);
+
+    expect(logger.error).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ err: expect.any(Error), status: 500 }),
+      'Server error',
+    );
+
+    expect(logger.info).not.toHaveBeenCalled();
+
+    metricsClient.expectTagSubset([
+      'http_method:get',
+      'http_status:500',
+      'http_status_family:5xx',
+      'route:/',
+    ]);
+  });
+
+  it('handles directly-thrown error', async () => {
+    const err = Error(chance.sentence());
+
+    middleware.mockImplementation(() => {
+      throw err;
+    });
+
+    await agent
+      .get('/')
+      .expect(500, '')
+      .expect('server', /.+/)
+      .expect('x-api-version', /.+/);
+
+    expect(logger.error).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ err, status: 500 }),
+      'Server error',
+    );
+
+    expect(logger.info).not.toHaveBeenCalled();
+
+    metricsClient.expectTagSubset([
+      'http_method:get',
+      'http_status:500',
+      'http_status_family:5xx',
+      'route:/',
+    ]);
+  });
+
+  it('handles null error', async () => {
+    middleware.mockImplementation(() => {
+      /* eslint-disable-next-line no-throw-literal */
+      throw null;
+    });
+
+    await agent
+      .get('/')
+      .expect(500, '')
+      .expect('server', /.+/)
+      .expect('x-api-version', /.+/);
+
+    expect(logger.error).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ err: null, status: 500 }),
+      'Server error',
+    );
+
+    expect(logger.info).not.toHaveBeenCalled();
+
+    metricsClient.expectTagSubset([
+      'http_method:get',
+      'http_status:500',
+      'http_status_family:5xx',
+      'route:/',
+    ]);
+  });
+
+  it('handles string error', async () => {
+    const err = chance.sentence();
+
+    middleware.mockImplementation(() => {
+      throw err;
+    });
+
+    await agent
+      .get('/')
+      .expect(500, '')
+      .expect('server', /.+/)
+      .expect('x-api-version', /.+/);
+
+    expect(logger.error).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ err, status: 500 }),
+      'Server error',
+    );
+
+    expect(logger.info).not.toHaveBeenCalled();
+
+    metricsClient.expectTagSubset([
+      'http_method:get',
+      'http_status:500',
+      'http_status_family:5xx',
+      'route:/',
+    ]);
+  });
+});

package/template/koa-rest-api/src/framework/server.ts

@@ -0,0 +1,51 @@
+import Koa from 'koa';
+import compose from 'koa-compose';
+import {
+  ErrorMiddleware,
+  MetricsMiddleware,
+  RequestLogging,
+  // SecureHeaders,
+  VersionMiddleware,
+} from 'seek-koala';
+
+import { config } from 'src/config';
+import { contextMiddleware, logger } from 'src/framework/logging';
+import { metricsClient } from 'src/framework/metrics';
+
+const metrics = MetricsMiddleware.create(
+  metricsClient,
+  ({ _matchedRoute }) => ({
+    route: typeof _matchedRoute === 'string' ? _matchedRoute : 'unspecified',
+  }),
+);
+
+const requestLogging = RequestLogging.createMiddleware((ctx, fields, err) => {
+  if (ctx.status < 400 && err === undefined) {
+    // Depend on sidecar logging for happy path requests
+    return;
+  }
+
+  return ctx.status < 500
+    ? logger.info(fields, 'Client error')
+    : logger.error(fields, 'Server error');
+});
+
+const version = VersionMiddleware.create({
+  name: config.name,
+  version: config.version,
+});
+
+export const createApp = <State, Context>(
+  ...middleware: Array<Koa.Middleware<State, Context>>
+) =>
+  new Koa()
+    // TODO: consider using a middleware that adds secure HTTP headers.
+    // https://github.com/seek-oss/koala/tree/master/src/secureHeaders
+    // https://github.com/venables/koa-helmet
+    // .use(SecureHeaders.middleware)
+    .use(contextMiddleware)
+    .use(requestLogging)
+    .use(metrics)
+    .use(ErrorMiddleware.handle)
+    .use(version)
+    .use(compose(middleware));

package/template/koa-rest-api/src/framework/validation.test.ts

@@ -0,0 +1,72 @@
+import { agentFromMiddleware } from 'src/testing/server';
+import {
+  IdDescriptionSchema,
+  chance,
+  mockIdDescription,
+} from 'src/testing/types';
+
+import { jsonBodyParser } from './middleware';
+import { validate } from './validation';
+
+const agent = agentFromMiddleware(jsonBodyParser, (ctx) => {
+  const result = validate({
+    ctx,
+    input: ctx.request.body,
+    schema: IdDescriptionSchema,
+  });
+
+  ctx.body = result;
+});
+
+describe('validate', () => {
+  it('permits valid input', () => {
+    const idDescription = mockIdDescription();
+
+    return agent.post('/').send(idDescription).expect(200, idDescription);
+  });
+
+  it('filters additional properties', () => {
+    const idDescription = mockIdDescription();
+
+    return agent
+      .post('/')
+      .send({ ...idDescription, hacker: chance.name() })
+      .expect(200, idDescription);
+  });
+
+  it('blocks mistyped prop', () => {
+    const idDescription = mockIdDescription();
+
+    return agent
+      .post('/')
+      .send({ ...idDescription, id: null })
+      .expect(422)
+      .expect(({ body }) =>
+        expect(body).toMatchInlineSnapshot(`
+          {
+            "invalidFields": {
+              "/id": "Expected string, received null",
+            },
+            "message": "Input validation failed",
+          }
+        `),
+      );
+  });
+
+  it('blocks missing props', () =>
+    agent
+      .post('/')
+      .send({})
+      .expect(422)
+      .expect(({ body }) =>
+        expect(body).toMatchInlineSnapshot(`
+          {
+            "invalidFields": {
+              "/description": "Required",
+              "/id": "Required",
+            },
+            "message": "Input validation failed",
+          }
+        `),
+      ));
+});

package/template/koa-rest-api/src/framework/validation.ts

@@ -0,0 +1,77 @@
+import { ErrorMiddleware } from 'seek-koala';
+import type { z } from 'zod';
+
+import type { Context } from 'src/types/koa';
+
+/**
+ * Converts a `ZodError` into an `invalidFields` object
+ *
+ * For example, the `ZodError`:
+ *
+ * ```json
+ * {
+ *   "issues": [
+ *     {
+ *       "code": "invalid_type",
+ *       "expected": "string",
+ *       "received": "undefined",
+ *       "path": ["advertiserId"],
+ *       "message": "advertiserId is required in the URL"
+ *     }
+ *   ],
+ *   "name": "ZodError"
+ * }
+ * ```
+ *
+ * Returns:
+ *
+ * ```json
+ * { "/advertiserId": "advertiserId is required in the URL" }
+ * ```
+ */
+const parseInvalidFieldsFromError = ({
+  errors,
+}: z.ZodError): Record<string, string> =>
+  Object.fromEntries(
+    errors.map((err) => [`/${err.path.join('/')}`, err.message]),
+  );
+
+export const validate = <
+  Output,
+  Def extends z.ZodTypeDef = z.ZodTypeDef,
+  Input = Output,
+>({
+  ctx,
+  input,
+  schema,
+}: {
+  ctx: Context;
+  input: unknown;
+  schema: z.ZodSchema<Output, Def, Input>;
+}): Output => {
+  const parseResult = schema.safeParse(input);
+  if (parseResult.success === false) {
+    return ctx.throw(
+      422,
+      new ErrorMiddleware.JsonResponse('Input validation failed', {
+        message: 'Input validation failed',
+        invalidFields: parseInvalidFieldsFromError(parseResult.error),
+      }),
+    );
+  }
+  return parseResult.data;
+};
+
+export const validateRequestBody = <
+  Output,
+  Def extends z.ZodTypeDef = z.ZodTypeDef,
+  Input = Output,
+>(
+  ctx: Context,
+  schema: z.ZodSchema<Output, Def, Input>,
+): Output =>
+  validate<Output, Def, Input>({
+    ctx,
+    input: ctx.request.body as unknown,
+    schema,
+  });