Idempotency bug audit: 13 reproduced bugs, issues to be opened after the next release

[leandrodamascena]

Same exercise as #8576, now for the Idempotency utility. I read the whole package, wrote a reproduction for every suspect and ran all of them (in-memory persistence layer, a fake Redis client, and botocore.stub.Stubber for DynamoDB). Everything below reproduces on develop. None has an open issue yet; the two Redis bugs I found earlier are already tracked in #8574 and #8575.

I'm holding these here on purpose: I'll open the individual issues after the next release, so we don't flood the queue while #8577-#8584 and #8586-#8601 are still open. All of them are candidates for good first issue except number 3.

Severity is my call: High gives wrong results or duplicate execution in normal use, Medium breaks a documented feature or leaves bad state behind, Low is an edge case.

---

High

1. Payload validation does not work with the Redis/Cache persistence layer

persistence/redis.py:489 (_update_record)

_update_record rewrites the whole JSON value with only data, status and expiration, dropping the validation hash that _put_in_progress_record stored. On replay _get_record yields payload_hash="", and _validate_payload raises for the same payload.

layer = CachePersistenceLayer(client=fake_redis)
config = IdempotencyConfig(event_key_jmespath="user_id", payload_validation_jmespath="amount")

@idempotent(persistence_store=layer, config=config)
def handler(event, context): return {"ok": True}

handler({"user_id": "u1", "amount": 10}, ctx)  # {'ok': True}
handler({"user_id": "u1", "amount": 10}, ctx)  # IdempotencyValidationError: Payload does not match stored record

The existing test only asserts the tampered-payload path. Fix: write validation_key_attr in _update_record when validation is enabled, like dynamodb.py:312 does. GFI: yes.

2. Falsy results (0, False, "", [], {}) are replayed as None

base.py:274

serialized_response = self.output_serializer.from_dict(response_dict) if response_dict else None uses truthiness. The record is stored correctly (data="0", "[]", "{}"...), only the replay is wrong. #8176 fixed the write side and promised falsy values are returned on replay; the read side still has the old check from #5251.

@idempotent_function(data_keyword_argument="rec", persistence_store=layer)
def f(rec): return {}

f(rec={"id": 1})  # {}
f(rec={"id": 1})  # None

Fix: if response_dict is not None. Add a parametrised replay test for {}, 0, False, "", []. GFI: yes.

3. One persistence layer instance shared by two decorated functions corrupts records and can execute twice

persistence/base.py:95-116 (configure) and base.py:118 (called on every invocation)

configure() overwrites function_name on every call but ignores everything else after the first (if self.configured: return). The docs define one module-level DynamoDBPersistenceLayer and show both decorators, so this pattern is natural:

layer = DynamoDBPersistenceLayer(table_name="t")
config = IdempotencyConfig(event_key_jmespath="order_id")

@idempotent_function(data_keyword_argument="order", persistence_store=layer, config=config)
def process(order): return {"ok": order["order_id"]}

@idempotent(persistence_store=layer, config=config)
def handler(event, context): return process(order={"order_id": event["order_id"] * 10})

handler({"order_id": 1}, ctx)  # ok
handler({"order_id": 1}, ctx)  # IdempotencyAlreadyInProgressError

After the first call the store has INPROGRESS handler#... and COMPLETED process#... twice: the handler's result was saved under the inner function's name. The handler stays INPROGRESS until the in-progress expiry and then runs again. If the inner function raises, delete_record also targets the wrong key. With two unrelated functions and two different IdempotencyConfigs on one layer, the second config (event_key_jmespath, payload_validation_jmespath, expires_after_seconds, use_local_cache) is silently ignored.

Fix: stop keeping per-function state on the layer. Pass function_name/key_prefix from IdempotencyHandler into the key computation, or snapshot the config per handler. At minimum raise when configure() is called with a different config and document "one layer instance per decorated function". This one needs a maintainer. GFI: no.

---

Medium

4. A result that is not JSON serializable leaves the INPROGRESS record behind

base.py:298-305

The function already ran, save_success fails on datetime/set/bytes, the error is wrapped as IdempotencyPersistenceLayerError and the INPROGRESS record is never deleted. Without register_lambda_context there is no in-progress expiry, so the key is locked for expires_after_seconds (1 h default).

@idempotent_function(data_keyword_argument="order", persistence_store=layer)
def h(order): return {"d": datetime(2026, 1, 1)}

h(order={"a": 1})  # IdempotencyPersistenceLayerError: Object of type datetime is not JSON serializable
h(order={"a": 1})  # IdempotencyAlreadyInProgressError

