@callback checksum(key()) :: {:ok, String.t() | nil} | {:error, term()}

The SHA-256 of the file with key, in Base64, as the store knows it, or nil when it keeps none: for a file uploaded straight to it. Optional.

@callback copy(from :: key(), to :: key()) :: :ok | {:error, term()}

Copies the file with key from to the key to, in the store, without it going through the app: to make a temporary file permanent (Storehouse.promote/2). A missing from gives {:error, :enoent}. Optional.

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

Deletes the file with key. A key with no file gives :ok.

@callback delete_many([key()]) :: :ok | {:error, term()}

Deletes the files with keys, at most a thousand, at once. A key with no file is deleted. Optional: without it, Storehouse.delete_prefix/2 deletes one at a time with delete/1.

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

What the store knows of the file with key, without reading it: to learn its size before a byte of it is read (Storehouse.head/2). A missing file gives {:error, :enoent}. Optional, with read_range/3.

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

The files whose keys start with prefix, in the order of their keys, as an enumerable that asks the store as it is taken (and raises Storehouse.ReadError when the store fails then). Optional. See Storehouse.list/2.

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

Gives up an upload: its parts are deleted.

@callback multipart_complete(key(), String.t(), [part()]) :: :ok | {:error, term()}

Puts the parts together: the file is then under its key.

@callback multipart_parts(key(), String.t()) :: {:ok, [part()]} | {:error, term()}

The parts the store has of an upload: {:ok, parts}, by number.

@callback multipart_put(key(), String.t(), pos_integer(), binary()) ::
  {:ok, part()} | {:error, term()}

Sends part number of an upload from the app itself (Storehouse.Tus.Plug), with its SHA-256, which the store checks: {:ok, part}.

@callback multipart_sign(key(), String.t(), pos_integer(), keyword()) ::
  {:ok, %{method: String.t(), url: String.t(), headers: map()}}
  | {:error, term()}

Signs the browser's PUT of part number, with its SHA-256 in Base64 (:checksum) when it is given, so that the store refuses other bytes, and its size (:bytes) when it is given, so that it refuses a larger part: {:ok, %{method: "PUT", url: …, headers: %{…}}}.

@callback multipart_start(key(), meta()) :: {:ok, String.t()} | {:error, term()}

Starts a multipart upload of a file under key, of meta's type, that the browser sends in parts straight to the store (Storehouse.presign_multipart/4): {:ok, upload_id}. Optional, with the other multipart_ callbacks: Storehouse.S3 has them.

@callback multipart_uploads(prefix :: String.t()) ::
  {:ok, [%{key: key(), upload_id: String.t(), started_at: DateTime.t()}]}
  | {:error, term()}

The uploads under prefix started and neither completed nor given up, with their :key, :upload_id and :started_at: for the sweeper.

@callback presign_upload(key(), meta(), opts :: keyword()) ::
  {:ok, upload()} | {:error, term()}

An upload of the file with key that a browser makes itself, without the store's keys, valid opts[:expires_in] seconds: of meta.bytes bytes exactly, of the type meta.content_type. Optional: a store without it takes its files through the app (Storehouse.store/2). See Storehouse.presign_upload/4.

@callback put(key(), path :: Path.t(), meta()) ::
  {:ok, url :: String.t()} | {:error, term()}

Stores the file at path under key, and returns its URL.

The file at path is a temporary file: the adapter copies it, and keeps no reference to it.

@callback read_head(key(), bytes :: pos_integer()) ::
  {:ok, head :: binary(), size :: non_neg_integer()} | {:error, term()}

The first bytes bytes of the file with key (all of it, when it is shorter), and its size: to check a file uploaded straight to the store. Optional; needed with presign_upload/3.

@callback read_range(key(), first :: non_neg_integer(), last :: non_neg_integer()) ::
  {:ok, binary()} | {:error, term()}

The bytes of the file with key from first to last, both included (fewer, when the file ends sooner; "" past its end): what Storehouse.read/2, Storehouse.stream/2 and Storehouse.download/3 read the file with, a part at a time. A missing file gives {:error, :enoent}. Optional, with head/1.

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

A URL of the file with key that is valid opts[:expires_in] seconds, for a file that is not public. opts[:disposition] is "inline" or "attachment", and opts[:filename] the name a download gets, when given. Optional. See Storehouse.signed_url/2.

@callback stream_abort(stream :: term()) :: :ok

Gives up a streamed file: nothing of it stays in the store.

@callback stream_close(stream :: term()) :: {:ok, url :: String.t()} | {:error, term()}

Ends a streamed file, which is then in the store: its URL.

@callback stream_open(key(), meta()) :: {:ok, stream :: term()} | {:error, term()}

Opens a file with key that its bytes are written to as they come, in stream_write/2: an upload streamed through the app, with no file of its own on the disk (Storehouse.Live.allow/3, mode: :stream). Optional, with the three other stream_ callbacks.

@callback stream_write(stream :: term(), iodata()) ::
  {:ok, stream :: term()} | {:error, term()}

Writes the next bytes of a streamed file.

@callback uploaded(key()) :: :ok

Told that a file the browser uploaded straight to the store (presign_upload/3) was checked and kept (Storehouse.verify_upload/2): for a store that does more with a file it takes (Storehouse.Mirror copies it to its mirrors). Optional.

@callback url(key()) :: String.t()

Returns the URL of the file with key.