Compare commits

...
Author SHA1 Message Date
Andrew BeveridgeandClaude Opus 4.5 c0e86a0302 docs: Add GCS path lessons and update E2E spec for testmail.app
- Add "GCS Blob Paths vs Full URIs" section to LESSONS-LEARNED.md
  documenting the path format confusion bug and double-slash gotcha
- Update E2E-HAPPY-PATH-TEST-SPEC.md secrets section to reflect
  testmail.app migration (was still referencing old names)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-03 17:53:03 -05:00
2 changed files with 53 additions and 7 deletions

No files matched your search

+10 -7
View File
@@ -18,14 +18,16 @@
- [ ] Navigate to landing page (`gen.nomadkaraoke.com`)
- [ ] Click "Sign In" or "Get Started" button
- [ ] Create a NEW testmail.app inbox (fresh email address for each test run)
- [ ] Generate a unique test email address (testmail.app namespace)
- [ ] Enter the test email in the beta enrollment form
- [ ] Submit the form
- [ ] Wait for welcome/magic-link email in testmail.app inbox
- [ ] Wait for welcome/magic-link email via testmail.app API
- [ ] Extract the magic link from the email
- [ ] Click/navigate to the magic link to authenticate
- [ ] Verify user is logged in and has credits
**Note**: When `use_test_token=true` workflow input is set, steps 1-9 above are skipped and the test uses a pre-authenticated token instead.
### 2. Create Karaoke Job (UI Only)
- [ ] Navigate to the karaoke creation page
@@ -118,9 +120,10 @@
### Environment Variables
```bash
TESTMAIL_API_KEY=xxx # Required - for email testing
TESTMAIL_NAMESPACE=xxx # Required - testmail.app namespace
# No pre-auth tokens - test handles full signup
TESTMAIL_NAMESPACE=xxx # Required - for email testing (testmail.app)
TESTMAIL_API_KEY=xxx # Required - for email testing (testmail.app)
E2E_TEST_TOKEN=xxx # Optional - skip signup, use existing account
# When use_test_token=true, skips email signup and uses pre-authenticated token
```
### Test Song
@@ -161,8 +164,8 @@ Log detailed progress at each step with timestamps for debugging.
### Secrets Required
- `TESTMAIL_API_KEY` - For email testing
- `TESTMAIL_NAMESPACE` - testmail.app namespace
- `TESTMAIL_API_KEY` - For email testing (testmail.app)
- `TESTMAIL_NAMESPACE` - testmail.app namespace for unique email addresses
### Workflow Steps
+43
View File
@@ -795,6 +795,49 @@ input_files = [f for f in input_files if "outputs" not in str(f)]
**Lesson**: When writing code that processes files downloaded from GCS, always use recursive glob patterns and verify the expected directory structure matches what's actually stored.
### GCS Blob Paths vs Full URIs
**Problem**: When uploading files to GCS and returning paths to other services, there's confusion between "blob paths" (just the path within a bucket) and "full GCS URIs" (gs://bucket/path).
**Symptoms**:
- 404 errors when downloading files that were just uploaded
- Paths look like: `bucket/gs://bucket/path/file.mp4` (doubled prefix)
- Storage service prepends bucket name to what's already a full URI
**Example of the bug**:
```python
# GCE worker uploads to gs://bucket/jobs/id/encoded/
# Then returns full URI in response: "gs://bucket/jobs/id/encoded/file.mp4"
# Backend tries: storage.download_file("gs://bucket/jobs/id/encoded/file.mp4")
# Storage service prepends bucket: "bucket/gs://bucket/jobs/id/encoded/file.mp4"
# Result: 404 - No such object
```
**Solution**: Return blob paths (path within bucket), not full GCS URIs:
```python
# output_gcs_path = "gs://bucket/jobs/id/encoded/"
gcs_path = output_gcs_path.replace("gs://", "")
parts = gcs_path.split("/", 1)
bucket = parts[0]
prefix = parts[1].rstrip("/") if len(parts) > 1 else ""
# Return blob paths like: "jobs/id/encoded/file.mp4"
blob_path = f"{prefix}/{filename}" if prefix else filename
```
**Related gotcha**: Double slashes in paths. When the prefix already ends with "/" and you concatenate with another "/":
```python
# BAD - creates "encoded//file.mp4"
prefix = "jobs/id/encoded/" # Has trailing slash
blob_name = f"{prefix}/{filename}" # Adds another slash
# GOOD - strip trailing slash first
prefix = parts[1].rstrip("/")
blob_name = f"{prefix}/{filename}" if prefix else filename
```
**Lesson**: When building systems that pass GCS paths between services, establish a clear contract: either always use full URIs (`gs://bucket/path`) or always use blob paths (`path/within/bucket`). Document which format each API expects.
### Library Caches Need GCS Sync in Cloud Run
**Problem**: Libraries like LyricsTranscriber cache API responses to local directories (e.g., `~/lyrics-transcriber-cache`). In Cloud Run, each container is ephemeral - the cache is lost on every restart or scale-up, causing redundant API calls.