ruby-asterisk 0.1.0 → 1.0.0

data/lib/ruby-asterisk/ari/websocket.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'websocket/driver'
+require 'socket'
+require 'openssl'
+require 'json'
+require 'uri'
+require 'logger'
+require 'monitor'
+require_relative 'websocket/socket_adapter'
+require_relative 'websocket/connection'
+require_relative 'websocket/reconnect'
+require_relative 'websocket/heartbeat'
+require_relative 'websocket/event_handlers'
+
+module RubyAsterisk
+  module ARI
+    # WebSocket client for ARI events
+    # Connects to the Asterisk ARI WebSocket endpoint to receive real-time events
+    #
+    # I/O model (no EventMachine): the WebSocket protocol is handled by the pure
+    # Ruby websocket-driver gem over a plain TCPSocket (SSLSocket for wss).
+    #
+    #   connection_thread — owns the socket lifecycle: connects, runs the read
+    #                       loop (readpartial -> driver.parse -> callbacks), and
+    #                       re-connects after a drop while auto-reconnect is on.
+    #
+    #   ping_thread       — started when the connection opens; wakes every
+    #                       ping_interval seconds and sends a WebSocket ping.
+    #
+    # Event callbacks execute in the connection thread. All driver calls are
+    # serialized through a reentrant Monitor so send_message? is safe from any
+    # thread.
+    class WebSocket
+      include Connection
+      include Reconnect
+      include Heartbeat
+      include EventHandlers
+
+      attr_reader :url, :app_name, :callbacks, :connected
+
+      # Ping interval in seconds to keep connection alive
+      PING_INTERVAL = 30
+
+      # Reconnect delay in seconds (base for exponential backoff)
+      RECONNECT_DELAY = 5
+
+      # Upper bound for the exponential reconnect backoff, in seconds
+      MAX_RECONNECT_DELAY = 60
+
+      # Maximum reconnection attempts (nil for infinite)
+      MAX_RECONNECT_ATTEMPTS = nil
+
+      # Initialize a new WebSocket client
+      #
+      # @param base_url [String] Base URL of the Asterisk server (e.g., 'http://localhost:8088')
+      # @param api_key [String] API key for authentication
+      # @param app_name [String] Stasis application name
+      # @param options [Hash] Additional options
+      # @option options [Logger] :logger Logger instance for debugging
+      # @option options [Integer] :ping_interval Ping interval in seconds (default: 30)
+      # @option options [Boolean] :auto_reconnect Enable auto-reconnect (default: true)
+      # @option options [Integer] :reconnect_delay Delay between reconnection attempts (default: 5)
+      def initialize(base_url, api_key, app_name, options = {})
+        @base_url = base_url
+        @api_key = api_key
+        @app_name = app_name
+        @callbacks = {}
+        @connected = false
+        @should_reconnect = options.fetch(:auto_reconnect, true)
+        @reconnect_attempts = 0
+        @logger = options[:logger] || Logger.new($stdout)
+        @ping_interval = options.fetch(:ping_interval, PING_INTERVAL)
+        @reconnect_delay = options.fetch(:reconnect_delay, RECONNECT_DELAY)
+        initialize_io_state
+      end
+
+      # Connect to the WebSocket endpoint
+      #
+      # @yield [self] Block called when connection is established
+      # @return [self]
+      def connect(&block)
+        @on_connect_callback = block
+        @connection_thread = Thread.new { connection_loop }
+        self
+      end
+
+      # Register a callback for a specific event type
+      #
+      # @param event_type [String, Symbol] Event type to listen for (e.g., 'StasisStart')
+      # @param block [Proc] Block to execute when event is received
+      # @return [self]
+      def on(event_type, &block)
+        @callbacks[event_type.to_s] = [] unless @callbacks.key?(event_type.to_s)
+        @callbacks[event_type.to_s] << block
+        self
+      end
+
+      # Disconnect from the WebSocket
+      #
+      # @return [self]
+      def disconnect
+        @should_reconnect = false
+        stop_ping_timer
+        close_connection
+        wake_sleepers
+
+        thread = @connection_thread
+        @connection_thread = nil
+        thread&.join(2) unless thread == Thread.current
+
+        @connected = false
+        @logger.info 'WebSocket disconnected'
+        self
+      end
+
+      # Check if WebSocket is connected
+      #
+      # @return [Boolean]
+      def connected?
+        !!(@connected && @driver && @driver.state == :open)
+      end
+
+      # Send a message through the WebSocket
+      #
+      # @param message [Hash, String] Message to send (will be converted to JSON if Hash)
+      # @return [Boolean] true if sent successfully
+      def send_message?(message)
+        driver = @driver
+        return false unless @connected && driver && driver.state == :open
+
+        data = message.is_a?(Hash) ? JSON.generate(message) : message
+        @driver_monitor.synchronize { driver.text(data) }
+        true
+      rescue IOError, SystemCallError
+        false
+      end
+
+      private
+
+      def initialize_io_state
+        @driver = nil
+        @socket = nil
+        @connection_thread = nil
+        @ping_thread = nil
+        @ping_token = nil
+        @awaiting_pong = false
+        @pending_dispatch = nil
+        @driver_monitor = Monitor.new
+        @wake_mutex = Mutex.new
+        @wake_cv = ConditionVariable.new
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/compat.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# IO#timeout / IO#timeout= were added in Ruby 3.2.
+# The async gem's Fiber Scheduler calls io.timeout inside io_wait to honour
+# per-IO timeouts; returning nil disables that path on Ruby 3.1.
+IO.define_method(:timeout) { nil } unless IO.method_defined?(:timeout)
+IO.define_method(:timeout=) { |_| nil } unless IO.method_defined?(:timeout=)

