punchblock 0.4.0

data/lib/punchblock/component/tropo/transfer.rb

@@ -0,0 +1,178 @@
+module Punchblock
+  module Component
+    module Tropo
+      class Transfer < ComponentNode
+        register :transfer, :transfer
+
+        include HasHeaders
+
+        ##
+        # Creates an Rayo transfer command
+        #
+        # @param [Hash] options for transferring a call
+        # @option options [String, Array[String]] :to The destination(s) for the call transfer (ie - tel:+14155551212 or sip:you@sip.tropo.com). Can be an array to hunt.
+        # @option options [String] :from The caller ID for the call transfer (ie - tel:+14155551212 or sip:you@sip.tropo.com)
+        # @option options [String, Optional] :terminator The string key press required to abort the transfer.
+        # @option options [Integer, Optional] :timeout How long to wait - in seconds - for an answer, busy signal, or other event to occur.
+        # @option options [Boolean, Optional] :answer_on_media If set to true, the call will be considered "answered" and audio will begin playing as soon as media is received from the far end (ringing / busy signal / etc)
+        # @option options [Symbol, Optional] :media Rules for handling media. Can be :direct, where parties negotiate media directly, or :bridge where the media server will bridge audio, allowing media features like recording and ASR.
+        # @option options [Ring, Hash, Optional] :ring to play to the caller untill connected
+        #
+        # @return [Message::Transfer] an Rayo "transfer" message
+        #
+        # @example
+        #   Transfer.new(:to => 'sip:you@yourdomain.com', :from => 'sip:myapp@mydomain.com', :terminator => '#').to_xml
+        #
+        #   returns:
+        #     <transfer xmlns="urn:xmpp:tropo:transfer:1" from="sip:myapp@mydomain.com" terminator="#">
+        #       <to>sip:you@yourdomain.com</to>
+        #     </transfer>
+        #
+        def self.new(options = {})
+          super().tap do |new_node|
+            options.each_pair { |k,v| new_node.send :"#{k}=", v }
+          end
+        end
+
+        ##
+        # @return [Array[String]] The destination(s) for the call transfer
+        #
+        def to
+          find('ns:to', :ns => self.class.registered_ns).map &:text
+        end
+
+        ##
+        # @param [String, Array[String]] :to The destination(s) for the call transfer (ie - tel:+14155551212 or sip:you@sip.tropo.com). Can be an array to hunt.
+        #
+        def to=(transfer_to)
+          find('//ns:to', :ns => self.class.registered_ns).each &:remove
+          if transfer_to
+            [transfer_to].flatten.each do |i|
+              to = RayoNode.new :to
+              to << i
+              self << to
+            end
+          end
+        end
+
+        ##
+        # @return [String] The caller ID for the call transfer
+        #
+        def from
+          read_attr :from
+        end
+
+        ##
+        # @param [String, Array[String]] :to The destination(s) for the call transfer (ie - tel:+14155551212 or sip:you@sip.tropo.com). Can be an array to hunt.
+        #
+        def from=(transfer_from)
+          write_attr :from, transfer_from
+        end
+
+        ##
+        # @return [String] The string key press required to abort the transfer.
+        #
+        def terminator
+          read_attr :terminator
+        end
+
+        ##
+        # @param [String] terminator The string key press required to abort the transfer.
+        #
+        def terminator=(terminator)
+          write_attr :terminator, terminator
+        end
+
+        ##
+        # @return [Integer] How long to wait - in seconds - for an answer, busy signal, or other event to occur.
+        #
+        def timeout
+          read_attr :timeout, :to_i
+        end
+
+        ##
+        # @param [Integer] timeout How long to wait - in seconds - for an answer, busy signal, or other event to occur.
+        #
+        def timeout=(timeout)
+          write_attr :timeout, timeout
+        end
+
+        ##
+        # @return [Boolean] If true, the call will be considered "answered" and audio will begin playing as soon as media is received from the far end (ringing / busy signal / etc)
+        #
+        def answer_on_media
+          read_attr('answer-on-media') == 'true'
+        end
+
+        ##
+        # @param [Boolean] aom If set to true, the call will be considered "answered" and audio will begin playing as soon as media is received from the far end (ringing / busy signal / etc)
+        #
+        def answer_on_media=(aom)
+          write_attr 'answer-on-media', aom.to_s
+        end
+
+        ##
+        # @return [Symbol] Rules for handling media. Can be :direct, where parties negotiate media directly, or :bridge where the media server will bridge audio, allowing media features like recording and ASR.
+        #
+        def media
+          read_attr 'media', :to_sym
+        end
+
+        ##
+        # @param [Symbol] media Rules for handling media. Can be :direct, where parties negotiate media directly, or :bridge where the media server will bridge audio, allowing media features like recording and ASR.
+        #
+        def media=(media)
+          write_attr 'media', media
+        end
+
+        ##
+        # @return [Ring] the ringer to play to the caller while transferring
+        #
+        def ring
+          node = find_first '//ns:ring', :ns => self.registered_ns
+          Ring.new node if node
+        end
+
+        ##
+        # @param [Hash] ring
+        # @option ring [String] :text Text to speak to the caller as an announcement
+        # @option ring [String] :url URL to play to the caller as an announcement
+        #
+        def ring=(ring)
+          ring = Ring.new(ring) unless ring.is_a?(Ring)
+          self << ring
+        end
+
+        class Ring < Say
+          register :ring, :transfer
+        end
+
+        def inspect_attributes # :nodoc:
+          [:to, :from, :terminator, :timeout, :answer_on_media] + super
+        end
+
+        class Complete
+          class Success < Event::Complete::Reason
+            register :success, :transfer_complete
+          end
+
+          class Timeout < Event::Complete::Reason
+            register :timeout, :transfer_complete
+          end
+
+          class Terminator < Event::Complete::Reason
+            register :terminator, :transfer_complete
+          end
+
+          class Busy < Event::Complete::Reason
+            register :busy, :transfer_complete
+          end
+
+          class Reject < Event::Complete::Reason
+            register :reject, :transfer_complete
+          end
+        end
+      end # Transfer
+    end # Tropo
+  end # Command
+end # Punchblock

