-
Notifications
You must be signed in to change notification settings - Fork 602
Documentation
WebSocket-Node includes both client and server functionality, available through WebSocketClient and WebSocketServer respectively. Once a connection is established, the API for sending and receiving messages is identical whether you're acting as a client or server.
var WebSocketServer = require('websocket').server
new WebSocketServer([serverConfig]);###mount(serverConfig)
mount will attach the WebSocketServer instance to a Node http.Server instance. serverConfig is required, and is an object with configuration values. For those values, see Server Config Options below. If you passed serverConfig to the constructor, this function will automatically be invoked.
###unmount()
unmount will detach the WebSocketServer instance from the Node http.Server instance. All existing connections are left alone and will not be affected, but no new WebSocket connections will be accepted.
###closeAllConnections()
Will gracefully close all open WebSocket connections.
###shutDown()
Gracefully closes all open WebSocket connections and unmounts the server from the Node http.Server instance.
httpServer - (http.Server instance)
The http server instance to attach to. Required.
maxReceivedFrameSize - uint - Default: 64KiB
The maximum allowed received frame size in bytes. Single frame messages will also be limited to this maximum.
maxReceivedMessageSize - uint - Default: 1MiB
The maximum allowed aggregate message size (for fragmented messages) in bytes.
fragmentOutgoingMessages - Boolean - Default: true
Whether or not to fragment outgoing messages. If true, messages will be automatically fragmented into chunks of up to fragmentationThreshold bytes.
fragmentationThreshold - uint - Default: 16KiB
The maximum size of a frame in bytes before it is automatically fragmented.
keepalive - boolean - Default: true
If true, the server will automatically send a ping to all clients every keepaliveInterval milliseconds.
keepaliveInterval - uint - Default: 20000
The interval in milliseconds to send keepalive pings to connected clients.
assembleFragments - boolean - Default: true
If true, fragmented messages will be automatically assembled and the full message will be emitted via a message event. If false, each frame will be emitted on the WebSocketConnection object via a frame event and the application will be responsible for aggregating multiple fragmented frames. Single-frame messages will emit a message event in addition to the frame event. Most users will want to leave this set to true.
autoAcceptConnections - boolean - Default: false
If this is true, websocket connections will be accepted regardless of the path and protocol specified by the client. The protocol accepted will be the first that was requested by the client. Clients from any origin will be accepted. This should only be used in the simplest of cases. You should probably leave this set to 'false' and inspect the request object to make sure it's acceptable before accepting it.
closeTimeout - uint - Default: 5000
The number of milliseconds to wait after sending a close frame for an acknowledgement to come back before giving up and just closing the socket.
There are three events emitted by a WebSocketServer instance that allow you to handle incoming requests, establish connections, and detect when a connection has been closed.
###request
function(webSocketRequest)
If autoAcceptConnctions is set to false, a request event will be emitted by the server whenever a new WebSocket request is made. You should inspect the requested protocols and the user's origin to verify the connection, and then accept or reject it by calling webSocketRequest.accept('chosen-protocol', 'accepted-origin') or webSocketRequest.reject()
###connection
function(webSocketConnection)
If autoAcceptConnections is set to true, a connection event will be emitted by the server when a new WebSocket request is made. The server automatically accepts all connections, so the connection event will pass the established WebSocketConnection object. This should only be used in extremely simplistic test servers etc. for security reasons, as it will accept connections from any source domain.
###close
function(webSocketConnection)
Whenever a connection is closed for any reason, the WebSocketServer instance will emit a close event, passing a reference to the WebSocketConnection instance that was closed.
This object represents a client requesting to connect to the server, and allows you to accept or reject the connection based on whatever criteria you decide.
This object is created internally by WebSocketServer.
However if you need to integrate WebSocket support without mounting an instance of WebSocketServer to your http server directly, you can handle the upgrade event yourself and pass the appropriate parameters to the WebSocketRequest constructor. NOTE: You must pass a complete set of config options to the constructor. See the section 'Server Config Options' above. The only option that isn't required in this context is httpServer.
new WebSocketRequest(socket, httpRequest, config);The constructor will immediately parse and validate the handshake from the client and will throw an error if the handshake from the client is invalid or if an errors is encountered, so it must always be wrapped in a try/catch block.
###httpRequest
A reference to the original Node HTTP request object. This may be useful in combination with some other Node-based web server, such as Express, for accessing cookies or session data.
###host
A string containing the contents of the Host header passed by the client. This will include the port number if a non-standard port is used.
Examples:
www.example.com
www.example.com:8080
127.0.0.1:3000
###resource
A string containing the path that was requested by the client.
###remoteAddress
The remote client's IP Address as a string. If an X-Forwarded-For header is present, the value will be taken from that header to facilitate WebSocket servers that live behind a reverse-proxy.
###websocketVersion
A string containing the version of the WebSocket protocol requested by the client.
###origin
If the client is a web browser, origin will be a string containing the URL of the page containing the script that opened the connection. If the client is not a web browser, origin may be null or "*".
###requestedExtensions
An array containing a list of extensions requested by the client. This is not currently used for anything. Example:
[
{
name: "simple-extension"
},
{
name: "my-great-compression-extension",
params: [
{
name: "compressionLevel",
value: "10"
}
]
}
]###requestedProtocols
An array containing a list of strings that indicate the subprotocols the client would like to speak. The server should select the best one that it can support from the list and pass it to the accept() function when accepting the connection.
###accept(acceptedProtocol, allowedOrigin) Returns: WebSocketConnection instance
After inspecting the WebSocketRequest's properties, call this function on the request object to accept the connection. If you don't have a particular subprotocol you wish to speak, you may pass null for the acceptedProtocol parameter. For browser clients (in which the origin property would be non-null) you must pass that user's origin as the allowedOrigin parameter to confirm that you wish to accept connections from the given origin. The return value contains the established WebSocketConnection instance that can be used to communicate with the connected client.
###reject([httpStatus], [reason])
If you decide to reject the connection, you must call reject. You may optionally pass in an HTTP Status code (such as 404) and a textual description that will be sent to the client in the form of an "X-WebSocket-Reject-Reason" header. The connection will then be closed.
###requestAccepted
function(webSocketConnection)
Emitted by the WebSocketRequest object when the accept method has been called and the connection has been established. webSocketConnection is the established WebSocketConnection instance that can be used to communicate with the connected client.
###requestRejected
function()
Emitted by the WebSocketRequest object when the reject method has been called and the connection has been terminated.
This object provides the interface through which you can communicate with connected peers. It is used in both WebSocketServer and WebSocketClient situations.
This object is created internally by WebSocketRequest.
###socket
The underlying net.Socket instance for the connection.
###protocol
The subprotocol that was chosen to be spoken on this connection.
###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.
###connected
A boolean value indicating whether or not the connection is still connected. Read-only
###close
Will gracefully close the connection. A close frame will be sent to the remote peer 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.
###drop([closeReason], [reasonText])
Will send a close frame to the remote peer with the provided closeReason and reasonText and will immediately close the socket without waiting for a response. This should generally be used only in error conditions. The default closeReason 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_MESSAGE_TOO_LARGE = 1004;###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.
###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.
###ping
Sends a ping frame to the remote peer.
###pong(buffer)
Sends a pong frame to the remote peer. Pong frames must be sent in response to a received ping frame, and must mirror the payload data of the ping frame exactly. The WebSocketConnection handles this internally for you, so there should be no need to use this method.
###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.
###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 message 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()
This message is emitted when the connection has been fully closed and the socket is no longer connected.
###error
function(error)
This message is emitted when there has been a socket error. If this occurs, a close event will also be emitted.
ver WebSocketFrame = require('websocket').frame
This object represents the low level individual frame and is used to drive how the bytes are serialized onto the wire.
new WebSocketFrame();###fin Boolean
Indicates that this is either the only frame in a message, or the last frame in a fragmentation sequence.
###rsv1 Boolean
Represents the RSV1 field in the framing, which is currently not used. Setting this to true will result in a Protocol Error on the receiving peer.
###rsv2 Boolean
Represents the RSV2 field in the framing, which is currently not used. Setting this to true will result in a Protocol Error on the receiving peer.
###rsv3 Boolean
Represents the RSV3 field in the framing, which is currently not used. Setting this to true will result in a Protocol Error on the receiving peer.
###mask uint
Whether or not this frame is (or should be) masked. For outgoing frames, when connected as a client, this flag is automatically forced to true by WebSocketConnection. Outgoing frames sent from the server-side of a connection are not masked.
###opcode uint
Identifies which kind of frame this is. List of Opcodes:
0x00 - Continuation
0x01 - Text Frame
0x02 - Binary Frame
0x08 - Close Frame
0x09 - Ping Frame
0x0A - Pong Frame
###length Read-only, uint
Identifies the length of the payload data on a received frame. When sending a frame, the length will be automatically calculated from the binaryPayload object.
###binaryPayload Buffer object
The binary payload data. NOTE: Even text frames are sent with a Buffer providing the binary payload data. When sending a UTF-8 Text Frame, you must serialize your string into a Buffer object before constructing your frame, and when receiving a UTF-8 Text Frame, you must deserialize the string from the provided Buffer object. Do not read UTF-8 data from fragmented Text Frames, as it may have fragmented the data in the middle of a UTF-8 encoded character. You should buffer all fragments of a text message before attempting to decode the UTF-8 data.
var WebSocketClient = require('websocket').client
This object allows you to make client connections to a WebSocket server.
new WebSocketClient([clientConfig]);maxReceivedFrameSize - uint - Default: 1MiB
The maximum allowed received frame size in bytes. Single frame messages will also be limited to this maximum.
maxReceivedMessageSize - uint - Default: 8MiB
The maximum allowed aggregate message size (for fragmented messages) in bytes.
fragmentOutgoingMessages - Boolean - Default: true
Whether or not to fragment outgoing messages. If true, messages will be automatically fragmented into chunks of up to fragmentationThreshold bytes.
fragmentationThreshold - uint - Default: 16KiB
The maximum size of a frame in bytes before it is automatically fragmented.
assembleFragments - boolean - Default: true
If true, fragmented messages will be automatically assembled and the full message will be emitted via a message event. If false, each frame will be emitted on the WebSocketConnection object via a frame event and the application will be responsible for aggregating multiple fragmented frames. Single-frame messages will emit a message event in addition to the frame event. Most users will want to leave this set to true.
closeTimeout - uint - Default: 5000
The number of milliseconds to wait after sending a close frame for an acknowledgement to come back before giving up and just closing the socket.
###connect(requestUrl, requestedProtocols, origin)
Will establish a connection to the given requestUrl. requestedProtocols indicates a list of multiple subprotocols supported by the client. The remote server will select the best subprotocol that it supports and send that back when establishing the connection. origin is an optional field that can be used in user-agent scenarios to identify the page containing any scripting content that caused the connection to be requested. (This seems unlikely in node.. probably should leave it null most of the time.) requestUrl should be a standard websocket url, such as:
ws://www.mygreatapp.com:1234/websocketapp/
###connect
function(webSocketConnection)
Emitted upon successfully negotiating the WebSocket handshake with the remote server. webSocketConnection is an instance of WebSocketConnection that can be used to send and receive messages with the remote server.
###error
function(error)
Emitted when there is an error connecting to the remote host.
###connectFailed
function(errorDescription)
Emitted when the handshake response sent by the server is invalid.