aws/constructs

Define composable configuration models through code

Constructs

Software-defined persistent state

What are constructs?

Constructs are classes which define a "piece of system state". Constructs can be composed together to form higher-level building blocks which represent more complex state.

Constructs are often used to represent the desired state of cloud applications. For example, in the AWS CDK, which is used to define the desired state for AWS infrastructure using CloudFormation, the lowest-level construct represents a resource definition in a CloudFormation template. These resources are composed to represent higher-level logical units of a cloud application, etc.

Contributing

This project has adopted the Amazon Open Source Code of Conduct.

We welcome community contributions and pull requests. See our contribution guide for more information on how to report issues, set up a development environment and submit code.

License

This project is distributed under the Apache License, Version 2.0.

constructs's Issues

Constructs.isConstruct not working.

I’m having trouble getting Construct.isConstruct to work. Every construct is supposed to have the CONSTRUCT_SYM defined, but when I try to enumerate the symbols of a Stack I get:

Code:

console.log(JSON.stringify(Object.getOwnPropertySymbols(this).map( s => s.toString() ?? "undefined")))

Result:

 ["Symbol(@aws-cdk/core.DependableTrait)","Symbol(@aws-cdk/core.Stack)"]

Same thing when I do it to a construct:

let subScope = new Construct(this, "AScope") 
console.log(JSON.stringify(Object.getOwnPropertySymbols(subScope).map( s => s.toString() ?? "undefined")))

Result:

["Symbol(@aws-cdk/core.DependableTrait)"]

I was expecting to see “Symbol(constructs.Construct)” in that list. What is wrong?
I am using constructs 10.1.176 and aws-cdk-lib 2.53.0
My library (which calls Constructs.isConstruct) is using constructs 10.0.97.
As is, Constructs.isConstruct only works if I'm using the same Construct library version. Which is I think wrong.

Add Dockerfile for building and testing packages

Could we add a Dockerfile for local development for those of us that don't have or want .NET and Java installed locally?

Feature Request: Find all context

Previously, all users of constructs would have to know beforehand the keys in the context to expect, and use either tryGetContext or getContext to retrieve a specific key from context.

I would suggest that we provide a mechanism to get the full context of a node in the construct tree, with overridable defaults.

DependableTrait wasn't renamed every to Depandable in the docs

While reading/learning the code of this repository, I found that there was mentioned a 'DependableTrait' in the docs, which should obviously be renamed to 'Dependable'. I fixed that in #1087

If multiple version of construct exists in node_modules some Constructs will not be prepared

I was developing a custom cdk constructs library (NestedStacks) and after the upgrade to a version > 1.28 stacks imported from my library are not prepared. The issue was due to the fact that I was using
npm link to test locally the library, in this case a copy of the dependencies exists in the node_module under the linked path.

I found the source of the problem in the implementation of the prepare() method on Construct in this library. instanceof breaks in this case so it would be better to use a type guard function (in the previous versions of cdk.Construct was handled in this way)

Using npm pack and then install the tar.gz file is a good temporary workaround.

duplicate IValidation definition

The definition of the IValidation interface exists twice in the constructs.ts. The code is 100% identical. I think one occurence could be deleted.

I fixed this in #1091

app.getAllContext() returns empty object

I am attempting to parse some context values from the CDK app. The feature was introduced by #1751

My code snippet is:

const app = new cdk.App();
console.log(app.node.getAllContext());

Which outputs:

{}

However, when I toss a console.log() in Node.getAllContext(), it prints my context variables:

console.log(this._context)

Outputs:

...
  '@aws-cdk/aws-ec2:restrictDefaultSecurityGroup': true,
  '@aws-cdk/aws-apigateway:requestValidatorUniqueId': true,
  longTermStorageBucketArn: 'backups-690e',
  'aws:cdk:enable-path-metadata': true,
  'aws:cdk:enable-asset-metadata': true,
...

Where longTermStorageBucketArn is the context I have passed on command line:

npm run cdk -- -c longTermStorageBucketArn=backups-690e synth

---

I also tested it in the constructor of a Stack object:

console.log('all context', this.node.getAllContext())
// as well as
console.log('all context', scope.node.getAllContext())

both of which produce:

all context {}

---

Is this the intended behavior? I don't seem to understand how to get all context from the app object, whereas app.node.getContext(...) works as expected.

Misleading error message for deprecated `prepare()`

In CDKv2, lifecycle method prepare() was deprecated. Implementing such method in a construct correctly reports an error message. However, the error message is misleading:

