docs(examples): add example for AWS SAM

[bpauwels]

Description of your changes

Added an example for AWS SAM

How to verify this change

see new SAM example, use SAM CLI to deploy it

Related issues, RFCs

#606

PR status

Is this ready for review?: YES
Is it a breaking change?: NO

Checklist

• My changes meet the tenets criteria
• I have performed a self-review of my own code
• I have commented my code where necessary, particularly in areas that should be flagged with a TODO, or hard-to-understand areas
• I have made corresponding changes to the documentation
• I have made corresponding changes to the examples
• My changes generate no new warnings
• The code coverage hasn't decreased
• I have added tests that prove my change is effective and works
• New and existing unit tests pass locally and in Github Actions
• Any dependent changes have been merged and published in downstream module
• The PR title follows the conventional commit semantics

Breaking change checklist

no breaking changes

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[dreamorosi]

Hello @bpauwels thanks a lot for opening this PR. I've made a first round of review in which I've left some comments. To avoid repeating I've left the comments only in one function but they apply to others as well.

[ijemmy]

I'm concerned about the long-term maintenance of Lambda functions for different tools examples/<tools>.

Right now, we may have only SAM and CDK. But we'll eventually end up with probably 5+ tools. If we add/modify a feature, we'll need to do it 5+ times. The person who updates it will need to be familiar with 5+ tools. This will be very challenging to maintain and the example will be outdated very soon.

I'm wondering if it's possible to use Lambda functions from another folder? If so, could we reuse the same set of Lambda functions existing in the cdk examples?

# Current
examples/
  |- cdk/
  |----<all lambda files here>
  |- sam/
  |----<all lambda files here>
  

# Alternative
examples/
 |- cdk/
 |--- <only cdk related code with reference to ../lambda-functions folder>
 |- sam/
 |--- <only SAM related code with reference to ../lambda-functions folder>

The drawback is that this is quite uncommon pattern for both CDK and SAM. So we need to decide on a trade-off here.

[dreamorosi]

As an alternative to @ijemmy's proposal, that I 100% share, I'd like to bring up the option of introducing a prerequisite step for users.

With a structure like this:

examples/
 |- lambda-functions/
 |- cdk/
 |--- <cdk related code & local reference>
 |- sam/
 |--- <SAM related code & local reference>

Before running cdk deploy or sam deploy customers would have to run some version of cp -R ../lambda-functions . (or run a sh script / npm script if copying process is more involved) to bring the code in the given example that they want to try out.

Since to test this they have to clone & checkout the repo locally anyway, any change they make would be on their local version.

This would help keep the examples consistent with their idiomatic way of structuring a project and would still ease the maintenance overhead. The trade-off in this scenario would be that the examples would be less easy to just browse on GitHub.

[bpauwels]

Thanks for reviewing, I have worked on the comments from @dreamorosi and added a few more commit.

I like your idea of using lambda functions from another folder - but as of now the CDK sample and the SAM sample use completely different functions. (actually the SAM sample is based on the SAM "Quick Start: App Backend using TypeScript"). Would it make sense then?

@ijemmy

[dreamorosi]

Thanks for reviewing, I have worked on the comments from @dreamorosi and added a few more commit.

I like your idea of using lambda functions from another folder - but as of now the CDK sample and the SAM sample use completely different functions. (actually the SAM sample is based on the SAM "Quick Start: App Backend using TypeScript"). Would it make sense then?

@ijemmy

Thank you @bpauwels for addressing all the comments, really appreciate it.

We are open to modify the content of the Lambda functions in the CDK example & converge to a common example surface that showcases Lambda Powertools, so that shouldn't be an issue.

I think at this stage, and for the scope of this PR, it would be great to have the functions of this example extracted from the folder while still being able to deploy it easily and in a relatively idiomatic way.

Later on we will adapt the CDK example to use all / some / most of these same functions and definitely remove all the leftover functions under examples/cdk.

For the CDK example, the functions that we consider most important are:

• example-function.MyFunction.ts
• example-function.MyFunctionWithDecorator.ts
• example-function.MyFunctionWithMiddy.ts

We consider them as such because these are the ones that show most of the features of the three utilities and with different patterns (manual instrumentation, decorator, Middy middleware).

[saragerion]

Thanks for your contribution and the samples added. I also agree with @ijemmy and @dreamorosi's observation that this risks to become hard to maintain for us in the long term.

[bpauwels]

@dreamorosi @saragerion @ijemmy - I could not find any way to automatically create a symlink of an higher level lamdba-functions/ folder to src/handlers/ inside the SAM example. Last thing I tried was a git post-checkout hook but hooks are not commited to the repo. So the only way then would be to add an instruction to the README.md to create the symlink manually.
Do you all agree?

[dreamorosi]

@dreamorosi @saragerion @ijemmy - I could not find any way to automatically create a symlink of an higher level lamdba-functions/ folder to src/handlers/ inside the SAM example. Last thing I tried was a git post-checkout hook but hooks are not commited to the repo. So the only way then would be to add an instruction to the README.md to create the symlink manually.
Do you all agree?

Yep, that's acceptable

[dreamorosi]

Yes, it's correct if you look at it relative to the larger template, but since this is a decontextualised code snippet it's a bit odd that the first line starts with 6 spaces.

Either way it's really a minor / nitpicky comment, you can leave it if you think it makes sense.

[dreamorosi]

After the latest round of commits I was finally able to deploy the sample & execute the functions, great job!

We have just 6 items remaining to address and then we're good to go:

• docs(examples): add example for AWS SAM #674 (comment)
• docs(examples): add example for AWS SAM #674 (comment)
• docs(examples): add example for AWS SAM #674 (comment)
• docs(examples): add example for AWS SAM #674 (comment)
• docs(examples): add example for AWS SAM #674 (comment)
• docs(examples): add example for AWS SAM #674 (comment)

We are really close!!

[dreamorosi]

Thanks a ton for your hard work @bpauwels, looking forward to see this merged and to hear customer's feedback on it!