Types
ProtocolError = object of Defect
- Source Edit
MaskingKey = string
- The type used as a masking key. This is string by default, use -d:websocketStricterMaskingKey to switch to array[4, char]. Source Edit
Opcode {...}{.pure.} = enum Cont = 0x00000000, ## Continued Frame (when the previous was fin = 0) Text = 0x00000001, ## Text frames need to be valid UTF-8 Binary = 0x00000002, ## Binary frames can be anything. Close = 0x00000008, ## The remote is closing the socket or we intend to close it. Ping = 0x00000009, ## Ping Pong = 0x0000000A ## Pong. Needs to echo back the app data in ping. ## This library handles these by default but you can use ## ``-d:websocketIgnorePing`` to handle them yourself.
- Source Edit
Frame = object fin {...}{.bitsize: 1.}: bool ## Last frame in current packet. rsv1 {...}{.bitsize: 1.}, rsv2 {...}{.bitsize: 1.}, rsv3 {...}{.bitsize: 1.}: bool ## Extension data: negotiated in http prequel, or 0. masked {...}{.bitsize: 1.}: bool ## If the frame was received masked/is supposed to be masked. opcode {...}{.bitsize: 4.}: Opcode ## The opcode of this frame. maskingKey: MaskingKey ## The masking key if the frame is supposed to be masked. ## If masked is false, this is an empty string. ## Otherwise, length is 4. data: string ## App data
- A frame read off the netlayer. Source Edit
SocketKind {...}{.pure.} = enum Client, Server
- Source Edit
AsyncWebSocketObj = object sock*: AsyncSocket protocol*: string kind*: SocketKind
- Source Edit
AsyncWebSocket = ref AsyncWebSocketObj
- A small wrapper around asyncnet.AsyncSocket that keeps track of whether the socket is a client or server and a string of the protocol being used to communicate. Source Edit
Procs
proc mask(data: var string; maskingKey: MaskingKey) {...}{.raises: [], tags: [].}
- Source Edit
proc generateMaskingKey(): MaskingKey {...}{.raises: [], tags: [].}
- Uses the random module of the standard library to generate a random 4 character string. Used by default. Not secure. Source Edit
proc makeFrame(f: Frame): string {...}{.raises: [ProtocolError], tags: [].}
- Generate valid websocket frame data, ready to be sent over the wire. This is useful for rolling your own impl, for example with AsyncHttpServer Source Edit
proc makeFrame(opcode: Opcode; data: string; maskingKey = generateMaskingKey()): string {...}{. raises: [ProtocolError], tags: [].}
- A convenience shorthand. Source Edit
proc recvFrame(ws: AsyncSocket): Future[Frame] {...}{. raises: [Exception, ValueError, FutureError], tags: [RootEffect].}
-
Read a full frame off the given socket.
You probably want to use the higher-level variant, readData.
Source Edit proc extractCloseData(data: string): tuple[code: int, reason: string] {...}{.raises: [], tags: [].}
- A way to get the close code and reason out of the data of a Close opcode. Source Edit
proc readData(ws: AsyncSocket): Future[tuple[opcode: Opcode, data: string]] {...}{. raises: [Exception, ValueError, FutureError], tags: [RootEffect].}
-
Reads reassembled data off the websocket and give you joined frame data.
Note: You will still see control frames, but they are all handled for you (Ping/Pong, Cont, Close, and so on).
The only ones you need to care about are Opcode.Text and Opcode.Binary, the so-called application frames.
Will raise IOError when the socket disconnects and ProtocolError on any websocket-related issues.
Source Edit proc sendText(sock: AsyncSocket; p: string; maskingKey = generateMaskingKey()): Future[ void] {...}{.raises: [Exception, FutureError], tags: [RootEffect].}
- Sends text data. Will only return after all data has been sent out. Source Edit
proc sendBinary(sock: AsyncSocket; p: string; maskingKey = generateMaskingKey()): Future[ void] {...}{.raises: [Exception, FutureError], tags: [RootEffect].}
- Sends binary data. Will only return after all data has been sent out. Source Edit
proc sendPing(sock: AsyncSocket; maskingKey = generateMaskingKey(); token: string = ""): Future[ void] {...}{.raises: [Exception, FutureError], tags: [TimeEffect, RootEffect].}
- Sends a WS ping message. Will generate a suitable token if you do not provide one. Source Edit
proc sendChain(sock: AsyncSocket; p: seq[string]; opcode = Opcode.Text; maskingKeys: seq[MaskingKey] = @[]): Future[void] {...}{. raises: [Exception, FutureError], tags: [RootEffect].}
- Sends data over multiple frames. Will only return after all data has been sent out. Source Edit
proc readData(ws: AsyncWebSocket): Future[tuple[opcode: Opcode, data: string]] {...}{. raises: [Exception, ValueError, FutureError], tags: [RootEffect].}
-
Reads reassembled data off the websocket and give you joined frame data.
Note: You will still see control frames, but they are all handled for you (Ping/Pong, Cont, Close, and so on).
The only ones you need to care about are Opcode.Text and Opcode.Binary, the so-called application frames.
Will raise IOError when the socket disconnects and ProtocolError on any websocket-related issues.
Source Edit proc sendText(ws: AsyncWebSocket; p: string; maskingKey = generateMaskingKey()): Future[ void] {...}{.raises: [Exception, FutureError], tags: [RootEffect].}
- Sends text data. Will only return after all data has been sent out. Source Edit
proc sendBinary(ws: AsyncWebSocket; p: string; maskingKey = generateMaskingKey()): Future[ void] {...}{.inline, raises: [Exception, FutureError], tags: [RootEffect].}
- Sends binary data. Will only return after all data has been sent out. Source Edit
proc sendPing(ws: AsyncWebSocket; maskingKey = generateMaskingKey(); token: string = ""): Future[void] {...}{.inline, raises: [Exception, FutureError], tags: [TimeEffect, RootEffect].}
- Sends a WS ping message. Will generate a suitable token if you do not provide one. Source Edit
proc closeWebsocket(ws: AsyncSocket; code = 0; reason = ""): Future[void] {...}{. raises: [Exception, FutureError], tags: [RootEffect, WriteIOEffect, TimeEffect, ReadIOEffect].}
- Closes the socket. Source Edit
proc close(ws: AsyncWebSocket; code = 0; reason = ""): Future[void] {...}{.inline, raises: [Exception, FutureError], tags: [RootEffect, WriteIOEffect, TimeEffect, ReadIOEffect].}
- Closes the socket. Source Edit
Templates
template unmask(data: var string; maskingKey: MaskingKey): auto
- Source Edit