WebsockexNova.ClientConn (WebsockexNova v0.1.0)
View SourceCanonical 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 implementingWebsockexNova.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
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
@type adapter() :: module()
Adapter module implementing behaviors
WebSocket stream reference
@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)
@type transport() :: module()
WebSocket transport module
Functions
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
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}
@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 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
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}