An intro to Socket.io

Recently I've been playing around with Socket.io, which, according to the site, enables real-time bidirectional event-based communication. Damn, that's some sexy copy.

Basically you can use it as a real-time server, and one of the things that makes it so interesting is that it works on pretty much every platform, browser, or device. I thought I'd write an intro on the subject as I found their documentation to be lacking in some cases and confusing in others; I frequently found myself with questions that I only answered through trial-and-error and reading the source code.

And you should never have to read the source code.

TypeScript!

I'm using TypeScript, so one of the first things I did was try and hook myself up with some definition files so I could get some code completion. I found the excellent DefinitelyTyped project and related tsd, or TypeScript Definition manager.

Unfortunately, after scratching my head for a day or two, I finally realised that the d.ts files were for an old version. Sadface.

So I learned how to create TypeScript definition files, and went through the code and created new definitions for the latest version (1.3.5 as of time of writing). If the pull request hasn't been accepted yet, then you can find them at the bottom of this post.

They're even commented to boot.

AND I went out of my way to describe the options object, which nobody apparently does, but blow trawling through documentation and READMEs for a lark. If it's not code-completed, it doesn't exist.

The setup

For the setup, I worked from the Chat example on the Socket.io website, with the exception that I didn't use Express (on a side node, Express is great and all, for beginners, one framework at a time, please). You should be able to follow that example in order to get setup. To install Socket.io (locally), just use:

npm install socket.io

