Skip to content

Latest commit

 

History

History
141 lines (91 loc) · 7.68 KB

WebSocketConnection.md

File metadata and controls

141 lines (91 loc) · 7.68 KB
Raw

WebSocketConnection

This object provides the interface through which you can communicate with connected peers. It is used in both WebSocketServer and WebSocketClient situations.

Constructor

This object is created internally by WebSocketRequest.

Properties

closeDescription

After the connection is closed, contains a textual description of the reason for the connection closure, or null if the connection is still open.

closeReasonCode

After the connection is closed, contains the numeric close reason status code, or -1 if the connection is still open.

socket

The underlying net.Socket instance for the connection.

protocol

The subprotocol that was chosen to be spoken on this connection. This field will have been converted to lower case.

extensions

An array of extensions that were negotiated for this connection. Currently unused, will always be an empty array.

remoteAddress

The IP address of the remote peer as a string. In the case of a server, the X-Forwarded-For header will be respected and preferred for the purposes of populating this field. If you need to get to the actual remote IP address, webSocketConnection.socket.remoteAddress will provide it.

webSocketVersion

A number indicating the version of the WebSocket protocol being spoken on this connection.

connected

A boolean value indicating whether or not the connection is still connected. Read-only

Methods

close([reasonCode], [description])

Will gracefully close the connection. A close frame will be sent to the remote peer with the provided reasonCode and description indicating that we wish to close the connection, and we will then wait for up to config.closeTimeout milliseconds for an acknowledgment from the remote peer before terminating the underlying socket connection. The closeTimeout is passed as part of the serverOptions or clientOptions hashes to either the WebSocketServer or WebSocketClient constructors. Most of the time, you should call close() without arguments to initiate a normal connection closure. If you specify a reasonCode that is defined as one of the standard codes in the WebSocket protocol specification and do not provide a description, the default description for the given code will be used. If you would prefer not to send a description at all, pass an empty string ''as the description parameter.

drop([reasonCode], [description])

Will send a close frame to the remote peer with the provided reasonCode and description and will immediately close the socket without waiting for a response. This should generally be used only in error conditions. The default reasonCode is 1002 (Protocol Error). Close reasons defined by the WebSocket protocol draft include:

WebSocketConnection.CLOSE_REASON_NORMAL = 1000;
WebSocketConnection.CLOSE_REASON_GOING_AWAY = 1001;
WebSocketConnection.CLOSE_REASON_PROTOCOL_ERROR = 1002;
WebSocketConnection.CLOSE_REASON_UNPROCESSABLE_INPUT = 1003;
WebSocketConnection.CLOSE_REASON_RESERVED = 1004; // Reserved value.  Undefined meaning.
WebSocketConnection.CLOSE_REASON_NOT_PROVIDED = 1005; // Not to be used on the wire
WebSocketConnection.CLOSE_REASON_ABNORMAL = 1006; // Not to be used on the wire
WebSocketConnection.CLOSE_REASON_INVALID_DATA = 1007;
WebSocketConnection.CLOSE_REASON_POLICY_VIOLATION = 1008;
WebSocketConnection.CLOSE_REASON_MESSAGE_TOO_BIG = 1009;
WebSocketConnection.CLOSE_REASON_EXTENSION_REQUIRED = 1010;

sendUTF(string)

Immediately sends the specified string as a UTF-8 WebSocket message to the remote peer. If config.fragmentOutgoingMessages is true the message may be sent as multiple fragments if it exceeds config.fragmentationThreshold bytes. Any object that implements the toString() method may be passed to sendUTF()

sendBytes(buffer)

Immediately sends the specified Node Buffer object as a Binary WebSocket message to the remote peer. If config.fragmentOutgoingMessages is true the message may be sent as multiple fragments if it exceeds config.fragmentationThreshold bytes.

send(data)

A convenience function that will auto-detect the data type and send the appropriate WebSocket message accordingly. Immediately sends the specified data as either a UTF-8 or Binary message. If data is a Node Buffer, a binary message will be sent. Otherwise, the object provided must implement the toString() method, and the result of calling toString() on the data object will be sent as a UTF-8 message.

ping(data)

Sends a ping frame to the remote peer. data can be a Node Buffer or any object that implements toString(), such as a string or number. Ping frames must not exceed 125 bytes in length.

pong(buffer)

Sends a pong frame to the remote peer. Pong frames may be sent unsolicited and such pong frames will trigger no action on the receiving peer. Pong frames sent in response to a ping frame must mirror the payload data of the ping frame exactly. The WebSocketConnection object handles this internally for you, so there should be no need to use this method to respond to pings unless you explicitly cancel() this internal behavior (see ping event below). Pong frames must not exceed 125 bytes in length.

sendFrame(webSocketFrame)

Serializes a WebSocketFrame object into binary data and immediately sends it to the remote peer. This is an advanced function, requiring you to manually compose your own WebSocketFrame. You should probably use sendUTF or sendBytes instead.

Events

message

function(message)

Emitted whenever a complete single-frame message is received, or if config.assembleFragments is true (the default), it will also be emitted with a complete message assembled from multiple fragmented frames. This is the primary event to listen for to receive messages from the remote peer. The message object looks like the following:

// For Text Frames:
{
    type: "utf8",
    utf8Data: "A string containing the received message."
}

// For Binary Frames:
{
    type: "binary",
    binaryData: binaryDataBuffer // a Buffer object containing the binary message payload
}

frame

function(webSocketFrame)

This event is emitted only if config.assembleFragments is false (default is true). This allows you to handle individual fragments as they are received without waiting on WebSocketConnection to buffer them into a single message event for you. This may be desirable if you are working with streaming data, as it is possible to send fragments continually without ever stopping. webSocketFrame is an instance of WebSocketFrame which has properties that represent all the individual fields in WebSocket's binary framing protocol.

close

function(reasonCode, description)

This event is emitted when the connection has been fully closed and the socket is no longer connected. reasonCode is the numeric reason code for the connection closure. description is a textual explanation for the connection closure, if available.

error

function(error)

This event is emitted when there has been a socket error. If this occurs, a close event will also be emitted.

ping

function(cancel, data)

This event is emitted when the connection receives a ping from the peer. cancel is a function taking no arguments that when called prevents the WebSocketConnection object from automatically replying with a pong. data is the binary payload contained in the ping frame.

pong

function(data)

This event is emitted when the connection receives a pong from the peer. data is the binary data contained in the pong frame.