WebsockexNova.Gun.Helpers.StateSyncHelpers (WebsockexNova v0.1.1)
View SourceHelpers for synchronizing state between ClientConn and ConnectionState.
This module provides functions to ensure proper state synchronization between
the canonical client state (WebsockexNova.ClientConn
) and the transport-local
state (WebsockexNova.Gun.ConnectionState
).
It implements the state layering principles:
- ClientConn is the canonical source of truth for session state
- ConnectionState only contains transport-local/process-local data
- During transitions (reconnection, ownership transfer), state is properly synchronized
Usage
# During ownership transfer:
updated_client_conn = StateSyncHelpers.sync_from_connection_state(client_conn, connection_state)
# When extracting transport-only state:
transport_state = StateSyncHelpers.extract_transport_state(client_conn)
# When updating client conn with transport state changes:
updated_client_conn = StateSyncHelpers.update_client_conn_from_transport(client_conn, connection_state)
Summary
Functions
Creates a ClientConn struct from a ConnectionState and existing ClientConn.
Extracts transport-level information from a ClientConn struct.
Registers a callback PID in both the ConnectionState and ClientConn.
Synchronizes client connection information from ConnectionState to ClientConn.
Synchronizes connection state information from ClientConn to ConnectionState.
Synchronizes handler modules between ClientConn connection_info and ConnectionState handlers.
Unregisters a callback PID from both the ConnectionState and ClientConn.
Updates a ClientConn struct with transport state from a ConnectionState.
Functions
@spec create_client_conn( WebsockexNova.ClientConn.t() | nil, WebsockexNova.Gun.ConnectionState.t() ) :: WebsockexNova.ClientConn.t()
Creates a ClientConn struct from a ConnectionState and existing ClientConn.
This is used when you need to call a behavior callback that expects a ClientConn but you only have ConnectionState. It preserves session data from the existing ClientConn while updating transport-specific fields from ConnectionState.
Parameters
client_conn
- The existing ClientConn struct (can be nil if creating fresh)conn_state
- The ConnectionState with transport information
Returns
A new or updated ClientConn struct
@spec extract_transport_state(WebsockexNova.ClientConn.t()) :: map()
Extracts transport-level information from a ClientConn struct.
Use this when you need to populate a ConnectionState with the configuration from a ClientConn, but don't want to copy user/session state.
Parameters
client_conn
- The ClientConn struct to extract transport info from
Returns
Map with transport-only fields that can be used to build a ConnectionState
@spec register_callback( WebsockexNova.ClientConn.t(), WebsockexNova.Gun.ConnectionState.t(), pid() ) :: {WebsockexNova.ClientConn.t(), WebsockexNova.Gun.ConnectionState.t()}
Registers a callback PID in both the ConnectionState and ClientConn.
Parameters
client_conn
- The ClientConn to updateconn_state
- The ConnectionState to updatepid
- The PID to register
Returns
{updated_client_conn, updated_conn_state}
@spec sync_client_conn_from_connection( WebsockexNova.ClientConn.t(), WebsockexNova.Gun.ConnectionState.t() ) :: WebsockexNova.ClientConn.t()
Synchronizes client connection information from ConnectionState to ClientConn.
This updates the ClientConn with the latest transport state from ConnectionState. Used during ownership transfer and status changes.
Parameters
client_conn
- The ClientConn to updateconn_state
- The ConnectionState with updated transport information
Returns
Updated ClientConn struct
@spec sync_connection_state_from_client( WebsockexNova.Gun.ConnectionState.t(), WebsockexNova.ClientConn.t() ) :: WebsockexNova.Gun.ConnectionState.t()
Synchronizes connection state information from ClientConn to ConnectionState.
This ensures the ConnectionState has the latest configuration from ClientConn without copying session state. Used during reconnection and initialization.
Parameters
conn_state
- The ConnectionState to updateclient_conn
- The ClientConn with canonical configuration
Returns
Updated ConnectionState
@spec sync_handler_modules( WebsockexNova.ClientConn.t(), WebsockexNova.Gun.ConnectionState.t() ) :: WebsockexNova.ClientConn.t()
Synchronizes handler modules between ClientConn connection_info and ConnectionState handlers.
Parameters
client_conn
- The ClientConn to updateconn_state
- The ConnectionState with handler module information
Returns
Updated ClientConn struct
@spec unregister_callback( WebsockexNova.ClientConn.t(), WebsockexNova.Gun.ConnectionState.t(), pid() ) :: {WebsockexNova.ClientConn.t(), WebsockexNova.Gun.ConnectionState.t()}
Unregisters a callback PID from both the ConnectionState and ClientConn.
Parameters
client_conn
- The ClientConn to updateconn_state
- The ConnectionState to updatepid
- The PID to unregister
Returns
{updated_client_conn, updated_conn_state} - ConnectionState will have nil callback_pid if the removed PID was the current one
@spec update_client_conn_from_transport( WebsockexNova.ClientConn.t(), WebsockexNova.Gun.ConnectionState.t() ) :: WebsockexNova.ClientConn.t()
Updates a ClientConn struct with transport state from a ConnectionState.
This should be used when the transport layer has information that needs to be reflected in the canonical client state (e.g., connection status, error).
Parameters
client_conn
- The ClientConn struct to updateconn_state
- The ConnectionState with updated transport information
Returns
Updated ClientConn struct