freeswitch-esl 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f837d66f54cb1b978273c193f63ae772a2c967943b330130e77bd56335d6dd5
-  data.tar.gz: 3e71ae84d554456aa359483b3d8a2923cba563904e03ecb1780cf94c440745bc
+  metadata.gz: 9c0d4b60476e72dd268724e8d4d2e560505295de1e5d91cb78c53e065b539d8e
+  data.tar.gz: d79c813eb54beaa5074f7b7e05659fb1fe272bb3ef914b2d50c0a1b35540de62
 SHA512:
-  metadata.gz: 742e626b3428f49a9a3e0bc5bb10e85ce284baa6a57ce7cd13157351ad3475201548028c0e124d37d56f428d3a6b3e03dd5eaedd908a24e7795ec17d4cb2b3c2
-  data.tar.gz: d4a46398d82a476311a0508780d6a15275b73b664657d22bd1236d488faaea62973992223a81d20b3fed29064a1f5e9d860040c0643307ee129f576e471d7dbf
+  metadata.gz: 6c815f9380e5de15a2e31d3fa9940b761ccdd4ac10b856cf82bb986c209a9f7d1b4b6236f626fd7ebf828a7379caaabc1469e0eb8eb3a62e3e9ed54b341dafde
+  data.tar.gz: eeca1cbb4a3ca90cfa48fbb5e4589f1efac8b55c29529162bc82f4f6bbe06749cb6d190aba2a2b4e0d005b222a30c7e0cd3d4537fd208d274f243e7cc6c41a18

data/README.md

@@ -1,7 +1,7 @@
 # freeswitch-esl
 
 `freeswitch-esl` is a Ruby gem for interacting with FreeSWITCH through ESL (Event Socket Library).
-This version is intentionally focused on one direction only: your Ruby process connects to `mod_event_socket` and uses a single shared client, `Freeswitch::ESL.client`.
+This version is intentionally focused on one direction only: your Ruby process connects inbound to `mod_event_socket` and manages one or more `Freeswitch::ESL::Client` instances.
 
 The implementation keeps the public API small and groups protocol concerns separately:
 
@@ -56,7 +56,7 @@ require 'freeswitch-esl'
 
 ## Configuration
 
-Configure the library once and then use the shared client:
+Configure the library once and then connect a client:
 
 ```ruby
 require 'logger'
@@ -66,10 +66,12 @@ Freeswitch::ESL.configure do |config|
   config.freeswitch.host = 'freeswitch.example.com'
   config.freeswitch.port = 8021
   config.freeswitch.password = 'ClueCon'
-  config.freeswitch.timeout = 5
+  config.freeswitch.reconnect = true
   config.freeswitch.retry_delay = 1.0
   config.freeswitch.max_retries = 5
   config.logger = Logger.new($stdout)
+  config.logger.level = Logger::INFO
+  config.debug = false
 end
 ```
 
@@ -77,11 +79,12 @@ Defaults:
 
 - `config.freeswitch.host = '127.0.0.1'`
 - `config.freeswitch.port = 8021`
-- `config.freeswitch.password = 'ClueCon'`
-- `config.freeswitch.timeout = 5`
+- `config.freeswitch.password = nil`
+- `config.freeswitch.reconnect = true`
 - `config.freeswitch.retry_delay = 1.0`
-- `config.freeswitch.max_retries = 5`
-- `config.logger = nil`
+- `config.freeswitch.max_retries = Float::INFINITY`
+- `config.logger = Logger.new(IO::NULL)`
+- `config.debug = false`
 
 ## FreeSWITCH Configuration
 
@@ -106,7 +109,7 @@ In the included Docker setup, `lan` is intentional because it allows both loopba
 
 ## Usage
 
-### Shared client
+### Connect a client
 
 ```ruby
 require 'freeswitch-esl'
@@ -117,7 +120,7 @@ Freeswitch::ESL.configure do |config|
   config.freeswitch.password = 'ClueCon'
 end
 
-client = Freeswitch::ESL.client
+client = Freeswitch::ESL::Client.connect
 
 client.subscribe('CHANNEL_CREATE', 'CHANNEL_HANGUP', 'DTMF')
 client.on('CHANNEL_CREATE') do |event|
@@ -128,10 +131,24 @@ client.on('DTMF') do |event|
   puts "digit=#{event['DTMF-Digit']} duration=#{event['DTMF-Duration']}"
 end
 
-response = client.api('status')
+response = client.exec('status').response
 puts response.body
 
-Freeswitch::ESL.reset_client!
+client.close
+```
+
+`Freeswitch::ESL::Client.connect` builds a client with the global configuration,
+opens the TCP socket, waits for FreeSWITCH `auth/request`, authenticates, subscribes
+to the default event set, and returns a ready client instance.
+
+### Reconfigure an existing client
+
+```ruby
+client = Freeswitch::ESL::Client.connect
+
+client.close
+client.configure(freeswitch: { host: 'fs-backup.example.com', reconnect: true })
+client.connect
 ```
 
 ### Background API
