skuba 12.1.0-hoist-less-20250722131939 → 12.1.0-main-20250812041011

package/template/koa-rest-api/.env

@@ -1 +1 @@
-ENVIRONMENT=local
+DEPLOYMENT=local

package/template/koa-rest-api/.gantry/dev.yml

@@ -1,4 +1,5 @@
-environment: dev
+deployment: dev
+env: development
 
 maxInstanceCount: 1
 minInstanceCount: 1
@@ -7,5 +8,4 @@ minInstanceCount: 1
 cloudwatchDashboardDisabled: true
 
 openTelemetry:
-  datadogEnvironmentName: development
-  enabled: false
+  enabled: true

package/template/koa-rest-api/.gantry/prod.yml

@@ -1,8 +1,8 @@
-environment: prod
+deployment: prod
+env: production
 
 maxInstanceCount: 10
 minInstanceCount: 3
 
 openTelemetry:
-  datadogEnvironmentName: production
-  enabled: false
+  enabled: true

package/template/koa-rest-api/README.md

@@ -29,7 +29,7 @@ It uses the [Koa] middleware framework and common SEEK packages.
 Resource APIs enable synchronous interactions and serve as the backbone of SEEK's general service architecture.
 
 The `koa-rest-api` template is modelled after a hypothetical service for posting and retrieving job advertisements.
-It's stubbed out with in-memory [storage](src/storage) which can observed by standing up an environment with multiple instances.
+It's stubbed out with in-memory [storage](src/storage) which can observed by standing up a deployment with multiple instances.
 Storage is local to each instance, so load balancing across the instances may render a read inconsistent with a previous write.
 This would be replaced with an external data store in production.
 
@@ -75,19 +75,19 @@ pnpm start:debug
 
 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
+- Commits to a feature branch can be deployed to the development environment by unblocking a step in the Buildkite UI
+- Commits to the default branch are automatically deployed to the development and production environments in sequence
 
 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;
+Note that this will introduce drift between the head of the default Git branch and the live deployment;
 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.
+TODO: add support links for the dev deployment.
 
 <!--
 - CloudWatch dashboard
@@ -97,7 +97,7 @@ TODO: add support links for the dev environment.
 
 ### Prod
 
-TODO: add support links for the prod environment.
+TODO: add support links for the prod deployment.
 
 <!--
 - CloudWatch dashboard

package/template/koa-rest-api/gantry.apply.yml

@@ -9,10 +9,14 @@ owner: '{{values "owner"}}'
 image: '{{values "image"}}'
 
 env:
-  ENVIRONMENT: '{{values "environment"}}'
-  OPENTELEMETRY_ENABLED: '{{.Values.openTelemetry.enabled | default false}}'
+  DEPLOYMENT: '{{values "deployment"}}'
   SERVICE: '{{values "service"}}'
 
+  DD_ENV: '{{values "env"}}'
+  DD_SERVICE: '{{values "service"}}'
+
+  OPENTELEMETRY_ENABLED: '{{values "openTelemetry.enabled"}}'
+
 {{if .Values.cloudwatchDashboardDisabled}}
 cloudwatchDashboardDisabled: {{values "cloudwatchDashboardDisabled"}}
 {{end}}
@@ -21,9 +25,17 @@ cloudwatchDashboardDisabled: {{values "cloudwatchDashboardDisabled"}}
 datadogSecretId: '{{values "datadogSecretId"}}'
 {{end}}
 
+# Uncomment if the `tin` tier is acceptable for your SEEK Auth Sidecar logs
+# The eeeoh log forwarder bypasses Amazon CloudWatch for cost savings
+# logSink:
+#   forwarder: eeeoh
+#   splunkIndex: '{{values "logSink.splunkIndex"}}'
+
 openTelemetry:
-  datadogEnvironmentName: '{{values "openTelemetry.datadogEnvironmentName"}}'
+  datadogEnvironmentName: '{{values "env"}}'
   enabled: {{values "openTelemetry.enabled"}}
+  useGantryServiceName: true
+
 {{if .Values.pagerDutyEndpoint}}
 pagerDutyEndpoint: '{{values "pagerDutyEndpoint"}}'
 {{end}}

package/template/koa-rest-api/package.json

