Merge branch 'master' of git://github.com/jed/Socket.IO-node into gh-…

…pages

.gitignore

@@ -0,0 +1,8 @@
+.DS_Store
+lib-cov
+*.seed
+*.log
+*.csv
+*.dat
+*.out
+*.pid

History.md

@@ -0,0 +1,127 @@
+
+0.6.0 / 2010-11-01 
+==================
+
+* Make sure to only write to open transports (thanks JohnDav)
+* _open is still false, so destroy the connection immediately upon websocket error
+* Make sure to disconnect directly onClose if the client is not handshaked and he can't possibly reconnect
+* Make sure to end and destroy connection onDisconnect (for timeouts)
+* Added missing .listen() call to example. Fixes #80. Thanks @machee
+* Invalid transport test completed
+* Initial stab at trying to detect invalid transport responses
+* Make sure to provide a default for `log` if no log key was provided (internal)
+* Removed unnecessary file extension verification when serving the client
+* Removed unnecessary Client check upon connection
+* Added support for /socket.io/WebSocketMain.swf
+* Added test for /socket.io/WebSocketMain.swf
+* Client serving ETag testing
+* Added htmlfile transport tests
+* Added extra byte to IE iframe bytes padding
+* Invalid session id test
+* end() before destroy()ing the socket for non-WebSocket or non-valid Upgrade requests
+* Added test for non-socket.io requests
+* Simplified index.js tests
+* Moved listener tests into listener.js
+* Make sure to call .end() when listening on connection 'end' event
+* Make sure the file descriptor is destroyed on disconnection
+* Fix for websocket client tracking test
+* Inline (same port) flash socket policy request.
+* If the server is not run with root privileges, then the flashsocket
+transport will instead listen to all new connections on the main port
+for policy requests. Flash policy requests happen to both port 843 and
+the destination port:
+http://www.lightsphere.com/dev/articles/flash_socket_policy.html
+
+* [websocket test] Fix sending message to client upon connecting
+* [websocket test] Fix for connection and handshake test
+* [client files serving] Leverage end() write() call
+* [client serving] Make sure to not do a useless file lookup when file is cached
+* Finished json encoding test
+* Look for the heartbeat in the decoded message
+* Refactored websocket transports tests to match polling/multipart helpers
+* Added coverage testing to Makefile
+* Added heartbeat test to multipart
+* Added buffered messages test for multipart
+* Added assertions for `connected` property for all the tests
+* Multipart clients tracking test
+* Multipart client>server message sending test
+* Make sure to only close the client stream when the roundtrip is complete
+* Multipart connection and handshake tests:
+  - Implemented HTTP client on top of net.Stream with multipart boundary parsing for testing
+  - Test for connection / server>client message sending
+* Removed unnecessary check for this.connection (since we now access the socket through req.connection for all transports)
+* Test for `duration` parameter
+* Added `make example` to Makefile
+* Added clients tracking test for long polling
+* Added message buffering test for long polling
+* Improve this.request/this.response/this.connection
+* Add 'end' listener onConnect, applies to all transports
+* Improved error handling onConnect
+* Remove legacy `flush` calls
+* Removed unnecessary closeTimeout clearing in jsonp polling
+* Make sure to close on disconnect if _open = true
+* Clear disconnection timeout on disconnection (double check)
+* Make sure to clear closeTimeout for polling transports on close.
+* Replaced empty with null in log option
+* Comma first style for client serving tests
+* Long polling integration tests
+* Test for heartbeat message
+* Added heartbeat timeout test
+* Support for listener#log false
+* Corrected onConnect signature to support a request and a socket, or a request and a response.
+* Removed error checking for non-upgradeable sockets, since they'll be destroyed, and error handling is done onConnect
+* Added tests for websocket client tracking
+* Added tests for websocket message buffering
+* Make sure disconnect timeout is cleared on websocket re-connect
+* Updated the flash socket with error detection, and readystate detection.
+* This is needed because when a error occures we close down the connection,
+* and the stream will become unwriteable.
+* Also changed to a single write instead of multiple writes.
+* Moved error handling to onConnect to avoid messing with the http.Server global error handlers
+* Do special error handling for websocket
+* Clearing heartbeat interval upon closing the connection
+* Added error listeners, if theses errors are not correcly caught, they will leak memory.
+* This caused http://speedo.no.de/ to go up from 1mb per connection after a ECONNECTRESET message
+* Added encode=UTF-8 in jsonp-polling.js and xhr-polling.js since UTF-8 is the default encoding for http.ServerResponse.write
+* Replaced string.length with Buffer.byteLength in jsonp-polling.js, listener.js and xhr-polling.js because content-length header requires number of bytes and not the number of symbols in string
+* Fix COR headers/requests for different ports on Safari.
+* Clearing the references to request, response and connection upon disconnect.
+* Every require is blocking and requiring the sys module over and over and over again just makes no sense + it hurt performance.. Not to mention.. that it's already included.
+* Socket.IO-node now serves the client out of the box for easier implementation
+* Memory caching and ETag support for static files
+* Tests
+* Simplified demo even further thanks to new static file serving
+* Failing to pass an origin header would throw an exception and crash the server. Added some handling.
+* .connected renamed to ._open, and adopted proper `connected` (fixes #41)
+* example/client updated to latest socket.io client
+* Better checking of WebSocket connections
+* Better handling of SSL location (thanks @jdub)
+* Fix for cross-domain websocket (fixes #42)
+* Removed clients/clientsIndex and only using the index (fixes #28)
+* Fixed WebSocket location header for ws/wss (Thanks @jdub, Fixes #40)
+* Cross domain issues with xhr-polling addressed. Thanks Niko Kaiser (@nicokaiser)
+* Added origin verification for incoming data.
+* Make sure pathname is set (thanks steadicat & swarmation team)
+* Fix for accessing routes that being with the namespace but are not a connection attempt. Thanks @steadicat from swarmation
+* JSONP-polling support
+* Graceful closing of connection for invalid websocket clients
+* Make it possible to just require 'socket.io'
+* Make sure to abort the connect() method upon bad upgrade / origin verification
+* Support for automatic JSON encoding/decoding
+* Simplified chat example to take advantage of JSON encoding/decoding
+* Removed fs sync call from example
+* Better `how to use`
+* Make sure to send content-type text/plain to `ok` POST responses
+
+0.6.1 / 2010-11-08
+
+* Restored flash policy server, but with these changes:
+  - It's contingent on the listener flashPolicyServer option 
+  - It's started by default if socket.io is started with root access
+  - It correctly closes the netserver upon all the dependent http servers being closed
+  - The handler for the inline request is still there regardless. This is important in the following circumstances, and has no performance hit
+    - The port 843 is filtered
+    - Flash at some point enables us to skip 843 checking altogether
+    - Tests compatibility
+* Fixed connection timeout, noDelay and socket encoding for draft 76 (had been  accidentally moved into the `else` block)
+* Some stylistic fixes

Makefile

@@ -0,0 +1,10 @@
+test:
+	./support/expresso/bin/expresso -I lib $(TESTFLAGS) tests/*.js
+
+test-cov:
+	@TESTFLAGS=--cov $(MAKE) test
+
+example:
+	node ./example/server.js
+
+.PHONY: example

README.md

@@ -0,0 +1,227 @@
+Socket.IO Server: Sockets for the rest of us
+============================================
+
+The `Socket.IO` server provides seamless support for a variety of transports intended for realtime communication.
+
+- WebSocket 
+- WebSocket over Flash (+ XML security policy support)
+- XHR Polling
+- XHR Multipart Streaming
+- Forever Iframe
+- JSONP Polling (for cross domain)
+
+## Requirements
+
+- Node v0.1.103+
+- The [Socket.IO client](http://github.com/LearnBoost/Socket.IO), to connect from the browser
+
+## How to use
+
+To run the demo, execute the following:
+
+	git clone git://github.com/LearnBoost/Socket.IO-node.git socket.io
+	cd socket.io/example/
+	sudo node server.js
+
+and point your browser to `http://localhost:8080`. In addition to `8080`, if the transport `flashsocket` is enabled, a server will be initialized to listen for requests on port `843`.
+
+### Implementing it on your project
+
+`Socket.IO` is designed not to take over an entire port or Node `http.Server` instance. This means that if you choose to have your HTTP server listen on port `80`, `socket.io` can intercept requests directed to it, and normal requests will still be served.
+
+By default, the server will intercept requests that contain `socket.io` in the path / resource part of the URI. You can change this as shown in the available options below.
+
+On the server:
+
+	var http = require('http'), 
+			io = require('./path/to/socket.io'),
+			
+	server = http.createServer(function(req, res){
+		// your normal server code
+		res.writeHeader(200, {'Content-Type': 'text/html'});
+		res.writeBody('<h1>Hello world</h1>');
+		res.finish();
+	});
+
+	server.listen(80);
+			
+	// socket.io, I choose you
+	var socket = io.listen(server);
+
+	socket.on('connection', function(client){
+	  // new client is here!
+	  client.on('message', function(){ … })
+	  client.on('disconnect', function(){ … })
+	});
+
+On the client:
+
+	<script src="/socket.io/socket.io.js"></script>
+	<script>
+		var socket = new io.Socket();
+		socket.on('connect', function(){ … })
+		socket.on('message', function(){ … })
+		socket.on('disconnect', function(){ … })
+	</script>
+
+The [client-side](http://github.com/learnboost/socket.io) files are served automatically by `Socket.IO-node`.
+
+## Documentation
+
+### Listener
+
+	io.listen(<http.Server>, [options])
+
+Returns: a `Listener` instance
+
+Public Properties:
+
+- *server*
+
+	An instance of _process.http.Server_.
+
+- *options*
+
+	The passed-in options, combined with the defaults.
+
+- *clients*
+
+	An object of clients, indexed by session ID.
+
+Methods:
+
+- *addListener(event, λ)*
+
+	Adds a listener for the specified event. Optionally, you can pass it as an option to `io.listen`, prefixed by `on`. For example: `onClientConnect: function(){}`
+
+- *removeListener(event, λ)*	
+
+	Removes a listener from the listener array for the specified event.
+
+- *broadcast(message, [except])*
+
+	Broadcasts a message to all clients. Optionally, you can pass a single session ID or array of session IDs to avoid broadcasting to, as the second argument.
+
+Options:
+
+- *resource*
+
+		socket.io
+
+  The resource is what allows the `socket.io` server to identify incoming connections from `socket.io` clients. Make sure they're in sync.
+
+- *flashPolicyServer*
+
+		true
+		
+	Create a Flash Policy file server on port `843` (this is restricted port and you will need to have root permission). If you disable the FlashPolicy file server, Socket.IO will automatically fall back to serving the policy file inline.
+		
+
+- *transports*
+
+		['websocket', 'server-events', 'flashsocket', 'htmlfile', 'xhr-multipart', 'xhr-polling']
+		
+	A list of the accepted transports.
+
+- *transportOptions*
+
+	An object of options to pass to each transport. For example `{ websocket: { closeTimeout: 8000 }}`
+
+- *log*
+
+		ƒ(){ sys.log }
+		
+	The logging function. Defaults to outputting to `stdout` through `sys.log`
+
+Events:
+
+- *clientConnect(client)*
+
+	Fired when a client is connected. Receives the Client instance as parameter.
+
+- *clientMessage(message, client)*
+
+	Fired when a message from a client is received. Receives the message and Client instance as parameters.
+
+- *clientDisconnect(client)*
+
+	Fired when a client is disconnected. Receives the Client instance as a parameter.
+
+Important note: `this` in the event listener refers to the `Listener` instance.
+
+### Client
+
+	Client(listener, req, res)
+
+Public Properties:
+
+- *listener*
+
+	The `Listener` instance to which this client belongs.
+
+- *connected*
+
+	Whether the client is connected.
+
+- *connections*
+
+	Number of times the client has connected.
+
+Methods:
+
+- *send(message)*
+
+	Sends a message to the client.
+
+- *broadcast(message)*
+
+	Sends a message to all other clients. Equivalent to Listener::broadcast(message, client.sessionId).
+
+## Protocol
+
+One of the design goals is that you should be able to implement whatever protocol you desire without `Socket.IO` getting in the way. `Socket.IO` has a minimal, unobtrusive protocol layer, consisting of two parts:
+
+* Connection handshake
+
+	This is required to simulate a full duplex socket with transports such as XHR Polling or Server-sent Events (which is a "one-way socket"). The basic idea is that the first message received from the server will be a JSON object that contains a session ID used for further communications exchanged between the client and server. 
+
+	The concept of session also naturally benefits a full-duplex WebSocket, in the event of an accidental disconnection and a quick reconnection. Messages that the server intends to deliver to the client are cached temporarily until reconnection.
+
+	The implementation of reconnection logic (potentially with retries) is left for the user. By default, transports that are keep-alive or open all the time (like WebSocket) have a timeout of 0 if a disconnection is detected.
+
+* Message batching
+
+	Messages are buffered in order to optimize resources. In the event of the server trying to send multiple messages while a client is temporarily disconnected (eg: xhr polling), the messages are stacked and then encoded in a lightweight way, and sent to the client whenever it becomes available.
+
+Despite this extra layer, the messages are delivered unaltered to the various event listeners. You can `JSON.stringify()` objects, send XML, or even plain text.
+
+## Credits
+
+- Guillermo Rauch &lt;[email protected]&gt; ([Guille](http://github.com/guille))
+
+- Arnout Kazemier ([3rd-Eden](http://github.com/3rd-Eden))
+
+## License 
+
+(The MIT License)
+
+Copyright (c) 2010 LearnBoost &lt;[email protected]&gt;
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.