canopycms-cdk 0.0.63 → 0.0.65

package/dist/constructs/asset-support.d.ts

@@ -1,5 +1,5 @@
 import { Construct } from 'constructs';
-import { RemovalPolicy, aws_cloudfront as cloudfront, aws_iam as iam, aws_lambda as lambda, aws_logs as logs, aws_s3 as s3 } from 'aws-cdk-lib';
+import { Duration, RemovalPolicy, aws_cloudfront as cloudfront, aws_iam as iam, aws_lambda as lambda, aws_logs as logs, aws_s3 as s3 } from 'aws-cdk-lib';
 export interface AssetSupportProps {
     /**
      * Use an existing bucket (BYO mode - e.g. a site's existing content
@@ -76,6 +76,26 @@ export interface AssetSupportProps {
      * three months / 90 days).
      */
     readonly transformLogRetention?: logs.RetentionDays;
+    /**
+     * Concurrency cap on the transform Lambda (default: 10).
+     *
+     * This is a reservation — a CAP carved from the account's concurrency pool,
+     * not pre-warmed capacity, so it costs nothing when idle. It bounds the
+     * blast radius of the anonymous `/assets/t/*` path; see the default
+     * constant's doc comment. Raise it for an unusually image-heavy site;
+     * setting it to 0 would disable transforms entirely.
+     */
+    readonly transformReservedConcurrency?: number;
+    /**
+     * How long generated derivatives under `assets/t/` are kept (default: 180
+     * days). Only applies to a bucket this construct creates — in BYO-bucket
+     * mode the caller owns lifecycle rules.
+     *
+     * These objects are regenerable; expiry is self-healing (the next request
+     * regenerates and re-stores). Source assets under `asset-originals/` are
+     * never affected.
+     */
+    readonly transformOutputRetention?: Duration;
     /**
      * Name for the transform Lambda's CloudWatch log group (default:
      * `/canopycms/<stackName>/transform`). Deliberately NOT
@@ -179,4 +199,3 @@ export declare class AssetSupport extends Construct {
      */
     grantUploadAccess(grantee: iam.IGrantable): void;
 }
-//# sourceMappingURL=asset-support.d.ts.map

package/dist/constructs/asset-support.js

@@ -56,6 +56,43 @@ const CORS_MAX_AGE_SECONDS = 3000;
 const DEFAULT_MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
 const TRANSFORM_LAMBDA_MEMORY_MB = 1536;
 const TRANSFORM_LAMBDA_TIMEOUT = Duration.seconds(30);
