freeswitch-esl 0.1.0 → 0.2.0

data/lib/freeswitch/esl/connection.rb

@@ -4,7 +4,8 @@ require "timeout"
 
 require "freeswitch/esl/protocol/event"
 require "freeswitch/esl/protocol/message"
-require "freeswitch/esl/connection/message_reader"
+require "freeswitch/esl/connection/command_dispatcher"
+require "freeswitch/esl/connection/command_request"
 require "freeswitch/esl/connection/event_dispatcher"
 
 module Freeswitch
@@ -15,77 +16,71 @@ module Freeswitch
     # {#initialize_socket} to start the reader and event-dispatcher threads.
     #
     # Threading model:
-    #   * A *reader thread* reads messages from the socket and routes them:
-    #     - command/api replies  → @response_queue (consumed by the calling thread)
-    #     - events               → @event_queue    (consumed by the dispatcher thread)
+    #   * A reader thread owned by {CommandDispatcher} reads messages from the
+    #     socket and routes them to pending command executions (FIFO) or to the
+    #     event dispatcher.
     #   * A *dispatcher thread* processes @event_queue and calls registered handlers.
-    #   * Command execution is serialised by @send_mutex so that each send+receive
-    #     pair is atomic and responses are never mixed up.
-    #   * On timeout the connection is closed because the protocol state is unknown.
+    #   * Command enqueue + write is atomic under a mutex in CommandDispatcher,
+    #     guaranteeing queue order == socket write order.
     class Connection
-      MSG_TERMINATOR = "\n\n"
-      DEFAULT_TIMEOUT = 5
+      include Freeswitch::ESL::Logger
 
       def initialize(socket)
         initialize_socket(socket)
       end
 
-      # Send a raw ESL command and return the {Message} reply.
-      def send_command(command, timeout: DEFAULT_TIMEOUT)
+      # Send a raw ESL command and return a CommandRequest object that can be used to wait for the response.
+      def send_command(command, timeout: nil)
         raise DisconnectedError, "Connection is closed" if closed?
 
-        # Keep write+read together so one thread cannot read another thread's
-        # reply by mistake.
-        @send_mutex.synchronize do
-          @socket.write("#{command}#{MSG_TERMINATOR}")
-          receive_response(timeout: timeout)
-        end
-      end
-
-      # Execute a synchronous +api+ command.  Returns the {Message} with the
-      # result in {Message#body}.
-      def api(command, args = nil, timeout: DEFAULT_TIMEOUT)
-        parts = ["api", command, args].compact
-        @send_mutex.synchronize do
-          @socket.write("#{parts.join(' ')}#{MSG_TERMINATOR}")
-          receive_response(timeout: timeout)
-        end
+        @command_dispatcher.execute_command(command, timeout:)
       end
 
       # Execute a background +bgapi+ command.  Returns the Job-UUID string.
       # The optional block is called with the BACKGROUND_JOB {Event} when the
       # result arrives.
-      def bgapi(command, args = nil, timeout: DEFAULT_TIMEOUT, &block)
-        parts = ["bgapi", command, args].compact
-        job_uuid = @send_mutex.synchronize do
-          @socket.write("#{parts.join(' ')}#{MSG_TERMINATOR}")
-          reply = receive_response(timeout: timeout)
-          reply["Job-UUID"]
-        end
+      def bgapi(command, *args, timeout: nil, &block)
+        raise DisconnectedError, "Connection is closed" if closed?
+
+        parts = ["bgapi", command, *args].compact
+        logger.debug("[BGAPI] #{parts.join(' ')}")
+        cmd = @command_dispatcher.execute_command(parts.join(" "), timeout:).wait
+        job_uuid = cmd.response["Job-UUID"]
+        raise CommandError, "FreeSWITCH bgapi did not return a Job-UUID" unless job_uuid
 
-        @event_dispatcher.register_bgapi_handler(job_uuid, block) if block && job_uuid
+        @event_dispatcher.register_bgapi_handler(job_uuid, block) if block
         job_uuid
       end
 
+      # Return the number of commands currently waiting for a response.
+      def pending_commands_count
+        @command_dispatcher.pending_commands_count
+      end
+
+      # Return an array of Job-UUID strings for all pending bgapi commands.
+      def pending_bgapi_command_uuids
+        @event_dispatcher.pending_bgapi_command_uuids
+      end
+
       # Subscribe to one or more event names (JSON format). Pass no arguments
       # or +"ALL"+ to receive every event.
       def subscribe(*event_names)
         events = event_names.empty? ? "ALL" : event_names.join(" ")
-        send_command("event json #{events}")
+        send_command("event json #{events}").wait
       end
 
       # Cancel subscriptions.  Without arguments cancels all events.
       def unsubscribe(*event_names)
         if event_names.empty?
-          send_command("noevents")
+          send_command("noevents").wait
         else
-          event_names.each { |e| send_command("nixevent #{e}") }
+          event_names.each { |e| send_command("nixevent #{e}").wait }
         end
       end
 
       # Add an event-header filter so FreeSWITCH only sends matching events.
       def filter(header, value)
-        send_command("filter #{header} #{value}")
+        send_command("filter #{header} #{value}").wait
       end
 
       # Register a handler block for an event name.  Use +"ALL"+ to handle
@@ -100,27 +95,27 @@ module Freeswitch
         @closed
       end
 
+      # Stop dispatchers and mark the connection closed. Event handlers are
+      # removed together with the dispatcher instances, so a reconnect path must
+      # rebuild them through {#initialize_socket}.
       def close
         return if @closed
 
         @closed = true
-        begin
-          @socket.close
-        rescue StandardError
-          nil
-        end
-        @message_reader&.stop
+        @command_dispatcher&.stop
         @event_dispatcher&.stop
+
+        send(:remove_instance_variable, :@command_dispatcher)
+        send(:remove_instance_variable, :@event_dispatcher)
       end
 
       protected
 
       # (Re-)initialise all per-connection state for the given socket.
       # Called by subclasses on initial connect and on reconnect.
-      def initialize_socket(socket)
-        @socket     = socket
-        @send_mutex = Mutex.new
-        @closed     = false
+      def initialize_socket(socket, debug: false)
+        @socket = socket
+        @closed = false
 
         # Keep dispatcher data across reconnects so existing handlers still work
         # after a new socket is created.
@@ -129,38 +124,21 @@ module Freeswitch
           @event_dispatcher.start
         end
 
-        # Always create new MessageReader for each socket
-        @message_reader = MessageReader.new(@socket, @event_dispatcher) { |error| on_disconnect(error) }
-        @message_reader.start
-      end
-
-      # Authenticate against FreeSWITCH after the initial auth/request message.
-      def authenticate!(password, timeout: DEFAULT_TIMEOUT)
-        auth_request = receive_response(timeout: timeout)
-        unless auth_request.content_type == "auth/request"
-          raise AuthenticationError, "Expected auth/request, got: #{auth_request.content_type}"
-        end
-
-        # `auth` is a basic ESL command with a command/reply response, so we
-        # use send_command (not api/bgapi).
-        reply = send_command("auth #{password}", timeout: timeout)
-        return if reply.successful?
-
-        raise AuthenticationError, "Authentication failed: #{reply.reply_text}"
+        # Always create a new CommandDispatcher for each socket
+        @command_dispatcher = CommandDispatcher.new(@socket, @event_dispatcher, debug:)
+        @command_dispatcher.on_disconnect { |error| on_disconnect(error) }
+        @command_dispatcher.start
       end
 
-      def receive_response(timeout:)
-        @message_reader.receive_response(timeout: timeout)
-      rescue TimeoutError
-        # If a request times out, the next reply might belong to the old
-        # command, so we close and start from a clean connection.
-        close
-        raise
+      # Wait for the initial auth/request bootstrap message before sending any
+      # commands that assume FreeSWITCH is ready to accept authenticated input.
+      def wait_for_auth_request(timeout: nil)
+        @command_dispatcher.wait_for_auth_request(timeout:)
       end
 
       private
 
