Closes FUNCTIONAL_AUDIT.md §4 #1: WebRTC 1:1 calls had working
signaling but no NAT traversal, so calls between two peers behind
symmetric NAT (corporate firewalls, mobile carrier CGNAT, Incus
container default networking) failed silently after the SDP exchange.
Backend:
- GET /api/v1/config/webrtc (public) returns {iceServers: [...]}
built from WEBRTC_STUN_URLS / WEBRTC_TURN_URLS / *_USERNAME /
*_CREDENTIAL env vars. Half-config (URLs without creds, or vice
versa) deliberately omits the TURN block — a half-configured TURN
surfaces auth errors at call time instead of falling back cleanly
to STUN-only.
- 4 handler tests cover the matrix.
Frontend:
- services/api/webrtcConfig.ts caches the config for the page
lifetime and falls back to the historical hardcoded Google STUN
if the fetch fails.
- useWebRTC fetches at mount, hands iceServers synchronously to
every RTCPeerConnection, exposes a {hasTurn, loaded} hint.
- CallButton tooltip warns up-front when TURN isn't configured
instead of letting calls time out silently.
Ops:
- infra/coturn/turnserver.conf — annotated template with the SSRF-
safe denied-peer-ip ranges, prometheus exporter, TLS for TURNS,
static lt-cred-mech (REST-secret rotation deferred to v1.1).
- infra/coturn/README.md — Incus deploy walkthrough, smoke test
via turnutils_uclient, capacity rules of thumb.
- docs/ENV_VARIABLES.md gains a 13bis. WebRTC ICE servers section.
Coturn deployment itself is a separate ops action — this commit lands
the plumbing so the deploy can light up the path with zero code
changes.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two consolidations:
(1) Annotate `/search`, `/search/suggestions`, `/social/trending` with
swag tags so orval generates typed clients for them. Migrate
`searchApi` and `socialApi` (the two remaining hand-written wrappers
in `apps/web/src/services/api/`) to delegate to the generated
functions. Removes the last drift surface where backend changes to
those endpoints could silently mismatch the SPA.
(2) Delete two orphan auth-service implementations that have parallel-
implemented login/register/verifyEmail with stale wire shapes:
- apps/web/src/services/authService.ts (only its own test imports it)
- apps/web/src/features/auth/services/authService.ts (re-exported
from features/auth/index.ts but the barrel itself has zero
importers across the SPA)
The active path remains `services/api/auth.ts` (the integration layer
that owns token storage, csrf, and proactive refresh) — the duplicates
were dead post-v1.0.8 orval migration and silently diverged from the
true backend shape (e.g., the deleted services still expected
`access_token` at the root of the register response, never matched
current backend, broke when v1.0.9 item 1.4 changed the shape).
Net diff: -944 LOC of dead code, +typed orval clients for 2 more
endpoints, zero importer rewires.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Item 1.4 — Register no longer issues an access+refresh token pair. The
prior flow set httpOnly cookies at register but the AuthMiddleware
refused them on every protected route until the user had verified
their email (`core/auth/service.go:527`). Users ended up with dead
credentials and a "logged in but locked out" UX. Register now returns
{user, verification_required: true, message} and the SPA's existing
"check your email" notice fires naturally.
Item 1.3 — `POST /auth/verify-email` reads the token from the
`X-Verify-Token` header in preference to the `?token=…` query param.
Query param logged a deprecation warning but stays accepted so emails
dispatched before this release still work. Headers don't leak through
proxy/CDN access logs that record URL but not headers.
Tests: 18 test files updated (sed `_, _, err :=` → `_, err :=` for the
new Register signature). `core/auth/handler_test.go` gets a
`registerVerifyLogin` helper for tests that exercise post-login flows
(refresh, logout). Two new E2E `@critical` specs lock in the defer-JWT
contract and the header read-path.
OpenAPI + orval regenerated to reflect the new RegisterResponse shape
and the verify-email header parameter.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes the two annotation gaps that blocked finishing the orval
migration in v1.0.8 :
- queue_handler.go (5 routes — GetQueue, UpdateQueue, AddQueueItem,
RemoveQueueItem, ClearQueue) — under @Tags Queue with @Security
BearerAuth, @Param body/path, @Success/@Failure on the standard
APIResponse envelope.
- queue_session_handler.go (5 routes — CreateSession, GetSession,
DeleteSession, AddToSession, RemoveFromSession). GetSession is
public (no @Security tag) since the share-token URL is meant for
join-via-link from outside the auth wall.
- password_reset_handler.go (2 routes — RequestPasswordReset and
ResetPassword factory functions). Both are public (no @Security)
since they're the entry-points for users who can't log in. The
request-side annotation documents the intentional generic 200
response (anti-enumeration: same body whether the email exists or
not).
After regen :
- openapi.yaml gains 7 queue paths (/queue, /queue/items[/{id}],
/queue/session[/{token}[/items[/{id}]]]) and 2 password paths
(/auth/password/reset, /auth/password/reset-request). +568 LOC.
- docs/{docs.go,swagger.json,swagger.yaml} updated identically by
swag init.
- apps/web/src/services/generated/queue/queue.ts created (10
HTTP funcs + matching React Query hooks). model/ index extended
with the queue + password-reset request/response shapes.
Validates with `swag init` (Swagger 2.0). go build ./... clean. No
runtime behaviour change — annotations are pure metadata read by the
spec generator. The orval regen IS the wiring point for the
follow-up frontend commit (queue.ts migration + authService finish).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Fourth batch. Closes the user/profile surface consumed by the
frontend users service. 6 handlers annotated across
internal/handlers/profile_handler.go (now 12/15 annotated).
Handlers annotated:
- SearchUsers — GET /users/search
- FollowUser — POST /users/{id}/follow
- GetFollowSuggestions — GET /users/suggestions
- UnfollowUser — DELETE /users/{id}/follow
- BlockUser — POST /users/{id}/block
- UnblockUser — DELETE /users/{id}/block
Added a blank `_ "veza-backend-api/internal/models"` import so swaggo
can resolve models.User in doc comments without forcing runtime use
(same pattern as track_hls_handler.go / track_waveform_handler.go).
Spec coverage: /users/* paths now 12 (all frontend-consumed endpoints).
make openapi: ✅ · go build ./...: ✅.
Completes the B-2 backend annotation scope for auth / users / tracks /
playlists — the four services that will migrate to orval in the next
commit. Remaining unannotated handlers (admin, moderation, analytics,
education, cloud, gear, social_group, etc.) are outside the v1.0.8
frontend migration and deferred to v1.0.9.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Third batch. Fills the playlist_handler.go gap (was 8/24 annotated,
now 20/24). Covers the functionality consumed by the frontend
playlists service: import, favoris, share tokens, collaborators,
analytics, search, recommendations, duplication.
Handlers annotated:
- ImportPlaylist — POST /playlists/import
- GetFavorisPlaylist — GET /playlists/favoris
- GetPlaylistByShareToken — GET /playlists/shared/{token}
- SearchPlaylists — GET /playlists/search
- GetRecommendations — GET /playlists/recommendations
- GetPlaylistStats — GET /playlists/{id}/analytics
- AddCollaborator — POST /playlists/{id}/collaborators
- GetCollaborators — GET /playlists/{id}/collaborators
- UpdateCollaboratorPermission — PUT /playlists/{id}/collaborators/{userId}
- RemoveCollaborator — DELETE /playlists/{id}/collaborators/{userId}
- CreateShareLink — POST /playlists/{id}/share
- DuplicatePlaylist — POST /playlists/{id}/duplicate
Not annotated (unrouted, survey false positives): FollowPlaylist,
UnfollowPlaylist — no route references in internal/api/routes_*.go.
Left unannotated to avoid polluting the spec with dead handlers.
Marketplace gap originally planned for this batch is deferred to
v1.0.9: the 13 remaining handlers (UploadProductPreview, reviews,
licenses, sell stats, refund, invoice) don't block the B-2 frontend
migration (auth/users/tracks/playlists only), so they will be done
after v1.0.8 ships. Task #48 updated to reflect.
Spec coverage:
/playlists/* paths: 5 → 15
make openapi: ✅ valid
go build ./...: ✅
Next: profile_handler.go + auth/handler.go to finish the B-2 spec
surface (users endpoints), then regen orval and migrate 4 services.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
First batch of the backend OpenAPI annotation campaign. Adds full
swaggo annotations to the 8 handlers in internal/core/track/track_crud_handler.go
so the resulting openapi.yaml exposes the track CRUD surface to
orval-generated frontend clients.
Handlers annotated (all under @Tags Track):
- ListTracks — GET /tracks
- GetTrack — GET /tracks/{id}
- UpdateTrack — PUT /tracks/{id} (Auth, ownership)
- GetLyrics — GET /tracks/{id}/lyrics
- UpdateLyrics — PUT /tracks/{id}/lyrics (Auth, ownership)
- DeleteTrack — DELETE /tracks/{id} (Auth, ownership)
- BatchDeleteTracks — POST /tracks/batch/delete (Auth)
- BatchUpdateTracks — POST /tracks/batch/update (Auth)
Each block follows the established pattern (auth.go + marketplace.go):
Summary / Description / Tags / Accept / Produce / Security when auth-required /
Param (path/query/body) with concrete types / Success envelope typed via
response.APIResponse{data=...} / Failure 400/401/403/404/500 / Router.
make openapi: ✅ valid (Swagger 2.0)
go build ./...: ✅
openapi.yaml: +490 LOC, 8 new paths exposed under /tracks.
Part of the Option B campaign tracked in
/home/senke/.claude/plans/audit-fonctionnel-wild-hickey.md.
~364 handlers total remain unannotated across 16 files in /internal/core/
and ~55 files in /internal/handlers/. Subsequent commits will annotate
one handler file at a time so each regenerated spec stays bisectable.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
