WebsockexNova.Gun.ConnectionState (WebsockexNova v0.1.0)

View Source

State structure for ConnectionWrapper.

This module defines the state structure used by the ConnectionWrapper, providing better type safety and organization of state data.

IMPORTANT: State Layering

This struct should ONLY contain transport-layer, process-local, or Gun-specific data. It should NOT store canonical application-level state like:

  • Authentication
  • Subscriptions
  • User credentials
  • Application handler state

The canonical application state lives in WebsockexNova.ClientConn. This struct may reference a ClientConn struct for operations, but should never duplicate the canonical state.

Reconnection Policy

  • The connection state no longer tracks reconnection attempts or delays.
  • All reconnection policy and tracking is handled by the error handler.

Summary

Types

Connection status

t()

Connection state structure

Functions

Adds an active stream to the state with the given status and data.

Clears all active streams from the state.

Gets the callback PID from the state.

Creates a new connection state.

Prepares the state for process termination by clearing references and resources.

Records an error in the state.

Removes a stream from the active streams map.

Removes multiple streams from the active streams map.

Sets up the auth handler module and stores it in the handlers map.

Sets up the connection handler module and stores it in the handlers map.

Sets up the error handler module and stores it in the handlers map.

Setup the logging handler module.

Sets up the message handler module and stores it in the handlers map.

Sets up the subscription handler module and stores it in the handlers map.

Updates the active streams map.

Updates the callback PID in the state.

Updates the connection handler state within the handlers map.

Updates the Gun connection monitor reference in the state.

Updates the Gun connection PID in the state.

Updates a handler module reference.

Updates multiple handlers at once in the handlers map.

Updates the connection status in the state.

Updates or adds a stream in the active streams map.

Types

status()

@type status() ::
  :initialized
  | :connecting
  | :connected
  | :websocket_connected
  | :disconnected
  | :reconnecting
  | :error
  | :closed

Connection status

t()

@type t() :: %WebsockexNova.Gun.ConnectionState{
  active_streams: %{required(reference()) => map()},
  callback_pid: pid() | nil,
  client_conns: %{required(reference()) => struct()},
  gun_monitor_ref: reference() | nil,
  gun_pid: pid() | nil,
  handlers: %{
    optional(:connection_handler) => module(),
    optional(:message_handler) => module(),
    optional(:error_handler) => module(),
    optional(:logging_handler) => module(),
    optional(:subscription_handler) => module(),
    optional(:auth_handler) => module(),
    optional(:rate_limit_handler) => module(),
    optional(:metrics_collector) => module()
  },
  host: String.t(),
  last_error: term() | nil,
  options: map(),
  path: String.t(),
  port: non_neg_integer(),
  status: status(),
  transport: atom(),
  ws_opts: map()
}

Connection state structure

Functions

add_active_stream(state, stream_ref, stream_data)

@spec add_active_stream(t(), reference(), atom() | map()) :: t()

Adds an active stream to the state with the given status and data.

Parameters

  • state - Current connection state
  • stream_ref - Stream reference to add
  • stream_data - Data for the stream, can be either an atom status or a map with data

Returns

Updated connection state struct

clear_all_streams(state)

@spec clear_all_streams(t()) :: t()

Clears all active streams from the state.

Parameters

  • state - Current connection state

Returns

Updated connection state struct with empty active_streams

get_callback_pid(state)

@spec get_callback_pid(t()) :: pid() | nil

Gets the callback PID from the state.

Parameters

  • state - Current connection state

Returns

The callback PID, or nil if none exists

new(host, port, options)

@spec new(String.t(), non_neg_integer(), map()) :: t()

Creates a new connection state.

Parameters

  • host - The hostname to connect to
  • port - The port to connect to
  • options - Connection options (only transport configuration is stored)

Returns

A new connection state struct

prepare_for_termination(state)

@spec prepare_for_termination(t()) :: t()

Prepares the state for process termination by clearing references and resources.

Parameters

  • state - Current connection state

Returns

Updated connection state ready for termination

record_error(state, error)

@spec record_error(t(), term()) :: t()

Records an error in the state.

Parameters

  • state - Current connection state
  • error - Error to record

Returns

Updated connection state struct

remove_stream(state, stream_ref)

@spec remove_stream(t(), reference()) :: t()

Removes a stream from the active streams map.

Parameters

  • state - Current connection state
  • stream_ref - Stream reference to remove

Returns

Updated connection state struct

remove_streams(state, stream_refs)