-      # Called by MessageReader when socket is disconnected or closed.
+      # Called by the command dispatcher when the current socket disconnects.
       def on_disconnect(_error)
         @closed = true
       end

data/lib/freeswitch/esl/logger.rb

@@ -13,7 +13,9 @@ module Freeswitch
       def logger
         return @logger if defined?(@logger) && @logger
 
-        @logger = Freeswitch::ESL.configuration.logger
+        @logger = Freeswitch::ESL.configuration.logger.dup
+        @logger.progname = self.class.name
+        @logger
       end
     end
   end

data/lib/freeswitch/esl/protocol/event.rb

@@ -7,36 +7,155 @@ module Freeswitch
     module Protocol
       # Represents a FreeSWITCH event received in JSON format.
       class Event
+        ERROR_BODY_PREFIX = /\A\s*-(ERR|USAGE)\b/
+
         attr_reader :data
 
         def initialize(raw_json)
           @data = JSON.parse(raw_json).freeze
         end
 
+        # Returns the raw value stored in the event payload for the given key.
+        # @return [Object, nil] Parsed JSON value for the requested field.
         def [](key)
           data[key]
         end
 
+        # Returns the canonical FreeSWITCH event name.
+        # @return [String, nil] Event name such as CHANNEL_CREATE, HEARTBEAT or BACKGROUND_JOB.
         def name
           data["Event-Name"]
         end
 
+        # Returns the UUID of the emitting FreeSWITCH core instance.
+        # @return [String, nil] Core identifier shared across events generated by the same node.
+        def core_uuid
+          data["Core-UUID"]
+        end
+
+        # Returns the hostname reported by the FreeSWITCH node.
+        # @return [String, nil] Hostname of the server that emitted the event.
+        def hostname
+          data["FreeSWITCH-Hostname"]
+        end
+
+        # Returns the logical FreeSWITCH switch name.
+        # @return [String, nil] Switch name configured on the emitting node.
+        def switchname
+          data["FreeSWITCH-Switchname"]
+        end
+
+        # Returns the IPv4 address advertised by FreeSWITCH.
+        # @return [String, nil] IPv4 address of the emitting node.
+        def ipv4
+          data["FreeSWITCH-IPv4"]
+        end
+
+        # Returns the IPv6 address advertised by FreeSWITCH.
+        # @return [String, nil] IPv6 address of the emitting node.
+        def ipv6
+          data["FreeSWITCH-IPv6"]
+        end
+
+        # Returns the event subclass when the event provides one.
+        # @return [String, nil] Module-specific subclass, often used by CUSTOM events.
         def subclass
           data["Event-Subclass"]
         end
 
+        # Returns the event timestamp formatted in the server local timezone.
+        # @return [String, nil] Human-readable local date and time string.
+        def date_local
+          data["Event-Date-Local"]
+        end
+
+        # Returns the event timestamp formatted in GMT.
+        # @return [String, nil] Human-readable GMT date and time string.
+        def date_gmt
+          data["Event-Date-GMT"]
+        end
+
+        # Returns the raw FreeSWITCH event timestamp.
+        # @return [String, nil] Epoch timestamp expressed in microseconds.
+        def timestamp
+          data["Event-Date-Timestamp"]
+        end
+
+        # Returns the FreeSWITCH source file that emitted the event.
+        # @return [String, nil] Internal source filename from the FreeSWITCH runtime.
+        def calling_file
+          data["Event-Calling-File"]
+        end
+
+        # Returns the FreeSWITCH source function that emitted the event.
+        # @return [String, nil] Internal function name from the FreeSWITCH runtime.
+        def calling_function
+          data["Event-Calling-Function"]
+        end
+
+        # Returns the FreeSWITCH source line number that emitted the event.
+        # @return [String, nil] Internal line number from the FreeSWITCH runtime.
+        def calling_line_number
+          data["Event-Calling-Line-Number"]
+        end
+
+        # Returns the monotonic event sequence assigned by FreeSWITCH.
+        # @return [String, nil] Sequence number as exposed by the event payload.
+        def sequence
+          data["Event-Sequence"]
+        end
+
+        # Returns the channel UUID associated with the event.
+        # @return [String, nil] Session identifier when the event refers to a channel.
         def uuid
           data["Unique-ID"]
         end
 
