Skip to content

Commit a3160a7

Browse files
mrgrainiliapologithub-actions
authored
feat(toolkit-lib): additional messages contain structured data (#193)
Adds many more explicit codes and message payload to messages that previously were default messages. Within `toolkit-lib` replace all previous message helpers with the new Message Maker pattern: `CODES.CDK_CAT_I1234.msg("my message")`. --- By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license --------- Signed-off-by: github-actions <[email protected]> Co-authored-by: Eli Polonsky <[email protected]> Co-authored-by: github-actions <[email protected]>
1 parent b242c23 commit a3160a7

File tree

23 files changed

+753
-496
lines changed

23 files changed

+753
-496
lines changed

‎.projenrc.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -1249,7 +1249,7 @@ toolkitLib.package.addField('exports', {
12491249
'./package.json': './package.json',
12501250
});
12511251

1252-
toolkitLib.postCompileTask.exec('ts-node scripts/gen-code-registry.ts');
1252+
toolkitLib.postCompileTask.exec('ts-node --prefer-ts-exts scripts/gen-code-registry.ts');
12531253
toolkitLib.postCompileTask.exec('node build-tools/bundle.mjs');
12541254
// Smoke test built JS files
12551255
toolkitLib.postCompileTask.exec('node ./lib/index.js >/dev/null 2>/dev/null </dev/null');

‎packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/private/message-maker.ts

+67-16
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { IoMessageCode, IoMessageLevel } from '../io-message';
2-
import { ActionLessMessage } from './action-aware';
2+
import { ActionLessMessage, ActionLessRequest } from './action-aware';
33

44
/**
55
* Information for each IO Message Code.
@@ -8,12 +8,12 @@ interface CodeInfo {
88
/**
99
* The message code.
1010
*/
11-
code: IoMessageCode;
11+
readonly code: IoMessageCode;
1212

1313
/**
1414
* A brief description of the meaning of this IO Message.
1515
*/
16-
description: string;
16+
readonly description: string;
1717

1818
/**
1919
* The name of the payload interface, if applicable.
@@ -24,7 +24,7 @@ interface CodeInfo {
2424
* The interface _must_ be exposed directly from toolkit-lib, so that it will
2525
* have a documentation page generated (that can be linked to).
2626
*/
27-
interface?: string;
27+
readonly interface?: string;
2828
}
2929

3030
/**
@@ -34,7 +34,7 @@ interface MessageInfo extends CodeInfo {
3434
/**
3535
* The message level
3636
*/
37-
level: IoMessageLevel;
37+
readonly level: IoMessageLevel;
3838
}
3939

