ChannelSocket

ChannelSocket module: WebSocket transport adapter for Channels.

ChannelSocket integrates the Channel wire protocol with March's WebSocket server. A socket endpoint is mounted in the HTTP router and handles:

WebSocket upgrade for incoming connections.
Authentication via the user-supplied connect/2 callback.
Routing incoming phx_join messages to the correct channel handler.
Forwarding ChannelPush messages from channel processes to the wire.

Usage:

fn my_router() do
  HttpServer.new(4000)
  |> HttpServer.plug(ChannelSocket.handler("/socket", my_routes, connect_fn))
  |> HttpServer.listen()
end

fn connect_fn(params, socket) do
  match verify_token(params) do
  | Ok(user) -> Ok(Channel.assign(socket, "user", user))
  | Err(_)   -> Err("unauthorized")
  end
end

Socket route list: Each ChannelRoute maps a topic pattern to a handler name string. On join, the handler name is used to look up the handler functions in the environment (see ChannelServer for the handler function protocol).

Transport loop (per client connection): The WebSocket handler runs a loop reading frames from the wire, deserialising them as ChannelMsg, and dispatching to channel processes. Outbound ChannelPush messages from channel processes are serialised and sent back over the WebSocket.

See also: channel.march, channel_server.march, websocket.march.

Types

typeSocketConfigSocketConfig(a) = SocketConfig(#

typeActiveChannelsActiveChannels = ActiveChannels(Map(String, Int))#

Functions

fnall_channelsall_channels(ac)#

Return all (topic, pid) pairs in the active channels map.

fnconfig_pathconfig_path(cfg)#

Return the path of a SocketConfig.

fnconfig_routesconfig_routes(cfg)#

Return the routes of a SocketConfig.

fnconfig_shardsconfig_shards(cfg)#

Return the shard pids of a SocketConfig.

fnderegister_channelderegister_channel(ac, topic)#

Remove a channel from the registry (after leave).

fnempty_channelsempty_channels()#

Empty active channels map.

fnfind_routefind_route(routes, topic)#

Find the first ChannelRoute whose pattern matches topic. Returns Some(route) if found, None otherwise.

fnhas_routehas_route(routes, topic)#

True when any route in routes matches topic.

fnlookup_channellookup_channel(ac, topic)#

Look up the channel process pid for a topic.

fnmake_configmake_config(path, routes, connect_fn)#

Construct a SocketConfig.

fnmake_config_with_shardsmake_config_with_shards(path, routes, connect_fn, shards)#

Construct a SocketConfig with pre-started shard pids.

fnparse_frameparse_frame(frame_text)#

Parse a WebSocket TextFrame string as a ChannelMsg. Returns Some(msg) or None on parse failure.

fnplug_forplug_for(cfg)#

Build a Conn → Conn plug function that handles WebSocket upgrade for the socket path. Mount with HttpServer.plug/2.

The plug:
  1. Checks that the request path starts with `socket_path`.
  2. Upgrades to WebSocket.
  3. In the WS handler loop: reads frames, parses them as ChannelMsgs,
     and routes them.

Usage:
  HttpServer.new(4000)
  |> HttpServer.plug(ChannelSocket.plug_for(cfg))
  |> HttpServer.listen()

fnregister_channelregister_channel(ac, topic, pid)#

fnroute_msgroute_msg(ac, msg, routes, cfg, transport_pid)#

Route a parsed ChannelMsg to the appropriate channel process or handle it as a socket-level message (phx_join, phx_leave, phx_heartbeat). Returns an updated ActiveChannels or triggers side effects. Requires actor runtime.

fnserialize_msgserialize_msg(msg)#

Serialize a ChannelMsg for sending as a WebSocket TextFrame.