Skip to content

Commit

Permalink
feat: interoperable Cloud Assembly contract (#133)
Browse files Browse the repository at this point in the history
### Issue

Relates to aws/aws-cdk#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

In aws/aws-cdk#32998 we are adding a mechanism to detect cross-library compatibility of the `CloudAssembly` class. **However, that alone doesn't help us with type checking.** Instead we introduce a new type `ICloudAssembly` into 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 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.
  • Loading branch information
mrgrain authored Jan 20, 2025
1 parent bc4db6a commit 50cc543
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 0 deletions.
1 change: 1 addition & 0 deletions lib/cloud-assembly/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,4 @@ export * from './schema';
export * from './metadata-schema';
export * from './artifact-schema';
export * from './context-queries';
export * from './interfaces';
31 changes: 31 additions & 0 deletions lib/cloud-assembly/interfaces.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
// The interfaces in this file, mainly exist __here__ because this is a convenient place to put them.
// The Assembly Schema package is already a jsii package and a dependency of `aws-cdk-lib`.
// It is effectively the only place we can put shared interfaces to be used across the jsii ecosystem.
//
// Putting a shared interface in here should be a huge exception.
// It needs to be justified by great benefits it provides to the ecosystems.
// All interfaces should be as minimal as possible.

/**
* Interoperable representation of a deployable cloud application.
*
* The external and interoperable contract for a Cloud Assembly is
* a directory containing a valid Cloud Assembly.
*
* Implementations should use the directory to load the Cloud Assembly from disk.
* It is recommended that implementations validate loaded manifest files using
* the provided functionality from this package.
* Within an implementation, it may be prudent to keep (parts of) the Cloud Assembly
* in memory during execution and use an implementation-specific contract.
* However when an implementation is providing an external contract,
* this interface should be used.
*/
export interface ICloudAssembly {
/**
* The directory of the cloud assembly.
*
* This directory will be used to read the Cloud Assembly from.
* Its contents (in particular `manifest.json`) must comply with the schema defined in this package.
*/
readonly directory: string;
}

0 comments on commit 50cc543

Please sign in to comment.