skuba 0.0.0-master-20230318044948

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

@@ -0,0 +1,8 @@
+import type Koa from 'koa';
+import type { RequestLogging } from 'seek-koala';
+
+export type Context = Koa.ParameterizedContext<State>;
+
+export type Middleware = Koa.Middleware<State>;
+
+export type State = RequestLogging.State;

package/template/lambda-sqs-worker/.buildkite/pipeline.yml

@@ -0,0 +1,96 @@
+agents:
+  queue: <%- prodBuildkiteQueueName %>
+
+configs:
+  plugins:
+    - &aws-sm
+      seek-oss/aws-sm#v2.3.1:
+        env:
+          NPM_READ_TOKEN: arn:aws:secretsmanager:ap-southeast-2:987872074697:secret:npm/npm-read-token
+
+    - &docker-ecr-cache
+      seek-oss/docker-ecr-cache#v2.0.0:
+        cache-on:
+          - package.json
+          - yarn.lock
+        secrets: id=npm,src=.npmrc
+
+    - &private-npm
+      seek-oss/private-npm#v1.2.0:
+        env: NPM_READ_TOKEN
+
+  base-steps:
+    - &deploy
+      commands:
+        - echo '+++ yarn deploy'
+        - yarn deploy
+      concurrency: 1
+      plugins:
+        - artifacts#v1.9.0:
+            build: ${BUILDKITE_BUILD_ID}
+            download: lib/*
+        - *aws-sm
+        - *private-npm
+        - *docker-ecr-cache
+        - docker-compose#v4.11.0:
+            dependencies: false
+            run: app
+      retry:
+        manual:
+          # Only use this if you need to roll back a deployment ASAP.
+          # Always follow up with a proper revert or fix in Git history.
+          permit_on_passed: true
+
+env:
+  VERSION: ${BUILDKITE_COMMIT:0:7}.${BUILDKITE_BUILD_NUMBER}
+
+steps:
+  - label: 🧪 Test, Lint & Build
+    artifact_paths: lib/**/*
+    commands:
+      - echo '+++ yarn test:ci'
+      - yarn test:ci
+      - echo '--- yarn lint'
+      - yarn lint
+      - echo '--- yarn build'
+      - yarn build
+    env:
+      GET_GITHUB_TOKEN: please
+    plugins:
+      - *aws-sm
+      - *private-npm
+      - *docker-ecr-cache
+      - docker-compose#v4.11.0:
+          run: app
+    timeout_in_minutes: 10
+
+  - agents:
+      queue: <%- devBuildkiteQueueName %>
+    branches: '!renovate-*'
+    label: 🧖‍♀️ Warm Dev
+    command: ':'
+    plugins:
+      - *aws-sm
+      - *private-npm
+      - *docker-ecr-cache
+
+  - wait
+  - block: 🙋🏻‍♀️ Deploy Dev
+    branches: '!${BUILDKITE_PIPELINE_DEFAULT_BRANCH}'
+
+  - <<: *deploy
+    agents:
+      queue: <%- devBuildkiteQueueName %>
+    env:
+      ENVIRONMENT: dev
+    concurrency_group: <%- repoName %>/deploy/dev
+    label: 🤞 Deploy Dev
+
+  - wait
+
+  - <<: *deploy
+    env:
+      ENVIRONMENT: prod
+    branches: ${BUILDKITE_PIPELINE_DEFAULT_BRANCH}
+    concurrency_group: <%- repoName %>/deploy/prod
+    label: 🚀 Deploy Prod

package/template/lambda-sqs-worker/.env

@@ -0,0 +1 @@
+ENVIRONMENT=local

package/template/lambda-sqs-worker/.nvmrc

@@ -0,0 +1 @@
+18

package/template/lambda-sqs-worker/Dockerfile

