Capstan.Error exception (Capstan v0.1.0)

Copy Markdown View Source

A typed, value-free error — the boundary normaliser that scrubs a raw driver / socket error, exception, or reason tuple to a stable atom reason (Rule 1, design § Rule 1 / F11).

No row value, column value, or connection password ever reaches a field here. A raw reason that could embed a value — a %SomeError{message: "... 'secret' ..."}, a connection keyword carrying password:, a nested tuple — is reduced to its structural shape: the exception's MODULE name (never its message) on :shape, or a stable atom on :reason. message/1 and the derived Inspect render ONLY the structural fields, so even a field a careless caller loaded with a value is never surfaced by the default string / inspect forms.

Mirrors replicant/lib/replicant/error.ex — refuse to leak DB payloads at the boundary.

Summary

Types

reason()

A stable, value-free error reason atom.

t()

Functions

from(error)

Normalise any raw reason / exception / tuple into a value-free Capstan.Error.

Types

reason()

@type reason() ::
  :config_invalid
  | :server_id_required
  | :tls_verification_unspecified
  | :invalid_sink
  | :sink_missing_handle_transaction
  | :sink_missing_checkpoint
  | :sink_missing_handle_schema_change
  | :checkpoint_store_required
  | :sink_owned_mode_unsupported
  | :start_position_current_unsupported
  | :start_position_override_unsupported
  | :unknown
  | atom()

A stable, value-free error reason atom.

t()

@type t() :: %Capstan.Error{
  __exception__: true,
  reason: reason(),
  shape: String.t() | nil
}

Functions

from(error)

@spec from(term()) :: t()

Normalise any raw reason / exception / tuple into a value-free Capstan.Error.

  • a Capstan.Error passes through unchanged;
  • a value-free atom stays as the :reason (capstan's reasons are atoms by construction);
  • an exception keeps ONLY inspect(module) on :shape — its message, which may embed a row value or a password, is discarded;
  • a {tag, payload} tuple keeps only the atom tag as the reason and discards the payload (which may carry a value or the connection keyword);
  • anything else — a bare string, a map, a list — is :unknown with no retained payload (a value must never survive as a captured term).