ruby-asterisk 0.1.0 → 1.0.0

data/lib/ruby-asterisk/agi/protocol.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module AGI
+    # Low-level formatter and parser for the FastAGI wire protocol.
+    module Protocol
+      ENV_LINE = /\A(agi_\w+):\s*(.*)/
+
+      # Matches a response carrying a result value:  CODE result=VALUE [extra]
+      RESULT_RE = /\A(\d{3})\s+result=(\S+)(?:\s+(.*?))?\s*\z/
+
+      # Matches any response line (fallback):  CODE[-space]message
+      CODE_RE = /\A(\d{3})(?:[-\s](.*?))?\s*\z/
+
+      # Format an AGI command string ready for sending to Asterisk.
+      #
+      # @param command [String]       AGI command verb (e.g. "ANSWER", "EXEC")
+      # @param args    [Array<#to_s>] zero or more arguments
+      # @return [String] space-joined, \n-terminated line
+      def self.format_command(command, *args)
+        parts = [command.to_s]
+        args.each { |a| parts << escape_argument(a.to_s) }
+        "#{parts.join(' ')}\n"
+      end
+
+      # Escape a single AGI command argument.
+      #
+      # Plain alphanumeric/dash/underscore/slash tokens are returned as-is.
+      # Empty strings and strings containing whitespace, quotes, or backslashes
+      # are double-quoted with internal special characters escaped.
+      #
+      # @param arg [String]
+      # @return [String]
+      def self.escape_argument(arg)
+        return '""' if arg.empty?
+        return arg unless arg.match?(/[\s"\\]/)
+
+        escaped = arg.gsub('\\') { '\\\\' }.gsub('"') { '\\"' }
+        "\"#{escaped}\""
+      end
+
+      # Always wrap +arg+ in double quotes, escaping any internal backslashes
+      # and double-quotes. Use for AGI arguments that Asterisk requires to be
+      # quoted regardless of content (filenames, variable values, messages).
+      #
+      # @param arg [String, #to_s]
+      # @return [String]
+      def self.quote(arg)
+        escaped = arg.to_s.gsub('\\') { '\\\\' }.gsub('"') { '\\"' }
+        "\"#{escaped}\""
+      end
+
+      # Parse a single raw AGI response line into a frozen Hash.
+      #
+      # @param line [String, nil]
+      # @return [Hash] { code: Integer, result: String|nil, data: String|nil }
+      def self.parse_response(line)
+        return { code: 0, result: nil, data: 'Connection closed' }.freeze if line.nil?
+
+        stripped = line.chomp
+        return { code: 0, result: nil, data: stripped }.freeze if stripped.empty?
+
+        parse_result_line(stripped) || parse_code_line(stripped) ||
+          { code: 0, result: nil, data: stripped }.freeze
+      end
+
+      # @param response [Hash] as returned by {parse_response}
+      # @return [Boolean] true when the response code signals an error
+      def self.error?(response)
+        response[:code] >= 500
+      end
+
+      # Parse a single line from the initial AGI environment block.
+      #
+      # @param line [String]
+      # @return [Array(String, String), nil] [key, value] pair or nil if not an env line
+      def self.parse_env_line(line)
+        m = ENV_LINE.match(line.chomp)
+        return nil unless m
+
+        [m[1], m[2].strip]
+      end
+
+      # Read and parse the AGI environment block from an I/O source.
+      #
+      # Reads lines via +io.gets+ until a blank line or EOF. Each recognised
+      # +agi_key: value+ line is stored in the returned Hash. Unrecognised lines
+      # are yielded to the optional block (e.g. for debug logging).
+      #
+      # @param io [#gets]
+      # @yieldparam line [String] each unrecognised line (without newline)
+      # @return [Hash{String=>String}]
+      def self.parse_env_block(io)
+        env = {}
+        while (raw = io.gets)
+          chopped = raw.chomp
+          break if chopped.empty?
+
+          pair = parse_env_line(chopped)
+          if pair
+            env[pair[0]] = pair[1]
+          elsif block_given?
+            yield chopped
+          end
+        end
+        env
+      end
+
+      # Complete a (possibly multi-line) 520 error response.
+      #
+      # Returns +first_response+ unchanged when +first_line+ does not begin with
+      # a continuation marker (+NNN-+). Otherwise reads continuation lines from
+      # +io+ until the +NNN <text>+ closing line, then returns a new frozen
+      # response hash with the accumulated body as +:data+.
+      #
+      # @param first_line     [String] the already-read first response line (chomped)
+      # @param first_response [Hash]   as returned by {parse_response}
+      # @param io             [#gets]
+      # @return [Hash]
+      def self.collect_multiline_error(first_line, first_response, io)
+        return first_response unless first_line.match?(/\A\d{3}-/)
+
+        lines = [first_line.sub(/\A\d{3}-/, '')]
+        while (l = io.gets)
+          chopped = l.chomp
+          if chopped.match?(/\A\d{3}\s/)
+            lines << chopped.sub(/\A\d{3}\s*/, '')
+            break
+          else
+            lines << chopped.sub(/\A\d{3}-/, '')
+          end
+        end
+
+        body = lines.reject(&:empty?).join(' ')
+        { code: first_response[:code], result: nil, data: body.freeze }.freeze
+      end
+
+      # -- private helpers ----------------------------------------------------
+
+      def self.parse_result_line(line)
+        m = RESULT_RE.match(line)
+        return nil unless m
+
+        extra = m[3]&.strip
+        data = extra.nil? || extra.empty? ? nil : extra.delete_prefix('(').delete_suffix(')')
+        { code: m[1].to_i, result: m[2].freeze, data: data&.freeze }.freeze
+      end
+      private_class_method :parse_result_line
+
+      def self.parse_code_line(line)
+        m = CODE_RE.match(line)
+        return nil unless m
+
+        msg = m[2]&.strip || ''
+        { code: m[1].to_i, result: nil, data: (msg.empty? ? nil : msg.freeze) }.freeze
+      end
+      private_class_method :parse_code_line
+    end
+  end
+end

data/lib/ruby-asterisk/agi/server.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'logger'
+require 'async'
+require_relative 'session'
+require_relative '../../ruby-asterisk/error'
+require_relative '../../ruby-asterisk/compat'
+
+module RubyAsterisk
+  module AGI
+    # FastAGI TCP server backed by an Async Fiber scheduler.
+    #
+    # Each incoming Asterisk connection is handled in its own Fiber, so all
+    # concurrent sessions share a single OS thread and their socket IO yields
+    # the Fiber rather than blocking.
+    #
+    # Usage:
+    #   server = RubyAsterisk::AGI::Server.new('0.0.0.0', 4573)
+    #   server.handle { |session| session.answer }
+    #   server.run         # blocks until server.stop is called
+    class Server
+      attr_reader :host, :port, :running
+
+      alias running? running
+
+      def initialize(host, port, logger: Logger.new($stdout))
+        @host    = host
+        @port    = port.to_i
+        @logger  = logger
+        @handler = nil
+        @running = false
+        @server  = nil
+      end
+
+      # Register the per-connection handler block.
+      #
+      # @yield [RubyAsterisk::AGI::Session]
+      # @return [self]
+      def handle(&block)
+        @handler = block
+        self
+      end
+
+      # Start accepting connections (blocks until {#stop} is called).
+      #
+      # @raise [RubyAsterisk::Error] if no handler has been registered
+      def run
+        raise Error, 'No handler registered' unless @handler
+
+        Sync do |parent|
+          @server  = TCPServer.new(@host, @port)
+          @port    = @server.addr[1]
+          @running = true
+          @logger.info("AGI server listening on #{@host}:#{@port}")
+          accept_loop(parent)
+        end
+      ensure
+        @running = false
+        close_server
+      end
+
+      # Signal the server to stop accepting new connections.
+      # Active sessions continue until they finish naturally.
+      def stop
+        return unless @running
+
+        @running = false
+        close_server
+      end
+
+      private
+
+      def accept_loop(parent)
+        loop do
+          begin
+            socket = @server.accept
+          rescue IOError, Errno::EBADF
+            break # server socket closed via stop — normal shutdown
+          rescue SystemCallError => e
+            # Transient accept error (e.g. EMFILE/ENFILE fd exhaustion,
+            # ECONNABORTED): log and keep serving instead of downing the server.
+            @logger.error("AGI accept error: #{e.message}")
+            next
+          end
+          parent.async { serve(socket) }
+        end
+      end
+
+      def serve(socket)
+        session = Session.new(socket, logger: @logger)
+        session.read_env
+        @handler.call(session)
+      rescue StandardError => e
+        @logger.error("AGI session error: #{e.message}")
+      ensure
+        socket.close rescue nil # rubocop:disable Style/RescueModifier
+      end
+
+      def close_server
+        @server&.close
+        @server = nil
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/agi/session.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require 'logger'
+require_relative 'protocol'
+require_relative '../../ruby-asterisk/error'
+
+module RubyAsterisk
+  module AGI
+    # Wraps a single FastAGI connection lifecycle.
+    #
+    # Parses the AGI environment block sent by Asterisk at connection start,
+    # then provides command methods that write AGI commands and return parsed
+    # response hashes.  Under an Async Fiber scheduler the socket reads/writes
+    # yield the Fiber rather than blocking a thread.
+    class Session
+      attr_reader :env, :socket
+
+      # @param env_timeout [Numeric, nil] seconds to wait for the initial AGI
+      #   environment block before giving up (guards against slowloris-style
+      #   connect-and-stall clients). Applied only to the handshake, never to
+      #   command reads (which may legitimately block for minutes, e.g. STREAM
+      #   FILE). Pass nil to disable. No-op on Ruby 3.1 (IO#timeout= shim).
+      def initialize(socket, logger: Logger.new($stdout), env_timeout: 10)
+        @socket      = socket
+        @logger      = logger
+        @env         = {}
+        @env_timeout = env_timeout
+      end
+
+      # Read the initial AGI environment block (agi_key: value lines until blank line).
+      #
+      # @raise [IO::TimeoutError] on Ruby >= 3.2 if the peer stalls beyond env_timeout
+      def read_env
+        with_env_timeout do
+          @env = Protocol.parse_env_block(@socket) do |line|
+            @logger.debug("AGI env: unexpected line: #{line}")
+          end
+        end
+      end
+
+      # Send a raw AGI command string and return the parsed response Hash.
+      #
+      # Handles Asterisk's two-line 520- syntax-error format by accumulating
+      # continuation lines until the closing `520 End of proper usage.` line.
+      #
+      # Any embedded CR/LF in +command_string+ is stripped before sending: AGI is
+      # a line-oriented protocol, so a newline in a (possibly caller-controlled)
+      # argument or identifier would otherwise inject additional commands.
+      #
+      # @param command_string [String]
+      # @return [Hash] { code: Integer, result: String|nil, data: String|nil }
+      # @raise [RubyAsterisk::Error] on EOF or 5xx response
+      # @raise [RubyAsterisk::HangupError] if Asterisk sends an out-of-band HANGUP
+      def execute(command_string)
+        line = command_string.to_s.delete("\r\n")
+        @socket.write("#{line}\n")
+        line = @socket.gets
+        raise Error, 'Connection closed by Asterisk' unless line
+        raise HangupError, 'Channel hung up' if line.chomp == 'HANGUP'
+
+        response = Protocol.parse_response(line)
+
+        if response[:code] >= 500
+          response = Protocol.collect_multiline_error(line.chomp, response, @socket)
+          raise Error, "AGI error (#{response[:code]}): #{response[:data]}"
+        end
+
+        response
+      end
+
+      # -- Existing wrappers (rewritten to use Protocol.format_command) -------
+
+      def answer
+        execute('ANSWER')
+      end
+
+      def hangup(channel = nil)
+        channel ? execute("HANGUP #{channel}") : execute('HANGUP')
+      end
+
+      def stream_file(filename, escape_digits = '')
+        execute("STREAM FILE #{Protocol.quote(filename)} #{Protocol.quote(escape_digits)}")
+      end
+
+      def say_digits(digits, escape_digits = '')
+        execute("SAY DIGITS #{digits} #{Protocol.escape_argument(escape_digits)}")
+      end
+
+      def say_number(number, escape_digits = '')
+        execute("SAY NUMBER #{number} #{Protocol.escape_argument(escape_digits)}")
+      end
+
+      def exec(application, *args)
+        execute("EXEC #{application} #{Protocol.quote(args.join(','))}")
+      end
+
+      def set_variable(name, value)
+        execute("SET VARIABLE #{name} #{Protocol.quote(value)}")
+      end
+
+      def get_variable(name)
+        execute("GET VARIABLE #{name}")
+      end
+
+      def get_data(filename, timeout: 5000, max_digits: 1024)
+        execute("GET DATA #{Protocol.quote(filename)} #{timeout} #{max_digits}")
+      end
+
+      def verbose(message, level: 1)
+        execute("VERBOSE #{Protocol.quote(message)} #{level}")
+      end
+
+      # -- Telephony commands -------------------------------------------------
+
+      # Originate a call leg via Dial dialplan application.
+      def dial(target, timeout: 30, options: '')
+        args = [target, timeout.to_s]
+        args << options unless options.to_s.empty?
+        execute("EXEC Dial #{Protocol.quote(args.join(','))}")
+      end
+
+      # Block until a DTMF digit is pressed or timeout expires.
+      # Like every verb this returns the parsed response Hash
+      # { code:, result:, data: }; the pressed key's decimal ASCII value
+      # (or -1 on timeout) is in response[:result].
+      def wait_for_digit(timeout_ms = 5000)
+        execute("WAIT FOR DIGIT #{timeout_ms}")
+      end
+
+      # Record audio to a file.
+      def record_file(filename, format: 'wav', escape_digits: '#', timeout_ms: -1, offset: 0, beep: true, silence: nil)
+        cmd = "RECORD FILE #{Protocol.quote(filename)} #{format} " \
+              "#{Protocol.quote(escape_digits)} #{timeout_ms} #{offset}"
+        cmd += ' BEEP' if beep
+        cmd += " s=#{silence}" if silence
+        execute(cmd)
+      end
+
+      def send_text(text)
+        execute("SEND TEXT #{Protocol.quote(text)}")
+      end
+
+      def send_image(filename)
+        execute("SEND IMAGE #{filename}")
+      end
+
+      def channel_status(channel = nil)
+        channel ? execute("CHANNEL STATUS #{channel}") : execute('CHANNEL STATUS')
+      end
+
+      # -- AstDB commands -----------------------------------------------------
+
+      def database_get(family, key)
+        execute("DATABASE GET #{family} #{key}")
+      end
+
+      def database_put(family, key, value)
+        execute("DATABASE PUT #{family} #{key} #{Protocol.quote(value)}")
+      end
+
+      def database_del(family, key)
+        execute("DATABASE DEL #{family} #{key}")
+      end
+
+      def database_deltree(family, keytree = nil)
+        keytree ? execute("DATABASE DELTREE #{family} #{keytree}") : execute("DATABASE DELTREE #{family}")
+      end
+
+      private
+
+      # Apply @env_timeout to the socket for the duration of the block, then
+      # restore it. No-op when the timeout is nil or the socket does not support
+      # IO#timeout= (Ruby 3.1 shim is a no-op; test doubles simply skip it).
+      def with_env_timeout
+        return yield if @env_timeout.nil? || !@socket.respond_to?(:timeout=)
+
+        previous = @socket.respond_to?(:timeout) ? @socket.timeout : nil
+        @socket.timeout = @env_timeout
+        begin
+          yield
+        ensure
+          @socket.timeout = previous
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'ruby-asterisk/version'
+require 'ruby-asterisk/error'
+require 'ruby-asterisk/request'
+require 'ruby-asterisk/response'
+require 'ruby-asterisk/response_builder'
+require 'ruby-asterisk/ami/promise'
+require 'ruby-asterisk/ami/reactor'
+
+# Commands
+Dir[File.join(File.dirname(__FILE__), 'commands', '*.rb')].each { |file| require file }
+
+module RubyAsterisk
+  module AMI
+    ##
+    # Asynchronous AMI client.
+    #
+    # {#execute} registers a {Promise} for the outgoing command and writes it
+    # to the socket via the internal {Reactor}, returning the Promise immediately
+    # without blocking.  Callers obtain the response by calling {Promise#value}
+    # on the returned Promise, which blocks only until the matching reply arrives
+    # (or a per-command timeout fires).
+    #
+    # Data pipeline:
+    #   Client (external thread)
+    #     → Reactor#send_command (Thread::Queue + IO.pipe doorbell)
+    #     → intake Fiber → socket write
+    #     → socket read → reader Fiber → Parser
+    #     → dispatcher → Promise#resolve (Mutex+CV)
+    #     → Client#execute caller (blocks on Promise#value)
+    #
+    class Client
+      include Commands::System
+      include Commands::Channel
+      include Commands::Conference
+      include Commands::Extension
+      include Commands::Queue
+      include Commands::Mailbox
+      include Commands::Sip
+      include Commands::Monitor
+
+      attr_accessor :host, :port, :connected, :timeout
+
+      def initialize(host:, port:)
+        self.host      = host.to_s
+        self.port      = port.to_i
+        self.connected = false
+        @timeout       = 5
+        @reactor       = nil
+      end
+
+      # Connect to the Asterisk AMI server and start the async reactor.
+      #
+      # @return [true, false]
+      def connect
+        @reactor = Reactor.new(host, port,
+                               on_event: method(:handle_event),
+                               on_disconnect: method(:handle_disconnect))
+        @reactor.start
+        self.connected = true
+        true
+      rescue StandardError => e
+        puts "Connection error: #{e.message}"
+        @reactor = nil
+        self.connected = false
+        false
+      end
+
+      # Disconnect from Asterisk, stop the reactor, and reject pending promises.
+      #
+      # @return [true, false]
+      def disconnect
+        @reactor&.stop
+        @reactor&.reject_all_promises(RuntimeError.new('Client disconnected'))
+        @reactor = nil
+        self.connected = false
+        true
+      rescue StandardError => e
+        puts e
+        false
+      end
+
+      def login(username:, secret:)
+        connect unless connected
+        raise Error, "Unable to connect to AMI at #{host}:#{port}" unless connected
+
+        execute 'Login', { 'Username' => username, 'Secret' => secret, 'Event' => 'On' }
+      end
+
+      def logoff
+        execute 'Logoff'
+      end
+
+      ##
+      # Send an AMI command asynchronously.
+      #
+      # A caller-supplied 'ActionID' option becomes the request's own ActionID
+      # instead of an extra header: two ActionID lines in one frame would leave
+      # the response uncorrelated with its Promise.
+      #
+      # @param command [String]  AMI action name (e.g. 'Ping', 'Login')
+      # @param options [Hash]    additional AMI headers
+      # @param timeout [Numeric, nil] seconds {Promise#value} waits by default
+      #   for this command only (does not affect other commands); nil waits
+      #   indefinitely
+      # @return [Promise]        call {Promise#value} to obtain the {Response}
+      # @raise [RubyAsterisk::Error] if the client is not connected
+      def execute(command, options = {}, timeout: @timeout)
+        raise Error, 'Not connected to AMI' unless @reactor
+
+        options   = options.dup
+        action_id = options.delete('ActionID')
+        request   = Request.new(command, options, action_id: action_id)
+        promise = Promise.new(action_id: request.action_id, command_type: command, timeout: timeout)
+        promise.on_timeout = -> { @reactor&.unregister_promise(request.action_id) }
+        @reactor.register_promise(request.action_id, promise)
+        # Push the whole frame in one operation so commands issued from concurrent
+        # threads cannot interleave their header lines on the wire.
+        @reactor.send_command(request.commands.join)
+        promise
+      end
+
+      private
+
+      def handle_event(_event)
+        # Async events received outside a command cycle — available for future use.
+      end
+
+      def handle_disconnect
+        self.connected = false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module AMI
+    module Commands
+      ##
+      #
+      # Channel commands
+      #
+      module Channel
+        def core_show_channels
+          execute 'CoreShowChannels'
+        end
+
+        def status(channel: nil, action_id: nil)
+          execute 'Status', { 'Channel' => channel, 'ActionID' => action_id }
+        end
+
+        def originate(channel, context, callee, priority, variable: nil, caller_id: nil, timeout: 30_000, async: nil)
+          execute 'Originate',
+                  { 'Channel' => channel, 'Context' => context, 'Exten' => callee, 'Priority' => priority,
+                    'CallerID' => caller_id || channel, 'Timeout' => timeout.to_s, 'Variable' => variable,
+                    'Async' => async },
+                  timeout: [@timeout, timeout / 1000].max
+        end
+
+        def originate_app(channel:, application:, data:, async:)
+          execute 'Originate',
+                  { 'Channel' => channel, 'Application' => application, 'Data' => data, 'Timeout' => '30000',
+                    'Async' => async }
+        end
+
+        def channels
+          execute 'Command', { 'Command' => 'show channels' }
+        end
+
+        def redirect(channel, context, callee, priority, variable: nil, caller_id: nil, timeout: 30_000)
+          execute 'Redirect',
+                  { 'Channel' => channel, 'Context' => context, 'Exten' => callee, 'Priority' => priority,
+                    'CallerID' => caller_id || channel, 'Timeout' => timeout.to_s, 'Variable' => variable },
+                  timeout: [@timeout, timeout / 1000].max
+        end
+
+        def hangup(channel)
+          execute 'Hangup', { 'Channel' => channel }
+        end
+
+        def atxfer(channel:, exten:, context:, priority: '1')
+          execute 'Atxfer',
+                  { 'Channel' => channel, 'Exten' => exten.to_s, 'Context' => context, 'Priority' => priority }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module AMI
+    module Commands
+      ##
+      #
+      # Conference commands
+      #
+      module Conference
+        def meet_me_list
+          execute 'MeetMeList'
+        end
+
+        def confbridges
+          execute 'ConfbridgeListRooms'
+        end
+
+        def confbridge(conference)
+          execute 'ConfbridgeList', { 'Conference' => conference }
+        end
+
+        def confbridge_mute(conference:, channel:)
+          execute 'ConfbridgeMute', { 'Conference' => conference, 'Channel' => channel }
+        end
+
+        def confbridge_unmute(conference:, channel:)
+          execute 'ConfbridgeUnmute', { 'Conference' => conference, 'Channel' => channel }
+        end
+
+        def confbridge_kick(conference:, channel:)
+          execute 'ConfbridgeKick', { 'Conference' => conference, 'Channel' => channel }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module AMI
+    module Commands
+      ##
+      #
+      # Extension commands
+      #
+      module Extension
+        def extension_state(exten:, context:, action_id: nil)
+          execute 'ExtensionState', { 'Exten' => exten, 'Context' => context, 'ActionID' => action_id }
+        end
+      end
+    end
+  end
+end