fix(convex): move playback state and avatars off the users document #100

Merged
joshuafhiggins merged 2 commits from t3/split-users-document into main 2026-11-16 21:56:01 -05:00
Owner

The users document held the playback queue, history, progress and a base64 avatar. Progress was saved about every 5 seconds, which reran every query that reads the user (currentUser, favorites, sidebar playlists, playback state) and resent the avatar each time. Queues from "play all songs" on a large library also went over Convex's 8,192 array limit, and the client retried the failed sync forever.

Changes

  • Playback tables. The queue, history, shuffle and repeat settings and the revision move into playbackStates. Progress moves into playbackProgress. getPlaybackState no longer reads progress, so progress saves only rerun getSongProgress. Clients fetch progress once when they adopt a new server queue. currentSongProgress stays in the response as 0 so older app builds keep working.
  • Avatars. Avatars now live in Convex file storage, capped at 2 MB. updateProfileImage keeps the same data URL API and moves the image into storage in the background. currentUser.image is now /api/user/<id>/avatar?v=<storageId>. A new web route proxies that path from Convex storage and resizes the image to 256px. Mobile resolves the path against the server URL.
  • Limits. The server caps queues at 5,000 songs and the client store applies the same cap. After its backoff runs out, the client stops retrying a rejected sync.
  • Migration. migrations:migrateUsers copies the legacy fields into the new tables, clears them from users, and moves data URL avatars into storage. It is idempotent and the Docker entrypoint runs it after each deploy. Until it runs, reads fall back to the legacy fields, and the first write migrates that user.
  • Deleting a user now also deletes their playback rows and avatar file.

Favorites stay as arrays on users. A parallel thread is reworking favorites updates, and they change rarely, so moving them is left as a follow-up.

Verification

All checks ran on a throwaway local Convex backend. I deployed main, seeded legacy data (9,000 songs; a user with a queue, progress and a data URL avatar; a user with an 8,000-song queue; a fresh user), then deployed this branch.

  • Before migrating, reads fell back to the legacy fields correctly. Migration moved all fields, cleared them from users and stored the avatar. A re-run made no changes.
  • An 8,000-song sync was stored as 5,000. Pagination, add-to-queue and shuffle on that queue still worked. Arrays over 8,192 are rejected when arguments are validated, and the client cap keeps it from sending them.
  • Subscription check: 5 progress saves caused 0 reruns of currentUser, getPlaybackState and getQueueHistory, and 5 reruns of getSongProgress.
  • Avatar upload, replace (the old file is deleted), the size cap and removal all worked.
  • pnpm -r typecheck passes.

The migration was tested on seeded data, not on a copy of a production database.


Changes made by Claude Opus 5.5 (claude-opus-5-5) running in Claude Code via T3 Code.

🤖 Generated with Claude Code

The `users` document held the playback queue, history, progress and a base64 avatar. Progress was saved about every 5 seconds, which reran every query that reads the user (`currentUser`, favorites, sidebar playlists, playback state) and resent the avatar each time. Queues from "play all songs" on a large library also went over Convex's 8,192 array limit, and the client retried the failed sync forever. ## Changes - **Playback tables.** The queue, history, shuffle and repeat settings and the revision move into `playbackStates`. Progress moves into `playbackProgress`. `getPlaybackState` no longer reads progress, so progress saves only rerun `getSongProgress`. Clients fetch progress once when they adopt a new server queue. `currentSongProgress` stays in the response as `0` so older app builds keep working. - **Avatars.** Avatars now live in Convex file storage, capped at 2 MB. `updateProfileImage` keeps the same data URL API and moves the image into storage in the background. `currentUser.image` is now `/api/user/<id>/avatar?v=<storageId>`. A new web route proxies that path from Convex storage and resizes the image to 256px. Mobile resolves the path against the server URL. - **Limits.** The server caps queues at 5,000 songs and the client store applies the same cap. After its backoff runs out, the client stops retrying a rejected sync. - **Migration.** `migrations:migrateUsers` copies the legacy fields into the new tables, clears them from `users`, and moves data URL avatars into storage. It is idempotent and the Docker entrypoint runs it after each deploy. Until it runs, reads fall back to the legacy fields, and the first write migrates that user. - Deleting a user now also deletes their playback rows and avatar file. Favorites stay as arrays on `users`. A parallel thread is reworking favorites updates, and they change rarely, so moving them is left as a follow-up. ## Verification All checks ran on a throwaway local Convex backend. I deployed `main`, seeded legacy data (9,000 songs; a user with a queue, progress and a data URL avatar; a user with an 8,000-song queue; a fresh user), then deployed this branch. - Before migrating, reads fell back to the legacy fields correctly. Migration moved all fields, cleared them from `users` and stored the avatar. A re-run made no changes. - An 8,000-song sync was stored as 5,000. Pagination, add-to-queue and shuffle on that queue still worked. Arrays over 8,192 are rejected when arguments are validated, and the client cap keeps it from sending them. - Subscription check: 5 progress saves caused 0 reruns of `currentUser`, `getPlaybackState` and `getQueueHistory`, and 5 reruns of `getSongProgress`. - Avatar upload, replace (the old file is deleted), the size cap and removal all worked. - `pnpm -r typecheck` passes. The migration was tested on seeded data, not on a copy of a production database. --- Changes made by Claude Opus 5.5 (`claude-opus-5-5`) running in Claude Code via T3 Code. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
joshuafhiggins added 1 commit 2026-11-16 14:15:42 -05:00
Playback queue, history and progress move into playbackStates and
playbackProgress tables, so progress saves no longer rerun user queries.
Avatars move to Convex file storage behind a web proxy route. The server
caps queues at 5,000 songs, and the client stops retrying rejected syncs.
migrations:migrateUsers moves existing data and runs on Docker boot.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
joshuafhiggins added 1 commit 2026-11-16 21:55:55 -05:00
# Conflicts:
#	docker/entrypoint.sh
#	packages/convex/convex/playback.ts
joshuafhiggins merged commit 51ceab738b into main 2026-11-16 21:56:01 -05:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: joshuafhiggins/otunes#100