data/lib/punchblock/component/tropo.rb

@@ -0,0 +1,12 @@
+module Punchblock
+  module Component
+    module Tropo
+      extend ActiveSupport::Autoload
+
+      autoload :Ask
+      autoload :Conference
+      autoload :Say
+      autoload :Transfer
+    end
+  end # Command
+end # Punchblock

data/lib/punchblock/component.rb

@@ -0,0 +1,73 @@
+module Punchblock
+  module Component
+    extend ActiveSupport::Autoload
+
+    autoload :Input
+    autoload :Output
+    autoload :Record
+    autoload :Tropo
+
+    InvalidActionError = Class.new StandardError
+
+    class ComponentNode < CommandNode
+      attr_accessor :event_queue, :complete_event, :event_callback
+
+      def initialize(*args)
+        super
+        @event_queue    = Queue.new
+        @complete_event = FutureResource.new
+        @event_callback = nil
+      end
+
+      def add_event(event)
+        event.original_component = self
+        transition_state! event
+        complete_event.resource = event if event.is_a? Event::Complete
+        if event_callback.respond_to?(:call)
+          add_event_to_queue = event_callback.call event
+        end
+        @event_queue << event unless add_event_to_queue
+      end
+
+      def transition_state!(event)
+        complete! if event.is_a? Event::Complete
+      end
+
+      def write_action(action)
+        connection.write call_id, action, component_id
+      end
+
+      def response=(other)
+        super
+        if other.is_a?(Blather::Stanza::Iq)
+          ref = other.rayo_node
+          if ref.is_a?(Ref)
+            @component_id = ref.id
+            @connection.record_command_id_for_iq_id @component_id, other.id
+          end
+        end
+      end
+
+      ##
+      # Create an Rayo stop message
+      #
+      # @return [Stop] an Rayo stop message
+      #
+      def stop_action
+        Stop.new :component_id => component_id, :call_id => call_id
+      end
+
+      ##
+      # Sends an Rayo stop message for the current component
+      #
+      def stop!(options = {})
+        raise InvalidActionError, "Cannot stop a #{self.class.name.split("::").last} that is not executing" unless executing?
+        stop_action.tap { |action| write_action action }
+      end
+    end
+
+    class Stop < CommandNode # :nodoc:
+      register :stop, :core
+    end
+  end # Component
+end # Punchblock

