ruby-asterisk 0.1.0 → 1.0.0

data/lib/ruby-asterisk/ami/commands/mailbox.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module AMI
+    module Commands
+      ##
+      #
+      # Mailbox commands
+      #
+      module Mailbox
+        def mailbox_status(mailbox:, context: 'default')
+          execute 'MailboxStatus', { 'Mailbox' => "#{mailbox}@#{context}" }
+        end
+
+        def mailbox_count(mailbox:, context: 'default')
+          execute 'MailboxCount', { 'Mailbox' => "#{mailbox}@#{context}" }
+        end
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ami/commands/monitor.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module AMI
+    module Commands
+      ##
+      #
+      # Monitor commands
+      #
+      module Monitor
+        def monitor(channel, mix: false, file: nil, format: 'wav')
+          execute 'Monitor', { 'Channel' => channel, 'File' => file, 'Mix' => mix, 'Format' => format }
+        end
+
+        def stop_monitor(channel)
+          execute 'StopMonitor', { 'Channel' => channel }
+        end
+
+        def pause_monitor(channel)
+          execute 'PauseMonitor', { 'Channel' => channel }
+        end
+
+        def unpause_monitor(channel)
+          execute 'UnpauseMonitor', { 'Channel' => channel }
+        end
+
+        def change_monitor(channel:, file:)
+          execute 'ChangeMonitor', { 'Channel' => channel, 'File' => file }
+        end
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ami/commands/queue.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module AMI
+    module Commands
+      ##
+      #
+      # Queue commands
+      #
+      module Queue
+        def queues
+          execute 'Queues', {}
+        end
+
+        def queue_add(queue, interface, penalty: 2, paused: false, member_name: '')
+          execute 'QueueAdd',
+                  { 'Queue' => queue, 'Interface' => interface, 'Penalty' => penalty, 'Paused' => paused,
+                    'MemberName' => member_name }
+        end
+
+        def queue_remove(queue:, interface:)
+          execute 'QueueRemove', { 'Queue' => queue, 'Interface' => interface }
+        end
+
+        def queue_status
+          execute 'QueueStatus'
+        end
+
+        def queue_summary(queue)
+          execute 'QueueSummary', { 'Queue' => queue }
+        end
+
+        def queue_pause(interface:, paused:, queue:, reason: 'none')
+          execute 'QueuePause', { 'Interface' => interface, 'Paused' => paused, 'Queue' => queue, 'Reason' => reason }
+        end
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ami/commands/sip.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module AMI
+    module Commands
+      ##
+      #
+      # Sip commands
+      #
+      module Sip
+        def sip_peers
+          execute 'SIPpeers'
+        end
+
+        def sip_show_peer(peer)
+          execute 'SIPshowpeer', { 'Peer' => peer }
+        end
+
+        def sip_show_registry
+          execute 'SIPshowregistry'
+        end
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ami/commands/system.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module AMI
+    module Commands
+      ##
+      #
+      # System commands
+      #
+      module System
+        def parked_calls
+          execute 'ParkedCalls'
+        end
+
+        def device_state_list
+          execute 'DeviceStateList'
+        end
+
+        def skinny_devices
+          execute 'SKINNYdevices'
+        end
+
+        def skinny_lines
+          execute 'SKINNYlines'
+        end
+
+        def ping
+          execute 'Ping'
+        end
+
+        def event_mask(event_mask = 'off')
+          execute 'Events', { 'EventMask' => event_mask }
+        end
+
+        # A negative Timeout tells Asterisk to wait indefinitely, so the Promise
+        # must not impose a deadline either: #value then blocks until an event
+        # arrives (pass an explicit `value(seconds)` to bound the wait).
+        def wait_event(timeout: -1)
+          seconds = timeout.to_i
+          execute 'WaitEvent', { 'Timeout' => timeout },
+                  timeout: (seconds.negative? ? nil : [@timeout, seconds].max)
+        end
+
+        def command(command)
+          execute 'Command', { 'Command' => command }
+        end
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ami/event.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module AMI
+    ##
+    # Immutable value object representing a parsed AMI event.
+    # All attributes are frozen for thread-safe sharing.
+    #
+    class Event
+      attr_reader :name, :headers, :raw
+
+      # @param headers [Hash] frozen hash of parsed AMI headers (Key => Value strings)
+      # @param raw     [String] frozen raw message string including the trailing \r\n\r\n
+      def initialize(headers, raw)
+        @name    = headers['Event'].freeze
+        @headers = headers
+        @raw     = raw
+        freeze
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ami/event_list_aggregation.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module AMI
+    # Frame-dispatch and EventList aggregation logic for {Reactor}.
+    #
+    # AMI list actions reply with an ack frame (Response: Success / EventList:
+    # start), one Event frame per item, then a terminating *Complete event —
+    # each a separate \r\n\r\n frame carrying the same ActionID. These methods
+    # buffer the follow-up events by ActionID and resolve the promise only once
+    # the Complete event arrives, so the full frame set reaches ResponseParser.
+    #
+    # Expects the includer to provide @promises, @promises_mutex, @buffers,
+    # @on_event and #resolve_promise.
+    module EventListAggregation
+      private
+
+      def dispatch(msg)
+        case msg[:type]
+        when :response
+          handle_response(msg[:action_id], msg[:headers], msg[:raw])
+        when :event
+          handle_event(msg[:event])
+        end
+      end
+
+      # A response frame either completes a single-reply command immediately or,
+      # when it opens an EventList, begins buffering the follow-up Event frames.
+      def handle_response(action_id, headers, raw)
+        if list_start?(headers)
+          start_buffer(action_id, raw)
+        else
+          resolve_promise(action_id, raw)
+        end
+      end
+
+      # Event frames carrying the ActionID of a buffering command are appended to
+      # that command's reply; the terminating Complete event resolves the promise
+      # with the full concatenated frame set. All other events go to on_event.
+      def handle_event(event)
+        action_id = event.headers['ActionID']
+        result = append_to_buffer(action_id, event.raw)
+        case result
+        when :buffered
+          nil # keep accumulating until the Complete event
+        when nil
+          @on_event&.call(event)
+        else # completed: joined raw frames
+          resolve_promise(action_id, result)
+        end
+      end
+
+      def start_buffer(action_id, raw)
+        @promises_mutex.synchronize do
+          @buffers[action_id] = [raw] if @promises.key?(action_id)
+        end
+      end
+
+      # Returns :buffered while accumulating, the joined raw when the list is
+      # complete, or nil when action_id has no active buffer.
+      def append_to_buffer(action_id, raw)
+        @promises_mutex.synchronize do
+          buffer = @buffers[action_id]
+          return nil unless buffer
+
+          buffer << raw
+          return :buffered unless list_terminator?(raw)
+
+          @buffers.delete(action_id).join
+        end
+      end
+
+      def list_start?(headers)
+        headers && headers['EventList'].to_s.casecmp?('start')
+      end
+
+      def list_terminator?(raw)
+        raw.match?(/^EventList:\s*Complete/i) || raw.match?(/^Event:.*Complete\s*$/)
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ami/parser.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'ruby-asterisk/ami/event'
+
+module RubyAsterisk
+  module AMI
+    # Stateless module for parsing raw AMI byte streams into structured messages.
+    #
+    # All methods are class-level and side-effect free; they can be called from
+    # any thread or Fiber without synchronization.
+    module Parser
+      DELIMITER     = "\r\n\r\n"
+      DELIMITER_LEN = DELIMITER.length
+
+      # Parses "Key: Value\r\n..." lines into a frozen hash.
+      # Lines without a colon separator (e.g. the AMI welcome banner) are skipped.
+      def self.parse_headers(raw)
+        headers = {}
+        raw.split(/\r?\n/).each do |line|
+          next if line.empty?
+
+          colon = line.index(':')
+          next unless colon&.positive?
+
+          headers[line[0, colon].freeze] = line[(colon + 1)..].strip.freeze
+        end
+        headers.freeze
+      end
+
+      # Extracts all complete AMI messages from +buffer+ (mutates it) and
+      # yields a frozen message hash for each one.
+      #
+      # @param buffer [String] mutable accumulation buffer
+      # @yieldparam msg [Hash] frozen: { type: :response|:event, headers:, raw:, action_id: }
+      def self.drain(buffer)
+        while (idx = buffer.index(DELIMITER))
+          raw = buffer.slice!(0, idx + DELIMITER_LEN)
+          msg = build_message(raw)
+          yield msg if msg
+        end
+      end
+
+      # Builds a single frozen message hash from a raw AMI frame, or nil if the
+      # frame carries no recognised Response/Event header.
+      def self.build_message(raw)
+        headers = parse_headers(raw)
+        return nil if headers.empty?
+
+        frozen_raw = raw.freeze
+        if headers.key?('Response')
+          { type: :response, headers: headers, raw: frozen_raw,
+            action_id: headers['ActionID'] }.freeze
+        elsif headers.key?('Event')
+          { type: :event,
+            event: RubyAsterisk::AMI::Event.new(headers, frozen_raw) }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ami/promise.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'timeout'
+require 'ruby-asterisk/response_builder'
+
+module RubyAsterisk
+  module AMI
+    ##
+    # Thread-safe promise representing a pending AMI command response.
+    #
+    # Created by {Client#execute} and resolved by the event-loop thread
+    # when the matching ActionID response arrives from Asterisk.
+    #
+    # Usage (blocking):
+    #   promise = client.ping
+    #   response = promise.value(5)   # blocks up to 5 s, returns a Response
+    #
+    # Usage (async):
+    #   promise = client.ping         # returns immediately
+    #   # ... do other work ...
+    #   response = promise.value      # blocks until resolved or timeout
+    #
+    class Promise
+      attr_reader :action_id
+
+      # Optional callback invoked when {#value} gives up on a timeout, used by
+      # the Reactor to drop the abandoned entry from its pending map.
+      attr_accessor :on_timeout
+
+      # @param action_id    [String]  the AMI ActionID this promise tracks
+      # @param command_type [String]  the AMI action name (e.g. 'Ping')
+      # @param timeout      [Numeric, nil] default seconds to wait in #value;
+      #   nil waits indefinitely (used by WaitEvent with a negative Timeout)
+      def initialize(action_id:, command_type:, timeout: 5)
+        @action_id    = action_id
+        @command_type = command_type
+        @timeout      = timeout
+        @mutex        = Mutex.new
+        @cv           = ConditionVariable.new
+        @raw          = nil
+        @error        = nil
+        @resolved     = false
+        @on_timeout   = nil
+      end
+
+      # Resolve the promise with raw AMI response data.
+      # Called by the Client event-loop thread — safe to call from any thread.
+      #
+      # @param raw [String] the raw AMI response string
+      def resolve(raw)
+        @mutex.synchronize do
+          @raw      = raw
+          @resolved = true
+          @cv.broadcast
+        end
+      end
+
+      # Reject the promise with an error.
+      # Called when the connection drops or the client disconnects.
+      #
+      # @param error [Exception]
+      def reject(error)
+        @mutex.synchronize do
+          @error    = error
+          @resolved = true
+          @cv.broadcast
+        end
+      end
+
+      # Block until the response arrives and return it as a {Response}.
+      #
+      # @param timeout [Numeric, nil] seconds to wait (defaults to the value set
+      #   at construction); nil blocks until the response arrives
+      # @return [RubyAsterisk::Response]
+      # @raise [Timeout::Error]  if no response arrives within +timeout+ seconds
+      # @raise [RuntimeError]   if the promise was rejected (e.g. disconnect)
+      def value(timeout = @timeout)
+        @mutex.synchronize do
+          unless @resolved
+            @cv.wait(@mutex, timeout)
+            unless @resolved
+              @on_timeout&.call
+              raise Timeout::Error,
+                    "Timeout waiting for AMI response (ActionID: #{@action_id})"
+            end
+          end
+          raise @error if @error
+
+          build_response
+        end
+      end
+
+      # @return [Boolean] true if the promise has been resolved or rejected
+      def resolved?
+        @mutex.synchronize { @resolved }
+      end
+
+      private
+
+      def build_response
+        ResponseBuilder.new.tap do |builder|
+          builder.type         = @command_type
+          builder.raw_response = @raw
+        end.build
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ami/reactor.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'ruby-asterisk/ami/parser'
+require 'ruby-asterisk/ami/event_list_aggregation'
+
+module RubyAsterisk
+  module AMI
+    # Hosts the AMI connection in two plain OS threads:
+    #
+    #   writer_thread — blocks on Thread::Queue#pop and writes commands to the
+    #                   AMI socket.  On :stop it closes the socket, which unblocks
+    #                   the reader thread's readpartial call.
+    #
+    #   reader_thread — loops on socket.readpartial, parses AMI frames with Parser,
+    #                   resolves pending Promises or fires the on_event callback.
+    #
+    # Using plain Threads (no Fiber scheduler) ensures deterministic shutdown on
+    # all Ruby versions: closing an IO from one Thread immediately raises IOError
+    # in any other Thread blocked on that IO.
+    #
+    # Thread-safety contract:
+    #   - External callers use #send_command, #register_promise,
+    #     #reject_all_promises, #stop — all thread-safe.
+    #   - Promise resolution via Mutex+CV (Promise class unchanged).
+    #   - No cross-thread IO inside the reactor; one thread reads, one writes.
+    class Reactor
+      include EventListAggregation
+
+      def initialize(host, port, on_event: nil, on_disconnect: nil)
+        @host          = host
+        @port          = port
+        @on_event      = on_event
+        @on_disconnect = on_disconnect
+
+        @command_queue  = Thread::Queue.new
+        @promises_mutex = Mutex.new
+        @promises       = {}
+        @buffers        = {} # action_id => Array<raw frame> for in-flight EventList replies
+        @socket         = nil
+        @writer_thread  = nil
+        @reader_thread  = nil
+        @stopping       = false
+      end
+
+      # Open the socket, consume the AMI banner, and start both threads.
+      # Raises if the connection fails.
+      def start
+        @socket = TCPSocket.new(@host, @port)
+        @socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_KEEPALIVE, true)
+        @socket.gets # consume AMI banner ("Asterisk Call Manager/x.y\n")
+
+        @writer_thread = Thread.new { writer_loop }
+        @reader_thread = Thread.new { reader_loop }
+        self
+      rescue StandardError
+        close_socket
+        raise
+      end
+
+      # Send a raw AMI command string from any external thread.
+      def send_command(cmd)
+        @command_queue.push(cmd.freeze)
+      end
+
+      # Register a Promise keyed by ActionID.
+      def register_promise(action_id, promise)
+        @promises_mutex.synchronize { @promises[action_id] = promise }
+      end
+
+      # Remove a pending Promise without resolving it (e.g. after a caller
+      # timeout) so the pending map does not grow unbounded.
+      def unregister_promise(action_id)
+        @promises_mutex.synchronize do
+          @promises.delete(action_id)
+          @buffers.delete(action_id)
+        end
+      end
+
+      # Reject all pending promises with the given error (thread-safe).
+      def reject_all_promises(error)
+        promises = @promises_mutex.synchronize do
+          @buffers.clear
+          @promises.values.tap { @promises.clear }
+        end
+        promises.each { |p| p.reject(error) }
+      end
+
+      # Stop both threads gracefully. Blocks until they exit.
+      def stop
+        return unless @writer_thread&.alive? || @reader_thread&.alive?
+
+        @stopping = true
+        @command_queue.push(:stop) # wakes writer_thread immediately
+        @writer_thread&.join(2)
+        @reader_thread&.join(2)
+        @writer_thread = nil
+        @reader_thread = nil
+      end
+
+      private
+
+      # Both loops bind the socket to a local before their first IO call:
+      # #close_socket nils out @socket, so reading the ivar inside the loop could
+      # raise NoMethodError on nil instead of the IOError the rescues expect.
+      # A closed IO object still raises IOError, which is the intended path.
+      def writer_loop
+        socket = @socket
+        loop do
+          cmd = @command_queue.pop
+          break if cmd == :stop
+
+          socket.write(cmd)
+        rescue IOError, SystemCallError
+          break # socket closed or peer reset — reader_loop handles caller notification
+        end
+      ensure
+        close_socket # raises IOError in reader_thread's readpartial
+      end
+
+      def reader_loop
+        socket = @socket
+        buffer = +''
+        loop do
+          chunk = socket.readpartial(4096)
+          buffer << chunk
+          Parser.drain(buffer) { |msg| dispatch(msg) }
+        end
+      rescue EOFError
+        handle_unexpected_disconnect('Disconnected: EOF from server') unless @stopping
+      rescue IOError, Errno::EBADF
+        handle_unexpected_disconnect('Disconnected') unless @stopping
+      rescue StandardError => e
+        # A deliberate #stop must never surface as a disconnect: the caller is
+        # notified by Client#disconnect, which rejects with its own message.
+        handle_unexpected_disconnect("Reactor read error: #{e.message}") unless @stopping
+      end
+
+      # Notify the client and fail every blocked caller when the link drops
+      # without an explicit #stop request.
+      def handle_unexpected_disconnect(message)
+        @on_disconnect&.call
+        reject_all_promises(RuntimeError.new(message))
+      end
+
+      def resolve_promise(action_id, raw_data)
+        promise = @promises_mutex.synchronize do
+          @buffers.delete(action_id)
+          @promises.delete(action_id)
+        end
+        promise&.resolve(raw_data)
+      end
+
+      def close_socket
+        @socket&.close
+        @socket = nil
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end