WebsockexNova.Gun.BehaviorBridge (WebsockexNova v0.1.0)

View Source

Connects 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:

  1. Event Translation: Converts Gun-specific messages to behavior-friendly formats
  2. Routing: Routes events to the appropriate behavior (ConnectionHandler, MessageHandler, ErrorHandler)
  3. State Management: Maintains and updates connection state based on behavior responses
  4. Response Processing: Handles behavior return values with appropriate actions
  5. 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_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

handle_error(error, context, state)

Handles errors encountered during Gun operations.

Routes the error to the error handler for processing.

Parameters

  • error - The error that occurred
  • context - Additional context about the error
  • state - 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

handle_gun_down(gun_pid, protocol, reason, state, killed_streams \\ [], unprocessed_streams \\ [])

@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 PID
  • protocol - The protocol that was in use
  • reason - Reason for the connection loss
  • state - Current connection state
  • killed_streams - List of stream references that were killed
  • unprocessed_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

handle_gun_up(gun_pid, protocol, state)

@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 PID
  • protocol - The protocol that was negotiated
  • state - Current connection state

Returns

{:noreply, updated_state} or other appropriate return value

handle_websocket_frame(gun_pid, stream_ref, frame, state)

@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 PID
  • stream_ref - The stream reference for the frame
  • frame - 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

handle_websocket_upgrade(gun_pid, stream_ref, headers, state)

@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 PID
  • stream_ref - The stream reference for the upgrade
  • headers - The response headers received
  • state - Current connection state

Returns

  • {:noreply, updated_state} - Standard response
  • {:stop, reason, updated_state} - Stop the process

should_reconnect?(error, attempt, state)

@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 disconnection
  • attempt - The current reconnection attempt number
  • state - Current connection state

Returns

  • {true, delay} - Should reconnect after the specified delay
  • {false, _} - Should not reconnect