ruby-asterisk 0.2.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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 ##
 #
 # File containing parsing constants
@@ -11,88 +13,88 @@ module RubyAsterisk
     '3' => 'Unavailable',
     '4' => 'Ringing',
     '5' => 'On Hold'
-  }
+  }.freeze
 
   PARSE_DATA = {
     'CoreShowChannels' => {
-      :symbol => :channels,
-      :search_for => 'Event: CoreShowChannel',
-      :stop_with => 'Event: CoreShowChannelsComplete'
+      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
+      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
+      symbol: :skinnylines,
+      search_for: 'Event: LineEntry',
+      stop_with: nil
     },
     'QueuePause' => {
-      :symbol => :queue_pause,
-      :search_for => 'Response:',
-      :stop_with => nil
+      symbol: :queue_pause,
+      search_for: 'Response:',
+      stop_with: nil
     },
     'Pong' => {
-      :symbol => :pong,
-      :search_for => 'Response:',
-      :stop_with => nil
+      symbol: :pong,
+      search_for: 'Response:',
+      stop_with: nil
     },
     'Events' => {
-      :symbol => :event_mask,
-      :search_for => 'Ping:',
-      :stop_with => nil
+      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
-    },
-  }
+      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,31 +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 = Request.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.to_s}: #{value.to_s}\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
+      command_list[-1] << "\r\n"
+      command_list
     end
 
-    protected
-
+    # 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
-      Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond).to_s(36)
+      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,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'ruby-asterisk/response_parser'
 
 module RubyAsterisk
@@ -6,43 +8,68 @@ module RubyAsterisk
   # Class for response coming from Asterisk
   #
   class Response
-    attr_accessor :type, :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.action_id = self._parse_action_id
-      self.message = self._parse_message
-      self.data = self._parse_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
 
     def success
-      self.raw_response.include?("Response: Success")
+      raw_response.join.include?('Response: Success')
     end
 
     protected
 
     def _parse_action_id
-      self._parse("ActionID:")
+      _parse('ActionID:')
     end
 
     def _parse_message
-      self._parse("Message:")
+      _parse('Message:')
     end
 
     def _parse(field)
-      _value = nil
-      self.raw_response.each_line do |line|
-        if line.start_with?(field)
-          _value = line[line.rindex(":")+1..line.size].strip
+      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
-      _value
+      nil
     end
 
     def _parse_response
-      ResponseParser.parse(self.raw_response, self.type)
+      ResponseParser.parse(raw_response, type)
+    end
+
+    private
+
+    def deep_freeze
+      @type.freeze
+      @action_id.freeze
+      @message.freeze
+      deep_freeze_value(@raw_response)
+      deep_freeze_value(@data)
     end
 
+    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
+      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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'ruby-asterisk/parsing_constants'
 
 module RubyAsterisk
@@ -6,32 +8,31 @@ module RubyAsterisk
   # Class for parsing response coming from Asterisk
   #
   class ResponseParser
-
     def self.parse(raw_response, type)
       if PARSE_DATA.include?(type)
-        self._parse_objects(raw_response, PARSE_DATA[type])
+        _parse_objects(raw_response, PARSE_DATA[type])
       else
         raw_response
       end
     end
 
-    protected
-
     def self._add_status(exten_array)
       exten_array.each do |hint|
-        hint["DescriptiveStatus"] = DESCRIPTIVE_STATUS[hint["Status"]]
+        hint['DescriptiveStatus'] = DESCRIPTIVE_STATUS[hint['Status']]
       end
       exten_array
     end
 
     def self._parse_objects(response, parse_params)
       object_array = []
-      object_regex = Regexp.new(/#{parse_params[:search_for]}\n(.*?)\n\n/m)
-      response.scan(object_regex) do |match|
+      # 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(/\n/).each do |line|
+        match[0].split(/\r?\n/).each do |line|
           tokens = line.split(':', 2)
-          object[tokens[0].strip]=tokens[1].strip unless tokens[1].nil?
+          object[tokens[0].strip] = tokens[1].strip unless tokens[1].nil?
         end
         object_array << object unless object.empty?
       end

data/lib/ruby-asterisk/version.rb

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