#Surge-client

Surge is a lightweight "framework" for SockJS, providing a Socket.io-like API on top of it, adding extra features out of the box.

##Inspiration

I wanted to build a reliable WebSocket server that i could deploy very fast and have everything i needed in matter of minutes. Having a standalone surge server, i can require the library include my socket-server ip and im good to go. Using the excellent pusher library was also a reason.

##How to use

You dont have to setup your own surge-server Surge-client connects automatically with a standalone surge server that i have already deployed. Alternatively, you can clone your own surge-server and change the ip that surge-client connects to.

<script src="surge-client.min.js"></script>
<script>
  
  var surge = new Surge(); //You can also use new Surge({host:'http://yourownserver.com:port'});
  
  var channel = surge.subscribe('room');
  
  surge.on('event', function() {});
  surge.emit('room','event',{});
  
  channel.unsubscribe();
  //or
  surge.unsubscribe('room');
  
</script>

Just copy paste the above code and it will work out of the box.

  var surge = new Surge()

will open the socket connection and configure everything you need to start trying it out.

Surge-client is built using browserify and includes SockJS library. Minified it is 70kB (including SockJS).

You should not use the default surge-server for production purposes.

###Node.JS (server-side usage)

Install the library

npm install --save surgejs-client

Example code

  var Surge = require('surgejs-client');
  var surge = new Surge();
  surge.on('event', function() {});
  surge.emit('room','event',{});
  
  var channel = surge.subscribe('room');
  surge.unsubscribe('room');

There is a plan for the future to create similar libraries for Python,PHP and Ruby servers. But if you want to built it yourself, do fork it and i will happily intergrate it and reference it here!

##Options Option | Description -------------------|-------------------------------------------------------------------------------------------------- host | Sets a new surge-server host debug | When set to true, you will see more details about what is happening on your console. Default is false authEndpoint | (Not enabled yet) Url that server will call for authorization

##API

When you call new Surge() you will get back a tiny API to interact with the socket. Calling multiple new Surge() objects will not likely work since SockJS has a limitation as to how many WebSockets it can use.

surge.on('event',callback)

Creates an event handler for this event. Callback returns data received from the socket.

surge.emit('channel','event',data={})

Channel is optional. Emits an event with data for all sockets connected to the channel (excluding self) or global (if not channel is given).

surge.broadcast('channel','event',data={})

Channel is optional. Emits an event with data for all sockets connected to the channel (including self) or global (if not channel is given).

surge.subscribe('room')

Subscribes to a particular room. Also returns a new Channel object where you can also put .on event handlers ( still in production ).

surge.unsubscribe('room')

Unsubscribe from room.

surge.disconnect()

Disconnect socket .

surge.connect()

Connect socket with server. If there is already an open connection it will close it and connect again.

surge.connection

Connection is an object containing: #####connection.state Returns the socket connection state. (connecting,disconnected,connected, attempting reconnection).

connection.rooms

Returns all rooms the socket currently exists in.

connection.inRoom(room)

Returns true if the socket exists in the room.

Channel

var channel = surge.subscribe('room');

Subscribing to a channel returns a channel object with the properties shown below

channel.room

Returns the room name

channel.state

Returns the channel connection state (initializing,connected,disconnected)

channel.type

Returns type (public,private)

channel.unsubscribe

Returns a function. Unsubscribes from the channel.

channel.emit

Returns a function. Emits to channel

channel.broadcast

Returns a function. Broadcasts to channel

Events

Event Name | Description ----------------------|----------------------------------------------------------------------------------------------- open | Gets called when the socket is connected. (Will include socket.id soon) close | Gets called when the socket is closed. surge-joined-room | Calls when you succesfully enter a room, returns the room as string. surge-left-room | Calls when you succesfully leave a room, returns the room as string.

##Features

• Its blazing fast to set something up for development purposes
• Auto-reconnecting already enabled (also reconnects to previously connected rooms)
• Smaller learning curve if you come from socket.io and you want to use some of its features heads on with the SockJS API
• Event buffering. If the socket gets disconnected all further emits will go to a buffer. Upon reconnection the events will fire with the same series that they were called
• I will be maintaining this library since i will be using it on production
• Open source! Want to change something? Fork it change it , do a pull request or don't and keep it for yourself
• Check roadmap for more!

##Build For development purposes you can install browserify, watchify and uglify and use the npm task manager to build the dependancies.

To build-watch everything for production purposes you can run :

npm run watch  

You can also build the surge-client library and minify it using

npm run build  

##Test

npm test

##Roadmap

• Authenticating connection requests using a token/secret hmac
• Add authentication endpoint option for Authenticating users on the socket
• Introduce Private - Preservance Channels after authenticating users
• Build an interface for main Surge server to register developers/apps generate keys and show usage stats for every app
• Add support for persisting users using cookie-based session
• Use redis to scale surge servers behind a HAProxy load balancer and provide a more production-ready library

##Contributions I will be maintaining this project since i will be using it in production for my apps, but if you want to help out filling the issue tracker or helping with the code, feel free to contact me or do a pull request

##Licence MIT