Error: the construct "Stack/Foobar" has a "prepare()" method which is no longer supported. Use "construct.node.addValidation()" to add validations to a construct

The error message suggests to use addValidation(), which doesn't serve the same purpose.

CDK team suggests to use Aspects to implement prepare logic in V2, e.g.:

Aspects.of(construct).add({
  visit: () => doPrepare()
})

In this case, the error message could be more clear, e.g.:

Error: the construct "Stack/Foobar" has a "prepare()" method which is no longer supported. Use Aspects to add preparation logic to a construct

Reproduction Steps

Synthesize any construct implementing the prepare() lifecycle method. Example:

import { Stack } from "aws-cdk-lib";
import { Construct } from 'constructs';

class MyConstruct extends Construct {
  constructor(scope: Construct, id: string) {
    super(scope, id)
  }

  prepare() { }
}

export class MyStack extends Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id, props);
    
    new MyConstruct(this, "myConstruct")
  }
}

What did you expect to happen?

Clear error message suggesting the usage of Aspects:

Error: the construct "Stack/MyConstruct" has a "prepare()" method which is no longer supported. Use Aspects to add preparation logic to a construct

What actually happened?

Misleading error message, suggesting using addValidation as a workaround:

Error: the construct "Stack/MyConstruct" has a "prepare()" method which is no longer supported. Use "construct.node.addValidation()" to add validations to a construct

Environment

• CDK CLI Version: 2.0.0-rc.1 (build 983379b)
• Framework Version: 2.0.0-rc.1
• Node.js Version: v15.12.0
• OS: MacOS Catalina 10.15.7
• Language (Version): TypeScript (3.9.9)

Other

---

This is 🐛 Bug Report

NuGet Release failed for `10.1.121`

We're getting errors in CI due to a missing constructs version 10.1.121, apparently it failed to release to NuGet:
https://github.com/aws/constructs/actions/runs/3178412027/jobs/5180232659

crypto.createHash('md5') fails in a FIPS-enabled environment

Description

Our team is building an operator based on cdk8s and one of our deployment targets is a FIPS-enabled kubernetes cluster. When running cdk8s (and by proxy the constructs library), we encounter the following error when attempting to to run a synth:

Error: error:060800C8:digital envelope routines:EVP_DigestInit_ex:disabled for FIPS

Root Cause

The root-cause of this bug is this line where crypto.createHash('md5') is invoked. According to the internet the md5 crypto hash algorithm is considered insecure by FIPS standards and is thus disabled in the underlying openssl libraries when the operating system is running in FIPS mode.

Repro

(In a FIPS-enabled cluster. Not sure how to easily reproduce this)

const crypto = require('crypto');
crypto.createHash('md5').update(path.join('/')).digest("hex");

Proposed Solution

I believe that the point of the offending line is simply to compute a unique value for the given string path, so I think we can simply replace 'md5' with a FIPS-approved algorithm like sha1 or sha256. I've tested both and they both produce valid hash values.

Volunteering!

I'd be happy to try to fix this one and submit a PR

Version `10.1.301` not available on NuGet / Maven

Hi! We're seeing errors in our builds because the latest publish to NuGet (and Maven) seems to have failed which cause an inconsistency in versions available on NPM vs e.g. NuGet.

`Node.synthesize()` should delegate nested syntheses to subconstructs

Node.synthesize() decides what constructs that it will synthesize into the CURRENT CloudAssembly, and it will select all constructs underneath itself that are synthesizable, and it will synthesize from the leaves to the root.

This makes it impossible to make an intermediary construct which synthesizes its childen into a different Cloud Assembly.

Consider the following:

       App
         \
        Stage
           \
          Child

When app.synth() is called, the first thing it will do is call child.synthesize() to synthesize that child into the given Cloud Assembly. This is a problem, as Stage would have wanted to create a sub-cloud assembly and synthesize Child into that.

Even if we had ordered the children differently, that would not have helped. We would have synthesized Stage first, and then Stage could synthesize Child into the inner Cloud Assembly. That's a good start, but then subsequently App would have synthesized Child again into the root cloud assembly, which is wrong.

At least if we had had the latter order we could have done some JavaScript hackery to replace the synthesize method on Child with a no-op function.

---

The right solution would have been for Node.synthesize() is to iterate through its subtree top-down, invoke synthesize() on constructs that implement it, and then stop iterating. It's then up to the constructs that synthesize themselves on what to do with their own subtree (recurse or not, and in which fashion they should recurse).

