Repository Public
1# Architecture23```4navigateur ──HTTPS──▶ Caddy (BHS64, TLS) ──WireGuard──▶ nœud :8690 server.ts5 ├─ /api/v1/stream/<id>, /api/v1/art/<id> → src/server/media-http.ts (Node natif)6 └─ tout le reste → Next.js (pages + API JSON)7worker (tsx) ── uploads / tracks (PostgreSQL) ── ffprobe / ffmpeg ── STORAGE_ROOT (privé)8```910## Séparation11121. **Interface et lecteur** — `src/app`, `src/components` (le lecteur vit dans le layout : il survit à la navigation).132. **API** — quatre surfaces, une route attrape-tout chacune, un garde exécuté *avant* la recherche du gestionnaire (`src/lib/api/router.ts`) :14 | Surface | Garde | Contenu |15 |---|---|---|16 | `/api/v1/auth/*` | aucun (limité en débit par adresse) | session, options/vérification WebAuthn, code de récupération, déconnexion |17 | `/api/v1/library/*` | `requireUser` | catalogue, recherche, favoris, listes, état de lecture, demande de rendu AAC |18 | `/api/v1/me/*` | `requireUser` | clés d'accès, sessions, préférences du compte |19 | `/api/v1/admin/*` | `requireAdmin` | import, édition, suppression, comptes, santé, journal |20 Un gestionnaire d'administration ne peut pas être atteint sans le contrôle de rôle : il n'est même pas recherché avant.213. **Métadonnées** — PostgreSQL. La base ne contient que des métadonnées et des clés de stockage.224. **Originaux** — `STORAGE_ROOT/originals/<aa>/<sha256>.<ext>`, jamais modifiés, jamais sous `public/`.235. **Pochettes et rendus** — `art/<aa>/<sha256>/{orig.*,96.jpg,320.jpg,640.jpg}`, `renditions/<aa>/<track>.m4a`.246. **Traitement asynchrone** — `src/worker/index.ts`.2526## Schéma (db/migrations/001_init.sql)2728`users` (rôle `admin`/`listener`, un seul `is_owner`), `authenticators` (clé d'accès : identifiant, clé **publique**,29compteur, transports, nom, dates), `sessions`, `setup_tokens`, `recovery_codes` (hachés), `webauthn_challenges`,30`rate_limits`, `audit_events` · `artists`, `genres`, `albums`, `tracks`, `artworks`, `media_assets` (original, rendu,31pochette, miniature) · `uploads` (import + file de traitement) · `playlists`, `playlist_tracks`, `favorites`,32`favorite_albums`, `playback_state`.3334Contraintes notables : un seul original par piste ; un même fichier (SHA-256) ne peut pas être stocké deux fois ;35un album est unique par (artiste d'album, titre normalisé) ; index trigrammes pour la recherche.36Une migration appliquée n'est jamais modifiée (somme de contrôle vérifiée) : on en ajoute une.3738## Import3940```41navigateur : POST /admin/uploads {nom, taille} → PATCH /admin/uploads/<id>?offset=N (morceaux de 8 Mo, écrits en flux)42uploading → received → validating → extracting → ready | duplicate | error | cancelled43```4445- **Reprise** : un morceau envoyé au mauvais décalage reçoit `409` avec le décalage attendu ; le client reprend là.46- **Validation** : type déterminé par les premiers octets (`sniff`), jamais par l'extension ; puis `ffprobe` doit trouver un flux audio mesurable. Exécutables, textes, vidéos : refusés.47- **Doublons** : `same_file` (même SHA-256) ou `same_track` (même artiste d'album, album, disque, numéro, titre). Rien n'est remplacé sans confirmation explicite ; le remplacement garde l'identifiant de la piste (listes et favoris intacts) et est journalisé.48- **ZIP** : chaque entrée audio est écrite sous un nom généré par le serveur ; limites sur le nombre d'entrées, la taille par entrée, la taille totale et le taux de compression, mesurées sur les octets produits ; archives chiffrées, imbriquées ou contenant un chemin `../` : refusées.49- **Tags** : titre, artiste, album, artiste d'album, piste, disque, année, genre ; à défaut, le nom du fichier (« 03 Titre.wav »).50- **Pochette** : extraite du fichier sans réencodage, dédupliquée par empreinte ; miniatures carrées JPEG générées à part.5152## Diffusion5354- `GET /api/v1/stream/<uuid>` exige la session ; `Range` → `206` avec `Content-Range` et `Content-Length` exacts ; `416` si la plage est hors fichier ; `ETag` = identifiant de l'asset, `Cache-Control: private, no-cache` (un fichier remplacé change d'asset, donc d'ETag).55- Lecture depuis le disque par `createReadStream({start, end})` : un morceau n'est jamais chargé en mémoire.56- **Original d'abord.** `tracks.web_playable` : `yes` (FLAC, MP3, AAC, WAV), `some` (ALAC, AIFF, Ogg : rendu AAC préparé à l'import), `no` (DSD : original conservé, rendu seulement si `TRANSCODE_DSD=true`).57- Le lecteur choisit avec `canPlayType` ; si le navigateur échoue à décoder un original, il demande le rendu (`POST /library/tracks/<id>/compat`) et reprend à la même position.58- Aucun transcodage haute résolution : le rendu de compatibilité est un AAC (`RENDITION_BITRATE_KBPS`, 44,1/48 kHz).5960## Stockage6162`src/server/storage.ts` définit `Storage` (`putFile`, `put`, `read(range)`, `size`, `delete`, `localPath`, `health`).63Seul le pilote `local` est livré : le cluster n'a pas de stockage objet. Un pilote S3 s'ajoute en implémentant cette64interface (`localPath` devant alors télécharger vers un fichier temporaire pour ffmpeg) ; `STORAGE_DRIVER=s3` échoue65aujourd'hui explicitement plutôt que de faire semblant.6667## Internationalisation6869`src/i18n/messages.ts` : une ligne par chaîne, `[français, English]`. Le français est la langue par défaut ; la langue70est une préférence du compte.7172## Clients natifs (SP Music pour macOS)7374L'application macOS (`ai.spboucher.spmusic`, dépôt `sp-music-macos`) garde sa propre copie du catalogue et lit hors ligne.75Elle utilise les mêmes surfaces que le site, plus ceci (migration `003_native_clients.sql`) :7677| Route | Rôle |78|---|---|79| `GET /api/v1/library/sync?since=<rev>` | Catalogue incrémental : artistes, albums, pistes dont la révision dépasse `since`, et pierres tombales des suppressions. Chaque piste porte son fichier (`assetId`, `sha256`, `sizeBytes`, `mime`) pour le téléchargement vérifié. `more: true` = redemander avec le `rev` reçu. |80| `GET /api/v1/library/sync/me` | Listes (avec leurs entrées), favoris et état de lecture du compte, en une réponse. |81| `GET` / `POST /api/v1/library/history` | Historique d'écoute ; l'identifiant de chaque événement vient du client (renvoi sans doublon). |82| `PATCH playlists/:id`, `PUT playlists/:id/order` | Champ facultatif `baseUpdatedAt` : `409 conflict` si la liste a changé depuis la copie du client (modification faite hors ligne). |83| `POST /api/v1/auth/device/{start,poll,info,decide}` | Association d'appareil (voir SECURITY.md). Page d'approbation : `/appareil`. |84| `GET /.well-known/apple-app-site-association` | Autorise l'application (`APPLE_APP_IDS`) à utiliser les clés d'accès du site. |8586**Révisions.** `artists`, `albums` et `tracks` portent une colonne `rev` tirée d'une seule séquence par un déclencheur ; un87verrou consultatif de transaction est pris *avant* le tirage, donc les révisions sont validées dans l'ordre croissant et88la plus haute révision d'une réponse est un curseur sûr. Un changement de fichier (`media_assets`) ou de paroles89(`lyrics`) fait avancer la révision de la piste. La lecture se fait dans un seul instantané (`REPEATABLE READ`).90