ruby-asterisk 0.1.0 → 1.0.0

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

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'ruby-asterisk/agi/session'
+require 'stringio'
+
+RSpec.describe RubyAsterisk::AGI::Session do
+  # A fake socket backed by StringIO for reads and a StringIO capture for writes.
+  def fake_socket(input_string, responses: [])
+    reader = StringIO.new(input_string)
+    writer = StringIO.new
+    socket = double('socket')
+
+    allow(socket).to receive(:gets) do
+      line = reader.gets
+      line || responses.shift
+    end
+    allow(socket).to receive(:write) { |data| writer.write(data) }
+
+    [socket, writer]
+  end
+
+  # Builds a socket whose reads cycle through env_block then response_lines
+  def session_socket(env_block, response_lines)
+    all_input = env_block + response_lines.map { |l| "#{l}\n" }.join
+    socket, writer = fake_socket(all_input)
+    [socket, writer]
+  end
+
+  let(:logger) { instance_double(Logger, debug: nil, info: nil, warn: nil, error: nil) }
+
+  describe '#read_env' do
+    it 'parses agi_* key/value pairs from the env block' do
+      env_block = "agi_channel: SIP/test-1\nagi_callerid: 1000\n\n"
+      socket, = fake_socket(env_block)
+      session = described_class.new(socket, logger: logger)
+      session.read_env
+
+      expect(session.env['agi_channel']).to eq('SIP/test-1')
+      expect(session.env['agi_callerid']).to eq('1000')
+    end
+
+    it 'stops at the blank line' do
+      env_block = "agi_channel: SIP/test-1\n\nagi_after_blank: ignored\n"
+      socket, = fake_socket(env_block)
+      session = described_class.new(socket, logger: logger)
+      session.read_env
+
+      expect(session.env).not_to have_key('agi_after_blank')
+    end
+
+    it 'ignores non-agi lines with a debug log' do
+      env_block = "agi_channel: SIP/x\nunknown line\n\n"
+      socket, = fake_socket(env_block)
+      session = described_class.new(socket, logger: logger)
+      session.read_env
+
+      expect(logger).to have_received(:debug).with(/unexpected line/)
+      expect(session.env.keys).to eq(['agi_channel'])
+    end
+  end
+
+  describe '#execute' do
+    subject(:session) { described_class.new(socket, logger: logger) }
+
+    let(:socket) do
+      s, = session_socket('', ['200 result=1'])
+      s
+    end
+
+    it 'returns a parsed response hash' do
+      result = session.execute('ANSWER')
+      expect(result).to eq(code: 200, result: '1', data: nil)
+    end
+
+    it 'raises RubyAsterisk::Error on 5xx response' do
+      s = double('socket')
+      allow(s).to receive(:write)
+      allow(s).to receive(:gets).and_return("510 Invalid or unknown command\n")
+      session = described_class.new(s, logger: logger)
+
+      expect { session.execute('BADCMD') }.to raise_error(RubyAsterisk::Error, /510/)
+    end
+
+    it 'raises RubyAsterisk::Error on EOF (nil)' do
+      s = double('socket')
+      allow(s).to receive(:write)
+      allow(s).to receive(:gets).and_return(nil)
+      session = described_class.new(s, logger: logger)
+
+      expect { session.execute('ANSWER') }.to raise_error(RubyAsterisk::Error)
+    end
+  end
+
+  describe 'command wrappers' do
+    let(:written) { StringIO.new }
+    let(:socket) do
+      s = double('socket')
+      allow(s).to receive(:write) { |data| written.write(data) }
+      allow(s).to receive(:gets).and_return("200 result=1\n")
+      s
+    end
+    subject(:session) { described_class.new(socket, logger: logger) }
+
+    it '#answer writes ANSWER command' do
+      session.answer
+      expect(written.string).to eq("ANSWER\n")
+    end
+
+    it '#hangup writes HANGUP without channel' do
+      session.hangup
+      expect(written.string).to eq("HANGUP\n")
+    end
+
+    it '#hangup writes HANGUP with channel' do
+      session.hangup('SIP/1001')
+      expect(written.string).to eq("HANGUP SIP/1001\n")
+    end
+
+    it '#stream_file quotes filename and escape_digits' do
+      session.stream_file('hello-world', '#*')
+      expect(written.string).to eq(%(STREAM FILE "hello-world" "#*"\n))
+    end
+
+    it '#stream_file uses empty escape_digits by default' do
+      session.stream_file('hello-world')
+      expect(written.string).to eq(%(STREAM FILE "hello-world" ""\n))
+    end
+
+    it '#say_digits writes SAY DIGITS command' do
+      session.say_digits('1234')
+      expect(written.string).to eq(%(SAY DIGITS 1234 ""\n))
+    end
+
+    it '#say_number writes SAY NUMBER command' do
+      session.say_number(42)
+      expect(written.string).to eq(%(SAY NUMBER 42 ""\n))
+    end
+
+    it '#exec writes EXEC command with joined args' do
+      session.exec('AGICommand', 'arg1', 'arg2')
+      expect(written.string).to eq(%(EXEC AGICommand "arg1,arg2"\n))
+    end
+
+    it '#set_variable writes SET VARIABLE command' do
+      session.set_variable('MYVAR', 'hello')
+      expect(written.string).to eq(%(SET VARIABLE MYVAR "hello"\n))
+    end
+
+    it '#get_variable writes GET VARIABLE command' do
+      session.get_variable('MYVAR')
+      expect(written.string).to eq("GET VARIABLE MYVAR\n")
+    end
+
+    it '#get_data writes GET DATA command with defaults' do
+      session.get_data('silence')
+      expect(written.string).to eq(%(GET DATA "silence" 5000 1024\n))
+    end
+
+    it '#get_data accepts timeout and max_digits overrides' do
+      session.get_data('beep', timeout: 3000, max_digits: 4)
+      expect(written.string).to eq(%(GET DATA "beep" 3000 4\n))
+    end
+
+    it '#verbose writes VERBOSE command' do
+      session.verbose('test message', level: 2)
+      expect(written.string).to eq(%(VERBOSE "test message" 2\n))
+    end
+
+    it '#exec escapes args containing commas correctly' do
+      session.exec('AGI', 'arg,with,commas', 'say "hi"')
+      expect(written.string).to eq(%(EXEC AGI "arg,with,commas,say \\"hi\\""\n))
+    end
+
+    # -- Telephony commands ---------------------------------------------------
+
+    it '#dial writes EXEC Dial with target and timeout' do
+      session.dial('SIP/1001', timeout: 30)
+      expect(written.string).to eq(%(EXEC Dial "SIP/1001,30"\n))
+    end
+
+    it '#dial includes options when provided' do
+      session.dial('SIP/1001', timeout: 15, options: 'r')
+      expect(written.string).to eq(%(EXEC Dial "SIP/1001,15,r"\n))
+    end
+
+    it '#wait_for_digit writes WAIT FOR DIGIT with timeout' do
+      session.wait_for_digit(3000)
+      expect(written.string).to eq("WAIT FOR DIGIT 3000\n")
+    end
+
+    it '#wait_for_digit uses 5000ms default timeout' do
+      session.wait_for_digit
+      expect(written.string).to eq("WAIT FOR DIGIT 5000\n")
+    end
+
+    it '#record_file writes RECORD FILE with beep by default' do
+      session.record_file('recording', format: 'wav', escape_digits: '#', timeout_ms: 10_000, offset: 0)
+      expect(written.string).to eq(%(RECORD FILE "recording" wav "#" 10000 0 BEEP\n))
+    end
+
+    it '#record_file includes silence param when provided' do
+      session.record_file('msg', silence: 5)
+      expect(written.string).to eq(%(RECORD FILE "msg" wav "#" -1 0 BEEP s=5\n))
+    end
+
+    it '#record_file omits BEEP when beep: false' do
+      session.record_file('msg', beep: false)
+      expect(written.string).to eq(%(RECORD FILE "msg" wav "#" -1 0\n))
+    end
+
+    it '#send_text writes SEND TEXT with quoted message' do
+      session.send_text('hello world')
+      expect(written.string).to eq(%(SEND TEXT "hello world"\n))
+    end
+
+    it '#send_image writes SEND IMAGE with filename' do
+      session.send_image('logo.png')
+      expect(written.string).to eq("SEND IMAGE logo.png\n")
+    end
+
+    it '#channel_status writes CHANNEL STATUS without arg by default' do
+      session.channel_status
+      expect(written.string).to eq("CHANNEL STATUS\n")
+    end
+
+    it '#channel_status writes CHANNEL STATUS with a channel name' do
+      session.channel_status('SIP/1001')
+      expect(written.string).to eq("CHANNEL STATUS SIP/1001\n")
+    end
+
+    # -- AstDB commands -------------------------------------------------------
+
+    it '#database_get writes DATABASE GET command' do
+      session.database_get('family', 'key')
+      expect(written.string).to eq("DATABASE GET family key\n")
+    end
+
+    it '#database_put writes DATABASE PUT command with quoted value' do
+      session.database_put('family', 'key', 'hello world')
+      expect(written.string).to eq(%(DATABASE PUT family key "hello world"\n))
+    end
+
+    it '#database_del writes DATABASE DEL command' do
+      session.database_del('family', 'key')
+      expect(written.string).to eq("DATABASE DEL family key\n")
+    end
+
+    it '#database_deltree writes DATABASE DELTREE without subtree' do
+      session.database_deltree('family')
+      expect(written.string).to eq("DATABASE DELTREE family\n")
+    end
+
+    it '#database_deltree writes DATABASE DELTREE with subtree' do
+      session.database_deltree('family', 'sub/tree')
+      expect(written.string).to eq("DATABASE DELTREE family sub/tree\n")
+    end
+  end
+
+  describe 'multi-line 520 error handling' do
+    let(:logger) { instance_double(Logger, debug: nil, info: nil, warn: nil, error: nil) }
+
+    it 'raises with the accumulated body for a 520- intro followed by 520 closer' do
+      lines = [
+        "520-Invalid command syntax.  Proper usage follows:\n",
+        "520-Usage: WAIT FOR DIGIT <timeout>\n",
+        "520 End of proper usage.\n"
+      ]
+      socket = double('socket')
+      allow(socket).to receive(:write)
+      allow(socket).to receive(:gets).and_return(*lines)
+      session = described_class.new(socket, logger: logger)
+
+      expect { session.execute('BADCMD') }
+        .to raise_error(RubyAsterisk::Error, /Invalid command syntax/)
+    end
+
+    it 'accumulates the usage lines into the error message' do
+      lines = [
+        "520-Invalid command syntax.  Proper usage follows:\n",
+        "520-Usage: WAIT FOR DIGIT <timeout>\n",
+        "520 End of proper usage.\n"
+      ]
+      socket = double('socket')
+      allow(socket).to receive(:write)
+      allow(socket).to receive(:gets).and_return(*lines)
+      session = described_class.new(socket, logger: logger)
+
+      expect { session.execute('BADCMD') }
+        .to raise_error(RubyAsterisk::Error, /WAIT FOR DIGIT/)
+    end
+  end
+end

