
# Storage

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

## 使う理由

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

## 例

```dart
@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 は要りません。パスは、サインインしたユーザーのものです。テンプレートで同じことをするには:

```dart
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` が必要。 |

```dart
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>` を返す。何もなくてもエラーではない。 |

- **Bean** はインターフェースにちなんだ名前になり、他の Bean と同じく AOP が効きます。`@PreAuthorize`、`@Cacheable` です。
- **起動時に検査。** アノテーションのないメソッドや、戻り値の型やコンテンツが誤っているメソッドは起動を止めます。メッセージは、そのインターフェースのすべての問題を示します。
- **独自の種類のメソッド**は、`StorageBucketOperation` を実装する Bean です。組み込みのものより先に尋ねられます。
- アプリケーションのビルド時に分からないもの (一覧、移動、バケット) には、テンプレートを使います。

## パスのルール

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

| パスの中 | 何で埋められるか |
|---|---|
| `${app.folder}` | 設定。アプリケーションの起動時に一度だけ |
| `{userId}` | 同じ名前のメソッドのパラメーター。呼び出しのたび |
| `#{authentication.name}` | SpEL。呼び出しのたび。パラメーターは `#name`、`authentication` と `principal` は `@PreAuthorize` と同じ、Bean は `@name` |

```dart
@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` を持ちます。

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

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

## 制限

- **アップロードは、送る前にすべて読み込まれます。** ストリームもです。トランスポートは、リクエストのボディをバイト列として受け取るためです。ダウンロードはストリームで渡されます。
- **再開可能なアップロード** (TUS) はありません。
- **オブジェクトの `Resource`** はありません。`resource(bucket, path)` はありません。
- **画像の変換**はありません。

## プロパティ

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

## Spring (Java) との対応

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

## 関連項目

- [誰として呼び出すか](credentials.md)
- [キャッシュ](cache.md)
- [SpEL](../spring-core-dart/spel/index.md)
- [メソッドセキュリティ](../spring-security-core/method-security.md)
