Potential Thread-Safety Concern with `@cached_property` Usage

[nitish-yaddala]

Description

The headers attribute is decorated with @cached_property, meaning the dictionary of headers is computed lazily and cached.

However, in high-concurrency environments (multi-threaded or async frameworks), caching without proper locking mechanisms could lead to:

• Race conditions,
• Inconsistent header state,
• Unexpected behavior in highly concurrent server setups.

While this may not always occur, explicitly documenting thread-safety assumptions improves robustness and developer awareness.

Affected Code

• headers(self) -> dict[str, str] — Line 216

Recommendation

• Add documentation clearly mentioning thread-safety assumptions around @cached_property usage.
• Optionally, consider using thread-safe lazy evaluation techniques if anticipating concurrent access (e.g., threading.Lock, or thread-safe cached property utilities).

[cak]

Thanks for flagging this.

I looked into it and did not find a true race condition: concurrent first access may compute twice, but the result is deterministic and identical. The real risk was mutability, since returning a dict allowed accidental changes to the cached value.

This will address this in v2.0: headers will return a read-only Mapping[str, str] via MappingProxyType, and the docstring will clarify lazy caching and immutability.

Impact: if code was mutating obj.headers, it will now raise TypeError. If mutation is needed, copy first: d = dict(obj.headers).

[cak]

Reviewed and addressed as part of the v2.0.0rc1 work, including code and documentation updates. If you see a specific remaining issue against the RC, please follow up with a concrete example.