skuba 0.0.0-master-20230318044948

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 { 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: 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 { z } from 'zod';
+
+import { 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,
+  });

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

@@ -0,0 +1,24 @@
+import './register';
+
+import app from './app';
+import { config } from './config';
+import { logger } from './framework/logging';
+
+// This implements a minimal version of `koa-cluster`'s interface
+// If your application is deployed with more than 1 vCPU you can delete this
+// file and use `koa-cluster` to run `lib/app`.
+
+const listener = app.listen(config.port, () => {
+  const address = listener.address();
+
+  if (typeof address === 'object' && address) {
+    logger.debug(`listening on port ${address.port}`);
+  }
+});
+
+// Gantry ALB default idle timeout is 30 seconds
+// https://nodejs.org/docs/latest-v18.x/api/http.html#serverkeepalivetimeout
+// Node default is 5 seconds
+// https://docs.aws.amazon.com/elasticloadbalancing/latest/application/application-load-balancers.html#connection-idle-timeout
+// AWS recommends setting an application timeout larger than the load balancer
+listener.keepAliveTimeout = 31000;

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

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

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

@@ -0,0 +1,28 @@
+import { randomUUID } from 'crypto';
+
+import { Job, JobInput } from 'src/types/jobs';
+
+const jobStore: Record<string, Job> = {};
+
+export const createJob = (jobInput: JobInput): Promise<Job> => {
+  const id = randomUUID();
+
+  const job = { ...jobInput, id };
+
+  jobStore[id] = job;
+
+  return Promise.resolve(job);
+};
+
+export const readJobs = (): Promise<Job[]> => {
+  const jobs = Object.values(jobStore);
+
+  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();
+};

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

@@ -0,0 +1,16 @@
+import * as logging from 'src/framework/logging';
+
+export const logger = {
+  error: jest.fn(),
+  info: jest.fn(),
+
+  clear: () => {
+    logger.error.mockClear();
+    logger.info.mockClear();
+  },
+
+  spy: () => {
+    jest.spyOn(logging.logger, 'error').mockImplementation(logger.error);
+    jest.spyOn(logging.logger, 'info').mockImplementation(logger.info);
+  },
+};

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

@@ -0,0 +1,29 @@
+import * as metrics from 'src/framework/metrics';
+
+function assertDefined<T>(value: T | undefined): asserts value is T {
+  expect(value).toBeDefined();
+}
+
+export const metricsClient = {
+  clear: () => (metrics.metricsClient.mockBuffer = []),
+
+  expectTagSubset: (subset: string[], index: number = 0) => {
+    const tags = metricsClient.tags(index);
+
+    subset.forEach((tag) => expect(tags).toContain(tag));
+  },
+
+  tags: (index: number = 0) => {
+    assertDefined(metrics.metricsClient.mockBuffer);
+
+    const line = metrics.metricsClient.mockBuffer[index];
+
+    assertDefined(line);
+
+    const [, tagString] = line.split('#', 2);
+
+    assertDefined(tagString);
+
+    return tagString.split(',');
+  },
+};

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

@@ -0,0 +1,31 @@
+import Router from '@koa/router';
+import Koa from 'koa';
+import request from 'supertest';
+
+import { createApp } from 'src/framework/server';
+
+/**
+ * Create a new SuperTest agent from a Koa application.
+ */
+export const agentFromApp = <State, Context>(app: Koa<State, Context>) =>
+  request.agent(app.callback());
+
+/**
+ * Create a new SuperTest agent from a set of Koa middleware.
+ */
+export const agentFromMiddleware = <State, Context>(
+  ...middleware: Koa.Middleware<State, Context>[]
+) => {
+  const app = createApp(...middleware);
+
+  return agentFromApp(app);
+};
+
+/**
+ * Create a new SuperTest agent from a Koa router.
+ */
+export const agentFromRouter = (router: Router) => {
+  const app = createApp(router.routes(), router.allowedMethods());
+
+  return agentFromApp(app);
+};

package/template/koa-rest-api/src/testing/types.ts

@@ -0,0 +1,24 @@
+import { Chance } from 'chance';
+import { z } from 'zod';
+
+import { JobInput } from 'src/types/jobs';
+
+export type IdDescription = z.infer<typeof IdDescriptionSchema>;
+
+export const IdDescriptionSchema = z.object({
+  id: z.string(),
+  description: z.string(),
+});
+
+export const chance = new Chance();
+
+export const mockIdDescription = (): IdDescription => ({
+  id: chance.guid({ version: 4 }),
+  description: chance.sentence(),
+});
+
+export const mockJobInput = (): JobInput => ({
+  hirer: {
+    id: chance.guid({ version: 4 }),
+  },
+});

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

@@ -0,0 +1,61 @@
+/**
+ * OpenTelemetry tracing initialisation. This is a standalone TS/JS module that is not
+ * referenced by application source code directly. It is required at runtime using the
+ * node command's `--require` argument, see Dockerfile for details.
+ */
+
+import { propagation } from '@opentelemetry/api';
+import { CompositePropagator } from '@opentelemetry/core';
+import { CollectorTraceExporter } from '@opentelemetry/exporter-collector-grpc';
+import { AwsInstrumentation } from '@opentelemetry/instrumentation-aws-sdk';
+import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+import { B3InjectEncoding, B3Propagator } from '@opentelemetry/propagator-b3';
+import { NodeSDK } from '@opentelemetry/sdk-node';
+
+const app = 'opentelemetry';
+const log = (level: string, msg: string, extra = {}) => {
+  const toLog = { msg, level, app, time: new Date().toISOString(), ...extra };
+  console.log(JSON.stringify(toLog)); // eslint-disable-line no-console
+};
+
+const main = () => {
+  // Use B3 propagation to ensure proper propagation between systems that use
+  // OpenTelemetry and native Datadog APM, such as Istio/Envoy.
+  propagation.setGlobalPropagator(
+    new CompositePropagator({
+      propagators: [
+        new B3Propagator(),
+        new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER }),
+      ],
+    }),
+  );
+
+  const sdk = new NodeSDK({
+    traceExporter: new CollectorTraceExporter(),
+    autoDetectResources: false,
+    instrumentations: [new HttpInstrumentation(), new AwsInstrumentation()],
+  });
+
+  sdk
+    .start()
+    .then(() => log('info', 'OpenTelemetry initialised'))
+    .catch((err: Error) =>
+      log('error', 'OpenTelemetry not initialised', { err }),
+    );
+
+  process.on('SIGTERM', () => {
+    sdk
+      .shutdown()
+      .then(() => log('info', 'OpenTelemetry successfully terminated'))
+      .catch((err: Error) =>
+        log('error', 'OpenTelemetry failed to terminate', { err }),
+      )
+      .finally(() => process.exit(0)); // eslint-disable-line no-process-exit
+  });
+};
+
+if (process.env.OPENTELEMETRY_ENABLED === 'true') {
+  main();
+} else {
+  log('info', 'OpenTelemetry not enabled');
+}

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

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+
+export interface Job {
+  id: string;
+
+  hirer: {
+    id: string;
+  };
+}
+
+export type JobInput = z.infer<typeof JobInputSchema>;
+
+export const JobInputSchema = z.object({
+  hirer: z.object({
+    id: z.string(),
+  }),
+});