Skip to content

Commit bfe7563

Browse files
heitorlessaheitorlessa
committed
docs(idempotency): cleanup intro and key features
1 parent 8f6250d commit bfe7563

File tree

1 file changed

+21
-23
lines changed

1 file changed

+21
-23
lines changed

‎docs/utilities/idempotency.md

+21-23
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,14 @@ description: Utility
55

66
<!-- markdownlint-disable MD051 -->
77

8-
The idempotency utility provides a simple solution to convert your Lambda functions into idempotent operations which are safe to retry.
8+
The idempotency utility allows you to retry operations with the same input within a time window, producing the same output.
99

1010
## Key features
1111

12-
* Prevent Lambda handler from executing more than once on the same event payload during a time window
13-
* Ensure Lambda handler returns the same result when called with the same payload
14-
* Select a subset of the event as the idempotency key using JMESPath expressions
15-
* Set a time window in which records with the same payload should be considered duplicates
16-
* Expires in-progress executions if the Lambda function times out halfway through
17-
* Support Amazon DynamoDB and Redis as persistence layers
12+
* Produces the same result when a function is called repeatedly with the same idempotency key
13+
* Choose your idempotency key from one or more fields, or entire payload
14+
* Safeguard concurrent requests, timeouts, missing idempotency keys, and payload tampering
15+
* Support for Amazon DynamoDB, Redis, and bring your own persistence layer
1816

1917
## Terminology
2018

@@ -73,7 +71,7 @@ We currently support Amazon DynamoDB and Redis as a storage layer. The following
7371
If you're not [changing the default configuration for the DynamoDB persistence layer](#dynamodbpersistencelayer), this is the expected default configuration:
7472

7573
| Configuration | Value | Notes |
76-
| ------------------ | ------------ |-------------------------------------------------------------------------------------|
74+
| ------------------ | ------------ | ----------------------------------------------------------------------------------- |
7775
| Partition key | `id` | |
7876
| TTL attribute name | `expiration` | This can only be configured after your table is created if you're using AWS Console |
7977

@@ -379,12 +377,12 @@ This persistence layer is built-in, allowing you to use an existing Redis servic
379377

380378
When using Redis as the persistence layer, you can customize the attribute names by providing the following parameters upon initialization of the persistence layer:
381379

382-
| Parameter | Required | Default | Description |
383-
| --------------------------- | ------------------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------- |
384-
| **in_progress_expiry_attr** | | `in_progress_expiration` | Unix timestamp of when record expires while in progress (in case of the invocation times out) |
385-
| **status_attr** | | `status` | Stores status of the Lambda execution during and after invocation |
386-
| **data_attr** | | `data` | Stores results of successfully executed Lambda handlers |
387-
| **validation_key_attr** | | `validation` | Hashed representation of the parts of the event used for validation |
380+
| Parameter | Required | Default | Description |
381+
| --------------------------- | -------- | ------------------------ | --------------------------------------------------------------------------------------------- |
382+
| **in_progress_expiry_attr** | | `in_progress_expiration` | Unix timestamp of when record expires while in progress (in case of the invocation times out) |
383+
| **status_attr** | | `status` | Stores status of the Lambda execution during and after invocation |
384+
| **data_attr** | | `data` | Stores results of successfully executed Lambda handlers |
385+
| **validation_key_attr** | | `validation` | Hashed representation of the parts of the event used for validation |
388386

389387
### Idempotency request flow
390388

@@ -733,15 +731,15 @@ For advanced configurations, such as setting up SSL certificates or customizing
733731

734732
Idempotent decorator can be further configured with **`IdempotencyConfig`** as seen in the previous example. These are the available options for further configuration
735733

736-
| Parameter | Default | Description |
737-
|---------------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
738-
| **event_key_jmespath** | `""` | JMESPath expression to extract the idempotency key from the event record using [built-in functions](./jmespath_functions.md#built-in-jmespath-functions){target="_blank"} |
739-
| **payload_validation_jmespath** | `""` | JMESPath expression to validate whether certain parameters have changed in the event while the event payload |
740-
| **raise_on_no_idempotency_key** | `False` | Raise exception if no idempotency key was found in the request |
741-
| **expires_after_seconds** | 3600 | The number of seconds to wait before a record is expired |
742-
| **use_local_cache** | `False` | Whether to locally cache idempotency results |
743-
| **local_cache_max_items** | 256 | Max number of items to store in local cache |
744-
| **hash_function** | `md5` | Function to use for calculating hashes, as provided by [hashlib](https://docs.python.org/3/library/hashlib.html){target="_blank" rel="nofollow"} in the standard library. |
734+
| Parameter | Default | Description |
735+
| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
736+
| **event_key_jmespath** | `""` | JMESPath expression to extract the idempotency key from the event record using [built-in functions](./jmespath_functions.md#built-in-jmespath-functions){target="_blank"} |
737+
| **payload_validation_jmespath** | `""` | JMESPath expression to validate whether certain parameters have changed in the event while the event payload |
738+
| **raise_on_no_idempotency_key** | `False` | Raise exception if no idempotency key was found in the request |
739+
| **expires_after_seconds** | 3600 | The number of seconds to wait before a record is expired |
740+
| **use_local_cache** | `False` | Whether to locally cache idempotency results |
741+
| **local_cache_max_items** | 256 | Max number of items to store in local cache |
742+
| **hash_function** | `md5` | Function to use for calculating hashes, as provided by [hashlib](https://docs.python.org/3/library/hashlib.html){target="_blank" rel="nofollow"} in the standard library. |
745743
| **response_hook** | `None` | Function to use for processing the stored Idempotent response. This function hook is called when an existing idempotent response is found. See [Manipulating The Idempotent Response](idempotency.md#manipulating-the-idempotent-response) |
746744

747745
### Handling concurrent executions with the same payload

0 commit comments

Comments
 (0)