Rindle.Upload.Broker (Rindle v0.1.5)

Copy Markdown View Source

Manages direct-to-storage upload sessions.

Summary

Types

cancel_resumable_result()

Tagged result of cancel_resumable_session/2 — session after broker-side cancellation bookkeeping.

initiate_multipart_result()

Tagged result of initiate_multipart_session/2 — session plus multipart upload metadata.

initiate_resumable_result()

Tagged result of initiate_resumable_session/2 — session plus resumable session metadata.

presigned_payload()

Presigned upload payload returned by sign_url and sign_multipart_part.

resumable_status_result()

Tagged result of resumable_session_status/2 — session plus remote committed bytes.

session_only_result()

Tagged result wrapping just an upload session.

sign_part_result()

Tagged result of sign_multipart_part/3 — session plus presigned part payload.

sign_url_result()

Tagged result of sign_url/2 — session plus presigned PUT payload.

verify_result()

Tagged result of verify_completion/2 and complete_multipart_upload/3 — session plus promoted asset.

Functions

cancel_resumable_session(session_id, opts \\ [])

Cancels a resumable session through the adapter's session-scoped lifecycle.

complete_multipart_upload(session_id, parts, opts \\ [])

Completes a multipart upload, then converges into the trusted verification lane.

initiate_multipart_session(profile_module, opts \\ [])

Initiates a new multipart upload session through the broker-owned lifecycle.

initiate_resumable_session(profile_module, opts \\ [])

Initiates a new resumable upload session through the broker-owned lifecycle.

initiate_session(profile_module, opts \\ [])

Initiates a new direct upload session.

resumable_session_status(session_id, opts \\ [])

Reads resumable session status without broadening the durable FSM semantics.

sign_multipart_part(session_id, part_number, opts \\ [])

Signs a multipart upload part without falling back to the presigned PUT path.

sign_url(session_id, opts \\ [])

Generates a presigned URL for an initialized session.

verify_completion(session_id, opts \\ [])

Verifies that a direct upload was completed in storage.

Types

cancel_resumable_result()

@type cancel_resumable_result() ::
  {:ok, %{session: Rindle.Domain.MediaUploadSession.t()}} | {:error, term()}

Tagged result of cancel_resumable_session/2 — session after broker-side cancellation bookkeeping.

initiate_multipart_result()

@type initiate_multipart_result() ::
  {:ok,
   %{
     session: Rindle.Domain.MediaUploadSession.t(),
     multipart: %{
       upload_id: String.t(),
       upload_key: String.t(),
       part_size: pos_integer(),
       part_headers: map()
     }
   }}
  | {:error, term()}

Tagged result of initiate_multipart_session/2 — session plus multipart upload metadata.

initiate_resumable_result()

@type initiate_resumable_result() ::
  {:ok,
   %{
     session: Rindle.Domain.MediaUploadSession.t(),
     resumable: %{
       session_uri: String.t(),
       upload_id: String.t(),
       expires_at: DateTime.t()
     }
   }}
  | {:error, term()}

Tagged result of initiate_resumable_session/2 — session plus resumable session metadata.

presigned_payload()

@type presigned_payload() :: %{
  :url => String.t(),
  :method => atom() | String.t(),
  :headers => map() | list(),
  optional(:part_number) => pos_integer(),
  optional(:upload_id) => String.t()
}

Presigned upload payload returned by sign_url and sign_multipart_part.

resumable_status_result()

@type resumable_status_result() ::
  {:ok,
   %{
     session: Rindle.Domain.MediaUploadSession.t(),
     committed_bytes: non_neg_integer(),
     state: :in_progress | :complete | :expired
   }}
  | {:error, term()}

Tagged result of resumable_session_status/2 — session plus remote committed bytes.

session_only_result()

@type session_only_result() ::
  {:ok, Rindle.Domain.MediaUploadSession.t()} | {:error, term()}

Tagged result wrapping just an upload session.

