serverpod-file-uploads

Serverpod ファイルアップロード

フロー：サーバーがアップロードの説明を発行 → クライアントがアップロード → サーバーが検証します。デフォルトのストレージはデータベースです。本番環境では、S3、GCP、R2、または互換性のあるオブジェクトストレージを使用してください。

サーバー：アップロードの説明を作成する

Future<String> getUploadDescription(Session session, String path) async {
  return await session.storage.createUploadDescription(
    storageId: 'public',
    path: path,
  );
}

リクエストは必ず認可し、信頼できるサーバー側の状態（ユーザー ID、テナント ID、オブジェクト ID）からパスを導出してください。任意のクライアントパスを受け入れてはいけません。

サーバー：アップロードを検証する

Future<bool> verifyUpload(Session session, String path) async {
  return await session.storage.verifyUpload(
    storageId: 'public', path: path);
}

オブジェクトストレージを使用する場合は、クライアントのアップロード後に必ず検証してください。

クライアント：アップロードする

var desc = await client.myEndpoint.getUploadDescription('profile/$userId/avatar.png');
var uploader = FileUploader(desc);
await uploader.upload(byteDataOrStream);
await client.myEndpoint.verifyUpload('profile/$userId/avatar.png');

大きなファイルには Stream を使用してください。パスは先頭にスラッシュを付けず、オブジェクトストアと互換性があり、正規化され、認証済みユーザー／テナントの範囲内に限定してください。

セキュリティチェックリスト

• 説明と検証の両方のエンドポイントで、認証／認可を必須にしてください。
• 説明を発行する前に、コンテンツタイプ、サイズ、拡張子を検証するか、サーバー側で導出してください。
• クライアントにテナントをまたぐパスやストレージ ID を選択させてはいけません。
• verifyUpload の成功後に、データベースへメタデータを保存してください。

保存済みファイルへのアクセス

• session.storage.fileExists(storageId: 'public', path: path)
• session.storage.publicDownloadUrl(storageId: 'public', path: path)（パブリックストレージのみ）
• session.storage.temporaryDownloadUrl(storageId: 'private', path: path)（プライベートファイルへの期間限定アクセス）
• session.storage.retrieveFile(storageId: 'public', path: path)

ストレージバックエンド

• データベース（デフォルト）： public と private のストレージです。開発環境に適しています。
• Google Cloud Storage： serverpod_cloud_storage_gcp を追加し、passwords.yaml または環境変数に HMAC キーを設定してください。登録方法：pod.addCloudStorage(GoogleCloudStorage(...))。
• AWS S3： serverpod_cloud_storage_s3 を追加し、AWS キーを設定してください。登録方法：pod.addCloudStorage(S3CloudStorage(...))。
• S3 互換／R2： 互換性のあるプロバイダーを対象とする場合は、対応する統合パッケージを使用してください。

デフォルトを置き換える場合は、storageId: 'public' または 'private' を使用してください。