punchblock 0.4.0

data/lib/punchblock/event/joined.rb

@@ -0,0 +1,50 @@
+module Punchblock
+  class Event
+    class Joined < Event
+      register :joined, :core
+
+      ##
+      # Create a joined event
+      #
+      # @param [Hash] options
+      # @option options [String, Optional] :other_call_id the call ID that was joined
+      # @option options [String, Optional] :mixer_id the mixer name that was joined
+      #
+      # @return [Event::Joined] a formatted Rayo joined event
+      #
+      def self.new(options = {})
+        super().tap do |new_node|
+          options.each_pair { |k,v| new_node.send :"#{k}=", v }
+        end
+      end
+
+      ##
+      # @return [String] the call ID that was joined
+      def other_call_id
+        read_attr :'call-id'
+      end
+
+      ##
+      # @param [String] other the call ID that was joined
+      def other_call_id=(other)
+        write_attr :'call-id', other
+      end
+
+      ##
+      # @return [String] the mixer name that was joined
+      def mixer_id
+        read_attr :'mixer-id'
+      end
+
+      ##
+      # @param [String] other the mixer name that was joined
+      def mixer_id=(other)
+        write_attr :'mixer-id', other
+      end
+
+      def inspect_attributes # :nodoc:
+        [:other_call_id, :mixer_id] + super
+      end
+    end # Joined
+  end
+end # Punchblock

data/lib/punchblock/event/offer.rb

@@ -0,0 +1,29 @@
+module Punchblock
+  class Event
+    class Offer < Event
+      register :offer, :core
+
+      include HasHeaders
+
+      def to
+        read_attr :to
+      end
+
+      def to=(offer_to)
+        write_attr :to, offer_to
+      end
+
+      def from
+        read_attr :from
+      end
+
+      def from=(offer_from)
+        write_attr :from, offer_from
+      end
+
+      def inspect_attributes # :nodoc:
+        [:to, :from] + super
+      end
+    end # Offer
+  end
+end # Punchblock

data/lib/punchblock/event/ringing.rb

@@ -0,0 +1,7 @@
+module Punchblock
+  class Event
+    class Ringing < Event
+      register :ringing, :core
+    end # End
+  end # Event
+end # Punchblock

data/lib/punchblock/event/unjoined.rb

@@ -0,0 +1,50 @@
+module Punchblock
+  class Event
+    class Unjoined < Event
+      register :unjoined, :core
+
+      ##
+      # Create an unjoined event
+      #
+      # @param [Hash] options
+      # @option options [String, Optional] :other_call_id the call ID that was unjoined
+      # @option options [String, Optional] :mixer_id the mixer name that was unjoined
+      #
+      # @return [Event::Unjoined] a formatted Rayo unjoined event
+      #
+      def self.new(options = {})
+        super().tap do |new_node|
+          options.each_pair { |k,v| new_node.send :"#{k}=", v }
+        end
+      end
+
+      ##
+      # @return [String] the call ID that was unjoined
+      def other_call_id
+        read_attr :'call-id'
+      end
+
+      ##
+      # @param [String] other the call ID that was unjoined
+      def other_call_id=(other)
+        write_attr :'call-id', other
+      end
+
+      ##
+      # @return [String] the mixer name that was unjoined
+      def mixer_id
+        read_attr :'mixer-id'
+      end
+
+      ##
+      # @param [String] other the mixer name that was unjoined
+      def mixer_id=(other)
+        write_attr :'mixer-id', other
+      end
+
+      def inspect_attributes # :nodoc:
+        [:other_call_id, :mixer_id] + super
+      end
+    end # Unjoined
+  end
+end # Punchblock

data/lib/punchblock/event.rb

@@ -0,0 +1,16 @@
+module Punchblock
+  class Event < RayoNode
+  end
+end
+
+%w{
+  answered
+  complete
+  dtmf
+  end
+  info
+  joined
+  offer
+  ringing
+  unjoined
+}.each { |e| require "punchblock/event/#{e}"}

data/lib/punchblock/generic_connection.rb

