@fjall/components-infrastructure 3.3.0 → 3.4.1

package/dist/lib/resources/aws/compute/ecsServiceFactory.d.ts

@@ -1,9 +1,9 @@
 import { FargateService, Ec2Service, AsgCapacityProvider, type DeploymentCircuitBreaker } from "aws-cdk-lib/aws-ecs";
 import type { FargateTaskDefinition, Ec2TaskDefinition } from "aws-cdk-lib/aws-ecs";
 import { type ISecurityGroup } from "aws-cdk-lib/aws-ec2";
-import { TargetTrackingScalingPolicy, type StepScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
+import { TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
 import { type AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
-import { type EcsServiceProps, type Ec2CapacityConfig } from "./ecsTypes.js";
+import { type EcsServiceProps, type Ec2CapacityConfig, type QueueScalingResources } from "./ecsTypes.js";
 import type { EcsConstructContext } from "./ecsContext.js";
 /**
  * Resolves the user's `circuitBreaker` config to the CDK
@@ -41,4 +41,4 @@ export declare function createService(ctx: EcsConstructContext, serviceName: str
  * policy on utilisation; `QUEUE` emits a step-scaling policy on SQS backlog
  * that can wake the service from `desiredCount: 0`.
  */
-export declare function addServiceScaling(ctx: EcsConstructContext, serviceName: string, serviceProps: EcsServiceProps, service: FargateService | Ec2Service): TargetTrackingScalingPolicy | StepScalingPolicy;
+export declare function addServiceScaling(ctx: EcsConstructContext, serviceName: string, serviceProps: EcsServiceProps, service: FargateService | Ec2Service): TargetTrackingScalingPolicy | QueueScalingResources;

package/dist/lib/resources/aws/compute/ecsServiceFactory.js

@@ -3,8 +3,9 @@ import { Peer, Port, SubnetType, UserData } from "aws-cdk-lib/aws-ec2";
 import { ServicePrincipal } from "aws-cdk-lib/aws-iam";
 import { Role } from "../iam/role.js";
 import { CfnOutput, Duration, Token } from "aws-cdk-lib";
-import { AdjustmentType, PredefinedMetric, ScalableTarget, ServiceNamespace, TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
-import { MathExpression } from "aws-cdk-lib/aws-cloudwatch";
+import { AdjustmentType, PredefinedMetric, ScalableTarget, ServiceNamespace, StepScalingAction, TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
+import { Alarm, ComparisonOperator, MathExpression } from "aws-cdk-lib/aws-cloudwatch";
+import { ApplicationScalingAction } from "aws-cdk-lib/aws-cloudwatch-actions";
 import { Monitoring } from "aws-cdk-lib/aws-autoscaling";
 import { SecurityGroup } from "../networking/securityGroup.js";
 import { Ec2Instance } from "./ec2.js";
@@ -283,13 +284,14 @@ export function createService(ctx, serviceName, serviceProps, taskDefinition, as
     return service;
 }
 /**
- * Step-scaling intervals on the queue-backlog metric, with
- * `AdjustmentType.EXACT_CAPACITY` (`change` is the absolute DesiredCount).
- * Backlog 0 → 0 tasks (wake-to-zero); ≥1 → 1; ≥100 → 2; ≥500 → 3. Capacities
- * are clamped to the service's `maxCapacity` at build time.
+ * Wake-ladder intervals on the queue-backlog metric, with
+ * `AdjustmentType.EXACT_CAPACITY` (`capacity` is the absolute DesiredCount).
+ * Backlog ≥1 → 1 task; ≥100 → 2; ≥500 → 3. Capacities are clamped to the
+ * service's `maxCapacity` at build time. Bounds are absolute backlog values;
+ * `buildQueueScalingPolicy` re-expresses them relative to the wake alarm's
+ * threshold (the first interval's `lower`).
  */
-const DEFAULT_QUEUE_SCALING_STEPS = [
-    { lower: 0, upper: 1, capacity: 0 },
+const QUEUE_WAKE_SCALING_STEPS = [
     { lower: 1, upper: 100, capacity: 1 },
     { lower: 100, upper: 500, capacity: 2 },
     { lower: 500, capacity: 3 }
@@ -327,11 +329,21 @@ export function addServiceScaling(ctx, serviceName, serviceProps, service) {
     });
 }
 /**
- * Builds the step-scaling policy for `ScalingType.QUEUE`. The alarm metric is a
- * `MathExpression` SUM of `ApproximateNumberOfMessagesVisible`
+ * Builds the wake/sleep step-scaling pair for `ScalingType.QUEUE`. The alarm
+ * metric is a `MathExpression` SUM of `ApproximateNumberOfMessagesVisible`
  * (+`…NotVisible` when `includeInFlight`) across the consumed queues, sampled at
  * `Maximum` over 1-minute periods — published independent of running-task count,
- * so the policy fires (and DesiredCount rises from 0) on backlog alone.
+ * so the alarms fire (and DesiredCount rises from 0) on backlog alone.
+ *
+ * The actions and alarms are wired explicitly rather than via
+ * `ScalableTarget.scaleOnMetric`: CDK's `StepScalingPolicy` middle-splits an
+ * all-`EXACT_CAPACITY` interval ladder to place its two alarm thresholds
+ * (`findAlarmThresholds` in aws-autoscaling-common), which for a
+ * 0/1/100/500 ladder puts BOTH thresholds at 100. Step policies are only
+ * invoked on alarm state transitions, so backlog 1–99 produced no transition
+ * and could never wake a zero-task service. The explicit pair pins the wake
+ * threshold at the ladder's first bound (backlog ≥ 1) and the sleep threshold
+ * at 0, making every 0↔1 backlog crossing a state transition.
  */
 function buildQueueScalingPolicy(serviceName, config, scalableTarget, maxCapacity) {
     if (config === undefined || config.queues.length === 0) {
@@ -363,16 +375,46 @@ function buildQueueScalingPolicy(serviceName, config, scalableTarget, maxCapacit
         period: Duration.minutes(1),
         label: `${serviceName}QueueBacklog`
     });
-    return scalableTarget.scaleOnMetric(`${serviceName}QueueScaling`, {
+    const cooldown = config.cooldown ?? DEFAULT_QUEUE_SCALE_COOLDOWN;
+    const wakeThreshold = QUEUE_WAKE_SCALING_STEPS[0]?.lower ?? 1;
+    const wakeAction = new StepScalingAction(scalableTarget, `${serviceName}QueueWakeAction`, {
+        scalingTarget: scalableTarget,
+        adjustmentType: AdjustmentType.EXACT_CAPACITY,
+        cooldown
+    });
+    QUEUE_WAKE_SCALING_STEPS.forEach((step, index) => {
+        wakeAction.addAdjustment({
+            adjustment: Math.min(step.capacity, maxCapacity),
+            lowerBound: step.lower - wakeThreshold,
+            ...(index < QUEUE_WAKE_SCALING_STEPS.length - 1 &&
+                step.upper !== undefined && { upperBound: step.upper - wakeThreshold })
+        });
+    });
+    const wakeAlarm = new Alarm(scalableTarget, `${serviceName}QueueWakeAlarm`, {
         metric: backlogMetric,
+        alarmDescription: `Scale out '${serviceName}' on queue backlog`,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+        threshold: wakeThreshold,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1
+    });
+    wakeAlarm.addAlarmAction(new ApplicationScalingAction(wakeAction));
+    const sleepAction = new StepScalingAction(scalableTarget, `${serviceName}QueueSleepAction`, {
+        scalingTarget: scalableTarget,
         adjustmentType: AdjustmentType.EXACT_CAPACITY,
-        scalingSteps: DEFAULT_QUEUE_SCALING_STEPS.map((step) => ({
-            lower: step.lower,
-            ...(step.upper !== undefined && { upper: step.upper }),
-            change: Math.min(step.capacity, maxCapacity)
-        })),
-        cooldown: config.cooldown ?? DEFAULT_QUEUE_SCALE_COOLDOWN,
+        cooldown
+    });
+    // upperBound is relative to the alarm threshold (0), so this single
+    // open-ended interval covers exactly backlog ≤ 0.
+    sleepAction.addAdjustment({ adjustment: 0, upperBound: 0 });
+    const sleepAlarm = new Alarm(scalableTarget, `${serviceName}QueueSleepAlarm`, {
+        metric: backlogMetric,
+        alarmDescription: `Scale '${serviceName}' to zero on empty queue`,
+        comparisonOperator: ComparisonOperator.LESS_THAN_OR_EQUAL_TO_THRESHOLD,
+        threshold: 0,
         evaluationPeriods: 1,
         datapointsToAlarm: 1
     });
+    sleepAlarm.addAlarmAction(new ApplicationScalingAction(sleepAction));
+    return { wakeAction, wakeAlarm, sleepAction, sleepAlarm };
 }

package/dist/lib/resources/aws/compute/ecsTypes.d.ts

@@ -4,7 +4,8 @@ import { type Monitoring } from "aws-cdk-lib/aws-autoscaling";
 import { type IService } from "aws-cdk-lib/aws-servicediscovery";
 import { type IManagedPolicy, type PolicyDocument } from "aws-cdk-lib/aws-iam";
 import type { DockerBuild } from "@fjall/util/manifest/schemas";
-import { type TargetTrackingScalingPolicy, type StepScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
+import { type TargetTrackingScalingPolicy, type StepScalingAction } from "aws-cdk-lib/aws-applicationautoscaling";
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
 import { type IQueue } from "aws-cdk-lib/aws-sqs";
 import { type Duration } from "aws-cdk-lib";
 import { type GeoLocation } from "aws-cdk-lib/aws-route53";
@@ -63,6 +64,29 @@ export interface QueueScalingConfig {
     /** Cooldown after a scale action. Default: 5 minutes. */
     cooldown?: Duration;
 }
+/**
+ * The explicitly-wired wake/sleep alarm pair emitted for `ScalingType.QUEUE`.
+ *
+ * Built by hand (NOT via `ScalableTarget.scaleOnMetric`) because CDK's
+ * `StepScalingPolicy` places its two alarm thresholds by middle-splitting the
+ * interval ladder when every `EXACT_CAPACITY` step carries a change — for the
+ * default 4-step ladder that puts BOTH thresholds at backlog 100, and since
+ * step policies are only invoked on alarm state transitions, a backlog of
+ * 1–99 can never wake a `desiredCount: 0` service (observed live: the prod
+ * deploy-worker sat at 0 tasks with 1 queued message indefinitely). The
+ * explicit pair pins the wake boundary at backlog ≥ 1 and the sleep boundary
+ * at backlog 0.
+ */
+export interface QueueScalingResources {
+    /** Scale-out action: backlog ≥ 1 → capacity ladder (1/2/3, clamped). */
+    wakeAction: StepScalingAction;
+    /** Alarm at backlog ≥ 1 driving `wakeAction`. */
+    wakeAlarm: Alarm;
+    /** Scale-in action: backlog 0 → capacity 0. */
+    sleepAction: StepScalingAction;
+    /** Alarm at backlog ≤ 0 driving `sleepAction`. */
+    sleepAlarm: Alarm;
+}
 import type { EcsCapacityProvider } from "@fjall/generator";
 export type { EcsCapacityProvider };
 /**
@@ -607,7 +631,7 @@ export interface ServiceData {
     containers: ContainerDefinition[];
     primaryContainer?: ContainerDefinition;
     targetGroup?: IApplicationTargetGroup;
-    scalingPolicy?: TargetTrackingScalingPolicy | StepScalingPolicy;
+    scalingPolicy?: TargetTrackingScalingPolicy | QueueScalingResources;
     /** Explicit log group shared by all of the service's containers. */
     logGroup: ILogGroup;
 }

package/dist/lib/resources/aws/networking/domainCertificate.js

@@ -1,6 +1,7 @@
 import { CfnOutput, Tags } from "aws-cdk-lib";
 import { Certificate, CertificateValidation } from "aws-cdk-lib/aws-certificatemanager";
 import { getDomainExportNames } from "@fjall/util";
+import { sanitiseAcmTagValue } from "../../../utils/acmTagValue.js";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
 import { applyCostAllocationTags } from "../../../utils/costAllocationTags.js";
 /**
@@ -33,10 +34,12 @@ export class DomainCertificate extends Certificate {
         this.description =
             props.description ??
                 `Fjall-managed ACM certificate for ${props.domainName}`;
-        Tags.of(this).add("fjall:description", this.description);
+        // ACM's tag-value charset excludes `*`, so a wildcard domainName in either
+        // tag fails CreateCertificate — sanitise both (see utils/acmTagValue.ts).
+        Tags.of(this).add("fjall:description", sanitiseAcmTagValue(this.description));
         applyCostAllocationTags(this, {
             service: "certificate",
-            domain: props.costAllocationDomain ?? props.domainName,
+            domain: sanitiseAcmTagValue(props.costAllocationDomain ?? props.domainName),
             environment: props.costAllocationEnvironment,
             inheritEnvironment: props.inheritCostAllocationEnvironment
         });

package/dist/lib/utils/acmTagValue.d.ts

@@ -0,0 +1,2 @@
+/** Replace every ACM-disallowed character with `_` (an allowed character). */
+export declare function sanitiseAcmTagValue(value: string): string;

package/dist/lib/utils/acmTagValue.js

@@ -0,0 +1,13 @@
+/**
+ * ACM rejects tag values containing characters outside
+ * `[\p{L}\p{Z}\p{N}_.:/=+\-@]*` (letters, spaces, numbers, `_ . : / = + - @`)
+ * with a CreateCertificate ValidationException — notably `*`, so any tag
+ * embedding a wildcard domain (`*.dev.example.com`) fails the whole stack at
+ * deploy time. Most other taggable services (S3, EC2, Route53) accept `*`,
+ * which is why the constraint only surfaces at the certificate boundary.
+ */
+const ACM_TAG_VALUE_DISALLOWED = /[^\p{L}\p{Z}\p{N}_.:/=+\-@]/gu;
+/** Replace every ACM-disallowed character with `_` (an allowed character). */
+export function sanitiseAcmTagValue(value) {
+    return value.replace(ACM_TAG_VALUE_DISALLOWED, "_");
+}

package/dist/lib/utils/costAllocationTags.d.ts

@@ -1,11 +1,6 @@
+import { COST_ALLOCATION_TAGS, DEFAULT_COST_ALLOCATION_ENVIRONMENT } from "@fjall/util/aws";
 import type { IConstruct } from "constructs";
-export declare const COST_ALLOCATION_TAGS: {
-    readonly ENVIRONMENT: "fjall:costAllocation:environment";
-    readonly SERVICE: "fjall:costAllocation:service";
-    readonly DOMAIN: "fjall:costAllocation:domain";
-    readonly OWNER: "fjall:costAllocation:owner";
-};
-export declare const DEFAULT_COST_ALLOCATION_ENVIRONMENT: "management";
+export { COST_ALLOCATION_TAGS, DEFAULT_COST_ALLOCATION_ENVIRONMENT };
 export interface CostAllocationTagsArgs {
     readonly service: string;
     readonly domain: string;

package/dist/lib/utils/costAllocationTags.js

@@ -1,11 +1,9 @@
+import { COST_ALLOCATION_TAGS, DEFAULT_COST_ALLOCATION_ENVIRONMENT } from "@fjall/util/aws";
 import { Tags } from "aws-cdk-lib";
-export const COST_ALLOCATION_TAGS = {
-    ENVIRONMENT: "fjall:costAllocation:environment",
-    SERVICE: "fjall:costAllocation:service",
-    DOMAIN: "fjall:costAllocation:domain",
-    OWNER: "fjall:costAllocation:owner"
-};
-export const DEFAULT_COST_ALLOCATION_ENVIRONMENT = "management";
+// Canonical home: @fjall/util (`util/src/aws/costAllocationTags.ts`) — shared
+// with deploy-core's `cdk bootstrap --tags` stamping. Re-exported here so
+// construct-package consumers keep their existing import path.
+export { COST_ALLOCATION_TAGS, DEFAULT_COST_ALLOCATION_ENVIRONMENT };
 export function applyCostAllocationTags(scope, args) {
     if (args.environment !== undefined) {
         Tags.of(scope).add(COST_ALLOCATION_TAGS.ENVIRONMENT, args.environment);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "3.3.0",
+  "version": "3.4.1",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {
@@ -67,8 +67,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1038.0",
-    "@fjall/generator": "^3.3.0",
-    "@fjall/util": "^3.3.0",
+    "@fjall/generator": "^3.4.1",
+    "@fjall/util": "^3.4.1",
     "constructs": "^10.6.0"
   },
   "overrides": {
@@ -82,5 +82,5 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "gitHead": "cc1e0f520f4b6b5312e16df3751d60ea746dfb7d"
+  "gitHead": "6d8ef9582d5abe6a8199431815dae761887c18d4"
 }