@@ -14,7 +14,7 @@
   },
   "dependencies": {
     "@koa/bodyparser": "^6.0.0",
-    "@koa/router": "^13.0.0",
+    "@koa/router": "^14.0.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/core": "^2.0.0",
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.203.0",
@@ -22,29 +22,28 @@
     "@opentelemetry/instrumentation-http": "^0.203.0",
     "@opentelemetry/propagator-b3": "^2.0.0",
     "@opentelemetry/sdk-node": "^0.203.0",
-    "@seek/logger": "^10.0.0",
-    "hot-shots": "^10.0.0",
-    "koa": "^2.16.1",
+    "@seek/logger": "11.0.0",
+    "hot-shots": "^11.0.0",
+    "koa": "^3.0.1",
     "koa-compose": "^4.1.0",
-    "seek-datadog-custom-metrics": "^4.6.3",
-    "seek-koala": "^7.0.0",
+    "seek-datadog-custom-metrics": "^6.0.0",
+    "seek-koala": "^7.1.0",
     "skuba-dive": "^2.0.0",
-    "zod": "^3.25.67"
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "@types/chance": "^1.1.3",
     "@types/co-body": "^6.1.3",
-    "@types/koa": "^2.13.4",
+    "@types/koa": "^3.0.0",
     "@types/koa__router": "^12.0.0",
     "@types/node": "^22.13.10",
     "@types/supertest": "^6.0.0",
     "chance": "^1.1.8",
-    "mime": "^4.0.1",
     "pino-pretty": "^13.0.0",
     "skuba": "*",
     "supertest": "^7.0.0"
   },
-  "packageManager": "pnpm@10.12.4",
+  "packageManager": "pnpm@10.14.0",
   "engines": {
     "node": ">=22"
   }

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

