skuba 0.0.0-master-20230318044948

package/template/lambda-sqs-worker/src/app.ts

@@ -0,0 +1,52 @@
+import 'skuba-dive/register';
+
+import { SQSEvent } from 'aws-lambda';
+
+import { createHandler } from 'src/framework/handler';
+import { logger } from 'src/framework/logging';
+import { metricsClient } from 'src/framework/metrics';
+import { validateJson } from 'src/framework/validation';
+import { scoreJobPublishedEvent, scoringService } from 'src/services/jobScorer';
+import { sendPipelineEvent } from 'src/services/pipelineEventSender';
+import { JobPublishedEventSchema } from 'src/types/pipelineEvents';
+
+/**
+ * Tests connectivity to ensure appropriate access and network configuration.
+ */
+const smokeTest = async () => {
+  await Promise.all([scoringService.smokeTest(), sendPipelineEvent({}, true)]);
+};
+
+export const handler = createHandler<SQSEvent>(async (event) => {
+  // Treat an empty object as our smoke test event.
+  if (!Object.keys(event).length) {
+    logger.info('Received smoke test request');
+    return smokeTest();
+  }
+
+  const count = event.Records.length;
+
+  if (count !== 1) {
+    throw Error(`Received ${count} records`);
+  }
+
+  logger.info({ count }, 'Received jobs');
+
+  metricsClient.distribution('job.received', event.Records.length);
+
+  const record = event.Records[0];
+
+  // TODO: this throws an error, which will cause the Lambda function to retry
+  // the event and eventually send it to your dead-letter queue. If you don't
+  // trust your source to provide consistently well-formed input, consider
+  // catching and handling this error in code.
+  const publishedJob = validateJson(record.body, JobPublishedEventSchema);
+
+  const scoredJob = await scoreJobPublishedEvent(publishedJob);
+
+  const snsMessageId = await sendPipelineEvent(scoredJob);
+
+  logger.info({ snsMessageId }, 'Scored job');
+
+  metricsClient.distribution('job.scored', 1);
+});

package/template/lambda-sqs-worker/src/config.ts

@@ -0,0 +1,57 @@
+import { Env } from 'skuba-dive';
+
+interface Config {
+  environment: Environment;
+
+  logLevel: string;
+  metrics: boolean;
+  name: string;
+  version: string;
+
+  destinationSnsTopicArn: string;
+}
+
+type Environment = (typeof environments)[number];
+
+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',
+    metrics: false,
+    name: '<%- serviceName %>',
+    version: 'local',
+
+    destinationSnsTopicArn: 'arn:aws:sns:us-east-2:123456789012:destination',
+  }),
+
+  test: () => ({
+    ...configs.local(),
+
+    logLevel: Env.string('LOG_LEVEL', { default: 'silent' }),
+    version: 'test',
+  }),
+
+  dev: () => ({
+    ...configs.prod(),
+
+    logLevel: 'debug',
+  }),
+
+  prod: () => ({
+    logLevel: 'info',
+    metrics: true,
+    name: Env.string('SERVICE'),
+    version: Env.string('VERSION'),
+
+    destinationSnsTopicArn: Env.string('DESTINATION_SNS_TOPIC_ARN'),
+  }),
+};
+
+export const config: Config = {
+  ...configs[environment](),
+  environment,
+};

package/template/lambda-sqs-worker/src/framework/handler.test.ts

