websocket

nimony/lib/std/websocket.nim

const WsGuid: string
The GUID of RFC 6455 §4.2.2, appended to the key to make the accept.
const WsVersion: string
The only version this module speaks. RFC 6455 has never had another.
const DefaultMaxMessage: int64
The largest message accepted, in bytes. A message is assembled before it is handed out, so this is also the most memory one peer can make the other spend on a message.
const DefaultHandshakeMs: int64
How long the client gives the server to answer the handshake.
const DefaultCloseMs: int64
How long a side waits for the peer's half of the closing handshake.
const wscNormal: int64
The connection did what it was for.
const wscGoingAway: int64
One side is going away: a server shutting down, a page unloading.
const wscProtocolError: int64
The peer broke the protocol.
const wscUnsupported: int64
A message of a type this endpoint does not take.
const wscNoStatus: int64
Never sent: what a peer sees when no code was sent at all.
const wscAbnormal: int64
Never sent: what a peer sees when the connection went away without a closing handshake.
const wscInvalidPayload: int64
A text message that was not UTF-8.
const wscPolicy: int64
The message was understood and refused.
const wscTooBig: int64
A frame or message was larger than the endpoint accepts.
const wscExtension: int64
The client wanted an extension the server did not agree to.
const wscInternalError: int64
The endpoint hit a condition of its own that it cannot describe.
const wscTlsError: int64
Never sent: the TLS handshake failed, which is a local fact.

type MsgKind = enum
  mkText = (0, "mkText")
  mkBinary = (1, "mkBinary")
  mkPing = (2, "mkPing")
  mkPong = (3, "mkPong")
  mkClose = (4, "mkClose")

func dollar`.MsgKind(e: MsgKind): string
type WsOpcode = HoleyEnum
func dollar`.WsOpcode(e: WsOpcode): string

type WsFrame = object
  fin: bool
  rsv: int64
  opcode: WsOpcode
  masked: bool
  key: array[0..3, char]
  len: int64

func dollar`.WsRole(e: WsRole): string

type WebSocketReader = object
  r: Reader
  role: WsRole
  maxMessage: int64
  idleMs: int64
  msgOp: int64
  msgBuf: string
  closeSeen: bool
  closeCode: int64
  failCode: int64
  err: ErrorCode

type WebSocketWriter = object
  w: Writer
  role: WsRole
  closeSent: bool
  closeCode: int64

type WebSocket = object
  reader: WebSocketReader
  writer: WebSocketWriter
  sub: string
  err: ErrorCode
  aborted: bool

proc applyMask(data: var openArray[char]; key: array[0..3, char]; offset: int64)
XORs data with the mask key, starting offset bytes into the payload.
Masking is its own inverse, so this both masks and unmasks: a sender applies it before the bytes go out, a receiver after they arrive. The offset is what makes a payload that arrives in pieces come out right — the key restarts at the front of the frame, not at the front of the read.
proc parseFrameHeader(bytes: openArray[char]; f: var WsFrame): int64
How many bytes the frame header at the front of bytes takes, ParseIncomplete while it has not all arrived, ParseBad when the header breaks the protocol.
The length is not checked against a limit here: a peer announcing a length is not the same as a peer sending one, and the caller decides how large a frame it will wait for.
proc frameHeader(opcode: WsOpcode; payloadLen: int64; masked: bool; key: array[0..3, char]; fin: bool): string
The header of a frame whose payload is payloadLen bytes.
fillHeader with a string to put it in: for a caller that needs the bytes on their own, not as part of a frame.
proc isSendableCloseCode(code: int64): bool
Whether code may go on the wire.
1005 and 1006 are what a peer sees when no code was sent, and 1015 is a local fact about TLS; sending any of them would be a lie about what happened. 1004 was never defined.
The rest of 1000 to 2999 belongs to the protocol and is not assigned: a peer that sends such a code is not speaking RFC 6455 (§7.4.2).
3000 to 3999 are for libraries and frameworks to use, 4000 to 4999 for private use; both are legal on the wire.
proc buffered(rd: WebSocketReader): int64
Protocol bytes the reader already has and has not consumed. Non-zero means a recv will not wait for the peer, which is what an echo server needs to know before it decides to flush: while frames are still buffered, the replies can wait and go out together.
proc deadline(rd: WebSocketReader): Deadline
The standing deadline of the receive side; the writer shares it.
proc renew(rd: var WebSocketReader; dl: Deadline)
Replaces the standing deadline of the connection. Raises BadOperation for a closed or default-constructed reader.
proc close(rd: var WebSocketReader)
Drops the receive side without reading anything else.
proc upgradeWebSocket(c: var HttpConnection; protocols: openArray[string]; maxMessage: int64; idleMs: int64): WebSocket
The WebSocket behind the request c.
The request has to be a WebSocket request — GET, HTTP/1.1, an Upgrade: websocket, a Connection that says Upgrade, the version 13 and a key — and the answer is the 101 that goes out before this returns. A request that is not one gets 400 (405 for the wrong method, 426 with the version this server speaks for a version it does not), and this raises: there is no falling back to HTTP, because a client that asked for a WebSocket and got a page has been told something false.
protocols are the subprotocols this server speaks, in the order it prefers them; the one the client asked for that this server has is named in the 101.
maxMessage is the largest message the connection accepts, in bytes. idleMs is how long recv waits for the next message, counted afresh for every call; 0 means no limit, which is what a WebSocket usually wants — a connection with nothing to say is idle, not stuck.
The Origin of the request is not this module's business. A server that cares about where a connection comes from — the cross-site WebSocket hijacking of 2010 was about a server that did not — reads the header itself and answers before the upgrade, because the answer is then an ordinary HTTP answer:
```
if not allowed(c.requestHeader("Origin")):
  c.respond(403, "this origin is not welcome\n")
  return
