Gitility.Error exception (Gitility v0.4.0)

Copy Markdown View Source

The normalized error type for every Gitility operation.

Normal failures return {:error, %Gitility.Error{}} — the public API does not raise for repository data, missing objects, timeouts, or backend failures. Callers branch on code and retryable; backend-specific reasons appear only in a sanitized cause.

The struct is also an exception, so !-variants and truly exceptional paths can raise it directly.

Stable error codes

invalid_argument          invalid_oid              invalid_path
invalid_cursor            unsupported_hash         unsupported_operation
unsupported_regex         not_a_commit             not_a_tree
not_a_blob                ref_not_found            ambiguous_prefix
missing_object            shallow_boundary         malformed_object
malformed_ref             hash_mismatch            pack_checksum_mismatch
index_checksum_mismatch   object_too_large         budget_exceeded
result_too_large          timeout                  await_timeout
cancelled                 busy                     authentication_failed
network_error             cleanup_failed           credentials_unavailable
provider_down             provider_timeout         provider_protocol_error
backend_error             runtime_mismatch         internal_error

Two timeouts are deliberately distinct: :await_timeout means Gitility.Job.await/2 gave up waiting but the job is still running; :timeout means the job's own budget expired and the work was cancelled.

Summary

Types

code()

One of the stable error codes — see the moduledoc.

t()

Functions

codes()

All stable error codes.

new(code, message, opts \\ [])

Builds an error. Used pervasively inside Gitility; also handy in backend implementations that want to surface normalized errors.

Types

code()

@type code() ::
  :internal_error
  | :runtime_mismatch
  | :backend_error
  | :provider_protocol_error
  | :provider_timeout
  | :provider_down
  | :credentials_unavailable
  | :cleanup_failed
  | :network_error
  | :authentication_failed
  | :busy
  | :cancelled
  | :await_timeout
  | :timeout
  | :result_too_large
  | :budget_exceeded
  | :object_too_large
  | :index_checksum_mismatch
  | :pack_checksum_mismatch
  | :hash_mismatch
  | :malformed_ref
  | :malformed_object
  | :shallow_boundary
  | :missing_object
  | :ambiguous_prefix
  | :ref_not_found
  | :not_a_blob
  | :not_a_tree
  | :not_a_commit
  | :unsupported_regex
  | :unsupported_operation
  | :unsupported_hash
  | :invalid_cursor
  | :invalid_path
  | :invalid_oid
  | :invalid_argument

One of the stable error codes — see the moduledoc.

t()

@type t() :: %Gitility.Error{
  __exception__: true,
  cause: term(),
  code: code(),
  details: map(),
  message: String.t(),
  operation: atom() | nil,
  retryable: boolean()
}

Functions

codes()

@spec codes() :: [code()]

All stable error codes.

new(code, message, opts \\ [])

@spec new(code(), String.t(), keyword()) :: t()

Builds an error. Used pervasively inside Gitility; also handy in backend implementations that want to surface normalized errors.