---
name: kotlin-coroutines
description: Coroutine usage guardrails for Kotlin backend reviewers
license: MIT
---

## Mission
- Preserve non-blocking performance characteristics by enforcing clear coroutine boundaries.
- Prevent thread pool exhaustion, deadlocks, and latency spikes caused by mixing blocking and suspend flows.

## Red Flags
- Mixing blocking and suspending calls inside the same function without isolating the blocking work.
- Calling `runBlocking` anywhere other than top-level entrypoints (resources, `main`) or when explicitly bridging to blocking code with the correct dispatcher.
- Using `async { ... }.await()` immediately, or using `async` just to change dispatchers.
- Wiring `AsyncResponse` (Dropwizard) to wrap blocking DAO calls instead of true suspend flows.

## Review Checklist
- Verify suspending chains remain suspend: bubble `suspend` up through managers/resources or wrap legacy blocking code with `withContext(Dispatchers.IO)`.
- Ensure blocking functions stay blocking all the way up the call stack; prefer dedicated blocking helpers (e.g., `getUserBlocking`) rather than ad-hoc `runBlocking`.
- When bridging to suspend from non-suspend contexts, check the dispatcher passed to `runBlocking` matches the underlying workload (usually `Dispatchers.IO`).
- Confirm `AsyncResponse` is only applied to non-blocking suspend flows (Cosmos, service clients with `await`/`executeAwait`). Flag usages that simply wrap JDBI or other blocking calls.
- Look for nested coroutine builders. Replace `async/await` pairs used sequentially with direct calls; use concurrent `async` only when awaiting later.
- Ensure dispatcher changes use `withContext`, not `async`, and that blocking calls inside suspend functions are guarded with the appropriate context.

## Tooling Tips
- `Grep` for `runBlocking`, `.await()`, `executeSync`, or `AsyncResponse` to inspect how coroutines and blocking APIs mix.
- `Read` affected managers/resources to trace whether suspend functions bubble correctly.
- `Glob` modules like `*Manager.kt`, `*Resource.kt`, and `*Dao.kt` when you need broader context about call chains.