Another solution is to have Node.synthesize() invoke synthesize on its own direct children, and have the default implementation recurse to its children, and so on, and always do full recursion.

use of deprecated Node.of()

While reading/learning the code of this repository, I mentioned that there was a leftover usage of the deprecated Node.of() method. I fixed that with #1086

Release notes

Could you please include release notes with each release, even if these are just generated from PR titles? This would help to evaluate upgrades. Thanks.

Deno compatible

Hey folks, I would like to use the package from Deno, but it uses some NodeJS API

constructs/src/private/uniqueid.ts

Line 1 in ede084c

import * as crypto from 'crypto';

Is there any opportunity to make this Deno compatible?

creating root construct in Python

I installed constructs version 10.1.14 via pip. I am using Python 3.9.12 and NodeJS 16.15.0. I tried to create a root construct, but it throws an exception.

import constructs

constructs.Construct(None, '')

jsii.errors.JavaScriptError:
Error: Got 'undefined' for non-optional instance of {"docs":{"summary":"The scope in which to define this construct."},"name":"scope","type":{"fqn":"constructs.Construct"}}
at nullAndOk (/tmp/tmpnx__46nv/lib/program.js:9608:23)
at Object.deserialize (/tmp/tmpnx__46nv/lib/program.js:9382:25)
at Kernel._toSandbox (/tmp/tmpnx__46nv/lib/program.js:8771:69)
at /tmp/tmpnx__46nv/lib/program.js:8819:42
at Array.map ()
at Kernel._boxUnboxParameters (/tmp/tmpnx__46nv/lib/program.js:8819:27)
at Kernel._toSandboxValues (/tmp/tmpnx__46nv/lib/program.js:8805:29)
at /tmp/tmpnx__46nv/lib/program.js:8420:75
at Kernel._wrapSandboxCode (/tmp/tmpnx__46nv/lib/program.js:8848:24)
at Kernel._create (/tmp/tmpnx__46nv/lib/program.js:8420:34)

Is this a bug? Or is there some other way I'm supposed to create a root construct in Python?

Suspicious release history

In our project dependabot wanted to update constructs from 3.2.71 to 7.0.1, but change history and commits in repository point to 3.3.* range. Also version history in https://pypi.org/project/constructs/#history looks quite suspicious

Add a `pathHash` method to `ConstructNode`

🚀 Feature Request

General Information

• 👋 I may be able to implement this feature request

• ⚠️ This feature might incur a breaking change

Description

See this comment.

Surprisingly strict node requirement in engines in package.json

https://github.com/aws/constructs/blob/10.x/package.json says:

"engines": {
  "node": ">= 14.17.0"
},

Does constructs actually need >= 14.17.0, or will older versions work? Could it be relaxed to just >= 14, or are there known issues with older node versions?

Reporting a vulnerability

Hello!

I hope you are doing well!

We are a security research team. Our tool automatically detected a vulnerability in this repository. We want to disclose it responsibly. GitHub has a feature called Private vulnerability reporting, which enables security research to privately disclose a vulnerability. Unfortunately, it is not enabled for this repository.

Can you enable it, so that we can report it?

Thanks in advance!

PS: you can read about how to enable private vulnerability reporting here: https://docs.github.com/en/code-security/security-advisories/repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository

Update Python dependencies (typeguard)

Hey!
I'm not sure about how you manage python dependencies.
I'm working on a project using glue Python shell scripts.
Trying to add Pandera to validate Pandas DFs, my dependency manager (poetry) shows:

Because no versions of pandera match >0.18.0,<0.19.0
 and pandera (0.18.0) depends on typeguard (>=3.0.2), pandera (>=0.18.0,<0.19.0) requires typeguard (>=3.0.2).
And because constructs (10.3.0) depends on typeguard (>=2.13.3,<2.14.0)
 and no versions of constructs match >10.3.0,<11.0.0, pandera (>=0.18.0,<0.19.0) is incompatible with constructs (>=10.3.0,<11.0.0).
So, because testglue depends on both constructs (^10.3.0) and pandera (^0.18.0), version solving failed.

That version of Typeguard is quite old (currently 4.x)

Is it possible to use updated dependencies?
thx!

NuGet publishing is failing

error: Response status code does not indicate success: 403 (The specified API key is invalid, has expired, or does not have permission to access the specified package.).

.github/pull_request_template.md is added twice with mixed case