data/lib/ruby-asterisk/error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  class Error < StandardError; end
+
+  # Raised when Asterisk sends an out-of-band `HANGUP` line mid-command
+  # (the channel was hung up). Callers may rescue this to abort cleanly
+  # instead of receiving a bogus response and desynchronizing the stream.
+  class HangupError < Error; end
+end

data/lib/ruby-asterisk/parsing_constants.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+##
+#
+# File containing parsing constants
+#
+module RubyAsterisk
+  DESCRIPTIVE_STATUS = {
+    '-1' => 'Extension not found',
+    '0' => 'Idle',
+    '1' => 'In Use',
+    '2' => 'Busy',
+    '3' => 'Unavailable',
+    '4' => 'Ringing',
+    '5' => 'On Hold'
+  }.freeze
+
+  PARSE_DATA = {
+    'CoreShowChannels' => {
+      symbol: :channels,
+      search_for: 'Event: CoreShowChannel',
+      stop_with: 'Event: CoreShowChannelsComplete'
+    },
+    'ParkedCalls' => {
+      symbol: :calls,
+      search_for: 'Event: ParkedCall',
+      stop_with: nil
+    },
+    'Originate' => {
+      symbol: :dial,
+      search_for: 'Event: Dial',
+      stop_with: nil
+    },
+    'MeetMeList' => {
+      symbol: :rooms,
+      search_for: 'Event: MeetmeList',
+      stop_with: nil
+    },
+    'ConfbridgeListRooms' => {
+      symbol: :rooms,
+      search_for: 'Event: ConfbridgeListRooms',
+      stop_with: nil
+    },
+    'ConfbridgeList' => {
+      symbol: :channels,
+      search_for: 'Event: ConfbridgeList',
+      stop_with: nil
+    },
+    'Status' => {
+      symbol: :status,
+      search_for: 'Event: Status',
+      stop_with: nil
+    },
+    'ExtensionState' => {
+      symbol: :hints,
+      search_for: 'Response: Success',
+      stop_with: nil
+    },
+    'DeviceStateList' => {
+      symbol: :hints,
+      search_for: 'Response: Success',
+      stop_with: nil
+    },
+    'SKINNYdevices' => {
+      symbol: :skinnydevs,
+      search_for: 'Event: DeviceEntry',
+      stop_with: nil
+    },
+    'SKINNYlines' => {
+      symbol: :skinnylines,
+      search_for: 'Event: LineEntry',
+      stop_with: nil
+    },
+    'QueuePause' => {
+      symbol: :queue_pause,
+      search_for: 'Response:',
+      stop_with: nil
+    },
+    'Pong' => {
+      symbol: :pong,
+      search_for: 'Response:',
+      stop_with: nil
+    },
+    'Events' => {
+      symbol: :event_mask,
+      search_for: 'Ping:',
+      stop_with: nil
+    },
+    'SIPpeers' => {
+      symbol: :peers,
+      search_for: 'Event: PeerEntry',
+      stop_with: nil
+    },
+    'SIPshowpeer' => {
+      symbol: :hints,
+      search_for: 'Response: Success',
+      stop_with: nil
+    }
+  }.each_value(&:freeze).freeze
+end