var ws = upgradeWebSocket(c)
```
The connection is move-only and has to be closed: leaving scope ends it.
proc connectWebSocket(url: string; headers: HttpHeaders; protocols: openArray[string]; maxMessage: int64; timeoutMs: int64; idleMs: int64; tls: ref TlsEngine.Obj): WebSocket
A WebSocket to url, which is ws://host:port/path — or wss:// for TLS.
headers are extra request headers, in their wire format, and are put on the handshake unchanged; protocols are offered as Sec-WebSocket-Protocol, in this order, and the one the server picks is subprotocol. timeoutMs bounds the whole handshake — connect, TLS and the answer — and idleMs is how long recv waits for the next message, counted afresh for every call, 0 for no limit.
A wss:// URL needs a TLS engine: std/tls's newTlsEngine() is the one to pass, and this module does not import it, so that a server that only listens pays for none of it. A wss:// URL without an engine, or an engine on a ws:// URL, is a BadOperation: one would speak plaintext to a TLS port, the other run a handshake the URL never asked for.
The answer is checked the way RFC 6455 §4.1 says a client has to: the status is 101, Upgrade and Connection say what they should, and Sec-WebSocket-Accept is the accept of the key this call made up. Anything else is a ProtocolError (or BadProtocol for a status that is not 101) — a server that does not upgrade did not, and pretending otherwise turns a protocol mismatch into a stream of nonsense frames.
proc reader(ws: var WebSocket): var WebSocketReader
The receiving half of the connection. The pair's recv is the usual entry point: it answers the pings and closes this half reports.
proc writer(ws: var WebSocket): var WebSocketWriter
The sending half of the connection. The pair's send is the usual entry point: it is the only place that knows the close handshake.
proc closeCode(ws: WebSocket): int64
The close code of the connection: the one the peer sent, the one that was sent, or 0 while the connection is still open.
proc closeCode(rd: WebSocketReader): int64
The close code the peer sent, or 0 while no close has been seen.
proc subprotocol(ws: WebSocket): string
The subprotocol the handshake agreed on; "" when there is none.
proc lastError(ws: WebSocket): ErrorCode
The error that ended the connection, if one did.
proc lastError(rd: WebSocketReader): ErrorCode
The error that ended the receive side, if one did.
proc abort(wr: var WebSocketWriter)
Drops the sending side without a close frame.
proc abort(ws: var WebSocket)
Drops the connection without a closing handshake.
The peer sees the connection go away without a goodbye, which is what an error looks like from its side. Use it when the connection is not worth a clean end — and see the note at the end of this module about the trap it is there to avoid.
proc send(wr: var WebSocketWriter; kind: MsgKind; data: openArray[char]; flush: bool)
Sends a message of kind with the bytes data.
Text has to be text: a mkText whose bytes are not UTF-8 raises rather than goes out, because the peer would have to fail the connection over it. A ping or a pong carries at most 125 bytes. Nothing may follow a close frame, so after one this raises BadOperation.
With flush = false the frame is only put in the connection's buffer and goes out with the next flush, or with the next frame that asks for one, or when the buffer fills. That is what makes a fan-out cheap: a task with several frames for one connection writes them all with one syscall — and the wait for that syscall is the backpressure that lets the next batch exist. A writer that stops writing has to flush; close does, and so does the pair's recv before it parks.
proc flush(wr: var WebSocketWriter)
Hands everything sent with flush = false to the kernel.
A flush of an empty buffer is free — it does not reach the descriptor — so this is safe to call whenever a batch of frames is finished.
proc close(wr: var WebSocketWriter; code: int64; reason: string)
Sends the close frame and nothing else. Waiting for the peer's half is the pair's job; this is for a caller that only drives the writer.
proc recv(rd: var WebSocketReader; msg: var string): MsgKind
The next message of the receive side, in msg.
A text or binary message is its payload. A ping, a pong and a close are handed over as mkPing, mkPong and mkClose: answering a ping and echoing a close need the writer, so that is the pair's business. A text message is checked as a whole; UTF-8 may be split across fragments.
The fragments of a message are put back together here. A protocol error raises ProtocolError with failCode naming the close code to send; the caller of a bare reader has to send it (the pair does).
With an idleMs, each call gets that long: it replaces whatever deadline the connection had.
proc recv(ws: var WebSocket; msg: var string): MsgKind
The next message of the connection, in msg.
A text or binary message is its payload. A ping is answered with a pong and not handed over — the peer asked whether the connection is alive, and the answer is not the application's business. A pong and a close are handed over: the first is the answer to a ping of this side's, the second ends the conversation.
proc send(ws: var WebSocket; kind: MsgKind; data: openArray[char]; flush: bool)
Sends a message of kind with the bytes data; see WebSocketWriter.send.
With flush = false the frames are only buffered; see WebSocketWriter.send, and flush below.
proc flush(ws: var WebSocket)
Hands everything sent with flush = false to the peer; see WebSocketWriter.flush.
proc close(ws: var WebSocket; code: int64; reason: string)
Ends the connection the way the protocol says: the close frame goes out, and then this side waits for the peer's close.
The wait is the connection's idleMs, or five seconds when it has none. A peer that does not answer is a timeout and raises like every other timeout in this API.
proc =destroy(ws: WebSocket)
proc =wasMoved(ws: var WebSocket)
.nodestroy: the halves have been handed to the destination, so clearing this one must not run their destructors on them. A moved-from connection has no reader, writer or subprotocol of its own.