Outlines the Socket <-> Transport communication.

This module specifies a behaviour that all sockets must implement. Phoenix.Socket is just one possible implementation of a socket that multiplexes events over multiple channels. Developers can implement their own sockets as long as they implement the behaviour outlined here.

Developers interested in implementing custom transports must invoke the socket API defined in this module. This module also provides many conveniences that invokes the underlying socket API to make it easier to build custom transports.

booting-sockets

Booting sockets

Whenever your endpoint starts, it will automatically invoke the child_spec/1 on each listed socket and start that specification under the endpoint supervisor.

Since the socket supervision tree is started by the endpoint, any custom transport must be started after the endpoint in a supervision tree.

operating-sockets

Operating sockets

Sockets are operated by a transport. When a transport is defined, it usually receives a socket module and the module will be invoked when certain events happen at the transport level.

Whenever the transport receives a new connection, it should invoke the connect/1 callback with a map of metadata. Different sockets may require different metadatas.

If the connection is accepted, the transport can move the connection to another process, if so desires, or keep using the same process. The process responsible for managing the socket should then call init/1.

For each message received from the client, the transport must call handle_in/2 on the socket. For each informational message the transport receives, it should call handle_info/2 on the socket.

Transports can optionally implement handle_control/2 for handling control frames such as :ping and :pong.

On termination, terminate/2 must be called. A special atom with reason :closed can be used to specify that the client terminated the connection.

example

Example

Here is a simple echo socket implementation:

defmodule EchoSocket do
  @behaviour Phoenix.Socket.Transport

  def child_spec(opts) do
    # We won't spawn any process, so let's return a dummy task
    %{id: __MODULE__, start: {Task, :start_link, [fn -> :ok end]}, restart: :transient}
  end

  def connect(state) do
    # Callback to retrieve relevant data from the connection.
    # The map contains options, params, transport and endpoint keys.
    {:ok, state}
  end

  def init(state) do
    # Now we are effectively inside the process that maintains the socket.
    {:ok, state}
  end

  def handle_in({text, _opts}, state) do
    {:reply, :ok, {:text, text}, state}
  end

  def handle_info(_, state) do
    {:ok, state}
  end

  def terminate(_reason, _state) do
    :ok
  end
end

It can be mounted in your endpoint like any other socket:

socket "/socket", EchoSocket, websocket: true, longpoll: true

You can now interact with the socket under /socket/websocket and /socket/longpoll.

security

Security

This module also provides functions to enable a secure environment on transports that, at some point, have access to a Plug.Conn.

The functionality provided by this module helps in performing "origin" header checks and ensuring only SSL connections are allowed.