README

jsSocket: generic javascript socket API
  (c) 2008 Aman Gupta (tmm1)

  http://github.com/tmm1/jsSocket


WHAT IS IT

  jsSocket uses Flash's XMLSocket to expose a simple socket API to javascript


REQUIREMENTS
  
  jquery, jquery.media, jsonStringify and jsSocket.swf
  mtasc (http://mtasc.org) or haxe (http://haxe.org) to re-compile the swfs from source


FEATURES

  * multiple sockets on the same page
  * keepalive to keep connections open
  * automatic reconnect
  * status callback for custom connecting/disconnected/reconnecting UI
  * customizable logger for debugging


WHY FLASH

  * high market penetration
      (according to a meebo study, more people had flash installed than javascript enabled)
  * single TCP connection (instead of one ajax connection per outgoing packet)
  * lower bandwidth usage and latency than long-polling


CAVEATS

  * extra initial TCP connection required for security policy
  * packets must be delimited by null bytes
  * html and binary content must be base64 encoded


USAGE

  - Specify the path to jsSocket.swf
  
      jsSocket.swf = '/flash/jsSocket.swf'


  - Connect to site.com on port 1234
  
      var socket = jsSocket()
      socket.connect('site.com', 1234)
      socket.send('hello world')


  - Connect to document.location.hostname on port 443
  
      var socket = jsSocket({ port: 443 })


  - Install socket with default port and connect manually after setting data callback
  
      var socket = jsSocket({ port: 443, autoconnect: false })
      socket.onData = function(data){ alert(data) }
      socket.connect()


  - Hook into connected/disconnected/data events
  
      var socket = jsSocket({
        onOpen:  function()    { alert('connected') },
        onData:  function(data){ alert('got data: ' + data) },
        onClose: function()    { alert('disconnected') }
      })


  - Disable keepalive pings and auto-reconnect
  
      var socket = jsSocket({ keepalive: false, autoreconnect: false })
      socket.connect('site.com', 1234)
  

  - Send custom keepalive packets every minute
    
      var socket = jsSocket()
      socket.keepalive = function(){ socket.send('ping') }
  

  - Track the status of a socket connection
    
      var socket = jsSocket({ port: 443 })
      socket.onStatus = function(type, val){
        switch(type){
          case 'connecting':   // connecting to the server
            break

          case 'connected':    // connected
            break

          case 'disconnected': // disconnected
            break
        
          case 'waiting':      // waiting to reconnect in val seconds
            break

          case 'failed':       // attempted max reconnects
            break
        }
      }


  - Debug jsSocket
  
      var socket = jsSocket({ debug: true })
      socket.logger = console.log     // log to firebug
      socket.logger = function(arg){  // log to a div
        if(!$('#logger'))
          $('<div/>').attr('id', 'logger').appendTo('body')

        $('#logger').append(
          $('<p/>').text(arg.toString())
        )
      }


OTHER RESOURCES

  Alex MacCaw's Juggernaut: http://juggernaut.rubyforge.org
  jssockets (uses Flex/Flash9's RemotingSocket): http://code.google.com/p/jssockets
  XMLSocket bridge: http://www.devpro.it/xmlsocket/
  FlashSocket: http://ionelmc.wordpress.com/2008/11/29/flash-socket-bridge-with-haxe/
  socketBridge: http://matthaynes.net/blog/2008/07/17/socketbridge-flash-javascript-socket-bridge/


LICENSE

  Licensed under the Ruby License (http://www.ruby-lang.org/en/LICENSE.txt).