docs/refactor: add documentation for invoking HTTP functions locally (#601)

* docs: fix  missing specified language on codeblock

* docs: concise examples to perform local testing
- use `cargo lambda watch` instead of `start` because `start` is not listed in `cargo lambda --help`
- fix incorrect redirect to `cargo lambda watch` instead of `cargo lambda invoke`

* docs: fix all non-visual markdown lint errors

* refactor: use non-deprecated `with_ymd_and_hms`

* docs: add example of the error received

* docs: fix incorrect detail on the `invoke` command

Author: winstxnhdw

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,7 +2,6 @@
 
 *Description of changes:*
 
-
 By submitting this pull request
 
 - [ ] I confirm that my contribution is made under the terms of the Apache 2.0 license.

CODE_OF_CONDUCT.md

@@ -1,4 +1,5 @@
 ## Code of Conduct
-This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). 
-For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact 
+
+This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
+For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
 [email protected] with any additional questions or comments.

CONTRIBUTING.md

@@ -6,7 +6,6 @@ documentation, we greatly value feedback and contributions from our community.
 Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
 information to effectively respond to your bug report or contribution.
 
-
 ## Reporting Bugs/Feature Requests
 
 We welcome you to use the GitHub issue tracker to report bugs or suggest features.
@@ -19,8 +18,8 @@ reported the issue. Please try to include as much information as you can. Detail
 * Any modifications you've made relevant to the bug
 * Anything unusual about your environment or deployment
 
-
 ## Contributing via Pull Requests
+
 Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
 
 1. You are working against the latest source on the *main* branch.
@@ -39,20 +38,19 @@ To send us a pull request, please:
 GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
 [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
 
-
 ## Finding contributions to work on
-Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any ['help wanted'](https://github.com/awslabs/aws-lambda-rust-runtime/labels/help%20wanted) issues is a great place to start.
 
+Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any ['help wanted'](https://github.com/awslabs/aws-lambda-rust-runtime/labels/help%20wanted) issues is a great place to start.
 
 ## Code of Conduct
+
 This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
 For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
 [email protected] with any additional questions or comments.
 
-
 ## Security issue notifications
-If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.
 
+If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.
 
 ## Licensing
 

README.md

@@ -41,7 +41,7 @@ See other installation options in [the Cargo Lambda documentation](https://www.c
 
 To create your first function, run Cargo Lambda with the [subcommand `new`](https://www.cargo-lambda.info/commands/new.html). This command will generate a Rust package with the initial source code for your function:
 
-```
+```bash
 cargo lambda new YOUR_FUNCTION_NAME
 ```
 
@@ -72,13 +72,12 @@ async fn func(event: LambdaEvent<Value>) -> Result<Value, Error> {
 
 If you already have Cargo Lambda installed in your machine, run the next command to build your function:
 
-```
+```bash
 cargo lambda build --release
 ```
 
 There are other ways of building your function: manually with the AWS CLI, with [AWS SAM](https://github.com/aws/aws-sam-cli), and with the [Serverless framework](https://serverless.com/framework/).
 
-
 ### 1. Cross-compiling your Lambda functions
 
 By default, Cargo Lambda builds your functions to run on x86_64 architectures. If you'd like to use a different architecture, use the options described below.
@@ -99,7 +98,7 @@ Amazon Linux 1 uses glibc version 2.17, while Rust binaries need glibc version 2
 
 If you are building for Amazon Linux 1, or you want to support both Amazon Linux 2 and 1, run:
 
-```
+```bash
 # Note: replace "aarch64" with "x86_64" if you are building for x86_64
 cargo lambda build --release --target aarch64-unknown-linux-gnu.2.17
 ```
@@ -125,7 +124,6 @@ cargo lambda deploy \
 This command will create a Lambda function with the same name of your rust package. You can change the name
 of the function by adding the argument at the end of the command:
 
-
 ```bash
 cargo lambda deploy \
   --iam-role arn:aws:iam::XXXXXXXXXXXXX:role/your_lambda_execution_role \
@@ -154,7 +152,6 @@ cargo lambda build --release --arm64 --output-format zip
 
 You can find the resulting zip file in `target/lambda/YOUR_PACKAGE/bootstrap.zip`. Use that file path to deploy your function with the [AWS CLI](https://aws.amazon.com/cli/):
 
-
 ```bash
 $ aws lambda create-function --function-name rustTest \
   --handler bootstrap \
@@ -257,7 +254,7 @@ $ npx serverless deploy
 Invoke it using serverless framework or a configured AWS integrated trigger source:
 
 ```bash
-$ npx serverless invoke -f hello -d '{"foo":"bar"}'
+npx serverless invoke -f hello -d '{"foo":"bar"}'
 ```
 
 #### 2.5. Docker
@@ -331,9 +328,38 @@ fn test_my_lambda_handler() {
 
 ### Cargo Lambda
 
-[Cargo Lambda](https://www.cargo-lambda.info) provides a local server that emulates the AWS Lambda control plane. This server works on Windows, Linux, and MacOS. In the root of your Lambda project, run the subcommand `cargo lambda start` to start the server. Your function will be compiled when the server receives the first request to process. Use the subcommand `cargo lambda invoke` to send requests to your function. The `start` subcommand will watch your function's code for changes, and it will compile it every time you save the source after making changes.
+[Cargo Lambda](https://www.cargo-lambda.info) provides a local server that emulates the AWS Lambda control plane. This server works on Windows, Linux, and MacOS. In the root of your Lambda project. You can run the following subcommand to compile your function(s) and start the server.
+
+```bash
+cargo lambda watch -a 127.0.0.1 -p 9001
+```
+
+Now you can use the `cargo lambda invoke` to send requests to your function. For example:
+
+```bash
+cargo lambda invoke <lambda-function-name> --data-ascii '{ "command": "hi" }'
+```
+
+Running the command on a HTTP function (Function URL, API Gateway, etc) will require you to use the appropriate scheme. You can find examples of these schemes [here](https://github.com/awslabs/aws-lambda-rust-runtime/tree/main/lambda-http/tests/data). Otherwise, you will be presented with the following error.
+
+```rust,no_run
+Error: serde_json::error::Error
+
+  × data did not match any variant of untagged enum LambdaRequest
+```
+
+An simpler alternative is to cURL the following endpoint based on the address and port you defined. For example:
+
+```bash
+curl -v -X POST \
+  'http://127.0.0.1:9001/lambda-url/<lambda-function-name>' \
+  -H 'content-type: application/json' \
+  -d '{ "command": "hi" }'
+```
+
+> **warning** Do not remove the `content-type` header. It is necessary to instruct the function how to deserialize the request body.
 
-You can read more about how [cargo lambda watch](https://www.cargo-lambda.info/commands/watch.html) and [cargo lambda invoke](https://www.cargo-lambda.info/commands/watch.html) work on the [project's documentation page](https://www.cargo-lambda.info).
+You can read more about how [cargo lambda watch](https://www.cargo-lambda.info/commands/watch.html) and [cargo lambda invoke](https://www.cargo-lambda.info/commands/invoke.html) work on the project's [documentation page](https://www.cargo-lambda.info).
 
 ### Lambda Debug Proxy
 

examples/advanced-sqs-partial-batch-failures/README.md

@@ -2,10 +2,8 @@
 
 This example shows how to process events from an SQS queue using the partial batch failure feature.
 
-_Important note:_ your lambda sqs trigger *needs* to be configured with partial batch response support
-(the ` ReportBatchItemFailures` flag set to true), otherwise failed message will be not be reprocessed.
-For more details see:
-https://docs.aws.amazon.com/lambda/latest/dg/with-sqs.html#services-sqs-batchfailurereporting
+_Important note:_ your lambda sqs trigger _needs_ to be configured with partial batch response support
+(the `ReportBatchItemFailures` flag set to true), otherwise failed message will be not be reprocessed. You may see more details [here](https://docs.aws.amazon.com/lambda/latest/dg/with-sqs.html#services-sqs-batchfailurereporting).
 
 ## Build & Deploy
 
@@ -15,4 +13,4 @@ https://docs.aws.amazon.com/lambda/latest/dg/with-sqs.html#services-sqs-batchfai
 
 ## Build for ARM 64
 
-Build the function with `cargo lambda build --release --arm64`
+Build the function with `cargo lambda build --release --arm64`

examples/basic-error-handling/README.md

@@ -3,9 +3,9 @@
 ## Build & Deploy
 
 1. Install [cargo-lambda](https://github.com/cargo-lambda/cargo-lambda#installation)
-2. Build the function with `cargo lambda build --release` 
+2. Build the function with `cargo lambda build --release`
 3. Deploy the function to AWS Lambda with `cargo lambda deploy --iam-role YOUR_ROLE`
 
 ## Build for ARM 64
 
-Build the function with `cargo lambda build --release --arm64` 
+Build the function with `cargo lambda build --release --arm64`

examples/basic-lambda/README.md

@@ -3,9 +3,9 @@
 ## Build & Deploy
 
 1. Install [cargo-lambda](https://github.com/cargo-lambda/cargo-lambda#installation)
-2. Build the function with `cargo lambda build --release` 
+2. Build the function with `cargo lambda build --release`
 3. Deploy the function to AWS Lambda with `cargo lambda deploy --iam-role YOUR_ROLE`
 
 ## Build for ARM 64
 
-Build the function with `cargo lambda build --release --arm64` 
+Build the function with `cargo lambda build --release --arm64`

examples/basic-shared-resource/README.md

@@ -3,9 +3,9 @@
 ## Build & Deploy
 
 1. Install [cargo-lambda](https://github.com/cargo-lambda/cargo-lambda#installation)
-2. Build the function with `cargo lambda build --release` 
+2. Build the function with `cargo lambda build --release`
 3. Deploy the function to AWS Lambda with `cargo lambda deploy --iam-role YOUR_ROLE`
 
 ## Build for ARM 64
 
-Build the function with `cargo lambda build --release --arm64` 
+Build the function with `cargo lambda build --release --arm64`

examples/extension-basic/README.md

@@ -8,7 +8,6 @@
 
 The last command will give you an ARN for the extension layer that you can use in your functions.
 
-
 ## Build for ARM 64
 
 Build the extension with `cargo lambda build --release --extension --arm64`

examples/extension-combined/README.md

@@ -8,7 +8,6 @@
 
 The last command will give you an ARN for the extension layer that you can use in your functions.
 
-
 ## Build for ARM 64
 
 Build the extension with `cargo lambda build --release --extension --arm64`

examples/extension-custom-events/README.md

@@ -8,7 +8,6 @@
 
 The last command will give you an ARN for the extension layer that you can use in your functions.
 
-
 ## Build for ARM 64
 
 Build the extension with `cargo lambda build --release --extension --arm64`

examples/extension-custom-service/README.md

@@ -8,7 +8,6 @@
 
 The last command will give you an ARN for the extension layer that you can use in your functions.
 
-
 ## Build for ARM 64
 
 Build the extension with `cargo lambda build --release --extension --arm64`

examples/extension-logs-basic/README.md

@@ -8,7 +8,6 @@
 
 The last command will give you an ARN for the extension layer that you can use in your functions.
 
-
 ## Build for ARM 64
 
 Build the extension with `cargo lambda build --release --extension --arm64`

examples/extension-logs-custom-service/README.md

@@ -8,7 +8,6 @@
 
 The last command will give you an ARN for the extension layer that you can use in your functions.
 
-
 ## Build for ARM 64
 
 Build the extension with `cargo lambda build --release --extension --arm64`

examples/extension-logs-kinesis-firehose/README.md

@@ -8,7 +8,6 @@
 
 The last command will give you an ARN for the extension layer that you can use in your functions.
 
-
 ## Build for ARM 64
 
 Build the extension with `cargo lambda build --release --extension --arm64`

examples/extension-telemetry-basic/README.md

@@ -8,7 +8,6 @@
 
 The last command will give you an ARN for the extension layer that you can use in your functions.
 
-
 ## Build for ARM 64
 
 Build the extension with `cargo lambda build --release --extension --arm64`

examples/http-axum/README.md

@@ -3,9 +3,9 @@
 ## Build & Deploy
 
 1. Install [cargo-lambda](https://github.com/cargo-lambda/cargo-lambda#installation)
-2. Build the function with `cargo lambda build --release` 
+2. Build the function with `cargo lambda build --release`
 3. Deploy the function to AWS Lambda with `cargo lambda deploy --iam-role YOUR_ROLE`
 
 ## Build for ARM 64
 
-Build the function with `cargo lambda build --release --arm64` 
+Build the function with `cargo lambda build --release --arm64`

examples/http-basic-lambda/README.md

@@ -3,9 +3,9 @@
 ## Build & Deploy
 
 1. Install [cargo-lambda](https://github.com/cargo-lambda/cargo-lambda#installation)
-2. Build the function with `cargo lambda build --release` 
+2. Build the function with `cargo lambda build --release`
 3. Deploy the function to AWS Lambda with `cargo lambda deploy --iam-role YOUR_ROLE`
 
 ## Build for ARM 64
 
-Build the function with `cargo lambda build --release --arm64` 
+Build the function with `cargo lambda build --release --arm64`

examples/http-cors/README.md

@@ -3,9 +3,9 @@
 ## Build & Deploy
 
 1. Install [cargo-lambda](https://github.com/cargo-lambda/cargo-lambda#installation)
-2. Build the function with `cargo lambda build --release` 
+2. Build the function with `cargo lambda build --release`
 3. Deploy the function to AWS Lambda with `cargo lambda deploy --iam-role YOUR_ROLE`
 
 ## Build for ARM 64
 
-Build the function with `cargo lambda build --release --arm64` 
+Build the function with `cargo lambda build --release --arm64`

examples/http-dynamodb/README.md

@@ -3,17 +3,15 @@
 ## Build & Deploy
 
 1. Install [cargo-lambda](https://github.com/cargo-lambda/cargo-lambda#installation)
-2. Build the function with `cargo lambda build --release` 
+2. Build the function with `cargo lambda build --release`
 3. Deploy the function to AWS Lambda with `cargo lambda deploy --iam-role YOUR_ROLE`
 
 ## Build for ARM 64
 
-Build the function with `cargo lambda build --release --arm64` 
+Build the function with `cargo lambda build --release --arm64`
 
 Setting up Dynamodb
 
 1. Log into your account.
 2. Create a Dynamodb table with the name 'lambda_dyno_example' with the partition key of "username".
 3. Create IAM role with the permissions for Lambda, Cloudwatch and Dynamodb.
-
-

examples/http-query-parameters/README.md

@@ -3,9 +3,9 @@
 ## Build & Deploy
 
 1. Install [cargo-lambda](https://github.com/cargo-lambda/cargo-lambda#installation)
-2. Build the function with `cargo lambda build --release` 
+2. Build the function with `cargo lambda build --release`
 3. Deploy the function to AWS Lambda with `cargo lambda deploy --iam-role YOUR_ROLE`
 
 ## Build for ARM 64
 
-Build the function with `cargo lambda build --release --arm64` 
+Build the function with `cargo lambda build --release --arm64`

examples/http-raw-path/README.md

@@ -3,9 +3,9 @@
 ## Build & Deploy
 
 1. Install [cargo-lambda](https://github.com/cargo-lambda/cargo-lambda#installation)
-2. Build the function with `cargo lambda build --release` 
+2. Build the function with `cargo lambda build --release`
 3. Deploy the function to AWS Lambda with `cargo lambda deploy --iam-role YOUR_ROLE`
 
 ## Build for ARM 64
 
-Build the function with `cargo lambda build --release --arm64` 
+Build the function with `cargo lambda build --release --arm64`

examples/http-shared-resource/README.md

@@ -3,9 +3,9 @@
 ## Build & Deploy
 
 1. Install [cargo-lambda](https://github.com/cargo-lambda/cargo-lambda#installation)
-2. Build the function with `cargo lambda build --release` 
+2. Build the function with `cargo lambda build --release`
 3. Deploy the function to AWS Lambda with `cargo lambda deploy --iam-role YOUR_ROLE`
 
 ## Build for ARM 64
 
-Build the function with `cargo lambda build --release --arm64` 
+Build the function with `cargo lambda build --release --arm64`