abstract classafWebSockets::WebSocket

sys::Obj
  afWebSockets::WebSocket

@Js

The main WebSocket class as defined by the W3C WebSocket API.

Sample client usage:

webSock := WebSocket()
webSock.onMessage |MsgEvent e| { ... }
webSock.open(`ws:localhost:8069`)
webSock.read

Sample BedSheet server usage:

WebSocket serviceWs() { 
    webSock := WebSocket()
    webSock.onMessage |MsgEvent e| { ... }
    return webSock
}

Note that all returned WebSocket instances are available from the WebSockets service for future use.

Sample WebMod server usage.

Void serviceWs() { 
    webSock := WebSocket()
    webSock.onMessage |MsgEvent e| { ... }
    webSock.upgrade(req, res)
    webSock.read
}

allowedOrigins

Source

Str[]? allowedOrigins

A list of regex globs that are matched against incoming requests. Only used by upgrade() and is ignored by client WebSocket instances.

A null value indicated that all origins are accepted. (Unsafe!)

webSock := WebSocket()
webSock.allowedOrigins = ["http://localhost:8069", "http://example.*"]

bufferedAmount

Source

abstract Int bufferedAmount()

The number of bytes that have been queued using sendXXXX() but have not yet been transmitted to the network.

This amount does not include framing overhead incurred by the protocol.

If the connection is closed, this attribute's value will only increase with each call to the sendXXXX() method (the number does not reset to zero once the connection closes).

close

Source

abstract Void close(Int? code := 1000, Str? reason := null)

Closes the WebSocket connection. Does nothing if the connection is already closed or closing.

The close code defaults to 1000 - Normal Closure - see RFC 6455 sec. 7.4.1 for a list of valid close codes.

id

Source

abstract Uri id()

A unique ID for this WebSocket instance. Use to retrieve instances from WebSockets.

make

Source

static new make()

Creates a WebSocket instance based the current runtime. (Fantom vs Javascript)

webSock := WebSocket.create()

onClose

Source

|CloseEvent? onClose

Hook for when an WebSocket closes.

webSock := WebSocket()
webSock.onClose = |CloseEvent ce| {
    echo("WebSocket closed")
}

onError

Source

|Err? onError

Hook for when an error occurs.

webSock := WebSocket()
webSock.onError = |Err err| {
    echo("WebSocket error - $err")
}

onMessage

Source

|MsgEvent? onMessage

Hook for when a message is received.

webSock := WebSocket()
webSock.onMessage = |MsgEvent me| {
    echo("WebSocket message: $me.txt")
}

onOpen

Source

|->Void? onOpen

Hook for when the WebSocket is connected.

webSock := WebSocket()
webSock.onOpen = |->| {
    echo("WebSocket open for business!")
}

open

Source

abstract This open(Uri url, Str[]? protocols := null)

Opens a HTTP connection to the given URL and upgrades the connection to a WebSocket. All URLs should have either a ws or wss scheme.

Usage designates this WebSocket instance as a client.

Throws IOErr on handshake errors.

read

Source

abstract Void read()

Enters a WebSocket read / event loop that blocks the current thread until the WebSocket is closed.

This method does nothing when called from a Javascript runtime.

readyState

Source

abstract ReadyState readyState()

Returns the state of the connection.

sendBinary

Source

abstract Void sendBinary(Buf data)

Transmits binary data through the WebSocket connection.

sendText

Source

abstract Void sendText(Str data)

Transmits text through the WebSocket connection.

upgrade

Source

abstract Obj upgrade(Obj webReq, Obj webRes, Bool commit := true)

Upgrades the given HTTP connection (WebReq and WebRes) to a WebSocket connection. If commit is true (default) then headers are flushed to the client, committing the response. If false then you must subsequently call WebRes.upgrade().

Server side usage only. Returns TcpSocket.

Throws IOErr on handshake errors.

url

Source

abstract Uri url()

The URL this WebSocket is connected to. Only available after calling open() or upgrade().