data/lib/ruby-asterisk/request.rb

@@ -1,32 +1,50 @@
+# frozen_string_literal: true
+
 module RubyAsterisk
+  ##
+  #
+  # Class responsible of building commands structure
+  #
   class Request
-    attr_accessor :action, :action_id, :parameters, :response_data
+    attr_reader :action, :action_id, :parameters
+
+    @id_mutex   = Mutex.new
+    @id_counter = 0
 
-    def initialize(action,parameters={})
-      self.action = action
-      self.action_id = self.generate_action_id
-      self.parameters = parameters
-      self.response_data = ""
+    # @param action     [String] AMI action name
+    # @param parameters [Hash]   additional AMI headers
+    # @param action_id  [String, nil] ActionID to use; a generated one when nil.
+    #   Passing it here (rather than as a parameter) keeps a single ActionID
+    #   header on the wire, so responses still correlate with their Promise.
+    def initialize(action, parameters = {}, action_id: nil)
+      @action = action.freeze
+      @action_id = (action_id || Request.generate_action_id).to_s.freeze
+      @parameters = deep_freeze_hash(parameters)
+      freeze
     end
 
     def commands
-      _commands=["Action: "+self.action+"\r\n","ActionID: "+self.action_id+"\r\n"]
-      self.parameters.each do |key,value|
-        _commands<<key+": "+value+"\r\n" unless value.nil?
+      command_list = ["Action: #{action}\r\n", "ActionID: #{action_id}\r\n"]
+      parameters.each do |key, value|
+        command_list << "#{key}: #{value}\r\n" unless value.nil?
       end
-      _commands[_commands.length-1]<<"\r\n"
-      _commands
-    end 
-
-    protected
+      command_list[-1] << "\r\n"
+      command_list
+    end
 
-    def generate_action_id
-      if RUBY_VERSION.start_with?("1.9")
-        Random.rand(999).to_s
-      else
-        rand(999).to_s
-      end
+    # Monotonic timestamp plus a process-wide atomic counter, so two calls made
+    # within the same nanosecond (or across an NTP clock step-back) never collide.
+    def self.generate_action_id
+      count = @id_mutex.synchronize { @id_counter += 1 }
+      "#{Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond).to_s(36)}-#{count.to_s(36)}"
     end
 
+    private
+
+    def deep_freeze_hash(hash)
+      hash.each_with_object({}) do |(key, value), result|
+        result[key.freeze] = value.freeze
+      end.freeze
+    end
   end
 end

data/lib/ruby-asterisk/response.rb

@@ -1,162 +1,75 @@
+# frozen_string_literal: true
+
+require 'ruby-asterisk/response_parser'
+
 module RubyAsterisk
+  ##
+  #
+  # Class for response coming from Asterisk
+  #
   class Response
-    attr_accessor :type, :success, :action_id, :message, :data, :raw_response
+    attr_reader :type, :action_id, :message, :data, :raw_response
 