@@ -0,0 +1,61 @@
+import { createCtx } from 'src/testing/handler';
+import { logger } from 'src/testing/logging';
+import { chance } from 'src/testing/types';
+
+import { createHandler } from './handler';
+
+describe('createHandler', () => {
+  const ctx = createCtx();
+  const input = chance.paragraph();
+
+  beforeAll(logger.spy);
+
+  afterEach(logger.clear);
+
+  it('handles happy path', async () => {
+    const output = chance.paragraph();
+
+    const handler = createHandler((event) => {
+      expect(event).toBe(input);
+
+      logger.info('Handler invoked');
+
+      return Promise.resolve(output);
+    });
+
+    await expect(handler(input, ctx)).resolves.toBe(output);
+
+    expect(logger.error).not.toHaveBeenCalled();
+
+    expect(logger.info.mock.calls).toEqual([
+      ['Handler invoked'],
+      ['Function succeeded'],
+    ]);
+  });
+
+  it('handles async error', async () => {
+    const err = Error(chance.sentence());
+
+    const handler = createHandler(() => Promise.reject(err));
+
+    await expect(handler(input, ctx)).rejects.toThrow('Function failed');
+
+    expect(logger.error).toHaveBeenCalledWith({ err }, 'Function failed');
+
+    expect(logger.info).not.toHaveBeenCalled();
+  });
+
+  it('handles sync error', async () => {
+    const err = Error(chance.sentence());
+
+    const handler = createHandler(() => {
+      throw err;
+    });
+
+    await expect(handler(input, ctx)).rejects.toThrow('Function failed');
+
+    expect(logger.error).toHaveBeenCalledWith({ err }, 'Function failed');
+
+    expect(logger.info).not.toHaveBeenCalled();
+  });
+});

package/template/lambda-sqs-worker/src/framework/handler.ts

@@ -0,0 +1,43 @@
+import { datadog } from 'datadog-lambda-js';
+
+import { config } from 'src/config';
+import { logger, loggerContext } from 'src/framework/logging';
+
+interface LambdaContext {
+  awsRequestId: string;
+}
+
+type Handler<Event, Output> = (
+  event: Event,
+  ctx: LambdaContext,
+) => Promise<Output>;
+
+/**
+ * Conditionally applies the Datadog wrapper to a Lambda handler.
+ *
+ * This also "fixes" its broken type definitions.
+ */
+const withDatadog = <Event, Output = unknown>(
+  fn: Handler<Event, Output>,
+): Handler<Event, Output> =>
+  // istanbul ignore next
+  config.metrics ? (datadog(fn) as Handler<Event, Output>) : fn;
+
+export const createHandler = <Event, Output = unknown>(
+  fn: (event: Event) => Promise<Output>,
+) =>
+  withDatadog<Event>((event, { awsRequestId }) =>
+    loggerContext.run({ awsRequestId }, async () => {
+      try {
+        const output = await fn(event);
+
+        logger.info('Function succeeded');
+
+        return output;
+      } catch (err) {
+        logger.error({ err }, 'Function failed');
+
+        throw new Error('Function failed');
+      }
+    }),
+  );

package/template/lambda-sqs-worker/src/framework/logging.ts

@@ -0,0 +1,27 @@
+import { AsyncLocalStorage } from 'async_hooks';
+
+import createLogger from '@seek/logger';
+
+import { config } from 'src/config';
+
+interface LoggerContext {
+  awsRequestId: string;
+}
+
+export const loggerContext = new AsyncLocalStorage<LoggerContext>();
+
+export const logger = createLogger({
+  base: {
+    environment: config.environment,
+    version: config.version,
+  },
+
+  level: config.logLevel,
+
+  mixin: () => ({ ...loggerContext.getStore() }),
+
+  name: config.name,
+
+  transport:
+    config.environment === 'local' ? { target: 'pino-pretty' } : undefined,
+});

package/template/lambda-sqs-worker/src/framework/metrics.ts

@@ -0,0 +1,14 @@
+import { sendDistributionMetric } from 'datadog-lambda-js';
+
+import { config } from 'src/config';
+
+const prefix = `${config.name}.`;
+
+export const metricsClient = {
+  distribution: (
+    ...[name, ...rest]: Parameters<typeof sendDistributionMetric>
+  ) =>
+    config.metrics
+      ? sendDistributionMetric(`${prefix}${name}`, ...rest)
+      : undefined,
+};

package/template/lambda-sqs-worker/src/framework/validation.test.ts