@@ -3,8 +3,8 @@ import type { Middleware } from 'src/types/koa.js';
 /**
  * Signifies that the API is available to serve requests.
  *
- * The deployment environment calls this endpoint to see if the container is
- * unhealthy and needs to be recycled.
+ * The workload hosting environment calls this endpoint to see if the container
+ * is unhealthy and needs to be recycled.
  */
 export const healthCheckHandler: Middleware = (ctx) => {
   ctx.state.skipRequestLogging = true;

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

@@ -1,7 +1,7 @@
 import { Env } from 'skuba-dive';
 
 interface Config {
-  environment: Environment;
+  deployment: Deployment;
 
   logLevel: string;
   name: string;
@@ -11,17 +11,17 @@ interface Config {
   port: number | null;
 }
 
-type Environment = (typeof environments)[number];
+type Deployment = (typeof deployments)[number];
 
 const dev = '<%- devGantryEnvironmentName %>';
 const prod = '<%- prodGantryEnvironmentName %>';
 
-const environments = ['local', 'test', dev, prod] as const;
+const deployments = ['local', 'test', dev, prod] as const;
 
-const environment = Env.oneOf(environments)('ENVIRONMENT');
+const deployment = Env.oneOf(deployments)('DEPLOYMENT');
 
 /* istanbul ignore next: config verification makes more sense in a smoke test */
-const configs: Record<Environment, () => Omit<Config, 'environment'>> = {
+const configs: Record<Deployment, () => Omit<Config, 'deployment'>> = {
   local: () => ({
     logLevel: 'debug',
     name: '<%- serviceName %>',
@@ -62,6 +62,6 @@ const configs: Record<Environment, () => Omit<Config, 'environment'>> = {
 };
 
 export const config: Config = {
-  ...configs[environment](),
-  environment,
+  ...configs[deployment](),
+  deployment,
 };

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

@@ -1,4 +1,4 @@
-import createLogger, { createDestination } from '@seek/logger';
+import { createDestination, createLogger } from '@seek/logger';
 import { RequestLogging } from 'seek-koala';
 
 import { config } from 'src/config.js';
@@ -9,26 +9,30 @@ const { createContextMiddleware, mixin } =
 export const contextMiddleware = createContextMiddleware();
 
 const { destination, stdoutMock } = createDestination({
-  mock: config.environment === 'test',
+  mock: config.deployment === 'test',
 });
 
 export { stdoutMock };
 
 export const logger = createLogger(
   {
-    base: {
-      environment: config.environment,
-      version: config.version,
+    eeeoh: {
+      /**
+       * TODO: choose an appropriate Datadog log tier.
+       *
+       * https://github.com/seek-oss/logger/blob/master/docs/eeeoh.md#datadog-log-tiers
+       */
+      datadog: 'tin',
+      team: '<%- teamName %>',
+      use: 'environment',
     },
 
     mixin,
 
     level: config.logLevel,
 
-    name: config.name,
-
     transport:
-      config.environment === 'local' ? { target: 'pino-pretty' } : undefined,
+      config.deployment === 'local' ? { target: 'pino-pretty' } : undefined,
   },
   destination,
 );

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

@@ -7,5 +7,5 @@ import { logger } from './logging.js';
 
 /* istanbul ignore next: StatsD client is not our responsibility */
 export const metricsClient = createStatsDClient(StatsD, config, (err) =>
-  logger.error({ err }, 'StatsD error'),
+  logger.error(err, 'StatsD error'),
 );

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

@@ -32,7 +32,6 @@ describe('createApp', () => {
 
     expect(stdoutMock.calls).toHaveLength(0);
 
-    metricsClient.expectTagSubset(['env:test', 'version:test']);
     metricsClient.expectTagSubset([
       'http_method:get',
       'http_status:200',
@@ -133,7 +132,7 @@ describe('createApp', () => {
 
     expect(stdoutMock.calls).toMatchObject([
       {
-        err: {
+        error: {
           statusCode: 400,
           type: 'BadRequestError',
         },
@@ -167,7 +166,7 @@ describe('createApp', () => {
 
     expect(stdoutMock.calls).toMatchObject([
       {
-        err: {
+        error: {
           statusCode: 500,
           type: 'InternalServerError',
         },
@@ -203,7 +202,7 @@ describe('createApp', () => {
 
     expect(stdoutMock.calls).toMatchObject([
       {
-        err: {
+        error: {
           message: err.message,
           type: 'Error',
         },
@@ -237,7 +236,7 @@ describe('createApp', () => {
 
     expect(stdoutMock.calls).toMatchObject([
       {
-        err: null,
+        error: null,
         level: 50,
         method: 'GET',
         msg: 'Server error',
@@ -256,10 +255,10 @@ describe('createApp', () => {
   });
 
   it('handles string error', async () => {
-    const err = chance.sentence();
+    const error = chance.sentence();
 
     middleware.mockImplementation(() => {
-      throw err;
+      throw error;
     });
 
     await agent
@@ -270,7 +269,7 @@ describe('createApp', () => {
 
     expect(stdoutMock.calls).toMatchObject([
       {
-        err,
+        error,
         level: 50,
         method: 'GET',
         msg: 'Server error',

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

@@ -30,10 +30,7 @@ const requestLogging = RequestLogging.createMiddleware((ctx, fields, err) => {
     : logger.error(fields, 'Server error');
 });
 
-const version = VersionMiddleware.create({
-  name: config.name,
-  version: config.version,
-});
+const version = VersionMiddleware.create(config);
 
 export const createApp = <State, Context>(
   ...middleware: Array<Koa.Middleware<State, Context>>

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

@@ -22,3 +22,9 @@ const listener = app.listen(config.port, () => {
 // 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;
+
+// Report unhandled rejections instead of crashing the process
+// Make sure to monitor these reports and alert as appropriate
+process.on('unhandledRejection', (err) =>
+  logger.error(err, 'Unhandled promise rejection'),
+);

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

@@ -81,7 +81,9 @@ steps:
     agents:
       queue: <%- devBuildkiteQueueName %>
     env:
-      ENVIRONMENT: dev
+      DD_DEPLOYMENT_ENVIRONMENT: development
+      DD_DEPLOYMENT_SERVICE: <%- serviceName %>
+      DEPLOYMENT: dev
       GET_NPM_TOKEN: please
     label: 🤞 Deploy Dev
     concurrency_group: '<%- repoName %>/deploy/dev'
@@ -89,7 +91,9 @@ steps:
 
   - <<: *deploy
     env:
-      ENVIRONMENT: prod
+      DD_DEPLOYMENT_ENVIRONMENT: production
+      DD_DEPLOYMENT_SERVICE: <%- serviceName %>
+      DEPLOYMENT: prod
       GET_NPM_TOKEN: please
     label: 🚀 Deploy Prod
     branches: ${BUILDKITE_PIPELINE_DEFAULT_BRANCH}

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

@@ -1 +1 @@
-ENVIRONMENT=local
+DEPLOYMENT=local

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

@@ -54,7 +54,7 @@ pnpm test
 awsauth
 
 # Run smoke test against deployed application
-ENVIRONMENT=dev pnpm smoke
+DEPLOYMENT=dev pnpm smoke
 ```
 
 ### Lint
@@ -88,8 +88,8 @@ curl --data '[{}, {"awsRequestId": "local"}]' --include localhost:<%- port %>
 
 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
+- Commits to a feature branch can be deployed to the development environment by unblocking a step in the Buildkite UI
+- Commits to the default branch are automatically deployed to the development and production environments in sequence
 
 To deploy locally:
 
@@ -97,7 +97,7 @@ To deploy locally:
 # Authenticate to dev account
 awsauth
 
-ENVIRONMENT=dev pnpm run deploy
+DEPLOYMENT=dev pnpm run deploy
 ```
 
 A hotswap deploy enables faster deployment but come with caveats such as requiring a Lambda to be rebuilt with every build.
@@ -108,19 +108,19 @@ To deploy a [hotswap]:
 # Authenticate to dev account
 awsauth
 
-ENVIRONMENT=dev pnpm run deploy:hotswap
+DEPLOYMENT=dev pnpm run deploy:hotswap
 ```
 
 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;
+Note that this will introduce drift between the head of the default Git branch and the live deployment;
 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.
+TODO: add support links for the dev deployment.
 
 <!--
 - CloudWatch dashboard
@@ -130,7 +130,7 @@ TODO: add support links for the dev environment.
 
 ### Prod
 
-TODO: add support links for the prod environment.
+TODO: add support links for the prod deployment.
 
 <!--
 - CloudWatch dashboard

package/template/lambda-sqs-worker-cdk/infra/__snapshots__/appStack.test.ts.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`returns expected CloudFormation stack for dev 1`] = `
 {
@@ -180,28 +180,29 @@ exports[`returns expected CloudFormation stack for dev 1`] = `
               "Ref": "datadogapikeysecret046FEF06",
             },
             "DD_CAPTURE_LAMBDA_PAYLOAD": "false",
+            "DD_ENV": "development",
             "DD_FLUSH_TO_LOG": "false",
             "DD_LAMBDA_HANDLER": "index.handler",
             "DD_LOGS_INJECTION": "false",
             "DD_MERGE_XRAY_TRACES": "false",
             "DD_SERVERLESS_APPSEC_ENABLED": "false",
             "DD_SERVERLESS_LOGS_ENABLED": "false",
+            "DD_SERVICE": "serviceName",
             "DD_SITE": "datadoghq.com",
             "DD_TRACE_CLOUD_REQUEST_PAYLOAD_TAGGING": "$.*",
             "DD_TRACE_CLOUD_RESPONSE_PAYLOAD_TAGGING": "$.*",
             "DD_TRACE_ENABLED": "true",
+            "DD_VERSION": "local",
+            "DEPLOYMENT": "dev",
             "DESTINATION_SNS_TOPIC_ARN": {
               "Ref": "destinationtopicDCE2E0B8",
             },
-            "ENVIRONMENT": "dev",
             "NODE_ENV": "production",
             "NODE_OPTIONS": "--enable-source-maps",
-            "SERVICE": "serviceName",
-            "VERSION": "local",
           },
         },
         "FunctionName": "serviceName",
-        "Handler": "node_modules/datadog-lambda-js/dist/handler.handler",
+        "Handler": "/opt/nodejs/node_modules/datadog-lambda-js/handler.handler",
         "KmsKeyArn": {
           "Fn::GetAtt": [
             "kmskey49FBC3B3",
@@ -209,6 +210,18 @@ exports[`returns expected CloudFormation stack for dev 1`] = `
           ],
         },
         "Layers": [
+          {
+            "Fn::Join": [
+              "",
+              [
+                "arn:aws:lambda:",
+                {
+                  "Ref": "AWS::Region",
+                },
+                ":464622532012:layer:Datadog-Node22-x:x",
+              ],
+            ],
+          },
           {
             "Fn::Join": [
               "",
@@ -222,7 +235,7 @@ exports[`returns expected CloudFormation stack for dev 1`] = `
             ],
           },
         ],
-        "ReservedConcurrentExecutions": 2,
+        "ReservedConcurrentExecutions": 3,
         "Role": {
           "Fn::GetAtt": [
             "workerServiceRole2130CC7F",
@@ -332,6 +345,7 @@ exports[`returns expected CloudFormation stack for dev 1`] = `
     },
     "workerAliasLiveSqsEventSourceappStackworkerqueue8281B9F443B0CF93": {
       "Properties": {
+        "BatchSize": 10,
         "EventSourceArn": {
           "Fn::GetAtt": [
             "workerqueueA05CE5C6",
@@ -359,6 +373,12 @@ exports[`returns expected CloudFormation stack for dev 1`] = `
             ],
           ],
         },
+        "FunctionResponseTypes": [
+          "ReportBatchItemFailures",
+        ],
+        "ScalingConfig": {
+          "MaximumConcurrency": 2,
+        },
         "Tags": [
           {
             "Key": "aws-codedeploy-hooks",
@@ -913,28 +933,29 @@ exports[`returns expected CloudFormation stack for prod 1`] = `
               "Ref": "datadogapikeysecret046FEF06",
             },
             "DD_CAPTURE_LAMBDA_PAYLOAD": "false",
+            "DD_ENV": "production",
             "DD_FLUSH_TO_LOG": "false",
             "DD_LAMBDA_HANDLER": "index.handler",
             "DD_LOGS_INJECTION": "false",
             "DD_MERGE_XRAY_TRACES": "false",
             "DD_SERVERLESS_APPSEC_ENABLED": "false",
             "DD_SERVERLESS_LOGS_ENABLED": "false",
+            "DD_SERVICE": "serviceName",
             "DD_SITE": "datadoghq.com",
             "DD_TRACE_CLOUD_REQUEST_PAYLOAD_TAGGING": "$.*",
             "DD_TRACE_CLOUD_RESPONSE_PAYLOAD_TAGGING": "$.*",
             "DD_TRACE_ENABLED": "true",
+            "DD_VERSION": "local",
+            "DEPLOYMENT": "prod",
             "DESTINATION_SNS_TOPIC_ARN": {
               "Ref": "destinationtopicDCE2E0B8",
             },
-            "ENVIRONMENT": "prod",
             "NODE_ENV": "production",
             "NODE_OPTIONS": "--enable-source-maps",
-            "SERVICE": "serviceName",
-            "VERSION": "local",
           },
         },
         "FunctionName": "serviceName",
-        "Handler": "node_modules/datadog-lambda-js/dist/handler.handler",
+        "Handler": "/opt/nodejs/node_modules/datadog-lambda-js/handler.handler",
         "KmsKeyArn": {
           "Fn::GetAtt": [
             "kmskey49FBC3B3",
@@ -942,6 +963,18 @@ exports[`returns expected CloudFormation stack for prod 1`] = `
           ],
         },
         "Layers": [
+          {
+            "Fn::Join": [
+              "",
+              [
+                "arn:aws:lambda:",
+                {
+                  "Ref": "AWS::Region",
+                },
+                ":464622532012:layer:Datadog-Node22-x:x",
+              ],
+            ],
+          },
           {
             "Fn::Join": [
               "",
@@ -1065,6 +1098,7 @@ exports[`returns expected CloudFormation stack for prod 1`] = `
     },
     "workerAliasLiveSqsEventSourceappStackworkerqueue8281B9F443B0CF93": {
       "Properties": {
+        "BatchSize": 10,
         "EventSourceArn": {
           "Fn::GetAtt": [
             "workerqueueA05CE5C6",
@@ -1092,6 +1126,12 @@ exports[`returns expected CloudFormation stack for prod 1`] = `
             ],
           ],
         },
+        "FunctionResponseTypes": [
+          "ReportBatchItemFailures",
+        ],
+        "ScalingConfig": {
+          "MaximumConcurrency": 19,
+        },
         "Tags": [
           {
             "Key": "aws-codedeploy-hooks",

package/template/lambda-sqs-worker-cdk/infra/appStack.test.ts

@@ -15,11 +15,11 @@ jest.useFakeTimers({
   now: new Date(currentDate),
 });
 
-const originalEnv = process.env.ENVIRONMENT;
+const originalDeployment = process.env.DEPLOYMENT;
 const originalVersion = process.env.VERSION;
 
 afterAll(() => {
-  process.env.ENVIRONMENT = originalEnv;
+  process.env.DEPLOYMENT = originalDeployment;
   process.env.VERSION = originalVersion;
 });
 
@@ -29,8 +29,8 @@ afterEach(() => {
 
 it.each(['dev', 'prod'])(
   'returns expected CloudFormation stack for %s',
-  async (env) => {
-    process.env.ENVIRONMENT = env;
+  async (deployment) => {
+    process.env.DEPLOYMENT = deployment;
     process.env.VERSION = 'local';
 
     const { AppStack } = await import('./appStack.js');
@@ -69,10 +69,7 @@ it.each(['dev', 'prod'])(
         /"DD_TAGS":"git.commit.sha:([0-9a-f]+),git.repository_url:([^\"]+)",/g,
         '',
       )
-      .replaceAll(
-        /(layer:Datadog-Extension-.+?:)\d+/g,
-        (_, layer) => `${layer}x`,
-      );
+      .replaceAll(/(layer:Datadog-[^-]+-.+?:)\d+/g, (_, layer) => `${layer}x`);
     expect(JSON.parse(json)).toMatchSnapshot();
   },
 );