skuba 9.0.0 → 9.0.1-upgrade-cdk-template-20241002233314

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

@@ -0,0 +1,116 @@
+import { PublishCommand } from '@aws-sdk/client-sns';
+
+import { metricsClient } from 'src/framework/metrics';
+import { createCtx, createSqsEvent } from 'src/testing/handler';
+import { logger } from 'src/testing/logging';
+import { scoringService, sns } from 'src/testing/services';
+import { chance, mockJobPublishedEvent } from 'src/testing/types';
+
+import * as app from './app';
+
+describe('app', () => {
+  it('exports a handler', () => expect(app).toHaveProperty('handler'));
+});
+
+describe('handler', () => {
+  const ctx = createCtx();
+
+  const jobPublished = mockJobPublishedEvent({ entityId: chance.name() });
+
+  const score = chance.floating({ max: 1, min: 0 });
+
+  const distribution = jest
+    .spyOn(metricsClient, 'distribution')
+    .mockReturnValue();
+
+  beforeAll(logger.spy);
+  beforeAll(scoringService.spy);
+
+  beforeEach(() => {
+    scoringService.request.mockResolvedValue(score);
+    sns.publish.resolves({ MessageId: chance.guid({ version: 4 }) });
+  });
+
+  afterEach(() => {
+    logger.clear();
+    distribution.mockClear();
+    scoringService.clear();
+    sns.clear();
+  });
+
+  it('handles one record', async () => {
+    const event = createSqsEvent([JSON.stringify(jobPublished)]);
+
+    await expect(app.handler(event, ctx)).resolves.toBeUndefined();
+
+    expect(scoringService.request).toHaveBeenCalledTimes(1);
+
+    expect(logger.error).not.toHaveBeenCalled();
+
+    expect(logger.debug.mock.calls).toEqual([
+      [{ count: 1 }, 'Received jobs'],
+      [{ snsMessageId: expect.any(String) }, 'Scored job'],
+      ['Function succeeded'],
+    ]);
+
+    expect(distribution.mock.calls).toEqual([
+      ['job.received', 1],
+      ['job.scored', 1],
+    ]);
+
+    expect(sns.client).toReceiveCommandTimes(PublishCommand, 1);
+  });
+
+  it('throws on invalid input', () => {
+    const event = createSqsEvent(['}']);
+
+    return expect(app.handler(event, ctx)).rejects.toThrow('Function failed');
+  });
+
+  it('bubbles up scoring service error', async () => {
+    const err = Error(chance.sentence());
+
+    scoringService.request.mockRejectedValue(err);
+
+    const event = createSqsEvent([JSON.stringify(jobPublished)]);
+
+    await expect(app.handler(event, ctx)).rejects.toThrow('Function failed');
+
+    expect(logger.error).toHaveBeenCalledWith({ err }, 'Function failed');
+  });
+
+  it('bubbles up SNS error', async () => {
+    const err = Error(chance.sentence());
+
+    sns.publish.rejects(err);
+
+    const event = createSqsEvent([JSON.stringify(jobPublished)]);
+
+    await expect(app.handler(event, ctx)).rejects.toThrow('Function failed');
+
+    expect(logger.error).toHaveBeenCalledWith({ err }, 'Function failed');
+  });
+
+  it('throws on zero records', async () => {
+    const err = new Error('Received 0 records');
+
+    const event = createSqsEvent([]);
+
+    await expect(app.handler(event, ctx)).rejects.toThrow('Function failed');
+
+    expect(logger.error).toHaveBeenCalledWith({ err }, 'Function failed');
+  });
+
+  it('throws on multiple records', async () => {
+    const err = new Error('Received 2 records');
+
+    const event = createSqsEvent([
+      JSON.stringify(jobPublished),
+      JSON.stringify(jobPublished),
+    ]);
+
+    await expect(app.handler(event, ctx)).rejects.toThrow('Function failed');
+
+    expect(logger.error).toHaveBeenCalledWith({ err }, 'Function failed');
+  });
+});

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

@@ -1,35 +1,57 @@
-import createLogger from '@seek/logger';
-import type { SQSEvent, SQSHandler } from 'aws-lambda';
+import 'skuba-dive/register';
 
-import { config } from './config';
+import type { SQSEvent } from 'aws-lambda';
 