4040
/**
@@ -50,28 +50,79 @@ export interface IoMessageMaker<T> extends MessageInfo {
5050
/**
5151
* Produce an IoMessageMaker for the provided level and code info.
5252
*/
53-
function generic<T = never>(level: IoMessageLevel, details: CodeInfo): IoMessageMaker<T> {
54-
const msg = (message: string, data: T) => ({
53+
function message<T = never>(level: IoMessageLevel, details: CodeInfo): IoMessageMaker<T> {
54+
const maker = (text: string, data: T) => ({
5555
time: new Date(),
5656
level,
5757
code: details.code,
58-
message: message,
59-
data: data,
58+
message: text,
59+
data,
6060
} as ActionLessMessage<T>);
6161

6262
return {
6363
...details,
6464
level,
65-
msg: msg as any,
65+
msg: maker as any,
6666
};
6767
}
6868

69+
/**
70+
* A type that is impossible for a user to replicate
71+
* This is used to ensure that results always have a proper type generic declared.
72+
*/
73+
declare const privateKey: unique symbol;
74+
export type ImpossibleType = {
75+
readonly [privateKey]: typeof privateKey;
76+
};
77+
6978
// Create `IoMessageMaker`s for a given level and type check that calls with payload are using the correct interface
7079
type CodeInfoMaybeInterface<T> = [T] extends [never] ? Omit<CodeInfo, 'interface'> : Required<CodeInfo>;
7180

72-
export const trace = <T = never>(details: CodeInfoMaybeInterface<T>) => generic<T>('trace', details);
73-
export const debug = <T = never>(details: CodeInfoMaybeInterface<T>) => generic<T>('debug', details);
74-
export const info = <T = never>(details: CodeInfoMaybeInterface<T>) => generic<T>('info', details);
75-
export const warn = <T = never>(details: CodeInfoMaybeInterface<T>) => generic<T>('warn', details);
76-
export const error = <T = never>(details: CodeInfoMaybeInterface<T>) => generic<T>('error', details);
77-
export const result = <T extends object>(details: Required<CodeInfo>) => generic<T extends object ? T : never>('result', details);
81+
export const trace = <T = never>(details: CodeInfoMaybeInterface<T>) => message<T>('trace', details);
82+
export const debug = <T = never>(details: CodeInfoMaybeInterface<T>) => message<T>('debug', details);
83+
export const info = <T = never>(details: CodeInfoMaybeInterface<T>) => message<T>('info', details);
84+
export const warn = <T = never>(details: CodeInfoMaybeInterface<T>) => message<T>('warn', details);
85+
export const error = <T = never>(details: CodeInfoMaybeInterface<T>) => message<T>('error', details);
86+
export const result = <T extends object = ImpossibleType>(details: Required<CodeInfo>) => message<T extends object ? T : never>('result', details);
87+
88+
interface RequestInfo<U> extends CodeInfo {
89+
readonly defaultResponse: U;
90+
}
91+
92+
/**
93+
* An interface that can produce requests for a specific code.
94+
*/
95+
export interface IoRequestMaker<T, U> extends MessageInfo {
96+
/**
97+
* Create a message for this code, with or without payload.
98+
*/
99+
req: [T] extends [never] ? (message: string) => ActionLessMessage<never> : (message: string, data: T) => ActionLessRequest<T, U>;
100+
}
101+
102+
/**
103+
* Produce an IoRequestMaker for the provided level and request info.
104+
*/
105+
function request<T = never, U = ImpossibleType>(level: IoMessageLevel, details: RequestInfo<U>): IoRequestMaker<T, U> {
106+
const maker = (text: string, data: T) => ({
107+
time: new Date(),
108+
level,
109+
code: details.code,
110+
message: text,
111+
data,
112+
defaultResponse: details.defaultResponse,
113+
} as ActionLessRequest<T, U>);
114+
115+
return {
116+
...details,
117+
level,
118+
req: maker as any,
119+
};
120+
}
121+
122+
/**
123+
* A request that is a simple yes/no question, with the expectation that 'yes' is the default.
124+
*/
125+
export const confirm = <T extends object = ImpossibleType>(details: Required<Omit<RequestInfo<boolean>, 'defaultResponse'>>) => request<T, boolean>('info', {
126+
...details,
127+
defaultResponse: true,
128+
});

‎packages/@aws-cdk/toolkit-lib/.projen/tasks.json

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/@aws-cdk/toolkit-lib/CODE_REGISTRY.md

+34-8
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22

33
| Code | Description | Level | Data Interface |
44
|------|-------------|-------|----------------|
5+
| CDK_TOOLKIT_I0000 | Default info messages emitted from the Toolkit | info | n/a |
6+
| CDK_TOOLKIT_I0000 | Default debug messages emitted from the Toolkit | debug | n/a |
7+
| CDK_TOOLKIT_W0000 | Default warning messages emitted from the Toolkit | warn | n/a |
58
| CDK_TOOLKIT_I1000 | Provides synthesis times. | info | [Duration](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/Duration.html) |
69
| CDK_TOOLKIT_I1901 | Provides stack data | result | [StackAndAssemblyData](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/StackAndAssemblyData.html) |
710
| CDK_TOOLKIT_I1902 | Successfully deployed stacks | result | [AssemblyData](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/AssemblyData.html) |
@@ -10,29 +13,52 @@
1013
| CDK_TOOLKIT_I5000 | Provides deployment times | info | [Duration](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/Duration.html) |
1114
| CDK_TOOLKIT_I5001 | Provides total time in deploy action, including synth and rollback | info | [Duration](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/Duration.html) |
1215
| CDK_TOOLKIT_I5002 | Provides time for resource migration | info | n/a |
16+
| CDK_TOOLKIT_W5021 | Empty non-existent stack, deployment is skipped | warn | n/a |
17+
| CDK_TOOLKIT_W5022 | Empty existing stack, stack will be destroyed | warn | n/a |
1318
| CDK_TOOLKIT_I5031 | Informs about any log groups that are traced as part of the deployment | info | n/a |
14-
| CDK_TOOLKIT_I5050 | Confirm rollback during deployment | info | n/a |
15-
| CDK_TOOLKIT_I5060 | Confirm deploy security sensitive changes | info | n/a |
19+
| CDK_TOOLKIT_I5050 | Confirm rollback during deployment | info | [ConfirmationRequest](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/ConfirmationRequest.html) |
20+
| CDK_TOOLKIT_I5060 | Confirm deploy security sensitive changes | info | [ConfirmationRequest](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/ConfirmationRequest.html) |
21+
| CDK_TOOLKIT_I5100 | Stack deploy progress | info | [StackDeployProgress](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/StackDeployProgress.html) |
22+
| CDK_TOOLKIT_I5310 | The computed settings used for file watching | debug | [WatchSettings](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/WatchSettings.html) |
23+
| CDK_TOOLKIT_I5311 | File watching started | info | [FileWatchEvent](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/FileWatchEvent.html) |
24+
| CDK_TOOLKIT_I5312 | File event detected, starting deployment | info | [FileWatchEvent](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/FileWatchEvent.html) |
25+
| CDK_TOOLKIT_I5313 | File event detected during active deployment, changes are queued | info | [FileWatchEvent](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/FileWatchEvent.html) |
26+
| CDK_TOOLKIT_I5314 | Initial watch deployment started | info | n/a |
27+
| CDK_TOOLKIT_I5315 | Queued watch deployment started | info | n/a |
1628
| CDK_TOOLKIT_I5501 | Stack Monitoring: Start monitoring of a single stack | info | [StackMonitoringControlEvent](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/StackMonitoringControlEvent.html) |
1729
| CDK_TOOLKIT_I5502 | Stack Monitoring: Activity event for a single stack | info | [StackActivity](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/StackActivity.html) |
1830
| CDK_TOOLKIT_I5503 | Stack Monitoring: Finished monitoring of a single stack | info | [StackMonitoringControlEvent](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/StackMonitoringControlEvent.html) |
1931
| CDK_TOOLKIT_I5900 | Deployment results on success | result | [SuccessfulDeployStackResult](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/SuccessfulDeployStackResult.html) |
32+
| CDK_TOOLKIT_I5901 | Generic deployment success messages | info | n/a |
33+
| CDK_TOOLKIT_W5400 | Hotswap disclosure message | warn | n/a |
2034
| CDK_TOOLKIT_E5001 | No stacks found | error | n/a |
2135
| CDK_TOOLKIT_E5500 | Stack Monitoring error | error | [ErrorPayload](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/ErrorPayload.html) |
2236
| CDK_TOOLKIT_I6000 | Provides rollback times | info | [Duration](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/Duration.html) |
37+
| CDK_TOOLKIT_I6100 | Stack rollback progress | info | [StackRollbackProgress](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/StackRollbackProgress.html) |
2338
| CDK_TOOLKIT_E6001 | No stacks found | error | n/a |
24-
| CDK_TOOLKIT_E6900 | Rollback failed | error | n/a |
39+
| CDK_TOOLKIT_E6900 | Rollback failed | error | [ErrorPayload](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/ErrorPayload.html) |
2540
| CDK_TOOLKIT_I7000 | Provides destroy times | info | [Duration](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/Duration.html) |
26-
| CDK_TOOLKIT_I7010 | Confirm destroy stacks | info | n/a |
41+
| CDK_TOOLKIT_I7010 | Confirm destroy stacks | info | [ConfirmationRequest](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/ConfirmationRequest.html) |
42+
| CDK_TOOLKIT_I7100 | Stack destroy progress | info | [StackDestroyProgress](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/StackDestroyProgress.html) |
43+
| CDK_TOOLKIT_I7900 | Stack deletion succeeded | result | [cxapi.CloudFormationStackArtifact](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/cxapi.CloudFormationStackArtifact.html) |
2744
| CDK_TOOLKIT_E7010 | Action was aborted due to negative confirmation of request | error | n/a |
28-
| CDK_TOOLKIT_E7900 | Stack deletion failed | error | n/a |
45+
| CDK_TOOLKIT_E7900 | Stack deletion failed | error | [ErrorPayload](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/ErrorPayload.html) |
2946
| CDK_TOOLKIT_I9000 | Provides bootstrap times | info | [Duration](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/Duration.html) |
30-
| CDK_TOOLKIT_I9900 | Bootstrap results on success | info | n/a |
31-
| CDK_TOOLKIT_E9900 | Bootstrap failed | error | n/a |
47+
| CDK_TOOLKIT_I9100 | Bootstrap progress | info | [BootstrapEnvironmentProgress](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/BootstrapEnvironmentProgress.html) |
48+
| CDK_TOOLKIT_I9900 | Bootstrap results on success | result | [cxapi.Environment](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/cxapi.Environment.html) |
49+
| CDK_TOOLKIT_E9900 | Bootstrap failed | error | [ErrorPayload](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/ErrorPayload.html) |
50+
| CDK_ASSEMBLY_I0010 | Generic environment preparation debug messages | debug | n/a |
51+
| CDK_ASSEMBLY_W0010 | Emitted if the found framework version does not support context overflow | warn | n/a |
3252
| CDK_ASSEMBLY_I0042 | Writing updated context | debug | [UpdatedContext](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/UpdatedContext.html) |
33-
| CDK_ASSEMBLY_I0241 | Fetching missing context | debug | [MissingContext](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/MissingContext.html) |
53+
| CDK_ASSEMBLY_I0240 | Context lookup was stopped as no further progress was made. | debug | [MissingContext](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/MissingContext.html) |
54+
| CDK_ASSEMBLY_I0241 | Fetching missing context. This is an iterative message that may appear multiple times with different missing keys. | debug | [MissingContext](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/MissingContext.html) |
3455
| CDK_ASSEMBLY_I1000 | Cloud assembly output starts | debug | n/a |
3556
| CDK_ASSEMBLY_I1001 | Output lines emitted by the cloud assembly to stdout | info | n/a |
3657
| CDK_ASSEMBLY_E1002 | Output lines emitted by the cloud assembly to stderr | error | n/a |
3758
| CDK_ASSEMBLY_I1003 | Cloud assembly output finished | info | n/a |
3859
| CDK_ASSEMBLY_E1111 | Incompatible CDK CLI version. Upgrade needed. | error | [ErrorPayload](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/ErrorPayload.html) |
60+
| CDK_ASSEMBLY_I0150 | Indicates the use of a pre-synthesized cloud assembly directory | debug | n/a |
61+
| CDK_ASSEMBLY_I9999 | Annotations emitted by the cloud assembly | info | [cxapi.SynthesisMessage](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/cxapi.SynthesisMessage.html) |
62+
| CDK_ASSEMBLY_W9999 | Warnings emitted by the cloud assembly | warn | [cxapi.SynthesisMessage](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/cxapi.SynthesisMessage.html) |
63+
| CDK_ASSEMBLY_E9999 | Errors emitted by the cloud assembly | error | [cxapi.SynthesisMessage](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/cxapi.SynthesisMessage.html) |
64+
| CDK_SDK_I0100 | An SDK trace. SDK traces are emitted as traces to the IoHost, but contain the original SDK logging level. | trace | [SdkTrace](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/SdkTrace.html) |

‎packages/@aws-cdk/toolkit-lib/lib/actions/bootstrap/index.ts

+17
Original file line numberDiff line numberDiff line change
@@ -227,3 +227,20 @@ export class BootstrapSource {
227227
};
228228
}
229229
}
230+
231+
export interface BootstrapEnvironmentProgress {
232+
/**
233+
* The total number of environments being deployed
234+
*/
235+
readonly total: number;
236+
/**
237+
* The count of the environment currently bootstrapped
238+
*
239+
* This is counting value, not an identifier.
240+
*/
241+
readonly current: number;
242+
/**
243+
* The environment that's currently being bootstrapped
244+
*/
245+
readonly environment: cxapi.Environment;
246+
}

‎packages/@aws-cdk/toolkit-lib/lib/actions/deploy/index.ts

+18
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { CloudFormationStackArtifact } from '@aws-cdk/cx-api';
12
import type { BaseDeployOptions } from './private/deploy-options';
23
import type { Tag } from '../../api/aws-cdk';
34

@@ -210,3 +211,20 @@ export interface HotswapProperties {
210211
*/
211212
readonly ecs: EcsHotswapProperties;
212213
}
214+
215+
export interface StackDeployProgress {
216+
/**
217+
* The total number of stacks being deployed
218+
*/
219+
readonly total: number;
220+
/**
221+
* The count of the stack currently attempted to be deployed
222+
*
223+
* This is counting value, not an identifier.
224+
*/
225+
readonly current: number;
226+
/**
227+
* The stack that's currently being deployed
228+
*/
229+
readonly stack: CloudFormationStackArtifact;
230+
}

‎packages/@aws-cdk/toolkit-lib/lib/actions/destroy/index.ts

+18
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import type { CloudFormationStackArtifact } from '@aws-cdk/cx-api';
12
import type { StackSelector } from '../../api/cloud-assembly';
23

34
export interface DestroyOptions {
@@ -18,3 +19,20 @@ export interface DestroyOptions {
1819
*/
1920
readonly ci?: boolean;
2021
}
22+
23+
export interface StackDestroyProgress {
24+
/**
25+
* The total number of stacks being destroyed
26+
*/
27+
readonly total: number;
28+
/**
29+
* The count of the stack currently attempted to be destroyed
30+
*
31+
* This is counting value, not an identifier.
32+
*/
33+
readonly current: number;
34+
/**
35+
* The stack that's currently being destroyed
36+
*/
37+
readonly stack: CloudFormationStackArtifact;
38+
}

‎packages/@aws-cdk/toolkit-lib/lib/actions/rollback/index.ts

+18
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import type { CloudFormationStackArtifact } from '@aws-cdk/cx-api';
12
import type { StackSelector } from '../../api/cloud-assembly';
23

34
export interface RollbackOptions {
@@ -42,3 +43,20 @@ export interface RollbackOptions {
4243
*/
4344
readonly validateBootstrapStackVersion?: boolean;
4445
}
46+
47+
export interface StackRollbackProgress {
48+
/**
49+
* The total number of stacks being rolled back
50+
*/
51+
readonly total: number;
52+
/**
53+
* The count of the stack currently attempted to be rolled back
54+
*
55+
* This is counting value, not an identifier.
56+
*/
57+
readonly current: number;
58+
/**
59+
* The stack that's currently being rolled back
60+
*/
61+
readonly stack: CloudFormationStackArtifact;
62+
}

‎packages/@aws-cdk/toolkit-lib/lib/actions/watch/index.ts

+29
Original file line numberDiff line numberDiff line change
@@ -38,3 +38,32 @@ export interface WatchOptions extends BaseDeployOptions {
3838
*/
3939
readonly outdir?: string;
4040
}
41+
42+
/**
43+
* The computed file watch settings
44+
*/
45+
export interface WatchSettings {
46+
/**
47+
* The directory observed for file changes
48+
*/
49+
readonly watchDir: string;
50+
/**
51+
* List of include patterns for watching files
52+
*/
53+
readonly includes: string[];
54+
/**
55+
* List of excludes patterns for watching files
56+
*/
57+
readonly excludes: string[];
58+
}
59+
60+
export interface FileWatchEvent {
61+
/**
62+
* The change to the path
63+
*/
64+
readonly event: string;
65+
/**
66+
* The path that has an observed event
67+
*/
68+
readonly path?: string;
69+
}

‎packages/@aws-cdk/toolkit-lib/lib/api/aws-cdk.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/* eslint-disable import/no-restricted-paths */
22

33
// APIs
4-
export { formatSdkLoggerContent, SdkProvider } from '../../../../aws-cdk/lib/api/aws-auth';
4+
export { SdkProvider } from '../../../../aws-cdk/lib/api/aws-auth';
55
export { Context, PROJECT_CONTEXT } from '../../../../aws-cdk/lib/api/context';
66
export { Deployments, type SuccessfulDeployStackResult } from '../../../../aws-cdk/lib/api/deployments';
77
export { Settings } from '../../../../aws-cdk/lib/api/settings';

0 commit comments

Comments
 (0)