dream/servers/mist/websocket

WebSocket support for Dream (Mist server adapter)

This module provides Dream’s WebSocket abstraction for the Mist server adapter. It upgrades an HTTP request to a WebSocket connection and runs a typed message loop driven by your handler functions.

Most applications will import this module as:

import dream/servers/mist/websocket

Concepts

• Connection – opaque handle to the WebSocket. Use it to send messages back to the client.
• Message(custom) – messages received from the client or from your application via a Selector(custom) (text, binary, custom, closed).
• Action(state, custom) – the next step in the WebSocket state machine, returned from your on_message handler.

The typical lifecycle is:

1. Router sends a request to a controller.
2. Controller calls upgrade_websocket.
3. on_init runs once when the WebSocket is established.
4. on_message runs for each incoming or custom message.
5. on_close runs after the connection closes.

Handlers follow Dream’s “no closures” rule: instead of capturing dependencies, you define a Dependencies type and pass it explicitly into upgrade_websocket so every handler receives what it needs.

Example (echo chat)

import dream/http/request.{type Request}
import dream/http/response.{type Response, text_response}
import dream/http/status
import dream/servers/mist/websocket
import gleam/erlang/process
import gleam/option

pub type Dependencies {
  Dependencies(user_name: String)
}

pub fn handle_upgrade(request: Request, context, services) -> Response {
  let user = request.get_query_param(request.query, "user")
  let user = option.unwrap(user, "Anonymous")
  let deps = Dependencies(user_name: user)

  websocket.upgrade_websocket(
    request,
    dependencies: deps,
    on_init: handle_init,
    on_message: handle_message,
    on_close: handle_close,
  )
}

fn handle_init(
  _connection: websocket.Connection,
  _deps: Dependencies,
) -> #(String, option.Option(process.Selector(String))) {
  // Initial state is the username, no extra messages yet
  #("", option.None)
}

fn handle_message(
  state: String,
  message: websocket.Message(String),
  connection: websocket.Connection,
  deps: Dependencies,
) -> websocket.Action(String, String) {
  case message {
    websocket.TextMessage(text) -> {
      let reply = deps.user_name <> ": " <> text
      let _ = websocket.send_text(connection, reply)
      websocket.continue_connection(state)
    }
    websocket.ConnectionClosed -> websocket.stop_connection()
    _ -> websocket.continue_connection(state)
  }
}

fn handle_close(_state: String, _deps: Dependencies) -> Nil {
  Nil
}

pub opaque type Action(state, custom)

pub opaque type Connection

pub type Message(custom) {
  TextMessage(String)
  BinaryMessage(BitArray)
  CustomMessage(custom)
  ConnectionClosed
}

pub type SendError {
  SocketClosed
  Timeout
  UnknownError
}

pub fn continue_connection(state: state) -> Action(state, custom)

pub fn continue_connection_with_selector(
  state: state,
  selector: process.Selector(custom),
) -> Action(state, custom)

pub fn send_binary(
  connection: Connection,
  message: BitArray,
) -> Result(Nil, SendError)

case websocket.send_binary(connection, data) {
  Ok(Nil) -> // Message sent successfully
  Error(reason) -> // Handle send error
}

pub fn send_text(
  connection: Connection,
  message: String,
) -> Result(Nil, SendError)

case websocket.send_text(connection, "Hello!") {
  Ok(Nil) -> // Message sent successfully
  Error(reason) -> // Handle send error
}

pub fn stop_connection() -> Action(state, custom)

pub fn upgrade_websocket(
  request request: request.Request,
  dependencies dependencies: deps,
  on_init on_init: fn(Connection, deps) -> #(
    state,
    option.Option(process.Selector(custom)),
  ),
  on_message on_message: fn(
    state,
    Message(custom),
    Connection,
    deps,
  ) -> Action(state, custom),
  on_close on_close: fn(state, deps) -> Nil,
) -> response.Response

websocket.upgrade_websocket(
  request,
  dependencies: services,
  on_init: init_handler,
  on_message: message_handler,
  on_close: close_handler,
)

fn init_handler(connection, services) {
  #(initial_state, None)
}

fn message_handler(state, message, connection, services) {
  case message {
    websocket.TextMessage(text) -> {
      // Handle text message
      websocket.continue_connection(state)
    }
    websocket.CustomMessage(msg) -> {
      // Handle custom message from selector
      websocket.continue_connection(state)
    }
    websocket.ConnectionClosed -> websocket.stop_connection()
    _ -> websocket.continue_connection(state)
  }
}

fn close_handler(state, services) {
  Nil
}