freeswitch-esl 0.1.0 → 0.2.0

data/lib/freeswitch/esl/configuration.rb

@@ -1,30 +1,56 @@
 # frozen_string_literal: true
 
 require "configatron"
+require "forwardable"
 
 module Freeswitch
   module ESL
     class Configuration
-      DEFAULTS = {
-        freeswitch: {
-          host: ENV.fetch("FREESWITCH_ESL_HOST", "127.0.0.1"),
-          port: ENV.fetch("FREESWITCH_ESL_PORT", 8021).to_i,
-          password: ENV.fetch("FREESWITCH_ESL_PASSWORD", "ClueCon"),
-          timeout: ENV.fetch("FREESWITCH_ESL_TIMEOUT", 5).to_i,
-          retry_delay: ENV.fetch("FREESWITCH_ESL_RETRY_DELAY", 1.0).to_f,
-          max_retries: Float::INFINITY
-        },
-        logger: Freeswitch::ESL::Logger.default_logger
-      }.freeze
+      extend Forwardable
 
       class << self
+        def defaults
+          @defaults ||= {
+            freeswitch: {
+              host: ENV.fetch("FREESWITCH_ESL_HOST", "127.0.0.1"),
+              port: ENV.fetch("FREESWITCH_ESL_PORT", 8021).to_i,
+              password: ENV.fetch("FREESWITCH_ESL_PASSWORD", nil),
+              reconnect: %w[true 1 yes].include?(ENV.fetch("FREESWITCH_ESL_RECONNECT", "true").downcase),
+              retry_delay: ENV.fetch("FREESWITCH_ESL_RETRY_DELAY", 1.0).to_f,
+              max_retries: Float::INFINITY
+            },
+            logger: Freeswitch::ESL::Logger.default_logger,
+            debug: false
+          }.freeze
+        end
+
         def build(**options)
           config = Configatron::RootStore.new
-          config.freeswitch.configure_from_hash(DEFAULTS[:freeswitch].dup.merge(options[:freeswitch] || {}))
-          config.logger = options[:logger] || DEFAULTS[:logger]
+          config.freeswitch.configure_from_hash(defaults[:freeswitch].dup.merge(options[:freeswitch] || {}))
+          config.logger = options[:logger] || defaults[:logger]
+          config.debug = options[:debug] || defaults[:debug]
           config
         end
       end
+
+      def_delegators :@config, :freeswitch, :logger, :debug, :to_h
+      def_delegators :@config, :logger=, :debug=
+
+      def initialize(**)
+        @config = self.class.build(**)
+      end
+
+      def update(**options)
+        %i[freeswitch logger debug].each do |key|
+          next unless options.key?(key)
+
+          if key == :freeswitch
+            @config.freeswitch.configure_from_hash(options[:freeswitch])
+          else
+            @config[key] = options[key] || @config[key]
+          end
+        end
+      end
     end
   end
 end

data/lib/freeswitch/esl/connection/command_dispatcher.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Freeswitch
+  module ESL
+    class Connection
+      # Coordinates command execution: manages socket write, command queueing,
+      # and response routing.
+      #
+      # Threading model:
+      #   * A *reader thread* reads messages from the socket and delivers them
+      #     to waiting {CommandRequest} objects via FIFO queue ordering.
+      #   * Command writes and enqueues are atomic under a single mutex so that
+      #     command order on wire matches queue order.
+      #   * Responses are matched to commands by simple FIFO order.
+      #   * Events (text/event-json) are forwarded to {EventDispatcher}.
+      #   * Server-initiated messages (auth/request) invoke callbacks.
+      #
+      class CommandDispatcher
+        include Freeswitch::ESL::Logger
+
+        MSG_TERMINATOR = "\n\n"
+
+        def initialize(socket, event_dispatcher, debug: false)
+          @socket = socket
+          @event_dispatcher = event_dispatcher
+          @write_mutex = Mutex.new
+          @cond = ConditionVariable.new
+          @queue = Queue.new
+          @on_disconnect = nil
+          @reader_thread = nil
+          @closed = false
+          @auth_request_received = false
+          @debug = debug
+          @disconnect_error = nil
+          @read_buffer = String.new
+        end
+
+        # Check if the dispatcher is closed.
+        def closed?
+          @closed
+        end
+
+        # Register a callback invoked after the dispatcher transitions to the
+        # disconnected state and pending commands have been notified.
+        def on_disconnect(&block)
+          @on_disconnect = block
+          self
+        end
+
+        # Start the socket reader thread and the periodic socket health check.
+        # Safe to call more than once: subsequent calls are ignored while the
+        # current reader thread reference is still present.
+        def start
+          return if @reader_thread
+
+          @reader_thread = Thread.new do
+            loop do
+              break if closed?
+
+              msg = read_message
+              unless msg
+                disconnect!(DisconnectedError.new("Connection closed by remote host"))
+                break
+              end
+
+              route_message(msg)
+            rescue IOError, Errno::ECONNRESET, Errno::ENOTCONN => e
+              disconnect!(DisconnectedError.new(e.message))
+              break
+            end
+          end
+          @reader_thread.name = "esl-reader"
+          @reader_thread.abort_on_exception = false
+          @healthcheck_timer = Ztimer.every(1000) { check_socket_health }
+        end
+
+        # Wait for the server-initiated +auth/request+ message from FreeSWITCH.
+        # Raises {TimeoutError} if the message does not arrive within +timeout+
+        # seconds, or re-raises the disconnect error if the socket closes first.
+        def wait_for_auth_request(timeout: nil)
+          @write_mutex.synchronize do
+            return if @auth_request_received
+
+            @cond.wait(@write_mutex, timeout)
+          end
+
+          raise @disconnect_error if @closed && @disconnect_error
+          raise TimeoutError, "Timed out waiting for auth/request" unless @auth_request_received
+        end
+
+        # Stop the dispatcher, cancel the healthcheck timer and broadcast to
+        # any waiters blocked on +wait_for_auth_request+.
+        #
+        # Socket close failures during teardown are ignored because shutdown is
+        # already in progress and there is no recovery path.
+        def stop
+          return if closed?
+
+          logger.debug "Stopping command dispatcher and closing socket"
+          @closed = true
+          @healthcheck_timer&.cancel!
+
+          begin
+            @socket.close
+          rescue StandardError
+            nil
+          end
+          @reader_thread&.join(0.1) if @reader_thread != Thread.current
+          @queue.close
+          @cond.broadcast # unblock wait_for_auth_request if still waiting
+          logger.debug "Command dispatcher stopped"
+        end
+
+        # Send a raw command on ESL socket and return CommandRequest.
+        #
+        # @param command [String] the ESL command to send
+        # @param timeout [Numeric, nil] seconds to wait for response
+        # @return [CommandRequest] the command request object
+        # @raise [TimeoutError] when the response does not arrive in time
+        # @raise [DisconnectedError] when the connection is closed
+        def execute_command(command, timeout: nil)
+          raise DisconnectedError, "Connection is closed" if @closed
+
+          cmd = CommandRequest.new(command, timeout)
+          @write_mutex.synchronize { execute(cmd) }
+
+          cmd
+        end
+
+        # Return the number of commands currently waiting for a response.
+        def pending_commands_count
+          @queue.size
+        end
+
+        private
+
+        # Transition the dispatcher to the disconnected state, fail every
+        # pending command with the same error and then invoke the disconnect
+        # callback once teardown has completed.
+        def disconnect!(error)
+          @disconnect_error = error
+          logger.debug "Disconnected: #{error.message}"
+
+          # Deliver DisconnectedError to all pending in-flight command executions
+          loop do
+            cmd = pop_command(non_block: true)
+            break unless cmd
+
+            cmd.disconnected!(error)
+          end
+
+          stop
+          @on_disconnect&.call(error)
+        end
+
+        # Enqueue and write the command while the caller holds +@write_mutex+ so
+        # queue order always matches socket write order.
+        def execute(cmd)
+          @queue << cmd
+          @socket.write("#{cmd.command}#{MSG_TERMINATOR}")
+          logger.debug "[SENT] #{cmd.command}" if @debug
+          cmd.sent!
+        rescue IOError, Errno::ECONNRESET, Errno::ENOTCONN => e
+          disconnect!(DisconnectedError.new(e.message))
+        rescue StandardError => e
+          cmd.process_error(e)
+        end
+
+        # Read one ESL message from the socket.
+        # Returns +nil+ when the stream reaches EOF or header parsing cannot
+        # produce a message.
+        def read_message
+          headers = read_message_headers
+          return nil if headers.nil? || headers.empty?
+
+          body = @socket.read(headers["Content-Length"].to_i) if headers.key?("Content-Length")
+          logger.debug "[RECEIVED] #{body}" if body && @debug
+          Protocol::Message.new(headers, body)
+        rescue JSON::ParserError => e
+          logger.error "Failed to parse JSON body: #{e.message}"
+          nil
+        end
+
+        # Read ESL headers until the blank-line terminator.
+        # Returns +nil+ on EOF or after the dispatcher has already been closed.
+        def read_message_headers
+          headers = {}
+
+          loop do
+            line = @socket.gets("\n")
+            return nil if closed? || line.nil?
+
+            line = line.chomp
+            break if line.empty?
+
+            key, value = line.split(": ", 2)
+            headers[key] = value
+            logger.debug "[RECEIVED] #{line}" if @debug
+          end
+
+          headers
+        end
+
+        # Process a reply message from the server.
+        def process_reply(message)
+          # Use non-blocking pop of the next command waiting for a response
+          cmd = pop_command(non_block: true)
+          if cmd
+            cmd.process_reply(message)
+          else
+            logger.warn "Received unexpected command reply: #{message.headers.inspect}"
+          end
+        end
+
+        # Route a protocol message to the auth bootstrap path, the pending
+        # command queue, the event dispatcher or the disconnect flow.
+        def route_message(message)
+          case message.content_type
+          when "auth/request"
+            # Server-initiated auth request
+            @write_mutex.synchronize do
+              @auth_request_received = true
+              @cond.broadcast
+            end
+          when "command/reply", "api/response"
+            # Response to a command we sent
+            process_reply(message)
+
+          when "text/event-json"
+            # Forward event to dispatcher
+            @event_dispatcher.enqueue_event(Protocol::Event.new(message.body))
+
+          when "text/disconnect-notice"
+            disconnect!(DisconnectedError.new("FreeSWITCH sent disconnect notice"))
+          end
+        end
+
+        def pop_command(non_block: true)
+          @queue.pop(non_block)
+        rescue StandardError
+          nil
+        end
+
+        # Periodically attempt a zero-byte write to detect half-open sockets in
+        # the background, without waiting for the next explicit command write.
+        def check_socket_health
+          @write_mutex.synchronize do
+            @socket.write_nonblock("", exception: false)
+          end
+        rescue Errno::EPIPE, Errno::ECONNRESET, Errno::ENOTCONN => e
+          disconnect!(DisconnectedError.new("Socket health check failed: #{e.message}"))
+        end
+      end
+    end
+  end
+end

