From 697cdcb5b07c3d253cde1cdb467459c1491d021c Mon Sep 17 00:00:00 2001 From: "jack.burridge" Date: Sun, 1 Feb 2026 17:06:34 +0000 Subject: [PATCH] docs(amgi-sqs-event-source-mapping): add record handling and lifespan documentation --- .../amgi-sqs-event-source-mapping/README.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/packages/amgi-sqs-event-source-mapping/README.md b/packages/amgi-sqs-event-source-mapping/README.md index 2124bc0..bf67733 100644 --- a/packages/amgi-sqs-event-source-mapping/README.md +++ b/packages/amgi-sqs-event-source-mapping/README.md @@ -36,6 +36,38 @@ async def order_queue(order: Order) -> None: handler = SqsEventSourceMappingHandler(app) ``` +## What it does + +- Converts SQS batch events into AMGI `message.receive` events +- Uses the SQS queue name as the AMGI message address +- Supports partial batch failures so only failed messages are retried +- Sends outbound messages back to SQS efficiently using batching +- Optionally manages application startup and shutdown via AMGI lifespan +- Verifies message integrity using the SQS-provided MD5 checksum and retries corrupted messages + +## Record handling + +- Record bodies are passed to your app as bytes +- SQS record attributes become AMGI headers +- Records are only acknowledged when your app emits `message.ack` +- Records that are not acknowledged are treated as failures and will be retried +- Corrupted messages are detected automatically and retried + +## Lifespan + +Lifespan support is enabled by default. + +- Startup runs once per Lambda execution environment +- Shutdown is attempted when the environment is terminated + +Shutdown handling relies on `signal.SIGTERM`, which is supported by Python 3.12 and later Lambda runtimes. + +To use fully stateless, per-invocation behavior, disable lifespan: + +```python +handler = SqsEventSourceMappingHandler(app, lifespan=False) +``` + ## Contact For questions or suggestions, please contact [jack.burridge@mail.com](mailto:jack.burridge@mail.com).