collapsarr 0.1.3__py3-none-any.whl

collapsarr/jobs/models.py

@@ -0,0 +1,90 @@
+"""ORM model for persisted job run history (COL-21).
+
+:mod:`collapsarr.jobs.queue` (COL-20) runs each enqueued file through the
+downmix pipeline and captures the outcome onto its own in-memory
+:class:`~collapsarr.jobs.queue.Job` -- ``status``, ``result``/``error``, and
+(as of COL-21) ``started_at``/``ended_at``. That in-memory state doesn't
+survive a process restart and isn't queryable, which is what this module
+fixes: :class:`JobHistory` is the durable row a completed (or in-flight)
+:class:`~collapsarr.jobs.queue.Job` gets persisted into, ready for a future
+Activity/History view.
+
+Deliberately reuses :class:`~collapsarr.jobs.queue.JobStatus` for the
+``status`` column rather than inventing a parallel status vocabulary --
+``JobStatus.PENDING`` is this ticket's "queued" per the acceptance criteria
+(the job is enqueued and has not started running yet).
+
+:mod:`collapsarr.jobs.history` is the service layer (record/list/get) built
+on top of this model; nothing in this module touches a session.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from sqlalchemy import Enum as SAEnum
+from sqlalchemy import Integer, String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from collapsarr.database import Base
+from collapsarr.jobs.queue import JobStatus
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class JobHistory(Base):
+    """One persisted record of a single job run.
+
+    ``job_id`` is the string form of the originating
+    :attr:`~collapsarr.jobs.queue.Job.id` and is unique -- :func:`collapsarr.
+    jobs.history.record_job_history` upserts by it, so the same row is
+    updated in place as a job progresses from queued -> running ->
+    succeeded/failed rather than accumulating one row per state change.
+
+    ``exit_code`` is FFmpeg's exit code from the remux stage
+    (:attr:`~collapsarr.downmix.remux.RemuxResult.returncode`) when the
+    pipeline reached that stage, else ``None`` (e.g. a probe failure, or
+    "nothing to do"). ``error_text`` is populated for a failed run: either
+    the unexpected exception's message, or the pipeline result's ``detail``
+    when the pipeline itself reported a failure outcome.
+
+    ``target``/``language`` capture what the job was configured to do --
+    the comma-joined enabled downmix targets and language allow-list from
+    the job's :class:`~collapsarr.downmix.targets.DownmixSettings` -- so
+    they're always present regardless of which stage the run reached
+    (unlike the pipeline's ``tracks_added``, which is only populated on
+    success). ``language`` is ``None`` when the job had no allow-list
+    (evaluates every language present on the file).
+    """
+
+    __tablename__ = "job_history"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    job_id: Mapped[str] = mapped_column(String(36), nullable=False, unique=True, index=True)
+    file_path: Mapped[str] = mapped_column(String(1000), nullable=False, index=True)
+    status: Mapped[JobStatus] = mapped_column(
+        SAEnum(
+            JobStatus,
+            values_callable=lambda enum_cls: [member.value for member in enum_cls],
+        ),
+        nullable=False,
+        default=JobStatus.PENDING,
+        index=True,
+    )
+    started_at: Mapped[datetime | None] = mapped_column(nullable=True, default=None)
+    ended_at: Mapped[datetime | None] = mapped_column(nullable=True, default=None)
+    exit_code: Mapped[int | None] = mapped_column(Integer, nullable=True, default=None)
+    error_text: Mapped[str | None] = mapped_column(Text, nullable=True, default=None)
+    target: Mapped[str | None] = mapped_column(String(100), nullable=True, default=None)
+    language: Mapped[str | None] = mapped_column(String(255), nullable=True, default=None)
+
+    created_at: Mapped[datetime] = mapped_column(default=_utcnow)
+    updated_at: Mapped[datetime] = mapped_column(default=_utcnow, onupdate=_utcnow)
+
+    def __repr__(self) -> str:
+        return (
+            f"JobHistory(id={self.id!r}, job_id={self.job_id!r}, "
+            f"file_path={self.file_path!r}, status={self.status!r})"
+        )

collapsarr/jobs/queue.py

@@ -0,0 +1,382 @@
+"""Job queue and bounded-concurrency worker pool (COL-20).
+
+Wires the Downmix Engine's end-to-end pipeline
+(:func:`~collapsarr.downmix.pipeline.run_downmix_pipeline`, COL-19) to a job
+queue: :meth:`JobQueue.enqueue` a file plus its target/language context (a
+:class:`~collapsarr.downmix.targets.DownmixSettings`), then
+:meth:`JobQueue.run_pending` drains the queue, running at most
+``max_concurrency`` jobs at once (default 1).
+
+Each job's execution invokes the pipeline synchronously in a worker thread
+and captures whatever it returns (or, as a safety net, whatever it raises)
+onto the :class:`Job` itself -- ``status`` plus ``result``/``error``. When a
+``history_recorder`` is configured (see :class:`JobQueue`), that same
+worker thread calls it once the job reaches a terminal status, so every job
+run is persisted (COL-21, :mod:`collapsarr.jobs.history`) without the
+caller having to remember to do it. Likewise, when a ``failure_notifier`` is
+configured, that same worker thread calls it -- but only for a job that
+reached ``FAILED`` -- so a downmix failure fans out to the configured
+notifiers (COL-37, :mod:`collapsarr.jobs.failure_notify`) without the
+caller having to remember to do it either.
+
+This module deliberately does not import :mod:`collapsarr.jobs.history` or
+:mod:`collapsarr.jobs.failure_notify` itself (those modules import *this*
+one, for :class:`Job`/:class:`JobStatus` -- importing them back here would
+be circular). Instead ``history_recorder``/``failure_notifier`` are plain
+injected callables, the same seam ``pipeline_runner`` already uses;
+:func:`collapsarr.jobs.history.make_history_recorder` and
+:func:`collapsarr.jobs.failure_notify.make_failure_notifier` build ones
+bound to a session factory.
+
+Threads, not asyncio: every stage of the downmix pipeline shells out to
+``ffprobe``/``ffmpeg`` via blocking :mod:`subprocess` calls, so a small
+:class:`~concurrent.futures.ThreadPoolExecutor` sized to ``max_concurrency``
+gives genuine bounded parallelism (the GIL is released for the whole
+``subprocess.run`` call) without pulling the rest of this synchronous
+codebase onto an event loop.
+
+``max_concurrency`` is a plain constructor argument, the same "Settings-
+shaped stand-in" pattern :class:`~collapsarr.downmix.targets.DownmixSettings`
+already uses -- there is no persisted Settings model yet. It defaults to 1,
+and :meth:`JobQueue.from_settings` sources it from
+:class:`~collapsarr.config.Settings`'s ``job_max_concurrency`` (env
+``COLLAPSARR_JOB_MAX_CONCURRENCY``), which is the closest thing this repo has
+to a Settings store today.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable, Mapping
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any
+from uuid import UUID, uuid4
+
+from collapsarr.config import Settings, get_settings
+from collapsarr.downmix.pipeline import PipelineResult, run_downmix_pipeline
+from collapsarr.downmix.targets import DownmixSettings
+
+DEFAULT_MAX_CONCURRENCY = 1
+
+#: Signature every pipeline runner (real or injected-for-tests) must match:
+#: ``(file_path, settings, **pipeline_kwargs) -> PipelineResult``.
+PipelineRunner = Callable[..., PipelineResult]
+
+
+class JobStatus(Enum):
+    """Lifecycle state of a single :class:`Job`."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+
+
+@dataclass(slots=True)
+class Job:
+    """One enqueued unit of work: a file plus its downmix target/language context.
+
+    ``id`` uniquely identifies the job -- COL-21's job-history layer
+    (:mod:`collapsarr.jobs.history`) persists against it as ``job_id``.
+    ``status``, ``result``/``error``, and ``started_at``/``ended_at`` start
+    empty and are filled in by the queue as the job runs -- never mutate
+    them directly.
+
+    ``result`` carries the pipeline's :class:`~collapsarr.downmix.pipeline.PipelineResult`
+    when the pipeline ran (success, no-op, or a captured failure at any
+    stage). ``error`` is populated instead only in the unexpected case where
+    the pipeline runner itself raised rather than returning a result (the
+    real pipeline never does this -- see its own docstring -- but an
+    injected runner in a test, or a future alternate runner, might).
+
+    ``started_at``/``ended_at`` are stamped (UTC) by :meth:`JobQueue._run_job`
+    when the job transitions to ``RUNNING`` and when it reaches a terminal
+    status, respectively -- the start/end timestamps COL-21's job history
+    persists. Both stay ``None`` for a job that has never run.
+    """
+
+    file_path: Path
+    settings: DownmixSettings
+    id: UUID = field(default_factory=uuid4)
+    status: JobStatus = JobStatus.PENDING
+    result: PipelineResult | None = None
+    error: BaseException | None = None
+    started_at: datetime | None = None
+    ended_at: datetime | None = None
+
+
+#: Signature a ``history_recorder`` must match: takes the just-terminated
+#: ``Job`` and persists it (see :func:`collapsarr.jobs.history.make_history_recorder`).
+HistoryRecorder = Callable[[Job], None]
+
+#: Signature a ``failure_notifier`` must match: takes the just-terminated
+#: ``Job`` (only ever called for one with ``status is JobStatus.FAILED``) and
+#: dispatches a notification for it (see :func:`collapsarr.jobs.
+#: failure_notify.make_failure_notifier`). Must never raise -- see
+#: :meth:`JobQueue._notify_failure`.
+FailureNotifier = Callable[[Job], None]
+
+
+class JobQueue:
+    """Bounded-concurrency queue that runs the downmix pipeline per enqueued file.
+
+    Usage::
+
+        queue = JobQueue(max_concurrency=2)
+        queue.enqueue("/media/movie.mkv", DownmixSettings())
+        queue.enqueue("/media/episode.mkv", DownmixSettings())
+        jobs = queue.run_pending()  # blocks until both have run
+
+    :meth:`run_pending` snapshots whatever is pending at the moment it is
+    called and runs exactly that batch, respecting ``max_concurrency``, then
+    returns those jobs (each updated in place with its final ``status`` and
+    ``result``). Jobs enqueued *during* a call are not picked up by it --
+    call :meth:`run_pending` again for a later batch. This keeps behaviour
+    simple and fully deterministic for tests; a long-running background
+    worker loop is left for a future scheduler ticket to build on top of
+    this primitive.
+
+    ``history_recorder``, when set, is called with each :class:`Job` from
+    the same worker thread that ran it, right after it reaches a terminal
+    status (``SUCCEEDED``/``FAILED``) -- see :func:`collapsarr.jobs.history.
+    make_history_recorder` for the constructor that builds one bound to a
+    real DB session factory. Since :meth:`run_pending` runs jobs across a
+    :class:`~concurrent.futures.ThreadPoolExecutor` (up to ``max_concurrency``
+    at once), ``history_recorder`` must itself be safe to call concurrently
+    from multiple threads; :func:`~collapsarr.jobs.history.
+    make_history_recorder` satisfies this by opening a fresh
+    :class:`~sqlalchemy.orm.Session` per call rather than sharing one --
+    SQLAlchemy sessions aren't thread-safe, but a ``sessionmaker`` safely
+    creates independent sessions from any thread.
+
+    ``failure_notifier``, when set, is called the same way -- same worker
+    thread, right after the job reaches its terminal status -- but only for
+    a job whose terminal status is ``FAILED`` (a ``SUCCEEDED`` job never
+    triggers it). See :func:`collapsarr.jobs.failure_notify.
+    make_failure_notifier` for the constructor that dispatches to the
+    configured notifiers (COL-37); it must be safe to call concurrently for
+    the same reason ``history_recorder`` must, and -- like
+    ``history_recorder`` -- any exception it raises is swallowed by
+    :meth:`_notify_failure` so a notifier problem can never fail the job it
+    is reporting on.
+    """
+
+    def __init__(
+        self,
+        *,
+        max_concurrency: int = DEFAULT_MAX_CONCURRENCY,
+        pipeline_runner: PipelineRunner = run_downmix_pipeline,
+        pipeline_kwargs: Mapping[str, Any] | None = None,
+        history_recorder: HistoryRecorder | None = None,
+        failure_notifier: FailureNotifier | None = None,
+    ) -> None:
+        if max_concurrency < 1:
+            raise ValueError(f"max_concurrency must be >= 1, got {max_concurrency}")
+        self._max_concurrency = max_concurrency
+        self._pipeline_runner = pipeline_runner
+        self._pipeline_kwargs = dict(pipeline_kwargs or {})
+        self._history_recorder = history_recorder
+        self._failure_notifier = failure_notifier
+        self._lock = threading.Lock()
+        self._jobs: dict[UUID, Job] = {}
+
+    @classmethod
+    def from_settings(
+        cls,
+        settings: Settings | None = None,
+        *,
+        pipeline_runner: PipelineRunner = run_downmix_pipeline,
+        pipeline_kwargs: Mapping[str, Any] | None = None,
+        history_recorder: HistoryRecorder | None = None,
+        failure_notifier: FailureNotifier | None = None,
+    ) -> JobQueue:
+        """Build a :class:`JobQueue` whose concurrency cap comes from Settings.
+
+        ``settings`` defaults to the process-wide cached
+        :func:`~collapsarr.config.get_settings`. Its ``job_max_concurrency``
+        (default 1, env ``COLLAPSARR_JOB_MAX_CONCURRENCY``) becomes
+        ``max_concurrency``.
+
+        Unlike the raw :meth:`__init__` (where ``history_recorder``/
+        ``failure_notifier`` default to ``None`` -- the right default for
+        lightweight unit construction that doesn't want DB writes, e.g.
+        COL-20's concurrency tests), this factory is the production path:
+        when either isn't passed explicitly, it defaults to a *real* one --
+        ``history_recorder`` via :func:`collapsarr.jobs.history.
+        make_history_recorder` and ``failure_notifier`` via
+        :func:`collapsarr.jobs.failure_notify.make_failure_notifier`, both
+        bound to the same session factory for ``resolved``'s database
+        (schema created via :func:`~collapsarr.database.init_db` if not
+        already present) -- rather than staying ``None``. This mirrors how
+        ``pipeline_runner`` already defaults to the real
+        :func:`~collapsarr.downmix.pipeline.run_downmix_pipeline` in the raw
+        ``__init__``: a bare ``JobQueue.from_settings()`` call, with no extra
+        plumbing, persists history and dispatches failure notifications for
+        real. Pass either explicitly (or ``None`` isn't obtainable here --
+        construct via :meth:`__init__` directly instead) to opt out.
+
+        The database engine backing those defaults is created at most once,
+        here, for this :class:`JobQueue` instance -- shared between
+        ``history_recorder`` and ``failure_notifier`` when both need
+        defaulting, but not shared with the FastAPI app's own request-scoped
+        engine (see :mod:`collapsarr.main`). For SQLite (this project's only
+        supported backend today) that's safe -- both point at the same
+        on-disk file -- but it does mean calling this factory repeatedly
+        opens a new engine each time, so production code should call it once
+        and hold onto the resulting :class:`JobQueue` (e.g. on
+        ``app.state``), the same way it already holds onto one session
+        factory.
+
+        The imports of :mod:`collapsarr.jobs.history` and
+        :mod:`collapsarr.jobs.failure_notify` below are deferred (inside this
+        method, not at module scope) because those modules import *this* one
+        (for :class:`Job`/:class:`JobStatus`) -- the same defer-to-break-a-
+        cycle trick :func:`collapsarr.database.init_db` already uses for its
+        own model-registration imports.
+        """
+        resolved = settings or get_settings()
+
+        resolved_history_recorder = history_recorder
+        resolved_failure_notifier = failure_notifier
+        if resolved_history_recorder is None or resolved_failure_notifier is None:
+            from collapsarr.database import (
+                create_engine_from_settings,
+                create_session_factory,
+                init_db,
+            )
+
+            engine = create_engine_from_settings(resolved)
+            init_db(engine)
+            session_factory = create_session_factory(engine)
+
+            if resolved_history_recorder is None:
+                from collapsarr.jobs.history import make_history_recorder
+
+                resolved_history_recorder = make_history_recorder(session_factory)
+
+            if resolved_failure_notifier is None:
+                from collapsarr.jobs.failure_notify import make_failure_notifier
+
+                resolved_failure_notifier = make_failure_notifier(session_factory)
+
+        return cls(
+            max_concurrency=resolved.job_max_concurrency,
+            pipeline_runner=pipeline_runner,
+            pipeline_kwargs=pipeline_kwargs,
+            history_recorder=resolved_history_recorder,
+            failure_notifier=resolved_failure_notifier,
+        )
+
+    @property
+    def max_concurrency(self) -> int:
+        """The configured cap on simultaneously running jobs."""
+        return self._max_concurrency
+
+    def enqueue(self, file_path: str | Path, settings: DownmixSettings) -> Job:
+        """Add a file + its target/language context to the queue as a new job.
+
+        Returns the created :class:`Job` (status ``PENDING``) immediately;
+        it is not run until a subsequent :meth:`run_pending` call.
+        """
+        job = Job(file_path=Path(file_path), settings=settings)
+        with self._lock:
+            self._jobs[job.id] = job
+        return job
+
+    def get_job(self, job_id: UUID) -> Job | None:
+        """Return the job with ``job_id``, or ``None`` if no such job exists."""
+        with self._lock:
+            return self._jobs.get(job_id)
+
+    def list_jobs(self) -> list[Job]:
+        """Return every job ever enqueued on this queue, in enqueue order."""
+        with self._lock:
+            return list(self._jobs.values())
+
+    def run_pending(self) -> list[Job]:
+        """Run every currently-``PENDING`` job to completion, then return them.
+
+        Runs the batch through a :class:`~concurrent.futures.ThreadPoolExecutor`
+        sized to ``max_concurrency``, so at most that many jobs execute the
+        pipeline at once; with ``max_concurrency=1`` the executor has a
+        single worker, so jobs run strictly one at a time, in the order they
+        were enqueued.
+
+        Blocks until the whole batch has finished. Returns an empty list if
+        nothing was pending. Each returned :class:`Job` has been updated in
+        place with its final ``status`` and ``result``/``error``, and -- if
+        this queue was built with a ``history_recorder`` -- already
+        persisted via it.
+        """
+        with self._lock:
+            batch = [job for job in self._jobs.values() if job.status is JobStatus.PENDING]
+        if not batch:
+            return []
+
+        with ThreadPoolExecutor(max_workers=self._max_concurrency) as executor:
+            futures = [executor.submit(self._run_job, job) for job in batch]
+            for future in futures:
+                future.result()  # re-raise any unexpected executor-level error
+
+        return batch
+
+    def _run_job(self, job: Job) -> None:
+        """Execute one job's pipeline run, record its outcome, and persist/notify.
+
+        Runs entirely on the calling (worker) thread. Once ``job`` reaches
+        its terminal status (``SUCCEEDED``/``FAILED``), ``self._history_recorder``
+        (if configured) is called with it, followed by ``self._notify_failure``
+        (a no-op unless the job actually ``FAILED`` and a ``failure_notifier``
+        is configured) -- both outside ``self._lock``, since by that point
+        only this thread ever touches this particular ``job`` (each job is
+        submitted to the executor exactly once), so there is nothing left to
+        race against.
+        """
+        with self._lock:
+            job.status = JobStatus.RUNNING
+            job.started_at = datetime.now(UTC)
+
+        try:
+            result = self._pipeline_runner(job.file_path, job.settings, **self._pipeline_kwargs)
+        except Exception as exc:  # noqa: BLE001 - captured as the job's outcome, not re-raised
+            with self._lock:
+                job.error = exc
+                job.status = JobStatus.FAILED
+                job.ended_at = datetime.now(UTC)
+            self._record_history(job)
+            self._notify_failure(job)
+            return
+
+        with self._lock:
+            job.result = result
+            job.status = JobStatus.SUCCEEDED if result.success else JobStatus.FAILED
+            job.ended_at = datetime.now(UTC)
+        self._record_history(job)
+        self._notify_failure(job)
+
+    def _record_history(self, job: Job) -> None:
+        """Persist ``job``'s just-reached terminal state, if configured to."""
+        if self._history_recorder is not None:
+            self._history_recorder(job)
+
+    def _notify_failure(self, job: Job) -> None:
+        """Dispatch a failure notification for ``job``, if configured and it failed.
+
+        A no-op for a job that reached ``SUCCEEDED``, or when no
+        ``failure_notifier`` was configured. ``self._failure_notifier`` is
+        expected to never raise on its own (COL-37's
+        :func:`~collapsarr.jobs.failure_notify.notify_job_failure` guarantees
+        this), but it is called inside a defensive ``try``/``except`` anyway
+        -- a notification problem must never be able to fail the job it is
+        reporting on, or the worker thread running it.
+        """
+        if self._failure_notifier is None or job.status is not JobStatus.FAILED:
+            return
+        try:
+            self._failure_notifier(job)
+        except Exception:  # noqa: BLE001 - a notifier failure must never fail the job
+            pass

collapsarr/jobs/routes.py

@@ -0,0 +1,193 @@
+"""HTTP REST endpoints for job history & on-demand triggers (COL-29).
+
+Thin layer wrapping the Job Queue & Scheduler epic's service surface, exposed as
+a FastAPI :class:`~fastapi.APIRouter` mounted under ``/api`` by
+:func:`collapsarr.main.create_app`. Because everything under ``/api`` is gated by
+the API-key middleware (COL-26), every route here inherits key-based auth -- no
+per-route auth wiring is needed.
+
+Three endpoints, each wrapping an existing service without adding new job logic:
+
+- ``GET /api/jobs/history`` -- lists persisted job history (COL-21,
+  :func:`collapsarr.jobs.history.list_job_history`), optionally filtered by
+  ``file`` (exact file path) and/or ``status`` (a :class:`~collapsarr.jobs.queue.
+  JobStatus` value). Mirrors Sonarr/Radarr's ``/history`` view.
+- ``POST /api/jobs/scan`` -- triggers an immediate full-library scan
+  (:meth:`collapsarr.jobs.scheduler.JobScheduler.scan_now`, COL-23), enqueuing a
+  downmix job for every monitored file that has a qualifying missing target. The
+  Sonarr/Radarr analogue is the ``RescanSeries``/``RefreshMovie`` command.
+- ``POST /api/jobs/trigger`` -- manually enqueues a downmix job for one specific
+  file (:meth:`collapsarr.jobs.scheduler.JobScheduler.trigger_file`, COL-23). The
+  optional ``extra_languages`` list is the allow-list-bypass option: those
+  languages are forced past the scheduler's ``language_allow_list`` for this one
+  call, letting a user downmix a language they normally don't auto-process.
+
+The scan/trigger endpoints operate on the live
+:class:`~collapsarr.jobs.scheduler.JobScheduler` the app wired onto
+``app.state.job_scheduler`` (see :func:`collapsarr.main.create_app`,
+``enable_scheduler=True``) so a manual trigger and the background loop share one
+queue. When no scheduler is wired (e.g. an app built without the scheduler), the
+dependency raises ``503`` rather than silently doing nothing.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel, ConfigDict
+from sqlalchemy.orm import Session
+
+from ..database import get_session
+from .history import list_job_history
+from .models import JobHistory
+from .queue import Job, JobStatus
+from .scheduler import JobScheduler
+
+router = APIRouter(prefix="/api", tags=["jobs"])
+
+
+# --- dependencies ------------------------------------------------------------
+
+
+def get_job_scheduler(request: Request) -> JobScheduler:
+    """Return the app's live :class:`JobScheduler`, or ``503`` if none is wired.
+
+    The scan/trigger endpoints act on the same scheduler (and its shared queue)
+    the background loop drains, exposed on ``app.state.job_scheduler`` by
+    :func:`collapsarr.main.create_app` when built with ``enable_scheduler=True``
+    (the production path). An app built without it has no on-demand trigger
+    surface, so we fail loudly with ``503`` instead of pretending to enqueue.
+    """
+    scheduler: JobScheduler | None = getattr(request.app.state, "job_scheduler", None)
+    if scheduler is None:
+        raise HTTPException(
+            status_code=503,
+            detail="Job scheduler is not available.",
+        )
+    return scheduler
+
+
+# --- schemas -----------------------------------------------------------------
+
+
+class JobHistoryRead(BaseModel):
+    """Response shape for one persisted job-history row (COL-21)."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    job_id: str
+    file_path: str
+    status: JobStatus
+    started_at: datetime | None
+    ended_at: datetime | None
+    exit_code: int | None
+    error_text: str | None
+    target: str | None
+    language: str | None
+    created_at: datetime
+    updated_at: datetime
+
+
+class EnqueuedJob(BaseModel):
+    """The identifying summary of a job the scheduler just enqueued in-memory."""
+
+    id: str
+    file_path: str
+    status: JobStatus
+
+    @classmethod
+    def from_job(cls, job: Job) -> EnqueuedJob:
+        return cls(id=str(job.id), file_path=str(job.file_path), status=job.status)
+
+
+class ScanResult(BaseModel):
+    """Response for ``POST /api/jobs/scan``: the jobs the scan pass enqueued."""
+
+    enqueued: list[EnqueuedJob]
+
+
+class ManualTriggerRequest(BaseModel):
+    """Request body for ``POST /api/jobs/trigger``.
+
+    ``file_path`` names the (host-local) file to downmix. ``extra_languages`` is
+    the allow-list-bypass option (COL-23): languages listed here are unioned onto
+    the scheduler's ``language_allow_list`` for this one call, so a language the
+    global allow-list would otherwise exclude still gets a downmix job. When the
+    scheduler has no allow-list (every language is already eligible) it has no
+    effect. Omit it (or send ``[]``) for a plain trigger honouring the allow-list.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    file_path: str
+    extra_languages: list[str] = []
+
+
+class ManualTriggerResult(BaseModel):
+    """Response for ``POST /api/jobs/trigger``.
+
+    ``enqueued`` is ``True`` with the created ``job`` when a downmix job was
+    queued. It is ``False`` with ``job`` ``null`` when the file was skipped -- a
+    duplicate (already queued / recently processed), unprobeable, or with no
+    qualifying target even after ``extra_languages`` -- mirroring
+    :meth:`collapsarr.jobs.scheduler.JobScheduler.trigger_file` returning ``None``.
+    """
+
+    enqueued: bool
+    job: EnqueuedJob | None
+
+
+# --- endpoints ---------------------------------------------------------------
+
+
+@router.get("/jobs/history", response_model=list[JobHistoryRead])
+def list_job_history_endpoint(
+    file: str | None = None,
+    status: JobStatus | None = None,
+    session: Session = Depends(get_session),
+) -> list[JobHistory]:
+    """List persisted job history, optionally filtered by file and/or status.
+
+    ``file`` matches a file path exactly (the form job history stores);
+    ``status`` matches a single :class:`~collapsarr.jobs.queue.JobStatus`
+    (``pending``/``running``/``succeeded``/``failed``). Both may be combined;
+    omitting both returns every row, ordered by insertion.
+    """
+    return list_job_history(session, file_path=file, status=status)
+
+
+@router.post("/jobs/scan", response_model=ScanResult, status_code=202)
+def scan_now_endpoint(scheduler: JobScheduler = Depends(get_job_scheduler)) -> ScanResult:
+    """Trigger an immediate full-library scan, returning the jobs it enqueued.
+
+    Runs the same scan the periodic loop runs (COL-22/COL-23), synchronously:
+    every configured instance's monitored files are re-probed and a downmix job
+    is enqueued for each with a qualifying missing target (skipped/no-op files
+    excluded). ``202 Accepted`` -- the jobs are queued, not yet run.
+    """
+    jobs = scheduler.scan_now()
+    return ScanResult(enqueued=[EnqueuedJob.from_job(job) for job in jobs])
+
+
+@router.post("/jobs/trigger", response_model=ManualTriggerResult, status_code=202)
+def manual_trigger_endpoint(
+    body: ManualTriggerRequest,
+    scheduler: JobScheduler = Depends(get_job_scheduler),
+) -> ManualTriggerResult:
+    """Manually enqueue a downmix job for one file, honouring the bypass option.
+
+    Wraps :meth:`collapsarr.jobs.scheduler.JobScheduler.trigger_file`: probes the
+    file, enqueues a job when a target qualifies, and threads ``extra_languages``
+    through as the allow-list-bypass. A ``202`` is returned whether or not a job
+    was enqueued; the ``enqueued`` flag distinguishes the two (a skipped file --
+    duplicate/unprobeable/nothing to do -- is not an error).
+    """
+    job = scheduler.trigger_file(
+        body.file_path,
+        extra_languages=body.extra_languages or None,
+    )
+    if job is None:
+        return ManualTriggerResult(enqueued=False, job=None)
+    return ManualTriggerResult(enqueued=True, job=EnqueuedJob.from_job(job))