WebSocket - Documentation

To upgrade an HTTP connection to WebSocket, start by looking at isWebSocketUpgrade.
To parse WebSocket frames, start by looking at getWebSocketOpCode.
To construct WebSocket frames, look at makeWebSocketTextFrame, makeWebSocketBinaryFrame, makeWebSocketCloseFrame or makeWebSocketPingFrame

Source:

websocket.js, line 2

Members

(inner, readonly) opCodes

The possible WebSocket opCodes that can be returned from getWebSocketOpCode. If anything other than any of these opCodes are received, an error should be thrown.

Properties:

Name	Type	Description
`text`	`number`	The opCode for a WebSocket text frame. Get the text content by calling getWebSocketTextPayload.
`binary`	`number`	The opCode for a WebSocket binary frame. Get the binary content by calling getWebSocketBinaryPayload.
`close`	`number`	The opCode for a WebSocket close frame. Get the close code by calling getWebSocketCloseCode. Get the close reason by calling getWebSocketCloseReason. If the WebSocket server did not initiate the closing handshake, the server MUST answer the client with a close frame back. A close frame can be created by calling makeWebSocketCloseFrame.
`ping`	`number`	The opCode for a WebSocket ping frame. The WebSocket MUST answer ping frames with a pong response that can be created by calling makeWebSocketPingResponse with the ping buffer. If ping frame contains a payload, it can be extracted by using the same functions for getting payload from text or binary frames.
`pong`	`number`	The opCode for a WebSocket pong frame. If pong frame contains a payload, it can be extracted by using the same functions for getting payload from text or binary frames.
`fragmentedText`	`number`	The opCode for a WebSocket text frame that is not the last for the message. Get the text content by calling getWebSocketTextPayload and buffer it until getting a `fragmentedEnd`. If a `fragmentedText` or `fragmentedBinary` has already been received without getting a `fragmentedEnd`, an error should be thrown.
`fragmentedBinary`	`number`	The opCode for a WebSocket binary frame that is not the last for the message. Get the binary content by calling getWebSocketBinaryPayload and buffer it until getting a `fragmentedEnd`. If a `fragmentedText` or `fragmentedBinary` has already been received without getting a `fragmentedEnd`, an error should be thrown.
`fragmentedContinue`	`number`	The opCode for a WebSocket frame continuing on a buffered message and is not the last for the message. Call getWebSocketTextPayload or getWebSocketBinaryPayload to get content and add it to the buffer. If a `fragmentedText` or `fragmentedBinary` has not been received before getting this opCode, an error should be thrown.
`fragmentedEnd`	`number`	The opCode for a WebSocket frame continuing on a buffered message and is the last buffer for the message. Call getWebSocketTextPayload or getWebSocketBinaryPayload to get content and add it to the buffer. If a `fragmentedText` or `fragmentedBinary` has not been received before getting this opCode, an error should be thrown. Since this is the last chunk in the buffered message, the buffer should now be handled the same way a normal `opCode.text` or `opCode.binary` frame is handled.

Source:

websocket.js, line 166

Methods

(inner) getWebSocketBinaryPayload(buffer) → {Uint8Array}

Gets the binary content from a WebSocket binary frame. Check if WebSocket frame is a binary frame with getWebSocketOpCode.

Source:

websocket.js, line 237

Parameters:

Name	Type	Description
`buffer`	`ArrayBuffer`	The WebSocket buffer received from a client

Returns:

Type:: Uint8Array

Unmasked WebSocket payload as an array buffer

(inner) getWebSocketCloseCode(buffer) → {number|undefined}

Gets the close status code for the connection. Check if WebSocket frame is a close frame with getWebSocketOpCode. More info about the WebSocket close codes can be found at https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent

Source:

websocket.js, line 254

Parameters:

Name	Type	Description
`buffer`	`ArrayBuffer`	The WebSocket buffer received from a client

Returns:

Type:: number | undefined

The status code received from the client or undefined if there is no code

(inner) getWebSocketCloseReason(buffer) → {string}

Gets the close reason in plain text for the connection. Check if WebSocket frame is a close frame with getWebSocketOpCode.

Source:

websocket.js, line 265

Parameters:

Name	Type	Description
`buffer`	`ArrayBuffer`	The WebSocket buffer received from a client

Returns:

Type:: string

Unmasked WebSocket payload as a string

(inner) getWebSocketOpCode(buffer) → {number}

Gets the WebSocket op code from a buffer. If it is a Websocket frame, the value is going to match one of the opCodes in opCodes. Read more for the specific opCodes on how handle them.

If an error is thrown, it should include a closeCode that can be used with makeWebSocketCloseFrame to close the socket.

Source:

websocket.js, line 118

Parameters:

Name	Type	Description
`buffer`	`ArrayBuffer`	The WebSocket buffer received from a client

Throws:

Is a fragmented frame (fragmented frames are not supported right now)
Has one or more reserved bits set
Payload is not masked
Control frame has message longer than 125

Returns:

Type:: number

The opCode for the WebSocket frame

(inner) getWebSocketTextPayload(buffer) → {string}

Gets the text content from a WebSocket text frame. Check if WebSocket frame is a text frame with getWebSocketOpCode.

Source:

websocket.js, line 220

Parameters:

Name	Type	Description
`buffer`	`ArrayBuffer`	The WebSocket buffer received from a client

Returns:

Type:: string

Unmasked WebSocket payload as a string

(inner) isWebSocketUpgrade(req) → {boolean}

Checks if HTTP request is a WebSocket upgrade.

If the request is an upgrade, makeWebSocketUpgradeResponse can be used to send an upgrade response to the client.
When upgrade response is sent, all future data MUST be WebSocket frames. To parse future WebSocket frames, start by calling getWebSocketOpCode to know how to handle the data

If an error is thrown, the function makeFailedHttpUpgradeResponse can be called with the error object as its only argument to get an HTTP response for that error.

Source:

websocket.js, line 16

Parameters:

Name	Type	Description
`req`	`HttpRequest`	The HTTP request object received from calling parseHttp or other HTTP parser with the structure of HttpRequest

Throws:

Is WebSocket upgrade but method is NOT GET
Is WebSocket upgrade but HTTP version is not 1.1 or higher
Is WebSocket upgrade but WebSocket version is not 13
Is WebSocket upgrade but WebSocket key header is not a string

Returns:

Type:: boolean

If the request is a WebSocket upgrade or not

(inner) makeFailedHttpUpgradeResponse(err) → {string}

Makes an HTTP response indicating the WebSocket upgrade request has failed.

Source:

websocket.js, line 80

Parameters:

Name	Type	Description
`err`	`Error`	An error from isWebSocketUpgrade call

Throws:

Error is not from isWebSocketUpgrade call

Returns:

Type:: string

An HTTP response for the error that occured. The function stringToBuffer can be used to convert the string result to a Uint8Array.

(inner) makeWebSocketBinaryFrame(payload) → {Uint8Array}

Makes a WebSocket binary frame containing the payload

Source:

websocket.js, line 306

Parameters:

Name	Type	Description
`payload`	`ArrayBuffer`	The binary content to send in the WebSocket frame

Throws:

Has a payload largeer than 32bit

Returns:

Type:: Uint8Array

The WebSocket frame containing the payload

(inner) makeWebSocketCloseFrame(codeopt, reasonopt) → {Uint8Array}

Makes a WebSocket close frame containing the close code and reason

Source:

websocket.js, line 321

Parameters:

Name	Type	Attributes	Description
`code`	`number`	<optional>	The close code to send. More info about the WebSocket close codes can be found at https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent
`reason`	`string`	<optional>	The close reason to send (requires close code to be defined)

Throws:

Code is ouside range of valid close codes
Reason argument is defined but not code argument

Returns:

Type:: Uint8Array

The close frame

(inner) makeWebSocketPingFrame() → {Uint8Array}

Makes a WebSocket ping frame

Source:

websocket.js, line 357

To Do:

Include payload in ping frame

Returns:

Type:: Uint8Array

The ping frame

(inner) makeWebSocketPingResponse(ping) → {Uint8Array}

Makes a WebSocket pong fram in response to a ping request

Source:

websocket.js, line 367

Parameters:

Name	Type	Description
`ping`	`ArrayBuffer`	The buffer from the ping request

Returns:

Type:: Uint8Array

The pong frame

(inner) makeWebSocketTextFrame(payload) → {Uint8Array}

Makes a WebSocket text frame containing the payload

Source:

websocket.js, line 291

Parameters:

Name	Type	Description
`payload`	`string`	The text content to send in the WebSocket frame

Throws:

Has a payload larger than 32bit

Returns:

Type:: Uint8Array

The WebSocket frame containing the payload

(inner) makeWebSocketUpgradeResponse(req) → {string}

Makes an HTTP response indicating the connection has successfully been upgraded to use the WebSocket protocol.

Source:

websocket.js, line 98

Parameters:

Name	Type	Description
`req`	`HttpRequest`	The HTTP request that was confirmed to be an upgraded to the WebSocket protocol by isWebSocketUpgrade

Returns:

Type:: string

The HTTP response to upgrade the client to use the WebSocket protocol. The function stringToBuffer can be used to convert the string result to a Uint8Array.