docs(idempotency): improve navigation, wording, and new section on guarantees (#4613)

* docs(idempotency): cleanup redis usage and link with setup/infra

* docs(idempotency): cleanup idempotent decorator; inline admonitions

Signed-off-by: heitorlessa <[email protected]>

* docs(idempotency): cleanup idempotent_decorator section

Signed-off-by: heitorlessa <[email protected]>

* docs(idempotency): cleanup serialization, fields subset, move batch to new common use cases section

Signed-off-by: heitorlessa <[email protected]>

* docs: cleanup handling exceptions

Signed-off-by: heitorlessa <[email protected]>

* docs: move caching to getting started

* docs: use env var for DDB table, no hardcode

* docs: moved expiration window to getting started; updated example to set to 24h

* docs: include IdempotencyValidationError in example

* Fixing errors on Redis examples

* docs(config): add social links

* docs(idempotency): cleanup intro and key features

* docs(idempotency): cleanup getting started ddb vs redis

* docs(idempotency): break iam permissions into table; IAM permission to clipboard

* docs(idempotency): cleanup dynamodb required resource; break subsections and update nav

* docs(idempotency): make terminologies crispier

Signed-off-by: heitorlessa <[email protected]>

* docs(idempotency): line editing before decorators

Signed-off-by: heitorlessa <[email protected]>

* docs(idempotency): cleanup timeout section

Signed-off-by: heitorlessa <[email protected]>

* docs(idempotency): use cards for required resources

Signed-off-by: heitorlessa <[email protected]>

* docs(idempotency): note to skip timeout section when using handler decorator

Signed-off-by: heitorlessa <[email protected]>

* docs: remove tabbed content for single timeout snippet

Signed-off-by: heitorlessa <[email protected]>

* docs: cleanup persistence layers attrs, snippet titles etc

Signed-off-by: heitorlessa <[email protected]>

* docs: typo in batch integration

Signed-off-by: heitorlessa <[email protected]>

* docs: rename batch integration to actual use case name

Signed-off-by: heitorlessa <[email protected]>

* docs(idempotency): cleanup default behavior section

Signed-off-by: heitorlessa <[email protected]>

* docs: move bold to draw attention to whole event as idempotency key

Signed-off-by: heitorlessa <[email protected]>

* docs: lead with parameter name over config name

* docs: moved composite key under DDB section

* docs: cut unnecessary anchor name

* docs: fix broken links after sections renaming

* Making mypy happy

* docs: fix conflicts out of order

* docs(leandro's feedback): add caching in key features

* Apply suggestions from code review

Co-authored-by: Leandro Damascena <[email protected]>
Signed-off-by: Heitor Lessa <[email protected]>

* docs(leandro's feedback): time window placement

* docs(leandro's feedback): key features success vs failure ambiguity

* docs(leandro's feedback): Redis anchor name

* docs(leandro's feedback): remove ambiguity on Redis VPC connectivity

* Update docs/utilities/idempotency.md

Co-authored-by: Leandro Damascena <[email protected]>
Signed-off-by: Heitor Lessa <[email protected]>

* Update docs/utilities/idempotency.md

Co-authored-by: Leandro Damascena <[email protected]>
Signed-off-by: Heitor Lessa <[email protected]>

* docs: move primary key for both persistence storages plus additional ctx

---------

Signed-off-by: heitorlessa <[email protected]>
Signed-off-by: Heitor Lessa <[email protected]>
Co-authored-by: Leandro Damascena <[email protected]>

Author: heitorlessa

docs/utilities/idempotency.md

@@ -1,11 +1,14 @@
+import os
+
 from aws_lambda_powertools.utilities.idempotency import (
     DynamoDBPersistenceLayer,
     idempotent,
 )
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
+table = os.getenv("IDEMPOTENCY_TABLE", "")
 persistence_layer = DynamoDBPersistenceLayer(
-    table_name="IdempotencyTable",
+    table_name=table,
     key_attr="idempotency_key",
     expiry_attr="expires_at",
     in_progress_expiry_attr="in_progress_expires_at",

examples/idempotency/src/customize_persistence_layer.py

@@ -1,3 +1,5 @@
+import os
+
 from aws_lambda_powertools.utilities.idempotency import (
     idempotent,
 )
@@ -6,8 +8,9 @@
 )
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
+redis_endpoint = os.getenv("REDIS_CLUSTER_ENDPOINT", "localhost")
 persistence_layer = RedisCachePersistenceLayer(
-    host="localhost",
+    host=redis_endpoint,
     port=6379,
     in_progress_expiry_attr="in_progress_expiration",
     status_attr="status",

examples/idempotency/src/customize_persistence_layer_redis.py

@@ -1,3 +1,4 @@
+import os
 from dataclasses import dataclass, field
 from uuid import uuid4
 
@@ -7,7 +8,8 @@
 )
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-persistence_layer = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
+table = os.getenv("IDEMPOTENCY_TABLE", "")
+persistence_layer = DynamoDBPersistenceLayer(table_name=table)
 
 
 @dataclass
@@ -17,8 +19,7 @@ class Payment:
     payment_id: str = field(default_factory=lambda: f"{uuid4()}")
 
 
-class PaymentError(Exception):
-    ...
+class PaymentError(Exception): ...
 
 
 @idempotent(persistence_store=persistence_layer)

examples/idempotency/src/getting_started_with_idempotency.py

@@ -1,3 +1,4 @@
+import os
 from dataclasses import dataclass, field
 from uuid import uuid4
 
@@ -11,8 +12,9 @@
 )
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
+redis_endpoint = os.getenv("REDIS_CLUSTER_ENDPOINT", "localhost")
 client = Redis(
-    host="localhost",
+    host=redis_endpoint,
     port=6379,
     socket_connect_timeout=5,
     socket_timeout=5,
@@ -29,8 +31,7 @@ class Payment:
     payment_id: str = field(default_factory=lambda: f"{uuid4()}")
 
 
-class PaymentError(Exception):
-    ...
+class PaymentError(Exception): ...
 
 
 @idempotent(persistence_store=persistence_layer)

examples/idempotency/src/getting_started_with_idempotency_redis_client.py

@@ -1,3 +1,4 @@
+import os
 from dataclasses import dataclass, field
 from uuid import uuid4
 
@@ -9,7 +10,8 @@
 )
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-persistence_layer = RedisCachePersistenceLayer(host="localhost", port=6379)
+redis_endpoint = os.getenv("REDIS_CLUSTER_ENDPOINT", "localhost")
+persistence_layer = RedisCachePersistenceLayer(host=redis_endpoint, port=6379)
 
 
 @dataclass
@@ -19,8 +21,7 @@ class Payment:
     payment_id: str = field(default_factory=lambda: f"{uuid4()}")
 
 
-class PaymentError(Exception):
-    ...
+class PaymentError(Exception): ...
 
 
 @idempotent(persistence_store=persistence_layer)

examples/idempotency/src/getting_started_with_idempotency_redis_config.py

@@ -1,5 +1,7 @@
-from aws_lambda_powertools import Logger
-from aws_lambda_powertools.utilities.batch import BatchProcessor, EventType
+import os
+from typing import Any, Dict
+
+from aws_lambda_powertools.utilities.batch import BatchProcessor, EventType, process_partial_response
 from aws_lambda_powertools.utilities.data_classes.sqs_event import SQSRecord
 from aws_lambda_powertools.utilities.idempotency import (
     DynamoDBPersistenceLayer,
@@ -8,30 +10,24 @@
 )
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-logger = Logger()
 processor = BatchProcessor(event_type=EventType.SQS)
 
-dynamodb = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
-config = IdempotencyConfig(
-    event_key_jmespath="messageId",  # see Choosing a payload subset section
-)
+table = os.getenv("IDEMPOTENCY_TABLE", "")
+dynamodb = DynamoDBPersistenceLayer(table_name=table)
+config = IdempotencyConfig(event_key_jmespath="messageId")
 
 
 @idempotent_function(data_keyword_argument="record", config=config, persistence_store=dynamodb)
 def record_handler(record: SQSRecord):
     return {"message": record.body}
 
 
-def lambda_handler(event: SQSRecord, context: LambdaContext):
+def lambda_handler(event: Dict[str, Any], context: LambdaContext):
     config.register_lambda_context(context)  # see Lambda timeouts section
 
-    # with Lambda context registered for Idempotency
-    # we can now kick in the Bach processing logic
-    batch = event["Records"]
-    with processor(records=batch, handler=record_handler):
-        # in case you want to access each record processed by your record_handler
-        # otherwise ignore the result variable assignment
-        processed_messages = processor.process()
-        logger.info(processed_messages)
-
-    return processor.response()
+    return process_partial_response(
+        event=event,
+        context=context,
+        processor=processor,
+        record_handler=record_handler,
+    )

examples/idempotency/src/integrate_idempotency_with_batch_processor.py

@@ -1,3 +1,5 @@
+import os
+
 from aws_lambda_powertools.utilities.idempotency import (
     DynamoDBPersistenceLayer,
     IdempotencyConfig,
@@ -6,8 +8,9 @@
 from aws_lambda_powertools.utilities.typing import LambdaContext
 from aws_lambda_powertools.utilities.validation import envelopes, validator
 
+table = os.getenv("IDEMPOTENCY_TABLE", "")
 config = IdempotencyConfig(event_key_jmespath='["message", "username"]')
-persistence_layer = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
+persistence_layer = DynamoDBPersistenceLayer(table_name=table)
 
 
 @validator(envelope=envelopes.API_GATEWAY_HTTP)

examples/idempotency/src/integrate_idempotency_with_validator.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from typing import Any
 
 from redis import Redis
@@ -8,11 +10,11 @@
     RedisCachePersistenceLayer,
 )
 
-redis_values: Any = parameters.get_secret("redis_info", transform="json")  # (1)!
+redis_values: dict[str, Any] = parameters.get_secret("redis_info", transform="json")  # (1)!
 
 redis_client = Redis(
-    host=redis_values.get("REDIS_HOST"),
-    port=redis_values.get("REDIS_PORT"),
+    host=redis_values.get("REDIS_HOST", "localhost"),
+    port=redis_values.get("REDIS_PORT", 6379),
     password=redis_values.get("REDIS_PASSWORD"),
     decode_responses=True,
     socket_timeout=10.0,

examples/idempotency/src/using_redis_client_with_aws_secrets.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from typing import Any
 
 from redis import Redis
@@ -9,12 +11,12 @@
     RedisCachePersistenceLayer,
 )
 
-redis_values: Any = parameters.get_secret("redis_info", transform="json")  # (1)!
+redis_values: dict[str, Any] = parameters.get_secret("redis_info", transform="json")  # (1)!
 
 
 redis_client = Redis(
-    host=redis_values.get("REDIS_HOST"),
-    port=redis_values.get("REDIS_PORT"),
+    host=redis_values.get("REDIS_HOST", "localhost"),
+    port=redis_values.get("REDIS_PORT", 6379),
     password=redis_values.get("REDIS_PASSWORD"),
     decode_responses=True,
     socket_timeout=10.0,