+/**
+ * Concurrency cap on the transform Lambda.
+ *
+ * `/assets/t/*` is reachable by any anonymous viewer through CloudFront, and
+ * `hash32` is not secret — it appears in every published page's `<img src>`.
+ * Width and quality are allowlisted precisely to bound how many cache keys one
+ * asset can have, but `crop` is a 4-decimal float rect (~10^16 values), so a
+ * scripted loop of unique crops is an unbounded stream of guaranteed
+ * CloudFront+S3 misses, each a sharp transform on a 1536MB Lambda plus a
+ * permanently stored S3 object.
+ *
+ * A reservation is the cheap half of bounding that: it is a CAP carved from the
+ * account's concurrency pool, not pre-warmed capacity, so it costs nothing when
+ * idle (that is `provisionedConcurrentExecutions`, which this is not).
+ *
+ * 10 mirrors the CMS Lambda's own reservation. Genuine demand is first-render
+ * misses only — every already-generated derivative is served by the S3 primary
+ * origin without invoking this function at all — so 10 concurrent transforms
+ * covers a cold page of images comfortably while capping a flood.
+ */
+const TRANSFORM_LAMBDA_RESERVED_CONCURRENCY = 10;
+/**
+ * Retention for generated derivatives under `assets/t/`.
+ *
+ * Everything under that prefix is REGENERABLE — source assets live under
+ * `asset-originals/` and are never touched by this rule. Without it the bucket
+ * keeps every derivative forever, including every object minted by the crop
+ * amplifier above.
+ *
+ * S3 lifecycle is prefix+age based; there is no "expire if not recently read"
+ * mode. Expiry is self-healing anyway: the next request for an expired
+ * derivative misses S3, fails over to the transform Lambda, regenerates and
+ * re-stores it — one invocation, then it is warm in both CloudFront and S3
+ * again. 180 days is set so ordinary traffic never notices and only genuinely
+ * cold or abusive objects age out.
+ */
+const TRANSFORM_OUTPUT_RETENTION = Duration.days(180);
 /**
  * `/assets/t/*`-specific cache TTLs. The managed `CachePolicy.CACHING_OPTIMIZED`
  * (used for the plain `/assets/*` static behavior) has a 1-second MIN TTL,
@@ -125,9 +162,17 @@ export class AssetSupport extends Construct {
                 versioned: props.versioned ?? false,
                 removalPolicy: props.removalPolicy ?? RemovalPolicy.RETAIN,
                 autoDeleteObjects: props.autoDeleteObjects ?? false,
-                // Only `asset-staging/` expires - originals/meta/public/transform
-                // outputs are all kept forever by design (content-addressed,
+                // `asset-staging/` expires after a day, and generated derivatives
+                // under `assets/t/` after `transformOutputRetention`. Originals, meta
+                // and the public prefix are kept forever by design (content-addressed,
                 // immutable - see the design record's "Storage" section).
+                //
+                // Derivatives were originally in that keep-forever set, on the same
+                // "immutable" reasoning. That holds for their CONTENT but not for
+                // their COUNT: `assets/t/` is the one prefix an anonymous caller can
+                // mint unbounded distinct keys in (see
+                // TRANSFORM_LAMBDA_RESERVED_CONCURRENCY), and unlike an original, a
+                // derivative that is deleted can simply be recomputed.
                 lifecycleRules: [
                     {
                         id: 'expire-asset-staging',
@@ -135,6 +180,12 @@ export class AssetSupport extends Construct {
                         prefix: `${PREFIXES.staging}/`,
                         expiration: Duration.days(1),
                     },
+                    {
+                        id: 'expire-transform-outputs',
+                        enabled: true,
+                        prefix: `${PREFIXES.transform}/`,
+                        expiration: props.transformOutputRetention ?? TRANSFORM_OUTPUT_RETENTION,
+                    },
                 ],
                 cors: [
                     {
@@ -179,6 +230,9 @@ export class AssetSupport extends Construct {
             architecture: lambda.Architecture.ARM_64,
             memorySize: TRANSFORM_LAMBDA_MEMORY_MB,
             timeout: TRANSFORM_LAMBDA_TIMEOUT,
+            // See the constant's doc comment: this is an anonymous, uncapped compute
+            // and storage amplifier without it.
+            reservedConcurrentExecutions: props.transformReservedConcurrency ?? TRANSFORM_LAMBDA_RESERVED_CONCURRENCY,
             // Pass the pre-created group via `logGroup`, NOT `logRetention` (CDK
             // throws LogRetentionLogGroupConflict/ConflictingLogPolicyOptions if
             // both are set on the same function) - the removal policy lives on the
@@ -220,7 +274,12 @@ export class AssetSupport extends Construct {
     }
     buildBehaviors() {
         const s3Origin = origins.S3BucketOrigin.withOriginAccessControl(this.bucket);
-        const transformLambdaOrigin = origins.FunctionUrlOrigin.withOriginAccessControl(this.transformFunctionUrl);
+        // readTimeout passed EXPLICITLY, matching the transform Lambda's own
+        // timeout. Unset, CloudFront applies its 30s service default, which
+        // happens to equal TRANSFORM_LAMBDA_TIMEOUT today -- an accidental match,
+        // not an asserted one: raising the Lambda's timeout alone would silently
+        // start 504ing the slow transforms the raise was meant to allow.
+        const transformLambdaOrigin = origins.FunctionUrlOrigin.withOriginAccessControl(this.transformFunctionUrl, { readTimeout: TRANSFORM_LAMBDA_TIMEOUT });
         const assets = {
             origin: s3Origin,
             viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
@@ -285,4 +344,3 @@ export class AssetSupport extends Construct {
         this.bucket.grantDelete(grantee, `${PREFIXES.meta}/*`);
     }
 }
-//# sourceMappingURL=asset-support.js.map

package/dist/constructs/cms-distribution.d.ts

@@ -1,5 +1,5 @@
 import { Construct } from 'constructs';
-import { aws_cloudfront as cloudfront, aws_certificatemanager as acm, aws_route53 as route53, aws_lambda as lambda } from 'aws-cdk-lib';
+import { Duration, aws_cloudfront as cloudfront, aws_certificatemanager as acm, aws_route53 as route53, aws_lambda as lambda } from 'aws-cdk-lib';
 export interface CanopyCmsDistributionProps {
     /** Lambda Function URL from CanopyCmsService */
     functionUrl: lambda.FunctionUrl;
