Skip to content
FutureBlitz

    Install

    Import std.net.ws.websocket

    std.net.ws.websocket

    std.net.ws's WebSocket, per RFC 6455: messages of text or bytes both ways over one connection, a client's from Connect, at a ws:// URL, or a wss:// one over TLS, or a server's from Accept, which answers the client's handshake. Each is blocking or Async, and a Ping gets its Pong while a Receive reads.

    std/net/ws/websocket.fb

    Types

    WebSocketState enum 

    Public Enum WebSocketState

    What a WebSocket is at.

    std/net/ws/websocket.fb, line 30

    • OPEN enum member #

      Open.

    • CLOSING enum member #

      Closing, once it's sent its Close and waits for the other side's.

    • CLOSED enum member #

      Closed, once the Close has gone both ways, or the connection ended.

    WebSocketMessage struct 

    Public Struct WebSocketMessage Implements Printable

    A WebSocket's message: text, which is UTF-8, or bytes.

    std/net/ws/websocket.fb, line 40

    • Public ReadOnly Field IsText: Bool field #

      Whether it's text, or bytes.

    • Public ReadOnly Field Bytes: UInt8[] field #

      Its bytes: a text message's UTF-8.

    • Public New(isText: Bool, bytes: UInt8[]) constructor #

      A message of bytes, text when isText.

    • Public Property Text: String property #

      Its text: a text message's, or a binary one's bytes as UTF-8, or "" when they aren't.

    • Public Method ToString(): String method #

      A text message's text, or how many bytes a binary one has.

    WebSocket class 

    Public Class WebSocket

    A WebSocket connection. A Receive gives each message as it comes, and answers a Ping with a Pong, and the other side's Close with its own, after which it gives Null; only one Receive reads at a time. Send and Ping throw a NetError of CLOSED once Close has been called, and every error is a NetError: of CLOSED for a connection that ended without a Close frame, RESET for one the other side ended badly, and OTHER for a frame that breaks RFC 6455, which closes it with the code the RFC gives. The connection closes when the WebSocket goes, or at Abort.

    std/net/ws/websocket.fb, line 76

    • Public ReadOnly Field Protocol: String field #

      The subprotocol the handshake chose, or "".

    • @PanicsAtCaller Public Static Method Connect(url: String, protocols: String[] = [], timeout: Duration? = Null, tls: TlsClient? = Null): WebSocket Throws NetError, TimeoutError static method #

      Connects to a ws:// URL, or a wss:// one over TLS as tls connects, or for a Null one, a TlsClient that trusts the OS's roots, and opens a WebSocket there, asking for the subprotocols, if any, in the order it would have them, waiting up to timeout to connect and as long for each read of the TLS handshake and the server's answer, or as long as it takes for a Null one. Throws a NetError as TcpStream.Connect and TlsClient.Connect do, and of OTHER for a URL that isn't ws:// or wss:// and an answer that isn't a WebSocket's. Panics when a subprotocol isn't a token.

    • @PanicsAtCaller Public Static Async Method ConnectAsync(url: String, protocols: String[] = [], timeout: Duration? = Null, tls: TlsClient? = Null): WebSocket Throws NetError, TimeoutError static method #

      Connect's Async twin, which waits on the main thread.

    • @PanicsAtCaller Public Static Method Accept(stream: TcpStream, protocols: String[] = []): WebSocket Throws NetError static method #

      Reads a client's handshake from a connection a TcpListener accepted, and opens a WebSocket over it, choosing the first of the client's subprotocols that protocols has, or none. A request that isn't a WebSocket's is answered with an error's status, and closed, and throws a NetError of OTHER; one that ends first throws a NetError of CLOSED. Panics when a subprotocol isn't a token.

    • @PanicsAtCaller Public Static Async Method AcceptAsync(stream: TcpStream, protocols: String[] = []): WebSocket Throws NetError static method #

      Accept's Async twin, which waits on the main thread.

    • @PanicsAtCaller Public Static Async Method AcceptAsync(request: HttpRequest, protocols: String[] = []): WebSocket Throws NetError static method #

      Opens a WebSocket over the connection of a request that an HttpServer's handler was given, answering its handshake as AcceptAsync of a TcpStream does, and takes the connection from the server, which then sends nothing of the handler's response, and doesn't close it as it stops. A request that isn't a WebSocket's throws a NetError of OTHER, and the server sends the handler's response to it. Panics when a subprotocol isn't a token, or the request's connection is a WebSocket's already.

    • Public Property State: WebSocketState property #

      Where it is: OPEN, CLOSING, or CLOSED.

    • Public Property CloseCode: Int? property #

      The code of the Close that came, 1005 for one without, or 1006 when the connection ended without one, as one this side failed for breaking RFC 6455 does, or Null while none has.

    • Public Property CloseReason: String property #

      The reason the other side's Close gave, or "".

    • @PanicsAtCaller Public Property MaxMessageSize: Int64 property #

      The most bytes a message it receives can have, 16 MiB unless it's set; a longer one closes it with 1009 and throws. Panics when it's set below 1.

    • @PanicsAtCaller Public Method Receive(): WebSocketMessage? Throws NetError method #

      The next message, waiting for it, or Null once the other side's Close has come, and after. Panics when another Receive is reading.

    • @PanicsAtCaller Public Async Method ReceiveAsync(): WebSocketMessage? Throws NetError method #

      Receive's Async twin, which waits on the main thread.

    • Public Method Send(text: String) Throws NetError method #

      Sends a text message.

    • Public Method Send(bytes: UInt8[]) Throws NetError method #

      Sends a binary message.

    • Public Async Method SendAsync(text: String) Throws NetError method #

      What Send does, without blocking its thread: a call gives its Task.

    • Public Async Method SendAsync(bytes: UInt8[]) Throws NetError method #

      What Send does, without blocking its thread: a call gives its Task.

    • @PanicsAtCaller Public Method Ping(bytes: UInt8[] = []) Throws NetError method #

      Sends a Ping, which the other side answers with a Pong of the same bytes, 125 at most, or it panics. A Receive reads past the Pong.

    • @PanicsAtCaller Public Async Method PingAsync(bytes: UInt8[] = []) Throws NetError method #

      What Ping does, without blocking its thread: a call gives its Task.

    • @PanicsAtCaller Public Method Close(code: Int = 1000, reason: String = "") method #

      Sends a Close with code and reason, unless it has already, and is CLOSING: Receive gives the messages that came before the other side's Close, and then Null. The code is 1000, a normal close, or one RFC 6455 has an endpoint send, from 1001 to 1003 or 1007 to 1014, or one of 3000 to 4999, and the reason's UTF-8 is 123 bytes at most, or it panics. A Close that can't be sent closes the connection.

    • @PanicsAtCaller Public Async Method CloseAsync(code: Int = 1000, reason: String = "") method #

      What Close does, without blocking its thread: a call gives its Task.

    • Public Method Abort() method #

      Closes the connection at once, without a Close frame, and is CLOSED.

    Report an issue with this page or with FutureBlitz on GitHub.