ruby-asterisk 0.1.0 → 1.0.0

data/lib/ruby-asterisk.rb

@@ -1,148 +1,6 @@
-require "ruby-asterisk/version"
-require "ruby-asterisk/request"
-require "ruby-asterisk/response"
+# frozen_string_literal: true
 
-require 'net/telnet'
-
-module RubyAsterisk
-  class AMI
-    attr_accessor :host, :port, :connected
-
-    def initialize(host,port)
-      self.host = host.to_s
-      self.port = port.to_i
-      self.connected = false
-      @session = nil
-    end
-
-    def connect
-      begin
-        @session = Net::Telnet::new("Host" => self.host,"Port" => self.port)
-        self.connected = true
-      rescue Exception => ex
-        false
-      end
-    end
-
-    def disconnect
-      begin
-        @session.close if self.connected
-        @session = nil
-        self.connected = false
-        true
-      rescue Exception => ex
-        puts ex
-        false
-      end
-    end
-
-    def login(username,password)
-      self.connect unless self.connected
-      execute "Login", {"Username" => username, "Secret" => password, "Event" => "On"}
-    end
-
-    def command(command)
-      execute "Command", {"Command" => command}
-    end
-
-    def core_show_channels
-      execute "CoreShowChannels"
-    end
-
-    def meet_me_list
-      execute "MeetMeList"
-    end
-
-    def parked_calls
-      execute "ParkedCalls"
-    end
-
-    def extension_state(exten, context, action_id=nil)
-      execute "ExtensionState", {"Exten" => exten, "Context" => context, "ActionID" => action_id}
-    end
-
-    def skinny_devices
-      execute "SKINNYdevices"
-    end
-    
-    def skinny_lines
-      execute "SKINNYlines"
-    end
-
-    def status(channel=nil,action_id=nil)
-      execute "Status", {"Channel" => channel, "ActionID" => action_id}
-    end
-
-    def originate(caller,context,callee,priority,variable=nil)
-      execute "Originate", {"Channel" => caller, "Context" => context, "Exten" => callee, "Priority" => priority, "Callerid" => caller, "Timeout" => "30000", "Variable" => variable  }
-    end
-
-    def channels
-      execute "Command", { "Command" => "show channels" }
-    end
-
-    def redirect(caller,context,callee,priority,variable=nil)
-      execute "Redirect", {"Channel" => caller, "Context" => context, "Exten" => callee, "Priority" => priority, "Callerid" => caller, "Timeout" => "30000", "Variable" => variable}
-    end
-
-    def queues
-      execute "Queues", {}
-    end
-
-    def queue_add(queue, exten, penalty=2, paused=false, member_name)
-      execute "QueueAdd", {"Queue" => queue, "Interface" => exten, "Penalty" => penalty, "Paused" => paused, "MemberName" => member_name}
-    end
-
-    def queue_pause(queue, exten)
-      execute "QueuePause", {"Interface" => exten, "Paused" => paused}
-    end
-
-    def queue_remove(queue, exten)
-      execute "QueueRemove", {"Queue" => queue, "Interface" => exten}
-    end
-
-    def queue_status
-      execute "QueueStatus"
-    end
-
-    def queue_summary(queue)
-      execute "QueueSummary", {"Queue" => queue}
-    end
-
-    def mailbox_status(exten, context="default")
-      execute "MailboxStatus", {"Mailbox" => "#{exten}@#{context}"}
-    end
-
-    def mailbox_count(exten, context="default")
-      execute "MailboxCount", {"Mailbox" => "#{exten}@#{context}"}
-    end
-
-    def queue_pause(interface,paused,queue,reason='none')
-      execute "QueuePause", {"Interface" => interface, "Paused" => paused, "Queue" => queue, "Reason" => reason}
-    end
-
-    def ping
-      execute "Ping"
-    end
-
-    def event_mask(event_mask="off")
-      execute "Events", {"EventMask" => event_mask}
-    end
-
-    def sip_peers
-      execute "SIPpeers"
-    end
-
-    private
-    def execute(command, options={})
-      request = Request.new(command, options)
-      request.commands.each do |command|
-        @session.write(command)
-      end
-      @session.waitfor("Match" => /ActionID: #{request.action_id}.*?\n\n/m, "Timeout" => 10) do |data|
-        request.response_data << data
-      end
-      Response.new(command,request.response_data)
-    end
-  end
-end
+require 'ruby-asterisk/ami/client'
+require 'ruby-asterisk/ari/client'
+require 'ruby-asterisk/ari/websocket'
+require 'ruby-asterisk/agi/server'

data/ruby-asterisk.gemspec

@@ -1,24 +1,33 @@
-# -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
-require "ruby-asterisk/version"
+# frozen_string_literal: true
+
+$LOAD_PATH.push File.expand_path('lib', __dir__)
+require 'ruby-asterisk/version'
 
 Gem::Specification.new do |s|
-  s.name        = "ruby-asterisk"
-  s.version     = Rami::VERSION
+  s.name        = 'ruby-asterisk'
+  s.version     = RubyAsterisk::VERSION
   s.platform    = Gem::Platform::RUBY
-  s.authors     = ["Emiliano Della Casa"]
-  s.email       = ["e.dellacasa@engim.eu"]
-  s.homepage    = "http://github.com/emilianodellacasa/ruby-asterisk"
-  s.summary     = %q{Asterisk Manager Interface in Ruby}
-  s.description = %q{Add support to your ruby or rails projects to Asterisk Manager Interface (AMI)}
-
-  s.rubyforge_project = "ruby-asterisk"
+  s.authors     = ['Emiliano Della Casa']
+  s.email       = ['emiliano.dellacasa@gmail.com']
+  s.homepage    = 'http://github.com/emilianodellacasa/ruby-asterisk'
+  s.summary     = 'Asterisk Manager Interface in Ruby'
+  s.description = 'Add support to your ruby or rails projects to Asterisk Manager Interface (AMI)'
+  s.licenses    = ['MIT']
+  s.required_ruby_version = '>= 3.1'
 
   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.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.require_paths = ['lib']
+
+  s.add_runtime_dependency 'async', '~> 2.0'
+  s.add_runtime_dependency 'faraday', '>= 1.0'
+  s.add_runtime_dependency 'logger'
+  s.add_runtime_dependency 'websocket-driver', '~> 0.8'
 
-	s.add_development_dependency "rake"
-	s.add_development_dependency 'rspec'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'rubocop'
+  s.add_development_dependency 'rubocop-performance'
+  s.add_development_dependency 'simplecov'
+  s.metadata['rubygems_mfa_required'] = 'true'
 end

data/spec/ruby-asterisk/agi/protocol_spec.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'ruby-asterisk/agi/protocol'
+
+RSpec.describe RubyAsterisk::AGI::Protocol do
+  describe '.parse_response' do
+    subject(:parse) { described_class.parse_response(line) }
+
+    context 'with a plain success result' do
+      let(:line) { '200 result=1' }
+
+      it { expect(parse).to eq(code: 200, result: '1', data: nil) }
+    end
+
+    context 'with result=0' do
+      let(:line) { '200 result=0' }
+
+      it { expect(parse).to eq(code: 200, result: '0', data: nil) }
+    end
+
+    context 'with endpos extra data' do
+      let(:line) { '200 result=0 endpos=12345' }
+
+      it { expect(parse).to eq(code: 200, result: '0', data: 'endpos=12345') }
+    end
+
+    context 'with parenthetical extra data' do
+      let(:line) { '200 result=1 (some text)' }
+
+      it { expect(parse).to eq(code: 200, result: '1', data: 'some text') }
+    end
+
+    context 'with trailing newline' do
+      let(:line) { "200 result=1\n" }
+
+      it { expect(parse[:code]).to eq(200) }
+      it { expect(parse[:result]).to eq('1') }
+    end
+
+    context 'with 510 error' do
+      let(:line) { '510 Invalid or unknown command' }
+
+      it { expect(parse).to eq(code: 510, result: nil, data: 'Invalid or unknown command') }
+    end
+
+    context 'with 511 error' do
+      let(:line) { '511 Command Not Permitted on a dead channel' }
+
+      it { expect(parse).to eq(code: 511, result: nil, data: 'Command Not Permitted on a dead channel') }
+    end
+
+    context 'with 520 single-line syntax error' do
+      let(:line) { '520 Invalid command syntax' }
+
+      it { expect(parse).to eq(code: 520, result: nil, data: 'Invalid command syntax') }
+    end
+
+    context 'with nil (socket EOF)' do
+      let(:line) { nil }
+
+      it { expect(parse).to eq(code: 0, result: nil, data: 'Connection closed') }
+    end
+
+    context 'with an unrecognised line' do
+      let(:line) { 'INVALID' }
+
+      it { expect(parse[:code]).to eq(0) }
+    end
+  end
+
+  describe '.format_command' do
+    it 'formats a bare command with no args' do
+      expect(described_class.format_command('ANSWER')).to eq("ANSWER\n")
+    end
+
+    it 'appends plain args without quoting' do
+      expect(described_class.format_command('WAIT FOR DIGIT', '5000')).to eq("WAIT FOR DIGIT 5000\n")
+    end
+
+    it 'wraps args that contain spaces in double quotes' do
+      expect(described_class.format_command('VERBOSE', 'hello world', '1')).to eq(%(VERBOSE "hello world" 1\n))
+    end
+
+    it 'escapes backslashes inside quoted args' do
+      expect(described_class.format_command('EXEC', 'foo', 'a\\b')).to eq(%(EXEC foo "a\\\\b"\n))
+    end
+
+    it 'escapes double quotes inside quoted args' do
+      expect(described_class.format_command('EXEC', 'foo', 'say "hi"')).to eq(%(EXEC foo "say \\"hi\\""\n))
+    end
+  end
+
+  describe '.escape_argument' do
+    it 'returns "" for an empty string' do
+      expect(described_class.escape_argument('')).to eq('""')
+    end
+
+    it 'returns the arg unchanged when no special chars' do
+      expect(described_class.escape_argument('hello-world')).to eq('hello-world')
+    end
+
+    it 'wraps in quotes when arg contains a space' do
+      expect(described_class.escape_argument('hello world')).to eq('"hello world"')
+    end
+
+    it 'escapes an internal backslash' do
+      expect(described_class.escape_argument('a\\b')).to eq('"a\\\\b"')
+    end
+
+    it 'escapes an internal double-quote' do
+      expect(described_class.escape_argument('say "hi"')).to eq('"say \\"hi\\""')
+    end
+  end
+
+  describe '.quote' do
+    it 'always wraps in double quotes even for plain strings' do
+      expect(described_class.quote('hello-world')).to eq('"hello-world"')
+    end
+
+    it 'wraps an empty string' do
+      expect(described_class.quote('')).to eq('""')
+    end
+
+    it 'escapes internal double quotes' do
+      expect(described_class.quote('say "hi"')).to eq('"say \\"hi\\""')
+    end
+
+    it 'escapes internal backslashes' do
+      expect(described_class.quote('a\\b')).to eq('"a\\\\b"')
+    end
+  end
+
+  describe '.parse_env_line' do
+    it 'returns [key, value] for a valid agi_ line' do
+      expect(described_class.parse_env_line('agi_channel: SIP/test-1')).to eq(['agi_channel', 'SIP/test-1'])
+    end
+
+    it 'strips leading/trailing whitespace from the value' do
+      expect(described_class.parse_env_line('agi_request:  agi://localhost  ')).to eq(['agi_request', 'agi://localhost'])
+    end
+
+    it 'returns nil for a non-agi line' do
+      expect(described_class.parse_env_line('unexpected garbage')).to be_nil
+    end
+
+    it 'returns nil for a blank line' do
+      expect(described_class.parse_env_line('')).to be_nil
+    end
+  end
+
+  describe '.parse_env_block' do
+    require 'stringio'
+
+    it 'parses multiple agi_* lines into a hash' do
+      io = StringIO.new("agi_channel: SIP/1001\nagi_callerid: 555\n\n")
+      env = described_class.parse_env_block(io)
+
+      expect(env).to eq('agi_channel' => 'SIP/1001', 'agi_callerid' => '555')
+    end
+
+    it 'stops at the blank line and ignores content after it' do
+      io = StringIO.new("agi_channel: SIP/1001\n\nagi_after_blank: ignored\n")
+      env = described_class.parse_env_block(io)
+
+      expect(env).not_to have_key('agi_after_blank')
+    end
+
+    it 'yields unrecognised lines to the block' do
+      io = StringIO.new("agi_channel: SIP/1001\nunknown line\n\n")
+      unrecognised = []
+      described_class.parse_env_block(io) { |l| unrecognised << l }
+
+      expect(unrecognised).to eq(['unknown line'])
+      expect(unrecognised.length).to eq(1)
+    end
+
+    it 'handles EOF gracefully (no blank line terminator)' do
+      io = StringIO.new("agi_channel: SIP/1001\n")
+      env = described_class.parse_env_block(io)
+
+      expect(env).to eq('agi_channel' => 'SIP/1001')
+    end
+  end
+
+  describe '.collect_multiline_error' do
+    require 'stringio'
+
+    let(:base_response) { { code: 520, result: nil, data: nil } }
+
+    it 'returns first_response unchanged when first_line has no continuation marker' do
+      io = StringIO.new('')
+      result = described_class.collect_multiline_error('520 Invalid command syntax', base_response, io)
+
+      expect(result).to equal(base_response)
+    end
+
+    it 'reads continuation lines until the closing NNN line and joins them' do
+      continuation = "520-Usage: WAIT FOR DIGIT <timeout>\n520 End of proper usage.\n"
+      io = StringIO.new(continuation)
+      result = described_class.collect_multiline_error('520-Invalid command syntax.', base_response, io)
+
+      expect(result[:code]).to eq(520)
+      expect(result[:data]).to include('Invalid command syntax')
+      expect(result[:data]).to include('WAIT FOR DIGIT')
+    end
+
+    it 'preserves the code from first_response' do
+      continuation = "520-Details\n520 End of proper usage.\n"
+      io = StringIO.new(continuation)
+      result = described_class.collect_multiline_error('520-Intro', { code: 520, result: nil, data: nil }, io)
+
+      expect(result[:code]).to eq(520)
+    end
+
+    it 'returns a frozen hash' do
+      continuation = "520-Usage line\n520 End of proper usage.\n"
+      io = StringIO.new(continuation)
+      result = described_class.collect_multiline_error('520-Intro', base_response, io)
+
+      expect(result).to be_frozen
+    end
+  end
+
+  describe '.error?' do
+    it 'returns true for 5xx codes' do
+      expect(described_class.error?(code: 510, result: nil, data: 'x')).to be(true)
+      expect(described_class.error?(code: 520, result: nil, data: 'x')).to be(true)
+    end
+
+    it 'returns false for 200' do
+      expect(described_class.error?(code: 200, result: '1', data: nil)).to be(false)
+    end
+
+    it 'returns false for code 0' do
+      expect(described_class.error?(code: 0, result: nil, data: 'x')).to be(false)
+    end
+  end
+end

data/spec/ruby-asterisk/agi/server_spec.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'ruby-asterisk/agi/server'
+require 'socket'
+require 'timeout'
+
+# Starts an AGI server on an ephemeral port and returns [server, server_thread, port].
+# Automatically registers an after hook that calls stop and joins the thread.
+def start_test_server(server, &)
+  server.handle(&)
+  thread = Thread.new { server.run }
+  Timeout.timeout(2) { sleep 0.01 until server.running? || !thread.alive? }
+  raise 'Server did not start' unless server.running?
+
+  [thread, server.port]
+end
+
+# Connect as a fake Asterisk client, send env + responses, collect written commands.
+def fake_asterisk_session(port, env_lines: [], responses: [])
+  socket = TCPSocket.new('127.0.0.1', port)
+  # Send env block
+  env_lines.each { |l| socket.puts(l) }
+  socket.puts('') # blank line terminates env
+
+  received_commands = []
+  responses.each do |resp|
+    cmd = socket.gets
+    received_commands << cmd.chomp if cmd
+    socket.puts(resp)
+  end
+
+  socket.close
+  received_commands
+rescue StandardError => e
+  socket&.close
+  raise e
+end
+
+RSpec.describe RubyAsterisk::AGI::Server do
+  let(:logger) { instance_double(Logger, info: nil, warn: nil, error: nil, debug: nil) }
+  subject(:server) { described_class.new('127.0.0.1', 0, logger: logger) }
+
+  after do
+    server.stop if server.running?
+  end
+
+  describe '#initialize' do
+    it 'stores the host' do
+      expect(server.host).to eq('127.0.0.1')
+    end
+
+    it 'starts with running? false' do
+      expect(server.running?).to be(false)
+    end
+  end
+
+  describe '#handle' do
+    it 'stores the handler and returns self' do
+      result = server.handle { |s| s }
+      expect(result).to be(server)
+    end
+  end
+
+  describe '#run' do
+    it 'raises RubyAsterisk::Error when no handler is registered' do
+      expect { server.run }.to raise_error(RubyAsterisk::Error, /No handler registered/)
+    end
+
+    it 'blocks and sets running? to true while accepting' do
+      _thread, _port = start_test_server(server) { |_s| nil }
+      expect(server.running?).to be(true)
+    end
+
+    it 'sets running? back to false after stop' do
+      thread, = start_test_server(server) { |_s| nil }
+      server.stop
+      thread.join(2)
+      expect(server.running?).to be(false)
+    end
+
+    it 'updates port to the actual bound port when given 0' do
+      start_test_server(server) { |_s| nil }
+      expect(server.port).to be > 0
+    end
+  end
+
+  describe 'connection handling' do
+    it 'invokes the handler with a Session for each connection' do
+      sessions_seen = []
+      _thread, port = start_test_server(server) do |session|
+        sessions_seen << session
+      end
+
+      fake_asterisk_session(port, env_lines: ['agi_channel: SIP/test'])
+      sleep 0.1
+      server.stop
+
+      expect(sessions_seen.length).to eq(1)
+      expect(sessions_seen.first).to be_a(RubyAsterisk::AGI::Session)
+    end
+
+    it 'populates session.env from the AGI environment block' do
+      captured_env = nil
+      _thread, port = start_test_server(server) do |session|
+        captured_env = session.env.dup
+      end
+
+      fake_asterisk_session(port, env_lines: ['agi_channel: SIP/alice', 'agi_callerid: 5551234'])
+      sleep 0.1
+      server.stop
+
+      expect(captured_env['agi_channel']).to eq('SIP/alice')
+      expect(captured_env['agi_callerid']).to eq('5551234')
+    end
+
+    it 'exchanges AGI commands and responses correctly' do
+      _thread, port = start_test_server(server) do |session|
+        session.answer
+        session.hangup
+      end
+
+      cmds = fake_asterisk_session(port,
+                                   env_lines: ['agi_channel: SIP/test'],
+                                   responses: ['200 result=1', '200 result=1'])
+      server.stop
+
+      expect(cmds).to eq(%w[ANSWER HANGUP])
+    end
+
+    it 'does not crash the accept loop when a handler raises' do
+      call_count = 0
+      _thread, port = start_test_server(server) do |_session|
+        call_count += 1
+        raise 'deliberate error' if call_count == 1
+      end
+
+      fake_asterisk_session(port, env_lines: [])
+      sleep 0.05
+      fake_asterisk_session(port, env_lines: [])
+      sleep 0.05
+      server.stop
+
+      expect(call_count).to eq(2)
+      expect(logger).to have_received(:error).at_least(:once)
+    end
+  end
+
+  describe 'concurrency' do
+    it 'handles multiple simultaneous connections using Fiber scheduling' do
+      guard            = Mutex.new
+      started          = 0
+      finished         = 0
+      captured_scheduler = nil
+
+      _thread, port = start_test_server(server) do |_session|
+        guard.synchronize do
+          started += 1
+          captured_scheduler ||= Fiber.scheduler
+        end
+        sleep 0.2
+        guard.synchronize { finished += 1 }
+      end
+
+      start = Time.now
+
+      Array.new(5) do
+        Thread.new do
+          fake_asterisk_session(port, env_lines: [])
+        rescue StandardError
+          nil
+        end
+      end.each(&:join)
+
+      # Wait until all 5 handlers have started.
+      Timeout.timeout(2) { sleep 0.01 until started == 5 }
+
+      server.stop
+
+      # With Fiber scheduling all 5 handlers run concurrently, so finishing
+      # takes ~0.2s regardless of connection count.
+      Timeout.timeout(2) { sleep 0.01 until finished == 5 }
+      elapsed = Time.now - start
+
+      expect(finished).to eq(5)
+      expect(elapsed).to be < 0.8
+      # Proves handlers ran inside an Async Fiber scheduler, not threads.
+      expect(captured_scheduler).not_to be_nil
+    end
+  end
+
+  describe '#stop' do
+    it 'is idempotent — calling twice does not raise' do
+      start_test_server(server) { |_s| nil }
+      server.stop
+      expect { server.stop }.not_to raise_error
+    end
+  end
+end