Threadline.Storage behaviour (Threadline v0.6.0)

Behaviour for storing and retrieving export files and other persistent artifacts.

Threadline provides a Threadline.Storage.Local implementation out-of-the-box for single-node deployments. Adopters needing multi-node support should implement an S3-compatible backend conforming to this behaviour.

The init/1 callback is used for dependency safeguards, ensuring adapters fail early if their required underlying library is missing from the environment.

Summary

Types

file_id()

options()

path_or_content()

Callbacks

delete(file_id)

Deletes a file from storage.

download_url(file_id, options)

Generates a presigned or localized URL for downloading the file.

get(file_id)

Retrieves a file's content from storage.

init(keyword)

Initializes the adapter. Called during application startup to verify configuration and presence of underlying dependencies.

path(file_id)

Returns a direct local path to the stored file, if supported by the backend.

put(path_or_content, options)

Puts a file into storage.

Types

file_id()

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

options()

@type options() :: keyword()

path_or_content()

@type path_or_content() :: String.t() | binary()

Callbacks

delete(file_id)

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

Deletes a file from storage.

download_url(file_id, options)

@callback download_url(file_id(), options()) :: {:ok, String.t()} | {:error, term()}

Generates a presigned or localized URL for downloading the file.

Options may include :expires_in (in seconds).

get(file_id)

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

Retrieves a file's content from storage.

init(keyword)

@callback init(keyword()) :: :ok | {:error, term()}

Initializes the adapter. Called during application startup to verify configuration and presence of underlying dependencies.

path(file_id)

(optional)

@callback path(file_id()) :: {:ok, String.t()} | {:error, term()}

Returns a direct local path to the stored file, if supported by the backend.

put(path_or_content, options)

@callback put(path_or_content(), options()) :: {:ok, file_id()} | {:error, term()}

Puts a file into storage.

Returns {:ok, file_id} where file_id is a backend-specific identifier (such as an S3 key or a local filesystem path) that can be used with get/1 and download_url/2.