encore-bucket

Encore オブジェクトストレージ

手順

Bucket はファイルの論理的なストアです。Encore は基盤となるオブジェクトストレージをプロビジョニングします（AWS では S3、GCP では GCS、ローカルではインメモリ）。バケットはパッケージレベルで宣言します。

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

// Private bucket (default)
export const uploads = new Bucket("user-uploads", {
  versioned: false,  // Set to true to keep multiple versions
});

// Public bucket — files accessible via public URL
export const publicAssets = new Bucket("public-assets", {
  public: true,
  versioned: false,
});

操作

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

// Download
const data = await uploads.download("path/to/file.jpg");

// Existence check
const exists = await uploads.exists("path/to/file.jpg");

// Attributes (size, content type, ETag)
const meta = await uploads.attrs("path/to/file.jpg");

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

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

// Public URL (only for public buckets)
const url = publicAssets.publicUrl("image.jpg");

署名付き URL

クライアントがサービスを経由せずに直接アップロード/ダウンロードできるよう、一時的な URL を生成します：

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

バケット参照

特定の権限セットを持つバケットアクセスを他のコードに渡します：

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

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

// Permission types: Downloader, Uploader, Lister, Attrser, Remover,
// SignedDownloader, SignedUploader, ReadWriter

エラー

• ObjectNotFound — オブジェクトが存在しません
• PreconditionFailed — アップロードの事前条件が満たされていません（例：setIfNotExists）
• ObjectsError — 基底のエラータイプ

ガイドライン

• バケットはパッケージレベルで宣言します。
• デフォルトではプライベートバケットを使用し、認証されていないダウンロードを想定したアセットにのみ public: true を指定します。
• ブラウザからのアップロード/ダウンロードには、サービスを経由してストリーミングするのではなく、署名付き URL を使用します。
• ヘルパーにアクセスを渡す際にはバケット参照を使用します — これにより権限の契約が型システムにエンコードされます。