Merge pull request 'feat(web): bulk jobs in the admin area (F3d)' (#79) from feat/admin-jobs into main

This commit is contained in:
squidd 2026-11-12 15:38:24 +01:00
commit e018bfde38
12 changed files with 742 additions and 3 deletions

View file

@ -27,7 +27,7 @@ It is a single executable, one database (SQLite by default, PostgreSQL if you pr
## What is not there yet
Radio queues, OpenSubsonic compatibility, transcoding, and the ListenBrainz integration. The web client exists (see [Web app](#web-app)) but `sondad` does not serve it yet, and its admin area covers libraries, scanning, users and the external providers so far (the bulk jobs are still API-only).
Radio queues, OpenSubsonic compatibility, transcoding, and the ListenBrainz integration. The web client exists (see [Web app](#web-app)) but `sondad` does not serve it yet, and its admin area covers everything the API can do for an admin: libraries and scanning, users, the external providers and the bulk jobs.
## Requirements
@ -328,9 +328,9 @@ npm install
SONDA_URL=http://127.0.0.1:8080 npm run dev # open http://localhost:5173, /api is proxied to Sonda
```
What it does today: sign in (and create the first account of a new server), browse artists, albums and songs, search, and play with a queue, shuffle, repeat, media keys, a volume slider with mute (remembered in the browser) and a full-screen player. Artist pages show the Wikipedia text, similar artists and tags when those providers are on, each with its credit, and the photo credit next to the photo. It reports one listen per play. Discover suggests artists from the ones you pick, or from your listening only after you allow it (a dialog says that their names go to Last.fm), explains each score, and keeps your wishlist and the artists you are not interested in. An admin who set up the `lidarr` provider gets a "Request on Lidarr" button on an artist's page and on the Discover cards: it asks first, then sends that one artist to their own Lidarr, which does the downloading (the web app downloads nothing; the page of an artist reads what Lidarr has, the cards ask nothing until you send). An admin also gets an Admin area to add, rename, move and remove libraries and to start a scan (of one library or all, optionally reading every file again) and follow it, and to manage accounts: add one by email, give or take away the admin role, reset a password (which ends that person's sessions) and delete an account. The last admin cannot be changed, and your own account has no buttons there. Providers have a card each that says what the provider is sent: turning one on asks first, the API key is write-only (never shown, and gone from the page once saved), and there are a test of the key, the contact or address, removing what a provider gave, and, for Lidarr, the profiles and root folder to use when an artist is added. There are six themes (Sonda, Tokyo Night, Gruvbox dark, Gruvbox light, Dracula and Neon) and two languages (English and Italian), both chosen in Settings.
What it does today: sign in (and create the first account of a new server), browse artists, albums and songs, search, and play with a queue, shuffle, repeat, media keys, a volume slider with mute (remembered in the browser) and a full-screen player. Artist pages show the Wikipedia text, similar artists and tags when those providers are on, each with its credit, and the photo credit next to the photo. It reports one listen per play. Discover suggests artists from the ones you pick, or from your listening only after you allow it (a dialog says that their names go to Last.fm), explains each score, and keeps your wishlist and the artists you are not interested in. An admin who set up the `lidarr` provider gets a "Request on Lidarr" button on an artist's page and on the Discover cards: it asks first, then sends that one artist to their own Lidarr, which does the downloading (the web app downloads nothing; the page of an artist reads what Lidarr has, the cards ask nothing until you send). An admin also gets an Admin area to add, rename, move and remove libraries and to start a scan (of one library or all, optionally reading every file again) and follow it, and to manage accounts: add one by email, give or take away the admin role, reset a password (which ends that person's sessions) and delete an account. The last admin cannot be changed, and your own account has no buttons there. Providers have a card each that says what the provider is sent: turning one on asks first, the API key is write-only (never shown, and gone from the page once saved), and there are a test of the key, the contact or address, removing what a provider gave, and, for Lidarr, the profiles and root folder to use when an artist is added. The bulk jobs (album covers, artist pictures, artist descriptions) each have a card that says what the job sends and to whom: starting one asks first and says it goes through the whole library, reading everything again is a separate choice, a job whose providers are off cannot be started, and the page follows its progress and can stop it. There are six themes (Sonda, Tokyo Night, Gruvbox dark, Gruvbox light, Dracula and Neon) and two languages (English and Italian), both chosen in Settings.
More commands, all run in `web/`: `npm test`, `npm run build`, and `npm run gen:api`, which rebuilds `src/api/schema.d.ts` from the OpenAPI spec (it fetches the generator with `npx`, so it needs the network once). The bulk jobs screen and serving the app from the binary come later.
More commands, all run in `web/`: `npm test`, `npm run build`, and `npm run gen:api`, which rebuilds `src/api/schema.d.ts` from the OpenAPI spec (it fetches the generator with `npx`, so it needs the network once). Serving the app from the binary comes later.
## Development

93
web/src/api/jobs.test.tsx Normal file
View file

@ -0,0 +1,93 @@
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { act, renderHook, waitFor } from '@testing-library/react'
import type { ReactNode } from 'react'
import { expect, test } from 'vitest'
import { apiError, mockFetch } from '@/test/mockFetch'
import { useJobStatus, useStartJob, useStopJob } from './jobs'
function setup() {
const client = new QueryClient({ defaultOptions: { queries: { retry: false }, mutations: { retry: false } } })
const wrapper = ({ children }: { children: ReactNode }) => <QueryClientProvider client={client}>{children}</QueryClientProvider>
return { client, wrapper }
}
const started = () => new Response(JSON.stringify({ status: 'started' }), { status: 202, headers: { 'Content-Type': 'application/json' } })
const none = () => new Response(null, { status: 204 })
test.each([
['covers', '/api/v1/library/covers'],
['artist-images', '/api/v1/library/artist-images'],
['descriptions', '/api/v1/library/descriptions'],
] as const)('the %s job is read from its own address', async (kind, path) => {
const { calls } = mockFetch({ [`GET ${path}`]: () => ({ running: false }) })
const { result } = renderHook(() => useJobStatus(kind), { wrapper: setup().wrapper })
await waitFor(() => expect(result.current.data).toEqual({ running: false }))
expect(calls.map((c) => c.key)).toEqual([`GET ${path}`])
})
test('while a job runs its status is read again and again, and it stops by itself when the job ends', async () => {
let n = 0
const { calls } = mockFetch({
'GET /api/v1/library/covers': () => (++n < 3 ? { running: true, progress: { done: n, total: 10 } } : { running: false }),
})
const { result } = renderHook(() => useJobStatus('covers', { intervalMs: 20 }), { wrapper: setup().wrapper })
await waitFor(() => expect(result.current.data?.running).toBe(false), { timeout: 2000 })
const seen = calls.length
await new Promise((r) => setTimeout(r, 120))
expect(calls).toHaveLength(seen)
expect(seen).toBe(3)
})
test.each([
['covers', '/api/v1/library/covers'],
['artist-images', '/api/v1/library/artist-images'],
['descriptions', '/api/v1/library/descriptions'],
] as const)('starting the %s job is a POST that reads everything again only when asked', async (kind, path) => {
const { calls } = mockFetch({ [`POST ${path}`]: started, [`GET ${path}`]: () => ({ running: true }) })
const { result } = renderHook(() => useStartJob(kind), { wrapper: setup().wrapper })
await act(() => result.current.mutateAsync({ refresh: false }))
await act(() => result.current.mutateAsync({ refresh: true }))
const posts = calls.filter((c) => c.key === `POST ${path}`)
expect(posts[0].url.searchParams.has('refresh')).toBe(false)
expect(posts[1].url.searchParams.get('refresh')).toBe('true')
})
test('starting a job makes its status be read at once, so the page follows it', async () => {
let running = false
const { calls } = mockFetch({
'GET /api/v1/library/covers': () => ({ running }),
'POST /api/v1/library/covers': () => {
running = true
return started()
},
})
const { wrapper } = setup()
const { result } = renderHook(() => ({ status: useJobStatus('covers', { intervalMs: 20 }), start: useStartJob('covers') }), { wrapper })
await waitFor(() => expect(result.current.status.data?.running).toBe(false))
await act(() => result.current.start.mutateAsync({ refresh: false }))
await waitFor(() => expect(result.current.status.data?.running).toBe(true))
expect(calls.filter((c) => c.key === 'GET /api/v1/library/covers').length).toBeGreaterThanOrEqual(2)
})
test('a job already running is refused, and the status is still read so the page follows the one that runs', async () => {
const { calls } = mockFetch({
'POST /api/v1/library/descriptions': () => apiError(409, 'descriptions_job_running'),
'GET /api/v1/library/descriptions': () => ({ running: true }),
})
const { result } = renderHook(() => ({ status: useJobStatus('descriptions', { intervalMs: 5000 }), start: useStartJob('descriptions') }), {
wrapper: setup().wrapper,
})
await waitFor(() => expect(result.current.status.isSuccess).toBe(true))
await act(() => result.current.start.mutateAsync({ refresh: false }).catch(() => undefined))
await waitFor(() => expect(calls.filter((c) => c.key === 'GET /api/v1/library/descriptions')).toHaveLength(2))
})
test('stopping is a DELETE and the status is read again', async () => {
const { calls } = mockFetch({ 'DELETE /api/v1/library/artist-images': none, 'GET /api/v1/library/artist-images': () => ({ running: false }) })
const { result } = renderHook(() => ({ status: useJobStatus('artist-images'), stop: useStopJob('artist-images') }), { wrapper: setup().wrapper })
await waitFor(() => expect(result.current.status.isSuccess).toBe(true))
await act(() => result.current.stop.mutateAsync())
await waitFor(() =>
expect(calls.map((c) => c.key)).toEqual(['GET /api/v1/library/artist-images', 'DELETE /api/v1/library/artist-images', 'GET /api/v1/library/artist-images']),
)
})

42
web/src/api/jobs.ts Normal file
View file

@ -0,0 +1,42 @@
import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
import { api } from './client'
import type { components } from './schema'
export type CoversJobStatus = components['schemas']['CoversJobStatus']
export type ArtistJobStatus = components['schemas']['ArtistJobStatus']
/** The bulk jobs that go through the whole library, each at its own address under `/library`. */
export type JobKind = 'covers' | 'artist-images' | 'descriptions'
export type JobStatus<K extends JobKind> = K extends 'covers' ? CoversJobStatus : ArtistJobStatus
const statusKey = (kind: JobKind) => ['library', kind]
/** Whether the job runs, how far it is, and how the last one ended. While it runs it is read again every `intervalMs`. */
export function useJobStatus<K extends JobKind>(kind: K, { intervalMs = 2000 }: { intervalMs?: number } = {}) {
return useQuery({
queryKey: statusKey(kind),
queryFn: () => api.get<JobStatus<K>>(`/library/${kind}`),
refetchInterval: (query) => (query.state.data?.running ? intervalMs : false),
})
}
/**
* Starts the job in the background. `refresh` goes through every item again, also those with a good answer.
* Whatever the answer (also "already running"), the status is read at once so the page follows the job.
*/
export function useStartJob(kind: JobKind) {
const client = useQueryClient()
return useMutation({
mutationFn: ({ refresh }: { refresh: boolean }) => api.post<{ status: 'started' }>(refresh ? `/library/${kind}?refresh=true` : `/library/${kind}`),
onSettled: () => client.invalidateQueries({ queryKey: statusKey(kind) }),
})
}
/** Asks the job to end after the item it is on. What it already did stays. */
export function useStopJob(kind: JobKind) {
const client = useQueryClient()
return useMutation({
mutationFn: () => api.del(`/library/${kind}`),
onSettled: () => client.invalidateQueries({ queryKey: statusKey(kind) }),
})
}

View file

@ -71,6 +71,29 @@ test('the admin area has a Providers section too', async () => {
expect(within(screen.getByRole('navigation', { name: 'Admin sections' })).getByRole('link', { name: 'Providers' })).toHaveAttribute('aria-current', 'page')
})
test('the admin area has a Jobs section too', async () => {
sessionStore.setState({ status: 'authenticated', user: { id: 1, email: 'tom@example.org', is_admin: true } })
mockFetch({
...adminRoutes,
'GET /api/v1/providers': () => ({ providers: [] }),
'GET /api/v1/library/covers': () => ({ running: false }),
'GET /api/v1/library/artist-images': () => ({ running: false }),
'GET /api/v1/library/descriptions': () => ({ running: false }),
})
renderAt('/admin/jobs')
expect(await screen.findByRole('region', { name: 'Jobs' })).toBeInTheDocument()
expect(within(screen.getByRole('navigation', { name: 'Admin sections' })).getByRole('link', { name: 'Jobs' })).toHaveAttribute('aria-current', 'page')
})
test('someone who is not an admin who opens the jobs address gets a notice and no request', async () => {
sessionStore.setState({ status: 'authenticated', user: { id: 2, email: 'ann@example.org', is_admin: false } })
const { calls } = mockFetch({ 'GET /api/v1/library/covers': () => ({ running: false }) })
renderAt('/admin/jobs')
expect(screen.getByText('Only admins can see this page.')).toBeInTheDocument()
await new Promise((r) => setTimeout(r, 30))
expect(calls).toHaveLength(0)
})
test('someone who is not an admin who opens the providers address gets a notice and no request', async () => {
sessionStore.setState({ status: 'authenticated', user: { id: 2, email: 'ann@example.org', is_admin: false } })
const { calls } = mockFetch({ 'GET /api/v1/providers': () => ({ providers: [] }) })

View file

@ -70,6 +70,65 @@
"sectionLibraries": "Libraries",
"sectionUsers": "Users",
"sectionProviders": "Providers",
"sectionJobs": "Jobs",
"jobs": {
"intro": "These jobs go through the whole library in the background, one item after the other. Each card says what it sends and to whom.",
"needs": "Needs {{names}} turned on: use the Providers section.",
"and": "and",
"refresh": "Do everything again",
"refreshHint": "Slower: asks again even for what already has an answer. A failure never replaces an answer that is stored.",
"start": "Start",
"startOne": "Start {{title}}",
"stop": "Stop",
"stopOne": "Stop {{title}}",
"confirmTitle": "Start {{title}}?",
"confirmBody": "This goes through the whole library. {{sends}}",
"confirmRefresh": "It asks again even for what already has an answer.",
"confirm": "Start job",
"progress": "{{done}} of {{total}}",
"last": "Last run",
"stopped": "It was stopped before the end.",
"finished": "Finished {{when}}",
"never": "This job has not run yet.",
"errors": {
"covers_job_running": "This job is already running.",
"artist_images_job_running": "This job is already running.",
"descriptions_job_running": "This job is already running."
},
"covers": {
"title": "Album covers",
"what": "Builds the cover of every album that has none that is still good: first from the pictures in your own files, then, only for albums with none there, from the Cover Art Archive if it is on.",
"sendsNothing": "Nothing leaves this server: it only reads the pictures in your own files.",
"sendsArchive": "The release group id of every album with no picture in your files goes to the Cover Art Archive, one after the other."
},
"artistImages": {
"title": "Artist pictures",
"what": "Looks for a free picture of every artist that has a MusicBrainz id and no answer that is still good.",
"sends": "The MusicBrainz id of every artist goes to MusicBrainz, Wikidata and Wikimedia Commons, one after the other."
},
"descriptions": {
"title": "Artist descriptions",
"what": "Reads the Wikipedia description of every artist that has a MusicBrainz id and no answer that is still good.",
"sends": "The MusicBrainz id of every artist goes to MusicBrainz, Wikidata and Wikipedia, one after the other."
},
"counts": {
"covers": {
"checked": "{{count}} looked at",
"from_files": "{{count}} from your files",
"from_archive": "{{count}} from the Cover Art Archive",
"none": "{{count}} with no cover",
"failed": "{{count}} could not be built",
"skipped": "{{count}} skipped"
},
"artists": {
"checked": "{{count}} looked at",
"found": "{{count}} found",
"none": "{{count}} with nothing at the provider",
"failed": "{{count}} could not be looked up",
"skipped": "{{count}} skipped"
}
}
},
"cancel": "Cancel",
"save": "Save",
"errors": {

View file

@ -70,6 +70,65 @@
"sectionLibraries": "Librerie",
"sectionUsers": "Utenti",
"sectionProviders": "Provider",
"sectionJobs": "Lavori",
"jobs": {
"intro": "Questi lavori passano in rassegna tutta la libreria in background, un elemento alla volta. Ogni scheda dice cosa manda e a chi.",
"needs": "Serve che {{names}} sia acceso: vai nella sezione Provider.",
"and": "e",
"refresh": "Rifai tutto",
"refreshHint": "Più lento: chiede di nuovo anche ciò che ha già una risposta. Un errore non sostituisce mai una risposta salvata.",
"start": "Avvia",
"startOne": "Avvia {{title}}",
"stop": "Ferma",
"stopOne": "Ferma {{title}}",
"confirmTitle": "Avviare {{title}}?",
"confirmBody": "Questo passa in rassegna tutta la libreria. {{sends}}",
"confirmRefresh": "Chiede di nuovo anche ciò che ha già una risposta.",
"confirm": "Avvia il lavoro",
"progress": "{{done}} di {{total}}",
"last": "Ultima esecuzione",
"stopped": "È stato fermato prima della fine.",
"finished": "Finito il {{when}}",
"never": "Questo lavoro non è ancora stato eseguito.",
"errors": {
"covers_job_running": "Questo lavoro è già in corso.",
"artist_images_job_running": "Questo lavoro è già in corso.",
"descriptions_job_running": "Questo lavoro è già in corso."
},
"covers": {
"title": "Copertine degli album",
"what": "Costruisce la copertina di ogni album che non ne ha una ancora buona: prima dalle immagini nei tuoi file, poi, solo per gli album che lì non ne hanno, dal Cover Art Archive se è acceso.",
"sendsNothing": "Dal server non esce niente: legge solo le immagini nei tuoi file.",
"sendsArchive": "L'id del release group di ogni album senza immagine nei tuoi file va al Cover Art Archive, uno dopo l'altro."
},
"artistImages": {
"title": "Immagini degli artisti",
"what": "Cerca un'immagine libera per ogni artista che ha un id MusicBrainz e nessuna risposta ancora buona.",
"sends": "L'id MusicBrainz di ogni artista va a MusicBrainz, Wikidata e Wikimedia Commons, uno dopo l'altro."
},
"descriptions": {
"title": "Descrizioni degli artisti",
"what": "Legge la descrizione di Wikipedia di ogni artista che ha un id MusicBrainz e nessuna risposta ancora buona.",
"sends": "L'id MusicBrainz di ogni artista va a MusicBrainz, Wikidata e Wikipedia, uno dopo l'altro."
},
"counts": {
"covers": {
"checked": "{{count}} esaminati",
"from_files": "{{count}} dai tuoi file",
"from_archive": "{{count}} dal Cover Art Archive",
"none": "{{count}} senza copertina",
"failed": "{{count}} non costruibili",
"skipped": "{{count}} saltati"
},
"artists": {
"checked": "{{count}} esaminati",
"found": "{{count}} trovati",
"none": "{{count}} senza niente dal provider",
"failed": "{{count}} non cercabili",
"skipped": "{{count}} saltati"
}
}
},
"cancel": "Annulla",
"save": "Salva",
"errors": {

View file

@ -9,6 +9,7 @@ const SECTIONS = [
{ to: '/admin/libraries', key: 'admin.sectionLibraries' },
{ to: '/admin/users', key: 'admin.sectionUsers' },
{ to: '/admin/providers', key: 'admin.sectionProviders' },
{ to: '/admin/jobs', key: 'admin.sectionJobs' },
]
/**

View file

@ -0,0 +1,209 @@
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { render, screen, waitFor, within } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { beforeEach, expect, test, vi } from 'vitest'
import type { JobKind } from '@/api/jobs'
import { sessionStore } from '@/auth/session'
import { initI18n } from '@/i18n'
import { apiError, mockFetch, type MockRoutes, type RecordedCall } from '@/test/mockFetch'
import JobCard from './JobCard'
const PATH = { covers: '/api/v1/library/covers', 'artist-images': '/api/v1/library/artist-images', descriptions: '/api/v1/library/descriptions' }
const TITLE = { covers: 'Album covers', 'artist-images': 'Artist pictures', descriptions: 'Artist descriptions' }
const started = () => new Response(JSON.stringify({ status: 'started' }), { status: 202, headers: { 'Content-Type': 'application/json' } })
const none = () => new Response(null, { status: 204 })
type Enabled = Partial<Record<string, boolean>>
function renderCard(kind: JobKind, enabled: Enabled = { musicbrainz: true, commons: true, wikipedia: true, coverartarchive: false }) {
const client = new QueryClient({ defaultOptions: { queries: { retry: false }, mutations: { retry: false } } })
return render(
<QueryClientProvider client={client}>
<JobCard kind={kind} enabled={enabled} />
</QueryClientProvider>,
)
}
function routes(kind: JobKind, status: object, over: MockRoutes = {}): MockRoutes {
return { [`GET ${PATH[kind]}`]: () => status, ...over }
}
const card = (kind: JobKind) => screen.findByRole('region', { name: TITLE[kind] })
const calls = (all: RecordedCall[], key: string) => all.filter((c) => c.key === key)
beforeEach(async () => {
vi.spyOn(navigator, 'language', 'get').mockReturnValue('en-US')
await initI18n()
sessionStore.setState({ status: 'authenticated', user: { id: 1, email: 'tom@example.org', is_admin: true } })
})
// --- what it is and what it sends --------------------------------------------------------------
test.each([
['covers', 'Nothing leaves this server: it only reads the pictures in your own files.'],
['artist-images', 'The MusicBrainz id of every artist goes to MusicBrainz, Wikidata and Wikimedia Commons, one after the other.'],
['descriptions', 'The MusicBrainz id of every artist goes to MusicBrainz, Wikidata and Wikipedia, one after the other.'],
] as const)('the %s card says what it sends before anything is started', async (kind, sends) => {
mockFetch(routes(kind, { running: false }))
renderCard(kind)
expect(await card(kind)).toHaveTextContent(sends)
})
test('the covers card says what leaves the server once the Cover Art Archive is on', async () => {
mockFetch(routes('covers', { running: false }))
renderCard('covers', { coverartarchive: true })
expect(await card('covers')).toHaveTextContent('The release group id of every album with no picture in your files goes to the Cover Art Archive, one after the other.')
})
test.each([
['artist-images', { musicbrainz: false, commons: true }, 'Needs MusicBrainz turned on: use the Providers section.'],
['artist-images', { musicbrainz: false, commons: false }, 'Needs MusicBrainz and Wikimedia Commons turned on: use the Providers section.'],
['descriptions', { musicbrainz: true, wikipedia: false }, 'Needs Wikipedia turned on: use the Providers section.'],
] as const)('a provider the %s job needs that is off blocks it, and the card says which: %j', async (kind, enabled, text) => {
mockFetch(routes(kind, { running: false }))
renderCard(kind, enabled)
const c = await card(kind)
expect(c).toHaveTextContent(text)
expect(within(c).getByRole('button', { name: `Start ${TITLE[kind]}` })).toBeDisabled()
})
test('while the providers are not known yet nothing blocks the job', async () => {
mockFetch(routes('artist-images', { running: false }))
renderCard('artist-images', {})
expect(within(await card('artist-images')).getByRole('button', { name: 'Start Artist pictures' })).toBeEnabled()
})
// --- starting ----------------------------------------------------------------------------------
test('starting asks first, says it goes through the whole library, and sends nothing until the answer is yes', async () => {
const all = mockFetch(routes('artist-images', { running: false }, { [`POST ${PATH['artist-images']}`]: started })).calls
renderCard('artist-images')
const c = await card('artist-images')
await userEvent.click(within(c).getByRole('button', { name: 'Start Artist pictures' }))
const dialog = await screen.findByRole('dialog')
expect(dialog).toHaveTextContent('Start Artist pictures?')
expect(dialog).toHaveTextContent('This goes through the whole library.')
expect(dialog).toHaveTextContent('The MusicBrainz id of every artist goes to MusicBrainz, Wikidata and Wikimedia Commons')
expect(calls(all, `POST ${PATH['artist-images']}`)).toHaveLength(0)
await userEvent.click(within(dialog).getByRole('button', { name: 'Cancel' }))
await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument())
expect(calls(all, `POST ${PATH['artist-images']}`)).toHaveLength(0)
})
test('yes starts the job, reading only what has no good answer', async () => {
const all = mockFetch(routes('descriptions', { running: false }, { [`POST ${PATH.descriptions}`]: started })).calls
renderCard('descriptions')
const c = await card('descriptions')
await userEvent.click(within(c).getByRole('button', { name: 'Start Artist descriptions' }))
await userEvent.click(within(await screen.findByRole('dialog')).getByRole('button', { name: 'Start job' }))
await waitFor(() => expect(calls(all, `POST ${PATH.descriptions}`)).toHaveLength(1))
expect(calls(all, `POST ${PATH.descriptions}`)[0].url.searchParams.has('refresh')).toBe(false)
})
test('"Do everything again" is a separate choice, said in the question and sent as refresh', async () => {
const all = mockFetch(routes('covers', { running: false }, { [`POST ${PATH.covers}`]: started })).calls
renderCard('covers')
const c = await card('covers')
await userEvent.click(within(c).getByRole('checkbox', { name: 'Do everything again' }))
await userEvent.click(within(c).getByRole('button', { name: 'Start Album covers' }))
const dialog = await screen.findByRole('dialog')
expect(dialog).toHaveTextContent('It asks again even for what already has an answer.')
await userEvent.click(within(dialog).getByRole('button', { name: 'Start job' }))
await waitFor(() => expect(calls(all, `POST ${PATH.covers}`)[0]?.url.searchParams.get('refresh')).toBe('true'))
})
test('a job that is already running is explained', async () => {
mockFetch(routes('covers', { running: false }, { [`POST ${PATH.covers}`]: () => apiError(409, 'covers_job_running') }))
renderCard('covers')
const c = await card('covers')
await userEvent.click(within(c).getByRole('button', { name: 'Start Album covers' }))
await userEvent.click(within(await screen.findByRole('dialog')).getByRole('button', { name: 'Start job' }))
expect(await within(c).findByRole('alert')).toHaveTextContent('This job is already running.')
})
test('another failure to start is said in words', async () => {
mockFetch(routes('covers', { running: false }, { [`POST ${PATH.covers}`]: () => apiError(500, 'internal') }))
renderCard('covers')
const c = await card('covers')
await userEvent.click(within(c).getByRole('button', { name: 'Start Album covers' }))
await userEvent.click(within(await screen.findByRole('dialog')).getByRole('button', { name: 'Start job' }))
expect(await within(c).findByRole('alert')).toHaveTextContent('Something went wrong. Try again.')
})
// --- running and stopping ----------------------------------------------------------------------
test('while it runs the card shows how far it is, cannot be started again, and can be stopped', async () => {
const all = mockFetch(routes('artist-images', { running: true, progress: { done: 30, total: 120 } }, { [`DELETE ${PATH['artist-images']}`]: none })).calls
renderCard('artist-images')
const c = await card('artist-images')
const bar = await within(c).findByRole('progressbar')
expect(bar).toHaveAttribute('aria-valuenow', '30')
expect(bar).toHaveAttribute('aria-valuemax', '120')
expect(c).toHaveTextContent('30 of 120')
expect(within(c).getByRole('button', { name: 'Start Artist pictures' })).toBeDisabled()
await userEvent.click(within(c).getByRole('button', { name: 'Stop Artist pictures' }))
await waitFor(() => expect(calls(all, `DELETE ${PATH['artist-images']}`)).toHaveLength(1))
})
test('a job that is not running has no Stop button', async () => {
mockFetch(routes('covers', { running: false }))
renderCard('covers')
const c = await card('covers')
expect(within(c).queryByRole('button', { name: 'Stop Album covers' })).not.toBeInTheDocument()
})
// --- how it ended ------------------------------------------------------------------------------
test('after a covers job it says what was done, leaving out what is zero', async () => {
mockFetch(
routes('covers', {
running: false,
last_finished_at: '2026-11-12T10:00:00Z',
last: { checked: 40, from_files: 30, from_archive: 4, none: 5, skipped: 0, failed: 1, stopped: false },
}),
)
renderCard('covers')
const list = await within(await card('covers')).findByRole('list', { name: 'Last run' })
expect(list).toHaveTextContent('40 looked at')
expect(list).toHaveTextContent('30 from your files')
expect(list).toHaveTextContent('4 from the Cover Art Archive')
expect(list).toHaveTextContent('5 with no cover')
expect(list).toHaveTextContent('1 could not be built')
expect(list).not.toHaveTextContent('skipped')
})
test('after an artist job it says what was found', async () => {
mockFetch(
routes('descriptions', {
running: false,
last_finished_at: '2026-11-12T10:00:00Z',
last: { checked: 50, found: 35, none: 10, skipped: 2, failed: 3, stopped: false },
}),
)
renderCard('descriptions')
const list = await within(await card('descriptions')).findByRole('list', { name: 'Last run' })
expect(list).toHaveTextContent('50 looked at')
expect(list).toHaveTextContent('35 found')
expect(list).toHaveTextContent('10 with nothing at the provider')
expect(list).toHaveTextContent('3 could not be looked up')
expect(list).toHaveTextContent('2 skipped')
})
test('a job that was stopped says so', async () => {
mockFetch(routes('covers', { running: false, last: { checked: 3, from_files: 3, from_archive: 0, none: 0, skipped: 0, failed: 0, stopped: true } }))
renderCard('covers')
expect(await within(await card('covers')).findByText('It was stopped before the end.')).toBeInTheDocument()
})
test('the reason a job ended early is shown as it is', async () => {
mockFetch(routes('artist-images', { running: false, last_error: 'the providers failed for five artists in a row' }))
renderCard('artist-images')
expect(await within(await card('artist-images')).findByRole('alert')).toHaveTextContent('the providers failed for five artists in a row')
})
test('before the first run it says so', async () => {
mockFetch(routes('covers', { running: false }))
renderCard('covers')
expect(await within(await card('covers')).findByText('This job has not run yet.')).toBeInTheDocument()
})

View file

@ -0,0 +1,153 @@
import { useState } from 'react'
import { useTranslation } from 'react-i18next'
import type { ProviderName } from '@/api/adminProviders'
import { useJobStatus, useStartJob, useStopJob, type JobKind } from '@/api/jobs'
import { ErrorMessage, Loading } from '@/components/Status'
import { Button } from '@/components/ui/button'
import Confirm from './Confirm'
import { errorText } from './errorText'
/** The providers a job cannot do without. With any of them off the job ends at once, so the card does not start it. */
const NEEDS: Record<JobKind, ProviderName[]> = {
covers: [],
'artist-images': ['musicbrainz', 'commons'],
descriptions: ['musicbrainz', 'wikipedia'],
}
/** The key of the job in the texts. */
const TEXT: Record<JobKind, string> = { covers: 'covers', 'artist-images': 'artistImages', descriptions: 'descriptions' }
const SCOPES = ['admin.jobs.errors', 'admin.errors']
type T = ReturnType<typeof useTranslation>['t']
/** What the last run did, as short sentences, leaving out what is zero (except what was looked at). */
function Summary({ kind, last, finishedAt }: { kind: JobKind; last: Record<string, number | boolean>; finishedAt?: string }) {
const { t, i18n } = useTranslation()
const keys = kind === 'covers' ? ['checked', 'from_files', 'from_archive', 'none', 'failed', 'skipped'] : ['checked', 'found', 'none', 'failed', 'skipped']
const rows = keys.filter((key) => key === 'checked' || Number(last[key]) > 0)
return (
<div className="flex flex-col gap-2">
<ul aria-label={t('admin.jobs.last')} className="flex flex-wrap gap-2">
{rows.map((key) => (
<li key={key} className="rounded-md bg-secondary px-3 py-1 text-sm font-semibold">
{t(`admin.jobs.counts.${kind === 'covers' ? 'covers' : 'artists'}.${key}`, { count: Number(last[key]) })}
</li>
))}
</ul>
{last.stopped === true && <p className="text-sm font-semibold">{t('admin.jobs.stopped')}</p>}
{finishedAt && <p className="text-sm text-muted-foreground">{t('admin.jobs.finished', { when: new Date(finishedAt).toLocaleString(i18n.language) })}</p>}
</div>
)
}
/** What the job sends, in words: for covers it depends on whether the Cover Art Archive is on. */
function sends(t: T, kind: JobKind, enabled: Partial<Record<string, boolean>>): string {
if (kind === 'covers') return t(enabled.coverartarchive ? 'admin.jobs.covers.sendsArchive' : 'admin.jobs.covers.sendsNothing')
return t(`admin.jobs.${TEXT[kind]}.sends`)
}
/**
* One bulk job: what it does and what it sends, start (after a question that says it goes through the whole
* library), progress, stop, and how the last run ended. The status follows the job by itself while it runs.
*/
export default function JobCard({ kind, enabled }: { kind: JobKind; enabled: Partial<Record<string, boolean>> }) {
const { t } = useTranslation()
const status = useJobStatus(kind)
const start = useStartJob(kind)
const stop = useStopJob(kind)
const [asking, setAsking] = useState(false)
const [refresh, setRefresh] = useState(false)
const title = t(`admin.jobs.${TEXT[kind]}.title`)
const running = status.data?.running === true
const off = NEEDS[kind].filter((name) => enabled[name] === false)
const progress = status.data?.progress
const last = status.data?.last as Record<string, number | boolean> | undefined
const failure = start.error ?? stop.error
return (
<section aria-label={title} className="flex flex-col gap-4 rounded-lg bg-card p-5 text-card-foreground">
<h3 className="text-xl font-bold">{title}</h3>
<p className="text-sm">{t(`admin.jobs.${TEXT[kind]}.what`)}</p>
<p className="text-sm font-semibold">{sends(t, kind, enabled)}</p>
{off.length > 0 && (
<p className="text-sm text-muted-foreground">
{t('admin.jobs.needs', { names: off.map((name) => t(`provider.${name}`)).join(` ${t('admin.jobs.and')} `) })}
</p>
)}
<label className="flex min-h-11 items-center gap-3 font-semibold">
<input type="checkbox" checked={refresh} onChange={(e) => setRefresh(e.target.checked)} className="size-5 accent-primary" />
{t('admin.jobs.refresh')}
</label>
<p className="-mt-3 text-sm text-muted-foreground">{t('admin.jobs.refreshHint')}</p>
<div className="flex flex-wrap gap-3">
<Button disabled={running || off.length > 0 || start.isPending} aria-label={t('admin.jobs.startOne', { title })} onClick={() => setAsking(true)}>
{t('admin.jobs.start')}
</Button>
{running && (
<Button variant="outline" disabled={stop.isPending} aria-label={t('admin.jobs.stopOne', { title })} onClick={() => stop.mutate()}>
{t('admin.jobs.stop')}
</Button>
)}
</div>
{failure ? (
<p role="alert" className="text-sm text-destructive">
{errorText(t, failure, SCOPES)}
</p>
) : null}
{status.isError ? (
<ErrorMessage error={status.error} onRetry={() => void status.refetch()} />
) : status.isPending ? (
<Loading />
) : running ? (
<div className="flex flex-col gap-2">
{progress && (
<>
<div
role="progressbar"
aria-label={title}
aria-valuemin={0}
aria-valuemax={progress.total}
aria-valuenow={progress.done}
className="h-2 w-full max-w-xl overflow-hidden rounded-sm bg-secondary"
>
<div className="h-full bg-primary" style={{ width: `${progress.total > 0 ? Math.min(100, (progress.done / progress.total) * 100) : 0}%` }} />
</div>
<p role="status" className="text-sm font-semibold tabular-nums">
{t('admin.jobs.progress', { done: progress.done, total: progress.total })}
</p>
</>
)}
</div>
) : (
<>
{last && <Summary kind={kind} last={last} finishedAt={status.data.last_finished_at} />}
{status.data.last_error && (
<p role="alert" className="text-sm text-destructive">
{status.data.last_error}
</p>
)}
{!last && !status.data.last_error && <p className="text-sm text-muted-foreground">{t('admin.jobs.never')}</p>}
</>
)}
{asking && (
<Confirm
title={t('admin.jobs.confirmTitle', { title })}
body={`${t('admin.jobs.confirmBody', { sends: sends(t, kind, enabled) })}${refresh ? ` ${t('admin.jobs.confirmRefresh')}` : ''}`}
confirm={t('admin.jobs.confirm')}
onClose={() => setAsking(false)}
onConfirm={() => {
start.mutate({ refresh })
setAsking(false)
}}
/>
)}
</section>
)
}

View file

@ -0,0 +1,70 @@
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { render, screen, waitFor, within } from '@testing-library/react'
import { beforeEach, expect, test, vi } from 'vitest'
import { sessionStore } from '@/auth/session'
import { initI18n } from '@/i18n'
import { apiError, mockFetch, type MockRoutes } from '@/test/mockFetch'
import JobsPage from './JobsPage'
const provider = (name: string, enabled: boolean) => ({
name,
enabled,
needs_api_key: false,
needs_url: false,
has_api_key: false,
contact: '',
url: '',
sends: '',
notes: '',
updated_at: null,
})
function routes(enabled: Record<string, boolean>, over: MockRoutes = {}): MockRoutes {
return {
'GET /api/v1/providers': () => ({ providers: Object.entries(enabled).map(([name, on]) => provider(name, on)) }),
'GET /api/v1/library/covers': () => ({ running: false }),
'GET /api/v1/library/artist-images': () => ({ running: false }),
'GET /api/v1/library/descriptions': () => ({ running: false }),
...over,
}
}
function renderPage() {
const client = new QueryClient({ defaultOptions: { queries: { retry: false }, mutations: { retry: false } } })
return render(
<QueryClientProvider client={client}>
<JobsPage />
</QueryClientProvider>,
)
}
beforeEach(async () => {
vi.spyOn(navigator, 'language', 'get').mockReturnValue('en-US')
await initI18n()
sessionStore.setState({ status: 'authenticated', user: { id: 1, email: 'tom@example.org', is_admin: true } })
})
test('it says what the jobs are and shows the three of them', async () => {
mockFetch(routes({ musicbrainz: true, commons: true, wikipedia: true, coverartarchive: false }))
renderPage()
expect(await screen.findByText(/These jobs go through the whole library in the background/)).toBeInTheDocument()
const names = (await screen.findAllByRole('heading', { level: 3 })).map((h) => h.textContent)
expect(names).toEqual(['Album covers', 'Artist pictures', 'Artist descriptions'])
})
test('a provider that is off blocks the jobs that need it, read from the server', async () => {
mockFetch(routes({ musicbrainz: true, commons: false, wikipedia: true, coverartarchive: false }))
renderPage()
const pictures = await screen.findByRole('region', { name: 'Artist pictures' })
await waitFor(() => expect(within(pictures).getByRole('button', { name: 'Start Artist pictures' })).toBeDisabled())
expect(pictures).toHaveTextContent('Needs Wikimedia Commons turned on')
const descriptions = screen.getByRole('region', { name: 'Artist descriptions' })
expect(within(descriptions).getByRole('button', { name: 'Start Artist descriptions' })).toBeEnabled()
})
test('the jobs still show, and are not blocked, when the providers cannot be read', async () => {
mockFetch(routes({}, { 'GET /api/v1/providers': () => apiError(500, 'internal') }))
renderPage()
const pictures = await screen.findByRole('region', { name: 'Artist pictures' })
expect(within(pictures).getByRole('button', { name: 'Start Artist pictures' })).toBeEnabled()
})

View file

@ -0,0 +1,28 @@
import { useTranslation } from 'react-i18next'
import { useProviders } from '@/api/adminProviders'
import type { JobKind } from '@/api/jobs'
import Section from '@/components/Section'
import JobCard from './JobCard'
const JOBS: JobKind[] = ['covers', 'artist-images', 'descriptions']
/**
* The bulk jobs, one card each. It reads which providers are on, to block a job whose provider is off; when
* they cannot be read nothing is blocked (the server would end such a job at once and say why).
*/
export default function JobsPage() {
const { t } = useTranslation()
const providers = useProviders()
const enabled = Object.fromEntries((providers.data ?? []).map((p) => [p.name, p.enabled]))
return (
<Section title={t('admin.sectionJobs')}>
<p className="max-w-2xl text-sm text-muted-foreground">{t('admin.jobs.intro')}</p>
<div className="flex flex-col gap-4">
{JOBS.map((kind) => (
<JobCard key={kind} kind={kind} enabled={enabled} />
))}
</div>
</Section>
)
}

View file

@ -7,6 +7,7 @@ import ArtistsPage from '@/pages/ArtistsPage'
import DiscoverPage from '@/pages/DiscoverPage'
import HomePage from '@/pages/HomePage'
import AdminLayout from '@/pages/admin/AdminLayout'
import JobsPage from '@/pages/admin/JobsPage'
import LibrariesPage from '@/pages/admin/LibrariesPage'
import ProvidersPage from '@/pages/admin/ProvidersPage'
import UsersPage from '@/pages/admin/UsersPage'
@ -36,6 +37,7 @@ export const routes: RouteObject[] = [
{ path: 'libraries', element: <LibrariesPage /> },
{ path: 'users', element: <UsersPage /> },
{ path: 'providers', element: <ProvidersPage /> },
{ path: 'jobs', element: <JobsPage /> },
],
},
{ path: '*', element: <NotFoundPage /> },