-    def initialize(type,response)
-      self.raw_response = response
-      self.type = type
-      self.success = self._parse_successfull(response)
-      self.action_id = self._parse_action_id(response)
-      self.message = self._parse_message(response)
-      self.data = self._parse_data(response)
+    def initialize(type, response)
+      @raw_response = [response].flatten
+      @type = type
+      @action_id = _parse_action_id
+      @message = _parse_message
+      @data = _parse_response
+      deep_freeze
+      freeze
     end
 
-    protected
-
-    def _parse_successfull(response)
-      response.include?("Response: Success")
+    def success
+      raw_response.join.include?('Response: Success')
     end
 
-    def _parse_action_id(response)
-      self._parse(response,"ActionID:")
-    end
+    protected
 
-    def _parse_message(response)
-      self._parse(response,"Message:")
+    def _parse_action_id
+      _parse('ActionID:')
     end
 
-    def _parse(response,field)
-      _value = nil
-      response.each_line do |line|
-        if line.start_with?(field)
-          _value = line[line.rindex(":")+1..line.size].strip
-        end
-      end
-      _value
+    def _parse_message
+      _parse('Message:')
     end
 
-    def _parse_data(response)
-      case self.type
-        when "CoreShowChannels"
-          self._parse_data_core_show_channels(response)
-        when "ParkedCalls"
-          self._parse_data_parked_calls(response)
-        when "Originate"
-          self._parse_originate(response)
-        when "MeetMeList"
-          self._parse_meet_me_list(response)
-        when "Status"
-          self._parse_status(response)
-        when "ExtensionState"
-          self._parse_extension_state(response)
-        when "SKINNYdevices"
-          self._parse_skinny_devices(response)
-        when "SKINNYlines"
-          self._parse_skinny_lines(response)
-        when "Command"
-          response
-        when "QueuePause"
-          self._parse_queue_pause(response)
-        when "Pong"
-          self._parse_pong(response)
-        when "Events"
-          self._parse_event_mask(response)
-        when "SIPpeers"
-          self._parse_sip_peers(response)
+    def _parse(field)
+      raw_response.each do |data|
+        data.each_line do |line|
+          # Split only on the field's own colon so values that themselves contain
+          # ':' (e.g. "Message: Call failed: no route") are not truncated.
+          return line[field.length..].strip if line.start_with?(field)
+        end
       end
-
-    end
-
-    def _parse_sip_peers(response)
-      self._parse_objects(response, :peers, "Event: PeerEntry")
+      nil
     end
 
-    def _parse_meet_me_list(response)
-      self._parse_objects(response,:rooms,"Event: MeetmeList")
+    def _parse_response
+      ResponseParser.parse(raw_response, type)
     end
 
-    def _parse_originate(response)
-      self._parse_objects(response,:dial,"Event: Dial")
-    end
-
-    def _parse_data_parked_calls(response)
-      self._parse_objects(response,:calls,"Event: ParkedCall")
-    end
+    private
 
-    def _parse_data_core_show_channels(response)
-      self._parse_objects(response,:channels,"Event: CoreShowChannel","Event: CoreShowChannelsComplete")
-    end
-
-    def _parse_extension_state(response)
-      _data = self._parse_objects(response,:hints,"Response:")
-      self._convert_status(_data)
-    end
-    
-    def _parse_skinny_devices(response)
-      self._parse_objects(response,:skinnydevs,"Event: DeviceEntry")
-    end
-
-    def _parse_skinny_lines(response)
-      self._parse_objects(response,:skinnylines,"Event: LineEntry")
-    end
-    
-    def _parse_queue_pause(response)
-      _data = self._parse_objects(response,:queue_pause,"Response:")
-    end
-    
-    def _parse_pong(response)
-      _data = self._parse_objects(response,:pong, "Response:")
-    end
-    
-    def _parse_event_mask(response)
-      _data = self._parse_objects(response, :event_mask, "Ping:")
-    end
-
-    def _parse_status(response)
-      self._parse_objects(response, :status, "Event: Status")
-    end
-
-    def _convert_status(_data)
-      _data[:hints].each do |hint|
-        case hint["Status"]
-          when "-1"
-            hint["DescriptiveStatus"] = "Extension not found"
-          when "0"
-            hint["DescriptiveStatus"] = "Idle"
-          when "1"
-            hint["DescriptiveStatus"] = "In Use"
-          when "2"
-            hint["DescriptiveStatus"] = "Busy"
-          when "4"
-            hint["DescriptiveStatus"] = "Unavailable"
-          when "8"
-            hint["DescriptiveStatus"] = "Ringing"
-          when "16"
-            hint["DescriptiveStatus"] = "On Hold"
-        end
-      end
-      _data
+    def deep_freeze
+      @type.freeze
+      @action_id.freeze
+      @message.freeze
+      deep_freeze_value(@raw_response)
+      deep_freeze_value(@data)
     end
 
