[ASHMEET555]

Issue number: closes #8697

Summary

Adds async coroutine function support to @circuit_breaker. When wrapping an async def function, the decorator now provides an async wrapper that awaits the coroutine inside the circuit breaker's state machine, allowing qualifying failures to be caught and counted towards failure_threshold.

Changes

• In aws_lambda_powertools/utilities/circuit_breaker/circuit_breaker.py:
  • Detect whether the decorated function is a coroutine function with inspect.iscoroutinefunction.
  • Return an async_wrapper for async functions that invokes await handler.handle_async().
  • In development disabled mode (POWERTOOLS_CIRCUIT_BREAKER_DISABLED), await the async function directly.
• In aws_lambda_powertools/utilities/circuit_breaker/base.py:
  • Added handle_async, _call_closed_async, _call_probe_async, and _open_response_async to CircuitBreakerHandler.
  • Awaits the protected call inside the failure and probe handlers to properly transition circuit states.
  • Supports both synchronous and asynchronous on_circuit_open callbacks.
• In tests/functional/circuit_breaker/test_circuit_breaker.py:
  • Added 8 async functional tests covering closed healthy calls, failure threshold tripping to OPEN, sync and async on_circuit_open callbacks, open circuit errors, half-open probe success/failure, and disabled environment bypass.

User experience

Decorating async def functions with @circuit_breaker now tracks failures as expected:

from aws_lambda_powertools.utilities.circuit_breaker import circuit_breaker, CircuitBreakerConfig

config = CircuitBreakerConfig(failure_threshold=2)

@circuit_breaker(name="payment-service", persistence_store=store, config=config)
async def call_payment():
    raise ConnectionError("Service unavailable")

# After 2 awaited failures, the circuit transitions from CLOSED to OPEN:
await call_payment()

Verification

• uv run pytest tests/functional/circuit_breaker/ tests/unit/circuit_breaker/ --cov=aws_lambda_powertools.utilities.circuit_breaker --cov-report=term-missing — 93 passed, 95.01% coverage.
• uv run ruff check aws_lambda_powertools/utilities/circuit_breaker/ tests/functional/circuit_breaker/ — Passed.
• uv run ruff format --check aws_lambda_powertools/utilities/circuit_breaker/ tests/functional/circuit_breaker/ — Passed (14 files already formatted).
• uv run mypy aws_lambda_powertools/utilities/circuit_breaker/ — Passed (no issues found in 10 source files).

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[leandrodamascena]

Thanks @ASHMEET555, good work, and fast. I tested it against a real DynamoDB table: on develop an async def never trips the circuit, with your change it opens on the second failure, awaits the async callback and closes again after the probe.

One thing I changed, and I pushed it to your branch so you can see it: the PR copied handle, _call_closed and _call_probe into async versions, which means two copies of the state machine to keep in sync. I split the routing into a single _route() and moved the bookkeeping into small _on_closed_* / _on_probe_* helpers, so the sync and async paths only differ in the await. Your tests pass unchanged. I also added a short docs section with an async example.

Approving, this goes out in 3.39.0, credit is yours in the release notes.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.00%. Comparing base (13dbc55) to head (6bcc9f3).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #8703      +/-   ##
===========================================
+ Coverage    96.99%   97.00%   +0.01%     
===========================================
  Files          321      321              
  Lines        16332    16415      +83     
  Branches      1473     1482       +9     
===========================================
+ Hits         15841    15924      +83     
  Misses         350      350              
  Partials       141      141              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[leandrodamascena]

@ASHMEET555 I pushed two more commits, take a look when you can.

While testing I noticed the probe owner id lives in thread-local storage. Coroutines share the thread, so when I ran asyncio.gather with 20 calls on a circuit that was due for a probe, all 20 hit the backend and the circuit closed on the first 3 successes. Threads don't have this problem because each one gets its own id.

I fixed it by tracking which circuits have a probe running in the process. The first coroutine probes, the rest get the open response. Added two tests for it. Sync code paths are untouched, I ran the develop test file against the new code to be sure.

[powertools-for-aws-oss-automation]

Awesome work, congrats on your first merged pull request and thank you for helping improve everyone's experience!

[ASHMEET555]

Thank @leandrodamascena! I really appreciate the detailed review, testing against real DynamoDB, and the clean refactoring.

Extracting _route() and the bookkeeping helpers is much cleaner than duplicating the state machine definitely a great pattern for keeping sync/async logic unified.

Also, the catch on thread-local storage with concurrent coroutines in asyncio.gather is fantastic. Because coroutines share the same thread and identical probe owner ID, in-process probe tracking was the exact right fix to prevent probe stampedes while keeping thread isolation intact.

Thanks for refining this and getting it over the finish line for 3.39.0! Looking forward to contributing more.