@@ -0,0 +1,84 @@
+import {
+  IdDescriptionSchema,
+  chance,
+  mockIdDescription,
+} from 'src/testing/types';
+
+import { validateJson } from './validation';
+
+describe('validateJson', () => {
+  const idDescription = mockIdDescription();
+
+  it('permits valid input', () => {
+    const input = JSON.stringify(idDescription);
+
+    expect(validateJson(input, IdDescriptionSchema)).toStrictEqual(
+      idDescription,
+    );
+  });
+
+  it('filters additional properties', () => {
+    const input = JSON.stringify({ ...idDescription, hacker: chance.name() });
+
+    expect(validateJson(input, IdDescriptionSchema)).toStrictEqual(
+      idDescription,
+    );
+  });
+
+  it('blocks mistyped prop', () => {
+    const input = JSON.stringify({ ...idDescription, id: null });
+
+    expect(() => validateJson(input, IdDescriptionSchema))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "[
+        {
+          "code": "invalid_type",
+          "expected": "string",
+          "received": "null",
+          "path": [
+            "id"
+          ],
+          "message": "Expected string, received null"
+        }
+      ]"
+    `);
+  });
+
+  it('blocks missing prop', () => {
+    const input = '{}';
+
+    expect(() => validateJson(input, IdDescriptionSchema))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "[
+        {
+          "code": "invalid_type",
+          "expected": "string",
+          "received": "undefined",
+          "path": [
+            "id"
+          ],
+          "message": "Required"
+        },
+        {
+          "code": "invalid_type",
+          "expected": "string",
+          "received": "undefined",
+          "path": [
+            "description"
+          ],
+          "message": "Required"
+        }
+      ]"
+    `);
+  });
+
+  it('blocks invalid JSON', () => {
+    const input = '}';
+
+    expect(() =>
+      validateJson(input, IdDescriptionSchema),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Unexpected token } in JSON at position 0"`,
+    );
+  });
+});

package/template/lambda-sqs-worker/src/framework/validation.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+
+export const validateJson = <
+  Output,
+  Def extends z.ZodTypeDef = z.ZodTypeDef,
+  Input = Output,
+>(
+  input: string,
+  schema: z.ZodSchema<Output, Def, Input>,
+): Output => schema.parse(JSON.parse(input));

package/template/lambda-sqs-worker/src/hooks.ts

@@ -0,0 +1,96 @@
+/* eslint-disable no-console */
+/* istanbul ignore file */
+
+// Use minimal dependencies to reduce the chance of crashes on module load.
+import {
+  CodeDeployClient,
+  PutLifecycleEventHookExecutionStatusCommand,
+} from '@aws-sdk/client-codedeploy';
+import { InvokeCommand, LambdaClient } from '@aws-sdk/client-lambda';
+import { toUtf8 } from '@aws-sdk/util-utf8-node';
+
+const codeDeploy = new CodeDeployClient({
+  apiVersion: '2014-10-06',
+  maxAttempts: 5,
+});
+
+const lambda = new LambdaClient({
+  apiVersion: '2015-03-31',
+  maxAttempts: 5,
+});
+
+type Status = 'Succeeded' | 'Failed';
+
+/**
+ * Synchronously invokes a Lambda function with a smoke test event.
+ *
+ * Any non-error response is treated as a success.
+ */
+const smokeTestLambdaFunction = async (): Promise<Status> => {
+  const functionName = process.env.FUNCTION_NAME_TO_INVOKE;
+
+  if (!functionName) {
+    console.error('Missing process.env.FUNCTION_NAME_TO_INVOKE');
+    return 'Failed';
+  }
+
+  console.info('Function:', functionName);
+
+  const response = await lambda.send(
+    new InvokeCommand({
+      FunctionName: functionName,
+      InvocationType: 'RequestResponse',
+      // Treat an empty object as our smoke test event.
+      Payload: Buffer.from('{}'),
+    }),
+  );
+
+  console.info('Version:', response.ExecutedVersion ?? '?');
+  console.info('Status', response.StatusCode ?? '?');
+
+  if (response.FunctionError) {
+    console.error('Error:', response.FunctionError);
+    if (response.Payload) {
+      console.error(toUtf8(response.Payload));
+    }
+    return 'Failed';
+  }
+
+  return response.StatusCode === 200 ? 'Succeeded' : 'Failed';
+};
+
+/**
+ * The event supplied to a CodeDeploy lifecycle hook Lambda function.
+ *
+ * {@link https://docs.aws.amazon.com/codedeploy/latest/userguide/tutorial-ecs-with-hooks-create-hooks.html}
+ */
+interface CodeDeployLifecycleHookEvent {
+  DeploymentId: string;
+  LifecycleEventHookExecutionId: string;
+}
+
+/**
+ * A handler to smoke test a new Lambda function version before it goes live.
+ *
+ * This tries to be exception safe so that a status reaches CodeDeploy. If we
+ * crash or otherwise fail to report back, the deployment will hang for an hour.
+ */
+export const pre = async (
+  event: CodeDeployLifecycleHookEvent,
+): Promise<void> => {
+  let status: Status;
+  try {
+    status = await smokeTestLambdaFunction();
+  } catch (err) {
+    console.error('Exception:', err);
+    status = 'Failed';
+  }
+
+  await codeDeploy.send(
+    new PutLifecycleEventHookExecutionStatusCommand({
+      deploymentId: event.DeploymentId,
+      lifecycleEventHookExecutionId: event.LifecycleEventHookExecutionId,
+      status,
+    }),
+  );
+};

