Skip to content
Newer
Older
100644 147 lines (112 sloc) 5.58 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 --------
519f5ba @theturtle32 Oops.. it's *not* recommended for production use yet! Heh.
authored
8 This code is currently unproven. It should be considered alpha quality, and is not recommended for production use, though it is used in production on worlize.com. Your mileage may vary.
9a30295 @theturtle32 Updating README with usage examples and a link to documentation.
authored
9
c709ab9 @theturtle32 Incrementing protocol version number.
authored
10 This is a pure JavaScript implementation of the WebSocket Draft -09 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
c709ab9 @theturtle32 Incrementing protocol version number.
authored
12 For a WebSocket -09 client written in Flash see my [AS3WebScocket](https://github.com/Worlize/AS3WebSocket) project.
eab09c6 @theturtle32 Updating server to implement websocket draft-07
authored
13
c709ab9 @theturtle32 Incrementing protocol version number.
authored
14 *There will not be a draft-08 implementation, as the -08 specification was only out for a week before being superseded by -09.*
15
16 If you're looking for the version supporting draft-07 or draft-06, see the draft-07 or draft-06 branches. 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
17
b3f4965 @theturtle32 Fixing a couple minor issues reported by Patrick McManus:
authored
18 **Tested against Node version 0.4.7.** It may work in earlier versions but I haven't tried it. YMMV.
19
00ac01d @theturtle32 Adding installation instructions to README.
authored
20 Installation
21 ------------
22 In your project root:
23
24 $ npm install websocket
25
26 Then in your code:
27
28 var WebSocketServer = require('websocket').server;
29 var WebSocketClient = require('websocket').client;
30 var WebSocketFrame = require('websocket').frame;
31 var WebSocketRouter = require('websocket').router;
32
9a30295 @theturtle32 Updating README with usage examples and a link to documentation.
authored
33 Current Features:
34 -----------------
c709ab9 @theturtle32 Incrementing protocol version number.
authored
35 - Draft-09 framing and handshake
9a30295 @theturtle32 Updating README with usage examples and a link to documentation.
authored
36 - Can handle/aggregate received fragmented messages
37 - Can fragment outgoing messages
38 - Router to mount multiple applications to various path and protocol combinations
39 - Tunable settings
40 - Max Receivable Frame Size
41 - Max Aggregate ReceivedMessage Size
42 - Whether to fragment outgoing messages
43 - Fragmentation chunk size for outgoing messages
44 - Whether to automatically send ping frames for the purposes of keepalive
45 - Keep-alive ping interval
46 - Whether or not to automatically assemble received fragments (allows application to handle individual fragments directly)
47 - How long to wait after sending a close frame for acknowledgment before closing the socket.
48
49
50 Known Issues/Missing Features:
51 ------------------------------
52 - No API for user-provided protocol extensions.
53 - The 'deflate-stream' extension put forward as a proof of concept extension in the protocol draft is not implemented.
54 - Haven't tested TLS. (Perhaps this is handled automatically by attaching the WebSocket server to a https.createServer instead of http.createServer?)
55
56
57 Usage Examples
58 ==============
59
60 Server Example
61 --------------
62
63 Here's a short example showing a server that echos back anything sent to it, whether utf-8 or binary.
64
65 #!/usr/bin/env node
66 var WebSocketServer = require('../lib/WebSocketServer');
67 var http = require('http');
68
69 var server = http.createServer(function(request, response) {
70 console.log((new Date()) + " Received request for " + request.url);
71 response.writeHead(404);
72 response.end();
73 });
74 server.listen(8080, function() {
75 console.log((new Date()) + " Server is listening on port 8080");
76 });
77
78 wsServer = new WebSocketServer({
79 httpServer: server,
80 autoAcceptConnections: true
81 });
82
83 wsServer.on('connect', function(connection) {
84 console.log((new Date()) + " Connection accepted.");
85 connection.on('message', function(message) {
86 if (message.type === 'utf8') {
87 console.log("Received Message: " + message.utf8Data);
88 connection.sendUTF(message.utf8Data);
89 }
90 else if (message.type === 'binary') {
91 console.log("Received Binary Message of " + message.binaryData.length + " bytes");
92 connection.sendBytes(message.binaryData);
93 }
94 });
95 connection.on('close', function(connection) {
96 console.log((new Date()) + " Peer " + connection.remoteAddress + " disconnected.");
97 });
98 });
99
100 Client Example
101 --------------
102
103 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.
104
105 #!/usr/bin/env node
106 var WebSocketClient = require('../lib/WebSocketClient');
107
108 var client = new WebSocketClient();
109
110 client.on('error', function(error) {
111 console.log("Connect Error: " + error.toString());
112 });
113
114 client.on('connect', function(connection) {
115 console.log("WebSocket client connected");
116 connection.on('error', function(error) {
117 console.log("Connection Error: " + error.toString());
118 });
119 connection.on('close', function() {
120 console.log("dumb-increment-protocol Connection Closed");
121 })
122 connection.on('message', function(message) {
123 console.log("Received: '" + message.utf8Data + "'");
124 });
125
126 function sendNumber() {
127 if (connection.connected) {
128 var number = Math.round(Math.random() * 0xFFFFFF);
129 connection.sendUTF(number);
130 setTimeout(sendNumber, 1000);
131 }
132 }
133 sendNumber();
134 });
135
c369da4 @theturtle32 s/dumb-increment-protocol/echo-protocol/
authored
136 client.connect("ws://localhost:8080/", ['echo-protocol']);
9a30295 @theturtle32 Updating README with usage examples and a link to documentation.
authored
137
4d2e6e2 @theturtle32 Calling out where to find an example of using the request router.
authored
138 Request Router Example
139 ----------------------
140
141 For an example of using the request router, see `libwebsockets-test-server.js` in the `test` folder.
142
143
9a30295 @theturtle32 Updating README with usage examples and a link to documentation.
authored
144 Documentation
145 =============
146
147 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.