Storage

StorageTemplate (Bean 名は storageTemplate) は、Supabase Storage のオブジェクトを読み書きします。@StorageBucket のインターフェースは、一つのバケットのオブジェクトを、そのパスを一か所にまとめて宣言します。どちらも現在のユーザーとして動作するので、呼び出しに何ができるかは、storage.objects の行レベルセキュリティのポリシーが決めます。

使う理由

バケットのポリシーは、パスの形に依存します。「ユーザーは、自分の ID の名前のフォルダーの下に書く」というものです。すべての呼び出し元がパラメーターからそのパスを組み立てていると、どれかが間違った場所からユーザーの ID を取ります。宣言したバケットは各パスを一度だけ書き、呼び出し元が別のユーザーの ID を入れられるパラメーターの代わりに、セキュリティコンテキストからユーザーを取れます。

例

@StorageBucket('avatars')
abstract interface class Avatars {
  @Upload('#{authentication.name}/avatar.png', upsert: true)
  Future<void> put(Uint8List bytes);

  @Download('{userId}/avatar.png')
  Stream<List<int>> get(String userId);

  @SignedUrl('{userId}/avatar.png', expiresIn: Duration(minutes: 5))
  Future<Uri> link(String userId);

  @PublicUrl('{userId}/avatar.png')
  Uri publicLink(String userId);

  @StorageObject('{userId}/settings.json')
  Future<Settings?> settings(String userId);

  @StorageObject('{userId}/settings.json')
  Future<void> saveSettings(String userId, Settings settings);

  @DeleteObject('{userId}/avatar.png')
  Future<void> remove(String userId);
}

put にユーザーの ID は要りません。パスは、サインインしたユーザーのものです。テンプレートで同じことをするには:

await storage.upload('avatars', 'u1/avatar.png', bytes,
    contentType: 'image/png', upsert: true);
final link = await storage.signedUrl('avatars', 'u1/avatar.png');
final settings = await storage.read<Settings>('config', 'app.json');

テンプレート

メソッド すること
upload(bucket, path, content, contentType:, upsert:, cacheControl:) バイト列、String (UTF-8 として)、または Stream<List<int>> を書き込む。upsert があると、すでにあるオブジェクトを置き換える。なければ StorageObjectAlreadyExistsException。コンテンツタイプは、指定しなければ application/octet-stream (String では text/plain;charset=utf-8)。
download(bucket, path) オブジェクトのバイト列。届いた順に渡される (Stream<List<int>>)。
downloadBytes(bucket, path) オブジェクト全体をメモリに読む。
read<T>(bucket, path) オブジェクトを JSON として、ObjectMapper で T に読む。そのオブジェクトがなければ null。
store(bucket, path, value, upsert:) 値を JSON として書き込む。upsert が false でない限り、あるものを置き換える。
publicUrl(bucket, path, download:) 公開バケットのオブジェクトのアドレス。Storage には何も問い合わせない。アドレスは、オブジェクトがあってもなくても存在する。
signedUrl(bucket, path, expiresIn:) トークンなしでオブジェクトを読めるアドレス。expiresIn の間だけ有効 (指定しなければ spring.supabase.storage.signed-url-expiry)。
signedUploadUrl(bucket, path) SignedUpload。トークンなしで、PUT で一度だけオブジェクトをアップロードできるアドレス (サーバーがブラウザーに渡すためのもの)。
list(bucket, prefix:, limit:, offset:, sortBy:, descending:, search:) プレフィックスの直下のオブジェクトとフォルダー。StorageObjectInfo のリストで、デフォルトは 100 件、name の順。フォルダーには id がない (isFolder)。
delete(bucket, path)、deleteAll(bucket, paths) オブジェクトを削除する。何もなくてもエラーではない。deleteAll は、あった数を返す。
move(bucket, from, to, toBucket:)、copy(…) オブジェクトを移動またはコピーする。指定すれば別のバケットへ。
exists(bucket, path)、info(bucket, path) 呼び出し元に見えるオブジェクトがあるかどうか。Storage がそれについて知っていること (size、contentType、etag、updatedAt など)、または null。
buckets()、bucket(id)、createBucket(id, isPublic:, fileSizeLimit:, allowedMimeTypes:)、updateBucket、emptyBucket、deleteBucket プロジェクトのバケット。
asServiceRole() すべての呼び出しをサービスロールとして行う、同じテンプレート。サービスロールはポリシーを通過し、バケットを管理できる。spring.supabase.service-role-key が必要。
await storage.asServiceRole().createBucket('avatars', isPublic: true);

