Uploads privés S3 et R2 dans Next.js

Synchronisé avec le commit e632762 du starter.

Utilisez cette fonction lorsque votre produit doit conserver des avatars, documents, imports ou fichiers générés sans les rendre publics ni faire transiter chaque octet par le serveur Next.js. À la fin, une personne connectée doit pouvoir charger, télécharger et supprimer un fichier depuis Compte → Fichiers, sans qu’une autre organisation puisse y accéder.

Choisir la politique de stockage adaptée

• Docker Compose utilise Garage comme défaut local open source maintenu et crée le bucket privé. Cloudflare R2 et AWS S3 sont des choix production courants. minio reste supporté pour les équipes qui l’exploitent, mais n’est plus le défaut livré. Tous partagent le même adaptateur.
• Choisissez general pour des fichiers mixtes, images pour les images avec une limite de politique de 10 Mo, documents pour les fichiers bureautiques et texte, ou verified lorsque le navigateur doit fournir un SHA-256.
• La limite réelle est la plus petite entre le plan, STORAGE_MAX_UPLOAD_MB et la politique. Gardez le bucket privé ; le modèle livré utilise des URL signées de courte durée.

Prêt pour la production signifie : le parcours UI fonctionne, CORS n’accepte que vos origines, une URL publique directe échoue, l’accès inter-organisation est refusé et cron supprime finalement l’objet d’un fichier effacé.

Définissez STORAGE_PROVIDER à garage, s3, r2 ou minio, puis bucket, région, endpoint et identifiants. Les objets restent privés et le navigateur ne reçoit que des URL signées courtes. L’exemple image utilise le même cycle privé.

Contrat

1. POST /api/storage/uploads valide organisation, storage.upload, politique (general, images, documents, verified), type et le minimum des limites plan/environnement/politique ; le quota est réservé atomiquement.
2. Le navigateur PUT directement ; XHR ne sert qu’à la progression.
3. POST /api/storage/uploads/complete vérifie métadonnées et SHA-256 optionnel puis active la ligne.
4. GET /api/storage/files/[uuid]?download=1 fournit une URL limitée à l’organisation.
5. DELETE /api/storage/files/[uuid] fait un soft-delete et planifie storage_object_delete durable.

Un upload abandonné libère sa réservation après une heure. La suppression réessaie par la file : cron doit tourner. Le service génère les clés ; le client ne choisit pas la clé bucket.

Testez flux complet, MIME/checksum invalide, concurrence quota, URL expirée, accès inter-organisation, reprise et nettoyage. Voir docs/storage-providers.md du starter pour CORS.

Étape suivante : fiabilisez suppression et nettoyage avec Tâches durables et readiness.

Pagination bornée

GET /api/storage/files accepte page entier de 1 à 10 000 et limit de 1 à 100 (50 par défaut), avec hasMore. L’écran localisé permet précédent, suivant et nouvelle tentative ; une ancienne réponse ne remplace pas une nouvelle page ou un autre espace. Un seul en-tête Content-Type est envoyé lors du téléversement.