@callback child_spec(keyword()) :: :supervisor.child_spec()

Returns a child specification for socket management.

This is invoked only once per socket regardless of the number of transports and should be responsible for setting up any process structure used exclusively by the socket regardless of transports.

Each socket connection is started by the transport and the process that controls the socket likely belongs to the transport. However, some sockets spawn new processes, such as Phoenix.Socket which spawns channels, and this gives the ability to start a supervision tree associated to the socket.

It receives the socket options from the endpoint, for example:

socket "/my_app", MyApp.Socket, shutdown: 5000

means child_spec([shutdown: 5000]) will be invoked.

@callback connect(transport_info :: map()) :: {:ok, state()} | :error

Connects to the socket.

The transport passes a map of metadata and the socket returns {:ok, state} or :error. The state must be stored by the transport and returned in all future operations.

This function is used for authorization purposes and it may be invoked outside of the process that effectively runs the socket.

In the default Phoenix.Socket implementation, the metadata expects the following keys:

• :endpoint - the application endpoint
• :transport - the transport name
• :params - the connection parameters
• :options - a keyword list of transport options, often given by developers when configuring the transport. It must include a :serializer field with the list of serializers and their requirements

@callback handle_control(
  {message :: term(), opts :: keyword()},
  state()
) ::
  {:ok, state()}
  | {:reply, :ok | :error, {opcode :: atom(), message :: term()}, state()}
  | {:stop, reason :: term(), state()}

Handles incoming control frames.

The message is represented as {payload, options}. It must return one of:

• {:ok, state} - continues the socket with no reply
• {:reply, status, reply, state} - continues the socket with reply
• {:stop, reason, state} - stops the socket

Control frames only supported when using websockets.

The options contains an opcode key, this will be either :ping or :pong.

If a control frame doesn't have a payload, then the payload value will be nil.

@callback handle_in(
  {message :: term(), opts :: keyword()},
  state()
) ::
  {:ok, state()}
  | {:reply, :ok | :error, {opcode :: atom(), message :: term()}, state()}
  | {:stop, reason :: term(), state()}

Handles incoming socket messages.

The message is represented as {payload, options}. It must return one of:

• {:ok, state} - continues the socket with no reply
• {:reply, status, reply, state} - continues the socket with reply
• {:stop, reason, state} - stops the socket

The reply is a tuple contain an opcode atom and a message that can be any term. The built-in websocket transport supports both :text and :binary opcode and the message must be always iodata. Long polling only supports text opcode.

@callback handle_info(message :: term(), state()) ::
  {:ok, state()}
  | {:push, {opcode :: atom(), message :: term()}, state()}
  | {:stop, reason :: term(), state()}

Handles info messages.

The message is a term. It must return one of:

• {:ok, state} - continues the socket with no reply
• {:push, reply, state} - continues the socket with reply
• {:stop, reason, state} - stops the socket

The reply is a tuple contain an opcode atom and a message that can be any term. The built-in websocket transport supports both :text and :binary opcode and the message must be always iodata. Long polling only supports text opcode.

@callback init(state()) :: {:ok, state()}

Initializes the socket state.

This must be executed from the process that will effectively operate the socket.

@callback terminate(reason :: term(), state()) :: :ok

Invoked on termination.

If reason is :closed, it means the client closed the socket. This is considered a :normal exit signal, so linked process will not automatically exit. See Process.exit/2 for more details on exit signals.