rindle

defmodule Rindle.Storage do
  @moduledoc """
  Behaviour contract for all storage adapters used by Rindle.

  Storage I/O must never happen inside database transactions. Callers should
  persist domain state first, then execute storage side effects in separate
  steps.
  """

  @typedoc """
  Shared storage capability vocabulary exposed by adapters via `c:capabilities/0`.

  Current adapters only need to advertise the capabilities they actually
  support. Additional resumable-oriented atoms are reserved additively for
  future adapters.
  """
  @type capability :: Rindle.Storage.Capabilities.capability()

  @callback store(key :: String.t(), source :: Path.t(), opts :: keyword()) ::
              {:ok, term()} | {:error, term()}

  @callback download(key :: String.t(), destination :: Path.t(), opts :: keyword()) ::
              {:ok, Path.t()} | {:error, term()}

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

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

  @callback presigned_put(key :: String.t(), expires_in :: pos_integer(), opts :: keyword()) ::
              {:ok, map()} | {:error, term()}

  @callback initiate_multipart_upload(
              key :: String.t(),
              part_size :: pos_integer(),
              opts :: keyword()
            ) :: {:ok, map()} | {:error, term()}

  @callback presigned_upload_part(
              key :: String.t(),
              upload_id :: String.t(),
              part_number :: pos_integer(),
              expires_in :: pos_integer(),
              opts :: keyword()
            ) :: {:ok, map()} | {:error, term()}

  @callback complete_multipart_upload(
              key :: String.t(),
              upload_id :: String.t(),
              parts :: [map() | {pos_integer(), String.t()}],
              opts :: keyword()
            ) :: {:ok, map()} | {:error, term()}

  @callback abort_multipart_upload(
              key :: String.t(),
              upload_id :: String.t(),
              opts :: keyword()
            ) :: {:ok, term()} | {:error, term()}

  @callback head(key :: String.t(), opts :: keyword()) ::
              {:ok, map()} | {:error, term()}

  @doc """
  Returns the adapter's supported capability atoms.

  Values must come from `t:capability/0`.
  """
  @callback capabilities() :: [capability()]
end