package/template/lambda-sqs-worker/src/mapping/jobScorer.ts

@@ -0,0 +1,19 @@
+import { JobScorerInput, JobScorerOutput } from 'src/types/jobScorer';
+import { JobPublishedEvent, JobScoredEvent } from 'src/types/pipelineEvents';
+
+export const jobPublishedEventToScorerInput = (
+  record: JobPublishedEvent,
+): JobScorerInput => ({
+  details: record.data.details,
+  id: record.entityId,
+});
+
+export const jobScorerOutputToScoredEvent = (
+  output: JobScorerOutput,
+): JobScoredEvent => ({
+  data: {
+    score: output.score,
+  },
+  entityId: output.id,
+  eventType: 'JobScored',
+});

package/template/lambda-sqs-worker/src/services/aws.ts

@@ -0,0 +1,5 @@
+import { SNSClient } from '@aws-sdk/client-sns';
+
+export const sns = new SNSClient({
+  apiVersion: '2010-03-31',
+});

package/template/lambda-sqs-worker/src/services/jobScorer.test.ts

@@ -0,0 +1,44 @@
+import { scoringService } from 'src/testing/services';
+import { chance, mockJobPublishedEvent } from 'src/testing/types';
+
+import * as jobScorer from './jobScorer';
+
+describe('scoreJobPublishedEvent', () => {
+  beforeAll(scoringService.spy);
+
+  afterEach(scoringService.clear);
+
+  it('scores an event', async () => {
+    const score = chance.floating({ max: 1, min: 0 });
+
+    scoringService.request.mockResolvedValue(score);
+
+    await expect(
+      jobScorer.scoreJobPublishedEvent(
+        mockJobPublishedEvent({ entityId: '1' }),
+      ),
+    ).resolves.toStrictEqual({
+      data: {
+        score,
+      },
+      entityId: '1',
+      eventType: 'JobScored',
+    });
+
+    expect(scoringService.request).toHaveBeenCalledTimes(1);
+  });
+
+  it('bubbles up scoring service error', async () => {
+    const err = Error(chance.sentence());
+
+    scoringService.request.mockRejectedValue(err);
+
+    await expect(
+      jobScorer.scoreJobPublishedEvent(
+        mockJobPublishedEvent({ entityId: '1' }),
+      ),
+    ).rejects.toThrow(err);
+
+    expect(scoringService.request).toHaveBeenCalledTimes(1);
+  });
+});

package/template/lambda-sqs-worker/src/services/jobScorer.ts

