faye-websocket 0.1.0

data/README.rdoc

@@ -0,0 +1,132 @@
+= Faye::WebSocket
+
+This is a robust, general-purpose WebSocket implementation extracted from the
+{Faye}[http://faye.jcoglan.com] project. It provides classes for easily building
+WebSocket servers and clients in Ruby. It does not provide a server itself, but
+rather makes it easy to handle WebSocket connections within an existing
+{Rack}[http://rack.rubyforge.org/] application running under
+{Thin}[http://code.macournoyer.com/thin/]. It does not provide any abstraction
+other than the standard {WebSocket API}[http://dev.w3.org/html5/websockets/].
+
+The server-side socket can process {draft-75}[http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-75],
+{draft-76}[http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76],
+{hybi-07}[http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-07]
+and later versions of the protocol. It selects protocol versions automatically,
+supports both +text+ and +binary+ messages, and transparently handles +ping+,
++pong+, +close+ and fragmented messages.
+
+
+== Accepting WebSocket connections in Rack
+
+You can handle WebSockets on the server side by listening for HTTP Upgrade
+requests, and creating a new socket for the request. This socket object exposes
+the usual WebSocket methods for receiving and sending messages. For example this
+is how you'd implement an echo server:
+
+    require 'faye/websocket'
+    require 'rack'
+    require 'eventmachine'
+    
+    app = lambda do |env|
+      if env['HTTP_UPGRADE']
+        ws = Faye::WebSocket.new(env)
+        
+        ws.onmessage = lambda do |event|
+          ws.send(event.data)
+        end
+        
+        ws.onclose = lambda do |event|
+          p [:close, event.code, event.reason]
+          ws = nil
+        end
+        
+        # Thin async response
+        [-1, {}, []]
+        
+      else
+        # Normal HTTP request
+        [200, {'Content-Type' => 'text/plain'}, ['Hello']]
+      end
+    end
+    
+    EM.run {
+      thin = Rack::Handler.get('thin')
+      thin.run(app, :Port => 9292)
+    }
+
+
+== Using the WebSocket client
+
+The client supports both the plain-text +ws+ protocol and the encrypted +wss+
+protocol, and has exactly the same interface as a socket you would use in a web
+browser. On the wire it identifies itself as hybi-08, though it's compatible
+with servers speaking later versions of the protocol, at least up to version 17.
+
+    require 'faye/websocket'
+    require 'eventmachine'
+    
+    EM.run {
+      ws = Faye::WebSocket::Client.new('ws://www.example.com/')
+      
+      ws.onopen = lambda do |event|
+        p [:open]
+        ws.send('Hello, world!')
+      end
+      
+      ws.onmessage = lambda do |event|
+        p [:message, event.data]
+      end
+      
+      ws.onclose = lambda do |event|
+        p [:close, event.code, event.reason]
+        ws = nil
+      end
+    }
+
+
+== WebSocket API
+
+The WebSocket API consists of several event handlers and a method for sending
+messages.
+
+* <b><tt>onopen</tt></b> fires when the socket connection is established. Event
+  has no attributes.
+* <b><tt>onerror</tt></b> fires when the connection attempt fails. Event has no
+  attributes.
+* <b><tt>onmessage</tt></b> fires when the socket receives a message. Event has
+  one attribute, <b><tt>data</tt></b>, which is either a +String+ (for text
+  frames) or an +Array+ of byte-sized integers (for binary frames).
+* <b><tt>onclose</tt></b> fires when either the client or the server closes the
+  connection. Event has two optional attributes, <b><tt>code</tt></b> and
+  <b><tt>reason</tt></b>, that expose the status code and message sent by the
+  peer that closed the connection.
+* <b><tt>send(message)</tt></b> accepts either a +String+ or an +Array+ of
+  byte-sized integers and sends a text or binary message over the connection to
+  the other peer.
+* <b><tt>close(code, reason)</tt></b> closes the connection, sending the given
+  status code and reason text, both of which are optional.
+
+
+== License
+
+(The MIT License)
+
+Copyright (c) 2009-2011 James Coglan
+
+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.
+

data/examples/autobahn_client.rb

@@ -0,0 +1,45 @@
+require 'rubygems'
+require File.expand_path('../../lib/faye/websocket', __FILE__)
+require 'cgi'
+
+EM.run {
+  host   = 'ws://localhost:9001'
+  agent  = "Faye (Ruby #{RUBY_VERSION})"
+  cases  = 0
+  skip   = [247,248,249,250,251,252,253,254,255,
+            256,257,258,259,260,261,262,263,264]
+  
+  socket = Faye::WebSocket::Client.new("#{host}/getCaseCount")
+  
+  socket.onmessage = lambda do |event|
+    puts "Total cases to run: #{event.data}"
+    cases = event.data.to_i
+  end
+  
+  socket.onclose = lambda do |event|
+    run_case = lambda do |n|
+      if n > cases
+        socket = Faye::WebSocket::Client.new("#{host}/updateReports?agent=#{CGI.escape agent}")
+        socket.onclose = lambda { |e| EM.stop }
+        
+      elsif skip.include?(n)
+        EM.next_tick { run_case.call(n+1) }
+        
+      else
+        puts "Running test case ##{n} ..."
+        socket = Faye::WebSocket::Client.new("#{host}/runCase?case=#{n}&agent=#{CGI.escape agent}")
+        
+        socket.onmessage = lambda do |event|
+          socket.send(event.data)
+        end
+        
+        socket.onclose = lambda do |event|
+          run_case.call(n + 1)
+        end
+      end
+    end
+    
+    run_case.call(1)
+  end
+}
+

data/examples/client.rb

@@ -0,0 +1,30 @@
+require 'rubygems'
+require File.expand_path('../../lib/faye/websocket', __FILE__)
+require 'eventmachine'
+
+port   = ARGV[0] || 7000
+secure = ARGV[1] == 'ssl'
+
+EM.run {
+  scheme = secure ? 'wss' : 'ws'
+  url    = "#{scheme}://localhost:#{port}/"
+  socket = Faye::WebSocket::Client.new(url)
+  
+  puts "Connecting to #{socket.url}"
+  
+  socket.onopen = lambda do |event|
+    p [:open]
+    socket.send("Hello, WebSocket!")
+  end
+  
+  socket.onmessage = lambda do |event|
+    p [:message, event.data]
+    # socket.close 1002, 'Going away'
+  end
+  
+  socket.onclose = lambda do |event|
+    p [:close, event.code, event.reason]
+    EM.stop
+  end
+}
+

data/examples/index.html

@@ -0,0 +1,35 @@
+<!doctype html>
+<html>
+  <head>
+    <meta http-equiv="Content-type" content="text/html; charset=utf-8">
+    <title>WebSocket test</title>
+  </head>
+  <body>
+    
+    <h1>WebSocket test</h1>
+    <ul></ul>
+    
+    <script type="text/javascript">
+      var logger = document.getElementsByTagName('ul')[0],
+          Socket = window.MozWebSocket || window.WebSocket,
+          socket = new Socket('ws://' + location.hostname + ':' + location.port + '/'),
+          index  = 0;
+      
+      socket.onopen = function() {
+        logger.innerHTML += '<li>OPEN</li>';
+        socket.send('Hello, world');
+      };
+      
+      socket.onmessage = function(event) {
+        logger.innerHTML += '<li>MESSAGE: ' + event.data + '</li>';
+        setTimeout(function() { socket.send(++index + ' ' + event.data) }, 2000);
+      };
+      
+      socket.onclose = function(event) {
+        logger.innerHTML += '<li>CLOSE: ' + event.code + ', ' + event.reason + '</li>';
+      };
+    </script>
+    
+  </body>
+</html>
+

data/examples/server.rb

@@ -0,0 +1,43 @@
+require 'rubygems'
+require File.expand_path('../../lib/faye/websocket', __FILE__)
+require 'rack'
+require 'eventmachine'
+
+port   = ARGV[0] || 7000
+secure = ARGV[1] == 'ssl'
+
+static = Rack::File.new(File.dirname(__FILE__))
+
+app = lambda do |env|
+  if env['HTTP_UPGRADE']
+    socket = Faye::WebSocket.new(env)
+    p [:open, socket.url, socket.version]
+    
+    socket.onmessage = lambda do |event|
+      socket.send(event.data)
+    end
+    
+    socket.onclose = lambda do |event|
+      p [:close, event.code, event.reason]
+      socket = nil
+    end
+    
+    [-1, {}, []]
+  else
+    static.call(env)
+  end
+end
+
+EM.run {
+  thin = Rack::Handler.get('thin')
+  thin.run(app, :Port => port) do |server|
+    if secure
+      server.ssl = true
+      server.ssl_options = {
+        :private_key_file => File.expand_path('../../spec/server.key', __FILE__),
+        :cert_chain_file  => File.expand_path('../../spec/server.crt', __FILE__)
+      }
+    end
+  end
+}
+

data/lib/faye/thin_extensions.rb

@@ -0,0 +1,75 @@
+# WebSocket extensions for Thin
+# Based on code from the Cramp project
+# http://github.com/lifo/cramp
+
+# Copyright (c) 2009-2011 Pratik Naik
+# 
+# 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.
+
+class Thin::Connection
+  def receive_data(data)
+    trace { data }
+
+    case @serving
+    when :websocket
+      callback = @request.env[Thin::Request::WEBSOCKET_RECEIVE_CALLBACK]
+      callback.call(data) if callback
+    else
+      if @request.parse(data)
+        if @request.websocket?
+          @request.env['em.connection'] = self
+          @response.persistent!
+          @response.websocket = true
+          @serving = :websocket
+        end
+
+        process
+      end
+    end
+  rescue Thin::InvalidRequest => e
+    log "!! Invalid request"
+    log_error e
+    close_connection
+  end
+end
+
+class Thin::Request
+  WEBSOCKET_RECEIVE_CALLBACK = 'websocket.receive_callback'.freeze
+  def websocket?
+    @env['HTTP_CONNECTION'] and
+    @env['HTTP_CONNECTION'].split(/\s*,\s*/).include?('Upgrade') and
+    ['WebSocket', 'websocket'].include?(@env['HTTP_UPGRADE'])
+  end
+end
+
+class Thin::Response
+  # Headers for sending Websocket upgrade
+  attr_accessor :websocket
+
+  def each
+    yield(head) unless websocket
+    if @body.is_a?(String)
+      yield @body
+    else
+      @body.each { |chunk| yield chunk }
+    end
+  end
+end
+

data/lib/faye/websocket.rb

@@ -0,0 +1,126 @@
+# API and protocol references:
+# 
+# * http://dev.w3.org/html5/websockets/
+# * http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-eventtarget
+# * http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-event
+# * http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-75
+# * http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76
+# * http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-17
+
+require 'base64'
+require 'digest/md5'
+require 'digest/sha1'
+require 'forwardable'
+require 'net/http'
+require 'uri'
+
+require 'eventmachine'
+require 'thin'
+require File.dirname(__FILE__) + '/thin_extensions'
+
+module Faye
+  class WebSocket
+    
+    root = File.expand_path('../websocket', __FILE__)
+    
+    autoload :API,             root + '/api'
+    autoload :Client,          root + '/client'
+    autoload :Draft75Parser,   root + '/draft75_parser'
+    autoload :Draft76Parser,   root + '/draft76_parser'
+    autoload :Protocol8Parser, root + '/protocol8_parser'
+    
+    # http://www.w3.org/International/questions/qa-forms-utf-8.en.php
+    UTF8_MATCH = /^([\x00-\x7F]|[\xC2-\xDF][\x80-\xBF]|\xE0[\xA0-\xBF][\x80-\xBF]|[\xE1-\xEC\xEE\xEF][\x80-\xBF]{2}|\xED[\x80-\x9F][\x80-\xBF]|\xF0[\x90-\xBF][\x80-\xBF]{2}|[\xF1-\xF3][\x80-\xBF]{3}|\xF4[\x80-\x8F][\x80-\xBF]{2})*$/
+    
+    def self.encode(string, validate_encoding = false)
+      if Array === string
+        return nil if validate_encoding and !valid_utf8?(string)
+        string = string.pack('C*')
+      end
+      return string unless string.respond_to?(:force_encoding)
+      string.force_encoding('UTF-8')
+    end
+    
+    def self.valid_utf8?(byte_array)
+      UTF8_MATCH =~ byte_array.pack('C*') ? true : false
+    end
+    
+    def self.parser(env)
+      if env['HTTP_SEC_WEBSOCKET_VERSION']
+        Protocol8Parser
+      elsif env['HTTP_SEC_WEBSOCKET_KEY1']
+        Draft76Parser
+      else
+        Draft75Parser
+      end
+    end
+    
+    extend Forwardable
+    def_delegators :@parser, :version
+    
+    attr_reader :env
+    include API
+    
+    def initialize(env)
+      @env      = env
+      @callback = @env['async.callback']
+      @stream   = Stream.new(self, @env['em.connection'])
+      @callback.call [200, {}, @stream]
+      
+      @url = determine_url
+      @ready_state = CONNECTING
+      @buffered_amount = 0
+      
+      @parser = WebSocket.parser(@env).new(self)
+      @stream.write(@parser.handshake_response)
+      
+      @ready_state = OPEN
+      
+      event = Event.new('open')
+      event.init_event('open', false, false)
+      dispatch_event(event)
+      
+      @env[Thin::Request::WEBSOCKET_RECEIVE_CALLBACK] = @parser.method(:parse)
+    end
+    
+  private
+    
+    def determine_url
+      secure = if @env.has_key?('HTTP_X_FORWARDED_PROTO')
+                 @env['HTTP_X_FORWARDED_PROTO'] == 'https'
+               else
+                 @env['HTTP_ORIGIN'] =~ /^https:/i
+               end
+      
+      scheme = secure ? 'wss:' : 'ws:'
+      "#{ scheme }//#{ @env['HTTP_HOST'] }#{ @env['REQUEST_URI'] }"
+    end
+  end
+  
+  class WebSocket::Stream
+    include EventMachine::Deferrable
+    
+    extend Forwardable
+    def_delegators :@connection, :close_connection, :close_connection_after_writing
+    
+    def initialize(web_socket, connection)
+      @web_socket = web_socket
+      @connection = connection
+    end
+    
+    def each(&callback)
+      @data_callback = callback
+    end
+    
+    def fail
+      @web_socket.close(1006, '', false)
+    end
+    
+    def write(data)
+      return unless @data_callback
+      @data_callback.call(data)
+    end
+  end
+  
+end
+