rastman 0.1.4

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007 Mathieu Lajugie
+
+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

@@ -0,0 +1,31 @@
+# = Rastman is a Ruby interface for the Asterisk Manager API
+#
+# When creating a new Rastman::Manager instance, it connects to an Asterisk server
+# on the manager port (<tt>5038</tt> by default), sends a login request
+# and listens to events published by the server. The instance can also
+# be used to send Manager API requests to the server.
+#
+# == Example
+# 
+# require "rubygems"
+# require "rastman"
+#
+# rastman = Rastman::Manager.new("myuser", "secret")
+#
+# rastman.add_event_hook(:event) { |evt| puts "Event received: [#{evt.inspect}]"
+#
+# rastman.connect
+#
+# rastman.events(:eventmask => "user,call")
+#
+# rastman.ping
+#
+# rastman.originate :channel => "SIP/myphone@mydomain.com",
+#										:context => "default", :exten => "voicemail",
+#									  :priority => 1
+#
+# rastman.logoff
+#
+#
+#  Created by Mathieul on 2007-02-08.
+#  Copyright (c) 2007. All rights reserved.

data/TODO

@@ -0,0 +1,4 @@
+[TODO]
+* [X] Rastman library
+* [X] testing suite using RSpec
+* [X] tool to generate calls

data/bin/rastman_mkcalls.rb

