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, handshake timeout controls, and frame limits. request_timeout applies an overall handshake deadline, while response_header_timeout, read_idle_timeout, and write_idle_timeout configure the underlying HTTP handshake phases. 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