chore(mixins-preview): implement Mixins RFC #36013

mrgrain · 2025-11-11T16:50:13Z

Reason for this change

This PR implements the foundational infrastructure for the CDK Mixins framework, introducing a composable abstraction system for applying functionality to CDK constructs. It is based on the current state of the RFC.

While the RFC is not yet approved and finalized, this PR aims to implement it including all its flaws so we can move forward with other implementing depending on this. We will update the package as the RFC evolves.

Description of changes

Core Framework:

Implemented IMixin interface and Mixin base class for creating composable abstractions
Added Mixins.of() API for applying mixins to constructs with apply() and mustApply() methods
Created ConstructSelector for filtering constructs by type, ID pattern, or CloudFormation resource type
Added comprehensive error handling and validation support
Added .with() augmentation to constructs for fluent mixin application

Testing:

Comprehensive unit tests for core framework, selectors, and all built-in mixins
Integration tests demonstrating real-world usage patterns
Property manipulation utility tests including edge cases

Documentation:

Updated README with usage examples, API reference, and best practices
Added Rosetta fixture for documentation code examples

Description of how you validated changes

All new code is covered by unit tests
Integration tests validate end-to-end functionality
Rosetta fixture ensures documentation examples are valid

Checklist

My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

### Reason for this change Refactor repeated pattern of anonymous classes that throw `UnscopedValidationError` when accessing `node` or `env` properties. This pattern exists because certain legacy CDK APIs like `ManagedPolicy.fromAwsManagedPolicyName()` and CloudFront's `fromManagedCachePolicy()` return construct-like objects without requiring a `scope` parameter. These APIs predate modern CDK patterns where all constructs require a scope. They cannot be changed without breaking existing customer code, so they return "detached" constructs that throw errors when used in APIs that require a proper construct tree context. But we also sometimes add new features to resource interfaces like `IManagedPolicy`. When this happens, we have to update this fake implementation in a number of places. It also prevents us (and users) from providing augmentations for the `IConstruct` interface like proposed in #36013. With this change, we have reduced the number of places to update to one. It's now also possible to augment `IConstruct`. ### Description of changes - Created `DetachedConstruct` base class in `core/lib/private/detached-construct.ts` that encapsulates the pattern of throwing `UnscopedValidationError` when accessing `node` or `env` - Refactored CloudFront policy classes (`CachePolicy`, `OriginRequestPolicy`, `ResponseHeadersPolicy`) to extend `DetachedConstruct` instead of implementing the pattern inline - Refactored `ManagedPolicy.fromAwsManagedPolicyName()` to use `DetachedConstruct` - Refactored `ElasticBeanstalkDeployAction` to use `DetachedConstruct` for managed policy reference - Added unit tests for `DetachedConstruct` to verify error throwing behavior This change reduces code duplication and makes the pattern more maintainable. The `DetachedConstruct` class is marked as internal and documented to discourage use in new APIs. ### Describe any new or updated permissions being added No new or updated permissions. ### Description of how you validated changes - Added unit tests in `core/test/private/detached-construct.test.ts` that verify `UnscopedValidationError` is thrown when accessing `node` and `env` properties - Existing tests continue to pass, ensuring no behavioral changes ### 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*

aws-cdk-automation · 2025-11-12T09:15:10Z

➡️ PR build request submitted to test-main-pipeline ⬅️

A maintainer must now check the pipeline and add the pr-linter/cli-integ-tested label once the pipeline succeeds.

rix0rrr · 2025-11-13T12:16:03Z

packages/@aws-cdk/mixins-preview/lib/with.ts