Like in my tutorial for Using Phaser with Visual Studio Code I'm not using Express, I'm using node-static (as all it does is serve files from whatever directory you throw at it, so it's a perfect light-weight solution). If you want to use that, then install via:

npm install node-static

Then set up your app.js file like this:

import nodeStatic 	= require( 'node-static' );
import http			= require( 'http' );
import socketIO		= require( 'socket.io' );

// create our file server config
var file = new nodeStatic.Server( 'bin', { // bin is the folder containing our html, etc
	cache:0,	// don't cache
	gzip:true	// gzip our assets
});

// create our server
var httpServer = http.createServer( function( request, response ) {
	request.addListener( 'end', function() {
		file.serve( request, response );
	});
	request.resume();
}).listen( 4000 );

That's it. From this point out, it's all Socket.io. Note that when we call http.createServer(), we save the returned Server as our httpServer var; we'll need that later when binding Socket.io.

The basics

First of all: connecting. On the server, setup Socket.io like this:

var sio = socketIO();
sio.serveClient( true ); // the server will serve the client js file
sio.attach( httpServer );

// listen for a connection
sio.on( 'connection', function( socket ){
	
	console.log( 'User ' + socket.id + ' connected' );
});

To explain a bit:

• var sio = socketIO() - here we're just creating our Socket.io server using the socketIO import above (NOTE: if you're not using TypeScript, then your import is in the form var socketIO = require('socket.io');)
• sio.serveClient( true ) - here we're telling the server to serve any requests for the socket.io-client.js file. You can serve it yourself if you wish, but this is pretty handy
• sio.attach( httpServer ) - here we're attaching Socket.io to the httpServer instance created above via http.createServer()
• sio.on( 'connection', function( socket ){... - this is called every time a client connects. In the callback function is where you'd add all your event listeners to the socket etc.

On the client, you embed the client side code via:

<script src="/socket.io/socket.io.js"></script>

That particular path is if you're using sio.serveClient( true ). Otherwise, if you're serving it yourself, replace it with the right path. To connect to our server, it's simply:

var clientSocket = io();

Start your server (node app.js), go to http://localhost:4000 in your browser, and you should see something like

User 8fyIQvC4HUYEpZeDAAAA connected

in your console. Eassssssy.

Namespaces and rooms

A quick note on namespaces and rooms and what the difference between the two is. By default, when you call io() on the client to connect, what you're actually calling is io( 'http://localhost:4000/' ), as by default, it will take the host and port of the current page, and connect to the default namespace, which is /. If you wanted to connect to a namespace called 'foo', then you'd have to call io( 'http://localhost:4000/foo' ).

So what's a namespace?

It's a way of separating your code. It's one socket to a namespace, so if you called:

var news = io( 'http://localhost:4000/news' );
var chat = io( 'http://localhost:4000/chat' );

while it might use the same physical TCP connection, they're two separate objects - news can't send messages to /chat and vice-versa.

The main namespace, /, is created by default, and all clients join it, even if they connect to another namespace.

On the server, when a namespace emits an event, all sockets connected to the namespace receive it.

After that, we have rooms. Rooms are essentially grouping of sockets, and let you send messages to a subgroup of a namespace. You only need to know the name of a room to send a message to it. Unlike with namespaces, sockets can join as many rooms as they want.

Think of it like this: the Socket.io server is your game website (e.g. all-poker.com), namespaces are each game (e.g. /texas, /omaha), and rooms are private rooms within each game (e.g. table1, table2, etc).

The differences in list form:

• Namespaces are joined when you create the socket, rooms are joined as you want, but you need to build your own events to call join() and leave()
• One socket per namespace, but one socket can be in multiple rooms
• Sockets can leave rooms as they please, but to leave the namespace, they need to disconnect
• Communication can happen between rooms, but not between namespaces (there are work-arounds if you keep references on the server)

Or in picture form:

Sending a message to the client

To send a message to the client, we call emit() on the socket, passing the event name, and whatever data we want to send:

socket.emit( 'greetings', 'Hello from the server!', socket.id );

Then on the client, we add a listener for the 'greetings' event:

clientSocket.on( 'greetings', function( message, id ) {
	console.log( 'Got a message from the server: "' + message + "', my ID is: " + id );
});

Note that we're sending the socket.id to the client with the emit() call. We could have also called clientSocket.id, but we can use this technique to send the IDs of other sockets, which will become useful later. The id is a auto-generated ID set when the socket connects. It'll be different everytime, so there's no point storing it.

Also note that the only parameter that's actually required is the event name, in this case 'greetings'. Anything after that is sent to the client as parameters for the callback - with one exception: if the last argument is a function, then it'll be used as an ack - called when receipt of the message is acknowledged. This is a bit more advanced, so for the minute, we don't care.

Sending a message to the server

Sending a message to the server is exactly the same. On the client:

clientSocket.emit( 'message', 'Hello from the client' );

While on the server, we need to add any listeners to the socket that we get during the 'connection' event:

// listen for a connection
sio.on( 'connection', function( socket ){

	console.log( 'User ' + socket.id + ' connected' );
	
	// listen for the 'message' event
	socket.on( 'message', function( msg ){
		
		console.log( 'User ' + this.id + ' sent message "' + msg + '"' );
	});
});

Note that in the socket callback, you can use this to reference the socket (or socket as it'll be bound).

This is about the height of what you need to do on the client. Everything after this (sending messages to different people etc) happens on the server.

Sending a message to everyone in the namespace

To send a message to everyone, instead of calling socket.emit(), which only sends a message to that socket, we get the namespace itself to send the event.

In this example, we're using the sio Server object, created when we created Socket.io on the server.

socket.on( 'tellEveryone', function( msg ){

	sio.emit( 'heyEveryone', msg, socket.id ); // pass the socket.id so other client know who it's from
});

The sio.emit() method here is actually a helper function that gets the default namespace (/) and calls emit() on that. The following 3 calls all do the same thing:

sio.emit( 'heyEveryone', msg, socket.id );
sio.sockets.emit( 'heyEveryone', msg, socket.id ); // sio.sockets is a reference to the main "/" namespace
sio.of( '/' ).emit( 'heyEveryone', msg, socket.id ); // of( '/' ) is how we reference a namespace, in this case the main "/" one

Notice that last of( '/' ) call? That's how we reference other namespaces. Remember how I said sockets in one namespace couldn't send messages to sockets in other namespaces? This is how you get around that:

socket.on( 'tellNamespace', function( msg, namespaceName ){

	sio.of( namespaceName ).emit( 'heyEveryone', msg, socket.id ); 	// NOTE: namespace will be created if it doesn't exist
});

Sending a message to everyone in a room

To send a message to a room, you need to know it's name. You don't actually need to have joined the room to send a message to it, but you do if you want to receive messages from that room.

socket.on( 'tellRoom', function( msg, roomName ) {

	socket.to( roomName ).emit( 'heyThere', msg, socket.id ); // NOTE: room will be created if it doesn't exist
});

You can also use in( roomName ) instead of to() if you wish.

You can also send to multiple rooms by chaining the to() calls:

socket.on( 'tellRooms', function( msg, room1Name, room2Name ){
	
	socket.to( room1Name ).to( room2Name ).emit( 'heyThere', msg, socket.id );
});

Note that on the client, if they've joined multiple rooms, when they get a message, they won't actually know which room (if any) sent it, so it's generally a good idea to pass the room name as one of the parameters.

Sending a message to everyone except you

The socket has a broadcast flag, that when used will send the event to everyone in the namespace/room except for yourself. For a namespace:

socket.on( 'broadcastMsg', function( msg ) {

	socket.broadcast.emit( 'broadcastFrom', msg, socket.id );
});

or for a room:

socket.on( 'broadcastMsg', function( msg, roomName ) {

	socket.to( roomName ).broadcast.emit( 'broadcastFrom', msg, socket.id );
});

Sending a message to another user

To send a message to another user, we can go about it two ways: we can get the socket of the other user from the connected dictionary on our namespace and call emit() on it:

socket.on( 'sendToUser', function( msg, userID ){
	
	// try and get the socket from our connected list
	var otherSocket = sio.sockets.connected[userID]; // NOTE: sockets is the default "/" namespace
	if( otherSocket )
		otherSocket.emit( 'messageFromUser', msg, socket.id );
});

But remember when I said it's a good idea for the client to know the IDs of other clients? This is because when a socket connects, one of the things that it does it join a room with the same name as its ID. So to send a message to a client, we can use the same logic as sending a message to a room:

socket.on( 'sendToUser', function( msg, userID ){

	socket.to( userID ).emit( 'messageFromUser', msg, socket.id );
});

Technically this means that if we join() this room, we'd be privy to all the private messages sent to this user, which opens up all sorts of interesting possibilities.

Getting the IDs of connected users

If you want to send a list of all the socket IDs in a particular namespace, you can go through the connected dictionary on the namespace:

var sids = keys( sio.sockets.connected ); // sockets = default "/" namespace

To send all the IDs for a particular room, you need to go through the adapter property on the namespace:

var socketsInRoom 	= sio.sockets.adapter.rooms[roomName]; // sockets = default "/" namespace
var sids 			= ( socketsInRoom ) ? keys( socketsInRoom ) : []

Nicknames

To enable nicknames, you simply need to keep a dictionary of socket ids => nicknames on the server. Then you can either do two things:

• Instead of sending the ID to the client, you send the nickname instead. Although this means that you need a way to convert back to the socket ID if you want to send one player to send a message to another, and nicknames generally aren't unique
• Send the client the socket ID/nickname dictionary, and it's up to them to keep it up-to-date and display the right name. A bit more awkward, but more flexible as well.

Fin

So there you have it! You should be set up for firing messages left and right. If there's another scenario you want covered, leave a comment, and I'll add it in.

In the meantime, check out Socket.io and download the v1.3.5 TypeScript definition files below.