Net.HTTP.WebSocket

module Net.HTTP.WebSocket

High-level RFC 6455 client messages. The runtime handles fragmentation and ping/pong frames; reconnect and heartbeat policies remain application-owned.

A Connection delivers complete messages rather than wire frames. Your code never has to assemble fragments or answer a protocol ping, but it does decide what a dropped connection means: reconnecting may require resubscribing or replaying an application cursor, so the library cannot do that safely for you.

using Net.HTTP.WebSocket

let socket = WebSocket.connect("wss://example.test/events").try
socket.send(Text("hello")).try
let message = socket.receiveMessage.try
socket.close

type Message

A complete high-level WebSocket message. Fragmentation and ping/pong control frames are handled by the connection runtime.

CloseMessage carries the peer's status code and reason. Treat it as the end of the message stream even when the code describes a normal shutdown.

Variants

• Text(String)
• BinaryMessage(Binary)
• CloseMessage(Integer, String)

record ClientOptions

Client handshake policy and the maximum reassembled message size.

Subprotocols are offered in preference order. The byte limit applies after fragments are reassembled, preventing a peer from bypassing the bound with many individually small frames.

Fields

subprotocols

[String] optional

maximumMessageBytes

Integer optional

record Session

Negotiated handshake information. The subprotocol is None when the server selected none.

Fields

subprotocol

String?

type Connection

An opaque RFC 6455 connection, client- or server-side. It does not reconnect automatically.

send(message: Message) -> Result<Void, NetError>

connection.send(Text(JSON.stringify({ action: "subscribe", topic: topic }))).try

receiveMessage(timeout: Duration?) -> Result<Message, NetError>

loop do
  match connection.receiveMessage.try do
    Text(text)                  => handleEvent(text)
    BinaryMessage(data)         => saveSnapshot(data)
    CloseMessage(code, reason)  => break
  end
end

session : Session

let protocol = connection.session.subprotocol.or("default")

close : Void

closed? : Bool

record Handshake

Subprotocols offered by an incoming upgrade request, in the order the peer listed them.

Fields

subprotocols

[String] optional

type Upgrade

A server's decision after inspecting a Handshake.

Accept takes over the connection once the 101 response is sent: handler runs with the negotiated server Connection, and its return value is discarded. headers are added to the 101 response; a name that manages the handshake itself (Upgrade, Connection, Sec-WebSocket-Accept, Sec-WebSocket-Protocol) is dropped rather than overridden. subprotocol must be one handshake.subprotocols actually offered, or None.

Reject answers with an ordinary buffered response instead, leaving the connection as plain HTTP — a client requesting an unsupported subprotocol might get Response.text(426, "chat.v2 required"), for instance.

Variants

• Accept((Connection) -> Void, Headers, String?)
• Reject(Response<Binary>)

module Net.HTTP.WebSocket.WebSocket

Constructors for high-level WebSocket connections, client- and server-side.

connect(url: String, options: ClientOptions) -> Result<Connection, NetError>

let socket = WebSocket.connect("wss://events.example.com/orders").try
match socket.receiveMessage.try do
  Text(json) => IO.printLine(json)
  _          => IO.warn("unexpected non-text event")
end

upgrade(request: Request<Binary>, decide: (Handshake -> Upgrade)) -> Response<Binary>

foul socketRoute(request: Request<Binary>, context: Context) -> Response<Binary> = WebSocket.upgrade(request) do |handshake|
  if handshake.subprotocols.contains?("chat.v2")
    let handler : Connection -> Void = { |socket| serveChat(socket) }
    Accept(handler, Headers.empty, Just("chat.v2"))
  else
    Reject(Response.text(426, "chat.v2 required"))
  end
end
let router = Router.build.get("/socket", ~socketRoute)