SSL.Lifecycle (ex_ssl v1.0.0-rc.9)

Provider lifecycle evidence and transferable cancellation authority.

Create a handle before connecting and pass {handle, lease} under ex_ssl: [lifecycle: ...]. A successful cancel accepts retirement; only a confirmed await receipt establishes local resource cleanup. Control deadlines are finite absolute monotonic milliseconds. Handles contain no cancellation authority and remain readable after the provider exits.

Summary

Functions

accept(transfer, deadline)

await(handle, deadline)

cancel(lease, deadline)

connect_failure(arg1)

Reads authenticated native connection failure evidence before establishment.

layers(descriptor)

Returns the fixed outer and inner scalar descriptors of one pair reservation.

new(options)

new_pair(options)

Reserves both independent lifecycle obligations before nested TLS performs I/O.

offer(lease, target, deadline)

offer_controller(arg1, controller, deadline)

Offers a new cancellation controller while preserving the provider's current socket owner.

setup_failure(arg1)

Reads authenticated fatal setup-phase evidence separately from resource cleanup.

status(handle)

status(handle, deadline)

Observes exact live resource counts within one finite absolute deadline.

Functions

accept(transfer, deadline)

@spec accept(
  SSL.Lifecycle.Transfer.t() | SSL.Lifecycle.Pair.Transfer.t(),
  {:abs_ms, integer()}
) ::
  term()

await(handle, deadline)

@spec await(
  SSL.Lifecycle.Handle.t() | SSL.Lifecycle.Pair.Handle.t(),
  {:abs_ms, integer()}
) :: term()

cancel(lease, deadline)

@spec cancel(
  SSL.Lifecycle.Lease.t() | SSL.Lifecycle.Pair.Lease.t(),
  {:abs_ms, integer()}
) ::
  :ok | {:error, term()}

connect_failure(arg1)

@spec connect_failure(SSL.Lifecycle.Handle.t()) ::
  {:ok, %{phase: :connect}} | :unknown

Reads authenticated native connection failure evidence before establishment.

Only the original allocator's observed failure, committed with its original resource ownership and deadline, establishes this phase. A generic setup error, cancellation, timeout or missing publication returns :unknown. The evidence survives provider exit and does not establish cleanup; use await/2 separately.

layers(descriptor)

@spec layers({SSL.Lifecycle.Pair.Handle.t(), SSL.Lifecycle.Pair.Lease.t()}) ::
  {:ok, map()} | {:error, atom()}

Returns the fixed outer and inner scalar descriptors of one pair reservation.

new(options)

@spec new(keyword()) ::
  {:ok, SSL.Lifecycle.Handle.t(), SSL.Lifecycle.Lease.t()} | {:error, atom()}

new_pair(options)

@spec new_pair(keyword()) ::
  {:ok, SSL.Lifecycle.Pair.Handle.t(), SSL.Lifecycle.Pair.Lease.t()}
  | {:error, term()}

Reserves both independent lifecycle obligations before nested TLS performs I/O.

Use layers/1 to give each scalar descriptor to its own TLS connection. Pair status and await require both receipts; a layer receipt never proves outer TCP cleanup. No extra data process or physical socket is allocated by the pair.

offer(lease, target, deadline)

@spec offer(
  SSL.Lifecycle.Lease.t() | SSL.Lifecycle.Pair.Lease.t(),
  %{controller: pid(), owner: pid()},
  {:abs_ms, integer()}
) :: term()

offer_controller(arg1, controller, deadline)

@spec offer_controller(SSL.Lifecycle.Lease.t(), pid(), {:abs_ms, integer()}) :: term()

Offers a new cancellation controller while preserving the provider's current socket owner.

setup_failure(arg1)

@spec setup_failure(SSL.Lifecycle.Handle.t()) ::
  {:ok, %{phase: :tls_setup}} | :unknown

Reads authenticated fatal setup-phase evidence separately from resource cleanup.

A proven result means the original Connection accepted ServerHello and committed a fatal setup failure within its original deadline. The fixed result survives provider exit. Missing or uncommitted evidence returns :unknown; cancellation, timeout, and a successful handshake alone do not establish this phase. Use await/2 separately to establish local resource cleanup.

status(handle)

@spec status(SSL.Lifecycle.Handle.t() | SSL.Lifecycle.Pair.Handle.t()) ::
  {:pending, map()} | {:terminal, map()} | {:unconfirmed, term()}

status(handle, deadline)

@spec status(
  SSL.Lifecycle.Handle.t() | SSL.Lifecycle.Pair.Handle.t(),
  {:abs_ms, integer()}
) :: term()

Observes exact live resource counts within one finite absolute deadline.