fix(circuit_breaker): address review feedback

- Make the counter race test catch a missing lock: park readers mid-increment so an unsynchronized read-modify-write deterministically loses updates (fails 10/10 unlocked, passes 10/10 locked)
- Document that on_circuit_open and on_transition callbacks can run concurrently and must be thread-safe
- Use dict.get's default instead of `or` for the per-circuit settings lookup

Author: Iamrodos

aws_lambda_powertools/utilities/circuit_breaker_alpha/persistence/base.py

@@ -100,7 +100,7 @@ def configure(self, config: CircuitBreakerConfig, circuit_name: str) -> None:
     def _settings_for(self, name: str) -> _CircuitSettings:
         """Return a circuit's configured settings, or the defaults if never configured."""
         with self._lock:
-            return self._settings.get(name) or _DEFAULT_SETTINGS
+            return self._settings.get(name, _DEFAULT_SETTINGS)
 
     # ------------------------------------------------------------------ cache
 

docs/utilities/circuit_breaker.md

@@ -186,13 +186,16 @@ After `recovery_timeout` seconds, the circuit moves to `HALF_OPEN` and elects a
 !!! note "Thread safety"
     The utility is safe to share across threads: within a multi-threaded environment the probe election picks a single
     thread, so the single-prober guarantee spans threads as well as environments, and the in-memory failure counter is
-    synchronized. Single-threaded functions (the normal Lambda model) are unaffected. `on_circuit_open` and
-    `on_transition` hooks may run concurrently from multiple threads.
+    synchronized. Single-threaded functions (the normal Lambda model) are unaffected.
 
     Probe ownership belongs to the thread that won the election. If that thread never runs the circuit again (for
     example, a thread-per-request worker pool), recovery waits for the probe lease to expire before another thread or
     environment takes over.
 
+!!! warning "Make your hooks thread-safe"
+    If your function runs multiple threads, `on_circuit_open` and `on_transition` callbacks can run concurrently
+    for the same circuit. Make them thread-safe.
+
 ### State coordination across environments
 
 The consecutive-failure counter lives in memory per execution environment, so a healthy circuit performs **no writes**. Only when an environment reaches `failure_threshold` does it persist `OPEN`. The shared state is cached locally for `local_cache_max_age` seconds to avoid a read per invocation. A cache miss (cold start or expired entry) forces a read-through before routing.

tests/functional/circuit_breaker_alpha/test_circuit_breaker.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import threading
+import time
 import warnings
 
 import pytest
@@ -680,8 +681,26 @@ def worker():
     assert store.db["c"].half_open_owner is not None
 
 
-def test_threads_trip_at_exactly_the_failure_threshold(store):
+class _RacyCounters(dict):
+    """Counter dict that yields between the read and the write of an increment.
+
+    Without this, the GIL makes the unlocked read-modify-write effectively atomic
+    (the interpreter rarely switches threads inside those few bytecodes), so a
+    missing lock would still pass. Holding every reader mid-increment long enough
+    for its siblings to read the same stale value makes the lost update
+    deterministic: unlocked, all threads write back the same count and the
+    threshold is never reached.
+    """
+
+    def get(self, key, default=None):
+        value = super().get(key, default)
+        time.sleep(0.005)  # park mid-increment so sibling threads read the same stale value
+        return value
+
+
+def test_threads_trip_at_exactly_the_failure_threshold(store, monkeypatch):
     """Racing increments must neither lose updates (tripping late) nor persist the trip twice."""
+    monkeypatch.setattr(base_module, "_LOCAL_FAILURES", _RacyCounters())
     threads_count, threshold = 8, 5
     config = CircuitBreakerConfig(failure_threshold=threshold, local_cache_max_age=0)
     barrier = threading.Barrier(threads_count)