socky 0.1.3 → 0.2.0

data/lib/socky/misc.rb

@@ -1,46 +1,68 @@
 module Socky
+  # common methods for all other classes
   module Misc
 
+    # extend including class by itself
     def self.included(base)
       base.extend Socky::Misc
     end
 
+    # return server-wide options
+    # @see Socky.options
     def options
       Socky.options
     end
 
+    # write server-wide options
     def options=(ob)
       Socky.options = ob
     end
 
+    # return name of current object
+    # @example when included in connection
+    #   @connection.name #=> "Connection(2149785820)"
     def name
       "#{self.class.to_s.split("::").last}(#{self.object_id})"
     end
 
+    # return log path
     def log_path
       Socky.log_path
     end
 
+    # return pid path
     def pid_path
       Socky.pid_path
     end
 
+    # return config path
     def config_path
       Socky.config_path
     end
 
+    # log message at info level
+    # @param [Array] args data for logging
     def info(args)
       Socky.logger.info args.join(" ")
     end
 
+    # log message at debug level
+    # @param [Array] args data for logging
     def debug(args)
       Socky.logger.debug args.join(" ")
     end
 
+    # log message at error level
+    # @param [String] name object name with raised error
+    # @param [Error] error error instance that was raised
     def error(name, error)
       debug [name, "raised:", error.class, error.message]
     end
 
+    # convert keys of hash to symbol
+    # @param [Hash] hash hash to symbolize
+    # @return [Hash] with symbolized keys
+    # @return [Object] if hash isn't instance of Hash
     def symbolize_keys(hash)
       return hash unless hash.is_a?(Hash)
       hash.inject({}) do |options, (key, value)|

data/lib/socky/net_request.rb

@@ -1,11 +1,16 @@
 require 'em-http'
 
 module Socky
+  # this class provide unobtrusive http request methods
   class NetRequest
     include Socky::Misc
 
     class << self
 
+      # send unobtrusive http POST request to gived address and return status of request as block response
+      # @param [String] url address to send request in format 'http://address[:port]/[path]'
+      # @param [Hash] params params for request(will be attached in post message)
+      # @yield [Boolean] called after request is finished - if response status is 200 then it's true, else false
       def post(url, params = {}, &block)
         http = EventMachine::HttpRequest.new(url).post :body => params, :timeout => options[:timeout] || 3
         http.errback  { yield false }

data/lib/socky/options.rb

@@ -2,12 +2,29 @@ require 'socky/options/config'
 require 'socky/options/parser'
 
 module Socky
+  # options parser - reads options from STDIN and config file and set Socky.options
   class Options
     include Socky::Misc
 
     class << self
+      # prepare server-wide options from config and parser
+      # @param [Array] argv arguments that will be provided to parser
+      # @see default_options default options
+      # @see Config.read merged with default options
+      # @see Parser.parse merges with default options after config
       def prepare(argv)
