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).