TASK-028: Add exception logging to fire-and-forget asyncio.create_task()
- Create logged_task() helper in backend/app/utils/async_utils.py to wrap fire-and-forget coroutines with exception logging - Ensures unhandled task exceptions are always logged to structlog instead of silently discarded (Python 3.11+ RuntimeWarning) - Update ban_service.py to use logged_task() for geo_cache.lookup_batch() background resolution - Add comprehensive tests for logged_task() in test_async_utils.py - Document fire-and-forget task conventions in Backend-Development.md The logged_task() wrapper catches any exception raised in a background task, logs it with full traceback context and task name, and never re-raises. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
@@ -309,6 +309,59 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None]:
|
||||
await app.state.db.close()
|
||||
```
|
||||
|
||||
### Fire-and-Forget Background Tasks
|
||||
|
||||
When you need to spawn a background task that runs independently without waiting for the result, use `asyncio.create_task()` with the `logged_task()` helper from `app.utils.async_utils`. This ensures exceptions in background tasks are always logged and never silently discarded.
|
||||
|
||||
**Why this matters:** In Python 3.11+, unhandled exceptions in fire-and-forget tasks become silent `RuntimeWarning`s. Without logging, background errors (network failures, database writes, API timeouts) become invisible in structured logs and are extremely hard to debug.
|
||||
|
||||
**Pattern:**
|
||||
```python
|
||||
from app.utils.async_utils import logged_task
|
||||
|
||||
# Bad — exceptions are silently discarded
|
||||
asyncio.create_task(some_background_work())
|
||||
|
||||
# Good — exceptions are logged
|
||||
asyncio.create_task(
|
||||
logged_task(some_background_work(), "task_name"),
|
||||
name="task_name",
|
||||
)
|
||||
```
|
||||
|
||||
The `logged_task()` wrapper:
|
||||
- Wraps your coroutine to catch any exception
|
||||
- Logs the exception with `log.exception()` (structlog automatically captures the traceback)
|
||||
- Adds `task_name` to the structured log context
|
||||
- Never re-raises — it's safe to use with `asyncio.create_task()`
|
||||
|
||||
Example:
|
||||
```python
|
||||
import asyncio
|
||||
from app.utils.async_utils import logged_task
|
||||
import structlog
|
||||
|
||||
log = structlog.get_logger()
|
||||
|
||||
async def geo_lookup_batch(ips: list[str]) -> None:
|
||||
"""Look up geolocation data for IPs asynchronously."""
|
||||
try:
|
||||
for ip in ips:
|
||||
# May timeout, fail network call, or fail DB write
|
||||
location = await lookup_ip_location(ip)
|
||||
await db.execute(INSERT_GEO_SQL, (ip, location))
|
||||
await db.commit()
|
||||
except Exception:
|
||||
# All exceptions are automatically logged by logged_task() wrapper
|
||||
raise
|
||||
|
||||
# In your request handler or service:
|
||||
asyncio.create_task(
|
||||
logged_task(geo_lookup_batch(uncached_ips), "geo_cache_batch"),
|
||||
name="geo_cache_batch",
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6.1 Database Query Conventions
|
||||
|
||||
@@ -1,36 +1,3 @@
|
||||
## TASK-027 — Debug compose hardcodes a publicly known weak session secret
|
||||
|
||||
**Severity:** Medium
|
||||
|
||||
### Where found
|
||||
`Docker/compose.debug.yml` line ~63:
|
||||
```yaml
|
||||
BANGUI_SESSION_SECRET: "${BANGUI_SESSION_SECRET:-dev-secret-do-not-use-in-production}"
|
||||
```
|
||||
|
||||
### Why this is needed
|
||||
The fallback value `dev-secret-do-not-use-in-production` is now publicly visible in the repository. If `compose.debug.yml` is used in any environment where `BANGUI_SESSION_SECRET` is not set (e.g., a CI environment or a staging server that uses the debug compose file), all session tokens can be forged by anyone who has seen this repository.
|
||||
|
||||
### Goal
|
||||
Remove the insecure default. Require the secret to be set explicitly before the container starts.
|
||||
|
||||
### What to do
|
||||
1. Change to `BANGUI_SESSION_SECRET: "${BANGUI_SESSION_SECRET:?BANGUI_SESSION_SECRET must be set — generate with: python -c 'import secrets; print(secrets.token_hex(32))'}"`.
|
||||
2. Create a `.env.example` file at the project root with placeholder values and generation instructions.
|
||||
3. Add `.env` to `.gitignore` (verify it is already there).
|
||||
|
||||
### Possible traps and issues
|
||||
- This will break `docker compose -f Docker/compose.debug.yml up` without a `.env` file. Add a clear error message and setup instructions to the README or `Instructions.md`.
|
||||
- `docker-compose.yml` (the legacy file) already uses the `:?` pattern — follow the same approach.
|
||||
|
||||
### Docs changes needed
|
||||
- `Instructions.md` — add first-run setup instructions for the `.env` file.
|
||||
|
||||
### Doc references
|
||||
- [Instructions.md](Instructions.md) — developer setup
|
||||
|
||||
---
|
||||
|
||||
## TASK-028 — Fire-and-forget `asyncio.create_task()` silently discards exceptions
|
||||
|
||||
**Severity:** Low
|
||||
|
||||
Reference in New Issue
Block a user