View Source WebSockex.Conn (WebSockex v0.5.0)

Handles establishing and controlling the TCP connection.

Dispatches to the correct module for the underlying connection. (:gen_tcp or :ssl)

Is woefully inadequite for verifying proper peers in SSL connections.

Summary

Types

Options used when establishing a tcp or ssl connection.

t()

Functions

Builds the request to be sent along the newly opened socket.

Closes the socket and returns the Conn map without the socket.

Set the socket's controlling process.

Waits for the request response, decodes the packet, and returns the response headers.

Returns a new WebSockex.Conn struct from a uri and options.

Opens a socket to a uri and returns a conn struct.

Parses a URI host Host can be "x.y.z.t" or "some.name.domain". If "x.y.z.t", the function will return a valid :inet.ipaddress() which _MODULE.open_socket accepts. This will prevent extra DNS operations which can time out in some contexts

Parses a url string for a valid URI

Sets the socket to active.

Sends data using the conn_mod module.

Types

certification()

@type certification() :: :public_key.der_encoded()

connection_option()

@type connection_option() ::
  {:extra_headers, [header()]}
  | {:cacerts, [certification()]}
  | {:insecure, boolean()}
  | {:socket_connect_timeout, non_neg_integer()}
  | {:socket_recv_timeout, non_neg_integer()}
  | {:ssl_options, [:ssl.tls_client_option()]}
  | {:socket_options, [:gen_tcp.option()]}

Options used when establishing a tcp or ssl connection.

  • :extra_headers - defines other headers to be send in the opening request.
  • :insecure - Determines whether to verify the peer in a SSL connection. SSL peer verification is currenctly broken and only works in certain cases in which the :cacerts are also provided. Sorry. Defaults to true.
  • :cacerts - The CA certifications for use in an secure connection when the :insecure option is false (has no effect when :insecure is true). These certifications need a list of decoded binaries. See the Erlang :public_key module for more information.
  • :socket_connect_timeout - Timeout in ms for creating a TCP connection, default 6000 ms.
  • :socket_recv_timeout - Timeout in ms for receiving a HTTP response header from socket, default 5000 ms.
  • :ssl_options - extra options for an SSL connection
  • :socket_options - extra options for the TCP part of the connection

header()

@type header() :: {field :: String.t(), value :: String.t()}

socket()

@type socket() :: :gen_tcp.socket() | :ssl.sslsocket()

t()

@type t() :: %WebSockex.Conn{
  cacerts: term(),
  conn_mod: :gen_tcp | :ssl,
  extra_headers: [header()],
  host: String.t(),
  insecure: term(),
  path: String.t(),
  port: non_neg_integer(),
  query: String.t() | nil,
  resp_headers: [header()],
  socket: socket() | nil,
  socket_connect_timeout: non_neg_integer(),
  socket_options: term(),
  socket_recv_timeout: non_neg_integer(),
  ssl_options: term(),
  transport: transport()
}

transport()

@type transport() :: :tcp | :ssl

Functions

build_request(conn, key)

@spec build_request(t(), key :: String.t()) :: {:ok, String.t()}

Builds the request to be sent along the newly opened socket.

The key parameter is part of the websocket handshake process.

close_socket(conn)

@spec close_socket(t()) :: %WebSockex.Conn{
  cacerts: term(),
  conn_mod: term(),
  extra_headers: term(),
  host: term(),
  insecure: term(),
  path: term(),
  port: term(),
  query: term(),
  resp_headers: term(),
  socket: nil,
  socket_connect_timeout: term(),
  socket_options: term(),
  socket_recv_timeout: term(),
  ssl_options: term(),
  transport: term()
}

Closes the socket and returns the Conn map without the socket.

When the :socket field is nil in the struct, the function just returns the struct as is.

controlling_process(conn, new_owner)

@spec controlling_process(t(), new_owner :: pid()) :: :ok | {:error, term()}

Set the socket's controlling process.

handle_response(conn, owner_pid)

@spec handle_response(t(), pid()) :: {:ok, [header()]} | {:error, reason :: term()}

Waits for the request response, decodes the packet, and returns the response headers.

Sends any access information in the buffer back to the process as a message to be processed.

new(url, opts \\ [])

@spec new(url :: String.t() | URI.t(), [connection_option()]) ::
  t() | {:error, %WebSockex.URLError{__exception__: true, url: term()}}

Returns a new WebSockex.Conn struct from a uri and options.

open_socket(conn)

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

Opens a socket to a uri and returns a conn struct.

parse_host(host)

@spec parse_host(String.t()) :: charlist() | :inet.ip_address()

Parses a URI host Host can be "x.y.z.t" or "some.name.domain". If "x.y.z.t", the function will return a valid :inet.ipaddress() which _MODULE.open_socket accepts. This will prevent extra DNS operations which can time out in some contexts

parse_url(url)

@spec parse_url(String.t()) ::
  {:ok, URI.t()}
  | {:error, %WebSockex.URLError{__exception__: true, url: term()}}

Parses a url string for a valid URI

set_active(conn, val \\ true)

@spec set_active(t(), true | false) :: :ok | {:error, reason :: term()}

Sets the socket to active.

socket_send(conn, message)

@spec socket_send(t(), binary()) :: :ok | {:error, reason :: term()}

Sends data using the conn_mod module.