宣言したバケット

@StorageBucket('avatars') は、メソッドが一つのバケットのオブジェクトを読み書きするインターフェースに付けます。バケットの ID は ${property} でもかまいません。各メソッドには、次のどれか一つを付けます。

アノテーション メソッド
@Upload(path, contentType:, upsert:, cacheControl:) コンテンツを受け取り、Future<void> を返す。コンテンツは Uint8List、List<int>、Stream<List<int>>、String のいずれかで、パスが使っていない唯一のパラメーターか、@RequestBody() の付いたパラメーター。
@Download(path) Stream<List<int>> (届いた順のバイト列) または Future<Uint8List> を返す。null 許容の Future<Uint8List?> は、そのオブジェクトがなければ null。
@SignedUrl(path, expiresIn:) Future<Uri> または Future<String> を返す。
@PublicUrl(path, download:) Storage に問い合わせずに、Uri または String を返す。
@StorageObject(path, upsert:) 値を返すときは JSON を読む (Future<Settings?> はオブジェクトがなければ null。null 非許容の型ではエラー)。値を受け取って Future<void> を返すときは書き込む。
@DeleteObject(path) Future<void> を返す。何もなくてもエラーではない。

パスのルール

宣言したバケットのパスには、三種類のプレースホルダーを書けます。

パスの中 何で埋められるか
${app.folder} 設定。アプリケーションの起動時に一度だけ
{userId} 同じ名前のメソッドのパラメーター。呼び出しのたび
#{authentication.name} SpEL。呼び出しのたび。パラメーターは #name、authentication と principal は @PreAuthorize と同じ、Bean は @name
@Download('{userId}/#{#kind.name}.png')
Stream<List<int>> get(String userId, AvatarKind kind);

値はパスの一つのセグメントで、パスではありません。 パラメーターや式が返すものは、次の場合に ArgumentError で拒否されます。

そのため、'{userId}/avatar.png' に userId = '../admin' を渡すと拒否され、どの呼び出しも自分のフォルダーの外に出ません。パスの固定のテキストにも、. や .. のセグメントは書けません。

テンプレートは、コードで渡されたものも含めて、すべてのパスをもう一度検査します。空、.、.. のセグメント、バックスラッシュ、制御文字を含むパスは ArgumentError で、各セグメントはパーセントエンコードされます。バケットの ID は一つのセグメントです。

エラー

例外 いつ
StorageObjectNotFoundException オブジェクトまたはバケットが存在しないか、呼び出し元に見えない。Storage はこの二つを区別しない。
StorageObjectAlreadyExistsException その場所に、すでにオブジェクト (またはバケット) がある。
StoragePermissionDeniedException storage.objects のポリシーが呼び出しを拒否した、またはトークンが受け入れられなかった。
StorageObjectTooLargeException オブジェクトが、バケットまたはプロジェクトの許す大きさを超えている。
StorageException Storage のその他の失敗。
SupabaseUnavailableException プロジェクトから応答がない。

どれも SupabaseException で、statusCode、code、message を持ちます。

try {
  await storage.upload('avatars', 'u1.png', bytes);
} on StorageObjectAlreadyExistsException {
  // upload(..., upsert: true) would have replaced it
}

download のストリームは、購読されたときに、その例外で失敗します。

制限

プロパティ

キー 型 デフォルト 意味
spring.supabase.storage.signed-url-expiry Duration 1h 呼び出しが指定しないときの、署名付き URL の有効期間。

Spring (Java) との対応

Spring 自体には対応するものがありません。Spring Cloud AWS には、StorageTemplate と同じ形の S3Template があります。宣言したバケットに対応するものはありません。

関連項目