0e7097ed1b
First-attempt commit3a5c6e184only captured the .gitignore change; the pre-commit hook silently dropped the 343 staged moves/deletes during lint-staged's "no matching task" path. This commit re-applies the intended J1 content on top ofbec75f143(which was pushed in parallel). Uses --no-verify because: - J1 only touches .md/.json/.log/.png/binaries — zero code that would benefit from lint-staged, typecheck, or vitest - The hook demonstrated it corrupts pure-rename commits in this repo - Explicitly authorized by user for this one commit Changes (343 total: 169 deletions + 174 renames): Binaries purged (~167 MB): - veza-backend-api/{server,modern-server,encrypt_oauth_tokens,seed,seed-v2} Generated reports purged: - 9 apps/web/lint_report*.json (~32 MB) - 8 apps/web/tsc_*.{log,txt} + ts_*.log (TS error snapshots) - 3 apps/web/storybook_*.json (1375+ stored errors) - apps/web/{build_errors*,build_output,final_errors}.txt - 70 veza-backend-api/coverage*.out + coverage_groups/ (~4 MB) - 3 veza-backend-api/internal/handlers/*.bak Root cleanup: - 54 audit-*.png (visual regression baselines, ~11 MB) - 9 stale MVP-era scripts (Jan 27, hardcoded v0.101): start_{iteration,mvp,recovery}.sh, test_{mvp_endpoints,protected_endpoints,user_journey}.sh, validate_v0101.sh, verify_logs_setup.sh, gen_hash.py Session docs archived (not deleted — preserved under docs/archive/): - 78 apps/web/*.md → docs/archive/frontend-sessions-2026/ - 43 veza-backend-api/*.md → docs/archive/backend-sessions-2026/ - 53 docs/{RETROSPECTIVE_V,SMOKE_TEST_V,PLAN_V0_,V0_*_RELEASE_SCOPE, AUDIT_,PLAN_ACTION_AUDIT,REMEDIATION_PROGRESS}*.md → docs/archive/v0-history/ README.md and CONTRIBUTING.md preserved in apps/web/ and veza-backend-api/. Note: The .gitignore rules preventing recurrence were already pushed in3a5c6e184and remain in place — this commit does not modify .gitignore. Refs: AUDIT_REPORT.md §11
37 lines
2.1 KiB
Markdown
37 lines
2.1 KiB
Markdown
# API Stabilization Report
|
|
|
|
## Executive Summary
|
|
Phase 4 focused on stabilizing the core API handlers by replacing brittle error handling logic with robust sentinel errors, ensuring consistency across services, and verifying cross-layer interactions with micro-E2E tests.
|
|
|
|
## Key Accomplishments
|
|
|
|
### 1. Handler Audits & Repairs
|
|
- **PlaylistHandler**: Replaced string literal checks (`"playlist not found"`) with sentinel errors (`services.ErrPlaylistNotFound`).
|
|
- **BitrateHandler**: Standardized error responses to use `services.ErrInvalidTrackID`, `ErrInvalidBitrate`, etc.
|
|
- **CommentHandler**: Implemented specific error codes (404, 403) for `ErrCommentNotFound`, `ErrParentCommentNotFound`, `ErrForbidden`.
|
|
- **RoomHandler**: Fixed "Blind 404" issue where internal errors were masked. Now distinguishes `ErrRoomNotFound` from other errors.
|
|
|
|
### 2. Service Layer Refactoring
|
|
- **Centralized Errors**: Created `internal/services/errors.go` to consolidate common errors and prevent duplication.
|
|
- **Updated Services**: `PlaylistService`, `BitrateAdaptationService`, `CommentService`, `RoomService` now return consistent, exported sentinel errors wrapping low-level DB errors.
|
|
|
|
### 3. Verification & Testing
|
|
- **Unit/Integration Tests**: Updated all affected service and handler tests to assert new error types.
|
|
- **Micro-E2E Test Suite**: Created `internal/handlers/api_flow_test.go` (`TestAPIFlow_UserJourney`) simulating a complete user session:
|
|
1. Artist uploads Track.
|
|
2. Listener streams (Bitrate Adaptation).
|
|
3. Listener comments on Track.
|
|
4. Artist replies.
|
|
5. Listener attempts unauthorized delete (Fail).
|
|
6. Listener creates Playlist and adds Track.
|
|
|
|
## Status Checklist
|
|
- [x] All defined handlers audit for HTTP semantics.
|
|
- [x] Brittle string matching replaced with `errors.Is`.
|
|
- [x] Cross-layer error consistency verified.
|
|
- [x] Regression testing via E2E flow.
|
|
|
|
## Recommendations for Phase 5 (Frontend Integration)
|
|
- The API is now stable and returns predictable error codes (400, 401, 403, 404).
|
|
- Frontend clients should handle `403` for permission issues specifically.
|
|
- `404` reliably indicates resource missing, not internal error.
|