RFC 814: CDK Mixins

[mrgrain]

This is a request for comments about CDK Mixins: Composable Abstractions for AWS Resources. See #814 for additional details.

APIs are signed off by @rix0r.

---

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

[gasolima]

I felt that it should be the other way around the .apply() will fail encountered a construct that's not supported, and another .mayApply() function that only maybe will apply.

This feeling come from as a customer expecting apply() should apply for everything and if it's not possible throw an error

[rix0rrr]

will fail encountered a construct that's not supported

I don't think that's what we're proposing. I think we're saying: "Must have applied to >=1 construct"

It might still track to have mustApply be the default...

[rix0rrr]

If the behavior is really "all selected constructs must support this", then basically every Mixins.of() call needs a selector.

Bucket already doesn't support CfnBucketPropsMixin... is that the experience we want?

[mrgrain]

This was based on some feedback. When using EncryptionAtRest mixin, I want to make sure the mixin really is applied to all constructs that I expect it to be applied to. So for this example you are right: It is pointless without selector.

[mrgrain]

3 options:

• must apply to everything
• must apply to at least one
• apply to only supported (maybe none)

[mrgrain]

mustApply only makes sense with selector.
other two are okay without selector.
fully optional case will warn if not applied

Is this just a naming question? What are the 3 cases called?

[gasolima]

What does depth-first and breadth-first mean here?

[rix0rrr]

Should we even get to specifying/picking traversal order?

(Probably we then also need preorder/postorder 😉 )

[mrgrain]

Was thinking that all() has a bunch of options for people who really care.

[gasolima]

What about resourcesOfTypes(type: string[] | Function[])?

EDIT: I feel a bit stupid now is those function coming out of the box from us to the customers or that's an example of how a customer using mixin 😅

[mrgrain]

sure we can make that work

[commiterate]

Is there a way for users to know when they can safely remove an unused mixin?

IMixin.supports() is a runtime check so compilers/transpilers won't show anything at compile time (or via LSP feedback with things like yellow squiggly underlines in your editor of choice).

It seems like the current proposed Mixins.mustApply() is the way to detect this, so mixin application being optional sounds like an intended property. I suspect this is because L2 constructs may conditionally create an L1 construct so it's not possible to guarantee a mixin will always be used.

[mrgrain]

Also planning to emit a warning for mixins that didn't apply to anything.

[commiterate]

If there's an L2 construct which internally generates multiple L1 constructs of the same type, would users have to know how the L1 construct IDs are being generated internally to select the right one?

Or would it be better for users to extend a mixin class and override the supports() function to do more complicated matching (e.g. type + value checks).

[commiterate]

For a mixin to support both L1 and L2 constructs, do we need something like:

class EnableVersioning implements IMixin {
  supports(construct: IConstruct): boolean {
    return construct instanceof s3.CfnBucket || construct instanceof s3.Bucket;
  }

  applyTo(bucket: IConstruct): IConstruct {
    if (construct instanceof s3.CfnBucket) {
      // ...
    } else if (construct instanceof s3.Bucket) {
      // ...
    }
  }
}

What if the user-defined portions of mixins instead always operate on L1 constructs and any L2 constructs are automatically decomposed to their L1 constructs?

[rix0rrr]

Hi @commiterate, L2s already contain their L1s, so this already works!

[commiterate]

Sorry I didn't make myself clear enough. I'm aware that L2s do have their L1s exposed via IConstruct.node.children so the question is whether IMixin.supports/applyTo should only receive L1s (i.e. have intermediary logic which automatically decomposes higher level constructs into L1s) or should higher level constructs be passed in and the CDK should only provide a utility decomposition function they can call within these mixin methods?

[mrgrain]

Excellent question @commiterate! Currently I have this goal split up into multiple places:

• The mixin itself should only support L1s. IMixin.supports will cause the the mixin to only be applied to the L1, even when given an L2.
• I envisioned the default selector for constructs to be one that picks the current construct if it's an L1 or picks IConstruct.node.children if that's an L1. This makes it however slightly awkward to apply mixins to L3s, so not sure.
• Constructs implementing .with() should either use the "magic selector" or simply pass their default resource

For mixin implementation, to recommendation would very strongly be to apply to L1s whenever possible.

[rix0rrr]

Are we doing variadic functions?

[mrgrain]

I think we want to. Downside is we cannot have optional props ever here.

[rix0rrr]

Hi @commiterate, L2s already contain their L1s, so this already works!

[rix0rrr]

Does this require passing a class? Because that won't work in jsii.

[mrgrain]

resourcesOfType(res: string | { readonly CFN_RESOURCE_TYPE_NAME: string })

[mrgrain]

ConstructSelector.resourcesOfType(s3.CfnBucket.CFN_RESOURCE_TYPE_NAME)

[rix0rrr]

Not sure what this does/adds over supports() ?

[mrgrain]

Use case is that I might want some buckets to be encrypted, but not others.

[mrgrain]

Potential future: ConstructSelector.css("....") a CSS style syntax

select based on tags, or construct context values

For now provides an interfaces to turn a construct tree into an ordered list of constructs

[mrgrain]

What's the point if with really?

// with on whole tree, must apply once
// fun.with(new PermissionsBoundaryMixin())
// Mixins.of(func).applyAtLeastOnce(new PermissionsBoundaryMixin());
// or
// typed, on L1 resource (same or default child) only, must apply

[mrgrain]

Could ConstructSelector be a predicate. Input probably needs to be current construct plus context (root path etc)

[rix0rrr]

Should we even get to specifying/picking traversal order?

(Probably we then also need preorder/postorder 😉 )

[rix0rrr]

We need some discussion of what they do and don't do.

Looks like:

• It can't automatically set required arguments.
• It doesn't do defaults.

Might be worth discussing up front?

[mrgrain]

CfnFunctionProps.code is a problem as well because it is required and cannot be a mixin

[rix0rrr]

Why does applyTo() return something? I was hoping to find the answer to that later on in the doc but didn't?

[mrgrain]

This was the idea:

declare const bucket: CfnBucket;
const bucketWithPolicy:  CfnBucket & HasResourcePolicy  = new TypedMixin().applyTo(bucket);

(Doesn't effect typing in with() or apply())

---

Application behavior of multiple .apply() vs. Tree and Selectors. Can we even return a changed construct?

[mrgrain]

.nowGetValue(); ?

[rix0rrr]

Something somewhere needs to discuss that L1 mixins allow desyncing the L1 state from the L2 state. We need to acknowledge that and formulate some thoughts around it.

"Don't do that if it hurts", "we will get to that later", ... something.

[rix0rrr]

Could be discussed up top where you discuss new EncryptionAtRest, that it is supported by this interface.

[rix0rrr]

If you say TypeScript you must say jsii 😉

[commiterate]

Not too sure if there was something specific in mind for this but I'll just interpret this as any breaking L2 changes.

#657 (comment) proposes such a change so I'll just use this thread (or the closest substitute we can get with GitHub PR comments) to discuss that proposal and how this RFC addresses it.

---

The linked proposal essentially wants L2 constructs to be split into 2 parts:

1. A "dumb/plain" dictionary/map of L1 constructs.
2. Wiring/currying/overlay functions which operate on L1 constructs.

L2 constructs today are fairly opaque since they complect both of these concerns without exposing much of the underlying details. The child L1 constructs aren't exactly that convenient to access (need to use IConstruct.node.children and do a bunch of if...else with instanceof to restore type information).

For 1, the general idea is possible but the implementation detail of using a TS interface (i.e. just a plain dictionary/map) isn't really possible since the CDK is heavily class based which is inherited from constructs. Passing immutable maps like in Clojure is out of the question.

For 2, it's essentially saying to extract all of the L2 wiring logic outside of the L2 construct (e.g. into functions, mixins, or whatever is decided upon).

---

If we assume something like the current class-based mixin design is accepted, that means we'd have something like this for AWS::Lambda::Function:

import { Construct, IConstruct } from "constructs";
import { IMixin, Resource } from "@aws-cdk/core";
import { aws_iam } from "@aws-cdk";

// L1. Auto-generated from Cfn resource definitions.

export class CfnFunctionProps {
  // ...
}

export class CfnFunction extends Construct {
  // Resource attributes. Same as today.
  public attr*: type;

  // Constructor. Same as today.
  constructor(scope: Construct, id: string, props: CfnFunctionProps) {
    // ...
  }
}

// L2. Manually written.

export interface FunctionExecutionRoleMixinProps {
  function: CfnFunction;
  role: aws_iam.CfnRole;
}

// I don't really know why this is a class. This can just be a function.
export class FunctionExecutionRoleMixin implements IMixin<FunctionExecutionRoleMixinProps> {
  static apply(props: FunctionExecutionRoleMixinProps): FunctionExecutionRoleMixinProps {
    // Add the Lambda-managed basic execution role policy.
    props.function.managedPolicyArns = (props.function.managedPolicyArns ?? []) + [aws_iam.ManagedPolicy.fromAwsManagedPolicyName("AWSLambdaBasicExecutionRole").managedPolicyArn];
    return props;
  }
}

export interface FunctionComponents {
  function: CfnFunction;
  role: aws_iam.CfnRole;
}

// Same as today.
export interface FunctionProps {
  // ...
}

export class Function extends Resource {
  // L1 components.
  public readonly components: FunctionComponents;

  // Existing properties for backwards compatibility.

  // Constructor.
  constructor(scope: Construct, id: String, props: FunctionProps) {
    this.components = {
      function: new CfnFunction(scope, "function", {
        // Wire in values from `props: FunctionProps`.
      }),
      role: props.role ?? new aws_iam.CfnRole(scope, "role", {
        // Default function execution role if absent.
      })
    };

    // Apply the function mixin. This is doing mutation in place, may not want this for the final design.
    FunctionExecutionRoleMixin.apply({
      function: this.components.function;
      role: this.components.role;
    });
  }

  // Existing methods for backwards compatibility.
  //
  // All of their logic (e.g. adding IAM policies for event sources) are
  // extracted into mixins. The methods just apply the mixin for users.
}

The L2 construct basically becomes a composition of L1s and default mixin applications. If users don't like the L2 construct, they're free to apply mixins directly to L1s they created or extract the L1s from the L2 and apply them.

[jiayiwang7]

Suggested change

	CDK Mixins provide a new, advanced way to add functionality to through composable abstractions.
	CDK Mixins provide a new, advanced way to add functionality through composable abstractions.

[jiayiwang7]

ah i was wondering before reading this section that - why would user ever want to use auto-generated mixins on L1s

and here ru saying that once the feature is available in service spec, u can use the CfnXpropsMixin to set up new properties dynamically here, instead of waiting for the L1 property is available in CDK version after we release like this

my understanding correct?

[jiayiwang7]

why?

[jiayiwang7]

should we also talk abt its comparision to property injections? i know they are applied in different ways and serving mostly different purpose but isnt there overlap use cases?