data/lib/punchblock/connection.rb

@@ -0,0 +1,209 @@
+%w{
+  timeout
+  blather/client/dsl
+  punchblock/core_ext/blather/stanza
+  punchblock/core_ext/blather/stanza/presence
+}.each { |f| require f }
+
+module Punchblock
+  class Connection < GenericConnection
+    include Blather::DSL
+
+    ##
+    # Initialize the required connection attributes
+    #
+    # @param [Hash] options
+    # @option options [String] :username client JID
+    # @option options [String] :password XMPP password
+    # @option options [String] :rayo_domain the domain on which Rayo is running
+    # @option options [Logger] :wire_logger to which all XMPP transactions will be logged
+    # @option options [Boolean, Optional] :auto_reconnect whether or not to auto reconnect
+    # @option options [Numeric, Optional] :write_timeout for which to wait on a command response
+    # @option options [Numeric, nil, Optional] :ping_period interval in seconds on which to ping the server. Nil or false to disable
+    #
+    def initialize(options = {})
+      super
+      raise ArgumentError unless @username = options.delete(:username)
+      raise ArgumentError unless options.has_key? :password
+      @rayo_domain = options[:rayo_domain] || Blather::JID.new(@username).domain
+
+      setup @username, options.delete(:password)
+
+      @callmap = {} # This hash maps call IDs to their XMPP domain.
+
+      @component_id_to_iq_id = {}
+      @iq_id_to_command = {}
+
+      @auto_reconnect = !!options[:auto_reconnect]
+      @reconnect_attempts = 0
+
+      @write_timeout = options[:write_timeout] || 3
+
+      @ping_period = options.has_key?(:ping_period) ? options[:ping_period] : 60
+
+      Blather.logger = options.delete(:wire_logger) if options.has_key?(:wire_logger)
+    end
+
+    ##
+    # Write a command to the Rayo server for a particular call
+    #
+    # @param [String] call the call ID on which to act
+    # @param [CommandNode] cmd the command to execute on the call
+    # @param [String, Optional] component_id the component_id on which to execute
+    #
+    # @raise Exception if there is a server-side error
+    #
+    # @return true
+    #
+    def write(call_id, cmd, component_id = nil)
+      async_write call_id, cmd, component_id
+      cmd.response(@write_timeout).tap { |result| raise result if result.is_a? Exception }
+    end
+
+    ##
+    # @return [Queue] Pop this queue to determine result of command execution. Will be true or an exception
+    def async_write(call_id, cmd, component_id = nil)
+      iq = prep_command_for_execution call_id, cmd, component_id
+      write_to_stream iq
+      cmd.request!
+    end
+
+    def prep_command_for_execution(call_id, cmd, component_id = nil)
+      cmd.connection = self
+      cmd.call_id = call_id
+      jid = cmd.is_a?(Command::Dial) ? @rayo_domain : "#{call_id}@#{@callmap[call_id]}"
+      jid << "/#{component_id}" if component_id
+      create_iq(jid).tap do |iq|
+        @logger.debug "Sending IQ ID #{iq.id} #{cmd.inspect} to #{jid}" if @logger
+        iq << cmd
+        @iq_id_to_command[iq.id] = cmd
+      end
+    end
+
+    ##
+    # Fire up the connection
+    #
+    def run
+      register_handlers
+      connect
+    end
+
+    def connect
+      begin
+        EM.run { client.run }
+      rescue Blather::SASLError, Blather::StreamError => e
+        raise ProtocolError.new(e.class.to_s, e.message)
+      end
+    end
+
+    def stop
+      @reconnect_attempts = nil
+      client.close
+    end
+
+    def connected?
+      client.connected?
+    end
+
+    ##
+    #
+    # Get the original command issued by command ID
+    #
+    # @param [String] component_id
+    #
+    # @return [RayoNode]
+    #
+    def original_component_from_id(component_id)
+      @iq_id_to_command[@component_id_to_iq_id[component_id]]
+    end
+
+    def record_command_id_for_iq_id(command_id, iq_id)
+      @component_id_to_iq_id[command_id] = iq_id
+    end
+
+    private
+
+    def handle_presence(p)
+      throw :pass unless p.rayo_event?
+      @logger.info "Receiving event for call ID #{p.call_id}" if @logger
+      @callmap[p.call_id] = p.from.domain
+      @logger.debug p.inspect if @logger
+      event = p.event
+      event.connection = self
+      if event.source
+        event.source.add_event event
+      else
+        @event_queue.push event
+      end
+    end
+
+    def handle_iq_result(iq)
+      # FIXME: Do we need to raise a warning if the domain changes?
+      throw :pass unless command = @iq_id_to_command[iq.id]
+      @callmap[iq.from.node] = iq.from.domain
+      @logger.debug "Command #{iq.id} completed successfully" if @logger
+      command.response = iq
+    end
+
+    def handle_error(iq)
+      e = Blather::StanzaError.import iq
+
+      protocol_error = ProtocolError.new e.name, e.text, iq.call_id, iq.component_id
+
+      throw :pass unless command = @iq_id_to_command[iq.id]
+
+      command.response = protocol_error
+    end
+
+    def register_handlers
+      # Push a message to the queue and the log that we connected
+      when_ready do
+        @event_queue.push connected
+        @logger.info "Connected to XMPP as #{@username}" if @logger
+        @reconnect_attempts = 0
+        @rayo_ping = EM::PeriodicTimer.new(@ping_period) { ping_rayo } if @ping_period
+      end
+
+      disconnected do
+        @rayo_ping.cancel if @rayo_ping
+        if @auto_reconnect && @reconnect_attempts
+          timer = 30 * 2 ** @reconnect_attempts
+          @logger.warn "XMPP disconnected. Tried to reconnect #{@reconnect_attempts} times. Reconnecting in #{timer}s." if @logger
+          sleep timer
+          @logger.info "Trying to reconnect..." if @logger
+          @reconnect_attempts += 1
+          connect
+        end
+      end
+
+      # Read/handle call control messages. These are mostly just acknowledgement of commands
+      iq :result? do |msg|
+        handle_iq_result msg
+      end
+
+      # Read/handle error IQs
+      iq :error? do |e|
+        handle_error e
+      end
+
+      # Read/handle presence requests. This is how we get events.
+      presence do |msg|
+        handle_presence msg
+      end
+    end
+
+    def ping_rayo
+      client.write_with_handler Blather::Stanza::Iq::Ping.new(:set, @rayo_domain) do |response|
+        begin
+          handle_error response if response.is_a? Blather::BlatherError
+        rescue ProtocolError => e
+          raise e unless e.name == :feature_not_implemented
+        end
+      end
+    end
+
+    def create_iq(jid = nil)
+      Blather::Stanza::Iq.new :set, jid || @call_id
+    end
+  end
+end

