punchblock 0.4.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.gitignore

@@ -0,0 +1,12 @@
+.*.swp
+.*.swo
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.rvmrc
+.yardoc
+doc
+log/*
+spec/reports
+vendor

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--colour
+--tty

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Jason Goecke
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,31 @@
+PUNCHBLOCK
+==========
+
+Punchblock is a middleware library for telephony applications.  Like Rack is to
+Rails and Sinatra, Punchblock provides a consistent API on top of several
+underlying third-party call control protocols.
+
+Design
+------
+
+In the same spirit that inspired Rack, the Punchblock library is envisioned to
+be the single library for call control wiring. Frameworks and applications may
+take advantage of Punchblock's single API to write powerful code for managing
+calls. Punchblock is not and will not be an application framework; rather it
+only surfaces the various protocols and presents a consistent interface to its
+consumers.
+
+Supported Protocols
+-------------------
+
+Punchblock is still in very early stages so this list
+is what we plan to support:
+
+* Rayo (Tropo, Voxeo Prism)
+* AGI/AMI (Asterisk)
+* EventSocket (FreeSWITCH, maybe)
+
+Installation
+------------
+
+	gem install punchblock

data/Rakefile

@@ -0,0 +1,23 @@
+require 'rubygems'
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+require 'ci/reporter/rake/rspec'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rspec_opts = '--color'
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+  spec.rspec_opts = '--color'
+end
+
+task :default => :spec
+task :hudson => ['ci:setup:rspec', :spec]
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/assets/ozone/ask-1.0.xsd

@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<schema xmlns="http://www.w3.org/2001/XMLSchema" 
+	targetNamespace="urn:xmpp:ozone:ask:1"
+	xmlns:tns="urn:xmpp:ozone:ask:1" 
+	elementFormDefault="qualified">
+
+	<element name="ask" type="tns:askType" />
+
+	<complexType name="askType">
+		<sequence>
+			<element name="prompt" type="tns:promptItemsType" />
+			<element name="choices" type="tns:choicesType" />
+		</sequence>
+		<attribute name="bargein" type="boolean" />
+		<attribute name="min-confidence" type="tns:percentageType" />
+		<attribute name="mode" type="tns:choicesModeType" />
+		<attribute name="recognizer" type="string" />
+		<attribute name="voice" type="string" />
+		<attribute name="terminator" type="string" />		
+		<attribute name="timeout" type="float" />		
+	</complexType>
+
+	<!-- Utility Types -->
+
+	<complexType name="promptItemsType">
+		<choice minOccurs="1" maxOccurs="unbounded">
+			<element name="audio" type="tns:audioReferenceType" />
+			<any namespace="http://www.w3.org/2001/10/synthesis" />
+		</choice>
+	</complexType>
+
+	<complexType name="audioReferenceType">
+		<attribute name="url" type="anyURI" />
+	</complexType>
+
+	<complexType name="choicesType" mixed="true">
+		<attribute name="content-type" type="string" />
+		<attribute name="url" type="anyURI" />
+	</complexType>
+	
+	<simpleType name="percentageType">
+		<restriction base="int">
+			<minInclusive value="0" />
+			<maxInclusive value="100" />
+		</restriction>
+	</simpleType>
+
+	<simpleType name="choicesModeType">
+		<restriction base="NCName">
+			<enumeration value="DTMF" />
+			<enumeration value="SPEECH" />
+			<enumeration value="ANY" />
+		</restriction>
+	</simpleType>
+	
+</schema>

data/assets/ozone/conference-1.0.xsd

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<schema xmlns="http://www.w3.org/2001/XMLSchema" 
+	targetNamespace="urn:xmpp:ozone:conference:1"
+	xmlns:tns="urn:xmpp:ozone:conference:1" 
+	elementFormDefault="qualified">
+
+	<element name="conference" type="tns:conferenceType" />
+
+	<complexType name="conferenceType">
+		<attribute name="id" type="string" use="required" />
+		<attribute name="beep" type="boolean" use="optional" />
+		<attribute name="mute" type="boolean" use="optional" />
+		<attribute name="tone-passthrough" type="boolean" use="optional" />
+		<attribute name="terminator" type="string" use="optional" />
+	</complexType>
+
+</schema>

data/assets/ozone/ozone-1.0.xsd

@@ -0,0 +1,127 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<schema xmlns="http://www.w3.org/2001/XMLSchema" 
+	targetNamespace="urn:xmpp:ozone:1" 
+	xmlns:tns="urn:xmpp:ozone:1" 
+	elementFormDefault="qualified">
+
+
+	<!-- Events -->
+
+	<element name="offer" type="tns:offerType" />
+	<element name="info" type="tns:infoType" />
+	<element name="end" type="tns:endType" />
+
+	<complexType name="offerType">
+		<sequence>
+			<element name="header" type="tns:headerType" minOccurs="0" maxOccurs="unbounded" />
+		</sequence>
+		<attribute name="callId" type="anyURI" use="required" />
+		<attribute name="timestamp" type="dateTime" use="required" />
+		<attribute name="to" type="anyURI" use="required" />
+		<attribute name="from" type="anyURI" use="optional" />
+	</complexType>
+
+	<complexType name="infoType">
+		<choice>
+			<element name="answer" type="tns:empty" />
+			<element name="ring" type="tns:empty" />
+		</choice>
+	</complexType>
+
+	<complexType name="endType">
+		<sequence>
+			<element name="header" type="tns:headerType" minOccurs="0" maxOccurs="unbounded" />
+			<choice>
+				<element name="hangup" type="tns:empty" />
+				<element name="timeout" type="tns:empty" />
+				<element name="busy" type="tns:empty" />
+				<element name="reject" type="tns:empty" />
+				<element name="error" type="tns:endErrorType" />
+			</choice>
+		</sequence>
+	</complexType>
+
+	<complexType name="endErrorType" mixed="true">
+		<attribute name="code" type="int" />
+	</complexType>
+
+	<!-- Commands -->
+
+	<element name="bind" type="tns:empty" />
+	<element name="unbind" type="tns:empty" />
+	
+	<element name="answer" type="tns:answerType" />
+	<element name="redirect" type="tns:redirectType" />
+	<element name="reject" type="tns:rejectType" />
+	<element name="hangup" type="tns:hangupType" />
+	<element name="call" type="tns:callType" />
+
+	<complexType name="answerType">
+		<attribute name="timeout" type="float" />
+	</complexType>
+
+	<complexType name="redirectType">
+		<attribute name="to" type="anyURI" />
+	</complexType>
+
+	<complexType name="rejectType" mixed="true">
+		<attribute name="code" type="int" />
+	</complexType>
+
+	<complexType name="hangupType">
+		<sequence>
+			<element name="header" type="tns:headerType" minOccurs="0" maxOccurs="unbounded" />
+		</sequence>
+	</complexType>
+
+	<complexType name="callType">
+		<sequence>
+			<element name="header" type="tns:headerType" minOccurs="0" maxOccurs="unbounded" />
+			<element name="recording" type="tns:recordingType" minOccurs="0" maxOccurs="1" />
+		</sequence>		
+		<attribute name="jid" type="string" use="optional">
+			<annotation>
+				<documentation>
+					Required when used as an IQ result
+				</documentation>
+			</annotation>
+		</attribute>
+		<attribute name="to" type="anyURI" use="required" />
+		<attribute name="from" type="anyURI" use="optional" />
+		<attribute name="timeout" type="float" use="optional" />
+	</complexType>
+	
+	<!-- Utility Types -->
+
+	<complexType name="recordingType">
+		<sequence>
+			<element name="credentials" type="tns:credentialsType" minOccurs="0" />
+		</sequence>
+		<attribute name="uri" type="anyURI" use="required" />
+		<attribute name="format" type="string" use="optional" />
+		<attribute name="httpMethod" type="tns:httpMethodType" use="optional" />
+	</complexType>
+
+	<complexType name="credentialsType">
+		<attribute name="username" type="string" use="required" />
+		<attribute name="password" type="string" use="required" />
+	</complexType>
+
+	<simpleType name="httpMethodType">
+		<restriction base="NCName">
+			<enumeration value="PUT" />
+			<enumeration value="POST" />
+		</restriction>
+	</simpleType>
+
+	<complexType name="headerType" mixed="true">
+		<attribute name="name" type="anyURI" />
+	</complexType>
+
+	<simpleType name="empty">
+		<restriction base="string">
+			<enumeration value='' />
+		</restriction>
+	</simpleType>
+
+</schema>

data/assets/ozone/say-1.0.xsd

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<schema xmlns="http://www.w3.org/2001/XMLSchema" 
+	targetNamespace="urn:xmpp:ozone:say:1"
+	xmlns:tns="urn:xmpp:ozone:say:1" 
+	elementFormDefault="qualified">
+
+	<element name="say" type="tns:sayType" />
+	<element name="complete" />
+	<element name="stop" />
+	
+	<complexType name="sayType">
+		<choice minOccurs="1" maxOccurs="unbounded">
+			<element name="audio" type="tns:audioReferenceType" />
+			<any namespace="http://www.w3.org/2001/10/synthesis" />
+		</choice>
+		<attribute name="id" type="string" />
+		<attribute name="voice" type="string" />
+	</complexType>
+
+	<complexType name="audioReferenceType">
+		<attribute name="url" type="anyURI" />
+	</complexType>
+
+</schema>

data/assets/ozone/transfer-1.0.xsd

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<schema xmlns="http://www.w3.org/2001/XMLSchema" 
+	targetNamespace="urn:xmpp:ozone:say:1"
+	xmlns:tns="urn:xmpp:ozone:say:1" 
+	elementFormDefault="qualified">
+
+	<element name="transfer" type="tns:transferType" />
+
+	<complexType name="transferType">
+		<sequence>
+			<element name="header" type="tns:headerType" minOccurs="0" maxOccurs="unbounded" />
+			<choice minOccurs="1" maxOccurs="unbounded">
+				<element name="audio" type="tns:audioReferenceType" />
+				<any namespace="http://www.w3.org/2001/10/synthesis" />
+			</choice>
+		</sequence>
+		<attribute name="to" type="anyURI" use="required" />
+		<attribute name="from" type="anyURI" use="optional" />
+		<attribute name="timeout" type="float" use="optional" />
+		<attribute name="answer-on-media" type="boolean" use="optional" />
+		<attribute name="terminator" type="string" use="optional" />
+	</complexType>
+
+	<complexType name="audioReferenceType">
+		<attribute name="url" type="anyURI" />
+	</complexType>
+
+	<complexType name="headerType" mixed="true">
+		<attribute name="name" type="anyURI" />
+	</complexType>
+	
+</schema>

data/bin/punchblock-console

@@ -0,0 +1,125 @@
+#!/usr/bin/env ruby
+$:.push File.join(File.dirname(__FILE__), '..', 'lib')
+require 'rubygems'
+require 'bundler/setup'
+require 'punchblock'
+require 'pry'
+require 'logger'
+require 'optparse'
+
+include Punchblock
+
+Thread.abort_on_exception = true
+
+options = { :username => 'usera@127.0.0.1', :password => '1', :wire_log_file => 'log/rayo-wire.log', :transport_log_file => 'log/rayo-transport.log', :auto_reconnect => false }
+
+option_parser = OptionParser.new do |opts|
+  opts.banner = "Usage: punchblock-console [-u usera@127.0.0.1] [-p abc123]"
+  opts.on("-u", "--username USERNAME", String, "Specify the XMPP JID to connect to") do |u|
+    options[:username] = u
+  end
+  opts.on("-p", "--password PASSWORD", String, "Specify the XMPP password to use") do |p|
+    options[:password] = p
+  end
+  opts.on("-d", "--rayo-domain DOMAIN", String, "Specify the domain Rayo is running on") do |d|
+    options[:rayo_domain] = d
+  end
+  opts.on("--wire-log-file log/wirelog.log", String, "Specify the file to which the wire log should be written") do |wlf|
+    options[:wire_log_file] = wlf
+  end
+  opts.on("--transport-log-file log/transportlog.log", String, "Specify the file to which the transport log should be written") do |tlf|
+    options[:transport_log_file] = tlf
+  end
+  opts.on_tail("-h", "--help", "Show this message") do
+    puts opts
+    exit
+  end
+  opts.on_tail("-v", "--version", "Show version") do
+    puts VERSION
+    exit
+  end
+end
+
+begin
+  option_parser.parse!
+rescue
+  puts $!
+  option_parser.parse '--help'
+end
+
+options[:wire_logger] = Logger.new options.delete(:wire_log_file)
+options[:wire_logger].level = Logger::DEBUG
+options[:wire_logger].debug "Starting up..."
+options[:transport_logger] = Logger.new options.delete(:transport_log_file)
+options[:transport_logger].level = Logger::DEBUG
+options[:transport_logger].debug "Starting up..."
+
+connection = Connection.new options
+
+[:INT, :TERM].each do |signal|
+  trap signal do
+    puts "Shutting down!"
+    connection.stop
+  end
+end
+
+connection_thread = Thread.new do
+  begin
+    connection.run
+  rescue => e
+    puts "Exception in XMPP thread! #{e.message}"
+    puts e.backtrace.join("\t\n")
+  end
+end
+
+CALL_QUEUES = {}
+INFO_EVENT_QUEUE = Queue.new
+
+### DISPATCHER THREAD
+# This thread multiplexes the event stream from the underlying connection handler and routes them
+# to the correct queue for each call.  It also starts a call handler, the run_call method) after creating
+# the queue.
+Thread.new do
+  loop do
+    event = connection.event_queue.pop
+    if event == connection.connected
+      puts event
+      puts "Waiting for a call..."
+      next
+    end
+    puts "#{event.class} event for call: #{event.call_id}"
+    case event
+    when Event::Offer
+      raise "Duplicate call ID for #{event.call_id}" if CALL_QUEUES.has_key?(event.call_id)
+      CALL_QUEUES[event.call_id] = Queue.new
+      CALL_QUEUES[event.call_id].push event
+      run_call connection, event
+    when Event::Info
+      INFO_EVENT_QUEUE.push event
+    when Event::Answered, Event::Complete, Event::End, Event::Ringing
+      CALL_QUEUES[event.call_id].push event
+    else
+      puts "Unknown event: #{event.inspect}"
+    end
+
+  end
+end
+
+def run_call(connection, offer)
+  ### CALL THREAD
+  # One thread is spun up to handle each call.
+  Thread.new do
+    raise "Unknown call #{offer.call_id}" unless CALL_QUEUES.has_key?(offer.call_id)
+    queue = CALL_QUEUES[offer.call_id]
+    call = queue.pop
+    dsl = DSL.new connection, offer.call_id, queue
+
+    puts "Incoming offer to #{offer.to} from #{offer.headers_hash[:from]} #{offer}"
+    dsl.pry
+
+    # Clean up the queue.
+    CALL_QUEUES[offer.call_id] = nil
+  end
+end
+
+connection_thread.join

data/lib/punchblock/command/accept.rb

@@ -0,0 +1,30 @@
+module Punchblock
+  module Command
+    class Accept < CommandNode
+      register :accept, :core
+
+      include HasHeaders
+
+      ##
+      # Create an Rayo accept command. This is equivalent to a SIP "180 Trying"
+      #
+      # @param [Hash] options
+      # @option options [Array[Header], Hash, Optional] :headers SIP headers to attach to
+      #   the call. Can be either a hash of key-value pairs, or an array of
+      #   Header objects.
+      #
+      # @return [Command::Accept] a formatted Rayo accept command
+      #
+      # @example
+      #    Accept.new.to_xml
+      #
+      #    returns:
+      #        <accept xmlns="urn:xmpp:rayo:1"/>
+      def self.new(options = {})
+        super().tap do |new_node|
+          new_node.headers = options[:headers]
+        end
+      end
+    end # Accept
+  end # Command
+end # Punchblock

data/lib/punchblock/command/answer.rb

@@ -0,0 +1,30 @@
+module Punchblock
+  module Command
+    class Answer < CommandNode
+      register :answer, :core
+
+      include HasHeaders
+
+      ##
+      # Create an Rayo answer command. This is equivalent to a SIP "200 OK"
+      #
+      # @param [Hash] options
+      # @option options [Array[Header], Hash, Optional] :headers SIP headers to attach to
+      #   the call. Can be either a hash of key-value pairs, or an array of
+      #   Header objects.
+      #
+      # @return [Command::Answer] a formatted Rayo answer command
+      #
+      # @example
+      #    Answer.new.to_xml
+      #
+      #    returns:
+      #        <answer xmlns="urn:xmpp:rayo:1"/>
+      def self.new(options = {})
+        super().tap do |new_node|
+          new_node.headers = options[:headers]
+        end
+      end
+    end # Answer
+  end # Command
+end # Punchblock

data/lib/punchblock/command/dial.rb

@@ -0,0 +1,88 @@
+module Punchblock
+  module Command
+    class Dial < CommandNode
+      register :dial, :core
+
+      include HasHeaders
+
+      ##
+      # Create a dial message
+      #
+      # @param [Hash] options
+      # @option options [String] :to destination to dial
+      # @option options [String, Optional] :from what to set the Caller ID to
+      # @option options [Array[Header], Hash, Optional] :headers SIP headers to attach to
+      #   the new call. Can be either a hash of key-value pairs, or an array of
+      #   Header objects.
+      # @option options [Join, Hash, Optional] :join a join (or set of join parameters) to
+      #   nest within the dial
+      #
+      # @return [Command::Dial] a formatted Rayo dial command
+      #
+      # @example
+      #    dial :to => 'tel:+14155551212', :from => 'tel:+13035551212'
+      #
+      #    returns:
+      #      <dial to='tel:+13055195825' from='tel:+14152226789' xmlns='urn:xmpp:rayo:1' />
+      #
+      def self.new(options = {})
+        super().tap do |new_node|
+          options.each_pair { |k,v| new_node.send :"#{k}=", v }
+        end
+      end
+
+      ##
+      # @return [String] destination to dial
+      def to
+        read_attr :to
+      end
+
+      ##
+      # @param [String] dial_to destination to dial
+      def to=(dial_to)
+        write_attr :to, dial_to
+      end
+
+      ##
+      # @return [String] the caller ID
+      def from
+        read_attr :from
+      end
+
+      ##
+      # @param [String] dial_from what to set the caller ID to
+      def from=(dial_from)
+        write_attr :from, dial_from
+      end
+
+      ##
+      # @return [Join] the nested join
+      #
+      def join
+        element = find_first 'ns:join', :ns => Join.registered_ns
+        Join.new element if element
+      end
+
+      ##
+      # @param [Hash, Join] other a join or hash of join options
+      #
+      def join=(other)
+        remove_children :join
+        join = Join.new(other) unless other.is_a?(Join)
+        self << join
+      end
+
+      def response=(other)
+        super
+        if other.is_a?(Blather::Stanza::Iq)
+          ref = other.rayo_node
+          @call_id = ref.id if ref.is_a?(Ref)
+        end
+      end
+
+      def inspect_attributes # :nodoc:
+        [:to, :from, :join] + super
+      end
+    end # Dial
+  end # Command
+end # Punchblock

data/lib/punchblock/command/hangup.rb

@@ -0,0 +1,25 @@
+module Punchblock
+  module Command
+    class Hangup < CommandNode
+      register :hangup, :core
+
+      include HasHeaders
+
+      ##
+      # Create an Rayo hangup message
+      #
+      # @param [Hash] options
+      # @option options [Array[Header], Hash, Optional] :headers SIP headers to attach to
+      #   the call. Can be either a hash of key-value pairs, or an array of
+      #   Header objects.
+      #
+      # @return [Command::Hangup] a formatted Rayo redirect command
+      #
+      def self.new(options = {})
+        super().tap do |new_node|
+          new_node.headers = options[:headers]
+        end
+      end
+    end # Hangup
+  end # Command
+end # Punchblock