canopycms-cdk 0.6.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -22,7 +22,7 @@ What changed in each release, for all five CanopyCMS packages, is in `node_modul
22
22
  **`CanopyCmsDistribution`** — CloudFront + DNS (optional):
23
23
 
24
24
  - ACM certificate with DNS validation
25
- - CloudFront distribution with Lambda Function URL origin
25
+ - CloudFront distribution with Lambda Function URL origin; its read timeout follows the Lambda's (60 s by default, at most 120 s, CloudFront's default quota)
26
26
  - Route53 A/AAAA alias records
27
27
  - Cache policies: no-cache for API/editor, long-cache for static assets
28
28
  - Response headers: framing protection (`frame-ancestors 'self'`), `nosniff`, HSTS, `X-Robots-Tag: noindex`
@@ -26,7 +26,7 @@ export interface CanopyCmsDistributionProps {
26
26
  * First-touch branch provisioning does a full `git clone` onto EFS inside the
27
27
  * request, so this is a real path.
28
28
  *
29
- * Capped at 60s: CloudFront rejects more without a service-quota increase.
29
+ * Capped at 120s (`MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT`), CloudFront's default quota.
30
30
  */
31
31
  originReadTimeout?: Duration;
32
32
  /**
@@ -25,10 +25,10 @@ export declare function withoutShellComments(...lines: string[]): string[];
25
25
  * One constant rather than two matching literals, so the pair cannot drift;
26
26
  * `cms-deploy.test.ts` asserts the emitted template keeps them equal.
27
27
  *
28
- * NOTE: CloudFront accepts an origin read timeout up to 60s without a quota
29
- * increase. A longer Lambda timeout needs an AWS quota increase before the
30
- * distribution can match it — `CanopyCmsDistribution` fails at synth rather
31
- * than deploying a configuration that would 504.
28
+ * NOTE: the Lambda timeout may not exceed `MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT`
29
+ * (120s, CloudFront's default origin response timeout quota):
30
+ * `CanopyCmsDistribution` and `attachTo` fail at synth rather than deploying a
31
+ * configuration that would 504.
32
32
  */
33
33
  export declare const DEFAULT_CMS_LAMBDA_TIMEOUT: Duration;
34
34
  /**
@@ -47,7 +47,7 @@ export interface CanopyCmsServiceProps {
47
47
  vpc?: ec2.IVpc;
48
48
  /** Lambda memory in MB (default: 2048) */
49
49
  memorySize?: number;
50
- /** Lambda timeout (default: 60 seconds) */
50
+ /** Lambda timeout (default: 60 seconds; at most 120 seconds, see {@link DEFAULT_CMS_LAMBDA_TIMEOUT}) */
51
51
  timeout?: Duration;
52
52
  /**
53
53
  * Cap on the CMS Lambda's concurrent invocations (default: 50).
@@ -396,8 +396,10 @@ export interface CanopyCmsServiceProps {
396
396
  * started and a worker whose loops have stopped. A deploy or a spot
397
397
  * replacement does not trip it. See `workerDownAlarm`.
398
398
  *
399
- * The topic is also notified when a worker boot could not upgrade its
400
- * packages and started on the AMI's. See `workerUnpatchedAlarm`.
399
+ * It is also notified when a live worker's git-sync cycles have all failed
400
+ * for an hour, and on recovery. See `workerSyncFailingAlarm`. And it is
401
+ * notified when a worker boot could not upgrade its packages and started on
402
+ * the AMI's. See `workerUnpatchedAlarm`.
401
403
  */
402
404
  alarmTopic?: sns.ITopic;
403
405
  /**
@@ -518,6 +520,11 @@ export declare class CanopyCmsService extends Construct {
518
520
  readonly workerLogGroup: logs.LogGroup;
519
521
  /** Alarms when the worker logs no git-sync cycle for 30 minutes. Set only with `alarmTopic`. */
520
522
  readonly workerDownAlarm?: cloudwatch.Alarm;
523
+ /**
524
+ * Alarms when the worker's git-sync cycles start but none completes for an hour. Set only with
525
+ * `alarmTopic`.
526
+ */
527
+ readonly workerSyncFailingAlarm?: cloudwatch.Alarm;
521
528
  /** Alarms when a worker boot started without its package upgrade. Set only with `alarmTopic`. */
522
529
  readonly workerUnpatchedAlarm?: cloudwatch.Alarm;
523
530
  /**
@@ -3,7 +3,7 @@ import { Annotations, ArnFormat, Duration, Names, RemovalPolicy, Stack, Token, T
3
3
  import { attachLambdaExecutionPolicies } from './lambda-execution-role.js';
4
4
  import { INSTANCE_FILES_DOWNLOAD_PATH, WORKER_BUNDLE_DOWNLOAD_PATH, workerBundleSource, } from './worker-bundle.js';
5
5
  import { attachEditorBehaviors } from './editor-routing.js';
6
- import { GATEWAY_SPLIT_CONTRACT, WORKER_CAPACITY_ENV, WORKER_CONTRACT_BANNER_PREFIX, WORKER_DRAIN_HOOK_NAME, WORKER_SYNC_LOG_PHRASE, } from './worker-lifecycle.js';
6
+ import { GATEWAY_SPLIT_CONTRACT, WORKER_CAPACITY_ENV, WORKER_CONTRACT_BANNER_PREFIX, WORKER_DRAIN_HOOK_NAME, WORKER_SYNC_DONE_LOG_PHRASE, WORKER_SYNC_LOG_PHRASE, } from './worker-lifecycle.js';
7
7
  import { CANOPY_INSPECT, EFS_MOUNT_PATH, GATEWAY_LOG, GATEWAY_LOG_DIR, GATEWAY_USER, INSPECT_CHECKS, INSPECT_RC, INSTANCE_FILES_DIR, WORKER_INSTALL_DIR, WORKER_LOG, WORKER_LOG_DIR, } from './worker-units.js';
8
8
  /**
9
9
  * Synth-time mirror of `resolveDeploymentName`'s rule in the `canopycms`
@@ -577,10 +577,10 @@ function assertGitHubAuthProps(props) {
577
577
  * One constant rather than two matching literals, so the pair cannot drift;
578
578
  * `cms-deploy.test.ts` asserts the emitted template keeps them equal.
579
579
  *
580
- * NOTE: CloudFront accepts an origin read timeout up to 60s without a quota
581
- * increase. A longer Lambda timeout needs an AWS quota increase before the
582
- * distribution can match it — `CanopyCmsDistribution` fails at synth rather
583
- * than deploying a configuration that would 504.
580
+ * NOTE: the Lambda timeout may not exceed `MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT`
581
+ * (120s, CloudFront's default origin response timeout quota):
582
+ * `CanopyCmsDistribution` and `attachTo` fail at synth rather than deploying a
583
+ * configuration that would 504.
584
584
  */
585
585
  export const DEFAULT_CMS_LAMBDA_TIMEOUT = Duration.seconds(60);
586
586
  /**
@@ -1092,6 +1092,52 @@ export class CanopyCmsService extends Construct {
1092
1092
  const topicAction = new cloudwatchActions.SnsAction(props.alarmTopic);
1093
1093
  this.workerDownAlarm.addAlarmAction(topicAction);
1094
1094
  this.workerDownAlarm.addOkAction(topicAction);
1095
+ const completionsPrefix = 'WorkerGitSyncCompletions-';
1096
+ const syncCompletions = new logs.MetricFilter(this, 'WorkerSyncCompletions', {
1097
+ logGroup: this.workerLogGroup,
1098
+ filterPattern: logs.FilterPattern.literal(`"${WORKER_SYNC_DONE_LOG_PHRASE}"`),
1099
+ metricNamespace: 'CanopyCMS',
1100
+ metricName: `${completionsPrefix}${Names.uniqueResourceName(this, { maxLength: 255 - completionsPrefix.length })}`,
1101
+ metricValue: '1',
1102
+ // Every other event in the group emits 0, the cycle-start line included, so a period
1103
+ // with a start always has a completion count, and the expression below never compares
1104
+ // a missing one: a worker that has never completed a cycle still alarms.
1105
+ defaultValue: 0,
1106
+ });
1107
+ // A period with a cycle start is 1 when no cycle completed in it and 0 when one did; a
1108
+ // period with no start has no data point at all (IF drops it). CloudWatch judges the two
1109
+ // most recent real points, reaching back past such gaps within its evaluation range, and
1110
+ // `ignore` keeps the state when fewer remain. So a worker that is down neither pages here
1111
+ // (the down alarm owns that case, and one outage pages once) nor reads as recovered.
1112
+ // Every 30-minute window holds a start whenever cycles start less than 30 minutes apart,
1113
+ // which is where the down alarm takes over: cycles start the sync interval after the last
1114
+ // one ends, so a slow failing cycle or a longer interval cannot leave a gap between the
1115
+ // two. Two in a row, an hour or more, keeps a short GitHub incident from paging. The
1116
+ // schema gate's hold completes its cycle, and a drain is minutes long.
1117
+ this.workerSyncFailingAlarm = new cloudwatch.Alarm(this, 'WorkerSyncFailingAlarm', {
1118
+ metric: new cloudwatch.MathExpression({
1119
+ expression: 'IF(started, completed == 0)',
1120
+ usingMetrics: {
1121
+ started: syncCycles.metric({ statistic: 'Sum', period: Duration.minutes(30) }),
1122
+ completed: syncCompletions.metric({ statistic: 'Sum', period: Duration.minutes(30) }),
1123
+ },
1124
+ period: Duration.minutes(30),
1125
+ label: 'Periods with git-sync cycles and no completed one',
1126
+ }),
1127
+ threshold: 1,
1128
+ comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
1129
+ evaluationPeriods: 2,
1130
+ datapointsToAlarm: 2,
1131
+ treatMissingData: cloudwatch.TreatMissingData.IGNORE,
1132
+ alarmDescription: `The CMS worker is running, but none of its git syncs has completed for an hour, so ` +
1133
+ `publishing and branch syncing are stalled. Check GitHub's status first: an outage ` +
1134
+ `fails every sync, and this clears on its own when syncs succeed again. Otherwise read ` +
1135
+ `the last git sync error in System health in the editor's admin panel, and the worker ` +
1136
+ `log group ${this.workerLogGroup.logGroupName}. In workerCode parameter mode, a ` +
1137
+ `template deployed ahead of its bundle also fires this until the bundle rolls.`,
1138
+ });
1139
+ this.workerSyncFailingAlarm.addAlarmAction(topicAction);
1140
+ this.workerSyncFailingAlarm.addOkAction(topicAction);
1095
1141
  const unpatchedPrefix = 'WorkerUnpatchedBoots-';