@@ -11,6 +11,46 @@ export interface CanopyCmsDistributionProps {
     hostedZone?: route53.IHostedZone;
     /** Optional: provide an existing ACM certificate instead of creating one */
     certificate?: acm.ICertificate;
+    /**
+     * How long CloudFront waits for the origin to respond.
+     *
+     * Defaults to {@link DEFAULT_CMS_LAMBDA_TIMEOUT}, matching the CMS Lambda's
+     * own default. Pass `cmsService.timeout` when you override the Lambda's
+     * timeout, so the two cannot drift.
+     *
+     * Left unset on the origin, CloudFront applies its service default of **30
+     * seconds** — which silently caps a 60s Lambda at half its budget. Every
+     * request landing in the 30-60s band is answered 504 at the edge while the
+     * invocation continues to completion behind it: server-side success,
+     * viewer-facing failure, and nothing in either log explaining the other
+     * half. First-touch branch provisioning does a full `git clone` onto EFS
+     * inside the request, so this is a real path.
+     *
+     * Capped at 60s: CloudFront rejects more without a service-quota increase.
+     */
+    originReadTimeout?: Duration;
+    /**
+     * Extra CloudFront behaviors, merged with this construct's own.
+     *
+     * The reason this exists: `AssetSupport.assetBehaviors()` returns the two
+     * behaviors a media-enabled deployment needs (`/assets/*` and
+     * `/assets/t/*`), and without a way to pass them in there was no route to
+     * attach them to the distribution the scaffold generates — making the
+     * scaffold's own "uncomment to enable media" path a dead end.
+     *
+     * ORDER MATTERS. CloudFront matches path patterns in the order given, so a
+     * more specific pattern must be listed before a more general one that also
+     * matches: `/assets/t/*` before `/assets/*`, or every transform request is
+     * served by the static S3-only behavior and never fails over to the
+     * transform Lambda.
+     *
+     * Keys here override this construct's own behaviors on collision, which is
+     * deliberate — the caller is more specific than the default — and an
+     * overridden key takes YOUR position in this object, not the position the
+     * default held. (A plain object spread would do the opposite; see
+     * `mergeBehaviors`.)
+     */
+    additionalBehaviors?: Record<string, cloudfront.BehaviorOptions>;
 }
 /**
  * Optional CDK construct for CanopyCMS CloudFront distribution.
@@ -32,4 +72,3 @@ export declare class CanopyCmsDistribution extends Construct {
     readonly distribution: cloudfront.Distribution;
     constructor(scope: Construct, id: string, props: CanopyCmsDistributionProps);
 }
-//# sourceMappingURL=cms-distribution.d.ts.map

package/dist/constructs/cms-distribution.js

@@ -1,5 +1,27 @@
 import { Construct } from 'constructs';
-import { Duration, aws_cloudfront as cloudfront, aws_cloudfront_origins as origins, aws_certificatemanager as acm, aws_route53 as route53, aws_route53_targets as targets, } from 'aws-cdk-lib';
+import { Duration, Stack, Token, aws_cloudfront as cloudfront, aws_cloudfront_origins as origins, aws_certificatemanager as acm, aws_route53 as route53, aws_route53_targets as targets, } from 'aws-cdk-lib';
+import { DEFAULT_CMS_LAMBDA_TIMEOUT, MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT } from './cms-service.js';
+/**
+ * Merge caller behaviors over this construct's own, preserving THE CALLER'S
+ * ordering for every key they supply.
+ *
+ * A plain `{ ...defaults, ...caller }` gets the values right and the ORDER
+ * wrong: JavaScript keeps an overridden key at its first-insertion index, so a
+ * caller who overrides `/_next/static/*` finds it pinned ahead of every other
+ * pattern they passed, regardless of the order they wrote. Since CloudFront
+ * matches path patterns in order, that silently makes a more specific pattern
+ * listed after it unreachable -- exactly the failure the prop's doc comment
+ * warns callers to avoid, introduced by the merge itself.
+ *
+ * Dropping collided defaults FIRST means the caller's own object contributes
+ * its keys in its own order.
+ */
+function mergeBehaviors(defaults, caller) {
+    if (!caller)
+        return defaults;
+    const uncollided = Object.fromEntries(Object.entries(defaults).filter(([pattern]) => !(pattern in caller)));
+    return { ...uncollided, ...caller };
+}
 /**
  * Optional CDK construct for CanopyCMS CloudFront distribution.
  *
@@ -28,6 +50,25 @@ export class CanopyCmsDistribution extends Construct {
         // ========================================================================
         // ACM Certificate
         // ========================================================================
+        // CloudFront requires its ACM certificate to live in us-east-1, and this
+        // construct creates one in the STACK's region. Nothing in the construct,
+        // the scaffold, or docs/deploying-to-aws.md said so -- the scaffold merely
+        // asks for an AWS_REGION variable with us-east-1 as an example -- so an
+        // adopter elsewhere got an opaque region error and had to research both
+        // workarounds themselves. Fail with the answer instead.
+        //
+        // Only when the region is actually known at synth: a region-agnostic stack
+        // resolves to a token, and rejecting that would break `cdk synth` for
+        // everyone (the token is not us-east-1 as a string). Those deploys are
+        // rejected by CloudFront at deploy time as before.
+        const stackRegion = Stack.of(this).region;
+        if (!props.certificate && !Token.isUnresolved(stackRegion) && stackRegion !== 'us-east-1') {
+            throw new Error(`CanopyCmsDistribution: CloudFront requires its ACM certificate in us-east-1, but this ` +
+                `stack is in ${stackRegion}, so the certificate this construct would create cannot be ` +
+                `used. Either (a) create the certificate in a us-east-1 stack and pass it as the ` +
+                `\`certificate\` prop, or (b) deploy this stack in us-east-1. See ` +
+                `docs/deploying-to-aws.md.`);
+        }
         const certificate = props.certificate ??
             new acm.Certificate(this, 'Cert', {
                 domainName: props.domainName,
@@ -41,7 +82,22 @@ export class CanopyCmsDistribution extends Construct {
         // Function URL only accepts traffic from this distribution — direct hits to
         // the Function URL are rejected (DEP-H2). withOriginAccessControl creates
         // the OAC and grants CloudFront lambda:InvokeFunctionUrl automatically.
-        const origin = origins.FunctionUrlOrigin.withOriginAccessControl(props.functionUrl);
+        //
+        // readTimeout is passed EXPLICITLY. aws-cdk-lib emits it as
+        // `originReadTimeout: this.props.readTimeout?.toSeconds()` — omitted
+        // entirely when unset, so CloudFront's 30s service default applies and
+        // silently halves the CMS Lambda's 60s budget. See the prop's doc comment.
+        const readTimeout = props.originReadTimeout ?? DEFAULT_CMS_LAMBDA_TIMEOUT;
+        if (readTimeout.toSeconds() > MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT.toSeconds()) {
+            throw new Error(`CanopyCmsDistribution: originReadTimeout is ${readTimeout.toSeconds()}s, but CloudFront ` +
+                `allows at most ${MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT.toSeconds()}s without a service-quota ` +
+                `increase. Either lower the CMS Lambda's timeout to match, or request a quota increase for ` +
+                `"Origin response timeout" and pass the higher value explicitly. Deploying with a shorter ` +
+                `origin timeout than the Lambda's would 504 at the edge on requests that actually succeed.`);
+        }
+        const origin = origins.FunctionUrlOrigin.withOriginAccessControl(props.functionUrl, {
+            readTimeout,
+        });
         // Cache policy for API/editor routes: AWS's managed CACHING_DISABLED
         // policy. Deploy-proven (deploy-test epic, 2026-07-23): CloudFront
         // rejects ANY non-none cache-key setting on a caching-disabled policy -
@@ -98,13 +154,13 @@ export class CanopyCmsDistribution extends Construct {
                     },
                 ],
             },
-            additionalBehaviors: {
+            additionalBehaviors: mergeBehaviors({
                 '/_next/static/*': {
                     origin,
                     cachePolicy: staticCachePolicy,
                     viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
                 },
-            },
+            }, props.additionalBehaviors),
         });
         // ========================================================================
         // DNS Records
@@ -121,4 +177,3 @@ export class CanopyCmsDistribution extends Construct {
         });
     }
 }
-//# sourceMappingURL=cms-distribution.js.map

package/dist/constructs/cms-service.d.ts

@@ -1,6 +1,27 @@
 import { Construct } from 'constructs';
 import { Duration, RemovalPolicy, aws_ec2 as ec2, aws_efs as efs, aws_lambda as lambda, aws_autoscaling as autoscaling, aws_logs as logs } from 'aws-cdk-lib';
 import type { IBucket } from 'aws-cdk-lib/aws-s3';
+/**
+ * Default CMS Lambda timeout.
+ *
+ * Shared with `CanopyCmsDistribution`, which uses it as its default origin
+ * read timeout: CloudFront's own default is **30 seconds**, so leaving the
+ * origin unset silently caps this Lambda at half its budget. Requests in the
+ * gap are answered 504 at the edge while the invocation runs to completion
+ * behind them — first-touch branch provisioning does a full `git clone` onto
+ * EFS inside the request, so this is a real path, not a hypothetical one.
+ *
+ * One constant rather than two matching literals, so the pair cannot drift;
+ * `cms-deploy.test.ts` asserts the emitted template keeps them equal.
+ *
+ * NOTE: CloudFront accepts an origin read timeout up to 60s without a quota
+ * increase. A longer Lambda timeout needs an AWS quota increase before the
+ * distribution can match it — `CanopyCmsDistribution` fails at synth rather
+ * than deploying a configuration that would 504.
+ */
+export declare const DEFAULT_CMS_LAMBDA_TIMEOUT: Duration;
+/** CloudFront's maximum origin read timeout without a service-quota increase. */
+export declare const MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT: Duration;
 export interface CanopyCmsServiceProps {
     /** Docker image for the CMS Lambda function */
     cmsDockerImage: lambda.DockerImageCode;
@@ -22,7 +43,14 @@ export interface CanopyCmsServiceProps {
     architecture?: lambda.Architecture;
     /** EC2 spot max price (default: on-demand rate for t4g.nano) */
     spotMaxPrice?: string;
-    /** Secrets Manager ARNs the worker needs to read (GitHub token, Clerk key) */
+    /**
+     * ADDITIONAL Secrets Manager ARNs the worker may read.
+     *
+     * You do NOT need to repeat `githubTokenSecretArn` or
+     * `clerkSecretKeySecretArn` here — those are unioned into the worker's IAM
+     * policy automatically. Use this only for secrets the construct does not
+     * know about.
+     */
     secretsArns?: string[];
     /**
      * Environment variables for the Lambda function.
@@ -136,6 +164,17 @@ export interface CanopyCmsServiceProps {
 export declare class CanopyCmsService extends Construct {
     /** Lambda Function URL — use as CloudFront origin */
     readonly functionUrl: lambda.FunctionUrl;
+    /**
+     * The CMS Lambda's resolved timeout — `props.timeout` or
+     * {@link DEFAULT_CMS_LAMBDA_TIMEOUT}.
+     *
+     * Exposed so a distribution in front of this service can set its origin read
+     * timeout to the SAME value. CloudFront's own default is 30s, which silently
+     * caps a longer Lambda: every request landing in the gap is answered 504 at
+     * the edge while the invocation runs to completion behind it (see
+     * `CanopyCmsDistribution`'s `originReadTimeout`).
+     */
+    readonly timeout: Duration;
     /** The EFS filesystem */
     readonly fileSystem: efs.FileSystem;
     /** The VPC */
@@ -150,4 +189,3 @@ export declare class CanopyCmsService extends Construct {
     readonly workerLogGroup: logs.LogGroup;
     constructor(scope: Construct, id: string, props: CanopyCmsServiceProps);
 }
-//# sourceMappingURL=cms-service.d.ts.map

package/dist/constructs/cms-service.js

@@ -65,6 +65,27 @@ function assertEnvSafe(name, value) {
     }
     return value;
 }
+/**
+ * Default CMS Lambda timeout.
+ *
+ * Shared with `CanopyCmsDistribution`, which uses it as its default origin
+ * read timeout: CloudFront's own default is **30 seconds**, so leaving the
+ * origin unset silently caps this Lambda at half its budget. Requests in the
+ * gap are answered 504 at the edge while the invocation runs to completion
+ * behind them — first-touch branch provisioning does a full `git clone` onto
+ * EFS inside the request, so this is a real path, not a hypothetical one.
+ *
+ * One constant rather than two matching literals, so the pair cannot drift;
+ * `cms-deploy.test.ts` asserts the emitted template keeps them equal.
+ *
+ * NOTE: CloudFront accepts an origin read timeout up to 60s without a quota
+ * increase. A longer Lambda timeout needs an AWS quota increase before the
+ * distribution can match it — `CanopyCmsDistribution` fails at synth rather
+ * than deploying a configuration that would 504.
+ */
+export const DEFAULT_CMS_LAMBDA_TIMEOUT = Duration.seconds(60);
+/** CloudFront's maximum origin read timeout without a service-quota increase. */
+export const MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT = Duration.seconds(60);
 /**
  * Core CDK construct for CanopyCMS deployment.
  *
@@ -258,10 +279,11 @@ export class CanopyCmsService extends Construct {
             retention: props.cmsLogRetention ?? logs.RetentionDays.THREE_MONTHS,
             removalPolicy: RemovalPolicy.DESTROY,
         });
+        this.timeout = props.timeout ?? DEFAULT_CMS_LAMBDA_TIMEOUT;
         this.lambdaFunction = new lambda.DockerImageFunction(this, 'CmsFunction', {
             code: props.cmsDockerImage,
             memorySize: props.memorySize ?? 2048,
-            timeout: props.timeout ?? Duration.seconds(60),
+            timeout: this.timeout,
             reservedConcurrentExecutions: props.reservedConcurrency ?? 10,
             architecture: props.architecture,
             vpc: this.vpc,
@@ -368,11 +390,33 @@ export class CanopyCmsService extends Construct {
             assumedBy: new iam.ServicePrincipal('ec2.amazonaws.com'),
             description: 'CanopyCMS EC2 Worker role',
         });
-        // Worker needs to read secrets
-        if (props.secretsArns && props.secretsArns.length > 0) {
+        // Worker needs to read secrets.
+        //
+        // The grant is the UNION of `secretsArns` and the individual ARN props,
+        // because the construct previously carried two disconnected
+        // representations of "the secrets the worker reads": `secretsArns` fed
+        // this policy, while `githubTokenSecretArn`/`clerkSecretKeySecretArn` fed
+        // only the worker's `.env`. An adopter hand-writing their stack (both are
+        // individually documented, and `secretsArns`'s doc comment did not say it
+        // was the sole source of IAM) could set the individual props and omit
+        // `secretsArns` -- producing a worker that knows WHICH secret to read and
+        // has no permission to read it. `cdk deploy` succeeded; the worker booted,
+        // got AccessDenied from GetSecretValue, exited, and systemd restart-looped
+        // it every 5s forever. Nothing flagged it at synth.
+        //
+        // Deduped so the emitted policy does not list the same ARN twice when an
+        // adopter correctly passes both.
+        const secretsArns = [
+            ...new Set([
+                ...(props.secretsArns ?? []),
+                props.githubTokenSecretArn,
+                props.clerkSecretKeySecretArn,
+            ].filter((arn) => typeof arn === 'string' && arn.length > 0)),
+        ];
+        if (secretsArns.length > 0) {
             workerRole.addToPolicy(new iam.PolicyStatement({
                 actions: ['secretsmanager:GetSecretValue'],
-                resources: props.secretsArns,
+                resources: secretsArns,
             }));
         }
         // Worker needs EFS access (handled via security group, but mount needs ec2:DescribeAvailabilityZones)
@@ -428,7 +472,7 @@ export class CanopyCmsService extends Construct {
             .join('\n');
         // UserData script
         const userData = ec2.UserData.forLinux();
-        userData.addCommands('#!/bin/bash', 'set -euo pipefail', '', '# Install dependencies (unzip is not guaranteed in the AL2023 AMI)', 'yum install -y git unzip', 'curl -fsSL https://rpm.nodesource.com/setup_20.x | bash -', 'yum install -y nodejs', '', '# Mount EFS', 'yum install -y amazon-efs-utils', 'mkdir -p /mnt/efs', `mount -t efs ${this.fileSystem.fileSystemId}:/ /mnt/efs`, '# Persist the mount across instance reboots: user-data runs once per', '# instance, so without an fstab entry a plain reboot leaves /mnt/efs an', '# empty local dir and the worker would clone a divergent remote.git', '# onto the instance disk, invisible to the Lambda.', `echo '${this.fileSystem.fileSystemId}:/ /mnt/efs efs _netdev 0 0' >> /etc/fstab`, '', '# Download worker from CDK S3 Asset', `aws s3 cp s3://${workerAsset.s3BucketName}/${workerAsset.s3ObjectKey} /tmp/canopy-worker.zip`, 'mkdir -p /opt/canopy-worker', 'cd /opt/canopy-worker', 'unzip -o /tmp/canopy-worker.zip', '# The worker bundle is ESM (esbuild --format=esm). Node 20 treats .js as', '# CommonJS without this marker and crash-loops on the import statement', '# (Node >=22.7 auto-detects and masks the bug locally).', `echo '{"type":"module"}' > /opt/canopy-worker/package.json`, '', '# Write environment file for systemd service', `cat > /opt/canopy-worker/.env << 'ENVEOF'`, envFileContent, 'ENVEOF', '', '# Create systemd service', `cat > /etc/systemd/system/canopy-worker.service << 'SVCEOF'`, '[Unit]', 'Description=CanopyCMS Worker Daemon', 'After=network.target', '# Never run against an unmounted /mnt/efs (see the fstab note above).', 'RequiresMountsFor=/mnt/efs', '', '[Service]', 'Type=simple', 'User=ec2-user', 'WorkingDirectory=/opt/canopy-worker', 'ExecStart=/usr/bin/node index.js', 'Restart=always', 'RestartSec=5', 'TimeoutStartSec=300', '# File output, not journal: the CloudWatch agent cannot read journald,', '# so it tails this file instead (see the agent config below).', '# CAUTION: /var/log/canopy-worker must exist BEFORE first start. systemd', '# opens append: targets before it creates LogsDirectory= dirs', '# (systemd#27591), so without the pre-created dir the exec fails with', '# 209/STDOUT and Restart=always crash-loops forever. User-data runs', '# mkdir before systemctl start; LogsDirectory= is kept for ownership.', 'LogsDirectory=canopy-worker', 'StandardOutput=append:/var/log/canopy-worker/worker.log', 'StandardError=append:/var/log/canopy-worker/worker.log', 'EnvironmentFile=/opt/canopy-worker/.env', '', '[Install]', 'WantedBy=multi-user.target', 'SVCEOF', '', '# Set ownership for ec2-user', 'chown -R ec2-user:ec2-user /opt/canopy-worker', '# Non-recursive: EFS access point enforces UID 1000 for Lambda.', '# Only set ownership on mount point and workspace dir to avoid', '# slow recursive chown on large filesystems during ASG replacements.', 'chown ec2-user:ec2-user /mnt/efs', 'mkdir -p /mnt/efs/workspace', 'chown ec2-user:ec2-user /mnt/efs/workspace', '', '# Pre-create the worker log dir (crash-loop guard, MUST precede the', '# first systemctl start): systemd opens StandardOutput=append: files', '# BEFORE it creates LogsDirectory= dirs (systemd#27591), so on a fresh', '# instance the unit would fail exec with 209/STDOUT and crash-loop', '# forever without this. The unit keeps LogsDirectory= for ownership', '# management on subsequent starts.', 'mkdir -p /var/log/canopy-worker', 'chown ec2-user:ec2-user /var/log/canopy-worker', '', '# Start worker', 'systemctl daemon-reload', 'systemctl enable canopy-worker', 'systemctl start canopy-worker', '', '# ---- CloudWatch log shipping ----', '# Placed AFTER worker start: with set -euo pipefail, a yum/agent failure', '# here must not prevent the worker from running (shipping is best-effort).', 'yum install -y amazon-cloudwatch-agent logrotate', '', '# Bound on-disk growth; copytruncate keeps the fd the CW agent tails valid', '# (tiny copy->truncate loss window is acceptable for diagnostic logs).', `cat > /etc/logrotate.d/canopy-worker << 'ROTEOF'`, '/var/log/canopy-worker/worker.log {', '    size 10M', '    rotate 5', '    compress', '    copytruncate', '    missingok', '    notifempty', '}', 'ROTEOF', '# The config above only fires when logrotate actually runs; AL2023', '# presets may leave logrotate.timer disabled, and without it the size', '# cap never triggers and worker.log grows until the nano disk fills.', '# --now is idempotent if the timer is already enabled/running.', 'systemctl enable --now logrotate.timer', '', '# No retention_in_days here: CDK owns retention on the pre-created group.', `cat > /opt/aws/amazon-cloudwatch-agent/etc/canopy-worker-logs.json << 'CWEOF'`, '{', '  "logs": {', '    "logs_collected": {', '      "files": {', '        "collect_list": [', '          {', '            "file_path": "/var/log/canopy-worker/worker.log",', `            "log_group_name": "${this.workerLogGroup.logGroupName}",`, '            "log_stream_name": "{instance_id}",', 
+        userData.addCommands('#!/bin/bash', 'set -euo pipefail', '', '# FAIL-FAST. Every step below is required for the worker to exist at', '# all, and until this trap existed a failure in any of them aborted', '# user-data BEFORE the systemd unit was written -- leaving an instance', "# that runs, passes the ASG's EC2-only health check indefinitely, and", '# does nothing. cfn-signal is deliberately not used here (it would', '# prove nothing about READINESS, which is the argument recorded below),', '# but that argument never covered a boot-SCRIPT failure: `cdk deploy`', '# reported success while publishes queued on EFS, the auth cache went', '# stale and PRs stopped being created, until a human noticed the admin', '# panel showing the worker absent.', '#', '# Shutting down makes the instance fail its EC2 health check, so the ASG', '# replaces it -- which is the only automatic recovery available in this', '# topology. The echo lands in the console log, readable via', '# `aws ec2 get-console-output`, because the CloudWatch agent is itself', '# configured further down and cannot be relied on to exist yet.', 'trap \'echo "canopy-worker user-data FAILED at line $LINENO (exit $?)" >&2; shutdown -h now\' ERR', '', '# Bounded retry for the network-dependent steps. Package mirrors and S3', '# have transient failures; a single flake should cost seconds, not an', '# instance replacement.', 'retry() {', '  local n=0', '  until "$@"; do', '    n=$((n + 1))', '    if [ "$n" -ge 5 ]; then', '      echo "canopy-worker: command failed after $n attempts: $*" >&2', '      return 1', '    fi', '    sleep $((n * 5))', '  done', '}', '', '# Install dependencies (unzip is not guaranteed in the AL2023 AMI)', 'retry dnf install -y git unzip', "# Node comes from AL2023's own repos, NOT a piped third-party installer.", '# The previous boot curled the NodeSource RPM setup script straight into', '# bash, so every instance replacement -- which the ASG performs on every', '# `cdk deploy`, plus every spot interruption -- depended on a third party', '# being reachable. cms-deploy.test.ts asserts that URL never comes back,', '# which is why it is not spelled out here.', '#', '# nodejs22, not 20: Node 20 reached upstream EOL on 2026-04-30, and this', '# repo declares `engines.node: ">=22"` with .nvmrc `v22`, so the worker', '# was running an EOL runtime BELOW the floor its own code is tested at.', "# 22 (EOL 2027-04-30) matches .nvmrc, CI, and the transform Lambda's", '# NODEJS_22_X, so one runtime is tested everywhere.', '#', '# ExecStart uses the NAMESPACED /usr/bin/node-22 (see the systemd unit', '# below), not the bare `node`: AL2023 installs versioned binaries and', '# points `/usr/bin/node` at one of them through `alternatives`, whose', '# selection AWS documents as able to change at any time.', 'retry dnf install -y nodejs22', '', '# Mount EFS', 'retry dnf install -y amazon-efs-utils', 'mkdir -p /mnt/efs', `mount -t efs ${this.fileSystem.fileSystemId}:/ /mnt/efs`, '# Persist the mount across instance reboots: user-data runs once per', '# instance, so without an fstab entry a plain reboot leaves /mnt/efs an', '# empty local dir and the worker would clone a divergent remote.git', '# onto the instance disk, invisible to the Lambda.', `echo '${this.fileSystem.fileSystemId}:/ /mnt/efs efs _netdev 0 0' >> /etc/fstab`, '', '# Download worker from CDK S3 Asset', `retry aws s3 cp s3://${workerAsset.s3BucketName}/${workerAsset.s3ObjectKey} /tmp/canopy-worker.zip`, 'mkdir -p /opt/canopy-worker', 'cd /opt/canopy-worker', 'unzip -o /tmp/canopy-worker.zip', '# The worker bundle is ESM (esbuild --format=esm). Without this marker a', '# .js file is CommonJS by default and the import statement fails.', '# Node >=22.7 auto-detects module syntax and would mask its absence, and', '# this instance now runs node-22 -- so the marker is kept BECAUSE that', '# auto-detection is a fallback we should not depend on, not because the', '# runtime here still needs it.', `echo '{"type":"module"}' > /opt/canopy-worker/package.json`, '', '# Write environment file for systemd service', `cat > /opt/canopy-worker/.env << 'ENVEOF'`, envFileContent, 'ENVEOF', '', '# Create systemd service', `cat > /etc/systemd/system/canopy-worker.service << 'SVCEOF'`, '[Unit]', 'Description=CanopyCMS Worker Daemon', 'After=network.target', '# Never run against an unmounted /mnt/efs (see the fstab note above).', 'RequiresMountsFor=/mnt/efs', '', '[Service]', 'Type=simple', 'User=ec2-user', 'WorkingDirectory=/opt/canopy-worker', '# Namespaced binary, not bare `node`: AL2023 points /usr/bin/node at', '# an installed version through `alternatives`, and AWS documents that', '# selection as able to change at any time. node-22 always means 22.', 'ExecStart=/usr/bin/node-22 index.js', 'Restart=always', 'RestartSec=5', 'TimeoutStartSec=300', '# File output, not journal: the CloudWatch agent cannot read journald,', '# so it tails this file instead (see the agent config below).', '# CAUTION: /var/log/canopy-worker must exist BEFORE first start. systemd', '# opens append: targets before it creates LogsDirectory= dirs', '# (systemd#27591), so without the pre-created dir the exec fails with', '# 209/STDOUT and Restart=always crash-loops forever. User-data runs', '# mkdir before systemctl start; LogsDirectory= is kept for ownership.', 'LogsDirectory=canopy-worker', 'StandardOutput=append:/var/log/canopy-worker/worker.log', 'StandardError=append:/var/log/canopy-worker/worker.log', 'EnvironmentFile=/opt/canopy-worker/.env', '', '[Install]', 'WantedBy=multi-user.target', 'SVCEOF', '', '# Set ownership for ec2-user', 'chown -R ec2-user:ec2-user /opt/canopy-worker', '# Non-recursive: EFS access point enforces UID 1000 for Lambda.', '# Only set ownership on mount point and workspace dir to avoid', '# slow recursive chown on large filesystems during ASG replacements.', 'chown ec2-user:ec2-user /mnt/efs', 'mkdir -p /mnt/efs/workspace', 'chown ec2-user:ec2-user /mnt/efs/workspace', '', '# Pre-create the worker log dir (crash-loop guard, MUST precede the', '# first systemctl start): systemd opens StandardOutput=append: files', '# BEFORE it creates LogsDirectory= dirs (systemd#27591), so on a fresh', '# instance the unit would fail exec with 209/STDOUT and crash-loop', '# forever without this. The unit keeps LogsDirectory= for ownership', '# management on subsequent starts.', 'mkdir -p /var/log/canopy-worker', 'chown ec2-user:ec2-user /var/log/canopy-worker', '', '# Start worker', 'systemctl daemon-reload', 'systemctl enable canopy-worker', 'systemctl start canopy-worker', '', '# ---- CloudWatch log shipping ----', '# Placed AFTER worker start: with set -euo pipefail, a package/agent', '# failure here must not prevent the worker from running (shipping is', '# best-effort).', '#', '# DISARM THE FAIL-FAST TRAP AND errexit FIRST. Everything above this line', '# is required for the worker to exist at all, so a failure there should', '# replace the instance. Nothing below it is: the worker is already', '# running and healthy by this point. Leaving the trap armed would let a', '# package-mirror outage during the agent install shut down a perfectly', '# good worker -- and the ASG would relaunch straight into the same', '# outage, turning degraded log shipping into a replacement loop with the', '# worker down for its duration. That is strictly worse than the', '# best-effort behaviour this section has always documented.', 'trap - ERR', 'set +e', 'retry dnf install -y amazon-cloudwatch-agent logrotate', '', '# Bound on-disk growth; copytruncate keeps the fd the CW agent tails valid', '# (tiny copy->truncate loss window is acceptable for diagnostic logs).', `cat > /etc/logrotate.d/canopy-worker << 'ROTEOF'`, '/var/log/canopy-worker/worker.log {', '    size 10M', '    rotate 5', '    compress', '    copytruncate', '    missingok', '    notifempty', '}', 'ROTEOF', '# The config above only fires when logrotate actually runs; AL2023', '# presets may leave logrotate.timer disabled, and without it the size', '# cap never triggers and worker.log grows until the nano disk fills.', '# --now is idempotent if the timer is already enabled/running.', 'systemctl enable --now logrotate.timer', '', '# No retention_in_days here: CDK owns retention on the pre-created group.', `cat > /opt/aws/amazon-cloudwatch-agent/etc/canopy-worker-logs.json << 'CWEOF'`, '{', '  "logs": {', '    "logs_collected": {', '      "files": {', '        "collect_list": [', '          {', '            "file_path": "/var/log/canopy-worker/worker.log",', `            "log_group_name": "${this.workerLogGroup.logGroupName}",`, '            "log_stream_name": "{instance_id}",', 
         // The worker prefixes every line with an ISO-8601 timestamp
         // (packages/canopycms/src/worker/log.ts). Parsing it here is what makes
         // CloudWatch show the time the WORKER emitted a line rather than the
@@ -538,4 +582,3 @@ export class CanopyCmsService extends Construct {
         this.workerAsg.node.addDependency(this.fileSystem.mountTargetsAvailable);
     }
 }
-//# sourceMappingURL=cms-service.js.map

package/dist/index.d.ts

@@ -1,9 +1,8 @@
-export { CmsWorker } from './worker';
-export type { CmsWorkerConfig } from './worker';
-export { CanopyCmsService } from './constructs/cms-service';
-export type { CanopyCmsServiceProps } from './constructs/cms-service';
-export { CanopyCmsDistribution } from './constructs/cms-distribution';
-export type { CanopyCmsDistributionProps } from './constructs/cms-distribution';
-export { AssetSupport } from './constructs/asset-support';
-export type { AssetSupportProps, AssetCloudFrontBehaviors } from './constructs/asset-support';
-//# sourceMappingURL=index.d.ts.map
+export { CmsWorker } from './worker.js';
+export type { CmsWorkerConfig } from './worker.js';
+export { CanopyCmsService } from './constructs/cms-service.js';
+export type { CanopyCmsServiceProps } from './constructs/cms-service.js';
+export { CanopyCmsDistribution } from './constructs/cms-distribution.js';
+export type { CanopyCmsDistributionProps } from './constructs/cms-distribution.js';
+export { AssetSupport } from './constructs/asset-support.js';
+export type { AssetSupportProps, AssetCloudFrontBehaviors } from './constructs/asset-support.js';

package/dist/index.js

@@ -1,7 +1,6 @@
 // Worker daemon
-export { CmsWorker } from './worker';
+export { CmsWorker } from './worker.js';
 // CDK Constructs
-export { CanopyCmsService } from './constructs/cms-service';
-export { CanopyCmsDistribution } from './constructs/cms-distribution';
-export { AssetSupport } from './constructs/asset-support';
-//# sourceMappingURL=index.js.map
+export { CanopyCmsService } from './constructs/cms-service.js';
+export { CanopyCmsDistribution } from './constructs/cms-distribution.js';
+export { AssetSupport } from './constructs/asset-support.js';

package/dist/worker.d.ts

@@ -5,4 +5,3 @@
  */
 export { CmsWorker } from 'canopycms/worker/cms-worker';
 export type { CmsWorkerConfig, AuthCacheRefresher } from 'canopycms/worker/cms-worker';
-//# sourceMappingURL=worker.d.ts.map

package/dist/worker.js

@@ -4,4 +4,3 @@
  * This file re-exports it for convenience from the CDK package.
  */
 export { CmsWorker } from 'canopycms/worker/cms-worker';
-//# sourceMappingURL=worker.js.map