feat(assets): enable local tooling scenarios such as lambda debugging

[eladb]

Adds CloudFormation resource metadata which enables tools such as SAM
CLI to find local assets used by resources in the template.

See design document under design/code-asset-metadata.md

Fixes #1432

[eladb]

@jfuss please review this and let me know if this looks good

[jfuss]

Looking now.

[jfuss]

Why only AWS::Lambda::Functions? What about AWS::Lambda::LayerVersion, AWS::Serverless::Function, and AWS::Serverless::LayerVersion?

We are purposefully excluding API Gateway from this correct?

Is there a generic way this could work to allow any resource using an Asset to get this metadata? Trying to think broader here to make less work in the future of manually adding this metadata to every resource.

[eladb]

The implementation allows anyone who uses an asset to attach this metadata to the resource by calling asset.addResourceMetadata(resource, prop). I decided against doing this automatically because this problem is basically confined to only L2 constructs. Any higher level constructs shouldn't care about this at all, so I opted for a more manual solution.

Layers are currently in PR (#1411) and @RomainMuller should probably.

[jfuss]

@eladb What about AWS::Serverless::Function?

[eladb]

@jfuss the AWS::Serverless::Function is currently only supported as an L1 construct (serverless.CfnFunction), and I suspect people who use it will likely not try to use it with CDK assets but rather with CodeUri. For example:

new serverless.CfnFunction(this, 'Func', {
  codeUri: 'file://mycode',
   runtime: 'nodejs8.10',
   handler: 'index.handler'
});

If users wish to use CDK assets (and invoke them locally through SAM CLI), this is what they will have to do:

const asset = new assets.ZipDirectoryAsset(this, 'Foo', {
  path: '/foo/boom'
});

const resource = new serverless.CfnFunction(this, 'Func', {
    codeUri: {
    bucket: asset.s3BucketName,
    key: asset.s3ObjectKey
  },
  runtime: 'nodejs8.10',
  handler: 'index.handler'
});

resource.addResourceMetadata(resource, 'CodeUri');

But TBH, I doubt that this makes sense. If you are already writing "CDK native" code, the L2 constructs for Lambda, API Gateway, etc provides a much richer API then the AWS::Serverless::Function resource.

What do you think?

[jfuss]

@eladb I see. So it's more like Assets aren't directly supported within AWS::Serverless::Function like it is with AWS::Lambda::Functions (over simplifying here due to the Construct level difference). I see Assets being powerful and something we should consider supporting directly but out of scope for this PR.

Thanks for clarifying this.

[mergify]

Thanks so much for taking the time to contribute to the AWS CDK ❤️

We will shortly assign someone to review this pull request and help get it
merged. In the meantime, please take a minute to make sure you follow this
checklist:

• PR title type(scope): text
  • type: fix, feat, refactor go into CHANGELOG, chore is hidden
  • scope: name of module without aws- or cdk- prefix or postfix (e.g. s3 instead of aws-s3-deployment)
  • text: use all lower-case, do not end with a period, do not include issue refs
• PR Description
  • Rationale: describe rationale of change and approach taken
  • Issues: indicate issues fixed via: fixes #xxx or closes #xxx
  • Breaking?: last paragraph: BREAKING CHANGE: <describe what changed + link for details>
• Testing
  • Unit test added. Prefer to add a new test rather than modify existing tests
  • CLI or init templates change? Re-run/add CLI integration tests
• Documentation
  • README: update module README to describe new features
  • API docs: public APIs must be documented. Copy from official AWS docs when possible
  • Design: for significant features, follow design process