@@ -0,0 +1,18 @@
+module Punchblock
+  class GenericConnection
+    attr_accessor :event_queue
+
+    ##
+    # @param [Hash] options
+    # @option options [Logger] :transport_logger The logger to which transport events will be logged
+    #
+    def initialize(options = {})
+      @event_queue = Queue.new
+      @logger = options.delete(:transport_logger) if options[:transport_logger]
+    end
+
+    def connected
+      'CONNECTED'
+    end
+  end
+end

data/lib/punchblock/has_headers.rb

@@ -0,0 +1,34 @@
+module Punchblock
+  module HasHeaders
+    ##
+    # @return [Hash] hash of key-value pairs of headers
+    #
+    def headers_hash
+      headers.inject({}) do |hash, header|
+        hash[header.name] = header.value
+        hash
+      end
+    end
+
+    ##
+    # @return [Array[Header]] headers
+    #
+    def headers
+      find('//ns:header', :ns => self.class.registered_ns).map do |i|
+        Header.new i
+      end
+    end
+
+    ##
+    # @param [Hash, Array] headers A hash of key-value header pairs, or an array of Header objects
+    #
+    def headers=(headers)
+      find('//ns:header', :ns => self.class.registered_ns).each &:remove
+      if headers.is_a? Hash
+        headers.each_pair { |k,v| self << Header.new(k, v) }
+      elsif headers.is_a? Array
+        [headers].flatten.each { |i| self << Header.new(i) }
+      end
+    end
+  end
+end

data/lib/punchblock/header.rb

@@ -0,0 +1,47 @@
+module Punchblock
+  class Header < RayoNode
+    ##
+    # @param [String] name
+    # @param [String] value
+    #
+    def self.new(name, value = '')
+      super(:header).tap do |new_node|
+        case name
+        when Nokogiri::XML::Node
+          new_node.inherit name
+        else
+          new_node.name = name
+          new_node.value = value
+        end
+      end
+    end
+
+    # The Header's name
+    # @return [Symbol]
+    def name
+      read_attr(:name).gsub('-', '_').to_sym
+    end
+
+    # Set the Header's name
+    # @param [Symbol] name the new name for the header
+    def name=(name)
+      write_attr :name, name.to_s.gsub('_', '-')
+    end
+
+    # The Header's value
+    # @return [String]
+    def value
+      read_attr :value
+    end
+
+    # Set the Header's value
+    # @param [String] value the new value for the header
+    def value=(value)
+      write_attr :value, value
+    end
+
+    def inspect_attributes # :nodoc:
+      [:name, :value] + super
+    end
+  end
+end # Punchblock

data/lib/punchblock/media_container.rb

@@ -0,0 +1,39 @@
+module Punchblock
+  module MediaContainer
+    ##
+    # @return [String] the TTS voice to use
+    #
+    def voice
+      read_attr :voice
+    end
+
+    ##
+    # @param [String] voice to use when rendering TTS
+    #
+    def voice=(voice)
+      write_attr :voice, voice
+    end
+
+    ##
+    # @return [String] the SSML document to render TTS
+    #
+    def ssml
+      children.to_xml
+    end
+
+    ##
+    # @param [String] ssml the SSML document to render TTS
+    #
+    def ssml=(ssml)
+      if ssml.instance_of?(String)
+        self << RayoNode.new('').parse(ssml) do |config|
+          config.noblanks.strict
+        end
+      end
+    end
+
+    def inspect_attributes # :nodoc:
+      [:voice, :ssml] + super
+    end
+  end
+end

data/lib/punchblock/media_node.rb

@@ -0,0 +1,17 @@
+module Punchblock
+  class MediaNode < RayoNode
+    include MediaContainer
+
+    def self.new(options = {})
+      super().tap do |new_node|
+        case options
+        when Hash
+          new_node << options.delete(:text) if options[:text]
+          options.each_pair { |k,v| new_node.send :"#{k}=", v }
+        when Nokogiri::XML::Element
+          new_node.inherit options
+        end
+      end
+    end
+  end
+end

