Skip to content
Newer
Older
100644 130 lines (101 sloc) 5.01 KB
9a30295 @theturtle32 Updating README with usage examples and a link to documentation.
authored
1 WebSocket Client & Server Implementation for Node
2 =================================================
071a49f @theturtle32 Adding README
authored
3
9a30295 @theturtle32 Updating README with usage examples and a link to documentation.
authored
4 *WARNING: This is an experimental library implementing the most recent draft of the WebSocket proposal.*
071a49f @theturtle32 Adding README
authored
5
9a30295 @theturtle32 Updating README with usage examples and a link to documentation.
authored
6 Overview
7 --------
8 This code is currently unproven. It should be considered alpha quality, and is recommended for production use, though it is used in production on worlize.com. Your mileage may vary.
9
10 This is a pure JavaScript implementation of the WebSocket Draft -07 for Node. There are some example client and server applications that implement various interoperability testing protocols in the "test" folder.
071a49f @theturtle32 Adding README
authored
11
eab09c6 @theturtle32 Updating server to implement websocket draft-07
authored
12 For a WebSocket -07 client written in Flash see my [AS3WebScocket](https://github.com/Worlize/AS3WebSocket) project.
13
14 If you're looking for the version supporting draft-06, see the draft-06 branch. It will not be maintained, as I plan to track each subsequent draft of the protocol until it's finalized, and will ultimately be supporting *only* the final draft.
b13fcbb @theturtle32 Adding notation in README about the node-bufferlist dependency.
authored
15
9a30295 @theturtle32 Updating README with usage examples and a link to documentation.
authored
16 Current Features:
17 -----------------
adf8b8f @theturtle32 Mentioning draft-07 handshake
authored
18 - Draft-07 framing and handshake
9a30295 @theturtle32 Updating README with usage examples and a link to documentation.
authored
19 - Can handle/aggregate received fragmented messages
20 - Can fragment outgoing messages
21 - Router to mount multiple applications to various path and protocol combinations
22 - Tunable settings
23 - Max Receivable Frame Size
24 - Max Aggregate ReceivedMessage Size
25 - Whether to fragment outgoing messages
26 - Fragmentation chunk size for outgoing messages
27 - Whether to automatically send ping frames for the purposes of keepalive
28 - Keep-alive ping interval
29 - Whether or not to automatically assemble received fragments (allows application to handle individual fragments directly)
30 - How long to wait after sending a close frame for acknowledgment before closing the socket.
31
32
33 Known Issues/Missing Features:
34 ------------------------------
35 - No API for user-provided protocol extensions.
36 - The 'deflate-stream' extension put forward as a proof of concept extension in the protocol draft is not implemented.
37 - Haven't tested TLS. (Perhaps this is handled automatically by attaching the WebSocket server to a https.createServer instead of http.createServer?)
38
39
40 Usage Examples
41 ==============
42
43 Server Example
44 --------------
45
46 Here's a short example showing a server that echos back anything sent to it, whether utf-8 or binary.
47
48 #!/usr/bin/env node
49 var WebSocketServer = require('../lib/WebSocketServer');
50 var http = require('http');
51
52 var server = http.createServer(function(request, response) {
53 console.log((new Date()) + " Received request for " + request.url);
54 response.writeHead(404);
55 response.end();
56 });
57 server.listen(8080, function() {
58 console.log((new Date()) + " Server is listening on port 8080");
59 });
60
61 wsServer = new WebSocketServer({
62 httpServer: server,
63 autoAcceptConnections: true
64 });
65
66 wsServer.on('connect', function(connection) {
67 console.log((new Date()) + " Connection accepted.");
68 connection.on('message', function(message) {
69 if (message.type === 'utf8') {
70 console.log("Received Message: " + message.utf8Data);
71 connection.sendUTF(message.utf8Data);
72 }
73 else if (message.type === 'binary') {
74 console.log("Received Binary Message of " + message.binaryData.length + " bytes");
75 connection.sendBytes(message.binaryData);
76 }
77 });
78 connection.on('close', function(connection) {
79 console.log((new Date()) + " Peer " + connection.remoteAddress + " disconnected.");
80 });
81 });
82
83 Client Example
84 --------------
85
86 This is a simple example client that will print out any utf-8 messages it receives on the console, and periodically sends a random number.
87
88 #!/usr/bin/env node
89 var WebSocketClient = require('../lib/WebSocketClient');
90
91 var client = new WebSocketClient();
92
93 client.on('error', function(error) {
94 console.log("Connect Error: " + error.toString());
95 });
96
97 client.on('connect', function(connection) {
98 console.log("WebSocket client connected");
99 connection.on('error', function(error) {
100 console.log("Connection Error: " + error.toString());
101 });
102 connection.on('close', function() {
103 console.log("dumb-increment-protocol Connection Closed");
104 })
105 connection.on('message', function(message) {
106 console.log("Received: '" + message.utf8Data + "'");
107 });
108
109 function sendNumber() {
110 if (connection.connected) {
111 var number = Math.round(Math.random() * 0xFFFFFF);
112 connection.sendUTF(number);
113 setTimeout(sendNumber, 1000);
114 }
115 }
116 sendNumber();
117 });
118
c369da4 @theturtle32 s/dumb-increment-protocol/echo-protocol/
authored
119 client.connect("ws://localhost:8080/", ['echo-protocol']);
9a30295 @theturtle32 Updating README with usage examples and a link to documentation.
authored
120
4d2e6e2 @theturtle32 Calling out where to find an example of using the request router.
authored
121 Request Router Example
122 ----------------------
123
124 For an example of using the request router, see `libwebsockets-test-server.js` in the `test` folder.
125
126
9a30295 @theturtle32 Updating README with usage examples and a link to documentation.
authored
127 Documentation
128 =============
129
130 For more complete documentation, see the [Documentation Wiki](https://github.com/Worlize/WebSocket-Node/wiki/Documentation).
Something went wrong with that request. Please try again.