@@ -0,0 +1,181 @@
+#!/usr/bin/env ruby
+# $Id$
+
+require "optparse"
+require "ostruct"
+require "yaml"
+require "rubygems"
+require "rastman"
+
+CMD = File.basename(__FILE__)
+
+class CmdLine
+
+  def self.parse(args, opts)
+    # set default options
+    opts[:login] ||= "username"
+    opts[:pwd] ||= "secret"
+    opts[:host] ||= "localhost"
+    opts[:recipient] ||= "1234567890@example.com"
+    opts[:context] ||= "default"
+    opts[:exten] ||= "987"
+    opts[:rounds] ||= 1
+    opts[:rounds_delay] ||= 20
+    opts[:calls] ||= 1
+    opts[:calls_delay] ||= 1
+    opts[:view_events] = false if opts[:view_events].nil?
+    opts[:rc] = false
+    
+    o = OptionParser.new do |o|
+      o.banner = "Usage: #{CMD} [options]"
+      o.separator ""
+      o.separator "Options:"
+
+      o.on("-l", "--login <login>",
+        String,
+        "Login to use from .../etc/manager.conf (default: #{opts[:login]})") do |login|
+        opts[:login] = login
+      end
+
+      o.on("-p", "--pwd <password>",
+        String,
+        "Password as declared in .../etc/manager.conf (default: #{opts[:pwd]})") do |pwd|
+        opts[:pwd] = pwd
+      end
+
+      o.on("-h", "--host <asterisk host name>",
+        String,
+        "Host name running the Asterisk server (default: #{opts[:host]})") do |host|
+        opts[:host] = host
+      end
+
+      o.on("-r", "--recipient <URI>",
+        String,
+        "Recipient URI (default: #{opts[:recipient]})") do |recipient|
+        opts[:recipient] = recipient
+      end
+
+      o.on("-c", "--context <context>",
+        String,
+        "Dialplan Context to connect the call to (default: #{opts[:context]})") do |context|
+        opts[:context] = context
+      end
+
+      o.on("-e", "--exten <extension>",
+        String,
+        "Dialplan Extension to connect the call to (default: #{opts[:exten]})") do |exten|
+        opts[:exten] = exten
+      end
+
+      o.on("-n", "--num-rounds <number>",
+        Integer,
+        "Number of rounds of call generation to make (default: #{opts[:rounds]})") do |rounds|
+        opts[:rounds] = rounds
+      end
+
+      o.on("-d", "--rounds-delay <delay>",
+        Float,
+        "Number of seconds between two rounds (default: #{opts[:rounds_delay]})") do |delay|
+        opts[:rounds_delay] = delay
+      end
+
+      o.on("-a", "--num-calls <number>",
+        Integer,
+        "Number of rounds of call generation to make (default: #{opts[:calls]})") do |calls|
+        opts[:calls] = calls
+      end
+
+      o.on("-t", "--calls-delay <delay>",
+        Float,
+        "Number of seconds between two calls (default: #{opts[:calls_delay]})") do |delay|
+        opts[:calls_delay] = delay
+      end
+
+      o.on("-v", "--view-events",
+        "View events generated by Asterisk (default: #{opts[:view_events]})") do |view_events|
+        opts[:view_events] = view_events
+      end
+
+      o.on("-m", "--[no-]make-rc",
+        "Save options in $HOME/.rastman_mkcallsrc instead of generating calls") do |rc|
+        opts[:rc] = rc
+      end
+
+      o.on_tail("-?", "--help", "Show this message") do
+        puts o
+        exit
+      end
+
+      o.parse!(args)
+    end
+    opts
+  end
+
+end
+
+# retrieve default parameters if resource file exists
+rc_options, rc_file = {}, File.join(ENV["HOME"], ".rastman_mkcallsrc")
+rc_options = YAML::load(File.read(rc_file)) if File.exists?(rc_file)
+
+# parse command line
+opts = CmdLine.parse(ARGV, rc_options)
+
+# save resource file if asked for
+if opts[:rc] == true
+  opts.delete(:rc)
+  File.open(rc_file, "w") { |f| f.write(YAML::dump(opts)) }
+  puts "#{CMD}: options saved in #{rc_file}."
+  exit
+end
+
+cmdr = Rastman::Manager.new(opts[:login], opts[:pwd], :host => opts[:host],
+  :connect => true, :eventmask => "off")
+
+lsnr = nil
+if opts[:view_events] == true
+  require 'pp'
+  lsnr = Rastman::Manager.new(opts[:login], opts[:pwd], :host => opts[:host])
+  lsnr.add_event_hook(:event) { |evt| pp evt; puts }
+  lsnr.connect
+end
+
+Signal.trap("INT") do
+  puts "#{CMD}: Logging off. Please wait for Asterisk to complete the logoff request."
+  cmdr.logoff
+  lsnr.logoff unless lsnr.nil?
+  Signal.trap("INT", "DEFAULT")
+end
+
+to = (opts[:recipient].include?("/") ? "": "SIP/") + opts[:recipient]
+
+puts "Starting #{opts[:rounds]} rounds of #{opts[:calls]} calls."
+puts "Call delay is #{opts[:calls_delay]} secs."
+puts "Round delay is #{opts[:rounds_delay]} secs."
+puts
+
+# round loop
+(1..opts[:rounds]).each do |round_number|
+  puts "Round ##{round_number}: #{opts[:calls]} calls"
+  caller_id_prefix = "#{Time.now.strftime "1%M%S"}"
+  # calls loop
+  (1..opts[:calls]).each do |call_number|
+    puts "  Call ##{call_number}"
+    cmdr.originate(:channel => to,
+    							 :context => opts[:context],
+    							 :exten => opts[:exten],
+    							 :priority => 1,
+    							 :callerid => %|#{caller_id_prefix}#{"%05d" % call_number}|)
+    sleep(opts[:calls_delay])
+  end
+  sleep(opts[:rounds_delay]) unless round_number == opts[:rounds]
+end
+
+if lsnr.nil?
+  cmdr.logoff
+else
+  sleep 0.1 while cmdr.connected?
+end
+
+#
+#  Created by Mathieul on 2007-02-08.
+#  Copyright (c) 2007. All rights reserved.

data/lib/rastman.rb

@@ -0,0 +1,352 @@
+# $Id$
+# RASTMAN - Ruby Asterisk Manager api
+#
+
+require 'monitor'
+require 'socket'
+require 'timeout'
+require 'logger'
+
+$rnlog = Logger.new(STDOUT)
+$rnlog.level = Logger::ERROR
+
+# The Rastman module contains the Rastman::Manager class that is used to
+# connect to an Asterisk server to send requests and listen to events.
+module Rastman
+
+  # Generic Rastman error
+  class RastmanError < StandardError; end  
+  # Rastman Login error
+  class LoginError < RastmanError; end  
+  # Rastman Connection error
+  class NotConnectedError < RastmanError; end  
+  # Rastman Deconnection error
+  class DisconnectedError < RastmanError; end  
+
+  LINE_SEPARATOR = "\r\n"
+
+  class << self
+    
+    # Change the log level (default: Logger::ERROR).
+    # Can be set to any of the following:
+    # * Logger::DEBUG
+    # * Logger::INFO
+    # * Logger::WARN
+    # * Logger::ERROR
+    # * Logger::FATAL
+    # * Logger::ANY
+    def log_level=(level)
+      $rnlog.level = level
+    end
+
+    # Return the current log level.
+    def log_level
+      $rnlog.level
+    end
+
+    # Change it for a new one
+    def set_logger(new_logger)
+      $rnlog = new_logger
+      $rnlog.info('Rastman#set_logger: done')
+    end
+
+  end
+  
+  module Parser
+
+    def parse_line(line) # :nodoc:
+      raise LocalJumpError, "no block given" unless block_given?
+      @buffer ||= ""
+      @buffer += line
+      # if the line doesn't end with CRLF, we store it for the next call
+      if /(^[\w\s\/-]*):[\s]*(.*)\r\n$/m =~ @buffer
+        yield($1.downcase.to_sym, $2)
+        @buffer = ""
+      else
+        if @buffer[-2..-1] == "\r\n"
+          yield(:unknown, "UNKNOWN")
+          @buffer = ""
+        end
+      end
+    end
+    
+  end
+
+  # A connection with an Asterisk server is established through a
+  # Rastman::Manager object. This object can then be used to
+  # send Asterisk Manager requests and listens to Asterisk events.
+  #
+  # Note that events generated from the result of a request won't be sent
+  # immediately back by Asterisk on the same connection.
+  # So you should probably use one object to send the requests,
+  # and one object to listen to the events.
+  class Manager
+    include Parser
+
+    attr_reader :host, :login
+
+    COMMANDS = [:login, :logoff, :events, :originate, :originate!, :redirect,
+      :redirect!, :hangup, :hangup!, :ping, :ping!, :setvar, :setvar!,
+      :command, :command!]
+    WAIT_FOR_ANSWER = 0.1
+
+    # Returns a Rastman::Manager object. The login and pwd parameters
+    # are the username and secret attributes of the user configured
+    # in /path/to/asterisk/configuration/manager.conf.
+    #
+    # The following options are also accepted:
+    # * <tt>:port</tt>:               Manager port to connect to (<i>default: 5038</i>),
+    # * <tt>:host</tt>:               Host name where Asterisk is running (<i>default: localhost</i>),
+    # * <tt>:reconnect_timeout</tt>:  Timeout between two reconnect attempts (<i>default: 1</i>),
+    # * <tt>:connect</tt>:            Flag to request a connection right away (<i>default: false</i>).
+    # * <tt>:eventmask</tt>:          Manager event mask (i.e.: "user,call") (<i>default: on</i>).
+    def initialize(login, pwd, opts = {})
+      @login, @pwd = login, pwd
+      @port = opts[:port] || 5038
+      @host = opts[:host] || 'localhost'
+      @version = opts[:version]
+      @eventmask = opts[:eventmask] || 'on'
+      @reconnect_timeout = opts[:reconnect_timeout] || 1
+      @connected, @hooks = false, {}
+      @conn_lock = nil
+      @conn_lock.extend(MonitorMixin)
+      add_event_hook(:reconnect) { event_reconnect }
+      connect if opts[:connect]
+    end
+
+    # Connects to the server, attempt to login, and start listening to
+    # events if successfull.
+    #
+    # If +should_reconnect+ is true, then the object will attempt to reconnect
+    # until successful (the reconnection timeout is configured in new).
+    def connect(should_reconnect = true)
+      @conn = TCPSocket.new(@host, @port)
+      login
+      @should_reconnect = should_reconnect
+      @listener = Listener.new(@conn, @hooks, :version => @version)
+      @listener.start
+    end
+
+    # Returns true if the object is currently connected to the server.
+    def connected?
+      $rnlog.debug("Rastman::Manager#connected?: @connected = #{@connected}")
+      @connected == true
+    end
+
+    # Disconnects from the server (without sending the _LogOff_ request).
+    def disconnect
+      raise NotConnectedError, "No active connection" if @conn.closed?
+      @should_reconnect = false
+      @conn.close
+      $rnlog.debug("Rastman::Manager#disconnect: closed connection")
+    end
+
+    # Adds (or replaces) a block to be executed when the specified event occurs:
+    # * <tt>:event</tt>:      an event was received
+    # * <tt>:action</tt>:     a response to an action was received
+    # * <tt>:reconnect</tt>:  the object got reconnected to the server
+    # * <tt>:disconnect</tt>: the object got disconnected from the server
+    def add_event_hook(event, &block)
+      check_supported_event(event)
+      @hooks[event] = block
+    end
+
+    # Delete the block that was to be executed for the specified event.
+    def del_event_hook(event)
+      check_supported_event(event)
+      @hooks.delete(event)
+    end
+    
+    def join
+      @listener.join
+    end
+
+    private
+    def check_supported_event(event)
+      unless [:event, :action, :disconnect, :reconnect].include?(event)
+        raise ArgumentError, "Unsupported event #{event}"
+      end
+    end
+    
+    def event_reconnect #:nodoc:
+      @connected = false
+      $rnlog.debug("Rastman::Manager#event_reconnect: should_reconnect(#{@should_reconnect})")
+      @hooks[:disconnect].call({:event => :disconnect}) unless @hooks[:disconnect].nil?
+      if @should_reconnect == true
+        while @connected == false
+          sleep @reconnect_timeout
+          connect rescue nil
+        end
+      end
+    end
+
+    def login # :nodoc:
+      send_action({ :action => 'login', :username => @login, :secret => @pwd, :events => @eventmask })
+      wait_for_login_acknowledgement
+    end
+
+    def wait_for_login_acknowledgement # :nodoc:
+      Timeout.timeout(10) do
+        event, done = {}, false
+        until done == true do
+          @conn.each(LINE_SEPARATOR) do |line|
+            if line == LINE_SEPARATOR
+              done = true
+              break
+            else
+              parse_line(line) { |key, value| event[key] = value }
+            end
+            done = true if @conn.closed?
+          end
+          if event[:response] == "Success"
+            @connected = true
+          else
+            raise LoginError, event[:message]
+          end
+          $rnlog.debug("Rastman::Manager#wait_for_login_acknowledgement: @connected(#{@connected}) event(#{event.inspect})")
+        end
+      end
+    rescue Timeout::Error
+      raise NotConnectedError, "No answer received for login request"
+    end
+
+    # send_action actually send the action requested to Asterisk.
+    # If expects_answer_before is NOT set (default), it sends the
+    # request and returns nil right away.
+    # If expects_answer_before is set, it sends the request, waits
+    # for expects_answer_before seconds or until the response is received
+    # (whichever comes first) and returns true if the response if received,
+    # false if not.
+    def send_action(action, expects_answer_before = nil) # :nodoc:
+      $rnlog.debug("Rastman::Manager#send_action: SEND '#{action[:action]}' (#{action.inspect})")
+      unless expects_answer_before.nil?
+        action_id = action[:actionid] ||= "#{action[:action]}-#{action.hash}"
+        answer = []
+        @listener.request_answer_for(action_id, answer)
+      end
+      @conn_lock.synchronize do
+        action.each do |key, value|
+          $rnlog.debug("Rastman::Manager#send_action: write (#{key.to_s}: #{value}\\r\\n)")
+          @conn.write("#{key.to_s}: #{value}\r\n")
+        end
+        $rnlog.debug("Rastman::Manager#send_action: write (\\r\\n)")
+        @conn.write("\r\n")
+      end
+      result = nil
+      unless expects_answer_before.nil?
+        waited = 0
+        until answer.length > 0
+          sleep WAIT_FOR_ANSWER
+          waited += WAIT_FOR_ANSWER
+          if waited >= expects_answer_before
+            answer << {}
+          end
+        end
+        result = answer.first[:response] == "Success" ? true : false rescue false
+      end
+      return result
+    rescue Exception => ex
+      $rnlog.info("Rastman::Manager#send_action: exception caught (connection probably closed already): #{ex}")
+    end
+
+    def method_missing(meth, *args, &block) # :nodoc:
+      unless COMMANDS.include?(meth)
+        raise NoMethodError.new(
+        "undefined method `#{meth}' for " +
+        "#{self.inspect}:#{self.class.name}"
+        )
+      end
+      command = meth.to_s.downcase
+      if command[-1] == ?!
+        case args.size
+        when 1
+          expects_answer_before = 10
+          action = args.first
+        when 2
+          expects_answer_before, action = args
+        else
+          raise ArgumentError, "#{meth} wrong number of arguments (#{args.size} for 1 or 2)"
+        end
+        command.chop!
+      else
+        action = args.size == 0 ? {} : args[0]
+        expects_answer_before = nil
+      end
+      action.merge!({ :action => command })
+      @should_reconnect = false if command == "logoff"
+      send_action(action, expects_answer_before)
+    end
+
+  end
+
+  class Listener  # :nodoc: all
+    include Parser
+
+    def initialize(conn, hooks, opts = {})
+      @conn, @hooks = conn, hooks
+      @action_ids = {}
+      @mode_1_0 = opts[:version] == "1.0"
+    end
+
+    def start
+      @th = Thread.new do
+        Thread.current.abort_on_exception = true
+        begin
+          event = {}
+          @conn.each(LINE_SEPARATOR) do |line|
+            $rnlog.debug("Rastman::Listener#start: read (#{line.strip})")
+            if line == LINE_SEPARATOR
+              if event[:event].nil?
+                @hooks[:action].call(event.clone) unless @hooks[:action].nil?
+                unless event[:actionid].nil?
+                  container = @action_ids.delete(event[:actionid])
+                  container << event.clone unless container.nil?
+                end
+              else
+                reformat_userevent(event) if @mode_1_0
+                @hooks[:event].call(event.clone) unless @hooks[:event].nil?
+              end
+              event.clear
+            else
+              parse_line(line) { |key, value| event[key] = value }
+            end
+          end
+        rescue IOError => e
+          $rnlog.warn("Rastman::Listener#start: IOError (#{e}) occured => we close the connection")
+          @conn.close rescue nil
+        end
+        $rnlog.info("Rastman::Listener#start: calling reconnect hook before stopping")
+        @hooks[:reconnect].call({:event => :reconnect}) unless @hooks[:reconnect].nil?
+      end
+    end
+
+    def join
+      @th.join
+    end
+    
+    def request_answer_for(id, container)
+      @action_ids[id] = container
+    end
+    
+    private 
+    def reformat_userevent(evt)
+      name = evt[:event].split("UserEvent")[1]
+      unless name.nil?
+        evt[:userevent] = name
+        evt[:event] = "UserEvent"
+        vars = evt.delete(:variables)
+        vars.split("|").each do |pair|
+          k, v = pair.split(/: */)
+          evt[k.downcase.to_sym] = v || ""
+        end unless vars.nil?
+        evt.delete(:channel)
+      end     
+    end
+
+  end
+
+end
+
+#
+#  Created by Mathieul on 2007-02-08.
+#  Copyright (c) 2007. All rights reserved.

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.2
+specification_version: 1
+name: rastman
+version: !ruby/object:Gem::Version 
+  version: 0.1.4
+date: 2007-06-28 00:00:00 -07:00
+summary: Asterisk Manager API interface for Ruby
+require_paths: 
+- lib
+email: mathieul@zlaj.org
+homepage: http://rastman.rubyforge.org/
+rubyforge_project: 
+description: Asterisk Manager API interface for Ruby
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.4
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Mathieu Lajugie
+files: 
+- MIT-LICENSE
+- README
+- TODO
+- bin/rastman_mkcalls.rb
+- lib/rastman.rb
+test_files: []
+
+rdoc_options: 
+- --quiet
+- --title
+- Rastman Documentation
+- --opname
+- index.html
+- --line-numbers
+- --main
+- README
+- --inline-source
+extra_rdoc_files: 
+- README
+executables: 
+- rastman_mkcalls.rb
+extensions: []
+
+requirements: []
+
+dependencies: []
+