veza/veza-backend-api/docs/UPLOAD_ASYNC_OPTIONS.md

Options pour Upload I/O Asynchrone (P2-008)

Date: 2025-01-27
Status: Analyse des options

---

Contexte

L'upload actuel dans UploadTrack attend la fin de la copie fichier (io.Copy) avant de répondre, bloquant le handler HTTP.

Problème: Pour les gros fichiers, le handler reste bloqué pendant plusieurs minutes.

---

Option A: 202 Accepted + Job ID (Asynchrone réel)

Sémantique HTTP

• Réponse: 202 Accepted
• Body: {"track_id": "uuid", "status": "uploading", "status_url": "/api/v1/tracks/{id}/status"}

Comportement

1. Créer le Track en DB avec Status=Uploading immédiatement
2. Lancer la copie fichier en goroutine avec suivi (context + cancellation)
3. Répondre 202 Accepted immédiatement
4. Mettre à jour le Status quand terminé (Completed ou Failed)
5. Client peut poller /api/v1/tracks/{id}/status pour suivre

Avantages

• ✅ Vraiment asynchrone (handler répond immédiatement)
• ✅ Cohérent avec l'architecture existante (GetUploadStatus existe déjà)
• ✅ Traçabilité complète (logs + request_id via context)
• ✅ Gestion d'erreurs robuste (nettoyage automatique)
• ✅ Support cancellation (context)

Inconvénients

• ⚠️ Nécessite polling côté client
• ⚠️ Plus complexe (goroutine + suivi)

Cohérence avec l'existant

• ✅ Endpoint GetUploadStatus existe déjà
• ✅ Track a déjà Status (Uploading, Processing, Completed, Failed)
• ✅ Système de jobs existe déjà

---

Option B: 200 OK mais Streaming Optimisé (Pas vraiment async)

Sémantique HTTP

• Réponse: 200 OK (mais après copie optimisée)
• Body: {"track": {...}}

Comportement

1. Lancer la copie en goroutine avec channel
2. Attendre la fin avec timeout (comme actuellement)
3. Répondre 200 OK après copie

Avantages

• ✅ Plus simple (pas de polling)
• ✅ Réponse immédiate avec résultat final

Inconvénients

• ❌ Pas vraiment asynchrone (handler attend quand même)
• ❌ Bloque toujours le handler (même si optimisé)
• ❌ Pas de suivi de progression

---

Recommandation: Option A

Raison:

• Cohérent avec l'architecture existante (GetUploadStatus, Track.Status)
• Vraiment asynchrone (handler répond immédiatement)
• Meilleure UX pour gros fichiers (pas de timeout HTTP)
• Traçabilité complète

Implémentation minimale:

1. Créer Track avec Status=Uploading avant copie
2. Goroutine avec context pour copie + mise à jour Status
3. Handler retourne 202 Accepted
4. Client poll GetUploadStatus

---

Décision: ✅ Option A (202 Accepted)