gh repo clone aws/constructs
Cloning into 'constructs'...
remote: Enumerating objects: 189, done.
remote: Counting objects: 100% (189/189), done.
remote: Compressing objects: 100% (133/133), done.
remote: Total 2855 (delta 103), reused 107 (delta 41), pack-reused 2666
Receiving objects: 100% (2855/2855), 2.06 MiB | 8.91 MiB/s, done.
Resolving deltas: 100% (2043/2043), done.
warning: the following paths have collided (e.g. case-sensitive paths
on a case-insensitive filesystem) and only one from the same
colliding group is in the working tree:

  '.github/PULL_REQUEST_TEMPLATE.md'
  '.github/pull_request_template.md'

Async code in constructor

Hi! How can I execute async code in construct's constructor? Javascript/Typescript constructors disallow await. I would like to have an async build step before passing results onto sub-constructs.

My build is broken with latest constructs.

Why did you guys move runtime condition without major version bump? Isn't this a breaking change ?

My tests started to fail with right after you guys shipped. I do have ^ here https://github.com/aws-amplify/amplify-cli/blob/f5cebf532894bf4a22d9f938933c38fc4f8e4b1a/packages/amplify-category-custom/resources/package.json#L13 . I would expect that when you ship minor or patch version increment my environment doesn't just break.

error [email protected]: The engine \"node\" is incompatible with this module. Expected version \">= 14.18.0\".

Looks like it went out here #1611 .

not existent parameter in the code docs of Construct.constructor

Within the code documentation of the Construct.constructor the linter complains about

JSDoc '@param' tag has name 'options', but there is no parameter with that name.ts(8024)

I fixed that in #1088

Allow a Custom Seperator for UniqueId

Allow a custom separator for Node#uniqueId, or introduce a friendlyUniqueId which takes an optional separator string.

Current behaviour

Node.of(this).uniqueId // => fooBar230sdkf

Desired behaviour

Node.of(this).uniqueId('_') // => foo_Bar_230sdkf

// since the above would change the interface, the following would also be good 

Node.of(this).friendlyUniqueId('_') // => foo_Bar_230sdkf

Right now I'm working around this by duplicating unique.ts and adjusting the code accordingly. Would be cool if that wasn't necessary.

.github/PULL_REQUEST_TEMPLATE.md exists twice with mixed case in the file name

gh repo clone aws/constructs
Cloning into 'constructs'...
remote: Enumerating objects: 189, done.
remote: Counting objects: 100% (189/189), done.
remote: Compressing objects: 100% (133/133), done.
remote: Total 2855 (delta 103), reused 107 (delta 41), pack-reused 2666
Receiving objects: 100% (2855/2855), 2.06 MiB | 8.91 MiB/s, done.
Resolving deltas: 100% (2043/2043), done.
warning: the following paths have collided (e.g. case-sensitive paths
on a case-insensitive filesystem) and only one from the same
colliding group is in the working tree:

  '.github/PULL_REQUEST_TEMPLATE.md'
  '.github/pull_request_template.md'

id docstring refers to nonexistent field "uniqueId"

constructs/src/construct.ts

Line 45 in a851178

* This is a a scope-unique id. To obtain an app-unique id for this construct, use `uniqueId`.

(This only applies to constructs v10).

I think this should refer to the addr field instead.

Patch update introduces breaking change

Updating from constructs version ^10.2.62 to ^10.2.63 introduces breaking changes. The update is trying to delete or recreate capacity providers in my ECS cluster which breaks the update flow.

4:26:44 PM | UPDATE_FAILED        | Custom::AWS                                     | ApplicationClu...thStrategyD973EC6E
Received response status [FAILED] from custom resource. Message returned: The specified capacity provider is in use and cannot
be removed. (RequestId: 7fa2ce86-d772-48e9-a4d9-802270f2823c)

I think this is because the capacity provider name changes with this update.

physicalResourceId: PhysicalResourceId.of(
          capacityProvider.capacityProviderName
        ),

maven constructs versions

The constructs package versions 3.3.118 through 3.3.158 are missing from the maven manifest starting on 10/07/2021
https://repo.maven.apache.org/maven2/software/constructs/constructs/maven-metadata.xml