@spec remove_streams(t(), [reference()]) :: t()

Removes multiple streams from the active streams map.

Parameters

  • state - Current connection state
  • stream_refs - List of stream references to remove

Returns

Updated connection state struct

setup_auth_handler(state, auth_handler, options)

@spec setup_auth_handler(t(), module(), map()) :: t()

Sets up the auth handler module and stores it in the handlers map.

Parameters

  • state - Current connection state
  • auth_handler - Auth handler module
  • options - Handler options (not stored in ConnectionState)

Returns

Updated connection state struct

setup_connection_handler(state, connection_handler, options)

@spec setup_connection_handler(t(), module(), map()) :: t()

Sets up the connection handler module and stores it in the handlers map.

Parameters

  • state - Current connection state
  • connection_handler - Connection handler module
  • options - Handler options (not stored in ConnectionState)

Returns

Updated connection state struct

setup_error_handler(state, error_handler, options)

@spec setup_error_handler(t(), module(), map()) :: t()

Sets up the error handler module and stores it in the handlers map.

Parameters

  • state - Current connection state
  • error_handler - Error handler module
  • options - Handler options (not stored in ConnectionState)

Returns

Updated connection state struct

setup_logging_handler(state, logging_handler, options)

@spec setup_logging_handler(t(), module(), map()) :: t()

Setup the logging handler module.

Parameters

  • state - Current connection state
  • logging_handler - Logging handler module
  • _options - Logging handler options (not stored in ConnectionState)

Returns

Updated connection state struct

setup_message_handler(state, message_handler, options)

@spec setup_message_handler(t(), module(), map()) :: t()

Sets up the message handler module and stores it in the handlers map.

Parameters

  • state - Current connection state
  • message_handler - Message handler module
  • options - Handler options (not stored in ConnectionState)

Returns

Updated connection state struct

setup_subscription_handler(state, subscription_handler, options)

@spec setup_subscription_handler(t(), module(), map()) :: t()

Sets up the subscription handler module and stores it in the handlers map.

Parameters

  • state - Current connection state
  • subscription_handler - Subscription handler module
  • options - Handler options (not stored in ConnectionState)

Returns

Updated connection state struct

update_active_streams(state, active_streams)

@spec update_active_streams(t(), map()) :: t()

Updates the active streams map.

Parameters

  • state - Current connection state
  • active_streams - Map of stream references to stream data

Returns

Updated connection state struct

update_callback_pid(state, pid)

@spec update_callback_pid(t(), pid() | nil) :: t()

Updates the callback PID in the state.

Parameters

  • state - Current connection state
  • pid - New callback PID

Returns

Updated connection state struct

update_connection_handler_state(state, handler_state)

@spec update_connection_handler_state(t(), any()) :: t()

Updates the connection handler state within the handlers map.

Parameters

  • state - Current connection state
  • handler_state - New handler state to store

Returns

Updated connection state struct

update_gun_monitor_ref(state, monitor_ref)

@spec update_gun_monitor_ref(t(), reference() | nil) :: t()

Updates the Gun connection monitor reference in the state.

Parameters

  • state - Current connection state
  • monitor_ref - Monitor reference for the Gun process

Returns

Updated connection state struct

update_gun_pid(state, gun_pid)

@spec update_gun_pid(t(), pid() | nil) :: t()

Updates the Gun connection PID in the state.

Parameters

  • state - Current connection state
  • gun_pid - The Gun connection process PID

Returns

Updated connection state struct

update_handler(state, handler_key, module)

@spec update_handler(t(), atom(), module()) :: t()

Updates a handler module reference.

Parameters

  • state - Current connection state
  • handler_key - Key for the handler (:connection_handler, :message_handler, etc.)
  • module - Handler module

Returns

Updated connection state struct

update_handlers(state, handlers)

@spec update_handlers(t(), map()) :: t()

Updates multiple handlers at once in the handlers map.

Parameters

  • state - Current connection state
  • handlers - Map of handler keys to handler modules or state

Returns

Updated connection state struct

update_status(state, status)

@spec update_status(t(), status()) :: t()

Updates the connection status in the state.

Parameters

  • state - Current connection state
  • status - New status to set

Returns

Updated connection state struct

update_stream(state, stream_ref, status)

@spec update_stream(t(), reference(), atom()) :: t()

Updates or adds a stream in the active streams map.

Parameters

  • state - Current connection state
  • stream_ref - Stream reference
  • status - Stream status

Returns

Updated connection state struct