Accrue.Storage behaviour (accrue v0.3.0)

Copy Markdown View Source

Behaviour + facade for pluggable PDF / asset storage.

v1.0 ships Accrue.Storage.Null only — all three callbacks are no-ops: put/3 echoes the key back, get/1 and delete/1 return {:error, :not_configured}. Accrue.Storage.Filesystem is deferred to v1.1. Hosts needing S3 (or any other backend) write a custom adapter implementing the three callbacks below and set config :accrue, :storage_adapter, MyApp.Storage.S3.

Telemetry

[:accrue, :storage, :put | :get | :delete, :start | :stop | :exception] is emitted via Accrue.Telemetry.span/3 with metadata %{adapter: module, key: binary, bytes: non_neg_integer} for put (bytes omitted on get/delete). Raw binary bodies are NEVER placed in metadata — :bytes is a scalar byte_size/1 of the payload only.

Key scheme

Keys are library-derived binaries (e.g., "invoices/<id>.pdf") — never user input in v1.0. The future Filesystem adapter (v1.1) MUST add a path-normalization guard against traversal.

Summary

Types

key()
meta()

Callbacks

delete(key)
get(key)
put(key, binary, meta)

Functions

delete(key)

Deletes the binary stored at key via the configured adapter. Null always returns {:error, :not_configured}.

get(key)

Fetches the binary stored at key via the configured adapter. Null always returns {:error, :not_configured}.

put(key, binary, meta \\ %{})

Stores binary at key via the configured adapter. Returns the canonical key on success (may differ from the input for adapters that apply transforms; Null echoes untouched).

Types

key()

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

meta()

@type meta() :: map()

Callbacks

delete(key)

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

get(key)

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

put(key, binary, meta)

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

Functions

delete(key)

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

Deletes the binary stored at key via the configured adapter. Null always returns {:error, :not_configured}.

get(key)

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

Fetches the binary stored at key via the configured adapter. Null always returns {:error, :not_configured}.

put(key, binary, meta \\ %{})

@spec put(key(), binary(), meta()) :: {:ok, key()} | {:error, term()}

Stores binary at key via the configured adapter. Returns the canonical key on success (may differ from the input for adapters that apply transforms; Null echoes untouched).