GitHub

WebSockets API

    Module and Core Types

    HTTP.WebSockets — Module
    HTTP.WebSockets

    WebSocket client and server helpers layered on top of the HTTP request/response stack and Reseau transports.

    Use open for client connections and listen!, listen, or serve! for servers. Most applications will work with WebSocket values directly rather than the lower-level Conn codec state.

    source
    HTTP.WebSockets.Conn — Type
    Conn

    Low-level WebSocket codec connection state.

    This is primarily useful for advanced integrations that need direct access to frame-level state. Most client and server code should work with WebSocket instead.

    source
    HTTP.WebSockets.WebSocketError — Type
    WebSocketError

    Exception raised when a WebSocket closes or encounters a protocol/payload error.

    Inspect err.message.code and err.message.reason to distinguish normal closures from errors.

    source

    Client Operations

    HTTP.WebSockets.open — Function
    open(url; kwargs...) -> WebSocket
open(f, url; kwargs...) -> Any

    Open a client WebSocket connection to url.

    Keyword arguments cover handshake headers, redirect behavior, cookies, proxy selection, TLS verification, timeout controls, and frame limits. request_timeout applies an overall handshake deadline, while response_header_timeout and write_idle_timeout configure HTTP handshake phases. read_idle_timeout bounds both handshake response-header reads and post-upgrade inbound WebSocket inactivity. When called with a function, the socket is closed automatically with status code 1000 when f returns.

    source
    HTTP.WebSockets.send — Function
    send(ws, message) -> Int

    Send one text or binary message on ws.

    message may be an AbstractString, an AbstractVector{UInt8}, or an iterable of chunks. Iterable inputs are sent as one fragmented message and the returned value is the total payload bytes sent.

    source
    HTTP.WebSockets.receive — Function
    receive(ws) -> Union{String, Vector{UInt8}}

    Receive the next complete message from ws.

    Text messages are returned as String; binary messages are returned as Vector{UInt8}. Throws WebSocketError once the connection has closed.

    source
    HTTP.WebSockets.ping — Function
    ping(ws, data=UInt8[]) -> nothing

    Send a WebSocket ping control frame with optional payload bytes.

    source
    HTTP.WebSockets.pong — Function
    pong(ws, data=UInt8[]) -> nothing

    Send a WebSocket pong control frame with optional payload bytes.

    source

    Server Operations

    HTTP.WebSockets.Server — Type
    Server(; network="tcp", address="127.0.0.1:0", handler, tls_config=nothing, ...)

    WebSocket server handle returned by listen! and serve!.

    Hold onto the returned value so you can inspect its bound address with server_addr, wait on it with wait(server), or stop it with forceclose.

    source
    HTTP.WebSockets.listen! — Function
    listen!(handler, host="127.0.0.1", port=8080; kwargs...) -> Server

    Start a background WebSocket server and return its Server handle.

    Pass tls_config to serve wss:// traffic, subprotocols to advertise supported subprotocols, and check_origin to customize origin validation. Pass listenany=true to ignore port and bind to an OS-assigned ephemeral port; read the actual address afterwards with server_addr.

    source
    HTTP.WebSockets.listen — Function
    listen(handler, host="127.0.0.1", port=8080; kwargs...) -> Server

    Start a WebSocket server and block until it exits.

    source
    HTTP.WebSockets.upgrade — Function
    upgrade(f, stream::HTTP.Stream; kwargs...)

    Upgrade an in-flight HTTP/1.1 server stream to a WebSocket connection and run f(ws::WebSocket). This is the manual counterpart to listen!: it lets a single HTTP.listen! / HTTP.Router server mix ordinary HTTP routes with WebSocket routes by upgrading the connection from inside a stream handler.

    Guard the call with isupgrade and call upgrade before writing any response to the stream:

    HTTP.listen!("127.0.0.1", 8080) do stream
    if HTTP.WebSockets.isupgrade(stream.message)
        HTTP.WebSockets.upgrade(stream) do ws
            for msg in ws
                HTTP.WebSockets.send(ws, msg)
            end
        end
    else
        HTTP.setstatus(stream, 200)
        HTTP.startwrite(stream)
        write(stream, "ok")
    end
end

    f runs synchronously; the connection is closed when it returns. Keyword arguments mirror listen!: subprotocols, check_origin, maxframesize, and maxfragmentation. WebSocket upgrades over HTTP/2 are not supported.

    source
    HTTP.WebSockets.isupgrade — Function
    isupgrade(message) -> Bool

    Return true when message is a WebSocket upgrade. For a request this checks for a valid client upgrade handshake — use it to guard upgrade inside an HTTP.listen! stream handler. For a response it checks for a 101 Switching Protocols handshake response.

    source