data/lib/punchblock/protocol_error.rb

@@ -0,0 +1,16 @@
+module Punchblock
+  ##
+  # This exception may be raised if a transport error is detected.
+  class ProtocolError < StandardError
+    attr_accessor :name, :text, :call_id, :component_id
+
+    def initialize(name = nil, text = nil, call_id = nil, component_id = nil)
+      @name, @text, @call_id, @component_id = name, text, call_id, component_id
+    end
+
+    def to_s
+      "#<#{self.class}: name=#{name.inspect} text=#{text.inspect} call_id=#{call_id.inspect} component_id=#{component_id.inspect}>"
+    end
+    alias :inspect :to_s
+  end
+end

data/lib/punchblock/rayo_node.rb

@@ -0,0 +1,88 @@
+require 'active_support/core_ext/class/attribute'
+require 'niceogiri'
+
+module Punchblock
+  class RayoNode < Niceogiri::XML::Node
+    @@registrations = {}
+
+    class_attribute :registered_ns, :registered_name
+
+    attr_accessor :call_id, :component_id, :connection, :original_component
+
+    # Register a new stanza class to a name and/or namespace
+    #
+    # This registers a namespace that is used when looking
+    # up the class name of the object to instantiate when a new
+    # stanza is received
+    #
+    # @param [#to_s] name the name of the node
+    # @param [String, nil] ns the namespace the node belongs to
+    def self.register(name, ns = nil)
+      self.registered_name = name.to_s
+      self.registered_ns = ns.is_a?(Symbol) ? RAYO_NAMESPACES[ns] : ns
+      @@registrations[[self.registered_name, self.registered_ns]] = self
+    end
+
+    # Find the class to use given the name and namespace of a stanza
+    #
+    # @param [#to_s] name the name to lookup
+    # @param [String, nil] xmlns the namespace the node belongs to
+    # @return [Class, nil] the class appropriate for the name/ns combination
+    def self.class_from_registration(name, ns = nil)
+      @@registrations[[name.to_s, ns]]
+    end
+
+    # Import an XML::Node to the appropriate class
+    #
+    # Looks up the class the node should be then creates it based on the
+    # elements of the XML::Node
+    # @param [XML::Node] node the node to import
+    # @return the appropriate object based on the node name and namespace
+    def self.import(node, call_id = nil, component_id = nil)
+      ns = (node.namespace.href if node.namespace)
+      klass = class_from_registration(node.element_name, ns)
+      event = if klass && klass != self
+        klass.import node, call_id, component_id
+      else
+        new.inherit node
+      end
+      event.tap do |event|
+        event.call_id = call_id
+        event.component_id = component_id
+      end
+    end
+
+    # Create a new Node object
+    #
+    # @param [String, nil] name the element name
+    # @param [XML::Document, nil] doc the document to attach the node to. If
+    # not provided one will be created
+    # @return a new object with the registered name and namespace
+    def self.new(name = registered_name, doc = nil)
+      super name, doc, registered_ns
+    end
+
+    def inspect_attributes # :nodoc:
+      [:call_id, :component_id]
+    end
+
+    def inspect
+      "#<#{self.class} #{inspect_attributes.map { |c| "#{c}=#{self.__send__(c).inspect}" rescue nil }.compact * ', '}>"
+    end
+
+    def eql?(o, *fields)
+      super o, *(fields + inspect_attributes)
+    end
+
+    ##
+    # @return [RayoNode] the original command issued that lead to this event
+    #
+    def source
+      @source ||= connection.original_component_from_id component_id if connection && component_id
+      @source ||= original_component
+    end
+
+    alias :to_s :inspect
+    alias :xmlns :namespace_href
+  end
+end

data/lib/punchblock/ref.rb

