Recent Changes - Search:

edit SideBar

Version2 /

web-socket-client module

(redirected from VersionCurrent.WebSocketClient)

This is version 2 of webSocketClient.

The webSocketClient module supports web socket clients. 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 one class, Client. To make a connection, create an instance of Client (using new) and set up listeners and/or invoke the send() function of the client to send a message.

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. These functions specify what types are supported by a particular implementation of this module. Implementations of this module should support at least the following types:

  • 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/plain: Any text type is sent as a string encoded in UTF-8.

Module Functions

  • supportedReceiveTypes: Return an array of the types supported by the current host for the receiveType options.
  • supportedSendTypes: Return an array of the types supported by the current host for the sendType option.

Client Class

A Client is constructed (using new) by the Client function, which takes one (optional) argument, an options object, defined below. A Client instance represents a single web socket connection to a server and can send and receive messages to and from that server.

A Client object is an EventEmitter, and you can register handlers for the following events:

  • open: Emitted when the socket has been successfully opened.
  • message: Emitted with the body of the message as an argument when an incoming message arrives on the socket.
  • close: Emitted when the socket is closed.
  • error: Emitted if an an error occurs (with an error message as an argument).

The functions provided by the Client class are:

  • open(): Open the socket connection. Call this after setting up event handlers.
  • send(data): Send data over the web socket. If the socket has not yet been successfully opened, then queue data to be sent later, when the socket is opened, unless the discardMessagesBeforeOpen option is given with value true.
  • close(): Close the current connection with the server. If there is data that was passed to this.send() but has not yet been successfully sent (because the socket was not open), then those messages will be lost.

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'. For this type, the host will use JSON.stringify() to convert any JavaScript object passed to send() into a string, and for received messages, will attempt to parse the message as a JSON string.

An example usage is given below:

    var webSocket = require('@accessors-modules/web-socket-client');
    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();
[$[Get Code]]

The above code sends a message even before the socket is opened. The module implementation is expected to queue that message to be sent later when the socket is opened (unless the option discardMessagesBeforeOpen is given with value true).

The options argument to the Client constructor 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.
  • 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.
  • 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.

See Also

Remote Resources

Back to Optional JavaScript Modules

Edit - History - Print - Recent Changes - Search
Page last modified on June 07, 2017, at 08:05 PM