Gamend.Storage.Adapter behaviour (gamend_core v1.0.1192)

Behaviour for object-storage backends.

Implemented by Gamend.Storage.Local (disk, the dev default) and Gamend.Storage.S3 (any S3-compatible service — AWS S3, Cloudflare R2, Backblaze B2, MinIO, DigitalOcean Spaces). Callers go through the Gamend.Storage facade, never an adapter directly.

Summary

Types

key()

object()

A stored object's metadata, as listed by the admin tools.

presigned()

An upload ticket handed to a client so it can upload bytes directly to the backend (S3/R2) or to the local upload endpoint — the client flow is identical either way.

stat()

What the backend reports about a stored object without fetching it.

Callbacks

delete(key)

delete_prefix(t)

Deletes every object under prefix. Returns how many were removed.

exists?(key)

get(key)

list(keyword)

One page of objects. Opts: :prefix, :offset, :limit.

presigned_upload(key, keyword)

put(key, iodata, keyword)

stat(key)

Size and stored content type of one object, without downloading it.

url(key, keyword)

usage(keyword)

Total object count and byte size. Opts: :prefix.

Types

key()

@type key() :: String.t()

object()

@type object() :: %{
  key: key(),
  size: non_neg_integer(),
  last_modified: DateTime.t() | nil
}

A stored object's metadata, as listed by the admin tools.

presigned()

@type presigned() :: %{
  method: String.t(),
  url: String.t(),
  headers: %{optional(String.t()) => String.t()},
  key: key(),
  expires_in: pos_integer()
}

An upload ticket handed to a client so it can upload bytes directly to the backend (S3/R2) or to the local upload endpoint — the client flow is identical either way.

stat()

@type stat() :: %{size: non_neg_integer(), content_type: String.t() | nil}

What the backend reports about a stored object without fetching it.

Callbacks

delete(key)

@callback delete(key()) :: :ok | {:error, term()}

delete_prefix(t)

@callback delete_prefix(String.t()) :: {:ok, non_neg_integer()} | {:error, term()}

Deletes every object under prefix. Returns how many were removed.

exists?(key)

@callback exists?(key()) :: boolean()

get(key)

@callback get(key()) :: {:ok, binary()} | {:error, term()}

list(keyword)

@callback list(keyword()) :: [object()]

One page of objects. Opts: :prefix, :offset, :limit.

presigned_upload(key, keyword)

@callback presigned_upload(
  key(),
  keyword()
) :: {:ok, presigned()} | {:error, term()}

put(key, iodata, keyword)

@callback put(key(), iodata(), keyword()) :: {:ok, key()} | {:error, term()}

stat(key)

@callback stat(key()) :: {:ok, stat()} | {:error, term()}

Size and stored content type of one object, without downloading it.

content_type is whatever the backend recorded; the local adapter keeps no per-object metadata and always reports nil.

url(key, keyword)

@callback url(
  key(),
  keyword()
) :: String.t()

usage(keyword)

@callback usage(keyword()) :: %{count: non_neg_integer(), bytes: non_neg_integer()}

Total object count and byte size. Opts: :prefix.