Senko-san
48e3418c7f
First ingest path beyond manual upload (plan §1C). Source abstraction +
the first concrete backend, so a homelab can index an existing library.
- domain: SourceBackend/IndexableSource ports + SourceInfo/SourceFile shapes
- infrastructure/sources: LocalFolderSource (walks a mounted dir, idempotent
source_id = relative path) + registry built from settings
- application: LibraryImportService — batch sibling of UploadService; dedup on
(source, source_id), copy into storage, minimal track (metadata_status=pending,
enrichment fills the rest in 1D), per-file failures isolated
- workers: scan_local_folder arq task (registered) + enqueue helper (503 if
Redis down)
- api: GET /sources, POST /sources/{source}/scan (admin, enqueues), /health
- config: LOCAL_MEDIA_IMPORT_PATH; README + .env.example documented
- tests: scanner, registry, import service (fakes) + DB-gated sources API path
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
127 lines
5.0 KiB
Markdown
127 lines
5.0 KiB
Markdown
# mcma-backend
|
|
|
|
Self-hosted, **offline-first** music service — backend. Searches/downloads music
|
|
from external sources, stores files + metadata, streams to clients, and serves a
|
|
native REST API plus a Subsonic-compatible API.
|
|
|
|
> Status: **Phase 1 (core/MVP)** — project skeleton in place. See the
|
|
> implementation plan for the full roadmap.
|
|
|
|
## Architecture — hexagonal (ports & adapters)
|
|
|
|
```
|
|
app/
|
|
├── domain/ pure core: entities, value objects, errors, ports (Protocols)
|
|
├── application/ use cases / services — orchestrate domain via ports
|
|
├── infrastructure/ driven adapters: ORM, repositories, db, redis, sources, ML client
|
|
│ ├── db/ declarative base, async engine, session factory
|
|
│ └── cache/ redis client
|
|
├── api/ driving adapter: FastAPI routers, schemas, deps, middleware
|
|
├── workers/ arq background tasks (download, enrich, transcode)
|
|
└── core/ cross-cutting: config, logging, security
|
|
```
|
|
|
|
**Rule:** dependencies point inward. `domain` imports nothing framework-specific;
|
|
`application` depends on domain ports; `infrastructure`/`api` are the outer ring
|
|
and are wired together at the composition root (`app/main.py`, `app/api/deps.py`).
|
|
|
|
## Build (Docker)
|
|
|
|
This repo ships only its own `Dockerfile` — the image runs anywhere and gets
|
|
every peer (Postgres, Redis, media path) from env. It carries **no**
|
|
orchestration. Full-stack wiring lives in the workspace compose one level up
|
|
(`../docker-compose.yml`, alongside `mcma-webui`):
|
|
|
|
```bash
|
|
docker build -t mcma-backend . # build just this service
|
|
# or, from the workspace root, the whole stack:
|
|
docker compose --profile app up --build # db, redis, api, worker, webui
|
|
```
|
|
|
|
## Local dev (without Docker)
|
|
|
|
```bash
|
|
uv sync # install deps (uses managed Python 3.14)
|
|
# start backing services from the workspace root: `docker compose up -d` (db + redis)
|
|
cp .env.example .env # then set a real JWT_SECRET
|
|
uv run uvicorn app.main:app --reload
|
|
```
|
|
|
|
## Tooling
|
|
|
|
```bash
|
|
uv run ruff check . # lint
|
|
uv run ruff format . # format
|
|
uv run mypy app # type-check (strict)
|
|
uv run pytest # tests
|
|
```
|
|
|
|
## Database migrations (Alembic)
|
|
|
|
```bash
|
|
uv run alembic revision --autogenerate -m "message" # after model changes
|
|
uv run alembic upgrade head # apply
|
|
```
|
|
|
|
The DB URL is injected from app settings — never hardcoded in `alembic.ini`.
|
|
|
|
## Configuration
|
|
|
|
All settings come from environment variables (or `.env` in dev). See
|
|
[`.env.example`](.env.example). External services (ML, AcoustID, MusicBrainz)
|
|
are **optional** — the backend degrades gracefully when they are absent.
|
|
|
|
## Sources & importing music
|
|
|
|
Music enters the library through **source backends** (`app/infrastructure/sources`),
|
|
selected via a registry. The first backend is **`local`** — it indexes a mounted
|
|
folder, copying each audio file into managed storage and creating a track
|
|
(`metadata_status=pending`; real metadata is filled later by enrichment).
|
|
|
|
```bash
|
|
# point the instance at an existing library (mount read-only in compose)
|
|
LOCAL_MEDIA_IMPORT_PATH=/import
|
|
|
|
GET /api/v1/sources # list configured sources + availability
|
|
POST /api/v1/sources/local/scan # admin: enqueue an import (runs in the worker)
|
|
GET /api/v1/sources/local/health # availability check
|
|
```
|
|
|
|
Scanning is a background job (arq worker) — the endpoint only enqueues it; the
|
|
walk + file copies never run in the request cycle. Re-scans are idempotent
|
|
(dedup on `(source, source_id)`, where `source_id` is the path within the root).
|
|
|
|
## Subsonic API (`/rest`)
|
|
|
|
A Subsonic-compatible API is mounted at `/rest`, so standard clients (Symfonium,
|
|
DSub, play:Sub, …) can browse the library and stream. It is a thin adapter over
|
|
the native services — it adds no business logic of its own.
|
|
|
|
**HTTPS is mandatory.** Subsonic authentication puts the credential in the URL
|
|
(`t=md5(password+salt)&s=…`, or the legacy `p=`), so `/rest` must only ever be
|
|
exposed behind TLS (terminate at the reverse proxy). Never serve it over plain
|
|
HTTP.
|
|
|
|
### App-passwords
|
|
|
|
Subsonic auth needs a recoverable secret, but login passwords are stored as a
|
|
one-way argon2 hash. So Subsonic clients authenticate against a separate,
|
|
per-user **app-password** — high-entropy, random, and encrypted at rest with a
|
|
key derived from `SUBSONIC_SECRET_KEY` (set this to a strong random string in
|
|
prod; rotating it invalidates all stored app-passwords).
|
|
|
|
Self-service lifecycle (native API, needs a normal JWT login):
|
|
|
|
```bash
|
|
GET /api/v1/users/me/subsonic-password # reveal (generated lazily on first read)
|
|
POST /api/v1/users/me/subsonic-password # rotate
|
|
# admin, for any user:
|
|
POST /api/v1/admin/users/{user_id}/subsonic-password
|
|
```
|
|
|
|
Point the client at the instance URL, use your **username** + the revealed
|
|
**app-password** (not your login password).
|
|
|
|
> **Cover art** (`getCoverArt`) currently returns a placeholder — the cover
|
|
> pipeline (`/api/v1/.../cover` endpoints) is not implemented yet.
|