Refactor config loading and add status code docs

- Move config loading to dedicated ConfigLoader class with validation
- Add DATABASE_MIGRATIONS.md content to TROUBLESHOOTING.md
- Add API_STATUS_CODES.md documenting all API response codes
- Update runner.csx to use new config structure
- Add check_responses.py validation script
- Update config tests for new structure

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
2026-05-03 11:52:01 +02:00
parent 8f26776bb3
commit 7b93499551
9 changed files with 1249 additions and 415 deletions

View File

@@ -1,94 +1,3 @@
### Issue #16: MEDIUM - Silent Failures in Error Handling (Broad Exception Handlers)
**Where found**:
- `backend/app/routers/config_misc.py` (line 54) - `except Exception:`
- `backend/app/ban_service.py` - Multiple broad exception handlers
- Silent failures hide programming errors
**Why this is needed**:
Broad `except Exception:` catches programming errors (AttributeError, KeyError) alongside legitimate errors, hiding bugs in logs.
**Goal**:
Catch only specific exceptions; let programming errors bubble up to global error handler.
**What to do**:
1. Replace broad handlers with specific exceptions:
```python
try:
config = parse_config(raw_text)
except ConfigParseError as e: # Specific
logger.error(f"Config parse failed: {e}")
except FileNotFoundError as e:
logger.error(f"Config file not found: {e}")
except Exception as e:
logger.exception("Unexpected error parsing config")
raise # Re-raise to global handler
```
2. Create domain-specific exception classes
3. Document what exceptions each function can raise
4. Update tests to verify exception handling
**Possible traps and issues**:
- Missing exception types will let errors bubble up unexpectedly
- Catching too few exceptions leads to uncaught errors
- Global exception handler needed to catch unhandled exceptions
**Docs changes needed**:
- Add exception handling guidelines to dev docs
- Create exception taxonomy document
**Doc references**:
- DETAILED_FINDINGS.md - Issue #16 "Broad Exception Handlers"
---
### Issue #17: MEDIUM - No API Response Status Code Documentation
**Where found**:
- All routers lack OpenAPI `responses={}` documentation
- Status codes for success/failure not documented
- Frontend must infer from response body
**Why this is needed**:
Frontend doesn't know:
- Is 400 a validation error or configuration error?
- Is 502 from backend or fail2ban?
- Which 503 status means setup incomplete vs fail2ban down?
**Goal**:
Document all possible status codes and response formats for each endpoint.
**What to do**:
1. Add to each router endpoint:
```python
@router.post(
"/login",
responses={
200: {"description": "Login successful", "model": LoginResponse},
400: {"description": "Invalid request format"},
401: {"description": "Invalid password"},
429: {"description": "Too many attempts, retry after 60s"},
503: {"description": "Setup not complete"},
}
)
```
2. Generate OpenAPI schema with descriptions
3. Update API docs with status code reference table
4. Validate in CI that all endpoints documented
**Possible traps and issues**:
- Documentation might become stale as code changes
- Multiple response types for single status code (must document each)
**Docs changes needed**:
- Create API reference documenting all status codes
- Add endpoint documentation template
**Doc references**:
- DATABASE_API_DEPLOYMENT_ISSUES.md - Issue "2.3 Missing Status Code Documentation"
---
### Issue #18: MEDIUM - Configuration Validation Missing at Startup
**Where found**: