socker 0.0.2 → 0.0.3

data/lib/socker.rb

@@ -23,6 +23,7 @@ module Socker
           WEBSOCKET_STANDARD_EVENTS.each(&register_handler(c, env))
         end
       end
+      # This is needed for Puma so we can log the requests to WebSockets
       @application.class.instance_eval {
         define_method(:log) { |message| Socker::App.log(message) }
       }
@@ -30,34 +31,56 @@ module Socker
       @application
     end
 
-    def connection(env, opts={}, &block)
-      conn = Faye::WebSocket.new(env)
-      yield conn if block_given?
-      conn.rack_response
-    end
-
-    def socket(socket=nil)
-      @socket = socket
-    end
-
+    # Helper method your application can use to register new handlers
+    # Supported events handlers are:
+    #
+    # * open    - The connection was succesfully established
+    # * close   - The connection was closed
+    # * error   - An error occured on the client side
+    # * message - A message was received from the socket
+    #
+    # Handler could be anything that implements the .call method, like
+    # lambda, Proc or Method...
+    #
     def on(event, handler)
       @events ||= {}
+      raise "Unable register handler for unsupported event: #{event}" unless event_supported?(event)
       @events[event] ||= lambda { |socket, ev| handler.call(socket, ev) }
     end
 
+    # A method used for mounting the application to Rack:
+    #
+    # run Rack::URLMap.new('/' => MyServer.new.to_app)
+    #
     def to_app
       @application
     end
 
+    # The default logging destination for the application.
+    # If you want to use custom logging or logging to a file, you can override
+    # this method.
+    #
     def self.log(message, level=:info)
       @log ||= Logger.new($stdout)
       @log.send(level, message)
     end
 
-    def log(message); self.class.log(message); end
+    def log(message)
+      self.class.log(message)
+    end
 
     private
 
+    def connection(env, opts={}, &block)
+      conn = Faye::WebSocket.new(env)
+      yield conn if block_given?
+      conn.rack_response
+    end
+
+    def event_supported?(event)
+      true if WEBSOCKET_STANDARD_EVENTS.include?(event.to_sym)
+    end
+
     def is_websocket?(env)
       Faye::WebSocket.websocket?(env)
     end
@@ -67,24 +90,24 @@ module Socker
     end
 
     def handle_with(event, opts={})
-      if events[event]
-        current_class = self.class
-        lambda do |ev|
-          @env = Rack::Request.new(opts[:env])
-          begin
-            handle(event, opts[:socket])
-            events[event].call(opts[:socket], ev)
-          rescue => error
-            current_class.log("[#{error.class}] #{error.message}\n#{error.backtrace.join("\n")}", :error)
-          end
+      return method(:handle_missing) if !events[event]
+      current_class = self.class
+      lambda do |ev|
+        @env = Rack::Request.new(opts[:env])
+        begin
+          handle(event, opts[:socket])
+          events[event].call(opts[:socket], ev)
+        rescue => error
+          current_class.log("[#{error.class}] #{error.message}\n#{error.backtrace.join("\n")}", :error)
         end
-      else
-        method(:handle_undefined)
       end
     end
 
-    def handle_undefined(event)
-      self.class.log("WARNING: The '#{event.type}' event is not defined.", :error)
+    # When the browser sent an event which has no handler defined, show an error
+    # message in the log, but don't crash the application.
+    #
+    def handle_missing(event)
+      self.class.log("WARNING: I dont know how to handle the '#{event.type}' event.", :error)
     end
 
   end

data/lib/socker/event_handlers.rb

@@ -2,18 +2,28 @@ module Socker
 
   module EventHandlers
 
+    # The list of active connections.
+    # This list is used for 'broadcasting' messages to all active connections
+    #
     def connections
       @connections ||= []
     end
 
+    # When a new connection is opened, we save it into the list
+    # of connections (so methods like 'broadcast' works). Also the :when_active
+    # callback is executed when this is a first connection.
+    #
     def on_open(connection)
       @callbacks[:when_active].call if connections.empty? and @callbacks[:when_active]
       connections << connection
     end
 
+    # When connection is closed, we remove it from the connections list and
+    # execute the :when_idle callback.
+    #
     def on_close(connection)
       connections.delete(connection)
-      @callbacks[:when_idle].call if connections.empty? and @callbacks[:when_active]
+      @callbacks[:when_idle].call if connections.empty? and @callbacks[:when_idle]
     end
 
     def handle(event, connection)

data/lib/socker/helper.rb

@@ -2,14 +2,30 @@ module Socker
 
   module Helper
 
+    # This function send an broadcast message to all active connections.
+    # The message must be String (but you can sent a JSON, etc..)
+    #
     def broadcast(message)
-      connections.each { |c| c.send(message) }
+      connections.each do |c|
+        begin
+          c.send(message)
+        rescue => error
+          log("ERROR: Connection #{c} seems invalid, ignoring. (#{error.message})")
+        end
+      end
     end
 
+    # If the protocol support PING, you can send this to all clients and when
+    # they replied with PONG message, you can handle that with callback.
+    #
     def pbroadcast(message, callback)
       connections.each { |c| c.ping(message, &callback) }
     end
 
+    # Provide access to the Rack params used for WebSocket connection, ie:
+    #
+    # socket = new Socket('ws://' + location.hostname + ':' + '9292' + '/?param1=value')
+    #
     def params
       @env.params
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: socker
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors: