@spec create_handler(keyword()) :: (term() -> any())

Create a callback function for handling specific message types.

@spec decode_and_handle_control(tuple()) ::
  {:ok, {:data, {atom(), binary()}}}
  | {:ok, :control_frame_handled}
  | {:error, {:protocol_error, term()}}

Decode a WebSocket frame and handle control frames automatically. Returns decoded data frames without invoking any handler callback.

Used by the Client GenServer which has its own routing layer (route_data_frame) for JSON parsing, subscription routing, and heartbeat handling.

@spec default_handler(term()) :: :ok

Default message handler that accepts a message and discards it, returning :ok.

This is the fallback handler everywhere a handler is not supplied — except ZenWebsocket.Client.connect/2, which installs a parent-forwarding handler via ZenWebsocket.Client.CallFacade.with_default_handler/2. Any other path that falls back to this function silently drops every inbound message, so supply your own handler when you need to observe traffic.

@spec handle_control_frame(term(), pid(), reference()) :: :handled | :not_control

Handle WebSocket control frames automatically. Returns :handled for control frames, :not_control for data frames.

@spec handle_message(tuple(), (term() -> any())) ::
  {:ok, term()} | {:error, {:protocol_error, term()}}

Handle incoming Gun messages and WebSocket frames. Routes messages to appropriate handler function.