+import type { IMixin } from './core';
+import { Mixins, ConstructSelector } from './core';
+
+declare module 'constructs' {


Does this work for consumers of this library?

It does work if they import the submodule as described in the readme.

packages/@aws-cdk/mixins-preview/lib/util/property-mixins.ts

packages/@aws-cdk/mixins-preview/lib/services/aws-s3/bucket.ts

packages/@aws-cdk/mixins-preview/lib/core/selectors.ts

rix0rrr · 2025-11-13T12:27:42Z

packages/@aws-cdk/mixins-preview/lib/core/mixins.ts

+  /**
+   * Validates the construct before applying the mixin.
+   */
+  validate?(construct: IConstruct): string[];


Is this not failing the jsii build?

I also still think validate() doesn't need to be here.

why should it be failing the build (it doesn't)?

That might be an oversight. There is approximately 0% chance this gets translated appropriately to Java.

Looks like jsii is silently ignoring it 🙈

{ "abstract": true, "docs": { "stability": "experimental", "summary": "Validates the construct before applying the mixin." }, "locationInModule": { "filename": "lib/core/mixins.ts", "line": 33 }, "name": "validate", "parameters": [ { "name": "construct", "type": { "fqn": "constructs.IConstruct" } } ], "returns": { "type": { "collection": { "elementtype": { "primitive": "string" }, "kind": "array" } } } }

packages/@aws-cdk/mixins-preview/lib/core/mixins.ts

packages/@aws-cdk/mixins-preview/lib/core/applicator.ts

mergify · 2025-11-14T12:48:01Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

mergify · 2025-11-14T12:58:33Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

mergify · 2025-11-14T13:00:55Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

mergify · 2025-11-14T14:01:27Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

github-actions · 2025-11-14T14:01:42Z

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.

github-actions bot added the p2 label Nov 11, 2025

aws-cdk-automation requested a review from a team November 11, 2025 16:50

mergify bot added the contribution/core This is a PR that came from AWS. label Nov 11, 2025

mrgrain force-pushed the mrgrain/chore/mixins-pt-1 branch from 23aad97 to 83cc751 Compare November 11, 2025 18:21

aws-cdk-automation added the pr/needs-further-review PR requires additional review from our team specialists due to the scope or complexity of changes. label Nov 11, 2025

mrgrain force-pushed the mrgrain/chore/mixins-pt-1 branch from 83cc751 to c7ec67c Compare November 11, 2025 19:10

mrgrain requested a review from a team as a code owner November 11, 2025 19:10

mrgrain mentioned this pull request Nov 11, 2025

chore(core): introduce DetachedConstruct base class #36015

Merged

1 task

mrgrain force-pushed the mrgrain/chore/mixins-pt-1 branch from c7ec67c to bdd296e Compare November 11, 2025 19:24

aws-cdk-automation removed the pr/needs-further-review PR requires additional review from our team specialists due to the scope or complexity of changes. label Nov 11, 2025

mrgrain force-pushed the mrgrain/chore/mixins-pt-1 branch from bdd296e to 22cf314 Compare November 11, 2025 20:03

mrgrain added pr/do-not-merge This PR should not be merged at this time. pr/request-cli-integ-tests Request CLI integ tests to be run. You will need to review the code and approve the deployment. labels Nov 11, 2025

mrgrain requested a deployment to test-pipeline November 11, 2025 20:04 — with GitHub Actions Waiting

mrgrain temporarily deployed to test-pipeline November 11, 2025 23:12 — with GitHub Actions Inactive

mrgrain force-pushed the mrgrain/chore/mixins-pt-1 branch from 3a93231 to 94e15f9 Compare November 12, 2025 09:12

mrgrain temporarily deployed to test-pipeline November 12, 2025 09:13 — with GitHub Actions Inactive

mrgrain force-pushed the mrgrain/chore/mixins-pt-1 branch from 94e15f9 to 56a98db Compare November 12, 2025 17:20

mrgrain requested a deployment to test-pipeline November 12, 2025 17:21 — with GitHub Actions Waiting

mrgrain requested a deployment to test-pipeline November 12, 2025 17:29 — with GitHub Actions Waiting

mrgrain force-pushed the mrgrain/chore/mixins-pt-1 branch from 56a98db to 7861e58 Compare November 13, 2025 11:24

rix0rrr reviewed Nov 13, 2025

View reviewed changes

aws-cdk-automation added the pr/needs-maintainer-review This PR needs a review from a Core Team Member label Nov 13, 2025

chore(mixins-preview): implement Mixins RFC

c1a9604

mrgrain force-pushed the mrgrain/chore/mixins-pt-1 branch from 7861e58 to 1c327df Compare November 14, 2025 11:17

mrgrain force-pushed the mrgrain/chore/mixins-pt-1 branch from 1c327df to 95339b8 Compare November 14, 2025 11:26

pr feedback

a903824

mrgrain force-pushed the mrgrain/chore/mixins-pt-1 branch from 95339b8 to a903824 Compare November 14, 2025 12:13

rix0rrr approved these changes Nov 14, 2025

View reviewed changes

mrgrain removed the pr-linter/cli-integ-tested Assert that any CLI changes have been integ tested label Nov 14, 2025

mrgrain mentioned this pull request Nov 14, 2025

chore(mixins-preview): add L1 property mixins #36062

Open

1 task

aws-cdk-automation removed the pr/needs-maintainer-review This PR needs a review from a Core Team Member label Nov 14, 2025

Merge branch 'main' into mrgrain/chore/mixins-pt-1

76fb10d

mergify bot merged commit 56f22aa into main Nov 14, 2025
18 of 19 checks passed

mergify bot deleted the mrgrain/chore/mixins-pt-1 branch November 14, 2025 14:01

github-actions bot locked as resolved and limited conversation to collaborators Nov 14, 2025

chore(mixins-preview): implement Mixins RFC #36013

chore(mixins-preview): implement Mixins RFC #36013

Conversation

mrgrain commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reason for this change

Description of changes

Description of how you validated changes

Checklist

Uh oh!

aws-cdk-automation commented Nov 12, 2025

Uh oh!

rix0rrr Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

mrgrain Nov 14, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rix0rrr Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

mrgrain Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rix0rrr Nov 14, 2025

Choose a reason for hiding this comment

Uh oh!

mrgrain Nov 14, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mergify bot commented Nov 14, 2025

Uh oh!

mergify bot commented Nov 14, 2025

Uh oh!

mergify bot commented Nov 14, 2025

Uh oh!

mergify bot commented Nov 14, 2025

Uh oh!

Uh oh!

github-actions bot commented Nov 14, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mrgrain commented Nov 11, 2025 •

edited

Loading

mrgrain Nov 14, 2025 •

edited

Loading