data/spec/ruby-asterisk/ami/async_client_spec.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'ruby-asterisk/ami/client'
+require 'ruby-asterisk/ami/promise'
+require 'support/mock_ami_server'
+require 'timeout'
+
+# Helpers shared across examples in this file
+ASYNC_NEWLINES = ["\r\n", "\n"].freeze
+
+# Builds a MockAMIServer block that responds to Login and Ping commands.
+def ami_responder
+  lambda do |sock|
+    buf = +''
+    while (line = sock.gets)
+      buf << line
+      next unless ASYNC_NEWLINES.include?(line)
+
+      if buf =~ /ActionID: (\S+)/
+        action_id = Regexp.last_match(1)
+        if buf.include?('Action: Login')
+          sock.print "Response: Success\r\nActionID: #{action_id}\r\nMessage: Authentication accepted\r\n\r\n"
+        elsif buf.include?('Action: Ping')
+          sock.print "Response: Success\r\nActionID: #{action_id}\r\nPing: Pong\r\n\r\n"
+        end
+      end
+      buf.clear
+    end
+  end
+end
+
+RSpec.describe 'RubyAsterisk::AMI::Client — async behaviour' do
+  # -------------------------------------------------------------------------
+  # Shared setup: a standard mock Asterisk server
+  # -------------------------------------------------------------------------
+  before do
+    @server_thread, @port = MockAMIServer.start(&ami_responder)
+  end
+
+  after { @server_thread&.kill }
+
+  let(:client) { RubyAsterisk::AMI::Client.new(host: 'localhost', port: @port) }
+
+  # -------------------------------------------------------------------------
+  # execute is non-blocking
+  # -------------------------------------------------------------------------
+  describe '#execute non-blocking behaviour' do
+    it 'returns a Promise without waiting for Asterisk' do
+      client.connect
+
+      start_time = Time.now
+      promise = client.ping # internally calls execute
+      elapsed = Time.now - start_time
+
+      expect(promise).to be_a(RubyAsterisk::AMI::Promise)
+      expect(elapsed).to be < 0.5    # near-instant — no blocking wait
+
+      promise.value(2)               # clean up: wait for response
+      client.disconnect
+    end
+
+    it 'promise is not yet resolved right after execute' do
+      client.connect
+      promise = client.ping
+      # Promise may or may not be resolved immediately — just check it is a Promise
+      expect(promise).to be_a(RubyAsterisk::AMI::Promise)
+      promise.value(2)
+      client.disconnect
+    end
+  end
+
+  # -------------------------------------------------------------------------
+  # Promise resolves to a proper Response
+  # -------------------------------------------------------------------------
+  describe 'Promise#value' do
+    it 'returns a RubyAsterisk::Response on success' do
+      client.connect
+      response = client.ping.value(2)
+      expect(response).to be_a(RubyAsterisk::Response)
+      expect(response.success).to be true
+      client.disconnect
+    end
+
+    it 'raises Timeout::Error when no response arrives in time' do
+      # Server accepts but never responds to commands
+      silent_thread, silent_port = MockAMIServer.start { |_sock| sleep 30 }
+
+      begin
+        slow_client = RubyAsterisk::AMI::Client.new(host: 'localhost', port: silent_port)
+        slow_client.connect
+        promise = slow_client.execute('Ping')
+        expect { promise.value(0.2) }.to raise_error(Timeout::Error)
+        slow_client.disconnect
+      ensure
+        silent_thread&.kill
+      end
+    end
+  end
+
+  # -------------------------------------------------------------------------
+  # Multiple concurrent commands
+  # -------------------------------------------------------------------------
+  describe 'concurrent commands' do
+    it 'resolves multiple in-flight promises independently' do
+      client.connect
+
+      # Fire three pings without waiting for any of them
+      promises = Array.new(3) { client.ping }
+
+      # Now collect all responses
+      responses = promises.map { |p| p.value(2) }
+
+      expect(responses).to all(be_a(RubyAsterisk::Response))
+      expect(responses.map(&:success)).to all(be true)
+
+      client.disconnect
+    end
+  end
+
+  # -------------------------------------------------------------------------
+  # Disconnect rejects pending promises
+  # -------------------------------------------------------------------------
+  describe '#disconnect' do
+    it 'rejects promises that are still pending' do
+      # Use a server that accepts the connection but never responds to commands
+      slow_thread, slow_port = MockAMIServer.start { |_sock| sleep 30 }
+
+      begin
+        slow_client = RubyAsterisk::AMI::Client.new(host: 'localhost', port: slow_port)
+        slow_client.connect
+
+        promise = slow_client.execute('Ping')
+        slow_client.disconnect # tears down before response arrives
+
+        expect { promise.value(0.5) }.to raise_error(RuntimeError, /disconnected/i)
+      ensure
+        slow_thread&.kill
+      end
+    end
+
+    it 'sets connected to false' do
+      client.connect
+      expect(client.connected).to be true
+      client.disconnect
+      expect(client.connected).to be false
+    end
+  end
+
+  # -------------------------------------------------------------------------
+  # A timed-out promise must not leak in the reactor's pending map
+  # -------------------------------------------------------------------------
+  describe 'pending-promise cleanup on timeout' do
+    it 'unregisters the promise after Promise#value times out' do
+      silent_thread, silent_port = MockAMIServer.start { |_sock| sleep 30 }
+
+      begin
+        c = RubyAsterisk::AMI::Client.new(host: 'localhost', port: silent_port)
+        c.connect
+        promise = c.execute('Ping')
+        expect { promise.value(0.2) }.to raise_error(Timeout::Error)
+
+        pending = c.instance_variable_get(:@reactor).instance_variable_get(:@promises)
+        expect(pending).to be_empty
+
+        c.disconnect
+      ensure
+        silent_thread&.kill
+      end
+    end
+  end
+
+  # -------------------------------------------------------------------------
+  # Per-command timeout must not mutate the client-wide default
+  # -------------------------------------------------------------------------
+  describe 'per-command timeout isolation' do
+    it 'does not raise the shared default timeout' do
+      client.connect
+      expect(client.instance_variable_get(:@timeout)).to eq(5)
+
+      client.originate('SIP/100', 'default', '200', '1', timeout: 300_000)
+
+      expect(client.instance_variable_get(:@timeout)).to eq(5)
+      client.disconnect
+    end
+  end
+
+  # -------------------------------------------------------------------------
+  # A caller-supplied ActionID replaces the generated one instead of being
+  # appended as a second ActionID header (which would break correlation)
+  # -------------------------------------------------------------------------
+  describe 'caller-supplied ActionID' do
+    it 'sends exactly one ActionID header and still resolves the promise' do
+      frames = Thread::Queue.new
+      echo_thread, echo_port = MockAMIServer.start do |sock|
+        buf = +''
+        while (line = sock.gets)
+          buf << line
+          next unless ASYNC_NEWLINES.include?(line)
+
+          frames << buf.dup
+          sock.print "Response: Success\r\nActionID: #{buf[/ActionID: (\S+)/, 1]}\r\n\r\n"
+          buf.clear
+        end
+      end
+
+      begin
+        c = RubyAsterisk::AMI::Client.new(host: 'localhost', port: echo_port)
+        c.connect
+        response = c.status(channel: 'SIP/alice-001', action_id: 'custom-id').value(2)
+
+        frame = frames.pop
+        expect(frame.scan(/^ActionID:/).size).to eq(1)
+        expect(frame).to include("ActionID: custom-id\r\n")
+        expect(response.success).to be true
+
+        c.disconnect
+      ensure
+        echo_thread&.kill
+      end
+    end
+  end
+
+  # -------------------------------------------------------------------------
+  # WaitEvent with a negative Timeout must not impose a Promise deadline
+  # -------------------------------------------------------------------------
+  describe '#wait_event' do
+    it 'leaves the promise without a deadline when Timeout is negative' do
+      client.connect
+
+      promise = client.wait_event(timeout: -1)
+
+      expect(promise.instance_variable_get(:@timeout)).to be_nil
+      client.disconnect
+    end
+
+    it 'keeps the client default as the floor for a positive Timeout' do
+      client.connect
+
+      promise = client.wait_event(timeout: 30)
+
+      expect(promise.instance_variable_get(:@timeout)).to eq(30)
+      client.disconnect
+    end
+  end
+
+  # -------------------------------------------------------------------------
+  # Commands issued before connect fail loudly rather than hanging
+  # -------------------------------------------------------------------------
+  describe 'guard when not connected' do
+    it 'raises instead of NoMethodError' do
+      fresh = RubyAsterisk::AMI::Client.new(host: 'localhost', port: @port)
+      expect { fresh.execute('Ping') }.to raise_error(RubyAsterisk::Error, /not connected/i)
+    end
+  end
+end

