feat(library): remote browse status + save/materialize API (§Phase2-3)

Search results now report whether a hit is already saved (in_library,
track_id, availability). New RemoteLibraryService backs POST
/tracks/remote (idempotent placeholder save) and POST
/tracks/{id}/materialize (on-demand fetch via a new materialize_track
arq task, reusing in-flight jobs).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

app/api/deps.py

@@ -17,6 +17,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from app.application.auth_service import AuthService
 from app.application.download_service import DownloadService
 from app.application.metadata_service import MetadataEnrichmentService
+from app.application.remote_library_service import RemoteLibraryService
 from app.application.streaming_service import StreamingService
 from app.application.subsonic_auth_service import SubsonicAuthService
 from app.application.upload_service import UploadService
@@ -43,7 +44,7 @@ from app.infrastructure.metadata.fingerprint import FpcalcFingerprinter
 from app.infrastructure.metadata.tags import MutagenTagReader
 from app.infrastructure.sources.registry import SourceRegistry, build_source_registry
 from app.infrastructure.storage.provider import get_file_storage
-from app.workers.queue import enqueue_download, enqueue_enrich
+from app.workers.queue import enqueue_download, enqueue_enrich, enqueue_materialize
 
 
 async def get_session() -> AsyncIterator[AsyncSession]:
@@ -172,10 +173,20 @@ def get_download_service(session: SessionDep, storage: FileStorageDep) -> Downlo
     )
 
 
+def get_remote_library_service(session: SessionDep) -> RemoteLibraryService:
+    return RemoteLibraryService(
+        tracks=SqlAlchemyTrackRepository(session),
+        artists=SqlAlchemyArtistRepository(session),
+        jobs=SqlAlchemyDownloadJobRepository(session),
+        enqueue_materialize=enqueue_materialize,
+    )
+
+
 UploadServiceDep = Annotated[UploadService, Depends(get_upload_service)]
 StreamingServiceDep = Annotated[StreamingService, Depends(get_streaming_service)]
 MetadataServiceDep = Annotated[MetadataEnrichmentService, Depends(get_metadata_service)]
 DownloadServiceDep = Annotated[DownloadService, Depends(get_download_service)]
+RemoteLibraryServiceDep = Annotated[RemoteLibraryService, Depends(get_remote_library_service)]
 
 
 # -- library repository deps ---------------------------------------------------

app/api/schemas/external_search.py

@@ -1,7 +1,10 @@
 """Schemas for searching external (fetch) sources — the §A4 discover screen."""
 
+import uuid
+
 from pydantic import BaseModel
 
+from app.domain.entities.track import Track
 from app.domain.sources import SearchResult
 
 
@@ -13,9 +16,16 @@ class ExternalSearchResultOut(BaseModel):
     album: str | None
     duration_seconds: int | None
     thumbnail_url: str | None
+    # Remote browse (plan: Model C) — set when this hit is already saved in the
+    # library, so the UI can show "Play"/"Saved" instead of "Save to library".
+    in_library: bool
+    track_id: uuid.UUID | None
+    availability: str | None
 
     @classmethod
-    def from_entity(cls, r: SearchResult) -> ExternalSearchResultOut:
+    def from_entity(
+        cls, r: SearchResult, *, existing: Track | None = None
+    ) -> ExternalSearchResultOut:
         return cls(
             source=r.source,
             source_id=r.source_id,
@@ -24,6 +34,9 @@ class ExternalSearchResultOut(BaseModel):
             album=r.album,
             duration_seconds=r.duration_seconds,
             thumbnail_url=r.thumbnail_url,
+            in_library=existing is not None,
+            track_id=existing.id if existing is not None else None,
+            availability=existing.availability if existing is not None else None,
         )
 
 

app/api/schemas/track.py

@@ -3,7 +3,9 @@
 import datetime as dt
 import uuid
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
+
+from app.api.schemas.download import DownloadJobOut
 
 
 class TrackOut(BaseModel):
@@ -62,3 +64,24 @@ class MetadataApply(BaseModel):
     year: int | None = None
     genre: str | None = None
     track_number: int | None = None
