feat(offline): make the web UI usable without a reachable backend
Three tiers of offline support, all scoped to the active backend's localStorage namespace (mirroring the auth slice): Tier 1 — persist client state. queue + player slices are saved (queue entries/index/source; player track/position/volume/repeat/shuffle) and rehydrated on load, so a reload with no backend restores where the user left off. Playback never auto-resumes (browsers block autoplay). Retires the DEMO_QUEUE and isQueueOpen:true stubs. Tier 2 — persist the RTK Query cache. Last-seen library/albums/artists are snapshotted (fulfilled queries only) and replayed via RTKQ's extractRehydrationInfo at startup, so the library renders read-only when the backend is down. ConnectionStatus tooltip flags cached data offline. No server data is copied into a slice — the cache feeds itself back. Tier 3 — service worker audio + cover cache (PWA). Audio streams are cached keyed by content id (token stripped), range-aware (synthetic 206 slicing), with a 500MB LRU cap, so already-played tracks play fully offline. Cover art uses stale-while-revalidate in its own bounded cache. Module worker (ESM); pure helpers split into sw-core.js and unit-tested. Web app manifest enables "Install app". Player source badge now reflects real cached state. tsc clean, lint clean, 19 new tests pass, production build verified. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Senko-san
@@ -0,0 +1,120 @@
|
||||
// @rstest-environment jsdom
|
||||
import { expect, test, beforeEach, rstest } from '@rstest/core';
|
||||
import {
|
||||
loadQueueState,
|
||||
loadPlayerState,
|
||||
startPersistence,
|
||||
} from '../src/store/persist';
|
||||
import { queueInitialState, type QueueState } from '../src/store/slices/queue';
|
||||
import {
|
||||
playerInitialState,
|
||||
type PlayerState,
|
||||
} from '../src/store/slices/player';
|
||||
import {
|
||||
upsertInstance,
|
||||
setActiveInstanceId,
|
||||
instanceStorage,
|
||||
} from '../src/config/instances';
|
||||
|
||||
beforeEach(() => {
|
||||
localStorage.clear();
|
||||
const inst = upsertInstance('http://test.local');
|
||||
setActiveInstanceId(inst.id);
|
||||
});
|
||||
|
||||
const sampleQueue: QueueState = {
|
||||
entries: [
|
||||
{
|
||||
trackId: 't1',
|
||||
title: 'A',
|
||||
artistName: 'X',
|
||||
albumTitle: 'Alb',
|
||||
durationMs: 1000,
|
||||
},
|
||||
{
|
||||
trackId: 't2',
|
||||
title: 'B',
|
||||
artistName: 'Y',
|
||||
albumTitle: 'Alb',
|
||||
durationMs: 2000,
|
||||
},
|
||||
],
|
||||
currentIndex: 1,
|
||||
source: 'album',
|
||||
sourceId: 'alb-1',
|
||||
sourceName: 'My Album',
|
||||
};
|
||||
|
||||
test('loaders fall back to initial state with nothing persisted', () => {
|
||||
expect(loadQueueState()).toEqual(queueInitialState);
|
||||
expect(loadPlayerState()).toEqual(playerInitialState);
|
||||
});
|
||||
|
||||
test('loadQueueState restores a persisted queue', () => {
|
||||
instanceStorage.set('queue', JSON.stringify(sampleQueue));
|
||||
expect(loadQueueState()).toEqual(sampleQueue);
|
||||
});
|
||||
|
||||
test('loadQueueState guards a currentIndex past the entries array', () => {
|
||||
instanceStorage.set(
|
||||
'queue',
|
||||
JSON.stringify({ ...sampleQueue, currentIndex: 99 }),
|
||||
);
|
||||
expect(loadQueueState().currentIndex).toBe(0);
|
||||
});
|
||||
|
||||
test('loadPlayerState restores fields but never auto-resumes playback', () => {
|
||||
instanceStorage.set(
|
||||
'player',
|
||||
JSON.stringify({
|
||||
currentTrackId: 't2',
|
||||
position: 42,
|
||||
volume: 0.5,
|
||||
muted: true,
|
||||
repeat: 'all',
|
||||
shuffle: true,
|
||||
// a stale isPlaying:true must not survive a reload
|
||||
isPlaying: true,
|
||||
}),
|
||||
);
|
||||
const loaded = loadPlayerState();
|
||||
expect(loaded.currentTrackId).toBe('t2');
|
||||
expect(loaded.position).toBe(42);
|
||||
expect(loaded.volume).toBe(0.5);
|
||||
expect(loaded.repeat).toBe('all');
|
||||
expect(loaded.isPlaying).toBe(false);
|
||||
});
|
||||
|
||||
test('corrupt JSON falls back to initial state', () => {
|
||||
instanceStorage.set('queue', '{not json');
|
||||
expect(loadQueueState()).toEqual(queueInitialState);
|
||||
});
|
||||
|
||||
test('startPersistence flushes changed state to storage after throttle', () => {
|
||||
rstest.useFakeTimers();
|
||||
let state = {
|
||||
queue: queueInitialState,
|
||||
player: playerInitialState,
|
||||
} as { queue: QueueState; player: PlayerState };
|
||||
let listener: (() => void) | null = null;
|
||||
const store = {
|
||||
getState: () => state as never,
|
||||
subscribe: (l: () => void) => {
|
||||
listener = l;
|
||||
return () => {};
|
||||
},
|
||||
};
|
||||
|
||||
startPersistence(store);
|
||||
|
||||
// mutate + notify
|
||||
state = { ...state, queue: sampleQueue };
|
||||
listener!();
|
||||
// nothing written before the throttle window elapses
|
||||
expect(instanceStorage.get('queue')).toBeNull();
|
||||
|
||||
rstest.advanceTimersByTime(1000);
|
||||
expect(JSON.parse(instanceStorage.get('queue')!).currentIndex).toBe(1);
|
||||
|
||||
rstest.useRealTimers();
|
||||
});
|
||||
@@ -0,0 +1,82 @@
|
||||
// @rstest-environment jsdom
|
||||
import { expect, test, beforeEach, rstest } from '@rstest/core';
|
||||
import {
|
||||
rehydrateApiCache,
|
||||
startApiPersistence,
|
||||
} from '../src/store/rtkqPersist';
|
||||
import { REHYDRATE_API } from '../src/api/rehydrate';
|
||||
import {
|
||||
upsertInstance,
|
||||
setActiveInstanceId,
|
||||
instanceStorage,
|
||||
} from '../src/config/instances';
|
||||
import type { RootState } from '../src/store/index';
|
||||
|
||||
beforeEach(() => {
|
||||
localStorage.clear();
|
||||
const inst = upsertInstance('http://test.local');
|
||||
setActiveInstanceId(inst.id);
|
||||
});
|
||||
|
||||
function apiStateWith(queries: Record<string, unknown>) {
|
||||
return {
|
||||
api: { queries, mutations: {}, provided: {}, subscriptions: {}, config: {} },
|
||||
} as unknown as RootState;
|
||||
}
|
||||
|
||||
test('rehydrateApiCache dispatches nothing when no cache is stored', () => {
|
||||
const dispatched: unknown[] = [];
|
||||
rehydrateApiCache((a) => dispatched.push(a));
|
||||
expect(dispatched).toHaveLength(0);
|
||||
});
|
||||
|
||||
test('rehydrateApiCache replays a stored cache as a rehydrate action', () => {
|
||||
instanceStorage.set(
|
||||
'rtkq',
|
||||
JSON.stringify({
|
||||
queries: { 'getLibrary(undefined)': { status: 'fulfilled', data: [1] } },
|
||||
mutations: {},
|
||||
}),
|
||||
);
|
||||
const dispatched: Array<{ type: string; payload: unknown }> = [];
|
||||
rehydrateApiCache((a) =>
|
||||
dispatched.push(a as { type: string; payload: unknown }),
|
||||
);
|
||||
expect(dispatched).toHaveLength(1);
|
||||
expect(dispatched[0].type).toBe(REHYDRATE_API);
|
||||
expect(dispatched[0].payload).toMatchObject({
|
||||
queries: { 'getLibrary(undefined)': { status: 'fulfilled' } },
|
||||
});
|
||||
});
|
||||
|
||||
test('startApiPersistence saves only fulfilled queries after throttle', () => {
|
||||
rstest.useFakeTimers();
|
||||
let state = apiStateWith({});
|
||||
let listener: (() => void) | null = null;
|
||||
const store = {
|
||||
getState: () => state,
|
||||
subscribe: (l: () => void) => {
|
||||
listener = l;
|
||||
return () => {};
|
||||
},
|
||||
};
|
||||
|
||||
startApiPersistence(store);
|
||||
|
||||
state = apiStateWith({
|
||||
'getAlbums(undefined)': { status: 'fulfilled', data: ['a'] },
|
||||
'getArtists(undefined)': { status: 'pending' },
|
||||
'getTracks(undefined)': { status: 'rejected', error: 'boom' },
|
||||
});
|
||||
listener!();
|
||||
|
||||
// throttled — nothing yet
|
||||
expect(instanceStorage.get('rtkq')).toBeNull();
|
||||
|
||||
rstest.advanceTimersByTime(2000);
|
||||
const saved = JSON.parse(instanceStorage.get('rtkq')!);
|
||||
expect(Object.keys(saved.queries)).toEqual(['getAlbums(undefined)']);
|
||||
expect(saved.mutations).toEqual({});
|
||||
|
||||
rstest.useRealTimers();
|
||||
});
|
||||
@@ -0,0 +1,79 @@
|
||||
import { expect, test } from '@rstest/core';
|
||||
import {
|
||||
trackIdFromUrl,
|
||||
cacheKeyFor,
|
||||
parseRangeHeader,
|
||||
selectEvictions,
|
||||
} from '../public/sw-core.js';
|
||||
|
||||
test('trackIdFromUrl extracts the content id from a stream URL', () => {
|
||||
expect(
|
||||
trackIdFromUrl('https://host/api/v1/streaming/tracks/abc123?token=xyz'),
|
||||
).toBe('abc123');
|
||||
expect(trackIdFromUrl('https://host/api/v1/library/albums')).toBeNull();
|
||||
});
|
||||
|
||||
test('cacheKeyFor strips the token so the key is token-stable', () => {
|
||||
const a = cacheKeyFor('https://host/api/v1/streaming/tracks/t1?token=AAA');
|
||||
const b = cacheKeyFor('https://host/api/v1/streaming/tracks/t1?token=BBB');
|
||||
expect(a).toBe(b);
|
||||
expect(a).toBe('https://host/api/v1/streaming/tracks/t1');
|
||||
});
|
||||
|
||||
test('cacheKeyFor keeps different origins distinct', () => {
|
||||
expect(cacheKeyFor('https://a/streaming/tracks/t1?token=x')).not.toBe(
|
||||
cacheKeyFor('https://b/streaming/tracks/t1?token=x'),
|
||||
);
|
||||
});
|
||||
|
||||
test('parseRangeHeader: closed range', () => {
|
||||
expect(parseRangeHeader('bytes=0-99', 1000)).toEqual({ start: 0, end: 99 });
|
||||
});
|
||||
|
||||
test('parseRangeHeader: open-ended range clamps to size', () => {
|
||||
expect(parseRangeHeader('bytes=500-', 1000)).toEqual({
|
||||
start: 500,
|
||||
end: 999,
|
||||
});
|
||||
});
|
||||
|
||||
test('parseRangeHeader: suffix range (last N bytes)', () => {
|
||||
expect(parseRangeHeader('bytes=-200', 1000)).toEqual({
|
||||
start: 800,
|
||||
end: 999,
|
||||
});
|
||||
});
|
||||
|
||||
test('parseRangeHeader: end past size is clamped', () => {
|
||||
expect(parseRangeHeader('bytes=900-5000', 1000)).toEqual({
|
||||
start: 900,
|
||||
end: 999,
|
||||
});
|
||||
});
|
||||
|
||||
test('parseRangeHeader: invalid / no range returns null', () => {
|
||||
expect(parseRangeHeader('', 1000)).toBeNull();
|
||||
expect(parseRangeHeader('items=0-1', 1000)).toBeNull();
|
||||
expect(parseRangeHeader('bytes=500-100', 1000)).toBeNull();
|
||||
});
|
||||
|
||||
test('selectEvictions: nothing evicted when under cap', () => {
|
||||
const index = {
|
||||
a: { size: 100, lastAccess: 1 },
|
||||
b: { size: 100, lastAccess: 2 },
|
||||
};
|
||||
expect(selectEvictions(index, 100, 1000)).toEqual([]);
|
||||
});
|
||||
|
||||
test('selectEvictions: evicts least-recently-used first until it fits', () => {
|
||||
const index = {
|
||||
a: { size: 400, lastAccess: 10 }, // oldest
|
||||
b: { size: 400, lastAccess: 30 },
|
||||
c: { size: 400, lastAccess: 20 },
|
||||
};
|
||||
// total 1200 + incoming 400 = 1600, cap 1000 → must free >=600.
|
||||
// LRU order: a (10), c (20). Evict a (1200→800... wait incl incoming)
|
||||
const evicted = selectEvictions(index, 400, 1000);
|
||||
// total with incoming = 1600; evict a → 1200; evict c → 800 <= 1000.
|
||||
expect(evicted).toEqual(['a', 'c']);
|
||||
});
|
||||
Reference in New Issue
Block a user