hackney_ws (hackney v2.0.0)

View Source

gen_statem process for WebSocket connections.

This module implements a state machine for WebSocket connections, handling HTTP upgrade handshake and WebSocket frame exchange.

States: - idle: Process started, not connected - upgrading: HTTP upgrade in progress - connected: WebSocket ready for messages - closing: Close handshake in progress - closed: Connection terminated

Summary

Types

ws_frame/0

Functions

close(Pid)

Close the WebSocket connection gracefully.

close(Pid, _)
closed(_, OldState, Data)
closing(_, OldState, Data)
connect(Pid)

Initiate WebSocket connection. Blocks until upgrade completes.

connect(Pid, Timeout)
connected(_, OldState, Ws_data)
controlling_process(Pid, NewOwner)

Assign a new controlling process.

idle(_, OldState, Data)
peername(Pid)

Return the address and port for the other end of connection.

recv(Pid)

Receive a WebSocket frame (passive mode only).

recv(Pid, Timeout)
send(Pid, Frame)

Send a WebSocket frame. Frame types: {text, Data}, {binary, Data}, ping, {ping, Data}, pong, {pong, Data}, close, {close, Code, Reason}

setopts(Pid, Opts)

Set socket options. Supported: [{active, true|false|once}]

sockname(Pid)

Get the local address and port of the socket.

start_link(Opts)

Start a WebSocket connection process. Options

upgrading(_, OldState, Data)

Types

ws_frame/0

-type ws_frame() ::
          {text, binary()} |
          {binary, binary()} |
          ping |
          {ping, binary()} |
          pong |
          {pong, binary()} |
          close |
          {close, integer(), binary()}.

Functions

close(Pid)

-spec close(pid()) -> ok.

Close the WebSocket connection gracefully.

close(Pid, _)

-spec close(pid(), {integer(), binary()}) -> ok.

closed(_, OldState, Data)

closing(_, OldState, Data)

connect(Pid)

-spec connect(pid()) -> ok | {error, term()}.

Initiate WebSocket connection. Blocks until upgrade completes.

connect(Pid, Timeout)

-spec connect(pid(), timeout()) -> ok | {error, term()}.

connected(_, OldState, Ws_data)

controlling_process(Pid, NewOwner)

-spec controlling_process(pid(), pid()) -> ok | {error, term()}.

Assign a new controlling process.

idle(_, OldState, Data)

peername(Pid)

-spec peername(pid()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, term()}.

Return the address and port for the other end of connection.

recv(Pid)

-spec recv(pid()) -> {ok, ws_frame()} | {error, term()}.

Receive a WebSocket frame (passive mode only).

recv(Pid, Timeout)

-spec recv(pid(), timeout()) -> {ok, ws_frame()} | {error, term()}.

send(Pid, Frame)

-spec send(pid(), ws_frame()) -> ok | {error, term()}.

Send a WebSocket frame. Frame types: {text, Data}, {binary, Data}, ping, {ping, Data}, pong, {pong, Data}, close, {close, Code, Reason}

setopts(Pid, Opts)

-spec setopts(pid(), list()) -> ok | {error, term()}.

Set socket options. Supported: [{active, true|false|once}]

sockname(Pid)

-spec sockname(pid()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, term()}.

Get the local address and port of the socket.

start_link(Opts)

-spec start_link(map()) -> {ok, pid()} | {error, term()}.

Start a WebSocket connection process. Options:

  • host: Target host (string or binary)
  • port: Target port (integer)
  • transport: hackney_tcp or hackney_ssl
  • path: WebSocket path (binary, default "/")
  • connect_timeout: Connection timeout (default 8000ms)
  • recv_timeout: Receive timeout (default infinity)
  • connect_options: Options passed to transport connect
  • ssl_options: Additional SSL options
  • active: false | true | once (default false)
  • headers: Extra headers for upgrade request
  • protocols: Sec-WebSocket-Protocol values

upgrading(_, OldState, Data)