mirror of
https://github.com/nomadkaraoke/karaoke-gen.git
synced 2026-11-20 13:07:57 +09:00
## Summary Two invisible upload failures on the same song led to this: - **Job 8729f19a**: large audio upload (signed-URL flow) abandoned mid-upload. The only UI signal was the "Creating..." button text and the card already said "Setting up", so the job sat `pending` forever with the credit spent. - **Job 2d0c1ae0**: 44 MB instrumental upload on the review screen was a multipart POST through Cloud Run (32 MiB cap) and failed silently. Only the CORS preflight was logged. ## Changes **Shared upload layer (frontend)**: all user uploads now go through one path: - `lib/upload.ts`: signed-URL PUT with progress, sequential multi-file upload with aggregate progress, client-side duration check. - `hooks/useUploadTask.ts`: progress state plus a `beforeunload` guard. - `components/upload/UploadProgressModal.tsx`: a modal the user can't close, showing progress, speed, ETA, "file N of M" and a keep-tab-open warning. - Used by guided job creation, tenant single job and instrumental review. Tenant bulk keeps its per-row table and uses the shared guard. **Guided flow** - Always uses the signed-URL path, which also fixes `requires_audio_edit` being silently dropped for uploads of 25MB or more. - Private upload jobs can attach their own instrumental (`existing_instrumental`). This skips separation and instrumental review. The duration is checked before upload, and the backing-vocals option is hidden. **Instrumental review** - New `instrumental-upload-url` and `instrumental-upload-complete` endpoints: direct-to-GCS upload, then a finalize step. - One shared processing helper with the multipart route: duration check, FLAC conversion, `stems.custom_instrumental`. - Returns a signed `audio_url`. The old post-upload preview URL had no backend route. - Inline error plus toast for mismatches and failures. **Backend robustness** - `state_data.awaiting_upload`: the dashboard shows "Waiting for upload" instead of "Setting up". - The hourly stale-review run also cancels and refunds non-tenant jobs still awaiting upload after 2h with nothing uploaded. - `uploads-complete` now checks ownership (previously any signed-in user could finalize any pending job). On an instrumental duration mismatch it cancels and refunds the job instead of stranding it. ## Testing - `make test`: backend 1839 + 4788 + 150 emulator passed; frontend Jest 1391 passed across 117 suites. - New tests: - backend: stale-upload processor; signed instrumental endpoints (15 cases); `requires_audio_edit` persistence; uploads-complete ownership and cancel-on-mismatch - frontend: upload lib, `useUploadTask`, modal (speed/ETA, can't be dismissed), `OwnInstrumentalField`, `TenantJobFlow`, API flows - Manual check against the real frontend (local dev, prod read-only; create, upload and finalize endpoints mocked, uploads sent to a throttled local PUT server, so no prod data was changed): - guided flow with and without an instrumental - instrumental review upload on 2d0c1ae0, including a mismatch caught before upload - Escape and outside clicks don't close the modal; navigating away triggers the `beforeunload` prompt Plan: `docs/archive/2026-09-26-unified-upload-flow-plan.md` 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2.6 KiB
2.6 KiB
Unified browser upload flow — plan (2026-09-26)
Why
- Job 8729f19a: large audio upload (signed-URL flow) was silently abandoned — the only signal was the "Creating..." button text, and the job card already said "Setting up". The job sat PENDING forever with the credit spent.
- Job 2d0c1ae0: instrumental-review "Alternate Instrumental" upload of a 44 MB WAV failed
invisibly — it's a multipart POST through Cloud Run (32 MiB request cap), no progress, and
the post-upload preview URL (
/api/jobs/{id}/audio-stream/...) has no backend route. - Singer-songwriters with their own instrumental must currently go through vocal separation
- instrumental review;
existing_instrumental(tenant-only in the UI) already skips both.
- instrumental review;
Shared frontend upload layer (DRY)
lib/upload.ts:putFileToSignedUrl(XHR PUT, progress, clear errors),uploadFilesToSignedUrls(sequential multi-file, aggregate progress + current file),getAudioFileDuration(best-effort via<audio>metadata).hooks/useUploadTask.ts: progress state +beforeunloadguard while active;run(fn).components/upload/UploadProgressModal.tsx: non-dismissable modal (progress, speed, ETA, file N of M, keep-tab-open warning); phase labels overridable per caller.- Used by: guided job creation, tenant single job, instrumental review upload.
Tenant bulk keeps its per-row resumable table but uses the shared
beforeunloadhook.
Backend
create-with-upload-urlsaccepts + persistsrequires_audio_edit(was silently dropped).uploads-complete: ownership check; on duration mismatch cancel the job (refund) so it can't be stranded, then return the 400.- Instrumental review:
POST /api/jobs/{id}/instrumental-upload-url→ signed PUT tojobs/{id}/uploads/custom_instrumental_source{ext};POST /api/jobs/{id}/instrumental-upload-complete→ shared processing helper (duration check, FLAC,stems.custom_instrumental) and returns a signedaudio_urlfor playback. Multipart endpoint kept (CLI/back-compat), same helper, also returnsaudio_url. - Previous work:
state_data.awaiting_upload, stale-upload sweep (cancel + refund after 2h).
Guided flow
- Always use the signed-URL path (single code path; gets awaiting-upload label + cleanup).
- Private + uploaded-audio jobs: optional "Use my own instrumental" file on the Customize
step; client-side duration pre-check; sent as
existing_instrumental.
Tests
Backend unit tests for new endpoints/fixes; Jest for upload lib, hook, modal, instrumental selector upload, guided-flow instrumental option; local Playwright run against the real frontend with a throttled PUT server.