data/lib/freeswitch/esl/connection/command_request.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Freeswitch
+  module ESL
+    class Connection
+      # Represents a pending command execution waiting for a response.
+      #
+      # Created before sending a command to the socket; the response is
+      # delivered asynchronously by the command dispatcher via {#process_reply},
+      # {#process_error} or {#disconnected!}.
+      #
+      # Handles timeout: if the caller exceeds the deadline, {#wait} raises
+      # {TimeoutError} and marks the execution as expired. A late-arriving
+      # response is silently discarded (callback not invoked), keeping the
+      # command queue in sync with the wire protocol.
+      class CommandRequest
+        attr_reader :command, :status, :created_at, :sent_at, :finished_at
+
+        def initialize(command, timeout = nil)
+          @command = command
+          @mutex = Mutex.new
+          @condition = ConditionVariable.new
+          @response = nil
+          @status = :queued
+          @created_at = Time.now
+          @sent_at = nil
+          @finished_at = nil
+          @timeout = timeout
+        end
+
+        def ok?
+          @status == :completed
+        end
+
+        def sent!
+          @mutex.synchronize do
+            return if terminated?
+
+            @status = :sent
+            @sent_at = Time.now
+          end
+        end
+
+        # Called by reader thread to deliver the response message or exception.
+        # No-op if the execution has already expired due to timeout.
+        def process_reply(reply)
+          return if terminated?
+
+          @mutex.synchronize do
+            @response = reply
+            @status = reply.successful? ? :completed : :failed
+            @error = reply.successful? ? nil : CommandError.new(failed_reply_error_message(reply))
+            @condition.signal
+            @finished_at = Time.now
+          end
+        end
+
+        def process_error(error)
+          @mutex.synchronize do
+            return if terminated?
+
+            @error = error
+            @status = :failed
+            @finished_at = Time.now
+            @condition.signal
+          end
+        end
+
+        def disconnected!(error)
+          @mutex.synchronize do
+            return if terminated? # already completed/failed/timeout
+
+            @error = error
+            @status = :disconnected
+            @finished_at = Time.now
+            @condition.signal
+          end
+        end
+
+        # Return the terminal reply, blocking without raising so callers can
+        # inspect failures through {#error} instead of exceptions.
+        def response
+          wait(raise_error: false) unless terminated?
+
+          @response
+        end
+
+        # Return the terminal error, blocking without raising so callers can
+        # branch on the request outcome after completion.
+        def error
+          wait(raise_error: false) unless terminated?
+
+          @error
+        end
+
+        # Block the calling thread until a response arrives or the deadline passes.
+        #
+        # @return [Protocol::Message] the response message
+        # @raise [TimeoutError] when the deadline passes without a response
+        # @raise [DisconnectedError] when the socket is closed
+        # @raise [StandardError] any error previously delivered through
+        #   {#process_error} or a failed reply when +raise_error+ is true.
+        def wait(raise_error: true)
+          @mutex.synchronize do
+            raise_error_if_necessary(raise_error:)
+            return self if terminated?
+
+            @condition.wait(@mutex, @timeout)
+
+            # If still pending after the wait window, mark as timed-out and raise.
+            if %i[queued sent].include?(@status)
+              @status = :timeout
+              @error = TimeoutError.new("Command timed out after #{@timeout}s waiting for response")
+            end
+
+            raise_error_if_necessary(raise_error:)
+          end
+
+          self
+        end
+
+        private
+
+        def terminated?
+          %i[
+            completed
+            failed
+            timeout
+            unauthorized
+            disconnected
+          ].include?(@status)
+        end
+
+        def failed_reply_error_message(reply)
+          if reply.content_type == "text/disconnect-notice"
+            "Disconnected: #{reply.body || reply.reply_text || 'No details'}"
+          else
+            filtered_command = @command.gsub(/auth\s+\S+/, "auth <REDACTED>")
+
+            <<~ERROR_MESSAGE.chomp
+              Command `#{filtered_command}` failed: (#{reply.content_type}) #{reply.body || reply.reply_text || 'Unknown error'}
+            ERROR_MESSAGE
+          end
+        end
+
+        # Re-raise the terminal error when the request has already completed in
+        # a failing state and the caller asked for exception-based handling.
+        def raise_error_if_necessary(raise_error: true)
+          raise @error if @error && raise_error && terminated?
+        end
+      end
+    end
+  end
+end

data/lib/freeswitch/esl/connection/event_dispatcher.rb

@@ -32,13 +32,16 @@ module Freeswitch
 
         # Register a handler for a background job result (by job UUID).
         def register_bgapi_handler(job_uuid, block)
+          return if job_uuid.nil? || block.nil?
+
           @bgapi_mutex.synchronize { @bgapi_handlers[job_uuid] = block }
         end
 
         # Start the dispatcher thread.
         def start
-          return if @dispatcher_thread
+          return if @dispatcher_thread&.alive?
 
+          @event_queue = Queue.new if @event_queue.closed? # reopen if previously closed
           @dispatcher_thread = Thread.new do
             loop do
               event = @event_queue.pop
@@ -53,8 +56,13 @@ module Freeswitch
 
         # Stop the dispatcher thread (close queue and join).
         def stop
-          @event_queue&.close
+          @event_queue.close
           @dispatcher_thread&.join
+          @dispatcher_thread = nil
+        end
+
+        def pending_bgapi_command_uuids
+          @bgapi_mutex.synchronize { @bgapi_handlers.keys }
         end
 
         private