document alternative workflow for local testing

Author: softprops

README.md

@@ -1,11 +1,13 @@
-# AWS Lambda [Rust](https://www.rust-lang.org/) docker builder 🐑 🐳 🦀 [![Build Status](https://github.com/softprops/lambda-rust/workflows/Main/badge.svg)](https://github.com/softprops/lambda-rust/actions)
+# AWS Lambda [Rust](https://www.rust-lang.org/) docker builder 🐑 🦀 🐳 [![Build Status](https://github.com/softprops/lambda-rust/workflows/Main/badge.svg)](https://github.com/softprops/lambda-rust/actions)
 
 
 ## 🤔 about
 
 This docker image extends [lambda ci `provided`](https://github.com/lambci/docker-lambda#documentation) builder docker image, a faithful reproduction of the actual AWS "**provided**" Lambda runtime environment,
 and installs [rustup](https://rustup.rs/) and the *stable* rust toolchain.
 
+This provides a build environment, consistent with your target execution environment for predicable results.
+
 ## 📦 install
 
 Tags for this docker image follow the naming convention `softprops/lambda-rust:{version}-rust-{rust-stable-version}`
@@ -66,13 +68,76 @@ The hooks' names are predefined and must be placed in a directory `.lambda-rust`
 
 You can take a look at an example [here](./tests/test-func-with-hooks).
 
+## 🔬 local testing
+
+Once you've built a Rust lambda function artifact, the `provided` runtime expects
+deployments of that artifact to be named "**bootstrap**". The `lambda-rust` docker image
+builds a zip file, named after the binary, containing your binary files renamed to "bootstrap" for you.
+
+You can invoke this bootstap executable with the lambda-ci docker image for the `provided` AWS lambda runtime with a one off container.
+
+```sh
+# start a one-off docker container replicating the "provided" lambda runtime
+# awaiting an event to be provided via stdin
+$ unzip -o \
+    target/lambda/release/{your-binary-name}.zip \
+    -d /tmp/lambda && \
+  docker run \
+    -i -e DOCKER_LAMBDA_USE_STDIN=1 \
+    --rm \
+    -v /tmp/lambda:/var/task:ro,delegated \
+    lambci/lambda:provided
+
+# provide an event payload via stdin (typically a json blob)
+
+# Ctrl-D to yield control back to your function
+```
+
+If you may find the one-off container less than ideal for if you wish to trigger your lambda multiple times. For these cases try using the "stay open" mode of execution.
+
+```sh
+# start a long running docker container replicating the "provided" lambda runtime
+# listening on port 9001
+$ unzip -o \
+    target/lambda/release/{your-binary-name}.zip \
+    -d /tmp/lambda && \
+  docker run \
+    --rm \
+    -v /tmp/lambda:/var/task:ro,delegated \
+    -e DOCKER_LAMBDA_STAY_OPEN=1 \
+    -p 9001:9001 \
+    lambci/lambda:provided
+```
+
+In a separate terminal, you can invoke your function with `curl`
+
+The `-d` flag is a means of providing your function's input.
+
+```sh
+curl -d '{}' \
+    http://localhost:9001/2015-03-31/functions/myfunction/invocations
+```
+
+You can also the `aws` cli to invoke your function locally.  The `--payload` is a means of providing your function's input.
+
+```sh
+aws lambda invoke \
+    --endpoint http://localhost:9001 \
+    --cli-binary-format raw-in-base64-out \
+    --no-sign-request \
+    --function-name myfunction \
+    --payload '{}' out.json \
+    && cat out.json \
+    && rm -f out.json
+```
+
 ## 🤸🤸 usage via cargo aws-lambda subcommand
 
-If you want to set up ad hoc lambda functions or have another reason to not to go with full blown devops orchestration tools,
-there's a cargo subcommand to compile your code into a zip file and deploy it to an existing function. This comes with only
+A third party cargo subcommand exists to compile your code into a zip file and deploy it. This comes with only
 rust and docker as dependencies.
 
 Setup
+
 ```sh
 $ cargo install cargo-aws-lambda
 ```
@@ -89,29 +154,5 @@ $ cargo aws-lambda --help
 
 More instructions can be found [here](https://github.com/vvilhonen/cargo-aws-lambda).
 
-## 🔬 local testing
-
-Once you've built a Rust lambda function artifact, the `provided` runtime expects
-deployments of that artifact to be named "**bootstrap**". The `lambda-rust` docker image
-builds a zip file, named after the binary, containing your binary files renamed to "bootstrap"
-
-You can invoke this bootstap executable with the lambda-ci docker image for the `provided` AWS lambda runtime.
-
-```sh
-# start a docker container replicating the "provided" lambda runtime
-# awaiting an event to be provided via stdin
-$ unzip -o \
-    target/lambda/release/{your-binary-name}.zip \
-    -d /tmp/lambda && \
-  docker run \
-    -i -e DOCKER_LAMBDA_USE_STDIN=1 \
-    --rm \
-    -v /tmp/lambda:/var/task \
-    lambci/lambda:provided
-
-# provide an event payload via stdin (typically a json blob)
-
-# Ctrl-D to yield control back to your function
-```
 
 Doug Tangren (softprops) 2020