Table of Contents

• WebSockets
• Constructors
• new WebSocketServer( url [, option ] )
• new WebSocket( uri [, option ] )
• Properties
• WebSocketServer.onconnection
• WebSocketServer.onclose
• WebSocket.readyState
• WebSocket.url
• WebSocket.onmessage
• WebSocket.onopen
• WebSocket.onclose
• WebSocket.onerror
• Methods
• WebSocketServer.close()
• WebSocket.send( msg )
• WebSocket.close()

WebSockets

Hop supports server WebSockets and client WebSockets.

Server WebSockets are system objects that listen to the Hop built-in multi-threaded http server. Connection parameters are thus the same as for the http server.

Client WebSockets enable a Hop process to connect to a Hop WebSocket server or to a third party WebSocket server.

Both server and client WebSocket API are built-in in Hop.js, no need to require a module.

WebSockets clients may also be created in Hop browser code (JavaScript scripts running in a web browser). In such a case, refer to the standard WebSocket API for web browsers.

This example shows how to create WebSocketServer and WebSocket client. Once the WebSocket is established, the two parties communicate sending messages, which raise event listeners to be fired on the other end of the channel.

websocket/wsserver.js

var serv = new WebSocketServer( { path: "serv", protocol: "foo" } );

serv.onconnection = function( event ) {
   var ws = event.value;

   console.error( "connection established:", ws.socket );

   ws.onmessage = function( event ) {
      console.log( "server received [%s]", event.data );
   };

   ws.onclose = function( event ) {
      console.log( "client socket closed." );
   }
   
   ws.send( "something" );
};

websocket/wsclient.js

var port = parseInt( process.argv[ process.argv.length - 1 ] );
var ws = new WebSocket( "ws://localhost:" + port + "/hop/serv", [ "bar", "foo" ] );

console.error( "ws=", "ws://localhost:" + port + "/hop/serv" );

ws.onopen = function( event ) {
   this.send( "toto n'est pas content" );
   this.send( "tutu non plus" );
};

ws.onmessage = function( event ) {
   console.log( "client received [%s]", event.data );
};

ws.onclose = function( event ) {
   console.error( "client websocket closed." );
}

Constructors

new WebSocketServer( url [, option ] )

The argument option is either:

• a string, in which case, it specifies the path of the WebSocketServer. Note that /hop/ is prepended to the url argument.
• an object, in which case the following properties are read:
  • path: the WebSocketServer path;
  • protocol: the protocol.

new WebSocket( uri [, option ] )

The argument uri is a complete URI, prefixed with either ws:or wss: depending on whether http or https is to be used. Contrary to the server side, the /hop/prefix must be explicitely provided in the path to connect to a Hop WebSocket server (but clients may also connect to third party servers).

The argument option is either:

• a string, in which case, it specifies the protocol of the WebSocket.
• a array of strings, which are the protocols supported by the client.
• an object, in which case, the field protocol is used as a raw string describing the WebSocket protocol.

Properties

WebSocketServer.onconnection

An EventListener called whenever a WebSocketServer establishes a new connection with a remote WebSocket client. The newly created WebSocket is in the valueproperty of the event argument.

WebSocketServer.onclose

An EventListener on the closeevent called when a WebSocketServer is closed (see method WebSocketServer.close).

WebSocket.readyState

The state of the WebSocket. It can be one of the following constant

• WebSocket.CONNECTING: 0
• WebSocket.OPEN: 1
• WebSocket.CLOSING: 2
• WebSocket.CLOSED: 3

WebSocket.url

The URL of the WebSocket.

WebSocket.onmessage

An EventListener called whenever the WebSocket receives a message. The message payload is in the data property of the event.

WebSocket.onopen

An EventListener called whenever the WebSocket is open.

WebSocket.onclose

An EventListener called whenever the WebSocket is closed.

WebSocket.onerror

An EventListener called whenever an error occurs on the WebSocket.

Methods

WebSocketServer.close()

Stops the WebSocketServer service.

WebSocket.send( msg )

Send msg, a string, to the WebSocket.

WebSocket.close()

Close a WebSocket.