ruby-asterisk 0.2.0 → 1.0.0

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

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

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'ruby-asterisk/ami/parser'
+
+RSpec.describe RubyAsterisk::AMI::Parser do
+  # Helper: push chunks into a buffer, drain, collect yielded messages.
+  def drain_chunks(*chunks)
+    buffer = +''
+    msgs   = []
+    chunks.each do |chunk|
+      buffer << chunk
+      described_class.drain(buffer) { |m| msgs << m }
+    end
+    msgs
+  end
+
+  # ── parse_headers ───────────────────────────────────────────────────────────
+
+  describe '.parse_headers' do
+    it 'parses key-value lines' do
+      raw = "Response: Success\r\nActionID: abc\r\nMessage: OK\r\n"
+      h = described_class.parse_headers(raw)
+      expect(h['Response']).to eq('Success')
+      expect(h['ActionID']).to eq('abc')
+      expect(h['Message']).to eq('OK')
+    end
+
+    it 'trims leading/trailing whitespace from values' do
+      h = described_class.parse_headers("Response: Success\r\nMessage:  hello world  \r\n")
+      expect(h['Message']).to eq('hello world')
+    end
+
+    it 'preserves colons inside values' do
+      h = described_class.parse_headers("Event: NewExten\r\nAppData: SIP/101:60\r\n")
+      expect(h['AppData']).to eq('SIP/101:60')
+    end
+
+    it 'skips lines without a colon separator (e.g. AMI welcome banner)' do
+      h = described_class.parse_headers("Asterisk Call Manager/1.1\nResponse: Success\r\n")
+      expect(h.keys).to eq(['Response'])
+    end
+
+    it 'returns a frozen hash with frozen keys and values' do
+      h = described_class.parse_headers("Response: OK\r\nActionID: x\r\n")
+      expect(h).to be_frozen
+      h.each_key   { |k| expect(k).to be_frozen }
+      h.each_value { |v| expect(v).to be_frozen }
+    end
+  end
+
+  # ── drain / split-packet reassembly ─────────────────────────────────────────
+
+  describe '.drain — split-packet reassembly' do
+    it 'assembles a Response split across two chunks' do
+      msgs = drain_chunks(
+        "Response: Success\r\nActionID: abc123\r\n",
+        "Message: OK\r\n\r\n"
+      )
+      expect(msgs.size).to eq(1)
+      expect(msgs.first[:type]).to eq(:response)
+      expect(msgs.first[:action_id]).to eq('abc123')
+      expect(msgs.first[:headers]['Message']).to eq('OK')
+    end
+
+    it 'assembles an Event split across three chunks' do
+      msgs = drain_chunks(
+        'Event: Han',
+        "gup\r\nChannel: SIP/",
+        "101\r\n\r\n"
+      )
+      expect(msgs.size).to eq(1)
+      expect(msgs.first[:type]).to eq(:event)
+      expect(msgs.first[:event].name).to eq('Hangup')
+      expect(msgs.first[:event].headers['Channel']).to eq('SIP/101')
+    end
+
+    it 'emits nothing until the delimiter arrives' do
+      msgs = drain_chunks("Response: Success\r\nActionID: xyz\r\n")
+      expect(msgs).to be_empty
+    end
+
+    it 'emits the message once the delimiter arrives' do
+      msgs = drain_chunks(
+        "Response: Success\r\nActionID: xyz\r\n",
+        "\r\n"
+      )
+      expect(msgs.size).to eq(1)
+    end
+  end
+
+  # ── multiple messages in one chunk ─────────────────────────────────────────
+
+  describe '.drain — multiple messages in one chunk' do
+    it 'emits all messages when two complete messages arrive together' do
+      two_msgs =
+        "Response: Success\r\nActionID: r1\r\n\r\n" \
+        "Event: FullyBooted\r\nPrivilege: system,all\r\nStatus: Fully Booted\r\n\r\n"
+
+      msgs = drain_chunks(two_msgs)
+      expect(msgs.size).to eq(2)
+      expect(msgs[0][:type]).to eq(:response)
+      expect(msgs[0][:action_id]).to eq('r1')
+      expect(msgs[1][:type]).to eq(:event)
+      expect(msgs[1][:event].name).to eq('FullyBooted')
+    end
+
+    it 'handles ten back-to-back events in a single chunk' do
+      chunk = (1..10).map { |i| "Event: TestEvent\r\nSequence: #{i}\r\n\r\n" }.join
+      msgs  = drain_chunks(chunk)
+      expect(msgs.size).to eq(10)
+      sequences = msgs.map { |m| m[:event].headers['Sequence'].to_i }
+      expect(sequences).to eq((1..10).to_a)
+    end
+  end
+
+  # ── Response routing ────────────────────────────────────────────────────────
+
+  describe 'response routing' do
+    it 'sets action_id from the ActionID header' do
+      msgs = drain_chunks("Response: Success\r\nActionID: myid\r\n\r\n")
+      expect(msgs.first[:action_id]).to eq('myid')
+    end
+
+    it 'sets action_id to nil when no ActionID header is present' do
+      msgs = drain_chunks("Response: Follows\r\nPrivilege: Command\r\n\r\n")
+      expect(msgs.first[:type]).to eq(:response)
+      expect(msgs.first[:action_id]).to be_nil
+    end
+
+    it 'exposes a frozen raw string' do
+      msgs = drain_chunks("Response: Error\r\nActionID: f2\r\n\r\n")
+      expect(msgs.first[:raw]).to be_frozen
+    end
+  end
+
+  # ── Event routing ───────────────────────────────────────────────────────────
+
+  describe 'event routing' do
+    it 'creates a frozen Event object with the correct name and headers' do
+      msgs = drain_chunks("Event: Hangup\r\nChannel: SIP/200\r\nCause: 16\r\n\r\n")
+      event = msgs.first[:event]
+      expect(event).to be_a(RubyAsterisk::AMI::Event)
+      expect(event).to be_frozen
+      expect(event.name).to eq('Hangup')
+      expect(event.headers['Cause']).to eq('16')
+    end
+
+    it 'Event object exposes the raw AMI message string' do
+      raw_input = "Event: Hangup\r\nChannel: SIP/200\r\n\r\n"
+      msgs = drain_chunks(raw_input)
+      expect(msgs.first[:event].raw).to eq(raw_input)
+    end
+  end
+
+  # ── AMI welcome banner tolerance ────────────────────────────────────────────
+
+  describe 'AMI welcome banner tolerance' do
+    it 'ignores the banner and still parses the subsequent response' do
+      combined =
+        "Asterisk Call Manager/1.1\n" \
+        "Response: Success\r\nActionID: banner_test\r\n\r\n"
+
+      msgs = drain_chunks(combined)
+      expect(msgs.size).to eq(1)
+      expect(msgs.first[:type]).to eq(:response)
+      expect(msgs.first[:action_id]).to eq('banner_test')
+    end
+  end
+
+  # ── build_message ────────────────────────────────────────────────────────────
+
+  describe '.build_message' do
+    it 'returns nil for frames with no recognised Response/Event header' do
+      expect(described_class.build_message("Asterisk Call Manager/1.1\r\n\r\n")).to be_nil
+    end
+
+    it 'returns a frozen response hash' do
+      msg = described_class.build_message("Response: OK\r\nActionID: x\r\n\r\n")
+      expect(msg).to be_frozen
+      expect(msg[:type]).to eq(:response)
+    end
+
+    it 'returns a frozen event hash' do
+      msg = described_class.build_message("Event: Hangup\r\n\r\n")
+      expect(msg).to be_frozen
+      expect(msg[:type]).to eq(:event)
+    end
+  end
+end