Slipstream.Configuration (Slipstream v0.6.2) View Source

Configuration for a Slipstream websocket connection

Slipstream server process configuration is passed in with Slipstream.connect/2 (or Slipstream.connect!/2), and so all configuration is evauated and validated at runtime, as opposed to compile-time validation. You should not expect to see validation errors on configuration unless you force the validation at compile-time, e.g.:

# you probably don't want to do this...
defmodule MyClient do
  @config Application.compile_env!(:my_app, __MODULE__)

  use Slipstream

  def start_link(args) do
    Slipstream.start_link(__MODULE__, args, name: __MODULE__)
  end

  def init(_args), do: {:ok, connect!(@config)}

  ..
end

This approach will validate the configuration at compile-time, but you will be unable to change the configuration after compilation, so any secrets contained in the configuration (e.g. a basic-auth request header) will be compiled into the beam files.

See the docs for Slipstream.init/1 for a safer approach.

Options

  • :uri - Required. The endpoint to which the websocket will connect. Schemes of "ws" and "wss" are supported, and a scheme must be provided. Either binaries or URI structs are accepted. E.g. "ws://localhost:4000/socket/websocket".

  • :heartbeat_interval_msec - The time between heartbeat messages. A value of 0 will disable automatic heartbeat sending. Note that a Phoenix.Channel will close out a connection after 60 seconds of inactivity (60_000). The default value is 30000.

  • :headers - A set of headers to merge with the request headers when GETing the websocket URI. Headers must be provided as two-tuples where both elements are binaries. Casing of these headers is inconsequential. The default value is [].

  • :json_parser - A JSON parser module which exports at least encode/1 and decode/2. The default value is Jason.

  • :reconnect_after_msec - A list of times to reference for trying reconnection when Slipstreamm.reconnect/0 is used to request reconnection. The msec time will be fetched based on its position in the list with Enum.at(reconnect_after_msec, try_number). If the number of tries exceeds the length of the list, the final value will be repeated. The default value is [10, 50, 100, 150, 200, 250, 500, 1000, 2000, 5000].

  • :rejoin_after_msec - A list of times to reference for trying to rejoin a topic when Slipstreamm.rejoin/0 is used. The msec time will be fetched based on its position in the list with Enum.at(rejoin_after_msec, try_number). If the number of tries exceeds the length of the list, the final value will be repeated. The default value is [100, 500, 1000, 2000, 5000, 10000].

  • :gun_open_options - A map of options to pass to :gun.open/3. See the :gun documentation for more information. Note that :gun does not support websocket over HTTP2 and that :gun naively prefers HTTP2 when connecting over TLS. The :protocols => [:http] option will be merged in by default to allow "wss" connections out of the box. The default value is %{protocols: [:http]}.

  • :test_mode? - Whether or not to start-up the client in test-mode. See Slipstream.SocketTest for notes on testing Slipstream clients. The default value is false.

Note that a Phoenix.Channel defined with

socket "/socket", UserSocket, ..

Can be connected to at /socket/websocket.

Link to this section Summary

Functions

Validates a proposed configuration

Validates a proposed configuration, raising on error

Link to this section Types

Specs

t() :: %Slipstream.Configuration{
  gun_open_options: term(),
  headers: [{String.t(), String.t()}],
  heartbeat_interval_msec: non_neg_integer(),
  json_parser: module(),
  reconnect_after_msec: [non_neg_integer()],
  rejoin_after_msec: [non_neg_integer()],
  test_mode?: term(),
  uri: %URI{
    authority: term(),
    fragment: term(),
    host: term(),
    path: term(),
    port: term(),
    query: term(),
    scheme: term(),
    userinfo: term()
  }
}

Link to this section Functions

Link to this function

validate(opts)

View Source (since 0.1.0)

Specs

validate(Keyword.t()) ::
  {:ok, t()}
  | {:error,
     %NimbleOptions.ValidationError{
       __exception__: term(),
       key: term(),
       keys_path: term(),
       message: term(),
       value: term()
     }}

Validates a proposed configuration

Specs

validate!(Keyword.t()) :: t()

Validates a proposed configuration, raising on error