1096
1142
  const unpatchedBoots = new logs.MetricFilter(this, 'WorkerUnpatchedBoots', {
1097
1143
  logGroup: this.workerLogGroup,
@@ -1,6 +1,16 @@
1
1
  import { Construct } from 'constructs';
2
2
  import { Duration, aws_cloudfront as cloudfront, aws_lambda as lambda } from 'aws-cdk-lib';
3
- /** CloudFront's maximum origin read timeout without a service-quota increase. */
3
+ /**
4
+ * The longest origin read timeout these constructs accept: CloudFront's default
5
+ * quota for "Response timeout per origin" (1-120 s; 30 s unset; CloudFront Developer Guide,
6
+ * Quotas > General quotas on distributions).
7
+ *
8
+ * A cap rather than a pass-through of a raised quota because the editor's client
9
+ * deadline sits just above it (`REQUEST_TIMEOUT_MS` in canopycms
10
+ * `api/request-deadline.ts`, pinned by `request-deadline-pin.test.ts`) and cannot
11
+ * see the account's quota: a longer origin would be given up on by the browser
12
+ * before CloudFront answers.
13
+ */
4
14
  export declare const MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT: Duration;
5
15
  /**
6
16
  * The routes the editor needs from the CMS Lambda on a distribution it shares
@@ -21,9 +31,8 @@ export declare const EDITOR_PATH_PATTERNS: readonly ["/edit", "/edit/*", "/api/c
21
31
  */
22
32
  export declare function cloudFrontPathPatternMatches(pattern: string, path: string): boolean;
23
33
  /**
24
- * Throws when the origin read timeout exceeds the 60s CloudFront accepts
25
- * without a quota increase, which it would reject at deploy. Neither construct
26
- * takes a higher, quota-raised value.
34
+ * Throws when the origin read timeout exceeds {@link MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT},
35
+ * so a configuration the editor's deadline cannot cover fails at synth, not mid-deploy.
27
36
  */
28
37
  export declare function assertOriginReadTimeout(readTimeout: Duration, owner: string): void;
29
38
  /**
@@ -1,8 +1,18 @@
1
1
  import { Construct } from 'constructs';
2
2
  import { Annotations, Duration, Stack, aws_cloudfront as cloudfront, aws_cloudfront_origins as origins, } from 'aws-cdk-lib';
3
3
  import { ASSETS_PATH_PATTERN, ASSETS_TRANSFORM_PATH_PATTERN } from './asset-support.js';
4
- /** CloudFront's maximum origin read timeout without a service-quota increase. */
5
- export const MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT = Duration.seconds(60);
4
+ /**
5
+ * The longest origin read timeout these constructs accept: CloudFront's default
6
+ * quota for "Response timeout per origin" (1-120 s; 30 s unset; CloudFront Developer Guide,
7
+ * Quotas > General quotas on distributions).
8
+ *
9
+ * A cap rather than a pass-through of a raised quota because the editor's client
10
+ * deadline sits just above it (`REQUEST_TIMEOUT_MS` in canopycms
11
+ * `api/request-deadline.ts`, pinned by `request-deadline-pin.test.ts`) and cannot
12
+ * see the account's quota: a longer origin would be given up on by the browser
13
+ * before CloudFront answers.
14
+ */
15
+ export const MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT = Duration.seconds(120);
6
16
  /**
7
17
  * The routes the editor needs from the CMS Lambda on a distribution it shares
8
18
  * with a site: the editor page and the catch-all API route `canopycms init`
@@ -72,17 +82,18 @@ export function cloudFrontPathPatternMatches(pattern, path) {
72
82
  return g === glob.length;
73
83
  }
74
84
  /**
75
- * Throws when the origin read timeout exceeds the 60s CloudFront accepts
76
- * without a quota increase, which it would reject at deploy. Neither construct
77
- * takes a higher, quota-raised value.
85
+ * Throws when the origin read timeout exceeds {@link MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT},
86
+ * so a configuration the editor's deadline cannot cover fails at synth, not mid-deploy.
78
87
  */
79
88
  export function assertOriginReadTimeout(readTimeout, owner) {
80
- if (readTimeout.toSeconds() > MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT.toSeconds()) {
81
- throw new Error(`${owner}: originReadTimeout is ${readTimeout.toSeconds()}s, but CloudFront ` +
82
- `allows at most ${MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT.toSeconds()}s without a service-quota ` +
83
- `increase, and these constructs do not take a higher value. Lower the CMS Lambda's ` +
84
- `timeout to ${MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT.toSeconds()}s or less. A shorter origin ` +
85
- `timeout than the Lambda's would 504 at the edge on requests that actually succeed.`);
89
+ const max = MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT.toSeconds();
90
+ if (readTimeout.toSeconds() > max) {
91
+ throw new Error(`${owner}: originReadTimeout is ${readTimeout.toSeconds()}s, but these constructs ` +
92
+ `support at most ${max}s, CloudFront's default quota for "Response timeout per ` +
93
+ `origin" (Service Quotas > CloudFront). Raising that quota does not lift this ` +
94
+ `limit: the editor's request deadline is set just above ${max}s. Lower the CMS ` +
95
+ `Lambda's timeout to ${max}s or less. A shorter origin timeout than the Lambda's ` +
96
+ `would 504 at the edge on requests that actually succeed.`);
86
97
  }
87
98
  }
88
99
  /**
@@ -68,3 +68,9 @@ export declare function workerContractShortfall(env: Readonly<Record<string, str
68
68
  * it, so the alarm misfires if the worker's text drifts from this one.
69
69
  */
70
70
  export declare const WORKER_SYNC_LOG_PHRASE = "Syncing git...";
71
+ /**
72
+ * The text of the line `syncGit()` logs when a git-sync cycle has run to its end. The
73
+ * sync-failing alarm alarms when cycles start ({@link WORKER_SYNC_LOG_PHRASE}) and none logs
74
+ * this, so it misfires if the worker's text drifts from this one.
75
+ */
76
+ export declare const WORKER_SYNC_DONE_LOG_PHRASE = "Git sync complete";
@@ -109,3 +109,9 @@ export function workerContractShortfall(env) {
109
109
  * it, so the alarm misfires if the worker's text drifts from this one.
110
110
  */
111
111
  export const WORKER_SYNC_LOG_PHRASE = 'Syncing git...';
112
+ /**
113
+ * The text of the line `syncGit()` logs when a git-sync cycle has run to its end. The
114
+ * sync-failing alarm alarms when cycles start ({@link WORKER_SYNC_LOG_PHRASE}) and none logs
115
+ * this, so it misfires if the worker's text drifts from this one.
116
+ */
117
+ export const WORKER_SYNC_DONE_LOG_PHRASE = 'Git sync complete';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "canopycms-cdk",
3
- "version": "0.6.0",
3
+ "version": "0.7.1",
4
4
  "description": "AWS CDK constructs and EC2 worker for CanopyCMS deployment",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -34,7 +34,7 @@
34
34
  "peerDependencies": {
35
35
  "aws-cdk-lib": "^2.260.0",
36
36
  "constructs": "^10.0.0",
37
- "canopycms": "0.6.0"
37
+ "canopycms": "0.7.1"
38
38
  },
39
39
  "peerDependenciesMeta": {
40
40
  "aws-cdk-lib": {
@@ -60,8 +60,8 @@
60
60
  "tsx": "^4.19.0",
61
61
  "typescript": "^5.6.3",
62
62
  "vitest": "^4.1.0",
63
- "canopycms": "0.6.0",
64
- "canopycms-auth-clerk": "0.6.0"
63
+ "canopycms-auth-clerk": "0.7.1",
64
+ "canopycms": "0.7.1"
65
65
  },
66
66
  "scripts": {
67
67
  "build": "rm -rf dist && tsc && node ../../scripts/add-js-extensions.mjs dist",