sign_part_result()

@type sign_part_result() :: sign_url_result()

Tagged result of sign_multipart_part/3 — session plus presigned part payload.

sign_url_result()

@type sign_url_result() ::
  {:ok,
   %{
     session: Rindle.Domain.MediaUploadSession.t(),
     presigned: presigned_payload()
   }}
  | {:error, term()}

Tagged result of sign_url/2 — session plus presigned PUT payload.

verify_result()

@type verify_result() ::
  {:ok,
   %{
     session: Rindle.Domain.MediaUploadSession.t(),
     asset: Rindle.Domain.MediaAsset.t()
   }}
  | {:error, term()}

Tagged result of verify_completion/2 and complete_multipart_upload/3 — session plus promoted asset.

Functions

cancel_resumable_session(session_id, opts \\ [])

@spec cancel_resumable_session(
  binary(),
  keyword()
) :: cancel_resumable_result()

Cancels a resumable session through the adapter's session-scoped lifecycle.

complete_multipart_upload(session_id, parts, opts \\ [])

@spec complete_multipart_upload(binary(), [map()], keyword()) :: verify_result()

Completes a multipart upload, then converges into the trusted verification lane.

initiate_multipart_session(profile_module, opts \\ [])

@spec initiate_multipart_session(
  module(),
  keyword()
) :: initiate_multipart_result()

Initiates a new multipart upload session through the broker-owned lifecycle.

initiate_resumable_session(profile_module, opts \\ [])

@spec initiate_resumable_session(
  module(),
  keyword()
) :: initiate_resumable_result()

Initiates a new resumable upload session through the broker-owned lifecycle.

initiate_session(profile_module, opts \\ [])

@spec initiate_session(
  module(),
  keyword()
) :: session_only_result()

Initiates a new direct upload session.

Creates a staged MediaAsset and an initialized MediaUploadSession in a single DB transaction, then emits [:rindle, :upload, :start] telemetry AFTER commit.

Examples

# Requires `config :rindle, :repo, MyApp.Repo` and a profile module.
iex> {:ok, session} = Rindle.Upload.Broker.initiate_session(MyApp.MediaProfile, filename: "photo.png")
iex> session.state
"initialized"

resumable_session_status(session_id, opts \\ [])

@spec resumable_session_status(
  binary(),
  keyword()
) :: resumable_status_result()

Reads resumable session status without broadening the durable FSM semantics.

sign_multipart_part(session_id, part_number, opts \\ [])

@spec sign_multipart_part(binary(), pos_integer(), keyword()) :: sign_part_result()

Signs a multipart upload part without falling back to the presigned PUT path.

sign_url(session_id, opts \\ [])

@spec sign_url(
  binary(),
  keyword()
) :: sign_url_result()

Generates a presigned URL for an initialized session.

Transitions the session to signed and returns {:ok, %{session: %MediaUploadSession{}, presigned: %{url: String.t()}}}.

Examples

# Requires `config :rindle, :repo, MyApp.Repo` and a configured S3-compatible storage adapter.
iex> {:ok, %{session: session, presigned: %{url: url}}} =
...>   Rindle.Upload.Broker.sign_url(session_id)
iex> session.state
"signed"
iex> is_binary(url)
true

verify_completion(session_id, opts \\ [])

@spec verify_completion(
  binary(),
  keyword()
) :: verify_result()

Verifies that a direct upload was completed in storage.

Transitions the session to completed and the asset to validating, then enqueues PromoteAsset. Emits [:rindle, :upload, :stop] telemetry AFTER the Ecto.Multi commits.

Examples

# Requires `config :rindle, :repo, MyApp.Repo`, the upload object to exist in storage, and the default `Oban` instance running.
iex> {:ok, %{session: session, asset: asset}} =
...>   Rindle.Upload.Broker.verify_completion(session_id)
iex> session.state
"completed"
iex> asset.state
"validating"