@@ -0,0 +1,56 @@
+import {
+  jobPublishedEventToScorerInput,
+  jobScorerOutputToScoredEvent,
+} from 'src/mapping/jobScorer';
+import {
+  JobScorerInput,
+  JobScorerOutput,
+  JobScorerOutputSchema,
+} from 'src/types/jobScorer';
+import { JobPublishedEvent, JobScoredEvent } from 'src/types/pipelineEvents';
+
+/* istanbul ignore next: simulation of an external service */
+export const scoringService = {
+  request: (details: string): Promise<unknown> => {
+    // Networking woes
+    if (Math.random() < 0.05) {
+      const err = Error('could not reach scoring service');
+
+      return Promise.reject(err);
+    }
+
+    // Unexpected behaviour on certain inputs
+    if (details.length % 100 === 0) {
+      return Promise.resolve(null);
+    }
+
+    return Promise.resolve(Math.random());
+  },
+
+  smokeTest: async (): Promise<void> => {
+    // A connectivity test
+    await Promise.resolve();
+  },
+};
+
+const scoreJob = async ({
+  details,
+  id,
+}: JobScorerInput): Promise<JobScorerOutput> => {
+  const score = await scoringService.request(details);
+
+  return JobScorerOutputSchema.parse({
+    id,
+    score,
+  });
+};
+
+export const scoreJobPublishedEvent = async (
+  publishedJob: JobPublishedEvent,
+): Promise<JobScoredEvent> => {
+  const scorerInput = jobPublishedEventToScorerInput(publishedJob);
+
+  const scorerOutput = await scoreJob(scorerInput);
+
+  return jobScorerOutputToScoredEvent(scorerOutput);
+};

package/template/lambda-sqs-worker/src/services/pipelineEventSender.test.ts

@@ -0,0 +1,40 @@
+import { PublishCommand } from '@aws-sdk/client-sns';
+
+import { sns } from 'src/testing/services';
+import { chance } from 'src/testing/types';
+
+import { sendPipelineEvent } from './pipelineEventSender';
+
+describe('sendPipelineEvent', () => {
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('handles happy path', async () => {
+    const messageId = chance.guid({ version: 4 });
+
+    sns.publish.resolves({ MessageId: messageId });
+
+    await expect(sendPipelineEvent({})).resolves.toBe(messageId);
+
+    expect(sns.client).toReceiveCommandTimes(PublishCommand, 1);
+  });
+
+  it('bubbles up SNS error', () => {
+    const err = Error(chance.sentence());
+
+    sns.publish.rejects(err);
+
+    return expect(sendPipelineEvent({})).rejects.toThrow(err);
+  });
+
+  it('throws on missing message ID', () => {
+    sns.publish.resolves({});
+
+    return expect(
+      sendPipelineEvent({}),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `"SNS did not return a message ID"`,
+    );
+  });
+});

package/template/lambda-sqs-worker/src/services/pipelineEventSender.ts

@@ -0,0 +1,33 @@
+import { PublishCommand } from '@aws-sdk/client-sns';
+
+import { config } from 'src/config';
+
+import { sns } from './aws';
+
+export const sendPipelineEvent = async (
+  event: unknown,
+  smokeTest: boolean = false,
+): Promise<string> => {
+  const snsResponse = await sns.send(
+    new PublishCommand({
+      Message: JSON.stringify(event),
+      ...(smokeTest && {
+        MessageAttributes: {
+          // Used for connectivity tests.
+          // Subscribers should filter out messages containing this attribute.
+          SmokeTest: {
+            DataType: 'String',
+            StringValue: 'true',
+          },
+        },
+      }),
+      TopicArn: config.destinationSnsTopicArn,
+    }),
+  );
+
+  if (snsResponse.MessageId === undefined) {
+    throw Error('SNS did not return a message ID');
+  }
+
+  return snsResponse.MessageId;
+};

package/template/lambda-sqs-worker/src/testing/handler.ts

@@ -0,0 +1,13 @@
+import { Context, SQSEvent } from 'aws-lambda';
+
+import { chance } from './types';
+
+export const createCtx = () =>
+  ({
+    awsRequestId: chance.guid({ version: 4 }),
+  } as Context);
+
+export const createSqsEvent = (bodies: string[]) =>
+  ({
+    Records: bodies.map((body) => ({ body })),
+  } as SQSEvent);

package/template/lambda-sqs-worker/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);
+  },
+};