-export const logger = createLogger({
-  base: {
-    environment: config.environment,
-    version: config.version,
-  },
-
-  level: config.logLevel,
-
-  name: config.name,
-
-  transport:
-    config.environment === 'local' ? { target: 'pino-pretty' } : undefined,
-});
+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 () => Promise.resolve();
+const smokeTest = async () => {
+  await Promise.all([scoringService.smokeTest(), sendPipelineEvent({}, true)]);
+};
 
-export const handler: SQSHandler = (event: SQSEvent) => {
+export const handler = createHandler<SQSEvent>(async (event) => {
   // Treat an empty object as our smoke test event.
   if (!Object.keys(event).length) {
     logger.debug('Received smoke test request');
     return smokeTest();
   }
 
-  logger.info('Hello World!');
+  const count = event.Records.length;
 
-  return;
-};
+  if (count !== 1) {
+    throw Error(`Received ${count} records`);
+  }
+
+  logger.debug({ count }, 'Received jobs');
+
+  metricsClient.distribution('job.received', event.Records.length);
+
+  const record = event.Records[0];
+  if (!record) {
+    throw new Error('Malformed SQS event with no records');
+  }
+
+  const { body } = record;
+
+  // 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(body, JobPublishedEventSchema);
+
+  const scoredJob = await scoreJobPublishedEvent(publishedJob);
+
+  const snsMessageId = await sendPipelineEvent(scoredJob);
+
+  logger.debug({ snsMessageId }, 'Scored job');
+
+  metricsClient.distribution('job.scored', 1);
+});

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

@@ -4,8 +4,11 @@ interface Config {
   environment: Environment;
 
   logLevel: string;
+  metrics: boolean;
   name: string;
   version: string;
+
+  destinationSnsTopicArn: string;
 }
 
 type Environment = (typeof environments)[number];
@@ -18,26 +21,38 @@ const environment = Env.oneOf(environments)('ENVIRONMENT');
 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: () => ({
     logLevel: Env.string('LOG_LEVEL', { default: 'silent' }),
+    metrics: false,
     name: '<%- serviceName %>',
     version: 'test',
+
+    destinationSnsTopicArn: 'arn:aws:sns:us-east-2:123456789012:destination',
   }),
 
   dev: () => ({
     logLevel: 'debug',
+    metrics: true,
     name: Env.string('SERVICE'),
     version: Env.string('VERSION'),
+
+    destinationSnsTopicArn: Env.string('DESTINATION_SNS_TOPIC_ARN'),
   }),
 
   prod: () => ({
     logLevel: 'info',
+    metrics: true,
     name: Env.string('SERVICE'),
     version: Env.string('VERSION'),
+
+    destinationSnsTopicArn: Env.string('DESTINATION_SNS_TOPIC_ARN'),
   }),
 };
 

package/template/lambda-sqs-worker-cdk/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.debug('Handler invoked');
+
+      return Promise.resolve(output);
+    });
+
+    await expect(handler(input, ctx)).resolves.toBe(output);
+
+    expect(logger.error).not.toHaveBeenCalled();
+
+    expect(logger.debug.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.debug).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.debug).not.toHaveBeenCalled();
+  });
+});

package/template/lambda-sqs-worker-cdk/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.debug('Function succeeded');
+
+        return output;
+      } catch (err) {
+        logger.error({ err }, 'Function failed');
+
+        throw new Error('Function failed');
+      }
+    }),
+  );

package/template/lambda-sqs-worker-cdk/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-cdk/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-cdk/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 '}', "}" is not valid JSON"`,
+    );
+  });
+});

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

@@ -0,0 +1,10 @@
+import type { 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-cdk/src/mapping/jobScorer.ts

@@ -0,0 +1,22 @@
+import type { JobScorerInput, JobScorerOutput } from 'src/types/jobScorer';
+import type {
+  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-cdk/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-cdk/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-cdk/src/services/jobScorer.ts

@@ -0,0 +1,59 @@
+import {
+  jobPublishedEventToScorerInput,
+  jobScorerOutputToScoredEvent,
+} from 'src/mapping/jobScorer';
+import {
+  type JobScorerInput,
+  type JobScorerOutput,
+  JobScorerOutputSchema,
+} from 'src/types/jobScorer';
+import type {
+  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-cdk/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"`,
+    );
+  });
+});