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:
@@ -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**:
|
||||
|
||||
Reference in New Issue
Block a user