Code Review Graph + Docs + Config
This commit is contained in:
@@ -0,0 +1,193 @@
|
||||
# Ombrora-YTDLP — Design Spec
|
||||
|
||||
Date: 2026-08-10
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
Interface web publique permettant a n'importe quel utilisateur de soumettre une URL de video a telecharger via yt-dlp. Les telechargements sont traites en arriere-plan par un worker Node.js gere par Passenger sur o2switch. Les fichiers sont stockes localement dans un dossier prive et accessibles via un lien temporaire a duree de vie configurable.
|
||||
|
||||
---
|
||||
|
||||
## Architecture generale
|
||||
|
||||
Approche retenue : **Monorepo Next.js + Worker script Node.js separe**.
|
||||
|
||||
- `src/` : app Next.js (UI React + API routes)
|
||||
- `worker/` : script Node.js long-running qui poll la DB et execute yt-dlp
|
||||
- `config/` : configuration centralisee (TTL, concurrence, chemins)
|
||||
- `prisma/` : schema et migrations
|
||||
- `docker-compose.yml` : MariaDB pour le developpement local
|
||||
- Un seul `package.json` a la racine (contrainte o2switch/Passenger)
|
||||
|
||||
---
|
||||
|
||||
## Structure du projet
|
||||
|
||||
```
|
||||
Ombrora-YTDLP/
|
||||
├── src/
|
||||
│ ├── app/
|
||||
│ │ ├── page.tsx # Formulaire de soumission
|
||||
│ │ ├── status/[uuid]/page.tsx # Page de statut
|
||||
│ │ └── api/
|
||||
│ │ ├── downloads/route.ts # POST soumission, GET statut
|
||||
│ │ ├── downloads/[uuid]/route.ts
|
||||
│ │ └── download/[token]/route.ts # Stream fichier via token
|
||||
│ ├── components/
|
||||
│ └── lib/
|
||||
│ ├── prisma.ts
|
||||
│ ├── rate-limit.ts
|
||||
│ └── token.ts
|
||||
├── worker/
|
||||
│ ├── index.ts # Worker long-running principal
|
||||
│ ├── cron-check.ts # Verifie que le worker tourne (cron 5 min)
|
||||
│ └── cron-cleanup.ts # Supprime les fichiers expires (cron 1x/jour)
|
||||
├── config/
|
||||
│ └── app.config.ts
|
||||
├── prisma/
|
||||
│ └── schema.prisma
|
||||
├── docker-compose.yml
|
||||
└── package.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Schema base de donnees (Prisma / MariaDB)
|
||||
|
||||
```prisma
|
||||
model Download {
|
||||
id String @id @default(cuid())
|
||||
uuid String @unique @default(uuid()) // expose sur les interfaces
|
||||
url String
|
||||
status Status @default(PENDING)
|
||||
format String // ex: "mp4", "mp3"
|
||||
quality String // ex: "best", "1080p"
|
||||
subtitles Boolean @default(false)
|
||||
extraArgs String? // options yt-dlp (JSON array de strings, ex: ["--sponsorblock-remove","all"])
|
||||
|
||||
filePath String? // chemin absolu sur disque
|
||||
fileName String? // nom original
|
||||
fileSize BigInt? // taille en octets
|
||||
errorMsg String?
|
||||
|
||||
ipAddress String
|
||||
submittedAt DateTime @default(now())
|
||||
startedAt DateTime?
|
||||
completedAt DateTime?
|
||||
deletedAt DateTime?
|
||||
|
||||
tokens DownloadToken[]
|
||||
}
|
||||
|
||||
model DownloadToken {
|
||||
id String @id @default(cuid())
|
||||
download Download @relation(fields: [downloadId], references: [id])
|
||||
downloadId String
|
||||
token String @unique @default(uuid())
|
||||
expiresAt DateTime
|
||||
usedAt DateTime?
|
||||
createdAt DateTime @default(now())
|
||||
}
|
||||
|
||||
enum Status {
|
||||
PENDING // en attente de traitement
|
||||
PROCESSING // worker en cours
|
||||
DONE // fichier disponible
|
||||
FAILED // echec yt-dlp
|
||||
FILE_DELETED // metadonnees conservees, fichier supprime du disque
|
||||
}
|
||||
```
|
||||
|
||||
**Regles immuables :**
|
||||
- Aucune entree n'est jamais supprimee de la DB (historique complet).
|
||||
- `id` (cuid) usage interne uniquement ; `uuid` expose sur toutes les interfaces.
|
||||
- Le fichier est stocke sous `{STORAGE_PATH}/{uuid}.{extension}`.
|
||||
|
||||
---
|
||||
|
||||
## Worker (worker/index.ts)
|
||||
|
||||
Processus Node.js long-running sous Passenger. Cycle a chaque iteration :
|
||||
|
||||
1. Requete DB : `SELECT` les `PENDING` ordonnes par `submittedAt`, limite a `WORKER_CONCURRENCY`.
|
||||
2. Passe les entrees selectionnees en `PROCESSING` (atomique : UPDATE WHERE status=PENDING).
|
||||
3. Spawne un `worker_thread` par telechargement.
|
||||
4. Chaque thread construit la commande yt-dlp :
|
||||
- `--no-playlist` toujours present
|
||||
- `-f {format}` pour le format
|
||||
- `--write-sub --sub-lang fr,en` si `subtitles=true`
|
||||
- `-o {STORAGE_PATH}/{uuid}.%(ext)s` pour le chemin de sortie
|
||||
- extraArgs injectes depuis le champ JSON
|
||||
5. Fin du thread :
|
||||
- **Succes** : `status=DONE`, remplit `filePath`, `fileName`, `fileSize`, `completedAt`, cree un `DownloadToken` avec `expiresAt = now + DOWNLOAD_LINK_TTL_HOURS`.
|
||||
- **Echec** : `status=FAILED`, remplit `errorMsg` (stderr yt-dlp).
|
||||
6. Attend `WORKER_POLL_INTERVAL_MS` puis recommence.
|
||||
|
||||
---
|
||||
|
||||
## Crons o2switch (cPanel)
|
||||
|
||||
| Script | Frequence | Role |
|
||||
|--------|-----------|------|
|
||||
| `worker/cron-check.ts` | Toutes les 5 min | Relance le worker s'il n'est pas actif |
|
||||
| `worker/cron-cleanup.ts` | 1x par jour | Supprime les fichiers dont `completedAt + TTL < now`, passe `status=FILE_DELETED`, remplit `deletedAt` |
|
||||
|
||||
---
|
||||
|
||||
## API Routes (Next.js)
|
||||
|
||||
| Methode | Route | Description |
|
||||
|---------|-------|-------------|
|
||||
| `POST` | `/api/downloads` | Valide IP (rate limit), cree l'entree DB, retourne `{ uuid }` |
|
||||
| `GET` | `/api/downloads/[uuid]` | Retourne statut et metadonnees du telechargement |
|
||||
| `GET` | `/api/download/[token]` | Verifie token (existence, expiration), stream le fichier, marque `usedAt` |
|
||||
|
||||
**Rate limiting** (`lib/rate-limit.ts`) :
|
||||
- Map en memoire : IP -> `{ count, resetAt }`
|
||||
- Limite et fenetre configurables dans `app.config.ts`
|
||||
- Pas de Redis requis
|
||||
- Hypothese : Passenger tourne avec 1 seul processus Next.js sur o2switch (standard). Si plusieurs processus sont configures, la Map n'est pas partagee et le rate limit serait par-processus — a surveiller.
|
||||
|
||||
---
|
||||
|
||||
## Configuration (config/app.config.ts)
|
||||
|
||||
```typescript
|
||||
export const config = {
|
||||
DOWNLOAD_LINK_TTL_HOURS: 24, // duree de validite du lien temporaire
|
||||
WORKER_CONCURRENCY: 3, // telechargements en parallele
|
||||
WORKER_POLL_INTERVAL_MS: 10_000, // intervalle de poll de la DB
|
||||
STORAGE_PATH: '/home/.../storage', // chemin absolu du dossier de stockage
|
||||
RATE_LIMIT_MAX: 5, // soumissions max par IP
|
||||
RATE_LIMIT_WINDOW_MS: 3_600_000, // fenetre de rate limit (1h)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Frontend (React / Next.js)
|
||||
|
||||
### `/` — Formulaire de soumission
|
||||
- Champ URL
|
||||
- Select format (mp4, mp3, webm, ...)
|
||||
- Select qualite (best, 1080p, 720p, 480p, ...)
|
||||
- Checkbox sous-titres
|
||||
- Champ options avancees (optionnel, libre)
|
||||
- Soumission -> POST `/api/downloads` -> redirect vers `/status/{uuid}`
|
||||
|
||||
### `/status/[uuid]` — Page de statut
|
||||
- Polling `GET /api/downloads/[uuid]` toutes les 5 secondes
|
||||
- Affichage selon statut :
|
||||
- `PENDING` / `PROCESSING` : indicateur de progression
|
||||
- `DONE` : bouton de telechargement (lien `/api/download/{token}`)
|
||||
- `FAILED` : message d'erreur yt-dlp
|
||||
- `FILE_DELETED` : message "fichier expire, le telechargement n'est plus disponible"
|
||||
|
||||
---
|
||||
|
||||
## Contraintes de deploiement o2switch
|
||||
|
||||
- Un seul `package.json` / `node_modules` a la racine (pas de `frontend/node_modules`).
|
||||
- Toute dependance runtime du frontend doit etre dans les `dependencies` de la racine ET dans `frontend/package.json` (si sous-dossier).
|
||||
- yt-dlp doit etre installe comme binaire precompile (pas de build depuis les sources).
|
||||
- Les dependances avec bindings natifs doivent publier des binaires precompiles pour la plateforme o2switch.
|
||||
Reference in New Issue
Block a user