socket

v0.3.13

socket v0.3.13 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!)

Link to this section Summary

Types

error()
packet()
t()

Functions

abort(web)

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

accept(self, options \\ [])

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

accept!(socket, options \\ [])

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

arguments(options)

Extract websocket specific options from the rest

close(web)

Close the socket when a close request has been received

close(self, reason, options \\ [])

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)

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

connect(address, options)

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

connect(address, port, options)

Connect to the given address, port and options

connect!(address)

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

connect!(address, options)

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 to the given address, port and options, raising if an error occurs

listen()

Listens on the default port (80)

listen(port)

Listens on the given port or with the given options

listen(port, options)

Listens on the given port with the given options

listen!()

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

listen!(port)

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

listen!(port, options)

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

local(web)

Return the local address and port

local!(web)

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

ping(self, cookie \\ :crypto.strong_rand_bytes(32))

Send a ping request with the optional cookie

ping!(self, cookie \\ :crypto.strong_rand_bytes(32))

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

pong(self, cookie)

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

pong!(self, cookie)

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

recv(self, options \\ [])

Receive a packet from the websocket

recv!(self, options \\ [])

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

remote(web)

Return the remote address and port

remote!(web)

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

send(self, packet, options \\ [])

Send a packet to the websocket

send!(self, packet, options \\ [])

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

Link to this section Types

Link to this type packet() 
packet() ::
  {:text, String.t()}
  | {:binary, binary()}
  | {:fragmented, :text | :binary | :continuation | :end, binary()}
  | :close
  | {:close, atom(), binary()}
  | {:ping, binary()}
  | {:pong, binary()}
Link to this type 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
}

Link to this section Functions

Link to this function abort(web) 
abort(t()) :: :ok | {:error, error()}

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

Link to this function 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.

Link to this function 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.

Link to this function arguments(options) 
arguments(Keyword.t()) :: {Keyword.t(), Keyword.t()}

Extract websocket specific options from the rest.

Link to this function close(web) 
close(t()) :: :ok | {:error, error()}

Close the socket when a close request has been received.

Link to this function 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.

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

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

Link to this function 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.

Link to this function 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.

Link to this function 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.

Link to this function 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.

Link to this function 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.

Link to this function listen() 
listen() :: {:ok, t()} | {:error, error()}

Listens on the default port (80).

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

Listens on the given port or with the given options.

Link to this function 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.

Link to this function listen!() 
listen!() :: t() | no_return()

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

Link to this function 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.

Link to this function 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.

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

Return the local address and port.

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

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

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

Send a ping request with the optional cookie.

Link to this function 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.

Link to this function pong(self, cookie) 
pong(t(), binary()) :: :ok | {:error, error()}

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

Link to this function pong!(self, cookie) 
pong!(t(), binary()) :: :ok | no_return()

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

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

Receive a packet from the websocket.

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

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

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

Return the remote address and port.

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

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

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

Send a packet to the websocket.

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

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