socket v0.3.9 Socket.Web

This module implements RFC 6455 WebSockets.

Client example

socket = Socket.Web.connect! "echo.websocket.org"
socket |> Socket.Web.send! { :text, "test" }
socket |> Socket.Web.recv! # => {:text, "test"}

Server example

server = Socket.Web.listen! 80
client = server |> Socket.Web.accept!

# here you can verify if you want to accept the request or not, call
# `Socket.Web.close!` if you don't want to accept it, or else call
# `Socket.Web.accept!`
client |> Socket.Web.accept!

# echo the first message
client |> Socket.Web.send!(client |> Socket.Web.recv!)

Summary

Functions

Close the underlying socket, only use when you mean it, normal closure procedure should be preferred

If you’re calling this on a listening socket, it accepts a new client connection

If you’re calling this on a listening socket, it accepts a new client connection

Extract websocket specific options from the rest

Close the socket when a close request has been received

Close the socket sending a close request, unless :wait is set to false it blocks until the close response has been received, and then closes the underlying socket. If :reason? is set to true and the response contains a closing reason and custom data the function returns it as a tuple

Connects to the given address or { address, port } tuple

Connect to the given address or { address, port } tuple with the given options or address and port

Connect to the given address, port and options

Connects to the given address or { address, port } tuple, raising if an error occurs

Connect to the given address or { address, port } tuple with the given options or address and port, raising if an error occurs

Connect to the given address, port and options, raising if an error occurs

Listens on the default port (80)

Listens on the given port or with the given options

Listens on the given port with the given options

Listens on the default port (80), raising if an error occurs

Listens on the given port or with the given options, raising if an error occurs

Listens on the given port with the given options, raising if an error occurs

Return the local address and port

Return the local address and port, raising if an error occurs

Send a ping request with the optional cookie

Send a ping request with the optional cookie, raising if an error occurs

Send a pong with the given (and received) ping cookie

Send a pong with the given (and received) ping cookie, raising if an error occurs

Receive a packet from the websocket

Receive a packet from the websocket, raising if an error occurs

Return the remote address and port

Return the remote address and port, raising if an error occurs

Send a packet to the websocket

Send a packet to the websocket, raising if an error occurs

Types

error()
packet()
packet ::
  {:text, String.t} |
  {:binary, binary} |
  {:fragmented, :text | :binary | :continuation | :end, binary} |
  :close |
  {:close, atom, binary} |
  {:ping, binary} |
  {:pong, binary}
t()
t() :: %Socket.Web{extensions: [String.t], headers: term, key: String.t, mask: boolean, origin: String.t, path: String.t, protocols: [String.t], socket: term, version: 13}

Functions

abort(web)
abort(t) :: :ok | {:error, error}

Close the underlying socket, only use when you mean it, normal closure procedure should be preferred.

accept(self, options \\ [])
accept(t, Keyword.t) :: {:ok, t} | {:error, error}

If you’re calling this on a listening socket, it accepts a new client connection.

If you’re calling this on a client socket, it finalizes the acception handshake, this separation is done because then you can verify the client can connect based on Origin header, path and other things.

accept!(socket, options \\ [])
accept!(t, Keyword.t) :: t | no_return

If you’re calling this on a listening socket, it accepts a new client connection.

If you’re calling this on a client socket, it finalizes the acception handshake, this separation is done because then you can verify the client can connect based on Origin header, path and other things.

In case of error, it raises.

arguments(options)
arguments(Keyword.t) :: {Keyword.t, Keyword.t}

Extract websocket specific options from the rest.

close(web)
close(t) :: :ok | {:error, error}

Close the socket when a close request has been received.

close(self, reason, options \\ [])
close(t, atom, Keyword.t) ::
  :ok |
  {:ok, atom, binary} |
  {:error, error}

Close the socket sending a close request, unless :wait is set to false it blocks until the close response has been received, and then closes the underlying socket. If :reason? is set to true and the response contains a closing reason and custom data the function returns it as a tuple.

connect(address)
connect({Socket.Address.t, :inet.port_number}) ::
  {:ok, t} |
  {:error, error}

Connects to the given address or { address, port } tuple.

connect(address, options)
connect({Socket.Address.t, :inet.port_number} | Socket.Address.t, Keyword.t | :inet.port_number) ::
  {:ok, t} |
  {:error, error}

Connect to the given address or { address, port } tuple with the given options or address and port.

connect(address, port, options)
connect(Socket.Address.t, :inet.port_number, Keyword.t) ::
  {:ok, t} |
  {:error, error}

Connect to the given address, port and options.

Options

:path sets the path to give the server, / by default :origin sets the Origin header, this is optional :handshake is the key used for the handshake, this is optional

You can also pass TCP or SSL options, depending if you’re using secure websockets or not.

connect!(address)
connect!({Socket.Address.t, :inet.port_number}) ::
  t |
  no_return

Connects to the given address or { address, port } tuple, raising if an error occurs.

connect!(address, options)
connect!({Socket.Address.t, :inet.port_number} | Socket.Address.t, Keyword.t | :inet.port_number) ::
  t |
  no_return

Connect to the given address or { address, port } tuple with the given options or address and port, raising if an error occurs.

connect!(address, port, options)
connect!(Socket.Address.t, :inet.port_number, Keyword.t) ::
  t |
  no_return

Connect to the given address, port and options, raising if an error occurs.

Options

:path sets the path to give the server, / by default :origin sets the Origin header, this is optional :handshake is the key used for the handshake, this is optional :headers are additional headers that will be sent

You can also pass TCP or SSL options, depending if you’re using secure websockets or not.

listen()
listen() :: {:ok, t} | {:error, error}

Listens on the default port (80).

listen(port)
listen(:inet.port_number | Keyword.t) ::
  {:ok, t} |
  {:error, error}

Listens on the given port or with the given options.

listen(port, options)
listen(:inet.port_number, Keyword.t) ::
  {:ok, t} |
  {:error, error}

Listens on the given port with the given options.

Options

:secure when true it will use SSL sockets

You can also pass TCP or SSL options, depending if you’re using secure websockets or not.

listen!()
listen!() :: t | no_return

Listens on the default port (80), raising if an error occurs.

listen!(port)
listen!(:inet.port_number | Keyword.t) :: t | no_return

Listens on the given port or with the given options, raising if an error occurs.

listen!(port, options)
listen!(:inet.port_number, Keyword.t) :: t | no_return

Listens on the given port with the given options, raising if an error occurs.

Options

:secure when true it will use SSL sockets

You can also pass TCP or SSL options, depending if you’re using secure websockets or not.

local(web)
local(t) ::
  {:ok, {:inet.ip_address, :inet.port_number}} |
  {:error, error}

Return the local address and port.

local!(web)
local!(t) :: {:inet.ip_address, :inet.port_number} | no_return

Return the local address and port, raising if an error occurs.

ping(self, cookie \\ :crypto.strong_rand_bytes(32))
ping(t, binary) :: :ok | {:error, error}

Send a ping request with the optional cookie.

ping!(self, cookie \\ :crypto.strong_rand_bytes(32))
ping!(t, binary) :: :ok | no_return

Send a ping request with the optional cookie, raising if an error occurs.

pong(self, cookie)
pong(t, binary) :: :ok | {:error, error}

Send a pong with the given (and received) ping cookie.

pong!(self, cookie)
pong!(t, binary) :: :ok | no_return

Send a pong with the given (and received) ping cookie, raising if an error occurs.

recv(self, options \\ [])
recv(t, Keyword.t) :: {:ok, packet} | {:error, error}

Receive a packet from the websocket.

recv!(self, options \\ [])
recv!(t, Keyword.t) :: packet | no_return

Receive a packet from the websocket, raising if an error occurs.

remote(web)
remote(t) ::
  {:ok, {:inet.ip_address, :inet.port_number}} |
  {:error, error}

Return the remote address and port.

remote!(web)
remote!(t) ::
  {:inet.ip_address, :inet.port_number} |
  no_return

Return the remote address and port, raising if an error occurs.

send(self, packet, options \\ [])
send(t, packet, Keyword.t) :: :ok | {:error, error}

Send a packet to the websocket.

send!(self, packet, options \\ [])
send!(t, packet, Keyword.t) :: :ok | no_return

Send a packet to the websocket, raising if an error occurs.