update READMEHEADmain

1 files changed, 93 insertions, 1 deletions

diff --git a/README.md b/README.md
index fe042a7..25faaa0 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,95 @@
 # notification-sender
 
-AWS Lambda to send notifications via Amazon SNS.
+A Java based AWS Lambda to send notifications via Amazon SNS (Amazon Simple Notification Service).
+
+
+## Setup
+
+### AWS Lambda
+
+- Choose the latest version of the Java runtime
+- The handler is `eu.ortlepp.notificationsender.NotificationHandler::handleRequest`
+- The recommended timeout is 30 seconds
+- The recommended RAM is 512 MB
+- Two environment variables are required to run the Lambda:
+  - `REGION` - the region of your SNS topic, e.g. `eu-central-1`
+  - `ARN` - the ARN of your SNS topic, something like `arn:aws:sns:eu-central-1:123456789:Topic-Name`
+- Create a function URL to trigger the Lambda
+  - It is recommended to secure the function URL with IAM
+
+### Amazon SNS
+
+- Create a new topic; in the topic, create a subscription
+  - Only e-mail subscriptions have been tested so far; other subscription types are untested
+
+
+## Data
+
+### Input (request)
+
+HTTP POST to the function URL with JSON body:
+
+```
+{
+  "messages" : ["first notification", "second notification"]
+}
+```
+
+### Output (response)
+
+The response is HTTP 200 with either
+
+```
+{
+  "status" : "SUCCESS"
+}
+```
+
+or
+
+```
+{
+  "status" : "FAILED"
+}
+```
+
+If the Lambda setup is improper, a timeout occurred, etc., the response is HTTP 500 from the AWS environment (not the Lambda itself).
+
+### Result (SNS message)
+
+If the messages array contains multiple messages, all elements of the messages array are combined into one SNS message. Empty messages (empty / whitespace-only string) are omitted.
+
+Only one message:
+
+```
+my notification
+```
+
+Multiple messages:
+
+```
+1. Notification:
+first notification
+
+2. Notification:
+second notification
+
+```
+
+SNS will automatically append an unsubscribe footer to each e-mail.
+
+
+## Testing
+
+You can use curl to trigger your Lambda:
+
+```
+curl -X POST -H "Content-Type: application/json" -d "{\"messages\":[\"my notification\"]}" --aws-sigv4 "aws:amz:eu-central-1:lambda" --user "ACCESS_KEY:SECRET_KEY" https://MY_FUNCTION_URL.lambda-url.eu-central-1.on.aws/
+```
+
+
+## Documentation
+
+- [Building Lambda functions with Java](https://docs.aws.amazon.com/lambda/latest/dg/lambda-java.html)
+- [How To Secure and Authenticate AWS Lambda Function URLs](https://www.rahulpnath.com/blog/how-to-secure-and-authenticate-lambda-function-urls/) & [FUNCTION URLs - Authenticating and Securing | AWS Lambda](https://www.youtube.com/watch?v=75EEaN-oBAg)
+- [Amazon SNS examples using SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/java_sns_code_examples.html)