Storage

StorageTemplate (the bean storageTemplate) reads and writes the objects of Supabase Storage. A @StorageBucket interface declares the objects of one bucket, with their paths in one place. Both act as the current user, so the policies of row-level security on storage.objects decide what a call may do.

Why

The policies of a bucket depend on the shape of the path: "a user writes under a folder named by their id". When every caller builds that path from a parameter, one of them will take the user's id from the wrong place. A declared bucket writes each path once, and can take the user from the security context instead of a parameter a caller could set to another user's.

Example

@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 needs no user id: the path is the signed-in user's. The same with the template:

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');

The template

Method What it does
upload(bucket, path, content, contentType:, upsert:, cacheControl:) Writes bytes, a String (as UTF-8) or a Stream<List<int>>. With upsert an object already there is replaced; without it, it is a StorageObjectAlreadyExistsException. The content type is application/octet-stream (text/plain;charset=utf-8 for a String) unless given.
download(bucket, path) The bytes of the object, as they arrive (Stream<List<int>>).
downloadBytes(bucket, path) The whole object in memory.
read<T>(bucket, path) The object read as JSON into a T through the ObjectMapper; null when there is no such object.
store(bucket, path, value, upsert:) Writes a value as JSON, replacing what is there unless upsert is false.
publicUrl(bucket, path, download:) The address of an object of a public bucket. Nothing is asked of Storage: the address exists whether the object does or not.
signedUrl(bucket, path, expiresIn:) An address that reads the object without a token, for expiresIn (spring.supabase.storage.signed-url-expiry unless given).
signedUploadUrl(bucket, path) A SignedUpload: an address the object can be uploaded to once, with a PUT, without a token (for a browser, given by a server).
list(bucket, prefix:, limit:, offset:, sortBy:, descending:, search:) The objects and folders directly under a prefix: StorageObjectInfos, 100 by default, ordered by name. A folder has no id (isFolder).
delete(bucket, path), deleteAll(bucket, paths) Removes objects; nothing there is no error. deleteAll tells how many there were.
move(bucket, from, to, toBucket:), copy(…) Moves or copies an object, to another bucket when given.
exists(bucket, path), info(bucket, path) Whether there is an object the caller may see; what Storage knows about it (size, contentType, etag, updatedAt…), or null.
buckets(), bucket(id), createBucket(id, isPublic:, fileSizeLimit:, allowedMimeTypes:), updateBucket, emptyBucket, deleteBucket The buckets of the project.
asServiceRole() The same template with every call made as the service role, which passes the policies and is the one that manages buckets. Needs spring.supabase.service-role-key.
await storage.asServiceRole().createBucket('avatars', isPublic: true);

Declared buckets

@StorageBucket('avatars') marks an interface whose methods read and write the objects of one bucket; the bucket's id may be a ${property}. Each method has one of these:

Annotation The method
@Upload(path, contentType:, upsert:, cacheControl:) takes the content and returns Future<void>. The content is a Uint8List, a List<int>, a Stream<List<int>> or a String: the only parameter the path does not use, or the one marked @RequestBody().
@Download(path) returns Stream<List<int>> (the bytes as they arrive) or Future<Uint8List>; a nullable Future<Uint8List?> is null when there is no such object.
@SignedUrl(path, expiresIn:) returns Future<Uri> or Future<String>.
@PublicUrl(path, download:) returns Uri or String, without asking Storage.
@StorageObject(path, upsert:) reads JSON when it returns a value (Future<Settings?> is null for no object; a non-nullable type is an error then); writes it when it takes a value and returns Future<void>.
@DeleteObject(path) returns Future<void>; nothing there is no error.

Path rules

A path of a declared bucket takes three kinds of placeholders:

In the path Filled from
${app.folder} the configuration, once, when the application starts
{userId} the method's parameter of that name, at each call
#{authentication.name} SpEL, at each call: the parameters as #name, authentication and principal as in @PreAuthorize, beans as @name
@Download('{userId}/#{#kind.name}.png')
Stream<List<int>> get(String userId, AvatarKind kind);

A value is one segment of the path, never a path. What a parameter or an expression gives is refused, with an ArgumentError, when it:

So '{userId}/avatar.png' with userId = '../admin' is refused, and no call leaves its folder. The fixed text of a path may not have a . or .. segment either.

The template checks every path again, also one given in code: a path with an empty, . or .. segment, a backslash or a control character is an ArgumentError, and each segment is percent-encoded. A bucket id is one segment.

Errors

Exception When
StorageObjectNotFoundException The object or the bucket does not exist, or the caller may not see it; Storage does not tell the two apart.
StorageObjectAlreadyExistsException There is an object (or a bucket) at that place already.
StoragePermissionDeniedException A policy on storage.objects refused the call, or the token was not accepted.
StorageObjectTooLargeException The object is larger than the bucket or the project allows.
StorageException Any other failure of Storage.
SupabaseUnavailableException No answer from the project.

All are SupabaseExceptions with statusCode, code and message.

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

A stream of download fails with the exception when it is listened to.

Limits

The properties

Key Type Default Meaning
spring.supabase.storage.signed-url-expiry Duration 1h How long a signed URL is valid when the call does not say.

In Spring (Java)

Spring itself has no counterpart. Spring Cloud AWS has S3Template of the same shape as StorageTemplate; declared buckets have none.

See also