Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix(music): make album and track membership mutations atomic (#11568)

[._.]/abbca39e240e
diff --git a/scripts/lib/dbTestFiles.js b/scripts/lib/dbTestFiles.js
index 04693b4617..82c792cf48 100644
--- a/scripts/lib/dbTestFiles.js
+++ b/scripts/lib/dbTestFiles.js
@@ -9,6 +9,7 @@ import { posix } from 'node:path';
* listed explicitly below (the drift guard fails the build if you forget).
*/
export const DB_TEST_INCLUDE = [
+ 'services/trackAlbumMembership.db.test.js',
'services/stackerNews.db.test.js',
'services/peerExecutionLedger.db.test.js',
'services/voice/profiles.db.test.js',
diff --git a/server/routes/albums.js b/server/routes/albums.js
index fe25fa8816..3b116906d4 100644
--- a/server/routes/albums.js
+++ b/server/routes/albums.js
@@ -17,7 +17,7 @@ import { z } from 'zod';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
import { validateRequest, isPaginationRequested, paginateArray } from '../lib/validation.js';
import * as albums from '../services/albums/index.js';
-import * as tracks from '../services/tracks/index.js';
+import { createAlbumWithTracks, updateAlbumWithTracks, deleteAlbumWithTracks } from '../services/trackAlbumMembership.js';
const router = Router();
@@ -53,58 +53,6 @@ const patchSchema = z.object({
trackIds: trackIdsField.optional(),
}).refine((p) => Object.keys(p).length > 0, { message: 'patch must include at least one field' });
-// Membership single-source-of-truth reconcile. The album's `trackIds` carry the
-// ORDER; each track's `albumId` is the membership pointer the Tracks API reports.
-// After an album write, stamp `albumId` on its member tracks and clear it on any
-// track that used to belong to this album but was dropped — so the two views
-// never disagree (a track removed from the album stops reporting that albumId,
-// and an added track starts). Best-effort per track: a missing/deleted track id
-// in `trackIds` is simply skipped (updateTrack 404s are swallowed). Runs after
-// the album persists so a rejected album write doesn't mutate track membership.
-async function reconcileAlbumMembership(album) {
- const desired = new Set(album.trackIds || []);
- const all = await tracks.listTracks().catch(() => []);
- const byId = new Map(all.map((t) => [t.id, t]));
- const ops = [];
- // A listed track that currently belongs to a DIFFERENT album is being moved
- // here — drop it from that other album's ordered `trackIds` so the old album
- // stops listing it (it now reports a different `albumId`). Call the album
- // SERVICE (not this route) so the write can't re-enter reconcile and loop.
- // Coalesce per-source-album removals into one update each.
- const removalsByAlbum = new Map();
- // Clear albumId on tracks that point here but are no longer listed.
- for (const t of all) {
- if (t.albumId === album.id && !desired.has(t.id)) {
- ops.push(tracks.updateTrack(t.id, { albumId: '' }).catch(() => {}));
- }
- }
- // Stamp albumId on listed tracks that don't already point here, and record any
- // prior album they're being stolen from.
- for (const id of desired) {
- const t = byId.get(id);
- if (t && t.albumId !== album.id) {
- ops.push(tracks.updateTrack(id, { albumId: album.id }).catch(() => {}));
- if (t.albumId) {
- const set = removalsByAlbum.get(t.albumId) || new Set();
- set.add(id);
- removalsByAlbum.set(t.albumId, set);
- }
- }
- }
- await Promise.all(ops);
- // Now prune each stolen track from its former album's list (one write per
- // source album; skips the album being saved and any missing/deleted album).
- await Promise.all([...removalsByAlbum.entries()].map(async ([srcAlbumId, stolen]) => {
- if (srcAlbumId === album.id) return;
- const src = await albums.getAlbum(srcAlbumId).catch(() => null);
- if (!src) return;
- const nextIds = (src.trackIds || []).filter((id) => !stolen.has(id));
- if (nextIds.length !== (src.trackIds || []).length) {
- await albums.updateAlbum(srcAlbumId, { trackIds: nextIds }).catch(() => {});
- }
- }));
-}
-
// Backward-compatible by default: returns the full albums array. When a client
// passes `limit`/`offset`, the response becomes the bounded
// `{ items, total, limit, offset }` envelope every paginated PortOS list shares.
@@ -116,8 +64,7 @@ router.get('/', asyncHandler(async (req, res) => {
router.post('/', asyncHandler(async (req, res) => {
const body = validateRequest(createSchema, req.body ?? {});
- const album = await albums.createAlbum(body);
- await reconcileAlbumMembership(album);
+ const album = await createAlbumWithTracks(body);
res.status(201).json(album);
}));
@@ -129,17 +76,12 @@ router.get('/:id', asyncHandler(async (req, res) => {
router.patch('/:id', asyncHandler(async (req, res) => {
const body = validateRequest(patchSchema, req.body ?? {});
- const album = await albums.updateAlbum(req.params.id, body);
- // Only reconcile when the membership list was part of this write.
- if ('trackIds' in body) await reconcileAlbumMembership(album);
+ const album = await updateAlbumWithTracks(req.params.id, body);
res.json(album);
}));
router.delete('/:id', asyncHandler(async (req, res) => {
- const result = await albums.deleteAlbum(req.params.id);
- // Orphan the album's tracks (clear their albumId) so they revert to singles
- // rather than pointing at a tombstoned album.
- await reconcileAlbumMembership({ id: req.params.id, trackIds: [] });
+ const result = await deleteAlbumWithTracks(req.params.id);
res.json(result);
}));
diff --git a/server/routes/tracks.js b/server/routes/tracks.js
index e95048dd93..066dcee437 100644
--- a/server/routes/tracks.js
+++ b/server/routes/tracks.js
@@ -50,7 +50,7 @@ import { PATHS } from '../lib/fileUtils.js';
import { probeVideoDuration } from '../lib/ffmpeg.js';
import * as tracks from '../services/tracks/index.js';
import { attachAudioAsRender } from '../services/trackAudioAttach.js';
-import { createTrackWithAlbum, updateTrackWithAlbum, removeTrackFromAlbum } from '../services/trackAlbumMembership.js';
+import { createTrackWithAlbum, updateTrackWithAlbum, deleteTrackWithAlbum } from '../services/trackAlbumMembership.js';
import {
listMusicLibrary, importUploadedTrack, statMusicTrack,
isSupportedMusicUpload, assertSafeMusicFilename, MUSIC_UPLOAD_MAX_BYTES,
@@ -225,17 +225,12 @@ router.get('/:id', asyncHandler(async (req, res) => {
router.patch('/:id', asyncHandler(async (req, res) => {
const body = validateRequest(patchSchema, req.body ?? {});
- const prev = await requireTrack(req.params.id);
- const track = await updateTrackWithAlbum(prev, body);
+ const track = await updateTrackWithAlbum({ id: req.params.id }, body);
res.json(track);
}));
router.delete('/:id', asyncHandler(async (req, res) => {
- const prev = await tracks.getTrack(req.params.id).catch(() => null);
- const result = await tracks.deleteTrack(req.params.id);
- // Drop the deleted track from its album's ordered list so the album doesn't
- // render a dangling (missing) entry.
- if (prev?.albumId) await removeTrackFromAlbum(req.params.id, prev.albumId);
+ const result = await deleteTrackWithAlbum(req.params.id);
res.json(result);
}));
diff --git a/server/services/albums/db.js b/server/services/albums/db.js
index 89c673ec7d..6717e8c6c6 100644
--- a/server/services/albums/db.js
+++ b/server/services/albums/db.js
@@ -46,15 +46,17 @@ async function persist(exec, album) {
return album;
}
-export async function listAlbums({ includeDeleted = false } = {}) {
+export async function listAlbums({ includeDeleted = false, client } = {}) {
+ const exec = client ? client.query.bind(client) : query;
const { rows } = includeDeleted
- ? await query(`SELECT data FROM albums ORDER BY title ASC`)
- : await query(`SELECT data FROM albums WHERE deleted = FALSE ORDER BY title ASC`);
+ ? await exec(`SELECT data FROM albums ORDER BY title ASC`)
+ : await exec(`SELECT data FROM albums WHERE deleted = FALSE ORDER BY title ASC`);
return rows.map(rowToAlbum);
}
-export async function getAlbum(id, { includeDeleted = false } = {}) {
- const { rows } = await query(`SELECT data FROM albums WHERE id = $1`, [id]);
+export async function getAlbum(id, { includeDeleted = false, client } = {}) {
+ const exec = client ? client.query.bind(client) : query;
+ const { rows } = await exec(`SELECT data FROM albums WHERE id = $1${client ? ' FOR UPDATE' : ''}`, [id]);
const album = rowToAlbum(rows[0]);
if (!album) return null;
return includeDeleted || !album.deleted ? album : null;
@@ -68,16 +70,16 @@ export async function listAlbumIds({ includeDeleted = false } = {}) {
return rows.map((r) => r.id);
}
-export async function createAlbum(input) {
+export async function createAlbum(input, { client } = {}) {
const album = buildAlbumRecord(input, { id: `album-${randomUUID()}`, now: new Date().toISOString() });
if (!album) throw new ServerError('Invalid album payload', { status: 400, code: 'VALIDATION' });
- await persist(query, album);
+ await persist(client ? client.query.bind(client) : query, album);
console.log(`💿 Created album: ${album.id} (${album.title})`);
return album;
}
-export async function updateAlbum(id, patch) {
- return withTransaction(async (client) => {
+export async function updateAlbum(id, patch, { client: transactionClient } = {}) {
+ const mutate = async (client) => {
const sel = await client.query(`SELECT data FROM albums WHERE id = $1 FOR UPDATE`, [id]);
const current = rowToAlbum(sel.rows[0]);
if (!current || current.deleted) throw new ServerError('Album not found', { status: 404, code: 'NOT_FOUND' });
@@ -85,11 +87,12 @@ export async function updateAlbum(id, patch) {
if (!next) throw new ServerError('Invalid album payload', { status: 400, code: 'VALIDATION' });
await persist(client.query.bind(client), next);
return next;
- });
+ };
+ return transactionClient ? mutate(transactionClient) : withTransaction(mutate);
}
-export async function deleteAlbum(id) {
- return withTransaction(async (client) => {
+export async function deleteAlbum(id, { client: transactionClient } = {}) {
+ const mutate = async (client) => {
const sel = await client.query(`SELECT data FROM albums WHERE id = $1 FOR UPDATE`, [id]);
const current = rowToAlbum(sel.rows[0]);
if (!current || current.deleted) throw new ServerError('Album not found', { status: 404, code: 'NOT_FOUND' });
@@ -97,7 +100,8 @@ export async function deleteAlbum(id) {
const next = { ...current, deleted: true, deletedAt: now, updatedAt: now };
await persist(client.query.bind(client), next);
return { id };
- });
+ };
+ return transactionClient ? mutate(transactionClient) : withTransaction(mutate);
}
/**
diff --git a/server/services/albums/file.js b/server/services/albums/file.js
index 6e98371f1f..0dd0f8b82a 100644
--- a/server/services/albums/file.js
+++ b/server/services/albums/file.js
@@ -10,6 +10,7 @@
import { join } from 'path';
import { randomUUID } from 'crypto';
import { PATHS, readJSONFile, atomicWrite, ensureDir } from '../../lib/fileUtils.js';
+import { readMusicFile, writeMusicFile } from '../musicMembershipMutation.js';
import { ServerError } from '../../lib/errorHandler.js';
import { sanitizeAlbum, buildAlbumRecord, applyAlbumPatch, mergeAlbumRecord } from './logic.js';
import {
@@ -20,14 +21,18 @@ import {
const ALBUMS_FILE = join(PATHS.data, 'albums.json');
async function loadAll() {
- // Albums are durable user records; never save an empty fallback over unreadable bytes.
- const raw = await readJSONFile(ALBUMS_FILE, [], { strict: true });
- return (Array.isArray(raw) ? raw : []).map(sanitizeAlbum).filter(Boolean);
+ return readMusicFile('albums', async () => {
+ // Albums are durable user records; never save an empty fallback over unreadable bytes.
+ const raw = await readJSONFile(ALBUMS_FILE, [], { strict: true });
+ return (Array.isArray(raw) ? raw : []).map(sanitizeAlbum).filter(Boolean);
+ });
}
async function saveAll(albums) {
- await ensureDir(PATHS.data);
- await atomicWrite(ALBUMS_FILE, albums);
+ return writeMusicFile('albums', albums, async (records) => {
+ await ensureDir(PATHS.data);
+ await atomicWrite(ALBUMS_FILE, records);
+ });
}
const byTitle = (a, b) => (a.title || '').localeCompare(b.title || '');
diff --git a/server/services/albums/index.js b/server/services/albums/index.js
index 38f96b69c5..197f904d42 100644
--- a/server/services/albums/index.js
+++ b/server/services/albums/index.js
@@ -11,6 +11,7 @@
*/
import { createRecordStoreBackendSelector } from '../../lib/pgFileFacade.js';
+import { withMusicMutation, musicMutationClient, afterMusicCommit } from '../musicMembershipMutation.js';
import { emitRecordUpdated, emitRecordDeleted, autoSubscribeRecordToAllPeers } from '../sharing/recordEvents.js';
export {
@@ -37,6 +38,9 @@ const { selectBackend, getBackendName, reset } = createRecordStoreBackendSelecto
requireDbMessage: 'Albums require PostgreSQL — run `npm run setup:db` (dev/test only: set MEMORY_BACKEND=file in .env for the unsupported file backend)',
});
+// The shared mutation boundary prepares both stores before reserving a client.
+export { selectBackend as prepareAlbumsBackend };
+
/** Name of the active backend, or null before first call (for diagnostics/tests). */
export function getAlbumsBackendName() {
return getBackendName();
@@ -48,7 +52,7 @@ export function _resetAlbumsBackend() {
}
export async function listAlbums(options = {}) {
- return (await selectBackend()).listAlbums(options);
+ return (await selectBackend()).listAlbums({ ...options, client: musicMutationClient() });
}
export async function listAlbumIds(options = {}) {
@@ -56,7 +60,7 @@ export async function listAlbumIds(options = {}) {
}
export async function getAlbum(id, options = {}) {
- return (await selectBackend()).getAlbum(id, options);
+ return (await selectBackend()).getAlbum(id, { ...options, client: musicMutationClient() });
}
function announceNewAlbum(id) {
@@ -65,21 +69,27 @@ function announceNewAlbum(id) {
}
export async function createAlbum(input) {
- const album = await (await selectBackend()).createAlbum(input);
- announceNewAlbum(album.id);
- return album;
+ return withMusicMutation(async () => {
+ const album = await (await selectBackend()).createAlbum(input, { client: musicMutationClient() });
+ afterMusicCommit(() => announceNewAlbum(album.id));
+ return album;
+ });
}
export async function updateAlbum(id, patch) {
- const next = await (await selectBackend()).updateAlbum(id, patch);
- emitRecordUpdated('album', next.id);
- return next;
+ return withMusicMutation(async () => {
+ const next = await (await selectBackend()).updateAlbum(id, patch, { client: musicMutationClient() });
+ afterMusicCommit(() => emitRecordUpdated('album', next.id));
+ return next;
+ });
}
export async function deleteAlbum(id) {
- const result = await (await selectBackend()).deleteAlbum(id);
- emitRecordDeleted('album', result.id);
- return result;
+ return withMusicMutation(async () => {
+ const result = await (await selectBackend()).deleteAlbum(id, { client: musicMutationClient() });
+ afterMusicCommit(() => emitRecordDeleted('album', result.id));
+ return result;
+ });
}
/** Merge an incoming batch of album records from a peer (LWW, tombstone-aware). */
diff --git a/server/services/musicMembershipMutation.js b/server/services/musicMembershipMutation.js
new file mode 100644
index 0000000000..75dcc3dfdc
--- /dev/null
+++ b/server/services/musicMembershipMutation.js
@@ -0,0 +1,88 @@
+/** Local album/track unit of work. Federation retains its per-record LWW path. */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { withTransaction } from '../lib/db.js';
+import { isFileBackend } from '../lib/pgFileFacade.js';
+import { ServerError } from '../lib/errorHandler.js';
+import { createFileWriteQueue } from '../lib/fileWriteQueue.js';
+
+const mutations = new AsyncLocalStorage();
+const queueFiles = createFileWriteQueue();
+
+export const musicMutationClient = () => mutations.getStore()?.client;
+
+export function afterMusicCommit(announce) {
+ const context = mutations.getStore();
+ if (context) context.events.push(announce);
+ else announce();
+}
+
+// The unsupported file backend stages both arrays before touching disk. A
+// failed second write restores the first, making an ordinary retry safe. This
+// is NOT crash atomic: production requires PostgreSQL.
+export async function readMusicFile(key, load) {
+ const context = mutations.getStore();
+ if (!context?.files) return load();
+ if (!context.files.has(key)) {
+ const original = await load();
+ context.files.set(key, { original, records: structuredClone(original), save: null });
+ }
+ return structuredClone(context.files.get(key).records);
+}
+
+export async function writeMusicFile(key, records, save) {
+ const context = mutations.getStore();
+ if (!context?.files) return save(records);
+ const entry = context.files.get(key);
+ entry.records = records;
+ entry.save = save;
+}
+
+async function commitFiles(files) {
+ const written = [];
+ try {
+ for (const entry of files.values()) {
+ if (!entry.save) continue;
+ await entry.save(entry.records);
+ written.push(entry);
+ }
+ } catch (error) {
+ const restored = await Promise.allSettled(written.map((entry) => entry.save(entry.original)));
+ if (restored.some((result) => result.status === 'rejected')) {
+ throw new ServerError('Music membership file recovery failed. Reconcile albums.json and tracks.json before retrying; use PostgreSQL for atomic writes.', {
+ code: 'MUSIC_MEMBERSHIP_RECONCILIATION_REQUIRED',
+ });
+ }
+ throw new ServerError('Music membership was not saved. Previous records were restored; retry the request.', {
+ code: 'MUSIC_MEMBERSHIP_WRITE_FAILED', context: { cause: error.code || 'WRITE_FAILED' },
+ });
+ }
+}
+
+export function withMusicMutation(operation) {
+ if (mutations.getStore()) return operation();
+ const run = async () => {
+ const context = { events: [] };
+ let result;
+ if (isFileBackend()) {
+ context.files = new Map();
+ result = await mutations.run(context, operation);
+ await commitFiles(context.files);
+ } else {
+ // Backend selection performs pool-based health/schema work. Finish it
+ // BEFORE checking out a transaction client: a cold burst can otherwise
+ // reserve the entire pool while its lock holder needs one more client.
+ const [albums, tracks] = await Promise.all([import('./albums/index.js'), import('./tracks/index.js')]);
+ await Promise.all([albums.prepareAlbumsBackend(), tracks.prepareTracksBackend()]);
+ result = await withTransaction(async (client) => {
+ // One domain lock, acquired before any row lock or membership read.
+ // All LOCAL writers share it, including track metadata saves.
+ await client.query('SELECT pg_advisory_xact_lock(hashtext($1))', ['portos:music-membership']);
+ context.client = client;
+ return mutations.run(context, operation);
+ });
+ }
+ for (const announce of context.events) announce();
+ return result;
+ };
+ return isFileBackend() ? queueFiles(run) : run();
+}
diff --git a/server/services/musicMembershipStartup.test.js b/server/services/musicMembershipStartup.test.js
new file mode 100644
index 0000000000..93324d70b7
--- /dev/null
+++ b/server/services/musicMembershipStartup.test.js
@@ -0,0 +1,49 @@
+import { describe, expect, it, vi } from 'vitest';
+
+const pool = vi.hoisted(() => ({ reserved: 0, capacity: 20 }));
+// A bounded pool stand-in rejects instead of waiting ten seconds when cold
+// backend health checks compete for a fully reserved transaction pool.
+vi.mock('../lib/db.js', () => ({
+ checkHealth: async () => {
+ if (pool.reserved === pool.capacity) throw new Error('Synthetic pool exhausted during backend initialization');
+ return { connected: true };
+ },
+ ensureSchema: async () => {},
+ withTransaction: async (operation) => {
+ pool.reserved++;
+ await Promise.resolve();
+ try {
+ return await operation({ query: async () => ({ rows: [] }) });
+ } finally {
+ pool.reserved--;
+ }
+ },
+}));
+vi.mock('../lib/pgFileFacade.js', async (importOriginal) => {
+ const actual = await importOriginal();
+ return {
+ ...actual,
+ isFileBackend: () => false,
+ createRecordStoreBackendSelector: (options) => actual.createRecordStoreBackendSelector({ ...options, isTestMode: () => false }),
+ };
+});
+vi.mock('./albums/db.js', () => ({}));
+vi.mock('./tracks/db.js', () => ({
+ createTrack: async (input) => ({ id: `track-${input.title}`, ...input }),
+}));
+
+import { createTrackWithAlbum } from './trackAlbumMembership.js';
+
+describe('cold music store startup', () => {
+ it('completes a full pool of concurrent first writes without starving backend initialization', async () => {
+ vi.stubEnv('MEMORY_BACKEND', '');
+ try {
+ const saved = await Promise.all(Array.from({ length: pool.capacity }, (_, i) =>
+ createTrackWithAlbum({ title: `example-${i}` })));
+ expect(new Set(saved.map(({ track }) => track.id)).size).toBe(pool.capacity);
+ expect(saved.every(({ track }) => track.albumId === '')).toBe(true);
+ } finally {
+ vi.unstubAllEnvs();
+ }
+ });
+});
diff --git a/server/services/trackAlbumMembership.db.test.js b/server/services/trackAlbumMembership.db.test.js
new file mode 100644
index 0000000000..9084102091
--- /dev/null
+++ b/server/services/trackAlbumMembership.db.test.js
@@ -0,0 +1,194 @@
+/** Real transactions against portos_test; no live database or media/provider work. */
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import { checkHealth, query, close } from '../lib/db.js';
+import { requireDbOrSkip } from '../lib/dbTestGate.js';
+import { request } from '../lib/testHelper.js';
+import { errorMiddleware } from '../lib/errorHandler.js';
+
+const fixture = await vi.hoisted(async () => {
+ const { randomUUID } = await import('node:crypto');
+ return { schema: 'music_membership_' + randomUUID().replaceAll('-', ''), created: false };
+});
+const fault = vi.hoisted(() => ({ failWrite: 0, writes: 0 }));
+// Every connection in this suite's pool has ONLY the invocation-owned schema
+// in its search path. Never initialize or clean up the shared public schema.
+vi.mock('pg', async (importOriginal) => {
+ const actual = await importOriginal();
+ return { ...actual, default: {
+ ...actual.default,
+ Pool: function Pool(options) {
+ return new actual.default.Pool({ ...options, options: '-csearch_path=' + fixture.schema });
+ },
+ } };
+});
+// Only inject a persistence failure. BEGIN/COMMIT/ROLLBACK, row locks, advisory
+// locks, reads and every other write still execute on the real PostgreSQL pool.
+vi.mock('../lib/db.js', async (importOriginal) => {
+ const actual = await importOriginal();
+ return {
+ ...actual,
+ ensureSchema: async () => {
+ if (!fixture.created) throw new Error('Fixture schema must exist before initializing music stores');
+ const { libraryDdl } = await import('../lib/db/schema/library.js');
+ for (const sql of libraryDdl) await actual.query(sql);
+ },
+ withTransaction: (operation) => actual.withTransaction((client) => operation({
+ query: async (sql, params) => {
+ if (/^INSERT INTO (albums|tracks)\b/.test(sql) && ++fault.writes === fault.failWrite) {
+ // A real SQL error aborts this PostgreSQL transaction.
+ return client.query('SELECT 1 / 0');
+ }
+ return client.query(sql, params);
+ },
+ })),
+ };
+});
+vi.mock('../lib/pgFileFacade.js', async (importOriginal) => {
+ const actual = await importOriginal();
+ return {
+ ...actual,
+ isFileBackend: () => false,
+ createRecordStoreBackendSelector: (options) => actual.createRecordStoreBackendSelector({ ...options, isTestMode: () => false }),
+ };
+});
+
+const health = await checkHealth();
+const runDb = requireDbOrSkip('trackAlbumMembership.db.test', health.connected, health.error);
+const prefix = 'Example membership fixture';
+const events = [];
+const subscribe = vi.fn(async () => {});
+let albums;
+let tracks;
+let membership;
+let bus;
+let app;
+const onUpdated = (event) => events.push(['updated', event]);
+const onDeleted = (event) => events.push(['deleted', event]);
+
+const createAlbum = (input = {}) => membership.createAlbumWithTracks({ title: prefix, ...input });
+const createTrack = async (albumId = '') => (await membership.createTrackWithAlbum({ title: prefix, albumId })).track;
+const snapshot = async () => ({
+ albums: (await query('SELECT data FROM albums WHERE title = $1 ORDER BY id', [prefix])).rows,
+ tracks: (await query('SELECT data FROM tracks WHERE title = $1 ORDER BY id', [prefix])).rows,
+});
+
+async function cleanup() {
+ await query('DELETE FROM tracks WHERE title = $1', [prefix]);
+ await query('DELETE FROM albums WHERE title = $1', [prefix]);
+}
+
+describe.skipIf(!runDb)('atomic local album membership on PostgreSQL', () => {
+ beforeAll(async () => {
+ expect((await query('SELECT current_database() AS name')).rows[0].name).toBe('portos_test');
+ vi.stubEnv('MEMORY_BACKEND', '');
+ await query(`CREATE SCHEMA ${fixture.schema}`);
+ fixture.created = true;
+ expect((await query('SHOW search_path')).rows[0].search_path).toBe(fixture.schema);
+ albums = await import('./albums/index.js');
+ tracks = await import('./tracks/index.js');
+ membership = await import('./trackAlbumMembership.js');
+ await albums.prepareAlbumsBackend();
+ await tracks.prepareTracksBackend();
+ bus = await import('./sharing/recordEvents.js');
+ bus.recordEvents.on('updated', onUpdated);
+ bus.recordEvents.on('deleted', onDeleted);
+ bus.registerSubscriptionAdapter({ autoSubscribeRecordToAllPeers: subscribe });
+ const { default: routes } = await import('../routes/albums.js');
+ app = express();
+ app.use(express.json());
+ app.use('/api/albums', routes);
+ app.use(errorMiddleware);
+ });
+ beforeEach(async () => {
+ await cleanup();
+ fault.failWrite = 0;
+ fault.writes = 0;
+ events.length = 0;
+ subscribe.mockClear();
+ });
+ afterAll(async () => {
+ if (bus) {
+ bus.recordEvents.off('updated', onUpdated);
+ bus.recordEvents.off('deleted', onDeleted);
+ bus.__resetSubscriptionAdapter();
+ }
+ try {
+ if (fixture.created) await query(`DROP SCHEMA ${fixture.schema} CASCADE`);
+ } finally {
+ vi.unstubAllEnvs();
+ await close();
+ }
+ });
+
+ it('retains competing additions and admits only one claimant for the final slot', async () => {
+ const album = await createAlbum();
+ const additions = await Promise.all([createTrack(album.id), createTrack(album.id)]);
+ expect((await albums.getAlbum(album.id)).trackIds.sort()).toEqual(additions.map((t) => t.id).sort());
+ const full = await createAlbum({ trackIds: Array.from({ length: albums.TRACK_IDS_MAX - 1 }, (_, i) => `track-example-${i}`) });
+ const results = await Promise.allSettled([createTrack(full.id), createTrack(full.id)]);
+ expect(results.filter((result) => result.status === 'fulfilled')).toHaveLength(1);
+ expect(results.find((result) => result.status === 'rejected').reason.code).toBe('ALBUM_FULL');
+ expect((await albums.getAlbum(full.id)).trackIds).toHaveLength(albums.TRACK_IDS_MAX);
+ const saved = (await snapshot()).tracks.map(({ data }) => data);
+ expect(saved.filter((track) => track.albumId === full.id)).toHaveLength(1);
+ });
+
+ // Each case represents a different public mutation whose partial commit
+ // would require a different repair (duplicate create, stale move or tombstone).
+ it.each(['album create', 'album edit', 'album delete', 'track create', 'track move', 'track delete'])(
+ 'rolls back %s on a later write failure, emits nothing, and succeeds on retry', async (operation) => {
+ const source = await createAlbum({ description: 'Preserved metadata' });
+ const destination = await createAlbum();
+ const track = await createTrack(source.id);
+ const before = await snapshot();
+ const actions = {
+ 'album create': () => request(app).post('/api/albums').send({ title: prefix, trackIds: [track.id] }),
+ 'album edit': () => request(app).patch(`/api/albums/${source.id}`).send({ trackIds: [] }),
+ 'album delete': () => request(app).delete(`/api/albums/${source.id}`),
+ 'track create': () => createTrack(source.id),
+ 'track move': () => membership.updateTrackWithAlbum(track, { albumId: destination.id }),
+ 'track delete': () => membership.deleteTrackWithAlbum(track.id),
+ };
+ fault.writes = 0;
+ fault.failWrite = operation === 'track move' ? 3 : 2;
+ events.length = 0;
+ subscribe.mockClear();
+ if (operation.startsWith('album')) {
+ const response = await actions[operation]();
+ expect(response.status).toBe(500);
+ expect(response.body).toMatchObject({ code: expect.any(String), error: expect.any(String) });
+ } else {
+ await expect(actions[operation]()).rejects.toThrow('division by zero');
+ }
+ expect(await snapshot()).toEqual(before);
+ expect(events).toEqual([]);
+ expect(subscribe).not.toHaveBeenCalled();
+ fault.failWrite = 0;
+ const result = await actions[operation]();
+ if (operation.startsWith('album')) expect(result.status).toBe(operation === 'album create' ? 201 : 200);
+ expect(events.length).toBeGreaterThan(0);
+ if (operation === 'album create') expect((await snapshot()).albums).toHaveLength(3);
+ if (operation === 'track create') expect((await snapshot()).tracks).toHaveLength(2);
+ if (operation === 'album delete') expect((await tracks.getTrack(track.id)).albumId).toBe('');
+ if (operation === 'track delete') expect((await albums.getAlbum(source.id)).trackIds).toEqual([]);
+ },
+ );
+
+ it('shares the lock across album edits and stale track moves without replacing metadata', async () => {
+ const source = await createAlbum();
+ const destination = await createAlbum({ genre: 'Example genre' });
+ const third = await createAlbum();
+ const track = await createTrack(source.id);
+ const neighbor = await createTrack(destination.id);
+ await membership.updateAlbumWithTracks(destination.id, { trackIds: [neighbor.id, track.id] });
+ await Promise.all([
+ membership.updateTrackWithAlbum(track, { albumId: third.id }),
+ membership.updateAlbumWithTracks(destination.id, { description: 'Example description' }),
+ ]);
+ expect(await albums.getAlbum(destination.id)).toMatchObject({ trackIds: [neighbor.id], genre: 'Example genre', description: 'Example description' });
+ expect((await albums.getAlbum(source.id)).trackIds).toEqual([]);
+ expect((await tracks.getTrack(track.id)).albumId).toBe(third.id);
+ expect((await albums.getAlbum(third.id)).trackIds).toEqual([track.id]);
+ });
+});
diff --git a/server/services/trackAlbumMembership.js b/server/services/trackAlbumMembership.js
index 1d174b282a..5ad0e36d4e 100644
--- a/server/services/trackAlbumMembership.js
+++ b/server/services/trackAlbumMembership.js
@@ -7,6 +7,7 @@ import { ServerError } from '../lib/errorHandler.js';
import { TRACK_IDS_MAX } from './albums/logic.js';
import * as albums from './albums/index.js';
import * as tracks from './tracks/index.js';
+import { withMusicMutation } from './musicMembershipMutation.js';
async function destinationAlbum(albumId, trackId) {
if (!albumId) return null;
@@ -26,7 +27,7 @@ async function appendTrackToAlbum(trackId, album) {
await albums.updateAlbum(album.id, { trackIds: [...(album.trackIds || []), trackId] });
}
-export async function removeTrackFromAlbum(trackId, albumId) {
+async function removeTrackFromAlbum(trackId, albumId) {
if (!albumId) return;
const album = await albums.getAlbum(albumId);
if (album?.trackIds?.includes(trackId)) {
@@ -36,22 +37,78 @@ export async function removeTrackFromAlbum(trackId, albumId) {
/** Completed audio may survive an unavailable destination as a single. */
export async function createTrackWithAlbum(input, { preserveUnassigned = false } = {}) {
- let albumAssignmentError = null;
- const album = await destinationAlbum(input.albumId).catch((err) => {
- if (!preserveUnassigned || !['ALBUM_FULL', 'ALBUM_NOT_FOUND'].includes(err.code)) throw err;
- albumAssignmentError = { code: err.code, message: err.message };
- return null;
+ return withMusicMutation(async () => {
+ let albumAssignmentError = null;
+ const album = await destinationAlbum(input.albumId).catch((err) => {
+ if (!preserveUnassigned || !['ALBUM_FULL', 'ALBUM_NOT_FOUND'].includes(err.code)) throw err;
+ albumAssignmentError = { code: err.code, message: err.message };
+ return null;
+ });
+ const track = await tracks.createTrack({ ...input, albumId: album?.id || '' });
+ await appendTrackToAlbum(track.id, album);
+ return { track, albumAssignmentError };
});
- const track = await tracks.createTrack({ ...input, albumId: album?.id || '' });
- await appendTrackToAlbum(track.id, album);
- return { track, albumAssignmentError };
}
export async function updateTrackWithAlbum(current, patch) {
- if (!('albumId' in patch)) return tracks.updateTrack(current.id, patch);
- const album = await destinationAlbum(patch.albumId, current.id);
- const track = await tracks.updateTrack(current.id, patch);
- await appendTrackToAlbum(track.id, album);
- if (current.albumId !== track.albumId) await removeTrackFromAlbum(track.id, current.albumId);
- return track;
+ return withMusicMutation(async () => {
+ // Callers may have read the track before another move/delete committed.
+ const fresh = await tracks.getTrack(current.id);
+ if (!fresh) throw new ServerError('Track not found', { status: 404, code: 'NOT_FOUND' });
+ if (!('albumId' in patch)) return tracks.updateTrack(fresh.id, patch);
+ const album = await destinationAlbum(patch.albumId, fresh.id);
+ const track = await tracks.updateTrack(fresh.id, patch);
+ await appendTrackToAlbum(track.id, album);
+ if (fresh.albumId !== track.albumId) await removeTrackFromAlbum(track.id, fresh.albumId);
+ return track;
+ });
+}
+
+export async function deleteTrackWithAlbum(id) {
+ return withMusicMutation(async () => {
+ const track = await tracks.getTrack(id);
+ if (!track) throw new ServerError('Track not found', { status: 404, code: 'NOT_FOUND' });
+ await removeTrackFromAlbum(id, track.albumId);
+ return tracks.deleteTrack(id);
+ });
+}
+
+async function reconcileAlbumMembership(album) {
+ const desired = new Set(album.trackIds || []);
+ const all = await tracks.listTracks();
+ for (const track of all) {
+ if (desired.has(track.id)) {
+ if (track.albumId === album.id) continue;
+ await removeTrackFromAlbum(track.id, track.albumId);
+ await tracks.updateTrack(track.id, { albumId: album.id });
+ } else if (track.albumId === album.id) {
+ await tracks.updateTrack(track.id, { albumId: '' });
+ }
+ }
+ // Missing/deleted ids remain tolerated, as in the existing album contract.
+ // Read/write failures propagate and roll back the entire mutation.
+}
+
+export async function createAlbumWithTracks(input) {
+ return withMusicMutation(async () => {
+ const album = await albums.createAlbum(input);
+ await reconcileAlbumMembership(album);
+ return album;
+ });
+}
+
+export async function updateAlbumWithTracks(id, patch) {
+ return withMusicMutation(async () => {
+ const album = await albums.updateAlbum(id, patch);
+ if ('trackIds' in patch) await reconcileAlbumMembership(album);
+ return album;
+ });
+}
+
+export async function deleteAlbumWithTracks(id) {
+ return withMusicMutation(async () => {
+ const result = await albums.deleteAlbum(id);
+ await reconcileAlbumMembership({ id, trackIds: [] });
+ return result;
+ });
}
diff --git a/server/services/trackAlbumMembership.test.js b/server/services/trackAlbumMembership.test.js
index 3012d11182..af04444285 100644
--- a/server/services/trackAlbumMembership.test.js
+++ b/server/services/trackAlbumMembership.test.js
@@ -1,125 +1,171 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { buildAlbumRecord, TRACK_IDS_MAX } from './albums/logic.js';
-import { buildTrackRecord } from './tracks/logic.js';
+import { beforeEach, afterAll, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { request } from '../lib/testHelper.js';
+import { errorMiddleware } from '../lib/errorHandler.js';
-const records = vi.hoisted(() => ({ albums: new Map(), tracks: new Map() }));
-
-// Exercise the real stored shapes: returning a patch verbatim would hide the
-// album sanitizer silently dropping the appended 201st track while the caller
-// still reports success.
-vi.mock('./albums/index.js', async () => {
- const { applyAlbumPatch } = await import('./albums/logic.js');
- return {
- getAlbum: async (id) => records.albums.get(id) || null,
- updateAlbum: async (id, patch) => {
- const next = applyAlbumPatch(records.albums.get(id), patch);
- records.albums.set(id, next);
- return next;
- },
- };
-});
-vi.mock('./tracks/index.js', async () => {
- const logic = await import('./tracks/logic.js');
+const failure = vi.hoisted(() => ({ writes: [], reads: null }));
+const dataRoot = mkdtempSync(join(tmpdir(), 'music-membership-'));
+vi.mock('../lib/fileUtils.js', async (importOriginal) => {
+ const actual = await importOriginal();
return {
- ...logic,
- getTrack: async (id) => records.tracks.get(id) || null,
- createTrack: async (input) => {
- const next = logic.buildTrackRecord(input, { id: 'track-new', now: '2026-01-01T00:00:00.000Z' });
- records.tracks.set(next.id, next);
- return next;
+ ...actual,
+ PATHS: { ...actual.PATHS, data: dataRoot },
+ readJSONFile: async (path, ...args) => {
+ if (failure.reads && path.endsWith(failure.reads)) throw new Error('Synthetic read failure');
+ return actual.readJSONFile(path, ...args);
},
- updateTrack: async (id, patch) => {
- const next = logic.applyTrackPatch(records.tracks.get(id), patch);
- records.tracks.set(id, next);
- return next;
+ atomicWrite: async (path, records) => {
+ if (failure.writes.length && path.endsWith(failure.writes[0])) {
+ failure.writes.shift();
+ throw new Error('Synthetic write failure');
+ }
+ return actual.atomicWrite(path, records);
},
};
});
-import { createTrackWithAlbum, updateTrackWithAlbum, removeTrackFromAlbum } from './trackAlbumMembership.js';
-
-const now = '2026-01-01T00:00:00.000Z';
+const albums = await import('./albums/index.js');
+const tracks = await import('./tracks/index.js');
+const membership = await import('./trackAlbumMembership.js');
+const { recordEvents, registerSubscriptionAdapter, __resetSubscriptionAdapter } = await import('./sharing/recordEvents.js');
+const { default: routes } = await import('../routes/albums.js');
+const app = express();
+app.use(express.json());
+app.use('/api/albums', routes);
+app.use(errorMiddleware);
+const events = [];
+const updated = (...args) => events.push(['updated', ...args]);
+const deleted = (...args) => events.push(['deleted', ...args]);
+recordEvents.on('updated', updated);
+recordEvents.on('deleted', deleted);
+const subscribe = vi.fn(async () => {});
-function seedAlbum(id, count) {
- const album = buildAlbumRecord({
- title: 'Example Album', trackIds: Array.from({ length: count }, (_, i) => `track-example-${i}`),
- }, { id, now });
- records.albums.set(id, album);
- return album;
-}
+beforeEach(() => {
+ rmSync(dataRoot, { recursive: true, force: true });
+ failure.writes = [];
+ failure.reads = null;
+ events.length = 0;
+ subscribe.mockClear();
+ registerSubscriptionAdapter({ autoSubscribeRecordToAllPeers: subscribe });
+});
+afterAll(() => {
+ recordEvents.off('updated', updated);
+ recordEvents.off('deleted', deleted);
+ __resetSubscriptionAdapter();
+ rmSync(dataRoot, { recursive: true, force: true });
+});
-function seedAssignedTrack() {
- const track = buildTrackRecord({ title: 'Example Track', albumId: 'album-old' }, { id: 'track-existing', now });
- const album = buildAlbumRecord({ title: 'Previous Album', trackIds: [track.id] }, { id: track.albumId, now });
- records.tracks.set(track.id, track);
- records.albums.set(album.id, album);
- return { track, album };
-}
+const createAlbum = (input = {}) => membership.createAlbumWithTracks({ title: 'Example Album', ...input });
+const createTrack = async (albumId = '') => (await membership.createTrackWithAlbum({ title: 'Example Track', albumId })).track;
-describe('track album membership through the stored record contract', () => {
- beforeEach(() => {
- records.albums.clear();
- records.tracks.clear();
+describe('local membership workflows through real file persistence (not a PostgreSQL guarantee)', () => {
+ it('retains concurrent additions in order and enforces the final slot without an orphan', async () => {
+ const album = await createAlbum();
+ const added = await Promise.all([createTrack(album.id), createTrack(album.id)]);
+ expect((await albums.getAlbum(album.id)).trackIds).toEqual(added.map((track) => track.id));
+ const full = await createAlbum({ trackIds: Array.from({ length: albums.TRACK_IDS_MAX - 1 }, (_, i) => `track-example-${i}`) });
+ const results = await Promise.allSettled([createTrack(full.id), createTrack(full.id)]);
+ expect(results.map((r) => r.status)).toEqual(['fulfilled', 'rejected']);
+ expect(results[1].reason.code).toBe('ALBUM_FULL');
+ expect((await tracks.listTracks()).filter((track) => track.albumId === full.id)).toHaveLength(1);
+ expect((await albums.getAlbum(full.id)).trackIds).toHaveLength(albums.TRACK_IDS_MAX);
+ await membership.updateTrackWithAlbum(results[0].value, { albumId: full.id });
});
- it('rejects a create into a full album before persisting a track', async () => {
- const album = seedAlbum('album-full', TRACK_IDS_MAX);
- await expect(createTrackWithAlbum({ title: 'New Track', albumId: album.id }))
- .rejects.toMatchObject({ status: 409, code: 'ALBUM_FULL' });
- expect(records.tracks.size).toBe(0);
- expect(records.albums.get(album.id)).toEqual(album);
+ it('serializes album edits, stale track moves and deletion while preserving metadata and order', async () => {
+ const source = await createAlbum();
+ const destination = await createAlbum({ genre: 'example genre' });
+ const third = await createAlbum();
+ const track = await createTrack(source.id);
+ const neighbor = await createTrack(destination.id);
+ const saved = await request(app).patch(`/api/albums/${destination.id}`).send({ trackIds: [neighbor.id, track.id] });
+ expect(saved.status).toBe(200);
+ await membership.updateTrackWithAlbum(track, { albumId: third.id, title: 'Example edit' });
+ expect((await albums.getAlbum(source.id)).trackIds).toEqual([]);
+ expect(await albums.getAlbum(destination.id)).toMatchObject({ trackIds: [neighbor.id], genre: 'example genre' });
+ await Promise.all([
+ membership.deleteTrackWithAlbum(track.id),
+ request(app).patch(`/api/albums/${third.id}`).send({ description: 'Example description' }),
+ ]);
+ expect(await tracks.getTrack(track.id)).toBeNull();
+ expect(await albums.getAlbum(third.id)).toMatchObject({ trackIds: [], description: 'Example description' });
});
- it('preserves the prior track and both albums when moving into a full album', async () => {
- const { track, album: prior } = seedAssignedTrack();
- const full = seedAlbum('album-full', TRACK_IDS_MAX);
- await expect(updateTrackWithAlbum(track, { title: 'Changed', albumId: full.id }))
- .rejects.toMatchObject({ status: 409, code: 'ALBUM_FULL' });
- expect(records.tracks.get(track.id)).toEqual(track);
- expect(records.albums.get(prior.id)).toEqual(prior);
- expect(records.albums.get(full.id)).toEqual(full);
+ it('rolls back a failed album PATCH, reports the standard error envelope, and permits retry', async () => {
+ const album = await createAlbum();
+ const track = await createTrack(album.id);
+ events.length = 0;
+ failure.writes = ['tracks.json'];
+ const response = await request(app).patch(`/api/albums/${album.id}`).send({ trackIds: [] });
+ expect(response.status).toBe(500);
+ expect(response.body.code).toBe('MUSIC_MEMBERSHIP_WRITE_FAILED');
+ expect((await albums.getAlbum(album.id)).trackIds).toEqual([track.id]);
+ expect((await tracks.getTrack(track.id)).albumId).toBe(album.id);
+ expect(events).toEqual([]);
+ expect((await request(app).patch(`/api/albums/${album.id}`).send({ trackIds: [] })).status).toBe(200);
+ expect((await tracks.getTrack(track.id)).albumId).toBe('');
});
- it('fills the last slot and accepts re-selecting that member in the full album', async () => {
- const album = seedAlbum('album-last-slot', TRACK_IDS_MAX - 1);
- const { track } = await createTrackWithAlbum({ title: 'Last Track', albumId: album.id });
- expect(track.albumId).toBe(album.id);
- const reselected = await updateTrackWithAlbum(track, { albumId: album.id });
- expect(reselected.albumId).toBe(album.id);
- expect(records.albums.get(album.id).trackIds).toEqual([...album.trackIds, track.id]);
+ it('does not strand a failed album DELETE behind a tombstone', async () => {
+ const album = await createAlbum();
+ const track = await createTrack(album.id);
+ failure.writes = ['tracks.json'];
+ expect((await request(app).delete(`/api/albums/${album.id}`)).status).toBe(500);
+ expect(await albums.getAlbum(album.id)).not.toBeNull();
+ expect((await request(app).delete(`/api/albums/${album.id}`)).status).toBe(200);
+ expect(await albums.getAlbum(album.id)).toBeNull();
+ expect((await tracks.getTrack(track.id)).albumId).toBe('');
});
- it('rejects a missing destination without removing existing membership', async () => {
- const { track, album } = seedAssignedTrack();
- await expect(updateTrackWithAlbum(track, { albumId: 'album-missing' }))
- .rejects.toMatchObject({ status: 404, code: 'ALBUM_NOT_FOUND' });
- expect(records.tracks.get(track.id)).toEqual(track);
- expect(records.albums.get(album.id)).toEqual(album);
+ it('discards failed creates without emitting events or leaving duplicate records on retry', async () => {
+ const track = await createTrack();
+ events.length = 0;
+ subscribe.mockClear();
+ failure.writes = ['tracks.json'];
+ const input = { title: 'Example retry', trackIds: [track.id] };
+ expect((await request(app).post('/api/albums').send(input)).status).toBe(500);
+ expect(await albums.listAlbums()).toEqual([]);
+ expect(events).toEqual([]);
+ expect(subscribe).not.toHaveBeenCalled();
+ expect((await request(app).post('/api/albums').send(input)).status).toBe(201);
+ expect(await albums.listAlbums()).toHaveLength(1);
+ expect(events.length).toBeGreaterThan(0);
+ expect(subscribe).toHaveBeenCalledTimes(1);
});
- it('moves a track between albums, appending to the destination and dropping the source', async () => {
- const { track, album: prior } = seedAssignedTrack();
- const next = seedAlbum('album-next', 2);
- const moved = await updateTrackWithAlbum(track, { albumId: next.id });
- expect(moved.albumId).toBe(next.id);
- expect(records.albums.get(next.id).trackIds).toEqual([...next.trackIds, track.id]);
- expect(records.albums.get(prior.id).trackIds).toEqual([]);
+ it('distinguishes missing/deleted tracks from storage failures', async () => {
+ const removed = await createTrack();
+ await membership.deleteTrackWithAlbum(removed.id);
+ const response = await request(app).post('/api/albums').send({ title: 'Example legacy', trackIds: ['track-missing', removed.id] });
+ expect(response.status).toBe(201);
+ failure.reads = 'tracks.json';
+ expect((await request(app).patch(`/api/albums/${response.body.id}`).send({ trackIds: [] })).status).toBe(500);
+ failure.reads = null;
+ expect((await albums.getAlbum(response.body.id)).trackIds).toEqual(['track-missing', removed.id]);
});
- it('keeps completed audio as a single when its destination album is unavailable', async () => {
- const { track, albumAssignmentError } = await createTrackWithAlbum(
- { title: 'Rendered Track', albumId: 'album-missing' },
- { preserveUnassigned: true },
- );
- expect(track.albumId).toBe('');
- expect(albumAssignmentError).toEqual({ code: 'ALBUM_NOT_FOUND', message: 'Album not found' });
- expect(records.tracks.get(track.id)).toEqual(track);
+ it('preserves completed audio for full/missing destinations but propagates arbitrary storage failures', async () => {
+ const full = await createAlbum({ trackIds: Array.from({ length: albums.TRACK_IDS_MAX }, (_, i) => `track-example-${i}`) });
+ for (const albumId of [full.id, 'album-missing']) {
+ const result = await membership.createTrackWithAlbum({ title: 'Example completed', albumId, audioFilename: 'example.wav' }, { preserveUnassigned: true });
+ expect(result.track).toMatchObject({ albumId: '', audioFilename: 'example.wav' });
+ expect(result.albumAssignmentError.code).toBe(albumId === full.id ? 'ALBUM_FULL' : 'ALBUM_NOT_FOUND');
+ }
+ failure.reads = 'albums.json';
+ await expect(membership.createTrackWithAlbum({ title: 'Example failed', albumId: full.id }, { preserveUnassigned: true })).rejects.toThrow('Synthetic read failure');
+ expect(await tracks.listTracks()).toHaveLength(2);
});
- it('removes a track from its album and ignores an album that no longer exists', async () => {
- const { track, album } = seedAssignedTrack();
- await removeTrackFromAlbum(track.id, album.id);
- expect(records.albums.get(album.id).trackIds).toEqual([]);
- await expect(removeTrackFromAlbum(track.id, 'album-missing')).resolves.toBeUndefined();
+ it('explicitly requires reconciliation when a failed file write cannot be restored', async () => {
+ const album = await createAlbum();
+ await createTrack(album.id);
+ failure.writes = ['tracks.json', 'albums.json'];
+ const response = await request(app).delete(`/api/albums/${album.id}`);
+ expect(response.status).toBe(500);
+ expect(response.body.code).toBe('MUSIC_MEMBERSHIP_RECONCILIATION_REQUIRED');
+ expect(response.body.error).toContain('before retrying');
});
});
diff --git a/server/services/tracks/db.js b/server/services/tracks/db.js
index 0196d9802c..fa40783be8 100644
--- a/server/services/tracks/db.js
+++ b/server/services/tracks/db.js
@@ -52,15 +52,17 @@ async function persist(exec, track) {
return track;
}
-export async function listTracks({ includeDeleted = false } = {}) {
+export async function listTracks({ includeDeleted = false, client } = {}) {
+ const exec = client ? client.query.bind(client) : query;
const { rows } = includeDeleted
- ? await query(`SELECT data FROM tracks ORDER BY created_at ASC`)
- : await query(`SELECT data FROM tracks WHERE deleted = FALSE ORDER BY created_at ASC`);
+ ? await exec(`SELECT data FROM tracks ORDER BY created_at ASC${client ? ' FOR UPDATE' : ''}`)
+ : await exec(`SELECT data FROM tracks WHERE deleted = FALSE ORDER BY created_at ASC${client ? ' FOR UPDATE' : ''}`);
return rows.map(rowToTrack);
}
-export async function getTrack(id, { includeDeleted = false } = {}) {
- const { rows } = await query(`SELECT data FROM tracks WHERE id = $1`, [id]);
+export async function getTrack(id, { includeDeleted = false, client } = {}) {
+ const exec = client ? client.query.bind(client) : query;
+ const { rows } = await exec(`SELECT data FROM tracks WHERE id = $1${client ? ' FOR UPDATE' : ''}`, [id]);
const track = rowToTrack(rows[0]);
if (!track) return null;
return includeDeleted || !track.deleted ? track : null;
@@ -74,16 +76,16 @@ export async function listTrackIds({ includeDeleted = false } = {}) {
return rows.map((r) => r.id);
}
-export async function createTrack(input) {
+export async function createTrack(input, { client } = {}) {
const track = buildTrackRecord(input, { id: `track-${randomUUID()}`, now: new Date().toISOString() });
if (!track) throw new ServerError('Invalid track payload', { status: 400, code: 'VALIDATION' });
- await persist(query, track);
+ await persist(client ? client.query.bind(client) : query, track);
console.log(`🎵 Created track: ${track.id} (${track.title})`);
return track;
}
-export async function updateTrack(id, patch) {
- return withTransaction(async (client) => {
+export async function updateTrack(id, patch, { client: transactionClient } = {}) {
+ const mutate = async (client) => {
const sel = await client.query(`SELECT data FROM tracks WHERE id = $1 FOR UPDATE`, [id]);
const current = rowToTrack(sel.rows[0]);
if (!current || current.deleted) throw new ServerError('Track not found', { status: 404, code: 'NOT_FOUND' });
@@ -91,11 +93,12 @@ export async function updateTrack(id, patch) {
if (!next) throw new ServerError('Invalid track payload', { status: 400, code: 'VALIDATION' });
await persist(client.query.bind(client), next);
return next;
- });
+ };
+ return transactionClient ? mutate(transactionClient) : withTransaction(mutate);
}
-export async function deleteTrack(id) {
- return withTransaction(async (client) => {
+export async function deleteTrack(id, { client: transactionClient } = {}) {
+ const mutate = async (client) => {
const sel = await client.query(`SELECT data FROM tracks WHERE id = $1 FOR UPDATE`, [id]);
const current = rowToTrack(sel.rows[0]);
if (!current || current.deleted) throw new ServerError('Track not found', { status: 404, code: 'NOT_FOUND' });
@@ -103,7 +106,8 @@ export async function deleteTrack(id) {
const next = { ...current, deleted: true, deletedAt: now, updatedAt: now };
await persist(client.query.bind(client), next);
return { id };
- });
+ };
+ return transactionClient ? mutate(transactionClient) : withTransaction(mutate);
}
/**
diff --git a/server/services/tracks/file.js b/server/services/tracks/file.js
index 70478f5515..44240b85e7 100644
--- a/server/services/tracks/file.js
+++ b/server/services/tracks/file.js
@@ -10,6 +10,7 @@
import { join } from 'path';
import { randomUUID } from 'crypto';
import { PATHS, readJSONFile, atomicWrite, ensureDir } from '../../lib/fileUtils.js';
+import { readMusicFile, writeMusicFile } from '../musicMembershipMutation.js';
import { ServerError } from '../../lib/errorHandler.js';
import { sanitizeTrack, buildTrackRecord, applyTrackPatch, mergeTrackRecord } from './logic.js';
import {
@@ -20,14 +21,18 @@ import {
const TRACKS_FILE = join(PATHS.data, 'tracks.json');
async function loadAll() {
- // Tracks are durable user records; never save an empty fallback over unreadable bytes.
- const raw = await readJSONFile(TRACKS_FILE, [], { strict: true });
- return (Array.isArray(raw) ? raw : []).map(sanitizeTrack).filter(Boolean);
+ return readMusicFile('tracks', async () => {
+ // Tracks are durable user records; never save an empty fallback over unreadable bytes.
+ const raw = await readJSONFile(TRACKS_FILE, [], { strict: true });
+ return (Array.isArray(raw) ? raw : []).map(sanitizeTrack).filter(Boolean);
+ });
}
async function saveAll(tracks) {
- await ensureDir(PATHS.data);
- await atomicWrite(TRACKS_FILE, tracks);
+ return writeMusicFile('tracks', tracks, async (records) => {
+ await ensureDir(PATHS.data);
+ await atomicWrite(TRACKS_FILE, records);
+ });
}
// Tracks list in creation order (the album's trackIds drive display order).
diff --git a/server/services/tracks/index.js b/server/services/tracks/index.js
index 9482e25a26..8571ddc1f3 100644
--- a/server/services/tracks/index.js
+++ b/server/services/tracks/index.js
@@ -12,6 +12,7 @@
import { randomUUID } from 'crypto';
import { createRecordStoreBackendSelector } from '../../lib/pgFileFacade.js';
+import { withMusicMutation, musicMutationClient, afterMusicCommit } from '../musicMembershipMutation.js';
import { emitRecordUpdated, emitRecordDeleted, autoSubscribeRecordToAllPeers } from '../sharing/recordEvents.js';
import { makeRender as makeRenderLogic } from './logic.js';
@@ -82,6 +83,9 @@ export function appendActiveTake(trackId, { audioFilename, engine, prompt, durat
return run;
}
+// The shared mutation boundary prepares both stores before reserving a client.
+export { selectBackend as prepareTracksBackend };
+
/** Name of the active backend, or null before first call (for diagnostics/tests). */
export function getTracksBackendName() {
return getBackendName();
@@ -93,7 +97,7 @@ export function _resetTracksBackend() {
}
export async function listTracks(options = {}) {
- return (await selectBackend()).listTracks(options);
+ return (await selectBackend()).listTracks({ ...options, client: musicMutationClient() });
}
export async function listTrackIds(options = {}) {
@@ -101,7 +105,7 @@ export async function listTrackIds(options = {}) {
}
export async function getTrack(id, options = {}) {
- return (await selectBackend()).getTrack(id, options);
+ return (await selectBackend()).getTrack(id, { ...options, client: musicMutationClient() });
}
function announceNewTrack(id) {
@@ -110,21 +114,27 @@ function announceNewTrack(id) {
}
export async function createTrack(input) {
- const track = await (await selectBackend()).createTrack(input);
- announceNewTrack(track.id);
- return track;
+ return withMusicMutation(async () => {
+ const track = await (await selectBackend()).createTrack(input, { client: musicMutationClient() });
+ afterMusicCommit(() => announceNewTrack(track.id));
+ return track;
+ });
}
export async function updateTrack(id, patch) {
- const next = await (await selectBackend()).updateTrack(id, patch);
- emitRecordUpdated('track', next.id);
- return next;
+ return withMusicMutation(async () => {
+ const next = await (await selectBackend()).updateTrack(id, patch, { client: musicMutationClient() });
+ afterMusicCommit(() => emitRecordUpdated('track', next.id));
+ return next;
+ });
}
export async function deleteTrack(id) {
- const result = await (await selectBackend()).deleteTrack(id);
- emitRecordDeleted('track', result.id);
- return result;
+ return withMusicMutation(async () => {
+ const result = await (await selectBackend()).deleteTrack(id, { client: musicMutationClient() });
+ afterMusicCommit(() => emitRecordDeleted('track', result.id));
+ return result;
+ });
}
/** Merge an incoming batch of track records from a peer (LWW, tombstone-aware). */