data/lib/punchblock/core_ext/blather/stanza/presence.rb

@@ -0,0 +1,11 @@
+module Blather
+  class Stanza
+    class Presence
+      alias :event :rayo_node
+
+      def rayo_event?
+        event.is_a? Punchblock::Event
+      end
+    end
+  end
+end

data/lib/punchblock/core_ext/blather/stanza.rb

@@ -0,0 +1,26 @@
+module Blather
+  class Stanza
+    ##
+    # @return [Punchblock::RayoNode] a child of RayoNode
+    #   representing the Rayo command/event contained within the stanza
+    #
+    def rayo_node
+      first_child = children.first
+      Punchblock::RayoNode.import first_child, call_id, component_id if first_child
+    end
+
+    ##
+    # @return [String] the call ID this stanza applies to
+    #
+    def call_id
+      from.node
+    end
+
+    ##
+    # @return [String] the command ID this stanza applies to
+    #
+    def component_id
+      from.resource
+    end
+  end
+end

data/lib/punchblock/dsl.rb

@@ -0,0 +1,46 @@
+##
+# DO NOT USE THIS API!
+# This file is temporary, to help make testing Punchblock easier.
+# THIS IS IMPERMANENT AND WILL DISAPPEAR
+module Punchblock
+  class DSL
+    def initialize(protocol, call, queue) # :nodoc:
+      @protocol, @call, @queue = protocol, call, queue
+    end
+
+    def accept # :nodoc:
+      write @protocol.class::Command::Accept.new
+    end
+
+    def answer # :nodoc:
+      write @protocol.class::Command::Answer.new
+    end
+
+    def hangup # :nodoc:
+      write @protocol.class::Command::Hangup.new
+    end
+
+    def reject(reason = nil) # :nodoc:
+      write @protocol.class::Command::Reject.new(:reason => reason)
+    end
+
+    def redirect(dest) # :nodoc:
+      write @protocol.class::Command::Redirect.new(:to => dest)
+    end
+
+    def record(options = {})
+      write @protocol.class::Component::Record.new(options)
+    end
+
+    def say(string, type = :text) # :nodoc:
+      write @protocol.class::Component::Tropo::Say.new(type => string)
+      puts "Waiting on the queue..."
+      response = @queue.pop
+      # TODO: Error handling
+    end
+
+    def write(msg) # :nodoc:
+      @protocol.write @call, msg
+    end
+  end
+end

