GSMLG.Socket v0.1.0

GSMLG.Socket.Web (GSMLG.Socket v0.1.0)

This module implements RFC 6455 WebGSMLG.Sockets.

client-example

 Client example 

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

server-example

 Server example 

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

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

# echo the first message
client |> GSMLG.Socket.Web.send!(client |> GSMLG.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

error()

@type error() :: GSMLG.Socket.TCP.error() | GSMLG.Socket.SSL.error()
Link to this type

packet()

@type 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()

@type t() :: %GSMLG.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)

@spec 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 \\ [])

@spec 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 \\ [])

@spec 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)

@spec arguments(Keyword.t()) :: {Keyword.t(), Keyword.t()}

Extract websocket specific options from the rest.

Link to this function

close(web)

@spec close(t()) :: :ok | {:error, error()}

Close the socket when a close request has been received.

Link to this function

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

@spec 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)

@spec connect({GSMLG.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)

@spec connect(
  {GSMLG.Socket.Address.t(), :inet.port_number()} | GSMLG.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)

@spec connect(GSMLG.Socket.Address.t(), :inet.port_number(), Keyword.t()) ::
  {:ok, t()} | {:error, error()}

Connect to the given address, port and options.

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)

@spec connect!({GSMLG.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)

@spec connect!(
  {GSMLG.Socket.Address.t(), :inet.port_number()} | GSMLG.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)

@spec connect!(GSMLG.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

 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()

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

Listens on the default port (80).

Link to this function

listen(port)

@spec 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)

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

Listens on the given port with the given options.

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!()

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

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

Link to this function

listen!(port)

@spec 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)

@spec listen!(:inet.port_number(), Keyword.t()) :: t() | no_return()

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

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

local(web)

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

Return the local address and port.

Link to this function

local!(web)

@spec 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))

@spec 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))

@spec 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)

@spec pong(t(), binary()) :: :ok | {:error, error()}

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

Link to this function

pong!(self, cookie)

@spec 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 \\ [])

@spec recv(t(), Keyword.t()) :: {:ok, packet()} | {:error, error()}

Receive a packet from the websocket.

Link to this function

recv!(self, options \\ [])

@spec recv!(t(), Keyword.t()) :: packet() | no_return()

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

Link to this function

remote(web)

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

Return the remote address and port.

Link to this function

remote!(web)

@spec 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 \\ [])

@spec send(t(), packet(), Keyword.t()) :: :ok | {:error, error()}

Send a packet to the websocket.

Link to this function

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

@spec send!(t(), packet(), Keyword.t()) :: :ok | no_return()

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