+        # Returns the UUID assigned to a background job.
+        # @return [String, nil] Job identifier for BACKGROUND_JOB events.
         def job_uuid
           data["Job-UUID"]
         end
 
+        # Returns the command executed by the background job.
+        # @return [String, nil] Original command name reported by a BACKGROUND_JOB event.
+        def job_command
+          data["Job-Command"]
+        end
+
+        # Returns the command executed by a synchronous API event.
+        # @return [String, nil] API command name reported by an API event.
+        def api_command
+          data["API-Command"]
+        end
+
+        # Returns the human-readable informational text attached to the event.
+        # @return [String, nil] Summary text such as the HEARTBEAT status message.
+        def info
+          data["Event-Info"]
+        end
+
+        # Returns the optional event body payload.
+        # @return [String, nil] Body content, commonly used for api/bgapi command output.
         def body
           data["_body"]
         end
 
+        # Returns whether the event represents a bgapi job completion.
+        # @return [Boolean] True when the event name is BACKGROUND_JOB.
+        def bg_job_event?
+          name == "BACKGROUND_JOB"
+        end
+
+        # Returns whether the event body represents an ESL command error.
+        # @return [Boolean] True for bodies starting with -ERR or -USAGE,
+        #   false for non-error bodies, false when the body is missing.
+        def error?
+          body&.match?(ERROR_BODY_PREFIX) || false
+        end
+
+        # Returns the value of a channel variable exported in the event payload.
+        # @return [String, nil] Value stored under the corresponding variable_* event field.
         def channel_variable(name)
           data["variable_#{name}"]
         end

data/lib/freeswitch/esl/protocol/message.rb

@@ -24,14 +24,19 @@ module Freeswitch
           headers["Reply-Text"]
         end
 
+        # Return true when the message payload represents a successful ESL reply.
+        # For +api/response+ messages the success marker lives in the body; for
+        # command replies it lives in the Reply-Text header.
         def successful?
           if content_type == "api/response"
-            body&.start_with?("+OK")
+            body&.start_with?("+OK") || false
           else
-            reply_text&.start_with?("+OK")
+            reply_text&.start_with?("+OK") || false
           end
         end
 
+        # Extract the FreeSWITCH error text without the leading +-ERR+ marker.
+        # Returns +nil+ for successful replies or when no error payload is present.
         def error_message
           text = content_type == "api/response" ? body : reply_text
           text&.start_with?("-ERR") ? text.sub(/\A-ERR\s*/, "").strip : nil

data/lib/freeswitch/esl/version.rb

@@ -2,6 +2,6 @@
 
 module Freeswitch
   module ESL
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/freeswitch/esl.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "logger"
+require "ztimer"
 
 require "freeswitch/esl/version"
 require "freeswitch/esl/errors"
@@ -9,6 +10,7 @@ require "freeswitch/esl/configuration"
 require "freeswitch/esl/protocol/message"
 require "freeswitch/esl/protocol/event"
 require "freeswitch/esl/connection"
+require "freeswitch/esl/command"
 require "freeswitch/esl/client"
 
 module Freeswitch
@@ -22,7 +24,7 @@ module Freeswitch
       end
 
       def configuration
-        @configuration ||= Configuration.build
+        @configuration ||= Configuration.new
       end
 
       def reset!

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: freeswitch-esl
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Demetra Opinioni.net Srl
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-05 00:00:00.000000000 Z
+date: 2026-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: configatron
@@ -38,6 +38,62 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: ztimer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -108,10 +164,12 @@ files:
 - lib/freeswitch-esl.rb
 - lib/freeswitch/esl.rb
 - lib/freeswitch/esl/client.rb