Fix: call delete_record before re-raising when save_success fails, mirroring the exception path. GFI: yes.

5. output_serializer=PydanticSerializer (class form) crashes under from __future__ import annotations

idempotency.py:211 and serialization/pydantic.py:44

function.__annotations__["return"] is a string under PEP 563, and issubclass(str, BaseModel) raises TypeError: issubclass() arg 1 must be a class at decoration time. Same for -> list[Model]. The repo itself uses future annotations everywhere.

from __future__ import annotations

@idempotent_function(data_keyword_argument="order", persistence_store=layer, output_serializer=PydanticSerializer)
def process(order: dict) -> OrderOutput: ...   # TypeError at import

Fix: typing.get_type_hints(function).get("return") in idempotent_function, and an inspect.isclass guard raising IdempotencyModelTypeError. GFI: yes.

6. DataclassSerializer cannot save datetime/UUID fields and does not rebuild nested dataclasses

serialization/dataclass.py:33-37

to_dict returns asdict() unchanged and save_success dumps it with the plain Encoder, which has no datetime/UUID support (same class of bug as #8569, fixed for Pydantic). And from_dict does self.__model(**data), so nested dataclasses come back as dicts on replay.

@dataclass
class Out: id: uuid.UUID; created: datetime
# -> IdempotencyPersistenceLayerError (datetime not JSON serializable), then stuck INPROGRESS (bug 4)

@dataclass
class Order: item: Item; tags: list[Item]
# first call: Order(item=Item(sku='x'), ...)   replay: Order(item={'sku': 'x'}, ...)

Fix: make to_dict produce JSON-safe values and rebuild nested dataclasses from dataclasses.fields() type hints in from_dict, or document the limitation. GFI: yes.

7. DynamoDB composite key: DataRecord.idempotency_key is the static partition key value

persistence/dynamodb.py:165

With sort_key_attr, _item_to_data_record sets idempotency_key=data[self.key_attr], which is static_pk_value for every record. Consequences: the local cache stores every record under the same key so use_local_cache never hits for records written by other containers, the response_hook receives idempotency_key='idempotency#myfn' (the docs example reads it), and the IdempotencyAlreadyInProgressError message shows the static value.

Fix: idempotency_key=data[self.sort_key_attr] if self.sort_key_attr else data[self.key_attr]. GFI: yes.

---

Low

8. A dataclass payload with set/frozenset/bytes fields cannot be hashed

persistence/base.py:41-55

_IdempotencyKeyEncoder handles Enum, date, UUID and Path only. f(p=P(1, {"a"})) fails with IdempotencyPersistenceLayerError: Failed to save in progress record ... Object of type set is not JSON serializable, which reads like a store outage. Fix: encode set/frozenset as a sorted list and bytes as base64. GFI: yes.

9. Redis _orphan_lock_timeout = min(10, expires_after_seconds) is always 10

persistence/redis.py:321

Computed in __init__, before configure() sets expires_after_seconds, so it always sees the 3600 default. With expires_after_seconds=2 the lock outlives the record by 8 s and a request in that window that finds an orphan fails with IdempotencyInconsistentStateError. Fix: compute it in _acquire_lock. GFI: yes.

10. Redis: a record expiring between SET NX and GET fails the invocation instead of retrying

persistence/redis.py:415

_get_record raises IdempotencyItemNotFoundError, which escapes _put_record and is wrapped as IdempotencyPersistenceLayerError. DynamoDB handles the same race through IdempotencyInconsistentStateError and the retry loop. Fix: catch it there and raise IdempotencyInconsistentStateError. GFI: yes.

11. POWERTOOLS_IDEMPOTENCY_DISABLED="" or any non-boolean value crashes every invocation

idempotency.py:109, 219

strtobool("") raises ValueError: invalid truth value ''. "0", "no", "False" work. Fix: treat unparsable values as not disabled. GFI: yes.

12. IdempotencyConfig docstring says local_cache_max_items defaults to 1024; it is 256

config.py. Docs table already says 256. GFI: yes.

---

Not reported as bugs, noting for the record

• Replay type drift with the default serializer in idempotent_function: Decimal("2.5") → "2.5", (1, 2) → [1, 2]. Same as Lambda's own JSON behaviour, but the docs don't warn for function results.
• "", [], {} from event_key_jmespath are treated as "missing key" and skip idempotency with a warning, while the docs only mention None.
• boto3_supports_condition_check_failure raises ValueError on versions like 1.40.0rc1. Source installs only.
• IdempotencyConfig(expires_after_seconds=0) makes Redis reject ex=0; DynamoDB tolerates it. No validation on either side.