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

Aborts an in-progress multipart upload, releasing storage-side resources.

Requires the adapter to advertise the :multipart_upload capability. Used by cleanup workers to compensate for orphaned multipart sessions. The success shape is intentionally adapter-specific ({:ok, term()}); on missing uploads adapters typically return {:error, :not_found}, which callers may treat as successful idempotent abort.

@callback cancel_resumable_upload(
  key :: String.t(),
  session_uri :: String.t(),
  opts :: keyword()
) :: {:ok, %{cancelled: boolean()}} | {:error, term()}

Cancels a resumable upload session, releasing remote-side state when possible.

Adapters expose this callback only when they advertise the :resumable_upload_session capability. Missing or expired sessions may still return tagged adapter errors callers treat as idempotent cleanup.

@callback capabilities() :: [capability()]

Returns the adapter's supported capability atoms.

Values must come from capability/0.

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

Finalizes a multipart upload after all parts have been uploaded.

Requires the adapter to advertise the :multipart_upload capability. Callers pass the upload_id and the ordered parts list (each entry carrying at least :part_number and the storage-side ETag). Returns multipart_complete_result/0 describing the assembled object.

@callback complete_part_stream(
  key :: String.t(),
  temp_path :: String.t() | nil,
  state :: tus_part_state(),
  opts :: keyword()
) :: {:ok, map()} | {:error, term()}

Finalizes a tus upload after the last PATCH, converging into the trusted verify/promote lane.

Adapters expose this callback only when they advertise the :tus_upload capability. It is the symmetric companion to upload_part_stream/5: the edge calls it once, polymorphically, after the final PATCH brings the committed offset to Upload-Length — there is no if adapter == Local branch.

temp_path is the final PATCH's drained temp file (the last bytes of the upload), passed for symmetry with upload_part_stream/5; the edge has already appended those bytes during the matching upload_part_stream/5 call, so temp_path is the residual handle the adapter may flush as the last part. state carries the accumulated tus_part_state/0 (S3's :upload_id + ordered :parts).

S3 flushes the remaining tail buffer as the final UploadPart (any size, even below the 5 MiB minimum, since it is the last part) and then complete_multipart_upload/4 with the full ordered parts list from state. Local performs the atomic same-filesystem File.rename of its part file onto the final key. After this returns {:ok, _} the edge calls Rindle.Upload.Broker.verify_completion/2, the single head/2-based trust gate (unchanged), to promote the asset.

@callback concatenate(
  final_key :: String.t(),
  source_keys :: [String.t()],
  opts :: keyword()
) :: {:ok, map()} | {:error, term()}

Combines multiple uploaded chunks into a single final object.

Required for the tus Concatenation extension.

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

Deletes the object at key.

Adapters return a delete_result/0 map (which MAY include :key when known). Deleting a non-existent key is adapter-defined: implementations may return :ok (idempotent) or {:error, :not_found}. Async-purge callers should treat both as successful eventual deletion.

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

Downloads the object at key to destination, returning the destination path.

The adapter reads the object identified by key and writes its bytes to destination. Callers are responsible for ensuring destination is a writable path; adapters may create the parent directory but should not assume it exists. Returns {:error, term()} if the object is missing or unreadable.

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

Returns object metadata (size, content-type) without downloading the body.

Requires the adapter to advertise the :head capability via capabilities/0. The returned head_result/0 carries :size (required) and best-effort :content_type. Used by the upload broker to verify storage-side completion before promoting an asset.

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

Initiates a multipart upload session for key with the given part_size.

Requires the adapter to advertise the :multipart_upload capability via capabilities/0. Returns multipart_init_result/0 carrying the :upload_id adopters must echo back through presigned_upload_part/5, complete_multipart_upload/4, and abort_multipart_upload/3.

@callback initiate_resumable_upload(
  key :: String.t(),
  expected_size :: pos_integer() | nil,
  opts :: keyword()
) :: {:ok, resumable_init_result()} | {:error, term()}

Initiates a resumable upload session for key.

Adapters expose this callback only when they advertise the :resumable_upload capability. Along with verify_resumable_completion/3, it forms the minimum adapter surface behind broker resumable initiation; the broker still owns the session lifecycle and persistence rules.

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

Generates a presigned PUT URL adopters can hand to clients for direct uploads.

Requires the adapter to advertise the :presigned_put capability via capabilities/0. The returned presign_result/0 includes :url, :method, and :headers that the client must use verbatim. expires_in is the URL lifetime in seconds.

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

Generates a presigned URL for one part of an in-progress multipart upload.

Requires the adapter to advertise the :multipart_upload capability. Callers pass the upload_id from initiate_multipart_upload/3 and a 1-based part_number. The returned presign_result/0 carries the part-scoped presigned PUT URL the client uploads the chunk to.

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

Returns remote status for an in-flight resumable upload session.

Adapters expose this callback only when they advertise the :resumable_upload_session capability. Together with cancel_resumable_upload/3, it provides the broker's operational surface for polling and cleanup.

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

Stores the file at source under key, returning adapter-specific write metadata.

Callers must pass an absolute or otherwise resolvable source path. The adapter writes the object at the storage-side address derived from key and returns a put_result/0 containing :key plus any adapter-specific metadata (path, ETag, etc.). Storage I/O must happen outside DB transactions.

@callback upload_part_stream(
  key :: String.t(),
  temp_path :: String.t(),
  base_offset :: non_neg_integer(),
  state :: tus_part_state(),
  opts :: keyword()
) :: {:ok, tus_part_state()} | {:error, term()}

Streams one PATCH body into the adapter's resumable part store for a tus upload.

Adapters expose this callback only when they advertise the :tus_upload capability. The tus edge (Rindle.Upload.TusPlug) drains the PATCH body to a temp file FIRST — bounded by the per-PATCH ceiling, so an oversize body is rejected with 413 before this callback is reached — then hands that temp_path. The temp file therefore holds exactly ONE PATCH worth of bytes; the adapter pulls bytes from it and never buffers the whole upload in memory.

base_offset is the upload's committed offset before this PATCH (the tus Upload-Offset the client sent). state carries the prior tus_part_state/0 (S3's :upload_id + accumulated :parts, or %{offset: n} for Local). Returns the updated tus_part_state/0 to persist on the session row.

S3 appends the temp file to a tail buffer under the sweepable Rindle.tmp/ root, slicing off each full 5 MiB part as a multipart UploadPart and keeping any sub-5-MiB remainder buffered across PATCHes. Local appends the bytes to its per-session part file. The edge dispatches polymorphically — it never branches on the adapter module.

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

Resolves the delivery URL for key.

Public adapters return a bare URL; private adapters return a signed URL whose expiry is governed by the adapter's signed-URL TTL configuration. Authorization (when configured) MUST be evaluated by the caller before invoking this callback; the adapter does not perform authorization itself.

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

Verifies resumable completion through adapter-side metadata lookup.

Adapters expose this callback only when they advertise the :resumable_upload capability. This exists for adapter parity and storage protocol handling, but it does not redefine broker trust: Rindle.Upload.Broker.verify_completion/2 remains head/2-based.