WebsockexNova.Transport behaviour (WebsockexNova v0.1.1)

View Source

Behaviour for pluggable WebSocket transport layers in WebsockexNova.

This abstraction allows the connection process to interact with any transport (e.g., Gun, test mocks) via a consistent, testable interface.

Callbacks

  • send_frame/3 — Send a WebSocket frame on a given stream
  • upgrade_to_websocket/3 — Upgrade an HTTP connection to WebSocket
  • close/1 — Close the transport connection
  • process_transport_message/2 — (Optional) Process a transport-specific message (e.g., Gun event)
  • get_state/1 — (Optional) Retrieve the current transport state (for testability)
  • open/4 — Open a new transport connection
  • schedule_reconnection/2 — (Optional) Schedule a reconnection attempt after a disconnect
  • start_connection/1 — (Optional) Start a new connection or reconnection attempt for the transport

Summary

Types

WebSocket frame type

Opaque transport state (implementation-defined)

Stream reference (opaque)

Callbacks

Close the transport connection. Returns :ok.

(Optional) Retrieve the current transport state (for testability).

Open a new transport connection. Returns {:ok, state} or {:error, reason}.

(Optional) Process a transport-specific message (e.g., Gun event). Returns updated state or other result as needed.

(Optional) Schedule a reconnection attempt after a disconnect. Returns the updated transport state.

Send a WebSocket frame on the given stream. Returns :ok or {:error, reason}.

(Optional) Start a new connection or reconnection attempt for the transport. Returns the updated transport state.

Upgrade the connection to WebSocket on the given path and headers. Returns {:ok, stream_ref} or {:error, reason}.

Types

frame()

@type frame() ::
  {:text, binary()}
  | {:binary, binary()}
  | :ping
  | :pong
  | :close
  | {:close, non_neg_integer(), binary()}

WebSocket frame type

state()

@type state() :: any()

Opaque transport state (implementation-defined)

stream_ref()

@type stream_ref() :: reference() | any()

Stream reference (opaque)

Callbacks

close(state)

@callback close(state()) :: :ok

Close the transport connection. Returns :ok.

get_state(state)

@callback get_state(state()) :: any()

(Optional) Retrieve the current transport state (for testability).

open(host, port, path, options)

@callback open(
  host :: binary(),
  port :: pos_integer(),
  path :: binary(),
  options :: map() | keyword()
) ::
  {:ok, state()} | {:error, term()}

Open a new transport connection. Returns {:ok, state} or {:error, reason}.

Parameters

  • host - Hostname or IP address to connect to
  • port - Port number
  • path - WebSocket endpoint path
  • options - Transport-specific options (map or keyword)

process_transport_message(state, message)

@callback process_transport_message(state(), message :: term()) :: any()

(Optional) Process a transport-specific message (e.g., Gun event). Returns updated state or other result as needed.

schedule_reconnection(state, function)

@callback schedule_reconnection(state(), (non_neg_integer(), non_neg_integer() -> any())) ::
  state()

(Optional) Schedule a reconnection attempt after a disconnect. Returns the updated transport state.

send_frame(state, stream_ref, arg3)

@callback send_frame(state(), stream_ref(), frame() | [frame()]) :: :ok | {:error, term()}

Send a WebSocket frame on the given stream. Returns :ok or {:error, reason}.

start_connection(state)

@callback start_connection(state()) :: state()

(Optional) Start a new connection or reconnection attempt for the transport. Returns the updated transport state.

upgrade_to_websocket(state, path, headers)

@callback upgrade_to_websocket(state(), path :: binary(), headers :: Keyword.t()) ::
  {:ok, stream_ref()} | {:error, term()}

Upgrade the connection to WebSocket on the given path and headers. Returns {:ok, stream_ref} or {:error, reason}.