data/spec/ruby-asterisk/ami/multi_event_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'ruby-asterisk/ami/client'
+require 'support/mock_ami_server'
+require 'timeout'
+
+# Regression coverage for AMI EventList (multi-frame) responses. A list action
+# replies with an ack frame (EventList: start), then one Event frame per item,
+# then a terminating *Complete event — each a separate \r\n\r\n frame carrying
+# the same ActionID. The Reactor must aggregate them before resolving so that
+# ResponseParser can extract the structured data.
+FRAME_NEWLINES = ["\r\n", "\n"].freeze
+
+def list_responder
+  lambda do |sock|
+    buf = +''
+    while (line = sock.gets)
+      buf << line
+      next unless FRAME_NEWLINES.include?(line)
+
+      if buf.include?('Action: CoreShowChannels') && buf =~ /ActionID: (\S+)/
+        id = Regexp.last_match(1)
+        sock.print "Response: Success\r\nActionID: #{id}\r\nEventList: start\r\n" \
+                   "Message: Channels will follow\r\n\r\n"
+        sock.print "Event: CoreShowChannel\r\nActionID: #{id}\r\n" \
+                   "Channel: SIP/100-00000001\r\nChannelState: 6\r\n\r\n"
+        sock.print "Event: CoreShowChannel\r\nActionID: #{id}\r\n" \
+                   "Channel: SIP/200-00000002\r\nChannelState: 6\r\n\r\n"
+        sock.print "Event: CoreShowChannelsComplete\r\nActionID: #{id}\r\n" \
+                   "EventList: Complete\r\nListItems: 2\r\n\r\n"
+      end
+      buf.clear
+    end
+  end
+end
+
+RSpec.describe 'RubyAsterisk::AMI::Client — EventList aggregation' do
+  before { @server_thread, @port = MockAMIServer.start(&list_responder) }
+  after { @server_thread&.kill }
+
+  let(:client) { RubyAsterisk::AMI::Client.new(host: 'localhost', port: @port) }
+
+  it 'aggregates the ack, event, and Complete frames into one Response' do
+    client.connect
+    response = client.core_show_channels.value(2)
+
+    expect(response).to be_a(RubyAsterisk::Response)
+    expect(response.data).to be_a(Hash)
+    channels = response.data[:channels]
+    expect(channels.size).to eq(2)
+    expect(channels.map { |c| c['Channel'] })
+      .to contain_exactly('SIP/100-00000001', 'SIP/200-00000002')
+
+    client.disconnect
+  end
+end