@@ -139,24 +156,51 @@ Freeswitch::ESL.reset_client!
 ```ruby
 require 'freeswitch-esl'
 
-client = Freeswitch::ESL.client
+client = Freeswitch::ESL::Client.connect
+
+command = client.exec('originate', 'sofia/default/1000 &park')
 
-job_uuid = client.bgapi('originate', 'sofia/default/1000 &park') do |event|
-  puts "job #{event.job_uuid} finished"
-  puts event.body
+command.on_complete do |completed|
+  puts "job #{completed.job_uuid} finished with status=#{completed.status}"
+  puts completed.response.body if completed.response
 end
 
-puts "submitted job=#{job_uuid}"
+puts "submitted job=#{command.job_uuid}"
+
+command.wait
+client.close
 ```
 
+`Client#exec` wraps `bgapi` and returns a `Freeswitch::ESL::Command` object.
+You can:
+
+- call `command.wait` for blocking flow
+- call `command.response` to block until completion and get the final `BACKGROUND_JOB` event
+- inspect `command.status`, `command.ok?`, `command.failed?`, `command.timeout?`
+- attach `command.on_complete { |cmd| ... }` for async completion handling
+
+If you prefer lower-level primitives, `Freeswitch::ESL::Client` also exposes the inherited connection API:
+
+- `send_command`
+- `bgapi`
+- `subscribe`
+- `unsubscribe`
+- `filter`
+- `on`
+
 ### Auto reconnect
 
-Event handlers remain registered across reconnects. After reconnect, re-subscribe to events:
+When `config.freeswitch.reconnect` is enabled, `Client#connect` retries on initial
+connection/authentication failure and the client reconnects automatically after later
+disconnects.
+
+Event handlers remain registered across reconnects because the event dispatcher is
+preserved. Subscriptions do not: after reconnect, re-subscribe to the events you need.
 
 ```ruby
 require 'freeswitch-esl'
 
-client = Freeswitch::ESL.client
+client = Freeswitch::ESL::Client.connect
 
 client.on('CHANNEL_HANGUP') do |event|
   puts "hangup cause=#{event['Hangup-Cause']}"
@@ -169,6 +213,9 @@ end
 client.subscribe('CHANNEL_HANGUP')
 ```
 
+`client.close` stops reconnect attempts immediately. The same client instance can be
+connected again later with `client.connect`.
+
 ## Docker Compose Test Lab
 
 This repository includes a local FreeSWITCH environment for ESL experimentation.
@@ -180,7 +227,20 @@ Files included:
 - `docker/freeswitch/autoload_configs/event_socket.conf.xml`
 - `examples/inbound_status.rb`
 
-The compose file uses the public image `safarov/freeswitch:latest` and overlays only the ESL-specific configuration needed for local development.
+The compose file builds FreeSWITCH locally from the official source repository release.
+The Dockerfile is aligned with the upstream reference at
+`signalwire/freeswitch/docker/examples/Debian11/Dockerfile`, adapted for Debian Bookworm and this project's runtime needs.
+By default it uses `FS_VERSION=latest`.
+
+To pin a specific release tag (recommended for reproducible environments), set the build arg in `docker-compose.yml`:
+
+```yaml
+services:
+  freeswitch:
+    build:
+      args:
+        FS_VERSION: v1.10.12
+```
 
 ### Start FreeSWITCH
 
@@ -188,7 +248,7 @@ The compose file uses the public image `safarov/freeswitch:latest` and overlays
 docker compose up -d
 ```
 
-If you change image or base distro later, verify that the configuration directory is still `/etc/freeswitch`.
+If you change image or base distro later, verify that the configuration directory is still `/usr/local/freeswitch/etc/freeswitch`.
 
 ### Check that FreeSWITCH is up
 
@@ -207,8 +267,9 @@ Freeswitch::ESL.configure do |config|
   config.freeswitch.password = 'ClueCon'
 end
 
-puts Freeswitch::ESL.client.api('status').body
-Freeswitch::ESL.reset_client!
+client = Freeswitch::ESL::Client.connect
+puts client.exec('status').response.body
+client.close
 ```
 
 Or run the ready-made example:

data/lib/freeswitch/esl/client.rb

@@ -8,26 +8,91 @@ module Freeswitch
     class Client < Connection
       include Freeswitch::ESL::Logger
 
+      # For full events list see https://github.com/signalwire/freeswitch/blob/master/src/switch_event.c
+      DEFAULT_EVENTS = [
+        # Events useful for channel state tracking
+        "CHANNEL_CREATE",
+        "CHANNEL_STATE",
+        "CHANNEL_CALLSTATE",
+        "CHANNEL_ANSWER",
+        "CHANNEL_BRIDGE",
+        "CHANNEL_UNBRIDGE",
+        "CHANNEL_HANGUP",
+        "CHANNEL_HANGUP_COMPLETE",
+        "CHANNEL_DESTROY",
+
+        # Extra CHANNEL events
+        "CHANNEL_EXECUTE",
+        "CHANNEL_EXECUTE_COMPLETE",
+        "CHANNEL_PROGRESS",
+        "CHANNEL_PROGRESS_MEDIA",
+
+        # Receive BACKGROUND_JOB events for bgapi commands.
+        "BACKGROUND_JOB",
+
+        # Other events that might be useful for various applications
+        "DTMF",
+        "PLAYBACK_START",
+        "PLAYBACK_STOP",
+        "RECORD_START",
+        "RECORD_STOP",
+        "HEARTBEAT",
+        "CUSTOM"
+      ].freeze
+
+      class << self
+        def connect(**)
+          new(**).connect
+        end
+      end
+
       def config
         @config ||= Freeswitch::ESL.configuration
       end
 
       def configure(**)
         close if instance_variable_defined?(:@socket) && @socket && !closed?
-        @config = Freeswitch::ESL::Configuration.build(**)
+        config.update(**)
         @intentionally_closed = false
-        establish_connection
         self
       end
 
-      def initialize(freeswitch: {}, logger: nil) # rubocop:disable Lint/MissingSuper
+      def initialize(freeswitch: {}, logger: nil, debug: false) # rubocop:disable Lint/MissingSuper
         @reconnect_handlers = []
         @intentionally_closed = false
+        @ready = false
+        @mutex = Mutex.new
+        @ready_cv = ConditionVariable.new
+
+        configure(freeswitch:, logger:, debug:)
+      end
+
+      def connect
+        @intentionally_closed = false
+        config.freeswitch.reconnect ? attempt_reconnect(sync: true) : establish_connection
+
+        self
+      end
+
+      def wait_until_ready(timeout: nil, raise_error: true)
+        @mutex.synchronize do
+          return self if ready?
+
+          @ready_cv.wait(@mutex, timeout)
+
+          raise TimeoutError, "Timed out waiting for FreeSWITCH ESL client to be ready" if raise_error && !ready?
+        end
+
+        self
+      end
 
-        configure(freeswitch:, logger:)
+      def ready?
+        @ready
       end
 
       def close
+        @mutex.synchronize { @ready = false }
+
         logger.info "Closing FreeSWITCH ESL client connection"
         @intentionally_closed = true
         if @reconnect_thread
@@ -44,14 +109,27 @@ module Freeswitch
         self
       end
 
-      private
+      # Execute a command via bgapi and return a {Command} object.
+      #
+      # @param command [String] the FreeSWITCH API command (e.g. "originate")
+      # @param args [String, nil] command arguments
+      # @param timeout [Integer] seconds to wait for the bgapi result event
+      # @yieldparam cmd [Command] called on completion (success or failure)
+      # @return [Command]
+      def exec(command, *, timeout: Command::DEFAULT_TIMEOUT, raise_error: true, &)
+        cmd = Command.new(self, command, *, timeout:, raise_error:, &)
+        cmd.execute!
+
+        cmd
+      end
 
       def establish_connection
         logger.info "Connecting to FreeSWITCH ESL at #{config.freeswitch.host}:#{config.freeswitch.port}"
-        socket = build_socket
-        initialize_socket(socket)
-        authenticate_with_config!
-        logger.info "Authenticated with FreeSWITCH ESL"
+        initialize_socket(build_socket, debug: config.debug)
+        authenticate!
+        subscribe(*DEFAULT_EVENTS)
+        ready!
+        logger.info "FreeSWITCH ESL client authenticated and ready!"
       end
 
       def build_socket
@@ -60,21 +138,47 @@ module Freeswitch
         socket
       end
 
