Socket.IO

Overview Server API Client APIRooms and NamespacesMigrating from 0.9Using multiple nodes Logging and DebuggingFAQHow to useInstallingUsing with Node http server$ npm install socket.ioHome Demos Get started Docs Blog Slack 78Server (app.js)var app = require('http').createServer(handler)var io = require('socket.io')(app);var fs = require('fs');Client (index.html)<script src="/socket.io/socket.io.js"></script><script>var socket = io('http://localhost');Using with Express 3/4Using with the Express frameworkapp.listen(80);function handler (req, res) {fs.readFile(__dirname + '/index.html', function (err, data) { if (err) {res.writeHead(500);return res.end('Error loading index.html'); }res.writeHead(200); res.end(data); });}io.on('connection', function (socket) { socket.emit('news', { hello: 'world' }); socket.on('my other event', function (data) { console.log(data); });});socket.on('news', function (data) { console.log(data);socket.emit('my other event', { my: 'data' }); });</script>Server (app.js)var app = require('express')();var server = require('http').Server(app);var io = require('socket.io')(server);server.listen(80);app.get('/', function (req, res) {res.sendfile(__dirname + '/index.html');});io.on('connection', function (socket) { socket.emit('news', { hello: 'world' });socket.on('my other event', function (data) { console.log(data); });});Client (index.html)<script src="/socket.io/socket.io.js"></script><script>var socket = io.connect('http://localhost'); socket.on('news', function (data) { console.log(data);socket.emit('my other event', { my: 'data' }); });</script>Server (app.js)Client (index.html)Sending and receiving eventsSocket.IO allows you to emit and receive custom events. Besides connect,messageanddisconnect, you canemit custom events:ServerRestricting yourself to a namespaceIf you have control over all the messages and events emitted for a particular application, using the default /namespace works. If you want to leverage 3rd-party code, or produce code to share with others, socket.io provides a way of namespacing a socket.This has the benefit of multiplexinga single connection. Instead of socket.io using twoWebSocketconnections,it’ll use one.// note, io(<port>) will create a http server for you var io = require('socket.io')(80);io.on('connection', function (socket) {io.emit('this', { will: 'be received by everyone'});socket.on('private message', function (from, msg) {console.log('I received a private message by ', from, ' saying ', msg); });socket.on('disconnect', function () { io.emit('user disconnected'); });});var app = require('express').createServer();var io = require('socket.io')(app);app.listen(80);app.get('/', function (req, res) {res.sendfile(__dirname + '/index.html');});io.on('connection', function (socket) {socket.emit('news', { hello: 'world' });socket.on('my other event', function (data) { console.log(data); });});<script src="/socket.io/socket.io.js"></script><script>var socket = io.connect('http://localhost'); socket.on('news', function (data) {console.log(data);socket.emit('my other event', { my: 'data' }); });</script>Sending volatile messagesSometimes certain messages can be dropped. Let’s say you have an app that shows realtime tweets for the keyword bieber .If a certain client is not ready to receive messages (because of network slowness or other issues, or because they’re connected through long polling and is in the middle of a request-response cycle), if they doesn’t receive ALL the tweets related to bieber your application won’t suffer.In that case, you might want to send those messages as volatile messages.Servervar io = require('socket.io')(80);io.on('connection', function (socket) { var tweets = setInterval(function () { getBieberTweet(function (tweet) {socket.volatile.emit('bieber tweet', tweet); }); }, 100);socket.on('disconnect', function () { clearInterval(tweets); });});Server (app.js)var io = require('socket.io')(80);var chat = io.of('/chat').on('connection', function (socket) { socket.emit('a message', { that: 'only' , '/chat': 'will get' });chat.emit('a message', { everyone: 'in' , '/chat': 'will get' }); });var news = io .of('/news').on('connection', function (socket) { socket.emit('item', { news: 'item' }); });Client (index.html)<script>var chat = io.connect('http://localhost/chat') , news =io.connect('http://localhost/news');chat.on('connect', function () { chat.emit('hi!'); });news.on('news', function () { news.emit('woot'); });</script>Sending and getting data (acknowledgements)Sometimes, you might want to get a callback when the client confirmed the message reception.To do this, simply pass a function as the last parameter of.sendor.emit. What’s more, when you use.emit,the acknowledgement is done by you, which means you can also pass data along:Broadcasting messagesTo broadcast, simply add a broadcast flag to emit and send method calls. Broadcasting means sending a message to everyone else except for the socket that starts it.ServerUsing it just as a cross-browser WebSocketIf you just want the WebSocket semantics, you can do that too. Simply leverage sendand listen on themessageevent:var io = require('socket.io')(80);io.on('connection', function (socket) { socket.broadcast.emit('user connected');});Server (app.js)var io = require('socket.io')(80);io.on('connection', function (socket) {socket.on('ferret', function (name, fn) { fn('woot'); });});Client (index.html)<script>var socket = io(); // TIP: io() with no args does auto-discoverysocket.on('connect', function () { // TIP: you can avoid listening on `connect` and listen on events directly too!socket.emit('ferret', 'tobi', function (data) {console.log(data); // data will be 'woot' }); });</script>Server (app.js)var io = require('socket.io')(80);Client (index.html)<script>var socket = io('http://localhost/');Home Demos Get started Docs Blog Slack78OverviewServer APIClient APIRooms and NamespacesMigrating from 0.9Using multiple nodesLogging and DebuggingFAQServer APIServerExposed by require('socket.io').Server()Creates a new Server. Works with and without new:var io = require('socket.io')();// orvar Server = require('socket.io');var io = new Server();Server#onconnection(socket:engine#Socket):ServerAdvanced use only. Creates a new socket.io client from the incoming engine.io (or compatible API) socket.Server#of(nsp:String):NamespaceInitializes and retrieves the given Namespace by its pathnameidentifier nsp.If the namespace was already initialized it returns it right away. Server#emitEmits an event to all connected clients. The following two are equivalent:var io = require('socket.io')();io.sockets.emit('an event sent to all connected clients');io.emit('an event sent to all connected clients');For other available methods, see Namespace below.Server#useSee Namespace#use below.NamespaceRepresents a pool of sockets connected under a given scope identified by a pathname (eg: /chat).By default the client always connects to /.Eventsconnection / connect. Fired upon a connection.Parameters:Socket the incoming socket.Namespace#name:StringThe namespace identifier property.Namespace#connected:ObjectHash of Socket objects that are connected to this namespace indexed by id.Namespace#use(fn:Function):NamespaceRegisters a middleware, which is a function that gets executed for every incoming Socket and receives as parameter the socket and a function to optionally defer execution to the next registered middleware.var io = require('socket.io')();e(function(socket, next){if (socket.request.headers.cookie) return next();next(new Error('Authentication error'));});Errors passed to middleware callbacks are sent as special error packets to clients.SocketA Socket is the fundamental class for interacting with browser clients. A Socket belongs to a certain Namespace (by default /)and uses an underlying Client to communicate.Socket#rooms:ArrayA list of strings identifying the rooms this socket is in.Socket#client:ClientA reference to the underlying Client object.Socket#conn:SocketA reference to the underyling Client transport connection (engine.ioHome Demos Get started Docs Blog Slack78OverviewServer APIClient APIRooms and NamespacesMigrating from 0.9Using multiple nodesLogging and DebuggingFAQClient APIIO(url:String, opts:Object):SocketExposed as the io global in window if using the standalone build (eg: /socket.io/socket.io.js or the CDN), or the result of calling require('socket.io-client').When called, it creates a new Manager for the given URL, and attemptsto reuse an existing Manager for subsequent calls, unless themultiplex option is passed with false. Passing this option is the equivalent of passing 'force new connection': true.The rest of the options are passed to the Manager constructor (see belowfor details).A Socket instance is returned for the namespace specified by the pathname in the URL, defaulting to /. For example, if the url is http://localhost/users, a transport connection will be established to http://localhost and a Socket.IO connection will be established to/users.IO#protocolSocket.io protocol revision number this client works with.IO#SocketReference to the Socket constructor.IO#ManagerReference to the Manager constructor.IO#EmitterReference to the Emitter constructor.Manager(url:String, opts:Object)A Manager represents a connection to a given Socket.IO server. One or more Socket instances are associated with the manager. The manager can be accessed through the io property of each Socket instance.The opts are also passed to engine.io upon initialization of the underlying Socket.Options:– reconnection whether to reconnect automatically (true)– reconnectionDelay how long to wait before attempting a new reconnection (1000)– reconnectionDelayMax maximum amount of time to wait between reconnections (5000). Each attempt increases the reconnection bythe amount specified by reconnectionDelay.– timeout connection timeout before a connect_errorand connect_timeout events are emitted (20000)Eventsconnect. Fired upon a successful connection.connect_error. Fired upon a connection error.Parameters:Object error objectconnect_timeout. Fired upon a connection timeout.reconnect. Fired upon a successful reconnection.Parameters:Number reconnection attempt numberreconnect_attempt. Fired upon an attempt to reconnect.reconnecting. Fired upon an attempt to reconnect.Parameters:Number reconnection attempt numberreconnect_error. Fired upon a reconnection attempt error.Parameters:Object error objectreconnect_failed. Fired when couldn’t reconnect within reconnectionAttemptsThe events above are also emitted on the individual sockets thatreconnect that depend on this Manager.Manager#reconnection(v:Boolean):ManagerSets the reconnection option, or returns it if no parametersare passed.Manager#reconnectionAttempts(v:Boolean):ManagerSets the reconnectionAttempts option, or returns it if no parametersare passed.Manager#reconnectionDelay(v:Boolean):ManagerSets the reconectionDelay option, or returns it if no parametersare passed.Manager#reconnectionDelayMax(v:Boolean):ManagerSets the reconectionDelayMax option, or returns it if no parametersare passed.Home Demos Get started Docs Blog Slack78OverviewServer APIClient APIRooms and NamespacesMigrating from 0.9Using multiple nodesLogging and DebuggingFAQNamespacesSocket.IO allows you to “namespace” your sockets, which essentially means assigning different endpoints or paths.This is a useful feature to minimize the number of resources (TCP connections) and at the same time separate concerns within your application by introducing separation between communication channels.Default namespaceWe call the default namespace / and it’s the one Socket.IO clients connect to by default, and the one the server listens to by default.This namespace is identified by io.sockets or simply io:// the following two will emit to all the sockets connected to `/`io.sockets.emit('hi', 'everyone');io.emit('hi', 'everyone'); // short formEach namespace emits a connection event that receives each Socket instance as a parameter io.on('connection', function(socket){socket.on('disconnect', function(){ });});Custom namespacesTo set up a custom namespace, you can call the of function on the server-side:var nsp = io.of('/my-namespace');nsp.on('connection', function(socket){console.log('someone connected'):});nsp.emit('hi', 'everyone!');On the client side, you tell Socket.IO client to connect to that namespace:var socket = io('/my-namespace');Important note: The namespace is an implementation detail of the Socket.IO protocol, and is not related to the actual URL of the underlying transport, which defaults to /socket.io/….RoomsWithin each namespace, you can also define arbitrary channels that sockets can join and leave.Joining and leavingYou can call join to subscribe the socket to a given channel:io.on('connection', function(socket){socket.join('some room');});And then simply use to or in (they are the same) when broadcasting or emitting:io.to('some room').emit('some event'):Home Demos Get started Docs Blog Slack77OverviewServer APIClient APIRooms and NamespacesMigrating from 0.9Using multiple nodesLogging and DebuggingFAQMigration from 0.9For most applications, the transition to 1.0 should be completely seamless and devoid of any hiccups. That said, we’ve done some work to streamline some APIs, and we have changed some internals, so this is a recommended read for most existing users.Authentication differencesSocket.io uses middleware nowYou can give a Socket.io server arbitrary functions via e() that are run when a socket is created. Check out this example:var srv = require('http').createServer();var io = require('socket.io')(srv);var run = 0;e(function(socket, next){run++; // 0 -> 1next();});e(function(socket, next) {run++; // 1 -> 2next();});var socket = require('socket.io-client')();socket.on('connect', function(){// run == 2 at this time});… so its cleaner to do auth via middleware nowThe old io.set() and io.get() methods are deprecated and only supported for backwards compatibility. Here is a translation of an old authorization example into middleware-style.io.set('authorization', function (handshakeData, callback) {// make sure the handshake data looks goodcallback(null, true); // error first, 'authorized' boolean second});vs.e(function(socket, next) {var handshakeData = socket.request;// make sure the handshake data looks good as before// if error do this:// next(new Error('not authorized');// else just call nextnext();});Namespace authorization?io.of('/namespace').use(function(socket, next) {var handshakeData = socket.request;next();});Log differencesLogging is now based on debugTo print all debug logging, set the environment variable DEBUG to *. ie: DEBUG=* node index.jsConfiguration differencesio.set is goneInstead do configuration in server initialization like this:var socket = require('socket.io')({// options go here});Options like log-level are gone. io.set('transports'), io.set('heartbeat interval'), io.set('heartbeat timeout', and io.set('resource') are still supported for backwards compatibility.Setting resource pathThe previous resource option is equivalent to the new path option, but needs a / in the beginning. For example, the following configurationvar socket = io.connect('localhost:3000', {'resource': 'path/to/socket.io';});becomesvar socket = io.connect('localhost:3000', {'path': '/path/to/socket.io';});Parser / Protocol differencesThis is only relevant for updating things like socket.io implementations in other languages, custom socket.io clients, etc.Difference 1 – packet encodingParsing is now class based and asynchronous. Instead of returning a single encoded string, encode calls callback with an array of encodings as the only argument. Each encoding should be written to the transport in order. This is more flexible and makes binary data transport work. Here’s an example:var encoding = parser.encode(packet);console.log(encoding); // fully encoded packetvs.Home Demos Get started Docs Blog Slack79OverviewServer APIClient APIRooms and NamespacesMigrating from 0.9Using multiple nodesLogging and DebuggingFAQUsing multiple nodesSticky load balancingIf you plan to distribute the load of connections among different processes or machines, you have to make sure that requests associated with a particular session id connect to the process that originated them.This is due to certain transports like XHR Polling or JSONP Polling relying on firing several requests during the lifetime of the “socket”.To illustrate why this is needed, consider the example of emitting an event to all connected clients: io.emit('hi', 'all sockets');Chances are that some of those clients might have an active bi-directional communication channel like WebSocket that we can write to immediately, but some of them might be using long-polling.If they’re using long polling, they might or might not have sent a request that we can write to. They could be “in between” those requests. In those situations, it means we have to buffer messages in the process. In order for the client to successfully claim those messages when he sends his request, the easiest way is for him to connect to be routed to that same process.An easy way to do that is by routing clients based on their originating address. An example follows using the NginX server:NginX configurationWithin the http { } section of your nginx.conf file, you can declare a upstream section with a list of Socket.IO process you want to balance load between:upstream io_nodes {ip_hash;server 127.0.0.1:6001;server 127.0.0.1:6002;server 127.0.0.1:6003;server 127.0.0.1:6004;}Notice the ip_hash instruction that indicates the connections will be sticky.In the same http { } section, you can declare a server { } that points to this upstream. In order for NginX to support and forward the WebSocket protocol, we explicitly pass along the required Upgrade headers:server {listen 3000;server_name ;location / {proxy_set_header Upgrade $http_upgrade;proxy_set_header Connection "upgrade";proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;proxy_set_header Host $host;proxy_http_version 1.1;proxy_pass http://io_nodes;}}Make sure you also configure worker_processes in the topmost level to indicate how many workers NginX should use. You might also want to look into tweaking the worker_connections setting within the events { } block.Using Node.JS Cluster。