Bsdkrun.Error exception (bsdkrun_ex v0.4.0)

Copy Markdown View Source

The single exception type raised (or returned in {:error, _} tuples) by the SDK. kind discriminates the failure:

  • :binary_not_found — the bsdkrun binary could not be located.
  • :command_failed — a bsdkrun invocation exited non-zero. Carries exit_code, stdout, stderr, and the label of the command.
  • :sandbox_not_found — no machine matched the given id / prefix.
  • :auth_error — the remote daemon (Bsdkrun.Client) rejected the bearer token, either over HTTP (401) or a GraphQL error with extensions.code == "UNAUTHENTICATED", or a graphql-transport-ws socket that closed before connection_ack ever arrived.
  • :graphql_error — any other Bsdkrun.Client failure: an unreachable daemon, a non-GraphQL response, or a GraphQL errors[] entry that isn't an auth failure. code carries the GraphQL extensions.code, if any.
  • :config_error — invalid or missing Bsdkrun.Client.from_env/0 configuration.

Summary

Types

kind()

The category of failure this error represents.

t()

Functions

auth_error(message \\ "the daemon rejected this token")

Build an :auth_error — the daemon rejected the bearer token.

binary_not_found(searched)

Build a :binary_not_found error listing the paths that were searched.

command_failed(exit_code, stdout, stderr, label)

Build a :command_failed error from a captured CLI result.

config_error(message)

Build a :config_error for invalid/missing Bsdkrun.Client.from_env/0 configuration.

file_transfer(message, path)

Build a :file_transfer error — a guest filesystem operation was refused.

graphql_error(message, code \\ nil)

Build a :graphql_error — an unreachable daemon, a non-GraphQL response, or a GraphQL errors[] entry that isn't an auth failure. code is the GraphQL extensions.code, if the server sent one.

sandbox_not_found(id)

Build a :sandbox_not_found error for the given id / prefix.

Types

kind()

@type kind() ::
  :binary_not_found
  | :command_failed
  | :sandbox_not_found
  | :file_transfer
  | :auth_error
  | :graphql_error
  | :config_error

The category of failure this error represents.

t()

@type t() :: %Bsdkrun.Error{
  __exception__: true,
  code: String.t() | nil,
  exit_code: integer() | nil,
  kind: kind(),
  label: String.t() | nil,
  message: String.t(),
  searched: [String.t()] | nil,
  stderr: String.t() | nil,
  stdout: String.t() | nil
}

Functions

auth_error(message \\ "the daemon rejected this token")

@spec auth_error(String.t()) :: t()

Build an :auth_error — the daemon rejected the bearer token.

binary_not_found(searched)

@spec binary_not_found([String.t()]) :: t()

Build a :binary_not_found error listing the paths that were searched.

command_failed(exit_code, stdout, stderr, label)

@spec command_failed(integer(), String.t(), String.t(), String.t()) :: t()

Build a :command_failed error from a captured CLI result.

config_error(message)

@spec config_error(String.t()) :: t()

Build a :config_error for invalid/missing Bsdkrun.Client.from_env/0 configuration.

file_transfer(message, path)

@spec file_transfer(String.t(), String.t()) :: t()

Build a :file_transfer error — a guest filesystem operation was refused.

label carries the path that could not be transferred.

graphql_error(message, code \\ nil)

@spec graphql_error(String.t(), String.t() | nil) :: t()

Build a :graphql_error — an unreachable daemon, a non-GraphQL response, or a GraphQL errors[] entry that isn't an auth failure. code is the GraphQL extensions.code, if the server sent one.

sandbox_not_found(id)

@spec sandbox_not_found(String.t()) :: t()

Build a :sandbox_not_found error for the given id / prefix.