@@ -0,0 +1,12 @@
+# syntax=docker/dockerfile:1.2
+
+FROM --platform=${BUILDPLATFORM:-<%- platformName %>} node:18-alpine AS dev-deps
+
+WORKDIR /workdir
+
+COPY package.json yarn.lock ./
+
+RUN \
+  --mount=type=secret,id=npm,dst=/workdir/.npmrc \
+  yarn install --frozen-lockfile --ignore-optional --non-interactive && \
+  yarn cache clean

package/template/lambda-sqs-worker/README.md

@@ -0,0 +1,132 @@
+# <%- repoName %>
+
+[![Powered by skuba](https://img.shields.io/badge/🤿%20skuba-powered-009DC4)](https://github.com/seek-oss/skuba)
+
+Next steps:
+
+1. [ ] Finish templating if this was skipped earlier:
+
+   ```shell
+   yarn skuba configure
+   ```
+
+2. [ ] Create a new repository in the appropriate GitHub organisation.
+3. [ ] Add the repository to BuildAgency;
+       see [Builds at SEEK] for more information.
+4. [ ] Add Datadog extension, deployment bucket configuration and data classification tags to [serverless.yml](serverless.yml).
+5. [ ] Push local commits to the upstream GitHub branch.
+6. [ ] Configure [GitHub repository settings].
+7. [ ] Delete this checklist 😌.
+
+[builds at seek]: https://builds-at-seek.ssod.skinfra.xyz
+[github repository settings]: https://github.com/<%-orgName%>/<%-repoName%>/settings
+
+## Design
+
+<%-repoName %> is a Node.js [Lambda] application built in line with our [technology strategy].
+It is backed by a typical SQS message + dead letter queue configuration and uses common SEEK packages.
+Workers enable fault-tolerant asynchronous processing of events.
+
+The `lambda-sqs-worker` template is modelled after a hypothetical enricher that scores job advertisements.
+It's stubbed out with in-memory [scoring service](src/services/jobScorer.ts).
+This would be replaced with internal logic or an external service in production.
+
+This project is deployed with [Serverless].
+The Lambda runtime provisions a single Node.js process per container.
+The supplied [serverless.yml](serverless.yml) starts out with a minimal `memorySize` which may require tuning based on workload.
+Under load, we autoscale horizontally in terms of container count up to `reservedConcurrency`.
+
+Serverless configures [CodeDeploy] for a blue-green deployment approach.
+A smoke test is run against the new version before traffic is switched over,
+providing an opportunity to test access and connectivity to online dependencies.
+This defaults to an invocation with an empty object `{}`, per [src/hooks.ts](src/hooks.ts).
+
+## Development
+
+### Test
+
+```shell
+# Run Jest tests locally
+yarn test
+
+# Authenticate to dev account
+awsauth
+
+# Run smoke test against deployed application
+ENVIRONMENT=dev yarn smoke
+```
+
+### Lint
+
+```shell
+# Fix issues
+yarn format
+
+# Check for issues
+yarn lint
+```
+
+### Start
+
+```shell
+# Start a local HTTP server
+yarn start
+
+# Start with Node.js Inspector enabled
+yarn start:debug
+```
+
+This serves the Lambda application over HTTP.
+For example, to invoke the handler with an empty object `{}` for smoke testing:
+
+```shell
+curl --data '[{}, {"awsRequestId": "local"}]' --include localhost:<%- port %>
+```
+
+### Deploy
+
+This project is deployed through a [Buildkite pipeline](.buildkite/pipeline.yml).
+
+- Commits to a feature branch can be deployed to the dev environment by unblocking a step in the Buildkite UI
+- Commits to the default branch are automatically deployed to the dev and prod environments in sequence
+
+To deploy locally:
+
+```shell
+# Authenticate to dev account
+awsauth
+
+ENVIRONMENT=dev yarn deploy
+```
+
+To rapidly roll back a change,
+retry an individual deployment step from the previous build in Buildkite.
+Note that this will introduce drift between the head of the default Git branch and the live environment;
+use with caution and always follow up with a proper revert or fix in Git history.
+
+## Support
+
+### Dev
+
+TODO: add support links for the dev environment.
+
+<!--
+- CloudWatch dashboard
+- Datadog dashboard
+- Splunk logs
+-->
+
+### Prod
+
+TODO: add support links for the prod environment.
+
+<!--
+- CloudWatch dashboard
+- Datadog dashboard
+- Splunk logs
+-->
+
+[codedeploy]: https://docs.aws.amazon.com/codedeploy
+[lambda]: https://docs.aws.amazon.com/lambda
+[serverless]: https://www.serverless.com/
+[technology strategy]: https://tech-strategy.ssod.skinfra.xyz

package/template/lambda-sqs-worker/docker-compose.yml

@@ -0,0 +1,27 @@
+version: '3.7'
+
+services:
+  app:
+    environment:
+      # Enable Buildkite + GitHub integrations.
+      - BUILDKITE
+      - BUILDKITE_AGENT_ACCESS_TOKEN
+      - BUILDKITE_BRANCH
+      - BUILDKITE_BUILD_NUMBER
+      - BUILDKITE_JOB_ID
+      - BUILDKITE_PIPELINE_DEFAULT_BRANCH
+      - BUILDKITE_STEP_ID
+      - GITHUB_API_TOKEN
+      # Tag AWS resources with the commit hash.
+      - BUILDKITE_COMMIT
+      # Pass through application configuration.
+      - ENVIRONMENT
+      - VERSION
+    image: ${BUILDKITE_PLUGIN_DOCKER_IMAGE:-''}
+    init: true
+    volumes:
+      - ./:/workdir
+      # Mount agent for Buildkite annotations.
+      - /usr/bin/buildkite-agent:/usr/bin/buildkite-agent
+      # Mount cached dependencies.
+      - /workdir/node_modules

package/template/lambda-sqs-worker/package.json

@@ -0,0 +1,44 @@
+{
+  "private": true,
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "skuba build",
+    "deploy": "serverless deploy --force --verbose",
+    "format": "skuba format",
+    "lint": "skuba lint",
+    "smoke": "serverless invoke --data '{}' --function Worker",
+    "start": "skuba start --port <%- port %>",
+    "start:debug": "yarn start --inspect-brk",
+    "test": "skuba test",
+    "test:ci": "skuba test --coverage",
+    "test:watch": "skuba test --watch"
+  },
+  "dependencies": {
+    "@aws-sdk/client-codedeploy": "^3.259.0",
+    "@aws-sdk/client-lambda": "^3.259.0",
+    "@aws-sdk/client-sns": "^3.259.0",
+    "@aws-sdk/util-utf8-node": "^3.259.0",
+    "@seek/logger": "^5.0.1",
+    "datadog-lambda-js": "^6.83.0",
+    "dd-trace": "^3.8.0",
+    "skuba-dive": "^2.0.0",
+    "zod": "^3.19.1"
+  },
+  "devDependencies": {
+    "@types/aws-lambda": "^8.10.84",
+    "@types/chance": "^1.1.3",
+    "@types/node": "^18.11.9",
+    "aws-sdk-client-mock": "^2.0.1",
+    "aws-sdk-client-mock-jest": "^2.0.1",
+    "chance": "^1.1.8",
+    "pino-pretty": "^10.0.0",
+    "serverless": "^3.25.0",
+    "serverless-plugin-canary-deployments": "^0.8.0",
+    "serverless-plugin-datadog": "^5.12.0",
+    "serverless-prune-plugin": "^2.0.0",
+    "skuba": "*"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/template/lambda-sqs-worker/serverless.yml

@@ -0,0 +1,202 @@
+service: <%- serviceName %>
+
+configValidationMode: error
+
+params:
+  default:
+    datadogApiKeySecretArn: 'TODO: arn:aws:secretsmanager:${aws:region}:${aws:accountId}:secret:SECRET-NAME'
+    description: <%- description %>
+  dev:
+    deploymentBucket: 'TODO: deployment-bucket-name'
+    isProduction: false
+  prod:
+    deploymentBucket: 'TODO: deployment-bucket-name'
+    isProduction: true
+
+custom:
+  datadog:
+    addLayers: false
+    apiKeySecretArn: ${param:datadogApiKeySecretArn}
+    enableDDLogs: false
+    # TODO: enable Datadog extension
+    enabled: false
+    exclude:
+      - WorkerPreHook
+    injectLogContext: false
+    version: ${env:VERSION}
+  prune:
+    automatic: true
+    number: 3
+
+plugins:
+  - serverless-plugin-canary-deployments
+  - serverless-plugin-datadog
+  - serverless-prune-plugin
+
+provider:
+  logRetentionInDays: 30
+  name: aws
+  region: ap-southeast-2
+  runtime: nodejs18.x
+  architecture: <%- lambdaServerlessArchitecture %>
+  deploymentMethod: direct
+  stackName: ${self:service}
+  stage: ${env:ENVIRONMENT}
+  deploymentBucket:
+    # Use a shared account-level bucket for Lambda bundles and other artefacts.
+    # This is easier to manage in terms of access, deployment, and tagging.
+    name: ${param:deploymentBucket}
+  environment:
+    NODE_ENV: production
+    # https://nodejs.org/api/cli.html#cli_node_options_options
+    NODE_OPTIONS: --enable-source-maps
+  iam:
+    role:
+      statements:
+        - Action:
+            - kms:Decrypt
+            - kms:GenerateDataKey*
+          Effect: Allow
+          Resource: !GetAtt EncryptionKey.Arn
+        - Action: lambda:InvokeFunction
+          Effect: Allow
+          Resource: !Sub arn:aws:lambda:${AWS::Region}:${AWS::AccountId}:function:${self:functions.Worker.name}
+        - Action: secretsmanager:GetSecretValue
+          Effect: Allow
+          Resource: ${param:datadogApiKeySecretArn}-??????
+        - Action: sns:Publish
+          Effect: Allow
+          Resource: !Ref DestinationTopic
+  stackTags:
+    # TODO: add data classification tags
+    # https://rfc.skinfra.xyz/RFC019-AWS-Tagging-Standard.html#seekdataconsumers
+    # seek:data:consumers: internal
+    # https://rfc.skinfra.xyz/RFC019-AWS-Tagging-Standard.html#seekdatatypes
+    # seek:data:types:restricted: job-ads
+    seek:env:label: ${env:ENVIRONMENT}
+    seek:env:production: ${param:isProduction}
+    seek:owner:team: '<%- teamName %>'
+    seek:source:sha: ${env:BUILDKITE_COMMIT, 'na'}
+    seek:source:url: 'https://github.com/SEEK-Jobs/<%- repoName %>'
+
+package:
+  patterns:
+    - '!**'
+    - lib/**
+    - node_modules/**
+
+functions:
+  Worker:
+    name: ${self:service}
+    handler: lib/app.handler
+    description: ${param:description}
+    memorySize: 128
+    reservedConcurrency: 20
+    timeout: 30
+    deploymentSettings:
+      type: AllAtOnce
+      alias: Live
+      preTrafficHook: WorkerPreHook
+    environment:
+      ENVIRONMENT: ${env:ENVIRONMENT}
+      SERVICE: ${self:service}
+      VERSION: ${env:VERSION, 'local'}
+
+      DESTINATION_SNS_TOPIC_ARN: !Ref DestinationTopic
+    events:
+      - sqs:
+          arn: !GetAtt MessageQueue.Arn
+          batchSize: 1
+  WorkerPreHook:
+    name: ${self:functions.Worker.name}-pre-hook
+    handler: lib/hooks.pre
+    memorySize: 128
+    # This is generous because a timeout will hang the deployment
+    timeout: 300
+    environment:
+      FUNCTION_NAME_TO_INVOKE: ${self:functions.Worker.name}
+
+resources:
+  # This becomes the Lambda application's description
+  Description: ${param:description}
+
+  Resources:
+    DeadLetterQueue:
+      Type: AWS::SQS::Queue
+      Properties:
+        MessageRetentionPeriod: 1209600
+        KmsDataKeyReusePeriodSeconds: 300
+        KmsMasterKeyId: !Ref EncryptionKey
+        QueueName: ${self:service}-dead-letters
+
+    MessageQueue:
+      Type: AWS::SQS::Queue
+      Properties:
+        MessageRetentionPeriod: 1209600
+        KmsDataKeyReusePeriodSeconds: 300
+        KmsMasterKeyId: !Ref EncryptionKey
+        QueueName: ${self:service}-messages
+        RedrivePolicy:
+          deadLetterTargetArn: !GetAtt DeadLetterQueue.Arn
+          maxReceiveCount: 3
+        VisibilityTimeout: 180
+
+    # MessageQueuePolicy:
+    #   Type: AWS::SQS::QueuePolicy
+    #   Properties:
+    #     PolicyDocument:
+    #       Version: '2012-10-17'
+    #       Statement:
+    #         - Action: sqs:SendMessage
+    #           Condition:
+    #             ArnEquals:
+    #               aws:SourceArn: 'TODO: sourceSnsTopicArn'
+    #           Effect: 'Allow'
+    #           Principal:
+    #             AWS: '*'
+    #           Resource: '*'
+    #     Queues:
+    #       - !Ref MessageQueue
+
+    # TopicSubscription:
+    #   Type: AWS::SNS::Subscription
+    #   Properties:
+    #     Endpoint: !GetAtt MessageQueue.Arn
+    #     Protocol: sqs
+    #     RawMessageDelivery: true
+    #     TopicArn: 'TODO: sourceSnsTopicArn'
+
+    DestinationTopic:
+      Type: AWS::SNS::Topic
+      Properties:
+        KmsMasterKeyId: alias/aws/sns
+        TopicName: ${self:service}
+
+    EncryptionKey:
+      Type: AWS::KMS::Key
+      Properties:
+        Description: ${self:service}
+        EnableKeyRotation: true
+        KeyPolicy:
+          Version: '2012-10-17'
+          Statement:
+            - Sid: Admin access
+              Effect: Allow
+              Action: kms:*
+              Principal:
+                AWS: !Ref AWS::AccountId
+              Resource: '*'
+            - Sid: SNS compatibility
+              Effect: Allow
+              Action:
+                - kms:Decrypt
+                - kms:GenerateDataKey*
+              Principal:
+                Service: sns.amazonaws.com
+              Resource: '*'
+
+    EncryptionKeyAlias:
+      Type: AWS::KMS::Alias
+      Properties:
+        AliasName: alias/seek/${self:service}
+        TargetKeyId: !Ref EncryptionKey

package/template/lambda-sqs-worker/skuba.template.js

@@ -0,0 +1,32 @@
+/**
+ * Run `skuba configure` to finish templating and remove this file.
+ */
+
+module.exports = {
+  entryPoint: 'src/app.ts#handler',
+  fields: [
+    {
+      name: 'serviceName',
+      message: 'Service slug',
+      initial: 'my-project',
+    },
+    {
+      name: 'description',
+      message: 'Description',
+      initial: 'A project just for me',
+    },
+    {
+      name: 'devBuildkiteQueueName',
+      message: 'Dev Buildkite queue',
+      initial: 'my-team-aws-account-dev:cicd',
+      validate: (value) => /^.+:.+$/.test(value),
+    },
+    {
+      name: 'prodBuildkiteQueueName',
+      message: 'Prod Buildkite queue',
+      initial: 'my-team-aws-account-prod:cicd',
+      validate: (value) => /^.+:.+$/.test(value),
+    },
+  ],
+  type: 'application',
+};

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