Ircxd.Client.Transport behaviour (ircxd v1.2.0)

Transport boundary for Ircxd.Client.

Ircxd.Client.Transport.Socket is the default adapter and preserves the existing TCP/TLS behavior. A configured adapter owns connection establishment and serialized writes, delivers framed IRC records to the client with deliver/4, and is told when the client accepts a record.

Returning a resumed connection restores bounded protocol state without sending IRC registration commands again. Transport metadata is emitted unchanged in the client's :resumed event. A custom adapter's connect/3 configuration and retained checkpoints exclude credentials and raw TLS options. send_data/2 necessarily receives complete IRC wire records, including registration or authentication commands, so adapters must treat outbound data as sensitive.

Summary

Types

config()

Public, credential-free connection settings passed to an adapter.

handle()

Adapter-owned identity for one active transport connection.

mode()

Whether IRC registration is required for the connected transport.

receipt()

Adapter-owned receipt reported after an inbound record is accepted.

Callbacks

accepted(handle, receipt, arg3)

Reports an accepted receipt and its complete post-record protocol checkpoint.

activate(handle)

Enables delivery of the next inbound record.

checkpoint?(handle)

Returns whether accepted records require resumable parser checkpoints.

close(handle, reason)

Releases one transport handle. Implementations must tolerate repeated calls.

connect(client, config, init_arg)

Connects one client using the adapter's initialization argument.

handle_info(message, handle)

Translates an adapter-owned process message into a transport event.

send_data(handle, iodata)

Writes one serialized IRC record through the active transport.

send_data_once(handle, keys, iodata)

Writes one serialized record once for an adapter-owned set of idempotency keys.

Functions

closed(client, handle, reason)

Reports closure of one transport handle to its client.

deliver(client, handle, receipt, line)

Delivers one framed IRC record to a client using the active transport handle.

Types

config()

@type config() :: %{
  host: String.t(),
  port: :inet.port_number(),
  tls?: boolean(),
  sni: String.t()
}

Public, credential-free connection settings passed to an adapter.

handle()

@type handle() :: term()

Adapter-owned identity for one active transport connection.

mode()

@type mode() :: :fresh | {:resumed, Ircxd.Client.Resume.t(), map()}

Whether IRC registration is required for the connected transport.

receipt()

@type receipt() :: term()

Adapter-owned receipt reported after an inbound record is accepted.

Callbacks

accepted(handle, receipt, arg3)

@callback accepted(
  handle(),
  receipt(),
  Ircxd.Client.Resume.t()
  | nil
  | {:unavailable, Ircxd.Client.Resume.unavailable_reason()}
) :: :ok | {:error, term()}

Reports an accepted receipt and its complete post-record protocol checkpoint.

activate(handle)

@callback activate(handle()) :: :ok | {:error, term()}

Enables delivery of the next inbound record.

checkpoint?(handle)

@callback checkpoint?(handle()) :: boolean()

Returns whether accepted records require resumable parser checkpoints.

close(handle, reason)

@callback close(handle(), reason :: term()) :: :ok | {:error, term()}

Releases one transport handle. Implementations must tolerate repeated calls.

connect(client, config, init_arg)

@callback connect(client :: pid(), config(), init_arg :: term()) ::
  {:ok, handle(), mode()} | {:error, term()}

Connects one client using the adapter's initialization argument.

handle_info(message, handle)

@callback handle_info(message :: term(), handle()) ::
  :unknown | {:data, receipt(), binary()} | {:closed, term()}

Translates an adapter-owned process message into a transport event.

send_data(handle, iodata)

@callback send_data(handle(), iodata()) :: :ok | {:error, term()}

Writes one serialized IRC record through the active transport.

send_data_once(handle, keys, iodata)

(optional)

@callback send_data_once(handle(), keys :: [binary()], iodata()) :: :ok | {:error, term()}

Writes one serialized record once for an adapter-owned set of idempotency keys.

This callback is optional. Ircxd supplies a deduplicated, non-empty list of non-empty binary keys. The adapter defines bounded key retention and must decide all-key repeat and partial-overlap semantics. When the callback is absent, Ircxd falls back to send_data/2 without duplicate suppression.

Functions

closed(client, handle, reason)

@spec closed(pid(), handle(), term()) :: :ok

Reports closure of one transport handle to its client.

deliver(client, handle, receipt, line)

@spec deliver(pid(), handle(), receipt(), binary()) :: :ok

Delivers one framed IRC record to a client using the active transport handle.