socky 0.1.3 → 0.2.0

data/CHANGELOG.textile

@@ -1,5 +1,14 @@
 h1. Changelog
 
+h2. 0.2.0 / 2010-10-03
+
+* new features:
+** inline documentation
+* bugfixes:
+** send authentication after finishing handshake
+** tests less using stubs and more real cases
+** fix some tests
+
 h2. 0.1.3 / 2010-09-23
 
 * new features:

data/Rakefile

@@ -1,4 +1,7 @@
 require 'rake'
+require 'rake/clean'
+CLEAN.include %w(**/*.{log,rbc})
+
 require 'spec/rake/spectask'
 
 task :default => :spec
@@ -19,6 +22,7 @@ begin
     gemspec.authors = ["Bernard Potocki"]
     gemspec.add_dependency('em-websocket', '>= 0.1.4')
     gemspec.add_dependency('em-http-request')
+    gemspec.add_dependency('json')
     gemspec.files.exclude ".gitignore"
   end
 rescue LoadError

data/VERSION

@@ -1 +1 @@
-0.1.3
+0.2.0

data/lib/socky.rb

@@ -5,21 +5,29 @@ require 'em-websocket'
 $:.unshift(File.dirname(__FILE__))
 require 'em-websocket_hacks'
 
+# Socky is a WebSocket server and client for Ruby on Rails 
+# @author Bernard "Imanel" Potocki
+# @see http://github.com/imanel/socky_gem main repository
 module Socky
 
   class SockyError < StandardError; end #:nodoc:
 
+  # server version
   VERSION = File.read(File.dirname(__FILE__) + '/../VERSION').strip
 
   class << self
+    # read server-wide options
     def options
       @options ||= {}
     end
 
+    # write server-wide options
     def options=(val)
       @options = val
     end
 
+    # access or initialize logger
+    # default logger writes to STDOUT
     def logger
       return @logger if defined?(@logger) && !@logger.nil?
       path = log_path
@@ -29,18 +37,22 @@ module Socky
       prepare_logger(STDOUT)
     end
 
+    # overwrite default logger
     def logger=(logger)
       @logger = logger
     end
 
+    # default log path
     def log_path
       options[:log_path] || nil
     end
 
+    # default pid path
     def pid_path
       options[:pid_path] || File.join(%w( / var run socky.pid ))
     end
 
+    # default config path
     def config_path
       options[:config_path] || File.join(%w( / var run socky.yml ))
     end

data/lib/socky/connection.rb

@@ -3,55 +3,82 @@ require 'socky/connection/authentication'
 require 'socky/connection/finders'
 
 module Socky
+  # every connection to server creates one instance of Connection
   class Connection
     include Socky::Misc
     include Socky::Connection::Authentication
-    include Socky::Connection::Finders
+    extend Socky::Connection::Finders
 
+    # reference to connection socket
     attr_reader :socket
 
     class << self
+      # list of all connections in pool
+      # @return [Array] list of connections
       def connections
         @connections ||= []
       end
     end
-
+    
+    # initialize new connection
+    # @param [WebSocket] socket valid connection socket
     def initialize(socket)
       @socket = socket
     end
 
+    # read query data from socket request
+    # @return [Hash] hash of query data
     def query
       socket.request["Query"] || {}
     end
 
+    # return if user appear to be admin
+    # this one should not be base to imply that user actually is
+    # admin - later authentication is needed
+    # @return [Boolean] is user claim to be admin?
     def admin
       ["true","1"].include?(query["admin"])
     end
 
+    # client individual id - multiple connection can be organized
+    # by client id and later accessed at once
+    # @return [String] client id(might be nil)
     def client
       query["client_id"]
     end
 
+    # client individual secret - used to check if user is admin
+    # and to sending authentication data to server(by subscribe_url)
+    # @return [String] client secret(might be nil)
     def secret
       query["client_secret"]
     end
 
+    # client channel list - one client can have multiple channels
+    # every client have at last channel - if no channels are provided
+    # at default then user is assigned to nil channel
+    # @return [Array] list of client channels
     def channels
       @channels ||= query["channels"].to_s.split(",").collect(&:strip).reject(&:empty?)
       @channels[0] ||= nil # Every user should have at last one channel
       @channels
     end
 
+    # check if client is valid and add him to pool or disconnect
     def subscribe
       debug [self.name, "incoming"]
       subscribe_request
     end
 
+    # remove client from pool and disconnect
     def unsubscribe
       debug [self.name, "terminated"]
       unsubscribe_request
     end
 
+    # check if client can send messages and process it
+    # @see Socky::Message.process
+    # @param [String] msg message to send in json format
     def process_message(msg)
       if admin && authenticated?
         Socky::Message.process(self, msg)
@@ -60,19 +87,35 @@ module Socky
       end
     end
 
+    # send message to client
+    # @param [Object] msg data to send(will be converted to json using to_json method)
     def send_message(msg)
       send_data({:type => :message, :body => msg})
     end
 
+    # disconnect connection
+    def disconnect
+      socket.close_connection_after_writing
+    end
+
+    # convert connection to json(used in show_connection query)
+    # @param [Any] args it is required by different versions of ruby
+    # @return [JSon] id, client_id and channel list data
+    def to_json(*args)
+      {
+        :id => self.object_id,
+        :client_id => self.client,
+        :channels => self.channels.reject{|channel| channel.nil?}
+      }.to_json
+    end
+
+    private
+
     def send_data(data)
       debug [self.name, "sending data", data.inspect]
       socket.send data.to_json
     end
 
-    def disconnect
-      socket.close_connection_after_writing
-    end
-
     def connection_pool
       self.class.connections
     end
@@ -89,13 +132,5 @@ module Socky
       connection_pool.delete(self)
     end
 
-    def to_json(*args)
-      {
-        :id => self.object_id,
-        :client_id => self.client,
-        :channels => self.channels.reject{|channel| channel.nil?}
-      }.to_json
-    end
-
   end
 end

data/lib/socky/connection/authentication.rb

@@ -1,23 +1,38 @@
 module Socky
   class Connection
+    # authentication module - included in Socky::Connection
     module Authentication
       include Socky::Misc
 
+      # check if user is valid and then send him authentication data and add to pool
+      # if not then user is given failure response(so client javascript
+      # will know that is should not reconnect again) and then is disconnected
+      # admin user is automaticaly authenticated but isn't added to pool
+      # he will be authenticated when he will try to send message
+      # thanks to that admin don't need to wait for authentication confirmation
+      # on every connection so it will fasten things for him
       def subscribe_request
         send_subscribe_request do |response|
           if response
             debug [self.name, "authentication successed"]
             add_to_pool
-            send_authentication("success")
+            EventMachine.add_timer(0.1) do
+              send_authentication("success")
+            end
             @authenticated_by_url = true
           else
             debug [self.name, "authentication failed"]
-            send_authentication("failure")
-            disconnect
+            EventMachine.add_timer(0.1) do
+              send_authentication("failure")
+              disconnect
+            end
           end
         end unless admin || authenticated?
       end
 
+      # if user is authenticated then he is removed from pool and 
+      # unsubscribe notification is sent to server unless he is admin
+      # if user is not authenticated then nothing will happen
       def unsubscribe_request
         if authenticated?
           remove_from_pool
@@ -25,14 +40,19 @@ module Socky
         end
       end
 
-      def send_authentication(msg)
-        send_data({:type => :authentication, :body => msg})
-      end
-
+      # if user is admin then his secred is compared with server secred
+      # in user isn't admin then it checks if user is authenticated by
+      # server request(defaults to true if subscribe_url is nil)
       def authenticated?
         @authenticated ||= (admin ? authenticate_as_admin : authenticate_as_user)
       end
 
+      private
+
+      def send_authentication(msg)
+        send_data({:type => :authentication, :body => msg})
+      end
+
       def authenticate_as_admin
         options[:secret].nil? || secret == options[:secret]
       end

data/lib/socky/connection/finders.rb

@@ -1,63 +1,74 @@
 module Socky
   class Connection
+    # finders module - extends Socky::Connection
     module Finders
 
-      def self.included(base)
-        base.extend ClassMethods
+      # Return list of all connections
+      def find_all
+        Socky::Connection.connections
       end
 
-      module ClassMethods
-        def find_all
-          Socky::Connection.connections
-        end
+      # Return filtered list of connections
+      # @param [Hash] opts the options for filters.
+      # @option opts [Hash] :to ({}) return only listed clients/channels. keys supported: clients, channels
+      # @option opts [Hash] :except ({}) return all clients/channels except listed. keys supported: clients, channels
+      # @return [Array] list of connections
+      # @example return all connections
+      #   Socky::Connection.find
+      # @example return no connections
+      #   # empty array as param means "no channels"
+      #   # nil is handles as "ignore param" so all clients/channels will be executed
+      #   Socky::Connection.find(:to => { :clients => [] })
+      #   Socky::Connection.find(:to => { :channels => [] })
+      # @example return connections of users "first" and "second" from channels "some_channel"
+      #   Socky::Connection.find(:to => { :clients => ["first","second"], :channels => "some_channel" })
+      # @example return all connections from channel "some_channel" except of ones belonging to "first"
+      #   Socky::Connection.find(:to => { :channels => "some_channel" }, :except => { :clients => "first" })
+      def find(opts = {})
+        to = symbolize_keys(opts[:to]) || {}
+        exclude = symbolize_keys(opts[:except]) || {}
 
-        def find(opts = {})
-          to = symbolize_keys(opts[:to]) || {}
-          exclude = symbolize_keys(opts[:except]) || {}
+        connections = find_all
+        connections = filter_by_clients(connections, to[:clients], exclude[:clients])
+        connections = filter_by_channels(connections, to[:channels], exclude[:channels])
 
-          connections = find_all
-          connections = filter_by_clients(connections, to[:clients], exclude[:clients])
-          connections = filter_by_channels(connections, to[:channels], exclude[:channels])
-
-          connections
-        end
-
-        private
-
-        def filter_by_clients(connections, included_clients = nil, excluded_clients = nil)
-          # Empty table means "no users" - nil means "all users"
-          return [] if (included_clients.is_a?(Array) && included_clients.empty?)
+        connections
+      end
 
-          included_clients = to_array(included_clients)
-          excluded_clients = to_array(excluded_clients)
+      private
 
-          connections.collect do |connection|
-            connection if (included_clients.empty? || included_clients.include?(connection.client)) && !excluded_clients.include?(connection.client)
-          end.compact
-        end
+      def filter_by_clients(connections, included_clients = nil, excluded_clients = nil)
+        # Empty table means "no users" - nil means "all users"
+        return [] if (included_clients.is_a?(Array) && included_clients.empty?)
 
-        def filter_by_channels(connections, included_channels = nil, excluded_channels = nil)
-          # Empty table means "no channels" - nil means "all channels"
-          return [] if (included_channels.is_a?(Array) && included_channels.empty?)
+        included_clients = to_array(included_clients)
+        excluded_clients = to_array(excluded_clients)
 
-          included_channels = to_array(included_channels)
-          excluded_channels = to_array(excluded_channels)
+        connections.collect do |connection|
+          connection if (included_clients.empty? || included_clients.include?(connection.client)) && !excluded_clients.include?(connection.client)
+        end.compact
+      end
 
-          connections.collect do |connection|
-            connection if connection.channels.any? do |channel|
-              (included_channels.empty? || included_channels.include?(channel) ) && !excluded_channels.include?(channel)
-            end
-          end.compact
-        end
+      def filter_by_channels(connections, included_channels = nil, excluded_channels = nil)
+        # Empty table means "no channels" - nil means "all channels"
+        return [] if (included_channels.is_a?(Array) && included_channels.empty?)
 
-        def to_array(obj)
-          return [] if obj.nil?
-          return obj if obj.is_a?(Array)
-          [obj]
-        end
+        included_channels = to_array(included_channels)
+        excluded_channels = to_array(excluded_channels)
 
+        connections.collect do |connection|
+          connection if connection.channels.any? do |channel|
+            (included_channels.empty? || included_channels.include?(channel) ) && !excluded_channels.include?(channel)
+          end
+        end.compact
       end
 
+      # This is implemented due to differences between methods of handling to_a in ruby 1.8 and 1.9
+      def to_array(obj)
+        return [] if obj.nil?
+        return obj if obj.is_a?(Array)
+        [obj]
+      end
     end
   end
 end

data/lib/socky/message.rb

@@ -1,6 +1,8 @@
 require 'json'
 
 module Socky
+  # every message from admin is stored as instance of Message
+  # and then processed by #process method
   class Message
     include Socky::Misc
 
@@ -8,9 +10,16 @@ module Socky
     class UnauthorisedQuery < Socky::SockyError; end #:nodoc:
     class InvalidQuery < Socky::SockyError; end #:nodoc:
 
-    attr_reader :params, :creator
+    # message params like command type or message content
+    attr_reader :params
+    # message sender(admin) required when some data are returned
+    attr_reader :creator
 
     class << self
+      # create new message and process it
+      # @see #process
+      # @param [Connection] connection creator of message
+      # @param [String] message message content
       def process(connection, message)
         message = new(connection, message)
         message.process
@@ -20,35 +29,44 @@ module Socky
       end
     end
 
+    # initialize new message
+    # @param [Connection] creator creator of message
+    # @param [String] message valid json containing hash of params
+    # @raise [InvalidJSON] if message is invalid json or don't evaluate to hash
     def initialize(creator, message)
       @params = symbolize_keys(JSON.parse(message)) rescue raise(InvalidJSON, "invalid request")
       @creator = creator
     end
 
+    # process message - check command('broadcast' or 'query')
+    # and send message to correct connections
+    # 'broadcast' command require 'body' of message and allows 'to' and 'except' hashes for filters
+    # 'query' command require 'type' of query - currently only 'show_connections' is supported
+    # @see Socky::Connection::Finders.find filtering options
+    # @raise [InvalidQuery, 'unknown command'] when 'command' param is invalid
+    # @raise [InvalidQuery, 'unknown query type'] when 'command' is 'queru' but no 'type' is provided
     def process
       debug [self.name, "processing", params.inspect]
 
-      case params[:command].to_sym
-        when :broadcast then broadcast
-        when :query then query
-        else raise
+      case params.delete(:command).to_s
+        when "broadcast" then broadcast
+        when "query" then query
+        else raise(InvalidQuery, "unknown command")
       end
-    rescue
-      raise(InvalidQuery, "unknown command")
     end
 
+    private
+
     def broadcast
       connections = Socky::Connection.find(params)
       send_message(params[:body], connections)
     end
 
     def query
-      case params[:type].to_sym
-        when :show_connections then query_show_connections
-        else raise
+      case params[:type].to_s
+        when "show_connections" then query_show_connections
+        else raise(InvalidQuery, "unknown query type")
       end
-    rescue
-      raise(InvalidQuery, "unknown query type")
     end
 
     def query_show_connections