This repository was archived by the owner on Feb 17, 2025. It is now read-only.
feat: interoperable Cloud Assembly contract #133
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
1 task
rix0rrr
approved these changes
Jan 20, 2025
mergify
bot
deleted the
mrgrain/feat/interoperable-cloud-assembly-interface
branch
mergify bot
pushed a commit
to aws/aws-cdk
that referenced
this pull request
Jan 21, 2025
…32998) ### Reason for this change We are publishing the `cx-api` package twice: Once as a standalone package `@aws-cdk/cx-api` and once as part of the construct library under `aws-cdk-lib/cx-api`. The code is copied during the release and the same versions of the packages will have the same code. However this makes it difficult for other packages to take a type dependency on types from this package. The most common class that's used from `cx-api` is `CloudAssembly` - the result of `app.synth()`. Previously a package had to take a dependency on the very large `aws-cdk-lib` just to use a single type. It would be better if other packages could instead depend on the smaller, much more focused `@aws-cdk/cx-api` package. ### Description of changes This adds the same mechanism to `CloudAssembly` to detect cross-library compatibility, that we already use for constructs like `Stack` or `App`. In TypeScript, it's now possible for a consuming package to receive an object from either package and check at runtime if it satisfies the requirements. We cannot get around type checking with this. Instead we introduce a new type `ICloudAssembly` into the Cloud Assembly Schema package (cdklabs/cloud-assembly-schema#133). This interface only declares a single property: `directory`. Consumers can use this type to indicate where they would like to receive a `CloudAssembly`. They can then use runtime code to either confirm a provided object already satisfies the requirements or fallback to creating a new `CloudAssembly` from the directory. Because the `CloudAssembly` in `cxapi` implements the new interface, this approach will work in all jsii languages. In TypeScript it's even compatible with older version of `aws-cdk-lib`. Jsii language will only support this going forward. #### Allowed breaking changes ``` weakened:aws-cdk-lib.cloud_assembly_schema.MetadataEntry weakened:aws-cdk-lib.cx_api.MetadataEntryResult ``` This PR updates the version of `@aws-cdk/cloud-assembly-schema` to make new of the new interface. However the update also includes a change to `MetadataEntry` which was introduced in cdklabs/cloud-assembly-schema#121. That change is weakening a type, because in #31041, the CDK started emitting booleans and numbers as metadata values. But since these types weren't officially declared in the schema, jsii runtime type checking failed to load them. The fix was to officially extend the type union to include `boolean` and `number` primitive values. This is considered breaking, because when used as an output any consuming code will now need to account for the possibility of the value being a `boolean` or `number`. In static languages, the type would already have been treated as a generic Object with required runtime checks. ### Describe any new or updated permissions being added n/a ### Description of how you validated changes Unit tests. ### Checklist - [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md) ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
moelasmar
pushed a commit
to aws/aws-cdk
that referenced
this pull request
Jan 24, 2025
…32998) ### Reason for this change We are publishing the `cx-api` package twice: Once as a standalone package `@aws-cdk/cx-api` and once as part of the construct library under `aws-cdk-lib/cx-api`. The code is copied during the release and the same versions of the packages will have the same code. However this makes it difficult for other packages to take a type dependency on types from this package. The most common class that's used from `cx-api` is `CloudAssembly` - the result of `app.synth()`. Previously a package had to take a dependency on the very large `aws-cdk-lib` just to use a single type. It would be better if other packages could instead depend on the smaller, much more focused `@aws-cdk/cx-api` package. ### Description of changes This adds the same mechanism to `CloudAssembly` to detect cross-library compatibility, that we already use for constructs like `Stack` or `App`. In TypeScript, it's now possible for a consuming package to receive an object from either package and check at runtime if it satisfies the requirements. We cannot get around type checking with this. Instead we introduce a new type `ICloudAssembly` into the Cloud Assembly Schema package (cdklabs/cloud-assembly-schema#133). This interface only declares a single property: `directory`. Consumers can use this type to indicate where they would like to receive a `CloudAssembly`. They can then use runtime code to either confirm a provided object already satisfies the requirements or fallback to creating a new `CloudAssembly` from the directory. Because the `CloudAssembly` in `cxapi` implements the new interface, this approach will work in all jsii languages. In TypeScript it's even compatible with older version of `aws-cdk-lib`. Jsii language will only support this going forward. #### Allowed breaking changes ``` weakened:aws-cdk-lib.cloud_assembly_schema.MetadataEntry weakened:aws-cdk-lib.cx_api.MetadataEntryResult ``` This PR updates the version of `@aws-cdk/cloud-assembly-schema` to make new of the new interface. However the update also includes a change to `MetadataEntry` which was introduced in cdklabs/cloud-assembly-schema#121. That change is weakening a type, because in #31041, the CDK started emitting booleans and numbers as metadata values. But since these types weren't officially declared in the schema, jsii runtime type checking failed to load them. The fix was to officially extend the type union to include `boolean` and `number` primitive values. This is considered breaking, because when used as an output any consuming code will now need to account for the possibility of the value being a `boolean` or `number`. In static languages, the type would already have been treated as a generic Object with required runtime checks. ### Describe any new or updated permissions being added n/a ### Description of how you validated changes Unit tests. ### Checklist - [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md) ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license* (cherry picked from commit 94ba772)
moelasmar
pushed a commit
to aws/aws-cdk
that referenced
this pull request
Jan 24, 2025
…32998) ### Reason for this change We are publishing the `cx-api` package twice: Once as a standalone package `@aws-cdk/cx-api` and once as part of the construct library under `aws-cdk-lib/cx-api`. The code is copied during the release and the same versions of the packages will have the same code. However this makes it difficult for other packages to take a type dependency on types from this package. The most common class that's used from `cx-api` is `CloudAssembly` - the result of `app.synth()`. Previously a package had to take a dependency on the very large `aws-cdk-lib` just to use a single type. It would be better if other packages could instead depend on the smaller, much more focused `@aws-cdk/cx-api` package. ### Description of changes This adds the same mechanism to `CloudAssembly` to detect cross-library compatibility, that we already use for constructs like `Stack` or `App`. In TypeScript, it's now possible for a consuming package to receive an object from either package and check at runtime if it satisfies the requirements. We cannot get around type checking with this. Instead we introduce a new type `ICloudAssembly` into the Cloud Assembly Schema package (cdklabs/cloud-assembly-schema#133). This interface only declares a single property: `directory`. Consumers can use this type to indicate where they would like to receive a `CloudAssembly`. They can then use runtime code to either confirm a provided object already satisfies the requirements or fallback to creating a new `CloudAssembly` from the directory. Because the `CloudAssembly` in `cxapi` implements the new interface, this approach will work in all jsii languages. In TypeScript it's even compatible with older version of `aws-cdk-lib`. Jsii language will only support this going forward. #### Allowed breaking changes ``` weakened:aws-cdk-lib.cloud_assembly_schema.MetadataEntry weakened:aws-cdk-lib.cx_api.MetadataEntryResult ``` This PR updates the version of `@aws-cdk/cloud-assembly-schema` to make new of the new interface. However the update also includes a change to `MetadataEntry` which was introduced in cdklabs/cloud-assembly-schema#121. That change is weakening a type, because in #31041, the CDK started emitting booleans and numbers as metadata values. But since these types weren't officially declared in the schema, jsii runtime type checking failed to load them. The fix was to officially extend the type union to include `boolean` and `number` primitive values. This is considered breaking, because when used as an output any consuming code will now need to account for the possibility of the value being a `boolean` or `number`. In static languages, the type would already have been treated as a generic Object with required runtime checks. ### Describe any new or updated permissions being added n/a ### Description of how you validated changes Unit tests. ### Checklist - [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md) ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license* (cherry picked from commit 94ba772)
moelasmar
pushed a commit
to aws/aws-cdk
that referenced
this pull request
Jan 24, 2025
…32998) ### Reason for this change We are publishing the `cx-api` package twice: Once as a standalone package `@aws-cdk/cx-api` and once as part of the construct library under `aws-cdk-lib/cx-api`. The code is copied during the release and the same versions of the packages will have the same code. However this makes it difficult for other packages to take a type dependency on types from this package. The most common class that's used from `cx-api` is `CloudAssembly` - the result of `app.synth()`. Previously a package had to take a dependency on the very large `aws-cdk-lib` just to use a single type. It would be better if other packages could instead depend on the smaller, much more focused `@aws-cdk/cx-api` package. ### Description of changes This adds the same mechanism to `CloudAssembly` to detect cross-library compatibility, that we already use for constructs like `Stack` or `App`. In TypeScript, it's now possible for a consuming package to receive an object from either package and check at runtime if it satisfies the requirements. We cannot get around type checking with this. Instead we introduce a new type `ICloudAssembly` into the Cloud Assembly Schema package (cdklabs/cloud-assembly-schema#133). This interface only declares a single property: `directory`. Consumers can use this type to indicate where they would like to receive a `CloudAssembly`. They can then use runtime code to either confirm a provided object already satisfies the requirements or fallback to creating a new `CloudAssembly` from the directory. Because the `CloudAssembly` in `cxapi` implements the new interface, this approach will work in all jsii languages. In TypeScript it's even compatible with older version of `aws-cdk-lib`. Jsii language will only support this going forward. #### Allowed breaking changes ``` weakened:aws-cdk-lib.cloud_assembly_schema.MetadataEntry weakened:aws-cdk-lib.cx_api.MetadataEntryResult ``` This PR updates the version of `@aws-cdk/cloud-assembly-schema` to make new of the new interface. However the update also includes a change to `MetadataEntry` which was introduced in cdklabs/cloud-assembly-schema#121. That change is weakening a type, because in #31041, the CDK started emitting booleans and numbers as metadata values. But since these types weren't officially declared in the schema, jsii runtime type checking failed to load them. The fix was to officially extend the type union to include `boolean` and `number` primitive values. This is considered breaking, because when used as an output any consuming code will now need to account for the possibility of the value being a `boolean` or `number`. In static languages, the type would already have been treated as a generic Object with required runtime checks. ### Describe any new or updated permissions being added n/a ### Description of how you validated changes Unit tests. ### Checklist - [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md) ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license* (cherry picked from commit 94ba772)
moelasmar
pushed a commit
to aws/aws-cdk
that referenced
this pull request
Jan 24, 2025
…32998) ### Reason for this change We are publishing the `cx-api` package twice: Once as a standalone package `@aws-cdk/cx-api` and once as part of the construct library under `aws-cdk-lib/cx-api`. The code is copied during the release and the same versions of the packages will have the same code. However this makes it difficult for other packages to take a type dependency on types from this package. The most common class that's used from `cx-api` is `CloudAssembly` - the result of `app.synth()`. Previously a package had to take a dependency on the very large `aws-cdk-lib` just to use a single type. It would be better if other packages could instead depend on the smaller, much more focused `@aws-cdk/cx-api` package. ### Description of changes This adds the same mechanism to `CloudAssembly` to detect cross-library compatibility, that we already use for constructs like `Stack` or `App`. In TypeScript, it's now possible for a consuming package to receive an object from either package and check at runtime if it satisfies the requirements. We cannot get around type checking with this. Instead we introduce a new type `ICloudAssembly` into the Cloud Assembly Schema package (cdklabs/cloud-assembly-schema#133). This interface only declares a single property: `directory`. Consumers can use this type to indicate where they would like to receive a `CloudAssembly`. They can then use runtime code to either confirm a provided object already satisfies the requirements or fallback to creating a new `CloudAssembly` from the directory. Because the `CloudAssembly` in `cxapi` implements the new interface, this approach will work in all jsii languages. In TypeScript it's even compatible with older version of `aws-cdk-lib`. Jsii language will only support this going forward. #### Allowed breaking changes ``` weakened:aws-cdk-lib.cloud_assembly_schema.MetadataEntry weakened:aws-cdk-lib.cx_api.MetadataEntryResult ``` This PR updates the version of `@aws-cdk/cloud-assembly-schema` to make new of the new interface. However the update also includes a change to `MetadataEntry` which was introduced in cdklabs/cloud-assembly-schema#121. That change is weakening a type, because in #31041, the CDK started emitting booleans and numbers as metadata values. But since these types weren't officially declared in the schema, jsii runtime type checking failed to load them. The fix was to officially extend the type union to include `boolean` and `number` primitive values. This is considered breaking, because when used as an output any consuming code will now need to account for the possibility of the value being a `boolean` or `number`. In static languages, the type would already have been treated as a generic Object with required runtime checks. ### Describe any new or updated permissions being added n/a ### Description of how you validated changes Unit tests. ### Checklist - [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md) ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license* (cherry picked from commit 94ba772)
moelasmar
pushed a commit
to aws/aws-cdk
that referenced
this pull request
Jan 24, 2025
…32998) ### Reason for this change We are publishing the `cx-api` package twice: Once as a standalone package `@aws-cdk/cx-api` and once as part of the construct library under `aws-cdk-lib/cx-api`. The code is copied during the release and the same versions of the packages will have the same code. However this makes it difficult for other packages to take a type dependency on types from this package. The most common class that's used from `cx-api` is `CloudAssembly` - the result of `app.synth()`. Previously a package had to take a dependency on the very large `aws-cdk-lib` just to use a single type. It would be better if other packages could instead depend on the smaller, much more focused `@aws-cdk/cx-api` package. ### Description of changes This adds the same mechanism to `CloudAssembly` to detect cross-library compatibility, that we already use for constructs like `Stack` or `App`. In TypeScript, it's now possible for a consuming package to receive an object from either package and check at runtime if it satisfies the requirements. We cannot get around type checking with this. Instead we introduce a new type `ICloudAssembly` into the Cloud Assembly Schema package (cdklabs/cloud-assembly-schema#133). This interface only declares a single property: `directory`. Consumers can use this type to indicate where they would like to receive a `CloudAssembly`. They can then use runtime code to either confirm a provided object already satisfies the requirements or fallback to creating a new `CloudAssembly` from the directory. Because the `CloudAssembly` in `cxapi` implements the new interface, this approach will work in all jsii languages. In TypeScript it's even compatible with older version of `aws-cdk-lib`. Jsii language will only support this going forward. #### Allowed breaking changes ``` weakened:aws-cdk-lib.cloud_assembly_schema.MetadataEntry weakened:aws-cdk-lib.cx_api.MetadataEntryResult ``` This PR updates the version of `@aws-cdk/cloud-assembly-schema` to make new of the new interface. However the update also includes a change to `MetadataEntry` which was introduced in cdklabs/cloud-assembly-schema#121. That change is weakening a type, because in #31041, the CDK started emitting booleans and numbers as metadata values. But since these types weren't officially declared in the schema, jsii runtime type checking failed to load them. The fix was to officially extend the type union to include `boolean` and `number` primitive values. This is considered breaking, because when used as an output any consuming code will now need to account for the possibility of the value being a `boolean` or `number`. In static languages, the type would already have been treated as a generic Object with required runtime checks. ### Describe any new or updated permissions being added n/a ### Description of how you validated changes Unit tests. ### Checklist - [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md) ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license* (cherry picked from commit 94ba772)
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Issue
Relates to aws/aws-cdk#32998
Reason for this change
We are publishing the
cx-apipackage twice: Once as a standalone package@aws-cdk/cx-apiand once as part of the construct library underaws-cdk-lib/cx-api. The code is copied during the release and the same versions of the packages will have the same code.However this makes it difficult for other packages to take a type dependency on types from this package. The most common class that's used from
cx-apiisCloudAssembly- the result ofapp.synth(). Previously a package had to take a dependency on the very largeaws-cdk-libjust to use a single type. It would be better if other packages could instead depend on the smaller, much more focused@aws-cdk/cx-apipackage.Description of changes
In aws/aws-cdk#32998 we are adding a mechanism to detect cross-library compatibility of the
CloudAssemblyclass. However, that alone doesn't help us with type checking. Instead we introduce a new typeICloudAssemblyinto the Cloud Assembly Schema. This interface only declares a single property:directory. Consumers can use this type to indicate where they would like to receive aCloudAssembly. They can then use runtime code to either confirm a provided object already satisfies the requirements or fallback to creating a newCloudAssemblyfrom the directory.