-      def authenticate_with_config!
-        authenticate!(config.freeswitch.password, timeout: config.freeswitch.timeout)
+      # Authenticate against FreeSWITCH after the initial auth/request message.
+      def authenticate!
+        # Wait for the initial auth/request message initiated by FreeSWITCH before sending the auth command.
+        # This ensures we don't send auth before FreeSWITCH is ready to receive it,
+        # which would cause an immediate disconnect.
+        logger.debug "Waiting for auth/request from FreeSWITCH..."
+        wait_for_auth_request(timeout: 10)
+
+        # Send the auth command and wait for the response to confirm authentication succeeded.
+        cmd = send_command("auth #{config.freeswitch.password}", timeout: 10).wait(raise_error: false)
+        return if cmd.ok?
+
+        raise AuthenticationError,
+              "Authentication failed: #{cmd.error.class} - #{cmd.error.message.inspect}"
+      end
+
+      def ready!
+        @mutex.synchronize { @ready = true }
+        @ready_cv.broadcast
       end
 
       def on_disconnect(error)
+        super
+
+        @mutex.synchronize { @ready = false }
         return if @intentionally_closed
 
-        super
         logger.warn "Disconnected from FreeSWITCH ESL: #{error.message}"
         # Check the flag again in case user code called close during
         # disconnect handling.
         attempt_reconnect unless @intentionally_closed
       end
 
-      def attempt_reconnect
+      def attempt_reconnect(sync: false)
+        # If sync is true, the reconnect attempt is made in the current thread and blocks until it succeeds or fails.
+        return reconnect_with_backoff if sync
+
+        # If a reconnect thread is already running, do not start another one.
+        return if @reconnect_thread&.alive?
+
+        # Start a new thread to handle reconnect attempts in the background.
         @reconnect_thread = Thread.new do
           reconnect_with_backoff
         end
@@ -86,17 +190,14 @@ module Freeswitch
         delay = config.freeswitch.retry_delay
 
         loop do
-          # Wait before each retry to avoid a tight retry loop.
-          sleep(delay)
           break if @intentionally_closed
-
           break if reconnect_once
 
+          # Wait before each retry to avoid a tight retry loop.
+          sleep(delay)
+
           retries += 1
           break if stop_reconnect?(retries)
-
-          # Increase delay after each failure, but keep it under max_retry_delay.
-          delay = [delay * 2, config.freeswitch.max_retry_delay].min
         end
       end
 

