aws-samples / aws-serverless-developer-experience-workshop-typescript

This repository contains the reference architecture implementation for the AWS Serverless Developer Experience workshop in TypeScript

AWS Serverless Developer Experience workshop reference architecture (TypeScript)

This repository contains the reference architecture for the AWS Serverless Developer Experience workshop.

The AWS Serverless Developer Experience workshop provides you with an immersive experience as a serverless developer. The goal of this workshop is to provide you with hands-on experience building a serverless solution using the AWS Serverless Application Model (AWS SAM) and AWS SAM CLI.

Along the way, you will learn about principals of distributed event-driven architectures, messaging patterns, orchestration, and observability and how to apply them in code. You will explore exciting open-source tools, the core features of Powertools for AWS Lambda, and simplified CI/CD deployments supported by AWS SAM Pipelines.

At the end of this workshop, you will be familiar with Serverless developer workflows and microservice composition using AWS SAM, Serverless development best practices, and applied event-driven architectures.

Introducing the Unicorn Properties architecture

Our use case is based on a real estate company called Unicorn Properties.

As a real estate agency, Unicorn Properties needs to manage the publishing of new property listings and sale contracts linked to individual properties, and provide a way for their customers to view approved property listings.

To support their needs, Unicorn Properties have adopted a serverless, event-driven approach to designing their architecture. This architecture is centred around two primary domains: Contracts (managed by the Contracts Service) and Properties (managed by the Web and Properties Services).

The Unicorn Contracts service (namespace: Unicorn.Contracts) is a simplified service that manages the contractual relationship between a seller of a property and Unicorn Properties. Contracts are drawn up that define the property for sale, the terms and conditions that Unicorn Properties sets, and how much it will cost the seller to engage the services of the agency.

The Unicorn Web (namespace: Unicorn.Web) manages the details of a property listing to be published on the Unicorn Properties website. Every property listing has an address, a sale price, a description of the property, and some photos that members of the public can look at to get them interested in purchasing the property. Only properties that have been approved for publication can be made visible to the public.

The Unicorn Properties service (namespace: Unicorn.Properties) approves a property listings. This service implements a workflow that checks for the existence of a contract, makes sure that the content and the images are safe to publish, and finally checks that the contract has been approved. We don’t want to publish a property until we have an approved contract!

Have a go at building this architecture yourself! Head over to the Serverless Developer Experience Workshop for more details.

Credits

Throughout this workshop we wanted to introduce you to some Open Source tools that can help you build serverless applications. This is not an exhaustive list, just a small selection of what we will be using in the workshop.

Many thanks to all the AWS teams and community builders who have contributed to this list:

Tools	Description	Download / Installation Instructions
cfn-lint	Validate AWS CloudFormation yaml/json templates against the AWS CloudFormation Resource Specification and additional checks.	https://github.com/aws-cloudformation/cfn-lint
cfn-lint-serverless	Compilation of rules to validate infrastructure-as-code templates against recommended practices for serverless applications.	https://github.com/awslabs/serverless-rules
@mhlabs/iam-policies-cli	CLI for generating AWS IAM policy documents or SAM policy templates based on the JSON definition used in the AWS Policy Generator.	https://github.com/mhlabs/iam-policies-cli
@mhlabs/evb-cli	Pattern generator and debugging tool for Amazon EventBridge	https://github.com/mhlabs/evb-cli

aws-serverless-developer-experience-workshop-typescript's Issues

Maintenance: Update main branch

Summary

Update main with latest changes from dev

Why is this needed?

branch hygiene

Solution

No response

ESBuild fails for SAM CLI > 1.56

ESBuild needs to move to project dependencies - see aws/aws-sam-cli#4183 (comment)

sam sync dependency layer is too big - causes sam sync to fail

When using sam sync --watch with the Typescript build, the AutoDependencyLayer that is generated is too big to deploy to Lambda (error is Unzipped size must be smaller than 262144000 bytes as per the AutoDependencyLayer CFN stack).

This is because all the node_modules are being included as raw, and hence easily flood the size cap for Lambda (unzipped).
It should be noted the resulting Lambda function file is only 4.8Mb (after esbuild combines everything as required).

