Stockage d'objets Encore

Instructions

Un Bucket est un magasin logique pour les fichiers. Encore provisionne le stockage d'objets sous-jacent (S3 sur AWS, GCS sur GCP, en mémoire localement). Déclarez les buckets au niveau du package.

import { Bucket } from "encore.dev/storage/objects";

// Bucket privé (défaut)
export const uploads = new Bucket("user-uploads", {
  versioned: false,  // Mettre à true pour conserver plusieurs versions
});

// Bucket public — fichiers accessibles via URL publique
export const publicAssets = new Bucket("public-assets", {
  public: true,
  versioned: false,
});

Opérations

// Téléverser
const attrs = await uploads.upload("path/to/file.jpg", buffer, {
  contentType: "image/jpeg",
});

// Télécharger
const data = await uploads.download("path/to/file.jpg");

// Vérifier l'existence
const exists = await uploads.exists("path/to/file.jpg");

// Attributs (taille, type de contenu, ETag)
const meta = await uploads.attrs("path/to/file.jpg");

// Supprimer
await uploads.remove("path/to/file.jpg");

// Lister
for await (const entry of uploads.list({})) {
  console.log(entry.key, entry.size);
}

// URL publique (pour les buckets publics uniquement)
const url = publicAssets.publicUrl("image.jpg");

URLs signées

Générez des URLs temporaires pour que les clients puissent téléverser/télécharger directement sans passer par votre service :

const uploadUrl = await uploads.signedUploadUrl("user-uploads/avatar.jpg", { ttl: 7200 });
const downloadUrl = await uploads.signedDownloadUrl("documents/report.pdf", { ttl: 7200 });

Références de bucket

Passez l'accès au bucket à d'autre code avec un ensemble de permissions spécifique :

import { Uploader, Downloader } from "encore.dev/storage/objects";

const uploaderRef = uploads.ref<Uploader>();
const downloaderRef = uploads.ref<Downloader>();

// Types de permissions : Downloader, Uploader, Lister, Attrser, Remover,
// SignedDownloader, SignedUploader, ReadWriter

Erreurs

ObjectNotFound — l'objet n'existe pas
PreconditionFailed — les préconditions de téléversement ne sont pas respectées (par exemple setIfNotExists)
ObjectsError — type d'erreur de base

Recommandations

Déclarez les buckets au niveau du package.
Privilegiez les buckets privés ; n'activez public: true que pour les ressources destinées au téléchargement non authentifié.
Utilisez les URLs signées pour les téléversements/téléchargements depuis le navigateur au lieu de les faire transiter par votre service.
Utilisez les références de bucket quand vous passez l'accès à des fonctions auxiliaires — elles encodent le contrat de permissions dans le système de types.

encore-bucket