Threadline.Storage behaviour (Threadline v0.12.0)

Stores and retrieves export files and other persistent artifacts.

Threadline uses Threadline.Storage.Local by default. Select another built-in or custom adapter in your host application's configuration:

config :threadline, storage_adapter: MyApp.AuditStorage

A custom adapter implements this behaviour. Threadline passes the keyword list stored under the adapter module to init/1 during application startup when a repository is configured:

config :threadline, MyApp.AuditStorage, region: "us-east-1"

Return :ok from init/1 only when the adapter is ready. Returning {:error, reason} or raising prevents Threadline's supervision tree from starting, so missing dependencies and invalid configuration fail early.

put/2 accepts binary content as the portable cross-adapter contract and returns an opaque file identifier used by the remaining callbacks. The built-in Local adapter also accepts the path of an existing regular file as a Local-specific convenience; custom and remote adapters do not need to support that shortcut.

path/1 is optional. Implement it only when the web process can serve a stored file from its local filesystem. When it is absent, or returns {:error, :not_local}, export delivery uses download_url/2 instead.

See Threadline.Storage.Local for single-node storage and Threadline.Storage.S3 for optional S3-compatible object storage.

Summary

Types

content()

file_id()

options()

Callbacks

delete(file_id)

Deletes a file from storage.

download_url(file_id, options)

Generates a URL for downloading the file.

get(file_id)

Retrieves a file's content from storage.

init(keyword)

Initializes the adapter from its module-keyed configuration.

path(file_id)

Returns a direct local path to the stored file when supported by the adapter.

put(content, options)

Stores binary content.

Types

content()

@type content() :: binary()

file_id()

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

options()

@type options() :: keyword()

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 URL for downloading the file.

Threadline may pass :expires_in in seconds. Remote adapters commonly return a short-lived presigned URL; adapters that cannot generate a URL return an adapter-specific error.

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 from its module-keyed configuration.

Threadline calls this during application startup. Return {:error, reason} for invalid configuration or unavailable dependencies.

path(file_id)

(optional)

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

Returns a direct local path to the stored file when supported by the adapter.

This callback is optional. Adapters without a locally readable file should omit it or return {:error, :not_local}.

put(content, options)

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

Stores binary content.

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.