Attached.StorageBackends.Behaviour behaviour (Attached v0.2.0)

Behaviour contract for storage backends.

A backend is a named instance in the registry — a {module, config} pair under config :attached, :storage_backends (see Attached.StorageBackends). Every callback receives that instance's config keyword list as its first argument: backend modules hold no global state, so the same module can back several named instances (e.g. two S3 buckets).

Callers should not use backend modules directly — go through Attached.StorageBackends, which resolves the default instance and dispatches with its config.

Summary

Types

config()

key()

Callbacks

compose(config, source_keys, destination_key)

Concatenate files at source_keys into a single file at destination_key.

delete(config, key)

Delete the file at key.

delete_prefixed(config, prefix)

Delete files at keys starting with the prefix.

direct_upload_url(config, key, opts)

Return a URL (plus the headers the client must send) for uploading the file at key directly from the browser via HTTP PUT.

download(config, key)

Download the file at key and return its binary content.

download_chunk(config, key, t)

Return the partial content in the byte range of the file at key.

exists?(config, key)

Return true if a file exists at key.

upload(config, key, source_path, opts)

Upload a file from source_path to the given key.

url(config, key, opts)

Return a URL for the file at key.

Types

config()

@type config() :: keyword()

key()

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

Callbacks

compose(config, source_keys, destination_key)

@callback compose(config(), source_keys :: [key()], destination_key :: key()) ::
  :ok | {:error, term()}

Concatenate files at source_keys into a single file at destination_key.

delete(config, key)

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

Delete the file at key.

delete_prefixed(config, prefix)

@callback delete_prefixed(config(), prefix :: String.t()) :: :ok | {:error, term()}

Delete files at keys starting with the prefix.

direct_upload_url(config, key, opts)

(optional)

@callback direct_upload_url(config(), key(), opts :: keyword()) ::
  {:ok, %{url: String.t(), headers: [{String.t(), String.t()}]}}
  | {:error, term()}

Return a URL (plus the headers the client must send) for uploading the file at key directly from the browser via HTTP PUT.

Options: :content_type, :checksum (base64 MD5, pinned via Content-MD5), :byte_size (pinned via Content-Length), :expires_in.

Optional — backends that cannot offer direct uploads simply don't implement it; Attached.StorageBackends.direct_upload_url/2 then returns {:error, :not_supported}.

download(config, key)

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

Download the file at key and return its binary content.

download_chunk(config, key, t)

@callback download_chunk(config(), key(), Range.t()) :: {:ok, binary()} | {:error, term()}

Return the partial content in the byte range of the file at key.

exists?(config, key)

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

Return true if a file exists at key.

upload(config, key, source_path, opts)

@callback upload(config(), key(), source_path :: String.t(), opts :: keyword()) ::
  :ok | {:error, term()}

Upload a file from source_path to the given key.

url(config, key, opts)

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

Return a URL for the file at key.