generated from john/python-template
81 lines
3.1 KiB
Markdown
81 lines
3.1 KiB
Markdown
# Ver1 Step 2 Results: Error Handling & Reliability Hardening
|
|
|
|
## Summary
|
|
|
|
Step 2 implementation is complete for the planned reliability and error-handling hardening scope:
|
|
|
|
1. Worker retries are now explicit, bounded, and category-driven.
|
|
2. Error behavior is more consistent across worker/API/UI boundaries.
|
|
3. Logging now includes stronger boundary context in key failure paths.
|
|
4. Test coverage was expanded for retry policy and new reliability settings.
|
|
|
|
## Implemented Changes
|
|
|
|
### 1) Worker retry policy and terminal behavior
|
|
|
|
- Updated `src/transcription/models.py`:
|
|
- Added `Job.retry_count` with default `0`.
|
|
- Updated `src/transcription/config.py`:
|
|
- Added `worker_max_retries`.
|
|
- Added `worker_retry_backoff_seconds`.
|
|
- Updated `src/transcription/worker.py`:
|
|
- Added bounded retry decision path (`_should_retry`).
|
|
- Added requeue behavior (`_requeue_for_retry`) for retriable errors.
|
|
- Added deterministic terminal failure behavior (`_finalize_failed_job`).
|
|
- Preserved transcript failure detail persistence (`error_id`, `category`, suggestion).
|
|
|
|
### 2) API fallback normalization hardening
|
|
|
|
- Updated `src/transcription/api/errors.py`:
|
|
- Fallback handler now emits safe generic internal message for unhandled exceptions.
|
|
- Added structured boundary logging fields including operation and exception type.
|
|
|
|
### 3) UI interaction reliability guard
|
|
|
|
- Updated `src/transcription/ui/upload_page.py`:
|
|
- Added duplicate in-flight submission guard to prevent repeated upload handling while busy.
|
|
|
|
### 4) Observability/logging improvements
|
|
|
|
- Updated worker logs in `src/transcription/worker.py` to include operation and domain identifiers in key transitions:
|
|
- pick
|
|
- retry
|
|
- transcribed
|
|
- failed
|
|
|
|
## Test Coverage Added/Updated
|
|
|
|
- Updated `tests/test_models.py`:
|
|
- Assert `retry_count` default.
|
|
- Updated `tests/test_config.py`:
|
|
- Added worker retry settings default test.
|
|
- Updated `tests/services/test_worker.py`:
|
|
- Added retriable requeue test.
|
|
- Added retry-exhaustion terminal failure test.
|
|
- Updated existing tests for settings-driven worker behavior.
|
|
- Existing API error tests remained green with fallback behavior updates:
|
|
- `tests/api/test_error_responses.py`
|
|
|
|
## Verification Evidence
|
|
|
|
Executed and passing:
|
|
|
|
- `uv run pytest tests/services/test_worker.py tests/test_models.py tests/test_config.py tests/api/test_error_responses.py -q`
|
|
- `uv run pytest -q`
|
|
|
|
## Residual Risks / Follow-ups
|
|
|
|
1. Retry policy currently uses simple fixed backoff; richer strategy (exponential/jitter) can be added in later hardening.
|
|
2. Full cross-layer structured logging standardization can be expanded in Step 6 observability work.
|
|
3. A formal Step 2 error-path inventory artifact (`ver1-step2-audit.md`) is still recommended for governance completeness.
|
|
|
|
## Step 2 Exit Assessment
|
|
|
|
- Error taxonomy and envelope stability: **met**
|
|
- Bounded retry and terminal failure behavior: **met**
|
|
- Worker reliability controls: **met**
|
|
- UI interaction hardening for duplicate actions: **met**
|
|
- Test coverage expansion and full-suite regression safety: **met**
|
|
|
|
Step 2 is complete and ready to hand off to Ver1 Step 3.
|