WebsockexNova.ClientConn (WebsockexNova v0.1.1)

View Source

Canonical state for a WebSocket client connection. All core application/session state is explicit and top-level. Handler/feature-specific state is namespaced in maps (e.g., :rate_limit, :logging, :metrics). Adapter-specific state is kept in :adapter_state. :extras is for extensibility.

This struct contains all the information needed to interact with a WebSocket connection, including the transport layer implementation, transport process, stream reference, adapter module, and adapter state.

Fields

  • :transport - The transport module implementing WebsockexNova.Transport
  • :transport_pid - PID of the transport process
  • :stream_ref - WebSocket stream reference
  • :adapter - Adapter module implementing various behaviors
  • :adapter_state - State maintained by the adapter (stores auth status, auth tokens, credentials, subscriptions, etc.)
  • :callback_pids - List of PIDs registered to receive event notifications
  • :connection_info - Connection information and initial configuration
  • :connection_id - Stable identifier that persists across reconnections
  • :rate_limit - Rate limit configuration
  • :logging - Logging configuration
  • :metrics - Metrics configuration
  • :reconnection - Reconnection configuration map for error handler
  • :connection_handler_settings - State specific to the connection handler
  • :auth_handler_settings - State specific to the auth handler
  • :subscription_handler_settings - State specific to the subscription handler
  • :error_handler_settings - State specific to the error handler
  • :message_handler_settings - State specific to the message handler
  • :extras - Extensible/optional state

Summary

Types

Adapter module implementing behaviors

WebSocket stream reference

t()

Client connection structure (canonical state)

WebSocket transport module

Functions

Implements the Access behaviour to enable bracket access (conn[:field]).

Implements the Access behaviour for updating ClientConn fields.

Get the current stream_ref for a connection.

Get the current transport_pid for a connection.

Implements the Access behaviour to pop values from ClientConn fields.

Types

adapter()

@type adapter() :: module()

Adapter module implementing behaviors

stream_ref()

@type stream_ref() :: reference() | any()

WebSocket stream reference

t()

@type t() :: %WebsockexNova.ClientConn{
  adapter: adapter(),
  adapter_state: map(),
  auth_handler_settings: map(),
  callback_pids: MapSet.t(pid()),
  connection_handler_settings: map(),
  connection_id: reference(),
  connection_info: map(),
  error_handler_settings: map(),
  extras: map(),
  logging: map(),
  message_handler_settings: map(),
  metrics: map(),
  rate_limit: map(),
  reconnection: map(),
  stream_ref: stream_ref(),
  subscription_handler_settings: map(),
  transport: transport(),
  transport_pid: pid()
}

Client connection structure (canonical state)

transport()

@type transport() :: module()

WebSocket transport module

Functions

fetch(conn, key)

@spec fetch(t(), atom() | String.t()) :: {:ok, any()} | :error

Implements the Access behaviour to enable bracket access (conn[:field]).

Allows retrieving fields from the ClientConn struct using Access syntax:

Examples

conn[:adapter]
Access.get(conn, :connection_info)
conn["adapter"]
Access.get(conn, "connection_info")

Parameters

  • conn: The ClientConn struct
  • key: The field name to access (atom or string)

Returns

  • {:ok, value} if the key exists
  • :error if the key doesn't exist

get_and_update(conn, key, fun)

@spec get_and_update(t(), atom() | String.t(), (any() -> {any(), any()} | :pop)) ::
  {any(), t()}

Implements the Access behaviour for updating ClientConn fields.

This enables functions like Access.get_and_update/3 to work with ClientConn.

Examples

{old_value, updated_conn} = Access.get_and_update(conn, :adapter_state, fn current ->
  {current, Map.put(current, :new_key, :new_value)}
end)

{old_value, updated_conn} = Access.get_and_update(conn, "adapter_state", fn current ->
  {current, Map.put(current, :new_key, :new_value)}
end)

Parameters

  • conn: The ClientConn struct
  • key: The field name to update (atom or string)
  • function: Function that transforms the current value

Returns

  • {get_value, updated_conn}

get_current_stream_ref(conn)

@spec get_current_stream_ref(t()) :: stream_ref()

Get the current stream_ref for a connection.

This is used alongside get_current_transport_pid to ensure operations use the current stream_ref, which may have changed after reconnection.

Parameters

  • conn: The ClientConn struct

Returns

  • stream_ref: The current stream reference

get_current_transport_pid(conn)

@spec get_current_transport_pid(t()) :: pid()

Get the current transport_pid for a connection.

This function checks the ConnectionRegistry first using the connection_id. If found, it returns the current transport PID. This ensures operations work even after reconnection when the transport_pid might have changed.

If the lookup fails, it falls back to the PID stored in the struct.

Parameters

  • conn: The ClientConn struct

Returns

  • pid: The current transport process PID

pop(conn, key)

@spec pop(t(), atom() | String.t()) :: {any(), t()}

Implements the Access behaviour to pop values from ClientConn fields.

Since ClientConn is a struct with fixed fields, actual removal is not supported. For map-type fields, this can clear the value by setting it to an empty map.

Examples

{value, updated_conn} = Access.pop(conn, :extras)
{value, updated_conn} = Access.pop(conn, "extras")

Parameters

  • conn: The ClientConn struct
  • key: The field name to pop (atom or string)

Returns

  • {current_value, updated_conn}