This can be worked around with sam sync --watch --no-dependency-layer

Ideally this is fixed so that dependencies can still be generated by sam sync but might need a way to better shake the dependency tree.

fix: add SqsManagedSseEnabled to SQS resources explicitly

Internal code scanning requirement. Example:

PropertiesEventBusRuleDLQ:
    Type: AWS::SQS::Queue
    UpdateReplacePolicy: Delete
    DeletionPolicy: Delete
    Properties:
      SqsManagedSseEnabled: true
      MessageRetentionPeriod: 1209600 # Maximum value, 1,209,600 (14days)
      Tags:
        - Key: project
          Value: AWS Serverless Developer Experience
        - Key: service
          Value: !Sub "{{resolve:ssm:/UniProp/${Stage}/UnicornPropertiesNamespace}}"
        - Key: stage
          Value: !Ref Stage

Bug: build github action failing

Expected Behaviour

Build should pass

Current Behaviour

Build does not pass due to miss configured gh action

Code snippet

NA

Possible Solution

No response

Steps to Reproduce

NA

Debugging logs

No response

Maintenance: Define namespaces only once

Summary

Namespaces defined in parameter store only need to be defined once per domain/sub-domain. They are not environment specific variables.

Why is this needed?

Simplify the use of namespace parameters and make the definitions of namespaces unique per domain.

Solution

No response

Bug: [/Resources/ContractsTableStreamToEventPipe/Type/SourceParameters/DynamoDBStreamParameters] 'null' values are not allowed in templates

Expected Behaviour

sam deploy
should lead to successful deployment

Current Behaviour

sam deploy
produced error:
Error: Failed to create changeset for the stack: uni-prop-local-contracts, ex: Waiter ChangeSetCreateComplete failed: Waiter encountered a terminal failure state: For expression "Status" we matched expected path: "FAILED" Status: FAILED. Reason: [/Resources/ContractsTableStreamToEventPipe/Type/SourceParameters/DynamoDBStreamParameters] 'null' values are not allowed in templates

Code snippet

sam deploy

                Managed S3 bucket: aws-sam-cli-managed-default-samclisourcebucket-yu9dziyvptkw
                A different default S3 bucket can be set in samconfig.toml
                Or by specifying --s3-bucket explicitly.
File with same data already exists at uni-prop-local-contracts/6cc61cdc11a1db27c197342a0f2461c4, skipping upload
File with same data already exists at uni-prop-local-contracts/d280835f54ec7e9b01096ed38c8dd4c7, skipping upload
File with same data already exists at uni-prop-local-contracts/453284e83228f68a2bd571ef9cf601a8.template, skipping upload
File with same data already exists at uni-prop-local-contracts/3ffa68cf01c3b07b5e8ebde79a8b0918.template, skipping upload

        Deploying with following values
        ===============================
        Stack name                   : uni-prop-local-contracts
        Region                       : us-west-2
        Confirm changeset            : False
        Disable rollback             : True
        Deployment s3 bucket         : aws-sam-cli-managed-default-samclisourcebucket-yu9dziyvptkw
        Capabilities                 : ["CAPABILITY_IAM", "CAPABILITY_AUTO_EXPAND"]
        Parameter overrides          : {"Stage": "local"}
        Signing Profiles             : {}

Initiating deployment
=====================

File with same data already exists at uni-prop-local-contracts/a68ada9b53b1e0e327df3a4aba53f7fa.template, skipping upload


Waiting for changeset to be created..

Error: Failed to create changeset for the stack: uni-prop-local-contracts, ex: Waiter ChangeSetCreateComplete failed: Waiter encountered a terminal failure state: For expression "Status" we matched expected path: "FAILED" Status: FAILED. Reason: [/Resources/ContractsTableStreamToEventPipe/Type/SourceParameters/DynamoDBStreamParameters] 'null' values are not allowed in templates

Possible Solution

No response

Steps to Reproduce

1. copy-paste template.yaml into workshop environment
2. run sam deploy

Debugging logs

No response