@spec decode(t(), data :: binary()) ::
  {:ok, t(), [frame() | {:error, term()}]} | {:error, t(), any()}

Decodes a binary into a list of frames

The binary may received from the connection with Mint.HTTP.stream/2.

This function will invoke the Mint.WebSocket.Extension.decode/2 callback for any accepted extensions.

Examples

message = receive(do: (message -> message))
{:ok, conn, [{:data, ^ref, data}]} = Mint.HTTP.stream(conn, message)
{:ok, websocket, frames} = Mint.WebSocket.decode(websocket, data)

@spec encode(t(), shorthand_frame() | frame()) ::
  {:ok, t(), binary()} | {:error, t(), any()}

Encodes a frame into a binary

The resulting binary may be sent with stream_request_body/3.

This function will invoke the Mint.WebSocket.Extension.encode/2 callback for any accepted extensions.

Examples

{:ok, websocket, data} = Mint.WebSocket.encode(websocket, {:text, "hello world"})
{:ok, conn} = Mint.WebSocket.stream_request_body(conn, websocket_ref, data)

Creates a new WebSocket data structure given the server's reply to the upgrade request

This function will setup any extensions accepted by the server using the Mint.WebSocket.Extension.init/2 callback.

Options

• :mode - (default: :active) either :active or :passive. This corresponds to the same option in Mint.HTTP.connect/4.

Examples

http_reply = receive(do: (message -> message))
{:ok, conn, [{:status, ^ref, status}, {:headers, ^ref, headers}, {:done, ^ref}]} =
  Mint.WebSocket.stream(conn, http_reply)

{:ok, conn, websocket} =
  Mint.WebSocket.new(conn, ref, status, resp_headers)

@spec recv(Mint.HTTP.t(), non_neg_integer(), timeout()) ::
  {:ok, Mint.HTTP.t(), [Mint.Types.response()]}
  | {:error, t(), Mint.Types.error(), [Mint.Types.response()]}

Receives data from the socket

This function is used instead of stream/2 when the connection is in :passive mode. You must pass the mode: :passive option to new/5 in order to use recv/3.

This function wraps Mint.HTTP.recv/3. See the Mint.HTTP.recv/3 documentation for more information.

Examples

{:ok, conn, [{:data, ^ref, data}]} = Mint.WebSocket.recv(conn, 0, 5_000)
{:ok, websocket, [{:text, "hello world!"}]} =
  Mint.WebSocket.decode(websocket, data)

@spec stream(Mint.HTTP.t(), term()) ::
  {:ok, Mint.HTTP.t(), [Mint.Types.response()]}
  | {:error, Mint.HTTP.t(), Mint.Types.error(), [Mint.Types.response()]}
  | :unknown

A wrapper around Mint.HTTP.stream/2 for streaming HTTP and WebSocket messages

This function does not decode WebSocket frames. Instead, once a WebSocket connection has been established, decode any {:data, request_ref, data} frames with decode/2.

This function is a drop-in replacement for Mint.HTTP.stream/2 which enables streaming WebSocket data after the bootstrapping HTTP/1 connection has concluded. It decodes both WebSocket and regular HTTP messages.

Examples

message = receive(do: (message -> message))
{:ok, conn, [{:data, ^websocket_ref, data}]} =
  Mint.WebSocket.stream(conn, message)
{:ok, websocket, [{:text, "hello world!"}]} =
  Mint.WebSocket.decode(websocket, data)

@spec stream_request_body(
  Mint.HTTP.t(),
  Mint.Types.request_ref(),
  iodata() | :eof | {:eof, trailing_headers :: Mint.Types.headers()}
) :: {:ok, Mint.HTTP.t()} | {:error, Mint.HTTP.t(), error()}

Streams chunks of data on the connection

stream_request_body/3 should be used to send encoded data on an established WebSocket connection that has already been upgraded with upgrade/5.

This function is a wrapper around Mint.HTTP.stream_request_body/3. It delegates to that function unless the request_ref belongs to an HTTP/1 WebSocket connection. When the request is an HTTP/1 WebSocket, this function allows sending data on a request which Mint considers to be closed, but is actually a valid WebSocket connection.

See the Mint.HTTP.stream_request_body/3 documentation for more information.

Examples

{:ok, websocket, data} = Mint.WebSocket.encode(websocket, {:text, "hello world!"})
{:ok, conn} = Mint.WebSocket.stream_request_body(conn, websocket_ref, data)

@spec upgrade(
  scheme :: :ws | :wss,
  conn :: Mint.HTTP.t(),
  path :: String.t(),
  headers :: Mint.Types.headers(),
  opts :: Keyword.t()
) ::
  {:ok, Mint.HTTP.t(), Mint.Types.request_ref()}
  | {:error, Mint.HTTP.t(), error()}

Requests that a connection be upgraded to the WebSocket protocol

This function wraps Mint.HTTP.request/5 to provide a single interface for bootstrapping an upgrade for HTTP/1 and HTTP/2 connections.

For HTTP/1 connections, this function performs a GET request with WebSocket-specific headers. For HTTP/2 connections, this function performs an extended CONNECT request which opens a stream to be used for the WebSocket connection.

The scheme argument should be either :ws or :wss, using :ws for connections established by passing :http to Mint.HTTP.connect/4 and :wss corresponding to :https.

Options

• :extensions - a list of extensions to negotiate. See the extensions section below.

Extensions

Extensions should be declared by passing the :extensions option in the opts keyword list. Note that in the WebSocket protocol, extensions are negotiated: the client proposes a list of extensions and the server may accept any (or none) of them. See Mint.WebSocket.Extension for more information about extension negotiation.

Extensions may be passed as a list of Mint.WebSocket.Extension structs or with the following shorthand notations:

• module - shorthand for {module, []}
• {module, params} - shorthand for {module, params, []}
• {module, params, opts} - a shorthand which is expanded to a Mint.WebSocket.Extension struct

Examples

{:ok, conn} = Mint.HTTP.connect(:http, "localhost", 9_000)
{:ok, conn, ref} =
  Mint.WebSocket.upgrade(:ws, conn, "/", [], extensions: [Mint.WebSocket.PerMessageDeflate])
# or provide params:
{:ok, conn, ref} =
  Mint.WebSocket.upgrade(
    :ws,
    conn,
    "/",
    [],
    extensions: [{Mint.WebSocket.PerMessageDeflate, [:client_max_window_bits]]}]
  )