+
+
+class RemoteTrackSave(BaseModel):
+    """Save a remote browse hit (§A4 discover) as a library placeholder —
+    ``availability="remote"``, no audio until first play (plan: Model C)."""
+
+    source: str
+    source_id: str = Field(min_length=1)
+    title: str
+    artist: str | None = None
+
+
+class MaterializeResponse(BaseModel):
+    """Result of requesting that a placeholder track's audio be fetched.
+
+    ``job`` is ``None`` when the track is already ``local`` — nothing to wait
+    for, the caller can stream immediately. Otherwise it's the (new or
+    already in-flight) job; poll ``GET /downloads/{job.id}`` until ``done``."""
+
+    track: TrackOut
+    job: DownloadJobOut | None

app/api/v1/search.py

@@ -18,6 +18,7 @@ router = APIRouter(prefix="/search", tags=["search"])
 async def search(
     _: CurrentUser,
     registry: SourceRegistryDep,
+    track_repo: TrackRepoDep,
     q: str = Query(min_length=1),
     limit: int = Query(20, ge=1, le=50),
 ) -> ExternalSearchResponse:
@@ -25,7 +26,9 @@ async def search(
 
     A source that is down contributes nothing rather than failing the whole
     request (graceful degradation); only available sources are reported as
-    searched."""
+    searched. Each hit is checked against the library by ``(source,
+    source_id)`` so the UI can show "Saved"/"Play" instead of "Save to
+    library" without a separate round-trip (remote browse, plan: Model C)."""
     results: list[ExternalSearchResultOut] = []
     searched: list[str] = []
     for backend in registry.searchables():
@@ -33,7 +36,9 @@ async def search(
             continue
         searched.append(backend.name)
         hits = await backend.search(q, limit=limit)
-        results.extend(ExternalSearchResultOut.from_entity(h) for h in hits)
+        for h in hits:
+            existing = await track_repo.get_by_source(h.source, h.source_id)
+            results.append(ExternalSearchResultOut.from_entity(h, existing=existing))
     return ExternalSearchResponse(results=results, searched_sources=searched)
 
 

app/api/v1/sources.py

@@ -6,7 +6,7 @@ is an admin action and runs in a worker — the endpoint only enqueues it.
 
 from fastapi import APIRouter, Query
 
-from app.api.deps import CurrentUser, SourceRegistryDep, SuperUser
+from app.api.deps import CurrentUser, SourceRegistryDep, SuperUser, TrackRepoDep
 from app.api.schemas.external_search import ExternalSearchResponse, ExternalSearchResultOut
 from app.api.schemas.source import ScanResponse, SourceHealthOut, SourceInfoOut
 from app.domain.errors import DependencyUnavailableError
@@ -42,6 +42,7 @@ async def search_source(
     source: str,
     _: CurrentUser,
     registry: SourceRegistryDep,
+    track_repo: TrackRepoDep,
     q: str = Query(min_length=1),
     limit: int = Query(20, ge=1, le=50),
 ) -> ExternalSearchResponse:
@@ -49,7 +50,8 @@ async def search_source(
     if not backend.is_available():
         raise DependencyUnavailableError(f"Source {source!r} is not available.")
     results = await backend.search(q, limit=limit)
-    return ExternalSearchResponse(
-        results=[ExternalSearchResultOut.from_entity(r) for r in results],
-        searched_sources=[source],
-    )
+    out: list[ExternalSearchResultOut] = []
+    for r in results:
+        existing = await track_repo.get_by_source(r.source, r.source_id)
+        out.append(ExternalSearchResultOut.from_entity(r, existing=existing))
+    return ExternalSearchResponse(results=out, searched_sources=[source])

app/api/v1/tracks.py

@@ -13,14 +13,18 @@ from app.api.deps import (
     CurrentUser,
     FileStorageDep,
     MetadataServiceDep,
+    RemoteLibraryServiceDep,
     StreamUser,
     TrackRepoDep,
 )
+from app.api.schemas.download import DownloadJobOut
 from app.api.schemas.pagination import PagedResponse
 from app.api.schemas.track import (
+    MaterializeResponse,
     MetadataApply,
     MetadataMatch,
     MetadataMatchesOut,
+    RemoteTrackSave,
     TrackOut,
     TrackUpdate,
 )
@@ -99,6 +103,57 @@ async def list_tracks(
     return PagedResponse(items=items, total=total, limit=limit, offset=offset)
 
 
+@router.post("/remote", status_code=201)
+async def save_remote_track(
+    body: RemoteTrackSave,
+    service: RemoteLibraryServiceDep,
+    artist_repo: ArtistRepoDep,
+    album_repo: AlbumRepoDep,
+    user: CurrentUser,
+) -> TrackOut:
+    """Save a remote browse hit (§A4 discover) as a library placeholder —
+    no audio is fetched yet (plan: Model C). Idempotent on ``(source,
+    source_id)``: saving an already-saved hit returns the existing track."""
+    track = await service.save_remote(
+        source=body.source,
+        source_id=body.source_id,
+        title=body.title,
+        artist=body.artist,
+        added_by=user.id,
+    )
+
+    artists = {a.id: a for a in await artist_repo.get_many([track.artist_id])}
+    album_ids = [track.album_id] if track.album_id else []
+    albums = {a.id: a for a in await album_repo.get_many(album_ids)}
+    items = await _build_track_out([track], artists, albums)
+    return items[0]
+
+
+@router.post("/{track_id}/materialize")
+async def materialize_track(
+    track_id: uuid.UUID,
+    service: RemoteLibraryServiceDep,
+    artist_repo: ArtistRepoDep,
+    album_repo: AlbumRepoDep,
+    user: CurrentUser,
+) -> MaterializeResponse:
+    """Fetch a placeholder track's audio on demand (plan: Model C lazy
+    materialization). Already-local tracks return ``job=None`` — nothing to
+    wait for. Otherwise poll ``GET /downloads/{job.id}`` until ``done``, then
+    stream as usual."""
+    outcome = await service.request_materialize(track_id, requested_by=user.id)
+
+    artists = {a.id: a for a in await artist_repo.get_many([outcome.track.artist_id])}
+    album_ids = [outcome.track.album_id] if outcome.track.album_id else []
+    albums = {a.id: a for a in await album_repo.get_many(album_ids)}
+    track_out = (await _build_track_out([outcome.track], artists, albums))[0]
+
+    return MaterializeResponse(
+        track=track_out,
+        job=DownloadJobOut.from_entity(outcome.job) if outcome.job is not None else None,
+    )
+
+
 @router.get("/{track_id}")
 async def get_track(
     track_id: uuid.UUID,

app/application/remote_library_service.py

@@ -0,0 +1,122 @@
+"""RemoteLibraryService — save-to-library + materialize for remote browse hits
+(plan: Model C, on-demand YTM library).
+
+Two operations:
+
+* ``save_remote`` persists a placeholder ``Track`` (``availability="remote"``,
+  ``storage_uri=None``) for a remote browse hit. Idempotent on
+  ``(source, source_id)`` — CLAUDE.md dedup.
+* ``request_materialize`` lazily fills a placeholder's audio in place: it
+  creates (or reuses) a ``DownloadJob`` pointing at the existing track and
+  enqueues the materialize worker, which calls ``TrackRepository.materialize``
+  on completion. ``track.id`` never changes (CLAUDE.md), so likes/playlists/
+  queue entries referencing the placeholder keep working once it's filled in.
+"""
+
+import uuid
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+from app.domain.entities.download import DownloadJob
+from app.domain.entities.track import Track
+from app.domain.errors import NotFoundError, ValidationError
+from app.domain.ports import ArtistRepository, DownloadJobRepository, TrackRepository
+
+_UNKNOWN_ARTIST = "Unknown Artist"
+
+# (job_id) -> None — enqueue the materialize worker, same deferred pattern as
+# download/enrich enqueuers.
+MaterializeEnqueuer = Callable[[uuid.UUID], Awaitable[None]]
+
+
+@dataclass(frozen=True)
+class MaterializeOutcome:
+    """Result of requesting materialization.
+
+    ``job`` is ``None`` when the track is already ``local`` — nothing to do,
+    the caller can stream immediately. Otherwise it's the (new or already
+    in-flight) job filling the placeholder."""
+
+    track: Track
+    job: DownloadJob | None
+
+
+class RemoteLibraryService:
+    def __init__(
+        self,
+        *,
+        tracks: TrackRepository,
+        artists: ArtistRepository,
+        jobs: DownloadJobRepository,
+        enqueue_materialize: MaterializeEnqueuer | None = None,
+    ) -> None:
+        self._tracks = tracks
+        self._artists = artists
+        self._jobs = jobs
+        self._enqueue_materialize = enqueue_materialize
+
+    async def save_remote(
+        self,
+        *,
+        source: str,
+        source_id: str,
+        title: str,
+        artist: str | None,
+        added_by: uuid.UUID | None,
+    ) -> Track:
+        """Persist a placeholder for a remote browse hit. Idempotent: a hit
+        already saved (by ``(source, source_id)``) is returned as-is."""
+        source_id = source_id.strip()
+        if not source_id:
+            raise ValidationError("A source_id is required to save.")
+
+        existing = await self._tracks.get_by_source(source, source_id)
+        if existing is not None:
+            return existing
+
+        artist_entity = await self._artists.get_or_create(artist or _UNKNOWN_ARTIST)
+        return await self._tracks.add(
+            id=uuid.uuid4(),
+            title=title,
+            artist_id=artist_entity.id,
+            storage_uri=None,
+            file_format=None,
+            file_size=None,
+            source=source,
+            source_id=source_id,
+            metadata_status="pending",
+            added_by=added_by,
+            availability="remote",
+        )
+
+    async def request_materialize(
+        self, track_id: uuid.UUID, *, requested_by: uuid.UUID | None
+    ) -> MaterializeOutcome:
+        """Kick off (or report on) materializing a placeholder track.
+
+        Already-local tracks are a no-op (``job=None``). A track with no
+        remote ``source_id`` (e.g. a deleted upload row reused for something
+        else) can't be materialized."""
+        track = await self._tracks.get_by_id(track_id)
+        if track is None:
+            raise NotFoundError(f"Track {track_id} not found.")
+        if track.availability == "local":
+            return MaterializeOutcome(track=track, job=None)
+        if track.source_id is None:
+            raise ValidationError("Track has no remote source to materialize from.")
+
+        active = await self._jobs.get_active_for_source(track.source, track.source_id)
+        if active is not None:
+            return MaterializeOutcome(track=track, job=active)
+
+        job = await self._jobs.add(
+            source=track.source,
+            source_id=track.source_id,
+            query=None,
+            requested_by=requested_by,
+        )
+        await self._jobs.set_status(job.id, status="queued", track_id=track.id)
+        if self._enqueue_materialize is not None:
+            await self._enqueue_materialize(job.id)
+        refreshed = await self._jobs.get_by_id(job.id)
+        return MaterializeOutcome(track=track, job=refreshed if refreshed is not None else job)

app/workers/arq_worker.py

@@ -12,6 +12,7 @@ from app.core.logging import configure_logging, get_logger
 from app.workers.tasks.download_task import download_track
 from app.workers.tasks.enrich_task import enrich_track
 from app.workers.tasks.import_task import scan_local_folder
+from app.workers.tasks.materialize_task import materialize_track
 
 log = get_logger("worker")
 
@@ -27,7 +28,12 @@ async def shutdown(_ctx: dict[str, Any]) -> None:
 
 
 class WorkerSettings:
-    functions: ClassVar[list[Any]] = [scan_local_folder, enrich_track, download_track]
+    functions: ClassVar[list[Any]] = [
+        scan_local_folder,
+        enrich_track,
+        download_track,
+        materialize_track,
+    ]
     on_startup = startup
     on_shutdown = shutdown
     max_jobs = get_settings().max_parallel_downloads

app/workers/queue.py

@@ -48,6 +48,17 @@ async def enqueue_download(job_id: uuid.UUID) -> None:
         log.warning("download_enqueue_failed", job_id=str(job_id))
 
 
+async def enqueue_materialize(job_id: uuid.UUID) -> None:
+    """Best-effort enqueue of a materialize job for the worker (plan: Model C
+    lazy materialization). Same deferred-commit reasoning as
+    :func:`enqueue_download` — the job row stays ``queued`` and can be retried
+    if the queue is unreachable."""
+    try:
+        await enqueue("materialize_track", job_id=str(job_id), _defer_by=3)
+    except DependencyUnavailableError:
+        log.warning("materialize_enqueue_failed", job_id=str(job_id))
+
+
 async def enqueue_enrich(track_id: uuid.UUID) -> None:
     """Best-effort enqueue of metadata enrichment for a freshly stored track.
 

app/workers/tasks/materialize_task.py

@@ -0,0 +1,101 @@
+"""arq task: materialize a remote placeholder track (plan: Model C).
+
+Counterpart to ``download_task`` for tracks that were *saved* from a remote
+browse hit without audio (``availability="remote"``, ``storage_uri=NULL``).
+The job's ``track_id`` already points at the existing placeholder row — on
+success the file is stored and ``TrackRepository.materialize`` fills the row
+in place (the track's ``id`` never changes), then enrichment is enqueued as
+usual.
+
+Shares its fetch/retry/failure machinery with ``download_task`` — only the
+"what happens on success" step differs (fill in an existing row vs. create a
+new one).
+"""
+
+import contextlib
+import uuid
+from typing import Any
+
+import anyio
+
+from app.core.config import get_settings
+from app.core.logging import correlation_id, get_logger
+from app.domain.errors import NotFoundError, ValidationError
+from app.domain.sources import DownloadResult
+from app.infrastructure.db import session_scope
+from app.infrastructure.db.repositories import (
+    SqlAlchemyDownloadJobRepository,
+    SqlAlchemyTrackRepository,
+)
+from app.infrastructure.sources.registry import build_source_registry
+from app.infrastructure.storage.provider import get_file_storage
+from app.workers.queue import enqueue_enrich
+from app.workers.tasks.download_task import _handle_failure, _load_job, _mark_failed, _run_fetch
+
+log = get_logger("worker.materialize")
+
+
+async def materialize_track(_ctx: dict[str, Any], *, job_id: str) -> dict[str, Any]:
+    correlation_id.set(f"mat:{job_id}")
+    jid = uuid.UUID(job_id)
+    settings = get_settings()
+
+    job = await _load_job(jid)
+    if job is None:
+        log.info("materialize_job_missing", job_id=job_id)  # cancelled before pickup
+        return {"job_id": job_id, "status": "missing"}
+    if job.track_id is None or job.source_id is None:
+        await _mark_failed(jid, "Materialize job missing track_id/source_id.")
+        return {"job_id": job_id, "status": "failed"}
+
+    registry = build_source_registry(settings)
+    try:
+        backend = registry.fetchable(job.source)
+    except (NotFoundError, ValidationError) as exc:
+        await _mark_failed(jid, f"Source unavailable: {exc}")
+        return {"job_id": job_id, "status": "failed"}
+
+    await _set_status(jid, "downloading")
+    try:
+        result = await _run_fetch(backend, job.source_id, jid)
+    except Exception as exc:
+        return await _handle_failure(jid, exc, settings.download_max_retries, job_id)
+
+    try:
+        await _materialize_result(jid, job.track_id, result)
+    except Exception as exc:
+        log.exception("materialize_finalize_failed", job_id=job_id)
+        await _mark_failed(jid, f"Materialize failed: {type(exc).__name__}: {exc}")
+        return {"job_id": job_id, "status": "failed"}
+
+    await enqueue_enrich(job.track_id)
+    log.info("materialize_complete", job_id=job_id, track_id=str(job.track_id))
+    return {"job_id": job_id, "status": "done", "track_id": str(job.track_id)}
+
+
+async def _materialize_result(jid: uuid.UUID, track_id: uuid.UUID, result: DownloadResult) -> None:
+    """Store the downloaded file and fill in the placeholder track in place."""
+    key = f"tracks/{str(track_id)[:2]}/{track_id}.{result.file_format}"
+    storage = get_file_storage()
+    try:
+        await storage.save_file(key, result.path)
+        async with session_scope() as session:
+            job_repo = SqlAlchemyDownloadJobRepository(session)
+            await job_repo.set_status(jid, status="enriching")
+            tracks = SqlAlchemyTrackRepository(session)
+            await tracks.materialize(
+                track_id,
+                storage_uri=key,
+                file_format=result.file_format,
+                file_size=result.file_size,
+                bitrate=result.bitrate,
+            )
+            await job_repo.set_status(jid, status="done", track_id=track_id)
+    finally:
+        with contextlib.suppress(Exception):
+            await anyio.Path(result.path).unlink(missing_ok=True)
+
+
+async def _set_status(jid: uuid.UUID, status: str) -> None:
+    async with session_scope() as session:
+        await SqlAlchemyDownloadJobRepository(session).set_status(jid, status=status)