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

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.

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.

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.

fnempty_channelsempty_channels()#

Empty active channels map.

fnregister_channelregister_channel(ac, topic, pid)#

fnlookup_channellookup_channel(ac, topic)#

Look up the channel process pid for a topic.

fnderegister_channelderegister_channel(ac, topic)#

Remove a channel from the registry (after leave).

fnall_channelsall_channels(ac)#

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

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.

fnparse_frameparse_frame(frame_text)#

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

fnserialize_msgserialize_msg(msg)#

Serialize a ChannelMsg for sending as a WebSocket TextFrame.

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:

Checks that the request path starts with socket_path.
Upgrades to WebSocket.
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()