websocket-eventmachine-server 1.0.0 → 1.0.1

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.0.1
+
+- Extract most functionality to websocket-eventmachine-base gem to reuse with client
+
 ## 1.0.0
 
 - initial release

data/README.md

@@ -2,11 +2,12 @@
 
 WebSocket-EventMachine-Server is Ruby WebSocket server based on EventMachine.
 
-## Why another WebSocket server?
+- [Autobahn tests](http://imanel.github.com/websocket-ruby/autobahn/server)
+- [Docs](http://rdoc.info/github/imanel/websocket-eventmachine-server/master/frames)
 
-There are multiple Ruby WebSocket servers, each with different quirks and errors. Most commonly used em-websocket is unfortunately slow and have multiple bugs(see Autobahn tests below). This library was created to fix most of them.
+## Why another WebSocket server?
 
-[Autobahn tests](http://imanel.github.com/websocket-ruby/autobahn/server)
+There are multiple Ruby WebSocket servers, each with different quirks and errors. Most commonly used em-websocket is unfortunately slow and have multiple bugs(see Autobahn tests above). This library was created to fix most of them.
 
 ## Installation
 
@@ -23,63 +24,191 @@ gem 'websocket-eventmachine-server'
 ## Simple server example
 
 ```ruby
-EventMachine.run {
+EM.run do
 
-    WebSocket::EventMachine::Server.start(:host => "0.0.0.0", :port => 8080) do |ws|
-        ws.onopen {
-          puts "WebSocket connection open"
+  WebSocket::EventMachine::Server.start(:host => "0.0.0.0", :port => 8080) do |ws|
+    ws.onopen do
+      puts "Client connected"
+    end
 
-          # publish message to the client
-          ws.send "Hello Client"
-        }
+    ws.onmessage do |msg, type|
+      puts "Received message: #{msg}"
+      ws.send msg, :type => type
+    end
 
-        ws.onclose { puts "Connection closed" }
-        ws.onmessage { |msg|
-          puts "Recieved message: #{msg}"
-          ws.send "Pong: #{msg}"
-        }
+    ws.onclose do
+      puts "Client disconnected"
     end
-}
+  end
+
+end
+```
+
+## Options
+
+Following options can be passed to WebSocket::EventMachine::Server initializer:
+
+- `[String] :host` - IP on which server should accept connections. '0.0.0.0' means all.
+- `[Integer] :port` - Port on which server should accept connections.
+- `[Boolean] :secure` - Enable secure WSS protocol. This will enable both SSL encryption and using WSS url and require `tls_options` key.
+- `[Boolean] :secure_proxy` - Enable secure WSS protocol over proxy. This will enable only using WSS url and assume that SSL encryption is handled by some kind proxy(like [Stunnel](http://www.stunnel.org/))
+- `[Hash] :tls_options` - Options for SSL(according to [EventMachine start_tls method](http://eventmachine.rubyforge.org/EventMachine/Connection.html#start_tls-instance_method))
+  - `[String] :private_key_file` - URL to private key file
+  - `[String] :cert_chain_file` - URL to cert chain file
+
+## Methods
+
+Following methods are available for WebSocket::EventMachine::Server object:
+
+### onopen
+
+Called after client is connected.
+
+Example:
+
+```ruby
+ws.onopen do
+  puts "Client connected"
+end
+```
+
+### onclose
+
+Called after client closed connection.
+
+Example:
+
+```ruby
+ws.onclose do
+  puts "Client disconnected"
+end
+```
+
+### onmessage
+
+Called when server receive message.
+
+Parameters:
+
+- `[String] message` - content of message
+- `[Symbol] type` - type is type of message(:text or :binary)
+
+Example:
+
+```ruby
+ws.onmessage do |msg, type|
+  puts "Received message: #{msg} or type: #{type}"
+end
+```
+
+### onerror
+
+Called when server discovers error.
+
+Parameters:
+
+- `[String] error` - error reason.
+
+Example:
+
+```ruby
+ws.onerror do |error|
+  puts "Error occured: #{error}"
+end
 ```
 
-## Secure server
+### onping
+
+Called when server receive ping request. Pong request is sent automatically.
 
-It is possible to accept secure wss:// connections by passing :secure => true when opening the connection. Safari 5 does not currently support prompting on untrusted SSL certificates therefore using signed certificates is highly recommended. Pass a :tls_options hash containing keys as described in http://eventmachine.rubyforge.org/EventMachine/Connection.html#M000296
+Parameters:
 
-For example,
+- `[String] message` - message for ping request.
+
+Example:
 
 ```ruby
-WebSocket::EventMachine::Server.start({
-    :host => "0.0.0.0",
-    :port => 443,
-    :secure => true,
-    :tls_options => {
-      :private_key_file => "/private/key",
-      :cert_chain_file => "/ssl/certificate"
-    }
-}) do |ws|
-...
+ws.onping do |message|
+  puts "Ping received: #{message}"
 end
 ```
 
-## Running behind an SSL Proxy/Terminator, like Stunnel
+### onpong
+
+Called when server receive pong response.
 
-The :secure_proxy => true option makes it possible to run correctly when behind a secure SSL proxy/terminator like [Stunnel](http://www.stunnel.org/). When setting :secure_proxy => true, any reponse from the em-websocket which contains the websocket url will use the wss:// url scheme. None of the traffic is encrypted.
+Parameters:
 
-This option is necessary when using websockets with an SSL proxy/terminator on Safari 5.1.x or earlier, and also on Safari in iOS 5.x and earlier. Most versions of Chrome, Safari 5.2, and Safari in iOS 6 do not appear to have this problem.
+- `[String] message` - message for pong response.
 
-For example,
+Example:
 
 ```ruby
-WebSocket::EventMachine::Server.start({
-    :host => "0.0.0.0",
-    :port => 8080,
-    :secure_proxy => true
-}) do |ws|
-...
+ws.onpong do |message|
+  puts "Pong received: #{message}"
 end
 ```
 
+### send
+
+Sends message to client.
+
+Parameters:
+
+- `[String] message` - message that should be sent to client
+- `[Hash] params` - params for message(optional)
+  - `[Symbol] :type` - type of message. Valid values are :text, :binary(default is :text)
+
+Example:
+
+```ruby
+ws.send "Hello Client!"
+ws.send "binary data", :type => :binary
+```
+
+### close
+
+Closes connection and optionally send close frame to client.
+
+Parameters:
+
+- `[Integer] code` - code of closing, according to WebSocket specification(optional)
+- `[String] data` - data to send in closing frame(optional)
+
+Example:
+
+```ruby
+ws.close
+```
+
+### ping
+
+Sends ping request.
+
+Parameters:
+
+- `[String] data` - data to send in ping request(optional)
+
+Example:
+
+```ruby
+ws.ping 'Hi'
+```
+
+### pong
+
+Sends pong request. Usually there should be no need to send this request, as pong responses are sent automatically by server.
+
+Parameters:
+
+- `[String] data` - data to send in pong request(optional)
+
+Example:
+
+``` ruby
+ws.pong 'Hello'
+```
+
 ## Migrating from EM-WebSocket
 
 This library is compatible with EM-WebSocket, so only thing you need to change is running server - you need to change from EM-WebSocket to WebSocket::EventMachine::Server in your application and everything will be working.

data/lib/websocket/eventmachine/server.rb

@@ -1,5 +1,4 @@
-require 'websocket'
-require 'eventmachine'
+require 'websocket-eventmachine-base'
 
 module WebSocket
   module EventMachine
@@ -12,7 +11,7 @@ module WebSocket
     #     ws.onclose   { puts "WebSocket closed" }
     #     ws.onerror   { |e| puts "Error: #{e}" }
     #   end
-    class Server < ::EventMachine::Connection
+    class Server < Base
 
       ###########
       ### API ###
@@ -41,188 +40,86 @@ module WebSocket
         @tls_options = args[:tls_options] || {}
       end
 
+      ############################
+      ### EventMachine methods ###
+      ############################
+
+      # Eventmachine internal
+      # @private
+      def post_init
+        @state = :connecting
+        @handshake = WebSocket::Handshake::Server.new(:secure => @secure_proxy)
+        start_tls(@tls_options) if @secure
+      end
+
+      #######################
+      ### Private methods ###
+      #######################
+
+      private
+
+      def incoming_frame
+        WebSocket::Frame::Incoming::Server
+      end
+
+      def outgoing_frame
+        WebSocket::Frame::Outgoing::Server
+      end
+
+      public
+
+      #########################
+      ### Inherited methods ###
+      #########################
+
       # Called when connection is opened.
       # No parameters are passed to block
-      def onopen(&blk);     @onopen = blk;    end
+      def onopen(&blk); super; end
 
       # Called when connection is closed.
       # No parameters are passed to block
-      def onclose(&blk);    @onclose = blk;   end
+      def onclose(&blk); super; end
 
       # Called when error occurs.
       # One parameter passed to block:
       #   error - string with error message
-      def onerror(&blk);    @onerror = blk;   end
+      def onerror(&blk); super; end
 
-      # Called when message is received from server.
+      # Called when message is received.
       # Two parameters passed to block:
-      #   message - string with message sent to server
+      #   message - string with received message
       #   type - type of message. Valid values are :text and :binary
-      def onmessage(&blk);  @onmessage = blk; end
+      def onmessage(&blk); super; end
 
-      # Called when ping message is received from server.
+      # Called when ping message is received
       # One parameter passed to block:
       #   message - string with ping message
-      def onping(&blk);     @onping = blk;    end
+      def onping(&blk); super; end
 
-      # Called when pond message is received from server.
+      # Called when pond message is received
       # One parameter passed to block:
       #   message - string with pong message
-      def onpong(&blk);     @onpong = blk;    end
+      def onpong(&blk); super; end
 
-      # Send data to client
+      # Send data
       # @param data [String] Data to send
       # @param args [Hash] Arguments for send
       # @option args [String] :type Type of frame to send - available types are "text", "binary", "ping", "pong" and "close"
       # @option args [Integer] :code Code for close frame
       # @return [Boolean] true if data was send, otherwise call on_error if needed
-      def send(data, args = {})
-        type = args[:type] || :text
-        unless type == :plain
-          frame = WebSocket::Frame::Outgoing::Server.new args.merge(:version => @handshake.version, :data => data)
-          if !frame.supported?
-            trigger_onerror("Frame type '#{type}' is not supported in protocol version #{@handshake.version}")
-            return false
-          elsif !frame.require_sending?
-            return false
-          end
-          data = frame.to_s
-        end
-        debug "Sending raw: ", data
-        send_data(data)
-        true
-      end
+      def send(data, args = {}); super; end
 
       # Close connection
-      # @return [Boolean] true if connection is closed immediately, false if waiting for server to close connection
-      def close(code = 1000, data = nil)
-        if @state == :open
-          @state = :closing
-          return false if send(data, :type => :close, :code => code)
-        else
-          send(data, :type => :close) if @state == :closing
-          @state = :closed
-        end
-        close_connection_after_writing
-        true
-      end
+      # @return [Boolean] true if connection is closed immediately, false if waiting for other side to close connection
+      def close(code = 1000, data = nil); super; end
 
-      # Send ping message to client
+      # Send ping message
       # @return [Boolean] false if protocol version is not supporting ping requests
-      def ping(data = '')
-        send(data, :type => :ping)
-      end
+      def ping(data = ''); super; end
 
-      # Send pong message to client
+      # Send pong message
       # @return [Boolean] false if protocol version is not supporting pong requests
-      def pong(data = '')
-        send(data, :type => :pong)
-      end
-
-      ############################
-      ### EventMachine methods ###
-      ############################
-
-      # Eventmachine internal
-      # @private
-      def post_init
-        @state = :connecting
-        @handshake = WebSocket::Handshake::Server.new(:secure => @secure_proxy)
-        start_tls(@tls_options) if @secure
-      end
-
-      # Eventmachine internal
-      # @private
-      def receive_data(data)
-        debug "Received raw: ", data
-        case @state
-        when :connecting then handle_connecting(data)
-        when :open then handle_open(data)
-        when :closing then handle_closing(data)
-        end
-      end
-
-      # Eventmachine internal
-      # @private
-      def unbind
-        unless @state == :closed
-          @state = :closed
-          close
-          trigger_onclose('')
-        end
-      end
-
-      #######################
-      ### Private methods ###
-      #######################
-
-      private
-
-      ['onopen'].each do |m|
-        define_method "trigger_#{m}" do
-          callback = instance_variable_get("@#{m}")
-          callback.call if callback
-        end
-      end
-
-      ['onerror', 'onping', 'onpong', 'onclose'].each do |m|
-        define_method "trigger_#{m}" do |data|
-          callback = instance_variable_get("@#{m}")
-          callback.call(data) if callback
-        end
-      end
-
-      def trigger_onmessage(data, type)
-        @onmessage.call(data, type) if @onmessage
-      end
-
-      def handle_connecting(data)
-        @handshake << data
-        return unless @handshake.finished?
-        if @handshake.valid?
-          send(@handshake.to_s, :type => :plain) if @handshake.should_respond?
-          @frame = WebSocket::Frame::Incoming::Server.new(:version => @handshake.version)
-          @state = :open
-          trigger_onopen
-          handle_open(@handshake.leftovers) if @handshake.leftovers
-        else
-          trigger_onerror(@handshake.error)
-          close
-        end
-      end
-
-      def handle_open(data)
-        @frame << data
-        while frame = @frame.next
-          case frame.type
-          when :close
-            @state = :closing
-            close
-            trigger_onclose(frame.to_s)
-          when :ping
-            pong(frame.to_s)
-            trigger_onping(frame.to_s)
-          when :pong
-            trigger_onpong(frame.to_s)
-          when :text
-            trigger_onmessage(frame.to_s, :text)
-          when :binary
-            trigger_onmessage(frame.to_s, :binary)
-          end
-        end
-        unbind if @frame.error?
-      end
-
-      def handle_closing(data)
-        @state = :closed
-        close
-        trigger_onclose
-      end
-
-      def debug(description, data)
-        return unless @debug
-        puts(description + data.bytes.to_a.collect{|b| '\x' + b.to_s(16).rjust(2, '0')}.join) unless @state == :connecting
-      end
+      def pong(data = ''); super; end
 
     end
   end

data/lib/websocket/eventmachine/server/version.rb

@@ -1,7 +1,7 @@
 module WebSocket
   module EventMachine
     class Server
-      VERSION = '1.0.0'
+      VERSION = '1.0.1'
     end
   end
 end

data/websocket-eventmachine-server.gemspec

@@ -12,9 +12,7 @@ Gem::Specification.new do |s|
   s.summary     = %q{WebSocket server for Ruby}
   s.description = %q{WebSocket server for Ruby}
 
-  s.add_dependency 'websocket', '~> 1.0'
-  s.add_dependency 'websocket-native', '~> 1.0'
-  s.add_dependency 'eventmachine', '~> 1.0'
+  s.add_dependency 'websocket-eventmachine-base', '~> 1.0'
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: websocket-eventmachine-server
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,42 +9,10 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-19 00:00:00.000000000 Z
+date: 2012-12-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: websocket
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: websocket-native
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: eventmachine
+  name: websocket-eventmachine-base
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements: