Module: webSocketServer

Module supporting web socket servers. Web sockets differ from HTTP interactions by including a notion of a bidirectional connection called a "socket". It differs from a TCP socket in that the connection carries not just a byte stream, but a sequence of "messages," where each message can have an arbitrary number of bytes. It also differs from a TCP socket in that the connection is established through HTTP and is supported by most web browsers.

This module defines two classes, Server, and Socket. To make a connection, create an instance of Server, set up event listeners, and start the server. On another machine (or the same machine), create an instance of Client (defined in the webSocketClient module) and set up listeners and/or invoke the send() function of the client to send a message. When a client connects to the Server, the Server will create an instance of the Socket object. This object can be used to send and receive messages to and from the client.

This module also provides two utility functions that return arrays of MIME types supported for sending or receiving messages. Specifying a message type facilitates conversion between the byte streams transported over the socket and JavaScript objects that are passed to send() or emitted as a 'message' event.

Version:
  • $$Id$$
Author:
  • Hokeun Kim and Edward A. Lee
Source:

Methods

(static) Server(options)

Construct an instance of WebSocket Server. After invoking this constructor (using new), the user script should set up listeners and then invoke the start() function on this Server. This will create an HTTP server on the local host. The options argument is a JSON object containing the following optional fields:

  • hostInterface: The IP address or name of the local interface for the server to listen on. This defaults to "localhost", but if the host machine has more than one network interface, e.g. an Ethernet and WiFi interface, then you may need to specifically specify the IP address of that interface here.
  • port: The port on which to listen for connections (the default is 80, which is the default HTTP port).
  • receiveType: The MIME type for incoming messages, which defaults to 'application/json'. See the Client documentation for supported types.
  • sendType: The MIME type for outgoing messages, which defaults to 'application/json'. See the Client documentation for supported types.
  • sslTls: True to accept secure connections.
  • pfxKeyCertPassword: The password to open the file specified in pfxKeyCertPath (required only if sslTls is true).
  • pfxKeyCertPath: The path of the file storing the server's private key and certificate in PFX (in PKCS#12) format (required only if sslTls is true).

    This subclasses EventEmitter, emitting events 'listening' and 'connection'. A typical usage pattern looks like this:

     var webSocket = require('webSocketServer');
     var server = new webSocket.Server({'port':8082});
     server.on('listening', onListening);
     server.on('connection', onConnection);
     server.start();
    

    where onListening is a handler for an event that this Server emits when it is listening for connections, and onConnection is a handler for an event that this Server emits when a client requests a websocket connection and the socket has been successfully established. When the 'connection' event is emitted, it will be passed a Socket object, and the onConnection handler can register a listener for 'message' events on that Socket object, as follows:

    server.on('connection', function(socket) {
        socket.on('message', function(message) {
            console.log(message);
            socket.send('Reply message');
        });
     });
    

    The Socket object also has a close() function that allows the server to close the connection.

    FIXME: Should provide a mechanism to validate the "Origin" header during the connection establishment process on the serverside (against the expected origins) to avoid Cross-Site WebSocket Hijacking attacks.

Parameters:
Name Type Description
options

The options.

Source:

(static) Socket(serverWebSocket, helper, receiveType, sendType)

Construct (using new) a Socket object for the server side of a new connection. This is called by the socketCreated function above whenever a new connection is established at the request of a client. It should not normally be called by the JavaScript programmer. The returned Socket is an event emitter that emits 'message' events.

Parameters:
Name Type Description
serverWebSocket

The Java ServerWebSocket object.

helper

The helper in charge of this web socket.

receiveType

The MIME type for incoming messages, which defaults to 'application/json'.

sendType

The MIME type for outgoing messages, which defaults to 'application/json'.

Source:

(static) supportedReceiveTypes()

Return an array of the types supported by the current host for receiveType arguments.

Source:

(static) supportedSendTypes()

Return an array of the types supported by the current host for sendType arguments.

Source: