Module: webSocket

Construct an instance of a socket client that can send or receive messages to a server at the specified host and port. The returned object subclasses EventEmitter. You can register handlers for events 'open', 'message', 'close', or 'error'. The event 'open' will be emitted when the socket has been successfully opened. The event 'message' will be emitted with the body of the message as an argument when an incoming message arrives on the socket. You can invoke the send() function to send data to the server.

The type of data sent and received can be specified with the 'sendType' and 'receiveType' options. In principle, any MIME type can be specified, but the host may support only a subset of MIME types. The client and the server have to agree on the type, or the data will not get through correctly.

The default type for both sending and receiving is 'application/json'. The types supported by this implementation include at least:

• application/json: The this.send() function uses JSON.stringify() and sends the result with a UTF-8 encoding. An incoming byte stream will be parsed as JSON, and if the parsing fails, will be provided as a string interpretation of the byte stream.
• text/*: Any text type is sent as a string encoded in UTF-8.

• image/x: Where x is one of json, png, gif, and more (FIXME: which, exactly?). In this case, the data passed to this.send() is assumed to be an image, as encoded on the host, and the image will be encoded as a byte stream in the specified format before sending. A received byte stream will be decoded as an image, if possible. FIXME: What happens if decoding fails?

  The event 'close' will be emitted when the socket is closed, and 'error' if an an error occurs (with an error message as an argument). For example,

    var WebSocket = require('@accessors-modules/web-socket');
    var client = new WebSocket.Client({'host': 'localhost', 'port': 8080});
    client.send({'foo': 'bar'});
    client.on('message', function(message) {
        console.log('Received from web socket: ' + message);
    });
    client.open();
  

  The above code may send a message even before the socket is opened. This module implementation will queue that message to be sent later when the socket is opened.

  The options argument is a JSON object that can contain the following properties:

• host: The IP address or host name for the host. Defaults to 'localhost'.
• port: The port on which the host is listening. Defaults to 80.
• sslTls: Whether SSL/TLS is enabled. This defaults to false.
• receiveType: The MIME type for incoming messages, which defaults to 'application/json'.
• sendType: The MIME type for outgoing messages, which defaults to 'application/json'.
• connectTimeout: The time to wait before giving up on a connection, in milliseconds (defaults to 1000).
• numberOfRetries: The number of times to retry connecting. Defaults to 10.
• timeBetweenRetries: The time between retries, in milliseconds. Defaults to 500.
• trustAll: Whether to trust any server certificate. This defaults to false.
• trustedCACertPath: The filename for the file that stores the certificate of a certificate authority (CA) that this client will use to verify server certificates.
• discardMessagesBeforeOpen: If true, discard messages before the socket is open. Defaults to false.
• throttleFactor: The number milliseconds to stall for each item that is queued waiting to be sent. Defaults to 0.

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.

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

   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.

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.

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

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