@@ -0,0 +1,26 @@
+module Punchblock
+  ##
+  # An rayo Ref message. This provides the command ID in response to execution of a command.
+  #
+  class Ref < RayoNode
+    register :ref, :core
+
+    ##
+    # @return [String] the command ID
+    #
+    def id
+      read_attr :id
+    end
+
+    ##
+    # @param [String] ref_id the command ID
+    #
+    def id=(ref_id)
+      write_attr :id, ref_id
+    end
+
+    def inspect_attributes # :nodoc:
+      [:id] + super
+    end
+  end # Offer
+end # Punchblock

data/lib/punchblock/version.rb

@@ -0,0 +1,3 @@
+module Punchblock
+  VERSION = "0.4.0"
+end

data/lib/punchblock.rb

@@ -0,0 +1,42 @@
+require 'active_support/dependencies/autoload'
+require 'active_support/core_ext/object/blank'
+require 'future-resource'
+
+module Punchblock
+  extend ActiveSupport::Autoload
+
+  autoload :Command
+  autoload :CommandNode
+  autoload :Component
+  autoload :Connection
+  autoload :DSL
+  autoload :GenericConnection
+  autoload :HasHeaders
+  autoload :Header
+  autoload :MediaContainer
+  autoload :MediaNode
+  autoload :ProtocolError
+  autoload :RayoNode
+
+  ##
+  # This exception may be raised if a transport error is detected.
+  TransportError = Class.new StandardError
+
+  BASE_RAYO_NAMESPACE   = 'urn:xmpp:rayo'
+  BASE_TROPO_NAMESPACE  = 'urn:xmpp:tropo'
+  RAYO_VERSION          = '1'
+  RAYO_NAMESPACES       = {:core => [BASE_RAYO_NAMESPACE, RAYO_VERSION].compact.join(':')}
+
+  [:ext, :record, :output, :input].each do |ns|
+    RAYO_NAMESPACES[ns] = [BASE_RAYO_NAMESPACE, ns.to_s, RAYO_VERSION].compact.join(':')
+    RAYO_NAMESPACES[:"#{ns}_complete"] = [BASE_RAYO_NAMESPACE, ns.to_s, 'complete', RAYO_VERSION].compact.join(':')
+  end
+
+  [:ask, :conference, :say, :transfer].each do |ns|
+    RAYO_NAMESPACES[ns] = [BASE_TROPO_NAMESPACE, ns.to_s, RAYO_VERSION].compact.join(':')
+    RAYO_NAMESPACES[:"#{ns}_complete"] = [BASE_TROPO_NAMESPACE, ns.to_s, 'complete', RAYO_VERSION].compact.join(':')
+  end
+end
+
+require 'punchblock/event'
+require 'punchblock/ref'

data/punchblock.gemspec

