queri 0.0.2

data/lib/queri.rb

@@ -0,0 +1,113 @@
+require "queri/version"
+require "yaml"
+require "xmlrpc/client"
+
+Dir[ File.join( File.dirname(__FILE__), "**", "*.rb" ) ].each {|f| require f}
+
+module Queri
+  LOGFILE = ""
+  PERIOD = ""
+  AGENT_FILTER = ""
+
+  @config = {
+    :host => "127.0.0.1",
+    :path => "/path/to/queuemetrics.do",
+    :port => "8080",
+    :username => "username",
+    :password => "some_secret"
+  }
+
+  @valid_config_keys = @config.keys
+
+  @@server = nil
+
+  private_constant :LOGFILE, :PERIOD, :AGENT_FILTER
+
+  def self.config
+    @config
+  end
+
+  def self.configure opts={}
+    raise ArgumentError, "expected hash, got something else" if opts.class != Hash
+    unless opts.empty?
+      if (@valid_config_keys - opts.keys).any?
+        puts "WARNING:  erroneous keys given to ::config. Acceptible keys include #{@valid_config_keys}"
+      end
+      if (opts.keys & @valid_config_keys).empty?
+        raise ArgumentError, "erroneous keys given to ::config. Acceptible keys include #{@valid_config_keys}"
+      else
+        opts.each {|k,v| @config[k.to_sym] = v if @valid_config_keys.include?(k.to_sym)}
+        @@server = XMLRPC::Client.new(host = @config[:host], path = @config[:path], port = @config[:port])
+      end
+    end
+  end
+
+  def self.configure_with path_to_yaml_file
+    raise ArgumentError, "expected path to yaml file as string, got something else" if path_to_yaml_file.class != String
+    begin
+      config = YAML.load(IO.read(path_to_yaml_file))
+    rescue Errno::ENOENT
+      raise LoadError, "the specified configuration file could not be found"
+    rescue Psych::SyntaxError
+      raise LoadError, "the specified configuration file contains invalid syntax"
+    end
+    configure(config)
+    @@server = XMLRPC::Client.new(host = @config[:host], path = @config[:path], port = @config[:port])
+  end
+
+  def self.send_request *args
+    raise LoadError, "client configs not set. Assign by passing a hash to Queri.configure or a yaml file path to Queri.configure_with" if (@config.nil? || @config.empty?)
+    request = Request.new(*args)
+    response = @@server.call(*request.parameters)
+    return response[request.report.class.xml_code]
+  end
+
+  class Request
+    attr_reader :report
+
+    def initialize *args
+      raise ArgumentError, "expected arguments: queues(Array), report(Stats or Realtime obj), period_start(Time or Nil), period_end(Time or Nil)" unless valid_args?(args)
+      @queues, @report, @period_start, @period_end = validate_args(args)
+    end
+
+    def parameters
+      if @period_start.nil? && @period_end.nil?
+        [@report.class.query_method, @queues.join("|"), Queri.config[:username], Queri.config[:password], LOGFILE, AGENT_FILTER, [@report.class.xml_code]]
+      else
+        [@report.class.query_method, @queues.join("|"), Queri.config[:username], Queri.config[:password], LOGFILE, PERIOD, @period_start, @period_end, AGENT_FILTER, [@report.class.xml_code]]
+      end
+    end
+
+    private
+
+      def valid_args? args
+        valid = true
+        valid = false if args[0].class != Array
+        valid = false if args[1].class == NilClass
+        valid = false if (args[2].class != NilClass && args[2].class != Time)
+        valid = false if (args[3].class != NilClass && args[3].class != Time)
+        return valid
+      end
+
+      def validate_args args
+        raise ArgumentError, "queues array cannot be empty" if args[0].empty?
+        if args[1].class.name.include?("Queri::Stats::")
+          if (args[2].nil? || args[3].nil?)
+            raise ArgumentError, "Queri::Stats reports require non-nil period start and end times"
+          end
+        elsif args[1].class.name.include?("Queri::Realtime::")
+          unless (args[2].nil? && args[3].nil?)
+            raise ArgumentError, "Queri::Realtime reports require nil period start and end times"
+          end
+        end
+        args[2] = format_time(args[2])
+        args[3] = format_time(args[3])
+        return args
+      end
+
+      def format_time time
+        return time unless time.respond_to?(:strftime)
+        time.strftime("%Y-%m-%d.%H:%M:%S")
+      end
+  end
+end

data/queri.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'queri/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "queri"
+  spec.version       = Queri::VERSION
+  spec.authors       = ["Brad Rice"]
+  spec.email         = ["bradley_rice@mac.com"]
+  spec.description   = %q{Queuemetrics Reporting Interface}
+  spec.summary       = %q{Send requests to QM's XMLRPC client and receive human-readable responses}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.files         -= ["spec/config.yml"]
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 2.14.1"
+end

data/spec/queri_spec.rb

@@ -0,0 +1,268 @@
+require 'spec_helper'
+
+describe Queri do
+  let(:queues) { ["10000"] }
+  let(:report) { double(Queri::Realtime::Queues) }
+
+  describe "constants" do
+    describe "for log file" do
+      let(:const_symbol) { :LOGFILE }
+      let(:constant) { Queri::LOGFILE }
+
+      it_behaves_like "a private constant"
+    end
+
+    describe "for period" do
+      let(:const_symbol) { :PERIOD }
+      let(:constant) { Queri::PERIOD }
+
+      it_behaves_like "a private constant"
+    end
+
+    describe "for agent filter" do
+      let(:const_symbol) { :AGENT_FILTER }
+      let(:constant) { Queri::AGENT_FILTER }
+
+      it_behaves_like "a private constant"
+    end
+  end
+
+  describe "::config" do
+    subject { Queri.config }
+
+    it "should respond" do
+      expect{ subject }.to_not raise_error
+    end
+
+    it "should return a Hash" do
+      subject.should be_a Hash
+    end
+  end
+
+  describe "::configure" do
+    let(:configs) { Hash[:password, "new_secret"] }
+
+    before do
+      @saved_configs = Queri.config.dup
+    end
+
+    subject { Queri.configure(configs) }
+
+    after do
+      Queri.configure(@saved_configs)
+    end
+
+    it "should respond" do
+      expect{ subject }.to_not raise_error
+    end
+
+    it "should require a Hash" do
+      expect{ Queri.configure(configs.to_a) }.to raise_error(ArgumentError)
+      expect{ Queri.configure(configs) }.to_not raise_error
+    end
+
+    it "should default to accept a Hash" do
+      expect{ Queri.configure }.to_not raise_error
+    end
+
+    it "should update project configurations" do
+      old_configs = Queri.config.dup
+      subject
+      Queri.config.should_not eq old_configs
+    end
+
+    context "given some erroneous keys" do
+      let(:configs) { Hash[:password, "new_secret", :foo, "bar"] }
+
+      it "should warn the user against bad data" do
+        Queri.should_receive(:puts).with("WARNING:  erroneous keys given to ::config. Acceptible keys include #{Queri.instance_variable_get(:@valid_config_keys)}")
+        subject
+      end
+
+      it "should update project configurations" do
+        old_configs = Queri.config.dup
+        subject
+        Queri.config.should_not eq old_configs
+      end
+    end
+
+    context "given all erroneous keys" do
+      let(:configs) { Hash[:foo, "bar"] }
+
+      it "should raise ArgumentError" do
+        expect{ subject }.to raise_error(ArgumentError)
+      end
+
+      it "should not update project configurations" do
+        old_configs = Queri.config
+        begin
+          subject
+        rescue ArgumentError
+        end
+        Queri.config.should eq old_configs
+      end
+    end
+  end
+
+  describe "::configure_with" do
+    let(:test_config_file) { File.join(File.dirname(__FILE__), 'test_config.yml') }
+
+    before do
+      @saved_configs = Queri.config.dup
+      File.open(test_config_file, 'w') do |f|
+        f << "---\n"
+        f << "  :password:  \"new_secret\""
+      end
+    end
+
+    subject { Queri.configure_with(test_config_file) }
+
+    after do
+      FileUtils.rm(test_config_file)
+      Queri.configure(@saved_configs)
+    end
+
+    it "should respond" do
+      expect{ subject }.to_not raise_error
+    end
+
+    it "should require a String" do
+      expect{ Queri.configure_with(Array.new) }.to raise_error(ArgumentError)
+      expect{ Queri.configure_with(test_config_file) }.to_not raise_error
+    end
+
+    it "should update project configurations" do
+      old_configs = Queri.config.dup
+      subject
+      Queri.config.should_not eq old_configs
+    end
+
+    context "given a bad file path" do
+      let(:bad_config_file) { File.join(File.dirname(__FILE__), 'nonexistant_config.yml') }
+
+      subject { Queri.configure_with(bad_config_file) }
+
+      it "should raise LoadError" do
+        expect{ subject }.to raise_error(LoadError)
+      end
+
+      it "should not update project configurations" do
+        old_configs = Queri.config.dup
+        begin
+          subject
+        rescue LoadError
+        end
+        Queri.config.should eq old_configs
+      end
+    end
+
+    context "given file with syntax error" do
+      before do
+        File.open(test_config_file, 'w') do |f|
+          f << "---"
+          f << "\t:password: bad_syntax"
+        end
+      end
+
+      it "should raise LoadError" do
+        expect{ subject }.to raise_error(LoadError)
+      end
+
+      it "should not update project configurations" do
+        old_configs = Queri.config.dup
+        begin
+          subject
+        rescue LoadError
+        end
+        Queri.config.should eq old_configs
+      end
+    end
+  end
+
+  describe "::send_request" do
+    before do
+      @client = double(XMLRPC::Client)
+      @client.stub(:call).and_return( {"xml_code" => [:keys, :for, :report]} )
+    end
+
+    subject { Queri.send_request(queues, report) }
+
+    context "without configurations" do
+      before do
+        @saved_configs = Queri.config.dup
+        Queri.instance_variable_set(:@config, {})
+      end
+
+      after do
+        Queri.configure(@saved_configs)
+      end
+
+      it "should raise LoadError" do
+        expect{ subject }.to raise_error(LoadError)
+      end
+    end
+
+    context "with configurations" do
+
+      before do
+        Queri.configure_with(File.join(File.dirname(__FILE__), 'config.yml'))
+        report.stub(:class).and_return( Queri::Realtime::Queues )
+      end
+
+      it "should respond" do
+        expect{ subject }.to_not raise_error
+      end
+
+      it "should call the XMLRPC client" do
+        xml_client = Queri.class_variable_get(:@@server)
+        Queri.class_variable_set(:@@server, @client)
+        subject
+        @client.should have_received(:call)
+        Queri.class_variable_set(:@@server, xml_client)
+      end
+
+      context "given no arguments" do
+        subject { Queri.send_request }
+
+        it "should raise ArgumentError" do
+          expect{ subject }.to raise_error(ArgumentError)
+        end
+      end
+
+      context "given an empty queues array" do
+        subject { Queri.send_request([], report) }
+
+        it "should raise ArgumentError" do
+          expect{ subject }.to raise_error(ArgumentError)
+        end
+      end
+
+      context "given a Stats report object" do
+        context "and period_start or period_end are nil" do
+          let(:report) { double(Queri::Stats::AnsweredCalls::AllCalls) }
+          let(:period_start) { Time.now - 10 }
+          let(:period_end) { nil }
+
+          subject { Queri.send_request(queues, report, period_start, period_end) }
+
+          it "should raise ArgumentError" do
+            expect{ subject }.to raise_error(ArgumentError)
+          end
+        end
+      end
+
+      context "given a Realtime report object" do
+        context "and period_start or period_end are not nil" do
+          let(:period_start) { Time.now - 10 }
+          let(:period_end) { nil }
+
+          subject { Queri.send_request(queues, report, period_start, period_end) }
+
+          it "should raise ArgumentError" do
+            expect{ subject }.to raise_error(ArgumentError)
+          end
+        end
+      end
+    end
+  end
+end

data/spec/realtime/agents_spec.rb

@@ -0,0 +1,18 @@
+require File.join( File.dirname(__FILE__), '..', 'spec_helper' )
+
+describe Queri::Realtime::Agents do
+  let(:report_class) { Queri::Realtime::Agents }
+  let(:xml_code) { report_class.xml_code }
+
+  it_behaves_like "a report class"
+
+  it_behaves_like "a report method"
+
+  it_behaves_like "a queuemetrics report"
+
+  it_behaves_like "a realtime report"
+
+  describe "An instance of", Queri::Realtime::Agents do
+    it_behaves_like "a realtime report instance"
+  end
+end

data/spec/realtime/queues_spec.rb

@@ -0,0 +1,18 @@
+require File.join( File.dirname(__FILE__), '..', 'spec_helper' )
+
+describe Queri::Realtime::Queues do
+  let(:report_class) { Queri::Realtime::Queues }
+  let(:xml_code) { report_class.xml_code }
+
+  it_behaves_like "a report class"
+
+  it_behaves_like "a report method"
+
+  it_behaves_like "a queuemetrics report"
+
+  it_behaves_like "a realtime report"
+
+  describe "An instance of", Queri::Realtime::Queues do
+    it_behaves_like "a realtime report instance"
+  end
+end

data/spec/realtime/realtime_spec.rb

@@ -0,0 +1,10 @@
+require File.join( File.dirname(__FILE__), '..', 'spec_helper' )
+
+describe Queri::Realtime do
+  let(:report_method) { Queri::Realtime }
+  let(:report_class) { Queri::Realtime }
+
+  it_behaves_like "a report method"
+
+  it_behaves_like "a report class"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'queri'
+Dir[File.join( File.dirname(__FILE__), 'support', '**', '*.rb' )].each {|f| require f}
+#require File.join(File.dirname(__FILE__), '..', 'lib', 'queuemetrics.rb')
+
+RSpec.configure do |config|
+  include TimeHelper
+  include Constantize
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+end

data/spec/stats/agents_and_sessions/agent_availability_spec.rb

@@ -0,0 +1,18 @@
+require File.join( File.dirname(__FILE__), '..', '..', 'spec_helper' )
+
+describe Queri::Stats::AgentsAndSessions::AgentAvailability do
+  let(:report_class) { Queri::Stats::AgentsAndSessions::AgentAvailability }
+  let(:xml_code) { report_class.xml_code }
+
+  it_behaves_like "a report class"
+
+  it_behaves_like "a report method"
+
+  it_behaves_like "a queuemetrics report"
+
+  it_behaves_like "a stats report"
+
+  describe "An instance of", Queri::Stats::AgentsAndSessions::AgentAvailability do
+    it_behaves_like "an agent-level report instance"
+  end
+end

data/spec/stats/agents_and_sessions/agents_and_sessions_spec.rb

@@ -0,0 +1,7 @@
+require File.join( File.dirname(__FILE__), '..', '..', 'spec_helper' )
+
+describe Queri::Stats::AgentsAndSessions do
+  let(:report_class) { Queri::Stats::AgentsAndSessions }
+
+  it_behaves_like "a report class"
+end

data/spec/stats/answered_calls/agents_on_queue_spec.rb

@@ -0,0 +1,18 @@
+require File.join( File.dirname(__FILE__), '..', '..', 'spec_helper' )
+
+describe Queri::Stats::AnsweredCalls::AgentsOnQueue do
+  let(:report_class) { Queri::Stats::AnsweredCalls::AgentsOnQueue }
+  let(:xml_code) { report_class.xml_code }
+
+  it_behaves_like "a report class"
+
+  it_behaves_like "a report method"
+
+  it_behaves_like "a queuemetrics report"
+
+  it_behaves_like "a stats report"
+
+  describe "An instance of", Queri::Stats::AnsweredCalls::AgentsOnQueue do
+    it_behaves_like "an agent-level report instance"
+  end
+end

data/spec/stats/answered_calls/all_calls_spec.rb

@@ -0,0 +1,18 @@
+require File.join( File.dirname(__FILE__), '..', '..', 'spec_helper' )
+
+describe Queri::Stats::AnsweredCalls::AllCalls do
+  let(:report_class) { Queri::Stats::AnsweredCalls::AllCalls }
+  let(:xml_code) { report_class.xml_code }
+
+  it_behaves_like "a report class"
+
+  it_behaves_like "a report method"
+
+  it_behaves_like "a queuemetrics report"
+
+  it_behaves_like "a stats report"
+
+  describe "An instance of", Queri::Stats::AnsweredCalls::AllCalls do
+    it_behaves_like "an aggregate report instance"
+  end
+end

data/spec/stats/answered_calls/answered_calls_spec.rb

@@ -0,0 +1,7 @@
+require File.join( File.dirname(__FILE__), '..', '..', 'spec_helper' )
+
+describe Queri::Stats::AnsweredCalls do
+  let(:report_class) { Queri::Stats::AnsweredCalls }
+
+  it_behaves_like "a report class"
+end

data/spec/stats/stats_spec.rb

@@ -0,0 +1,7 @@
+require File.join( File.dirname(__FILE__), '..', 'spec_helper' )
+
+describe Queri::Stats do
+  let(:report_class) { Queri::Stats }
+
+  it_behaves_like "a report method"
+end

data/spec/stats/unanswered_calls/all_calls_spec.rb

@@ -0,0 +1,18 @@
+require File.join( File.dirname(__FILE__), '..', '..', 'spec_helper' )
+
+describe Queri::Stats::UnansweredCalls::AllCalls do
+  let(:report_class) { Queri::Stats::UnansweredCalls::AllCalls }
+  let(:xml_code) { report_class.xml_code }
+
+  it_behaves_like "a report class"
+
+  it_behaves_like "a report method"
+
+  it_behaves_like "a queuemetrics report"
+
+  it_behaves_like "a stats report"
+
+  describe "An instance of", Queri::Stats::UnansweredCalls::AllCalls do
+    it_behaves_like "an aggregate report instance"
+  end
+end

data/spec/stats/unanswered_calls/unanswered_calls_spec.rb

@@ -0,0 +1,7 @@
+require File.join( File.dirname(__FILE__), '..', '..', 'spec_helper' )
+
+describe Queri::Stats::UnansweredCalls do
+  let(:report_class) { Queri::Stats::UnansweredCalls }
+
+  it_behaves_like "a report class"
+end

data/spec/support/constantize.rb

@@ -0,0 +1,27 @@
+module Constantize
+  def constantize(camel_cased_word)
+    names = camel_cased_word.split('::')
+    names.shift if names.empty? || names.first.empty?
+
+    names.inject(Object) do |constant, name|
+      if constant == Object
+        constant.const_get(name)
+      else
+        candidate = constant.const_get(name)
+        next candidate if constant.const_defined?(name, false)
+        next candidate unless Object.const_defined?(name)
+
+        # Go down the ancestors to check it it's owned
+        # directly before we reach Object or the end of ancestors.
+        constant = constant.ancestors.inject do |const, ancestor|
+          break const    if ancestor == Object
+          break ancestor if ancestor.const_defined?(name, false)
+          const
+        end
+
+        # owner is in Object, so raise
+        constant.const_get(name, false)
+      end
+    end
+  end
+end

data/spec/support/shared/shared_examples_for_agent_level_report_instance.rb

@@ -0,0 +1,37 @@
+shared_examples "an agent-level report instance" do
+  let(:queues) { ["10000"] }
+  let(:period_start) { Time.now - 7200 }
+  let(:period_end) { Time.now - 3600 }
+
+  before do
+    @client = double(XMLRPC::Client)
+    @client.stub(:call).and_return( {xml_code => [report_class.keys]} )
+  end
+
+  subject { report_class.new(queues, period_start, period_end) }
+
+  it { should_not respond_to :response= }
+
+  describe "#response" do
+    subject { report_class.new(queues, period_start, period_end).response }
+
+    it "should respond" do
+      XMLRPC::Client.stub(:new).and_return(@client)
+      expect{ subject }.to_not raise_error
+    end
+
+    it "should be an Array" do
+      XMLRPC::Client.stub(:new).and_return(@client)
+      subject.should be_a Array
+    end
+
+    context "for a period during which records are saved" do
+      let(:period_start) { most_recent_11_am_hour }
+      let(:period_end) { most_recent_12_pm_hour }
+
+      it "should contain Hashes" do
+        subject.each {|obj| obj.should be_a Hash}
+      end
+    end
+  end
+end

data/spec/support/shared/shared_examples_for_aggregate_report_instance.rb

@@ -0,0 +1,37 @@
+shared_examples "an aggregate report instance" do
+  let(:queues) { ["10000"] }
+  let(:period_start) { Time.now - 7200 }
+  let(:period_end) { Time.now - 3600 }
+
+  before do
+    @client = double(XMLRPC::Client)
+    @client.stub(:call).and_return( {xml_code => []} )
+  end
+
+  subject { report_class.new(queues, period_start, period_end) }
+
+  it { should_not respond_to :response= }
+
+  describe "#response" do
+    subject { report_class.new(queues, period_start, period_end).response }
+
+    it "should respond" do
+      XMLRPC::Client.stub(:new).and_return(@client)
+      expect{ subject }.to_not raise_error
+    end
+
+    it "should be a Hash" do
+      XMLRPC::Client.stub(:new).and_return(@client)
+      subject.should be_a Hash
+    end
+
+    context "for a period during which records are saved" do
+      let(:period_start) { most_recent_11_am_hour }
+      let(:period_end) { most_recent_12_pm_hour }
+
+      it "should not be an empty Hash" do
+        subject.should_not be_empty
+      end
+    end
+  end
+end