-        self.options = {
+        self.options = default_options
+
+        parsed_options = Parser.parse(argv)
+        config_options = Config.read(parsed_options[:config_path] || config_path, :kill => parsed_options[:kill])
+
+        self.options.merge!(config_options)
+        self.options.merge!(parsed_options)
+      end
+      
+      # default options for server
+      def default_options
+        {
           :config_path => config_path,
           :port => 8080,
           :debug => false,
@@ -15,12 +32,6 @@ module Socky
           :secure => false,
           :log_path => log_path
         }
-
-        parsed_options = Parser.parse(argv)
-        config_options = Config.read(parsed_options[:config_path] || config_path, :kill => parsed_options[:kill])
-
-        self.options.merge!(config_options)
-        self.options.merge!(parsed_options)
       end
     end
 

data/lib/socky/options/config.rb

@@ -3,24 +3,23 @@ require 'erb'
 
 module Socky
   class Options
+    # config parser class - used by Socky::Options
     class Config
 
-      class NoConfigFile < Socky::SockyError #:nodoc:
-      end
-
-      class InvalidConfig < Socky::SockyError #:nodoc:
-      end
-
-      class AlreadyExists < Socky::SockyError #:nodoc:
-      end
-
-      class ConfigUnavailable < Socky::SockyError #:nodoc:
-      end
-
-      class SuccessfullyCreated < Socky::SockyError #:nodoc:
-      end
+      class NoConfigFile < Socky::SockyError; end #:nodoc:
+      class InvalidConfig < Socky::SockyError; end #:nodoc:
+      class AlreadyExists < Socky::SockyError; end #:nodoc:
+      class ConfigUnavailable < Socky::SockyError; end #:nodoc:
+      class SuccessfullyCreated < Socky::SockyError; end #:nodoc:
 
       class << self
+        # read config file or exits if file don't exists or is invalid
+        # @param [String] path path to valid yaml file
+        # @param [Hash] args args to rescue eventual problems
+        # @option args [Any] kill (nil) if not nil then empty hash will be returned if config file isn't found
+        # @return [Hash] parsed config options
+        # @raise [NoConfigFile] if file doesn't exists
+        # @raise [InvalidConfig] if file isn't valid yaml
         def read(path, args = {})
           raise(NoConfigFile, "You must generate a config file (socky -g filename.yml)") unless File.exists?(path)
           result = YAML::load(ERB.new(IO.read(path)).result)
@@ -35,6 +34,12 @@ module Socky
           end
         end
 
+        # generate default config file
+        # @see DEFAULT_CONFIG_FILE
+        # @param [String] path path to file that will be created
+        # @raise [AlreadyExists] if file exists(you must delete it manually)
+        # @raise [ConfigUnavailable] if file cannot be created(wrong privilages?)
+        # @raise [SuccessfullyCreated] if file is successfully created
         def generate(path)
           raise(AlreadyExists, "Config file already exists. You must remove it before generating a new one.") if File.exists?(path)
           File.open(path, 'w+') do |file|
@@ -46,6 +51,7 @@ module Socky
           exit
         end
 
+        # default config file content
         DEFAULT_CONFIG_FILE= <<-EOF
 :port: 8080
 :debug: false

data/lib/socky/options/parser.rb

@@ -2,9 +2,14 @@ require 'optparse'
 
 module Socky
   class Options
+    # STDIN options parser - used by Socky::Options
     class Parser
 
       class << self
+        # parse options(usually from STDIN)
+        # see source code for available options
+        # @param [Array] argv options for parser
+        # @return [Hash] parsed options from array
         def parse(argv)
           result = {}
           opts = OptionParser.new do |opts|

data/lib/socky/runner.rb

@@ -1,8 +1,10 @@
 module Socky
+  # default runner class - creates server and runs it
   class Runner
     include Socky::Misc
 
     class << self
+      # create new eventmachine server
       def run(argv = ARGV)
         server = self.new(argv)
 
@@ -16,10 +18,13 @@ module Socky
       end
     end
 
+    # set server-wide options from args
     def initialize(argv = ARGV)
       Options.prepare(argv)
     end
 
+    # start eventmachine server
+    # require options to be parsed earlier
     def start
       EventMachine.epoll
 
@@ -42,33 +47,28 @@ module Socky
       end
     end
 
+    # stop eventmachine server
     def stop
       info ["Server stopping"]
       EventMachine.stop
     end
 
-    def store_pid(pid)
-     FileUtils.mkdir_p(File.dirname(pid_path))
-     File.open(pid_path, 'w'){|f| f.write("#{pid}\n")}
-    rescue => e
-      puts e
-      exit
-    end
-
+    # run server in daemon mode
     def daemonize
       fork do
-         Process.setsid
-         exit if fork
-         store_pid(Process.pid)
-         # Dir.chdir "/" # Mucks up logs
-         File.umask 0000
-         STDIN.reopen "/dev/null"
-         STDOUT.reopen "/dev/null", "a"
-         STDERR.reopen STDOUT
-         start
-       end
+        Process.setsid
+        exit if fork
+        store_pid(Process.pid)
+        # Dir.chdir "/" # Mucks up logs
+        File.umask 0000
+        STDIN.reopen "/dev/null"
+        STDOUT.reopen "/dev/null", "a"
+        STDERR.reopen STDOUT
+        start
+      end
     end
 
+    # kill daemonized server according to pid file in pid_path
     def kill_pid
       begin
         pid = IO.read(pid_path).chomp.to_i
@@ -80,5 +80,16 @@ module Socky
       end
       exit
     end
+
+    private
+    
+    def store_pid(pid)
+     FileUtils.mkdir_p(File.dirname(pid_path))
+     File.open(pid_path, 'w'){|f| f.write("#{pid}\n")}
+    rescue => e
+      puts e
+      exit
+    end
+
   end
 end

data/spec/em-websocket_spec.rb

@@ -3,9 +3,8 @@ require 'spec_helper'
 describe EM::WebSocket::Connection do
 
   it "should not receive debug message if :debug option is false" do
-    Socky.logger.stub!(:debug)
-    Socky.logger.should_not_receive(:debug)
     EM.run do
+      Socky.logger.should_not_receive(:debug)
       EM.add_timer(0.1) do
         http = EventMachine::HttpRequest.new('ws://127.0.0.1:9999/').get(:timeout => 0)
         http.errback  { http.close_connection }
@@ -19,9 +18,9 @@ describe EM::WebSocket::Connection do
   end
 
   it "should use Socky.logger.debug instead of pp when instance call #debug" do
-    Socky.logger.stub!(:debug)
-    Socky.logger.should_receive(:debug).with("Socket initialize")
     EM.run do
+      Socky.logger.should_receive(:debug).with("Socket initialize")
+      Socky.logger.should_receive(:debug).with(anything()).at_least(:once)
       EM.add_timer(0.1) do
         http = EventMachine::HttpRequest.new('ws://127.0.0.1:9999/').get(:timeout => 0)
         http.errback  { http.close_connection }

data/spec/socky/connection/authentication_spec.rb

@@ -20,22 +20,33 @@ describe Socky::Connection::Authentication do
         subscribe_request
       end
       it "should add self to connection list if #send_subscribe_request block is true" do
-        stub!(:authenticated?).and_return(false)
-        stub!(:send_subscribe_request).and_yield(true)
-        should_receive(:add_to_pool)
-        subscribe_request
+        EM.run do
+          stub!(:authenticated?).and_return(false)
+          stub!(:send_subscribe_request).and_yield(true)
+          should_receive(:add_to_pool)
+          subscribe_request
+          EM.stop
+        end
       end
       it "should be authenticated by url if #send_subscribe_request block is true" do
-        stub!(:authenticated?).and_return(false)
-        stub!(:send_subscribe_request).and_yield(true)
-        stub!(:add_to_pool)
-        subscribe_request
-        authenticated_by_url?.should be_true
+        EM.run do
+          stub!(:authenticated?).and_return(false)
+          stub!(:send_subscribe_request).and_yield(true)
+          stub!(:add_to_pool)
+          subscribe_request
+          authenticated_by_url?.should be_true
+          EM.stop
+        end
       end
       it "should disconnect if #send_subscribe_request block is false" do
-        stub!(:send_subscribe_request).and_yield(false)
-        should_receive(:disconnect)
-        subscribe_request
+        EM.run do
+          stub!(:send_subscribe_request).and_yield(false)
+          should_receive(:disconnect)
+          subscribe_request
+          EM.add_timer(0.1) do
+            EM.stop
+          end
+        end
       end
     end
     context "#unsubscribe_request" do
@@ -119,25 +130,25 @@ describe Socky::Connection::Authentication do
       it "should not call Socky::NetRequest#post if socky option subscribe_url is nil" do
         Socky.stub!(:options).and_return({:subscribe_url => nil})
         Socky::NetRequest.should_not_receive(:post)
-        send_subscribe_request
+        send_subscribe_request{}
       end
     end
     context "#send_unsubscribe_request" do
       it "should build params for request if socky option unsubscribe_url is not nil" do
         Socky.stub!(:options).and_return({:unsubscribe_url => "any"})
         should_receive(:params_for_request)
-        send_unsubscribe_request
+        send_unsubscribe_request{}
       end
       it "should call Socky::NetRequest#post if socky option unsubscribe_url is not nil" do
         Socky.stub!(:options).and_return({:unsubscribe_url => "any"})
         stub!(:params_for_request)
         Socky::NetRequest.should_receive(:post)
-        send_unsubscribe_request
+        send_unsubscribe_request{}
       end
       it "should not call Socky::NetRequest#post if socky option unsubscribe_url is nil" do
         Socky.stub!(:options).and_return({:unsubscribe_url => nil})
         Socky::NetRequest.should_not_receive(:post)
-        send_unsubscribe_request
+        send_unsubscribe_request{}
       end
     end
     context "#params_for_request" do

data/spec/socky/connection/finders_spec.rb

@@ -18,86 +18,86 @@ describe Socky::Connection::Finders do
     end
     
     it "#find_all should return all connections" do
-      self.class.find_all.should eql(@connections)
+      find_all.should eql(@connections)
     end
     context "#find" do
       it "should return all connections if no options specified" do
-        self.class.find.should eql(@connections)
+        find.should eql(@connections)
       end
       context "on :to" do
         context "if :clients option is specified" do
           it "should return all connections if :clients is nil" do
-            self.class.find(:to => {:clients => nil}).should eql(@connections)
+            find(:to => {:clients => nil}).should eql(@connections)
           end
           it "should return none connections if :clients is empty" do
-            self.class.find(:to => {:clients => []}).should eql([])
+            find(:to => {:clients => []}).should eql([])
           end
           it "should return only connections from specified client" do
-            self.class.find(:to => {:clients => "client1"}).should eql([@connection1,@connection2])
+            find(:to => {:clients => "client1"}).should eql([@connection1,@connection2])
           end
           it "should return only connections from specified clients if array provided" do
-            self.class.find(:to => {:clients => ["client1","client2"]}).should eql([@connection1,@connection2,@connection3])
+            find(:to => {:clients => ["client1","client2"]}).should eql([@connection1,@connection2,@connection3])
           end
         end
         context "if :channels option is specified" do
           it "should return all connections if :channels is nil" do
-            self.class.find(:to => {:channels => nil}).should eql(@connections)
+            find(:to => {:channels => nil}).should eql(@connections)
           end
           it "should return none connections if :channels is empty" do
-            self.class.find(:to => {:channels => []}).should eql([])
+            find(:to => {:channels => []}).should eql([])
           end
           it "should return all connections that include specified channel" do
-            self.class.find(:to => {:channels => "3"}).should eql([@connection2,@connection4])
+            find(:to => {:channels => "3"}).should eql([@connection2,@connection4])
           end
           it "should return all connections that include at last one of specified channels" do
-            self.class.find(:to => {:channels => ["2","3"]}).should eql([@connection2,@connection3,@connection4])
+            find(:to => {:channels => ["2","3"]}).should eql([@connection2,@connection3,@connection4])
           end
         end
         context "if both :clients and :channels options are provided" do
           context "but :channels are nil" do
             it "should return only connections from specified client" do
-              self.class.find(:to => {:channels => nil,:clients => "client1"}).should eql([@connection1,@connection2])
+              find(:to => {:channels => nil,:clients => "client1"}).should eql([@connection1,@connection2])
             end
             it "should return only connections from specified clients if array provided" do
-              self.class.find(:to => {:channels => nil,:clients => ["client1","client2"]}).should eql([@connection1,@connection2,@connection3])
+              find(:to => {:channels => nil,:clients => ["client1","client2"]}).should eql([@connection1,@connection2,@connection3])
             end
           end
           context "but :channels are empty" do
             it "should return none connections" do
-              self.class.find(:to => {:channels => [],:clients => "client1"}).should eql([])
+              find(:to => {:channels => [],:clients => "client1"}).should eql([])
             end
             it "should return none connections if array provided" do
-              self.class.find(:to => {:channels => [],:clients => ["client1","client2"]}).should eql([])
+              find(:to => {:channels => [],:clients => ["client1","client2"]}).should eql([])
             end
           end
           context "but :clients are nil" do
             it "should return all connections that include specified channel" do
-              self.class.find(:to => {:clients => nil,:channels => "3"}).should eql([@connection2,@connection4])
+              find(:to => {:clients => nil,:channels => "3"}).should eql([@connection2,@connection4])
             end
             it "should return all connections that include at last one of specified channels" do
-              self.class.find(:to => {:clients => nil,:channels => ["2","3"]}).should eql([@connection2,@connection3,@connection4])
+              find(:to => {:clients => nil,:channels => ["2","3"]}).should eql([@connection2,@connection3,@connection4])
             end
           end
           context "but :clients are empty" do
             it "should return none connections" do
-              self.class.find(:to => {:clients => [],:channels => "3"}).should eql([])
+              find(:to => {:clients => [],:channels => "3"}).should eql([])
             end
             it "should return none connections if array provided" do
-              self.class.find(:to => {:clients => [],:channels => ["2","3"]}).should eql([])
+              find(:to => {:clients => [],:channels => ["2","3"]}).should eql([])
             end
           end
           it "should return only connections from specified client that include specified channel" do
-            self.class.find(:to => {:clients => "client1",:channels => "3"}).should eql([@connection2])
-            self.class.find(:to => {:clients => "client1",:channels => "2"}).should eql([])
+            find(:to => {:clients => "client1",:channels => "3"}).should eql([@connection2])
+            find(:to => {:clients => "client1",:channels => "2"}).should eql([])
           end
           it "should return only connections from specified client that include one of specified channels" do
-            self.class.find(:to => {:clients => "client1",:channels => ["2","3"]}).should eql([@connection2])
+            find(:to => {:clients => "client1",:channels => ["2","3"]}).should eql([@connection2])
           end
           it "should return only connections from specified clients that include specified channel" do
-            self.class.find(:to => {:clients => ["client1","client2"],:channels => "2"}).should eql([@connection3])
+            find(:to => {:clients => ["client1","client2"],:channels => "2"}).should eql([@connection3])
           end
           it "should return only connections from specified clients that include at last one of specified channels" do
-            self.class.find(:to => {:clients => ["client1","client2"],:channels => ["2","1"]}).should eql([@connection2,@connection3])
+            find(:to => {:clients => ["client1","client2"],:channels => ["2","1"]}).should eql([@connection2,@connection3])
           end
         end
       end
@@ -105,63 +105,63 @@ describe Socky::Connection::Finders do
       context "on :except" do
         context "if :clients option is specified" do
           it "should return all connections if :clients is nil" do
-            self.class.find(:except => {:clients => nil}).should eql(@connections)
+            find(:except => {:clients => nil}).should eql(@connections)
           end
           it "should return all connections if :clients is empty" do
-            self.class.find(:except => {:clients => []}).should eql(@connections)
+            find(:except => {:clients => []}).should eql(@connections)
           end
           it "should return all connections except of specified client" do
-            self.class.find(:except => {:clients => "client1"}).should eql([@connection3,@connection4])
+            find(:except => {:clients => "client1"}).should eql([@connection3,@connection4])
           end
           it "should return all connections except of specified clients if array provided" do
-            self.class.find(:except => {:clients => ["client1","client2"]}).should eql([@connection4])
+            find(:except => {:clients => ["client1","client2"]}).should eql([@connection4])
           end
         end
         context "if :channels option is specified" do
           it "should return all connections if :channels is nil" do
-            self.class.find(:except => {:channels => nil}).should eql(@connections)
+            find(:except => {:channels => nil}).should eql(@connections)
           end
           it "should return all connections if :channels is empty" do
-            self.class.find(:except => {:channels => []}).should eql(@connections)
+            find(:except => {:channels => []}).should eql(@connections)
           end
           it "should return all connections except of that include all specified channels" do
-            self.class.find(:except => {:channels => ["2","5"]}).should eql([@connection1,@connection2,@connection4])
+            find(:except => {:channels => ["2","5"]}).should eql([@connection1,@connection2,@connection4])
           end
         end
         context "if both :clients and :channels options are provided" do
           context "but :channels are nil" do
             it "should return all connections except of specified client" do
-              self.class.find(:except => {:channels => nil,:clients => "client1"}).should eql([@connection3,@connection4])
+              find(:except => {:channels => nil,:clients => "client1"}).should eql([@connection3,@connection4])
             end
             it "should return all connections except of specified clients if array provided" do
-              self.class.find(:except => {:channels => nil,:clients => ["client1","client2"]}).should eql([@connection4])
+              find(:except => {:channels => nil,:clients => ["client1","client2"]}).should eql([@connection4])
             end
           end
           context "but :channels are empty" do
             it "should return all connections except of specified client" do
-              self.class.find(:except => {:channels => [],:clients => "client1"}).should eql([@connection3,@connection4])
+              find(:except => {:channels => [],:clients => "client1"}).should eql([@connection3,@connection4])
             end
             it "should return all connections except of provided clients if array provided" do
-              self.class.find(:except => {:channels => [],:clients => ["client1","client2"]}).should eql([@connection4])
+              find(:except => {:channels => [],:clients => ["client1","client2"]}).should eql([@connection4])
             end
           end
           context "but :clients are nil" do
             it "should return all connections except of that include all of specified channels" do
-              self.class.find(:except => {:clients => nil,:channels => ["2","5"]}).should eql([@connection1,@connection2,@connection4])
+              find(:except => {:clients => nil,:channels => ["2","5"]}).should eql([@connection1,@connection2,@connection4])
             end
           end
           context "but :clients are empty" do
             it "should return all connections except of that include all of specified channels " do
-              self.class.find(:except => {:clients => [],:channels => ["2","5"]}).should eql([@connection1,@connection2,@connection4])
+              find(:except => {:clients => [],:channels => ["2","5"]}).should eql([@connection1,@connection2,@connection4])
             end
           end
           it "should return all connections except of specified client or all specified channels" do
-            self.class.find(:except => {:clients => "client2",:channels => "3"}).should eql([@connection1,@connection2,@connection4])
-            self.class.find(:except => {:clients => "client2",:channels => ["3","5"]}).should eql([@connection1,@connection2])
+            find(:except => {:clients => "client2",:channels => "3"}).should eql([@connection1,@connection2,@connection4])
+            find(:except => {:clients => "client2",:channels => ["3","5"]}).should eql([@connection1,@connection2])
           end
           it "should return only connections from specified clients that include specified channel" do
-            self.class.find(:except => {:clients => ["client1","client2"],:channels => "3"}).should eql([@connection4])
-            self.class.find(:except => {:clients => ["client1","client2"],:channels => ["3","5"]}).should eql([])
+            find(:except => {:clients => ["client1","client2"],:channels => "3"}).should eql([@connection4])
+            find(:except => {:clients => ["client1","client2"],:channels => ["3","5"]}).should eql([])
           end
         end
       end
@@ -169,16 +169,16 @@ describe Socky::Connection::Finders do
       context "on :to and :except" do
         context "should value 'except' more that 'to'" do
           it "on :client" do
-            self.class.find(:to => {:clients => "client1"},:except => {:clients => "client1"}).should eql([])
+            find(:to => {:clients => "client1"},:except => {:clients => "client1"}).should eql([])
           end
           it "on :channels" do
-            self.class.find(:to => {:channels => "5"},:except => {:channels => "5"}).should eql([])
+            find(:to => {:channels => "5"},:except => {:channels => "5"}).should eql([])
           end
           it "on :client allow and :channels except" do
-            self.class.find(:to => {:clients => "client2"},:except => {:channels => ["2","5"]}).should eql([])
+            find(:to => {:clients => "client2"},:except => {:channels => ["2","5"]}).should eql([])
           end
           it "on :channels allow and :clients except" do
-            self.class.find(:to => {:channels => ["5"]},:except => {:clients => "client2"}).should eql([@connection2,@connection4])
+            find(:to => {:channels => ["5"]},:except => {:clients => "client2"}).should eql([@connection2,@connection4])
           end
         end
       end