WebsockexNova.Gun.BehaviorBridge (WebsockexNova v0.1.1)
View SourceConnects Gun events to WebsockexNova behavior callbacks.
This module serves as the bridge between the Gun transport layer and the WebsockexNova behavior-based architecture. It translates Gun-specific events into standardized callbacks to the appropriate behavior implementations.
Responsibilities
The BehaviorBridge has the following key responsibilities:
- Event Translation: Converts Gun-specific messages to behavior-friendly formats
- Routing: Routes events to the appropriate behavior (ConnectionHandler, MessageHandler, ErrorHandler)
- State Management: Maintains and updates connection state based on behavior responses
- Response Processing: Handles behavior return values with appropriate actions
- Error Handling: Ensures robust error handling throughout the bridge
Integration Points
The BehaviorBridge integrates with:
- Gun Connection Events: Handles gun_up, gun_down, and other Gun protocol events
- WebSocket Frames: Processes WebSocket frames and routes them to handlers
- Connection State: Updates and manages connection state through transitions
- Behavior Callbacks: Invokes the appropriate callbacks on behavior implementations
This module is designed to be used internally by the ConnectionWrapper, which acts as the main GenServer responsible for receiving and processing Gun messages.
Summary
Functions
Handles errors encountered during Gun operations.
Handles the :gun_down
message when a connection is lost.
Handles the :gun_up
message when a connection is established.
Handles WebSocket frames received from Gun.
Handles WebSocket upgrades received from Gun.
Determines if reconnection should be attempted after an error.
Functions
@spec handle_error(term(), map(), WebsockexNova.Gun.ConnectionState.t()) :: {:noreply, WebsockexNova.Gun.ConnectionState.t()} | {:noreply, {:reconnect, WebsockexNova.Gun.ConnectionState.t()}} | {:stop, term(), WebsockexNova.Gun.ConnectionState.t()}
Handles errors encountered during Gun operations.
Routes the error to the error handler for processing.
Parameters
error
- The error that occurredcontext
- Additional context about the errorstate
- Current connection state
Returns
{:noreply, updated_state}
- Continue with the updated state{:noreply, {:reconnect, updated_state}}
- Attempt reconnection{:stop, reason, updated_state}
- Stop the process
@spec handle_gun_down( pid() | any(), atom(), term(), WebsockexNova.Gun.ConnectionState.t(), [reference()] | nil, [reference()] | nil ) :: {:noreply, WebsockexNova.Gun.ConnectionState.t()} | {:noreply, {:reconnect, WebsockexNova.Gun.ConnectionState.t()}} | {:stop, term(), WebsockexNova.Gun.ConnectionState.t()}
Handles the :gun_down
message when a connection is lost.
Translates this event to a call to the connection handler's handle_disconnect callback.
Parameters
gun_pid
- The Gun connection PIDprotocol
- The protocol that was in usereason
- Reason for the connection lossstate
- Current connection statekilled_streams
- List of stream references that were killedunprocessed_streams
- List of stream references with unprocessed data
Returns
{:noreply, updated_state}
- Standard response{:noreply, {:reconnect, updated_state}}
- Request reconnection{:stop, reason, updated_state}
- Request process termination
@spec handle_gun_up(pid() | any(), atom(), WebsockexNova.Gun.ConnectionState.t()) :: {:noreply, WebsockexNova.Gun.ConnectionState.t()}
Handles the :gun_up
message when a connection is established.
Translates this event to a call to the connection handler's handle_connect callback.
Parameters
gun_pid
- The Gun connection PIDprotocol
- The protocol that was negotiatedstate
- Current connection state
Returns
{:noreply, updated_state}
or other appropriate return value
@spec handle_websocket_frame( pid() | any(), reference() | any(), tuple(), WebsockexNova.Gun.ConnectionState.t() ) :: {:noreply, WebsockexNova.Gun.ConnectionState.t()} | {:reply, atom(), binary(), WebsockexNova.Gun.ConnectionState.t(), reference() | any()} | {:stop, term(), WebsockexNova.Gun.ConnectionState.t()}
Handles WebSocket frames received from Gun.
Processes the frame and routes it to the appropriate handler.
Parameters
gun_pid
- The Gun connection PIDstream_ref
- The stream reference for the frameframe
- The WebSocket frame (as a tuple like{:text, data}
)state
- Current connection state
Returns
{:noreply, updated_state}
- Standard response{:reply, frame_type, data, updated_state, stream_ref}
- Response to send{:stop, reason, updated_state}
- Stop the process
@spec handle_websocket_upgrade( pid() | any(), reference() | any(), list(), WebsockexNova.Gun.ConnectionState.t() ) :: {:noreply, WebsockexNova.Gun.ConnectionState.t()} | {:stop, term(), WebsockexNova.Gun.ConnectionState.t()}
Handles WebSocket upgrades received from Gun.
Transitions the state to websocket_connected and notifies the connection handler.
Parameters
gun_pid
- The Gun connection PIDstream_ref
- The stream reference for the upgradeheaders
- The response headers receivedstate
- Current connection state
Returns
{:noreply, updated_state}
- Standard response{:stop, reason, updated_state}
- Stop the process
@spec should_reconnect?( term(), non_neg_integer(), WebsockexNova.Gun.ConnectionState.t() ) :: {boolean(), non_neg_integer() | nil}
Determines if reconnection should be attempted after an error.
Consults the error handler to make this decision.
Parameters
error
- The error that caused the disconnectionattempt
- The current reconnection attempt numberstate
- Current connection state
Returns
{true, delay}
- Should reconnect after the specified delay{false, _}
- Should not reconnect