yet those versions exists in the package directory: ( https://repo.maven.apache.org/maven2/software/constructs/constructs/3.3.124/ for example) and in other language repos like pypy, npm and nuget.

Our company uses jsii-pacmak to compile and publishe cdk constructs internally for developer use. We have a standard practice of pinning the version of aws cdk constructs packages and the aws construct library to a specific version to ensure consistent build and usage. We were using aws cdk 1.118.0 and constructs version 3.3.124. We new need to do an emergency upgrade to something 3.3.159 or later.

If these versions were removed accidentally from maven, can they be added back? Our published java packages that have this version pinned are broken.

If these versions were removed intentionally, can we get an explaination as to why? Secondary question: is not a good practice to pin the constructs library version. I notice that aws cdk project does not. ex: https://github.com/aws/aws-cdk/blob/v1.118.0/packages/@aws-cdk/core/package.json#L193

Thank you

Too easy to have bad dependency versions and errors are confusing

Was recently working on an update to some cdk8s code and ran into an issue where I was using a jsii-library I had previously compiled to earlier versions of cdk8s and constructs. After the upgrade the construct was failing on the consumer side with an obscure error around this code:

https://github.com/aws/constructs/blob/10.x/src/construct.ts#L71

It was ultimately caused by the consuming code using an older version of the constructs library.

I recommend an error get added here to check and suggest a solution.

`Node.of(this).uniqueId` is bound to CloudFormation's logical ID rules

I understand that constructs were supposed to support cdk, so It was also understandable that Node.of(this).uniqueId is bound to CloudFormation's logical ID rules:
([A-Za-z0-9]{255})
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resources-section-structure.html#resources-section-structure-resource-fields
https://docs.amazonaws.cn/en_us/AWSCloudFormation/latest/UserGuide/cloudformation-limits.html

However, constructs is now also used as a foundation of cdk8s, and Kubernetes imposes different rules to resource names and labels:

DNS Subdomain Names

Most resource types require a name that can be used as a DNS subdomain name as defined in RFC 1123. This means the name must:

• contain no more than 253 characters
• contain only lowercase alphanumeric characters, '-' or '.'
• start with an alphanumeric character
• end with an alphanumeric character

DNS Label Names

Some resource types require their names to follow the DNS label standard as defined in RFC 1123. This means the name must:

• contain at most 63 characters
• contain only lowercase alphanumeric characters or '-'
• start with an alphanumeric character
• end with an alphanumeric character

https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names

Valid label keys have two segments: an optional prefix and name, separated by a slash (/). The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain (...)

Valid label values must be 63 characters or less and must be empty or begin and end with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between.

https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set

Some CF names might exceed K8s' name length limit, and contain upper case letters, and some K8s names/labels might contain invalid characters for CF ('-', '_', '.', '_')

Removing Node.of(this).uniqueId from constructs and letting cdk and cdk8s to implement their own uniqueId would prevent confusions and unnecessary limits on each frameworks.

Maybe this is related to this: #120

Copyright information in the License file needs to be updated

Hi,

Could you please the update Copyright information in the License file.

Are npm latest releases correct?

See https://www.npmjs.com/package/constructs

Is it intentional to mark 3.3.161 as 'latest' ? This version seems incompatible with new aws-cdk@2, it was crashing with TypeError. Explicitly installing 10.0.9 solved the problem for me.

In certain cases it is not possible to downcast `IConstruct` to `Construct`

The way nodes are associated with constructs breaks a use case where IConstruct objects would be treated as Construct objects through downcasting.

See aws/aws-cdk#6885

Granted, down-casting is against the "contract" of the API, but it still exists in a few places in the AWS CDK is already a stable product, and therefore we have to figure out a way to enable this use case.

Constructs dependency is not supporting Node 12.x

Dear dev team,
we are currently facing the issue with Constructs library on our project. One of our projects is running on Node 12.x and since 9th of June 2022 we are having troubles with Constructs library. Many AWS libraries have transient dependency to your Constructs package. Unfortunatelly a day ago one of your dependencies introduced backward not compatible breaking change in minor version. If we are right the issue is in your dev-dependency "jsii": "^1.60.0". They have published 1.60.0 version with following words: "Beginning with this release, jsii packages no longer support node 12." (https://github.com/aws/jsii/releases/tag/v1.60.0). As far as we know AWS-CDK in version 1.159.0 should support Node 12.x but it seems like issue right now. Can you verify the issue, please?

Current issue:

/node_modules/constructs/lib/construct.js:501
            const nodeFactory = options.nodeFactory ?? { createNode: (host, nodeScope, nodeId) => new Node(host, nodeScope, nodeId) };
                                                     ^

    SyntaxError: Unexpected token '?'

      at Runtime.createScriptFromCode (node_modules/jest-runtime/build/index.js:1350:14)
      at Object.<anonymous> (node_modules/constructs/src/index.ts:2:1)