data/lib/freeswitch/esl/command.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Freeswitch
+  module ESL
+    # Represents the asynchronous execution of a bgapi command.
+    #
+    # A Command is created by {Client#exec} and tracks the full lifecycle of the
+    # request: pending → completed (success or failure).
+    #
+    # === Async usage (non-blocking)
+    #
+    #   cmd = client.exec("originate", "sofia/default/1234@example.com")
+    #   cmd.on_complete { |c| puts c.response.body }
+    #   # ... do other work ...
+    #   cmd.response  # blocks until completed (or timeout)
+    #
+    # === Sync usage (blocking)
+    #
+    #   cmd = client.exec("originate", "sofia/default/1234@example.com")
+    #   cmd.wait
+    #   puts cmd.response.body
+    #
+    # === Timeout
+    #
+    # The default timeout is {DEFAULT_TIMEOUT} seconds. If the bgapi result event
+    # does not arrive in time the command transitions to :timeout and any
+    # subsequent result is silently ignored.
+    class Command
+      DEFAULT_TIMEOUT = 60
+
+      # @return [:pending, :ok, :failed, :timeout] current status of the command
+      attr_reader :status
+
+      # @return [String, nil] Job-UUID assigned by FreeSWITCH (nil if invalid)
+      attr_reader :job_uuid
+
+      # @return [CommandError, TimeoutError, nil] the error that caused the command to fail (nil if successful)
+      attr_reader :error
+
+      attr_reader :command, :args, :sent_at, :finished_at
+
+      def initialize(client, command, *args, timeout: DEFAULT_TIMEOUT, raise_error: true, &block)
+        @client = client
+        @command = command
+        @args = args
+        @timeout = timeout
+        @raise_error = raise_error
+        @status = :pending
+        @job_uuid = nil
+        @response = nil
+        @error = nil
+        @callbacks = block ? [block] : []
+        @mutex = Mutex.new
+        @cond = ConditionVariable.new
+        @sent_at = nil
+        @finished_at = nil
+
+        validate_command!
+      end
+
+      def execute!
+        configure_timeout!
+        return unless wait_until_client_ready
+
+        @sent_at = now
+        @status = :sent
+        @job_uuid = @client.bgapi(@command, *@args) do |event|
+          event.error? ? fail!(event) : complete!(event)
+        end
+      rescue StandardError => e
+        @status = :failed
+        @error = e
+        @finished_at = now
+        raise e if @raise_error
+      end
+
+      # Register a callback to be called when the command completes (success or
+      # failure). Multiple callbacks are supported and are called in order.
+      # If the command is already completed the block is called immediately.
+      # Returns +self+ for chaining.
+      def on_complete(&block)
+        raise ArgumentError, "Block is required" unless block_given?
+
+        @callbacks << block
+        block.call(self) if completed?
+
+        self
+      end
+
+      # Block the calling thread until the command completes or the timeout
+      # expires.
+      # @return [Protocol::Event] the event returned by FreeSWITCH when the command completed successfully
+      # @return [nil] if the command failed or timed out but did not raise an exception (raise_error: false)
+      # @raise [CommandError, TimeoutError] when the command failed or timed out
+      def response
+        wait unless completed?
+
+        @response
+      end
+
+      # Wait for the command to complete, fail or timeout.
+      # @return [Command] self after completion
+      def wait
+        @mutex.synchronize do
+          return self if completed?
+
+          wait_time = @timeout ? (@timeout - execution_time.to_f) : nil
+          @cond.wait(@mutex, wait_time)
+        end
+
+        raise @error if @error && @raise_error
+
+        self
+      end
+
+      # @return [Boolean] true when the command has finished (success or failure)
+      def completed?
+        !pending?
+      end
+
+      # @return [Boolean] true when the command is still waiting for a result
+      def pending?
+        %i[pending sent].include?(@status)
+      end
+
+      # @return [Boolean] true when the command completed successfully
+      def ok?
+        @status == :ok
+      end
+
+      # @return [Boolean] true when the command terminated with a timeout (a special kind of failure)
+      def timeout?
+        @status == :timeout
+      end
+
+      # @return [Boolean] true when the command failed or timed out
+      def failed?
+        %i[failed timeout].include?(@status)
+      end
+
+      def execution_time
+        return nil unless @sent_at
+
+        (@finished_at || now) - @sent_at
+      end
+
+      private
+
+      def validate_command!
+        return unless @command.nil? || @command.strip.empty?
+
+        @status = :failed
+        @error = "Command cannot be blank"
+        raise ArgumentError, @error
+      end
+
+      def configure_timeout!
+        return unless @timeout
+
+        Ztimer.after(@timeout * 1000) do
+          timeout!("Command timed out after #{@timeout}s waiting for BACKGROUND_JOB result")
+        end
+      end
+
+      # Wait until the client is ready to send commands. If readiness does not
+      # happen within the configured timeout, the command fails before any bgapi
+      # request is sent to FreeSWITCH.
+      def wait_until_client_ready
+        is_ready = @client.wait_until_ready(timeout: @timeout, raise_error: false).ready?
+        return is_ready if is_ready
+
+        settle(:failed) do
+          @error = ConnectionError.new("FreeSWITCH ESL Client is not ready to send commands")
+        end
+
+        false
+      end
+
+      # Called when the BACKGROUND_JOB event reports an ESL-level failure body.
+      # @param event [Protocol::Event] the terminal event containing the error details.
+      def fail!(event)
+        settle(:failed) do
+          @response = event
+          @error = CommandError.new("Command `#{@command}#{@args.map { |arg| " #{arg}" }.join}` failed: #{event.body}")
+        end
+      end
+
+      # Called internally by {EventDispatcher} when the BACKGROUND_JOB event
+      # arrives. Ignored if the command is no longer pending (e.g. already
+      # timed out).
+      # @param event [Protocol::Event]
+      def complete!(event)
+        settle(:ok) { @response = event }
+      end
+
+      def timeout!(message)
+        settle(:timeout) { @error = TimeoutError.new(message) }
+      end
+
+      # Apply a terminal state transition under the mutex, wake waiters and run
+      # completion callbacks after the internal state is visible to observers.
+      def settle(status)
+        @mutex.synchronize do
+          return unless pending? # do nothing if already completed
+
+          yield
+          @status = status.to_sym
+          @finished_at = now
+          @sent_at ||= @finished_at # if the command never sent, set sent_at to finished_at
+          @cond.broadcast
+        end
+
+        @callbacks.each { |cb| cb.call(self) }
+      end
+
+      def now
+        Time.now
+      end
+    end
+  end
+end