GitHub

WebSockets API

    Module and Core Types

    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

    Client Operations

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

    Connect to the WebSocket server at url, a ws:// or wss:// URL, and return the WebSocket. With a function f, open calls f(ws), closes the connection with status 1000 when f returns, and returns the value of f.

    • headers, query, subprotocols: the handshake's headers, query parameters, and offered subprotocols.
    • maxframesize = 16 MiB, maxfragmentation = 1024: the largest incoming frame, and the most frames in one message.
    • compress = false: offer permessage-deflate compression (RFC 7692), used when the server accepts it.
    • connect_timeout = 30, request_timeout, response_header_timeout, read_idle_timeout, write_idle_timeout: handshake timeouts in seconds, as for HTTP.request. read_idle_timeout keeps applying after the handshake: if nothing arrives for that long, the connection closes.
    • client, proxy, redirect, redirect_limit, redirect_method, forwardheaders, cookies, cookiejar, require_ssl_verification: as for HTTP.request.
    source
    open(io::IO; target="/", host="", headers=[], subprotocols=String[],
     maxframesize=16 MiB, maxfragmentation=1024) -> WebSocket
open(f, io::IO; kwargs...)

    Do the client handshake over io, a stream that is already connected, such as a TCPSocket or a TLS stream, instead of connecting to a URL. target is the request path, and host the Host header, which is left out when empty. open never closes io; with f, it sends a close frame over io 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 WebSocket server in the background and return its Server. handler(ws::WebSocket) runs for each connection. Port 0, or listenany = true, picks a free port; server_addr returns the address.

    • tls_config: a Reseau.TLS.Config to serve wss://.
    • subprotocols: the subprotocols the server accepts.
    • check_origin: a function (request) or (request, origin) that returns true to accept a handshake. By default a handshake with an Origin header is accepted only when the origin's scheme, host, and port match the server.
    • compress = false: accept permessage-deflate compression (RFC 7692) from clients that offer it.
    • maxframesize = 16 MiB, maxfragmentation = 1024: the largest incoming frame, and the most frames in one message.

    WebSocket server tasks use Julia's :interactive thread pool. Start Julia with at least one interactive thread, such as --threads=4,1, to isolate server work from non-yielding tasks on the default pool. Without an interactive thread, Julia falls back to the default pool.

    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; subprotocols=String[], check_origin=nothing,
        maxframesize=16 MiB, maxfragmentation=1024, compress=false)

    Answer a WebSocket handshake on an HTTP/1.1 server stream and call f(ws::WebSocket). Use it in an HTTP.listen! handler to serve WebSockets and ordinary HTTP routes from one server. Check the request with isupgrade first, and call upgrade before writing 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

    upgrade returns when f does, and the connection is then closed. The keywords work as for listen!. A stream on an HTTP/2 connection throws WebSocketError.

    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