data/lib/punchblock/event/answered.rb

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

data/lib/punchblock/event/complete.rb

@@ -0,0 +1,65 @@
+module Punchblock
+  class Event
+    class Complete < Event
+      # TODO: Validate response and return response type.
+      # -----
+      # <complete xmlns="urn:xmpp:rayo:ext:1"/>
+
+      register :complete, :ext
+
+      def reason
+        element = find_first('*')
+        if element
+          RayoNode.import(element).tap do |reason|
+            reason.call_id = call_id
+            reason.component_id = component_id
+          end
+        end
+      end
+
+      def recording
+        element = find_first('//ns:recording', :ns => RAYO_NAMESPACES[:record_complete])
+        if element
+          RayoNode.import(element).tap do |recording|
+            recording.call_id = call_id
+            recording.component_id = component_id
+          end
+        end
+      end
+
+      def inspect_attributes # :nodoc:
+        [:reason, :recording] + super
+      end
+
+      class Reason < RayoNode
+        def name
+          super.to_sym
+        end
+
+        def inspect_attributes # :nodoc:
+          [:name] + super
+        end
+      end
+
+      class Stop < Reason
+        register :stop, :ext_complete
+      end
+
+      class Hangup < Reason
+        register :hangup, :ext_complete
+      end
+
+      class Error < Reason
+        register :error, :ext_complete
+
+        def details
+          text.strip
+        end
+
+        def inspect_attributes # :nodoc:
+          [:details] + super
+        end
+      end
+    end # Complete
+  end
+end # Punchblock

data/lib/punchblock/event/dtmf.rb

@@ -0,0 +1,19 @@
+module Punchblock
+  class Event
+    class DTMF < Event
+      register :dtmf, :core
+
+      def signal
+        read_attr :signal
+      end
+
+      def signal=(other)
+        write_attr :signal, other
+      end
+
+      def inspect_attributes # :nodoc:
+        [:signal] + super
+      end
+    end # End
+  end
+end # Punchblock

data/lib/punchblock/event/end.rb

@@ -0,0 +1,15 @@
+module Punchblock
+  class Event
+    class End < Event
+      register :end, :core
+
+      def reason
+        children.select { |c| c.is_a? Nokogiri::XML::Element }.first.name.to_sym
+      end
+
+      def inspect_attributes # :nodoc:
+        [:reason] + super
+      end
+    end # End
+  end
+end # Punchblock

data/lib/punchblock/event/info.rb

@@ -0,0 +1,15 @@
+module Punchblock
+  class Event
+    class Info < Event
+      register :info, :core
+
+      def event_name
+        children.select { |c| c.is_a? Nokogiri::XML::Element }.first.name.to_sym
+      end
+
+      def inspect_attributes # :nodoc:
+        [:event_name] + super
+      end
+    end # Info
+  end
+end # Punchblock