WebsockexNova.Gun.Helpers.StateSyncHelpers (WebsockexNova v0.1.1)

View Source

Helpers 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

create_client_conn(client_conn \\ nil, conn_state)

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

extract_transport_state(client_conn)

@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

register_callback(client_conn, conn_state, pid)

Registers a callback PID in both the ConnectionState and ClientConn.

Parameters

  • client_conn - The ClientConn to update
  • conn_state - The ConnectionState to update
  • pid - The PID to register

Returns

{updated_client_conn, updated_conn_state}

sync_client_conn_from_connection(client_conn, conn_state)

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 update
  • conn_state - The ConnectionState with updated transport information

Returns

Updated ClientConn struct

sync_connection_state_from_client(conn_state, client_conn)

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 update
  • client_conn - The ClientConn with canonical configuration

Returns

Updated ConnectionState

sync_handler_modules(client_conn, conn_state)

Synchronizes handler modules between ClientConn connection_info and ConnectionState handlers.

Parameters

  • client_conn - The ClientConn to update
  • conn_state - The ConnectionState with handler module information

Returns

Updated ClientConn struct

unregister_callback(client_conn, conn_state, pid)

Unregisters a callback PID from both the ConnectionState and ClientConn.

Parameters

  • client_conn - The ClientConn to update
  • conn_state - The ConnectionState to update
  • pid - 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

update_client_conn_from_transport(client_conn, conn_state)

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 update
  • conn_state - The ConnectionState with updated transport information

Returns

Updated ClientConn struct