+- lib/freeswitch/esl/command.rb
 - lib/freeswitch/esl/configuration.rb
 - lib/freeswitch/esl/connection.rb
+- lib/freeswitch/esl/connection/command_dispatcher.rb
+- lib/freeswitch/esl/connection/command_request.rb
 - lib/freeswitch/esl/connection/event_dispatcher.rb
-- lib/freeswitch/esl/connection/message_reader.rb
 - lib/freeswitch/esl/errors.rb
 - lib/freeswitch/esl/logger.rb
 - lib/freeswitch/esl/protocol/event.rb

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

@@ -1,109 +0,0 @@
-# frozen_string_literal: true
-
-require "timeout"
-
-module Freeswitch
-  module ESL
-    class Connection
-      # Reads ESL protocol messages from the socket and routes them appropriately.
-      # Runs in a dedicated thread and handles socket parsing and message dispatch.
-      class MessageReader
-        def initialize(socket, event_dispatcher, &on_disconnect_callback)
-          @socket = socket
-          @event_dispatcher = event_dispatcher
-          @on_disconnect_callback = on_disconnect_callback
-          @response_queue = Queue.new
-          @reader_thread = nil
-        end
-
-        # Get the response queue (where command replies are enqueued).
-        attr_reader :response_queue
-
-        # Start the reader thread.
-        def start
-          return if @reader_thread
-
-          @reader_thread = Thread.new do
-            loop do
-              msg = read_message
-              unless msg
-                on_disconnect(DisconnectedError.new("Connection closed by remote host"))
-                break
-              end
-
-              route_message(msg)
-            rescue IOError, Errno::ECONNRESET, Errno::ENOTCONN => e
-              on_disconnect(DisconnectedError.new(e.message))
-              break
-            end
-          end
-          @reader_thread.name = "esl-reader"
-          @reader_thread.abort_on_exception = false
-        end
-
-        # Stop the reader thread and join it.
-        def stop
-          # The thread exits when socket reads hit EOF/error. `stop` is only a
-          # synchronisation point to wait for clean shutdown.
-          @reader_thread&.join
-        end
-
-        # Wait for and return a response from the response queue with timeout.
-        def receive_response(timeout:)
-          result = nil
-          Timeout.timeout(timeout) { result = @response_queue.pop }
-          raise result if result.is_a?(Exception)
-
-          result
-        rescue Timeout::Error
-          raise TimeoutError, "Command timed out after #{timeout}s — connection closed"
-        end
-
-        # Enqueue an error to unblock waiting threads (e.g., on disconnect).
-        def enqueue_error(error)
-          @response_queue << error
-        end
-
-        private
-
-        def read_message
-          headers = {}
-
-          loop do
-            line = @socket.gets("\n")
-            return nil unless line
-
-            line = line.chomp
-            break if line.empty?
-
-            key, value = line.split(": ", 2)
-            headers[key] = value
-          end
-
-          return nil if headers.empty?
-
-          body = @socket.read(headers["Content-Length"].to_i) if headers.key?("Content-Length")
-          Protocol::Message.new(headers, body)
-        end
-
-        def route_message(message)
-          # Unknown content types are ignored on purpose.
-          case message.content_type
-          when "auth/request", "command/reply", "api/response"
-            @response_queue << message
-          when "text/event-json"
-            @event_dispatcher.enqueue_event(Protocol::Event.new(message.body))
-          when "text/disconnect-notice"
-            on_disconnect(DisconnectedError.new("FreeSWITCH sent disconnect notice"))
-          end
-        end
-
-        def on_disconnect(error)
-          # First wake up waiting command calls, then notify upper layers.
-          @response_queue << error # unblock any waiting receive_response
-          @on_disconnect_callback&.call(error)
-        end
-      end
-    end
-  end
-end