-    def _parse_objects(response,symbol_name,search_for,stop_with=nil)
-       _data = { symbol_name => [] }
-      parsing = false
-      object = nil
-      response.each_line do |line|
-        line.strip!
-        if line.strip.empty? or (!stop_with.nil? and line.start_with?(stop_with))
-          parsing = false
-        elsif line.start_with?(search_for)
-          _data[symbol_name] << object unless object.nil?
-          object = {}
-          parsing = true
-        elsif parsing
-          tokens = line.split(':', 2)
-          object[tokens[0].strip]=tokens[1].strip unless tokens[1].nil?
+    def deep_freeze_value(obj)
+      case obj
+      when Hash
+        obj.each do |key, value|
+          key.freeze
+          deep_freeze_value(value)
         end
+      when Array
+        obj.each { |element| deep_freeze_value(element) }
       end
-      _data[symbol_name] << object unless object.nil?
-      _data
+      obj.freeze
     end
   end
 end

data/lib/ruby-asterisk/response_builder.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  ##
+  #
+  # Mutable builder that produces an immutable Response
+  #
+  class ResponseBuilder
+    attr_accessor :type, :raw_response
+
+    def build
+      raise ArgumentError, 'type is required' if @type.nil?
+      raise ArgumentError, 'raw_response is required' if @raw_response.nil?
+
+      Response.new(@type, @raw_response)
+    end
+  end
+end

data/lib/ruby-asterisk/response_parser.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'ruby-asterisk/parsing_constants'
+
+module RubyAsterisk
+  ##
+  #
+  # Class for parsing response coming from Asterisk
+  #
+  class ResponseParser
+    def self.parse(raw_response, type)
+      if PARSE_DATA.include?(type)
+        _parse_objects(raw_response, PARSE_DATA[type])
+      else
+        raw_response
+      end
+    end
+
+    def self._add_status(exten_array)
+      exten_array.each do |hint|
+        hint['DescriptiveStatus'] = DESCRIPTIVE_STATUS[hint['Status']]
+      end
+      exten_array
+    end
+
+    def self._parse_objects(response, parse_params)
+      object_array = []
+      # AMI frames are CRLF-delimited on the wire; tolerate both \r\n and \n so
+      # aggregated multi-event responses parse regardless of line endings.
+      object_regex = /#{parse_params[:search_for]}\r?\n(.*?)\r?\n\r?\n/m
+      response.join.scan(object_regex) do |match|
+        object = {}
+        match[0].split(/\r?\n/).each do |line|
+          tokens = line.split(':', 2)
+          object[tokens[0].strip] = tokens[1].strip unless tokens[1].nil?
+        end
+        object_array << object unless object.empty?
+      end
+      object_array = _add_status(object_array) if parse_params[:symbol].eql?(:hints)
+      { parse_params[:symbol] => object_array }
+    end
+  end
+end

data/lib/ruby-asterisk/version.rb

@@ -1,3 +1,5 @@
-module Rami
-  VERSION = "0.1.0"
+# frozen_string_literal: true
+
+module RubyAsterisk
+  VERSION = '1.0.0'
 end