@@ -0,0 +1,42 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "punchblock/version"
+
+Gem::Specification.new do |s|
+  s.name        = %q{punchblock}
+  s.version     = Punchblock::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.licenses    = ["MIT"]
+  s.authors     = ["Jason Goecke", "Ben Klang", "Ben Langfeld"]
+  s.email       = %q{punchblock@adhearsion.com}
+  s.homepage    = %q{http://github.com/adhearsion/punchblock}
+  s.summary     = "Punchblock is a telephony middleware library"
+  s.description = "Like Rack is to Rails and Sinatra, Punchblock provides a consistent API on top of several underlying third-party call control protocols."
+
+  s.rubyforge_project = "punchblock"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.3.7") if s.respond_to? :required_rubygems_version=
+
+  s.add_runtime_dependency %q<niceogiri>, [">= 0.0.4"]
+  s.add_runtime_dependency %q<blather>, [">= 0.5.3"]
+  s.add_runtime_dependency %q<pry>, [">= 0.8.3"]
+  s.add_runtime_dependency %q<activesupport>, [">= 2.1.0"]
+  s.add_runtime_dependency %q<state_machine>, [">= 1.0.1"]
+  s.add_runtime_dependency %q<future-resource>, [">= 0.0.2"]
+
+  s.add_development_dependency %q<bundler>, ["~> 1.0.0"]
+  s.add_development_dependency %q<rspec>, ["~> 2.3.0"]
+  s.add_development_dependency %q<ci_reporter>, [">= 1.6.3"]
+  s.add_development_dependency %q<yard>, ["~> 0.6.0"]
+  s.add_development_dependency %q<bluecloth>, [">= 0"]
+  s.add_development_dependency %q<rcov>, [">= 0"]
+  s.add_development_dependency %q<rake>, [">= 0"]
+  s.add_development_dependency %q<mocha>, [">= 0"]
+  s.add_development_dependency %q<i18n>, [">= 0"]
+  s.add_development_dependency %q<countdownlatch>, [">= 0"]
+end

data/spec/punchblock/command/accept_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+
+module Punchblock
+  module Command
+    describe Accept do
+      it 'registers itself' do
+        RayoNode.class_from_registration(:accept, 'urn:xmpp:rayo:1').should == Accept
+      end
+
+      it_should_behave_like 'command_headers'
+    end
+  end
+end # Punchblock

data/spec/punchblock/command/answer_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+
+module Punchblock
+  module Command
+    describe Answer do
+      it 'registers itself' do
+        RayoNode.class_from_registration(:answer, 'urn:xmpp:rayo:1').should == Answer
+      end
+
+      it_should_behave_like 'command_headers'
+    end
+  end
+end # Punchblock

data/spec/punchblock/command/dial_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+
+%w{
+  blather/client/dsl
+  punchblock/core_ext/blather/stanza
+  punchblock/core_ext/blather/stanza/presence
+}.each { |f| require f }
+
+module Punchblock
+  module Command
+    describe Dial do
+
+      it 'registers itself' do
+        RayoNode.class_from_registration(:dial, 'urn:xmpp:rayo:1').should == Dial
+      end
+
+      describe "when setting options in initializer" do
+        let(:join_params) { {:other_call_id => 'abc123'} }
+
+        subject { Dial.new :to => 'tel:+14155551212', :from => 'tel:+13035551212', :headers => { :x_skill => 'agent', :x_customer_id => 8877 }, :join => join_params }
+
+        it_should_behave_like 'command_headers'
+
+        its(:to)    { should == 'tel:+14155551212' }
+        its(:from)  { should == 'tel:+13035551212' }
+        its(:join)  { should == Join.new(join_params) }
+      end
+
+      describe "#response=" do
+        before { subject.request! }
+
+        let(:call_id) { 'abc123' }
+
+        let :ref do
+          Ref.new.tap do |ref|
+            ref.id = call_id
+          end
+        end
+
+        let :iq do
+          Blather::Stanza::Iq.new(:result, 'blah').tap do |iq|
+            iq.from = "call.rayo.net"
+            iq << ref
+          end
+        end
+
+        it "should set the call ID from the ref" do
+          subject.response = iq
+          subject.call_id.should == call_id
+        end
+      end
+    end
+  end
+end # Punchblock

data/spec/punchblock/command/hangup_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+
+module Punchblock
+  module Command
+    describe Hangup do
+      it 'registers itself' do
+        RayoNode.class_from_registration(:hangup, 'urn:xmpp:rayo:1').should == Hangup
+      end
+
+      it_should_behave_like 'command_headers'
+    end
+  end
+end # Punchblock

data/spec/punchblock/command/join_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+module Punchblock
+  module Command
+    describe Join do
+
+      it 'registers itself' do
+        RayoNode.class_from_registration(:join, 'urn:xmpp:rayo:1').should == Join
+      end
+
+      describe "when setting options in initializer" do
+        subject { Join.new :other_call_id => 'abc123', :mixer_id => 'blah', :direction => :duplex, :media => :bridge }
+
+        its(:other_call_id) { should == 'abc123' }
+        its(:mixer_id)      { should == 'blah' }
+        its(:direction)     { should == :duplex }
+        its(:media)         { should == :bridge }
+      end
+    end
+  end
+end # Punchblock

data/spec/punchblock/command/mute_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+module Punchblock
+  module Command
+    describe Mute do
+      it 'registers itself' do
+        RayoNode.class_from_registration(:mute, 'urn:xmpp:rayo:1').should == Mute
+      end
+    end
+  end
+end # Punchblock