skuba 13.0.0-custom-conditions-exports-20250730235248 → 13.0.0-custom-conditions-exports-20250923005538

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

@@ -0,0 +1,56 @@
+/**
+ * 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 { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-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 OTLPTraceExporter(),
+    autoDetectResources: false,
+    instrumentations: [new HttpInstrumentation(), new AwsInstrumentation()],
+  });
+
+  sdk.start();
+
+  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/greeter/Dockerfile

@@ -1,4 +1,4 @@
-# syntax=docker/dockerfile:1.17
+# syntax=docker/dockerfile:1.18
 
 FROM public.ecr.aws/docker/library/node:22-alpine AS dev-deps
 

package/template/greeter/README.md

@@ -75,7 +75,7 @@ For inspiration in this space, check out:
 
 ### Dev
 
-TODO: add support links for the dev environment.
+TODO: add support links for the dev deployment.
 
 <!--
 - CloudWatch dashboard
@@ -85,7 +85,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/greeter/package.json

@@ -23,9 +23,9 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.10",
-    "skuba": "13.0.0-custom-conditions-exports-20250730235248"
+    "skuba": "13.0.0-custom-conditions-exports-20250923005538"
   },
-  "packageManager": "pnpm@10.12.4",
+  "packageManager": "pnpm@10.15.1",
   "engines": {
     "node": ">=22"
   }

package/template/koa-rest-api/.buildkite/pipeline.yml

@@ -77,6 +77,9 @@ steps:
       queue: <%- devBuildkiteQueueName %>
     label: 🤞 Deploy Dev
     concurrency_group: <%- teamName %>/deploy/gantry/<%- devGantryEnvironmentName %>
+    env:
+      DD_DEPLOYMENT_ENVIRONMENT: development
+      DD_DEPLOYMENT_SERVICE: <%- serviceName %>
     key: deploy-dev
     plugins:
       - seek-jobs/gantry#v4.0.0:
@@ -93,6 +96,9 @@ steps:
     branches: ${BUILDKITE_PIPELINE_DEFAULT_BRANCH}
     concurrency_group: <%- teamName %>/deploy/gantry/<%- prodGantryEnvironmentName %>
     depends_on: deploy-dev
+    env:
+      DD_DEPLOYMENT_ENVIRONMENT: production
+      DD_DEPLOYMENT_SERVICE: <%- serviceName %>
     plugins:
       - seek-jobs/gantry#v4.0.0:
           command: apply

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/Dockerfile.dev-deps

@@ -1,4 +1,4 @@
-# syntax=docker/dockerfile:1.17
+# syntax=docker/dockerfile:1.18
 
 FROM public.ecr.aws/docker/library/node:22-alpine AS dev-deps
 

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

@@ -20,22 +20,22 @@
   },
   "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",
-    "@opentelemetry/instrumentation-aws-sdk": "^0.56.0",
-    "@opentelemetry/instrumentation-http": "^0.203.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.204.0",
+    "@opentelemetry/instrumentation-aws-sdk": "^0.58.0",
+    "@opentelemetry/instrumentation-http": "^0.204.0",
     "@opentelemetry/propagator-b3": "^2.0.0",
-    "@opentelemetry/sdk-node": "^0.203.0",
-    "@seek/logger": "^10.0.0",
-    "hot-shots": "^10.0.0",
+    "@opentelemetry/sdk-node": "^0.204.0",
+    "@seek/logger": "^11.1.0",
+    "hot-shots": "^11.0.0",
     "koa": "^3.0.1",
     "koa-compose": "^4.1.0",
-    "seek-datadog-custom-metrics": "^4.6.3",
+    "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",
@@ -45,12 +45,11 @@
     "@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.15.1",
   "engines": {
     "node": ">=22"
   }

package/template/koa-rest-api/skuba.template.js

@@ -2,7 +2,7 @@
  * Run `skuba configure` to finish templating and remove this file.
  */
 
-module.exports = {
+export default {
   entryPoint: 'src/app.ts',
   fields: [
     {

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 { config } from '#src/config.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

@@ -20,3 +20,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/Dockerfile

@@ -1,4 +1,4 @@
-# syntax=docker/dockerfile:1.17
+# syntax=docker/dockerfile:1.18
 
 FROM public.ecr.aws/docker/library/node:22-alpine AS dev-deps
 

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