freeswitch-esl 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c0d4b60476e72dd268724e8d4d2e560505295de1e5d91cb78c53e065b539d8e
-  data.tar.gz: d79c813eb54beaa5074f7b7e05659fb1fe272bb3ef914b2d50c0a1b35540de62
+  metadata.gz: a8cd34473eb85fec06aef418a2560d26a64975cb08245de7776aae2678dea90e
+  data.tar.gz: e79323aad3dd7655ea46c731818edbbf056dc6c24fb051fedc26a46327133231
 SHA512:
-  metadata.gz: 6c815f9380e5de15a2e31d3fa9940b761ccdd4ac10b856cf82bb986c209a9f7d1b4b6236f626fd7ebf828a7379caaabc1469e0eb8eb3a62e3e9ed54b341dafde
-  data.tar.gz: eeca1cbb4a3ca90cfa48fbb5e4589f1efac8b55c29529162bc82f4f6bbe06749cb6d190aba2a2b4e0d005b222a30c7e0cd3d4537fd208d274f243e7cc6c41a18
+  metadata.gz: 106d51156de70d8fcd97dc9c1d2f1f4c8d748b3c107f0967a23c40627dbcdd4d7a86d146c91b7a30e6e11913932b17c5e7470f5ef0d0651e48d49b332a802ac2
+  data.tar.gz: 4a4d954236148455f75d44518e9c08e8f17f430d786bba00332cb724920788af46e361b40c5d4421f9acfc95dc46e2e7b78a0341c08e813669542f09f9aa1348

data/README.md

@@ -1,5 +1,9 @@
 # freeswitch-esl
 
+![Coverage](https://gitlab.opinioni.net/demetra-developers/rubygems/freeswitch-esl/badges/main/coverage.svg)
+[![Gem Version](https://badge.fury.io/rb/freeswitch-esl.svg)](https://badge.fury.io/rb/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 inbound to `mod_event_socket` and manages one or more `Freeswitch::ESL::Client` instances.
 
@@ -179,6 +183,16 @@ You can:
 - inspect `command.status`, `command.ok?`, `command.failed?`, `command.timeout?`
 - attach `command.on_complete { |cmd| ... }` for async completion handling
 
+As of 0.2.2, `client.exec(..., timeout: seconds)` shares one monotonic timeout
+budget across client readiness, the initial `bgapi` acknowledgement and the
+`BACKGROUND_JOB` result. `exec` waits for that acknowledgement; `wait`/`response`
+wait for the result. `timeout: nil` disables the deadline. Submission timeout
+raises `Freeswitch::ESL::TimeoutError` unless `raise_error: false`, in which case
+the command records `status: :timeout`. Late replies are consumed in FIFO order
+without reviving the command or closing the connection. A timeout after sending
+does **not** prove that FreeSWITCH did not execute the command; reconcile its
+remote outcome before deciding whether a retry is safe.
+
 If you prefer lower-level primitives, `Freeswitch::ESL::Client` also exposes the inherited connection API:
 
 - `send_command`
@@ -215,6 +229,9 @@ client.subscribe('CHANNEL_HANGUP')
 
 `client.close` stops reconnect attempts immediately. The same client instance can be
 connected again later with `client.connect`.
+Call `close` for cleanup even after a remote disconnect: it releases the event
+dispatcher too. Local shutdown fails pending command replies with
+`Freeswitch::ESL::DisconnectedError` and does not trigger a reconnect.
 
 ## Docker Compose Test Lab
 

data/lib/freeswitch/esl/command.rb

@@ -22,9 +22,10 @@ module Freeswitch
     #
     # === 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.
+    # The default timeout is {DEFAULT_TIMEOUT} seconds across client readiness,
+    # the bgapi acknowledgement and the result event. A timeout after submission
+    # does not establish whether FreeSWITCH executed the command. Late replies
+    # remain in the connection FIFO until consumed; late results are ignored.
     class Command
       DEFAULT_TIMEOUT = 60
 
@@ -61,17 +62,13 @@ module Freeswitch
       def execute!
         configure_timeout!
         return unless wait_until_client_ready
+        return unless begin_submission?
 
-        @sent_at = now
-        @status = :sent
-        @job_uuid = @client.bgapi(@command, *@args) do |event|
+        @job_uuid = @client.bgapi(@command, *@args, timeout: remaining_timeout) do |event|
           event.error? ? fail!(event) : complete!(event)
         end
       rescue StandardError => e
-        @status = :failed
-        @error = e
-        @finished_at = now
-        raise e if @raise_error
+        handle_submission_error(e)
       end
 
       # Register a callback to be called when the command completes (success or
@@ -82,7 +79,7 @@ module Freeswitch
         raise ArgumentError, "Block is required" unless block_given?
 
         @callbacks << block
-        block.call(self) if completed?
+        yield(self) if completed?
 
         self
       end
@@ -104,10 +101,14 @@ module Freeswitch
         @mutex.synchronize do
           return self if completed?
 
-          wait_time = @timeout ? (@timeout - execution_time.to_f) : nil
-          @cond.wait(@mutex, wait_time)
+          while pending?
+            break if deadline_expired?
+
+            @cond.wait(@mutex, remaining_timeout)
+          end
         end
 
+        timeout!("Command timed out after #{@timeout}s waiting for completion") if pending?
         raise @error if @error && @raise_error
 
         self
@@ -157,16 +158,48 @@ module Freeswitch
       def configure_timeout!
         return unless @timeout
 
+        @deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout
         Ztimer.after(@timeout * 1000) do
-          timeout!("Command timed out after #{@timeout}s waiting for BACKGROUND_JOB result")
+          timeout!("Command timed out after #{@timeout}s waiting for completion")
+        end
+      end
+
+      def remaining_timeout
+        [@deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max if @deadline
+      end
+
+      def deadline_expired?
+        @deadline && remaining_timeout.zero?
+      end
+
+      # The watchdog may already have settled the command while bgapi was
+      # waiting. Never overwrite that result or invoke completion twice.
+      def handle_submission_error(error)
+        settle(error.is_a?(TimeoutError) ? :timeout : :failed) { @error = error }
+        raise @error if @raise_error && @error
+      end
+
+      def begin_submission?
+        @mutex.synchronize do
+          return false unless pending?
+
+          if !@deadline || remaining_timeout.positive?
+            @sent_at = now
+            @status = :sent
+            @cond.broadcast
+            return true
+          end
         end
+
+        timeout!("Command timed out after #{@timeout}s waiting for client readiness")
+        false
       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?
+        is_ready = @client.wait_until_ready(timeout: remaining_timeout, raise_error: false).ready?
         return is_ready if is_ready
 
         settle(:failed) do

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

@@ -100,6 +100,8 @@ module Freeswitch
 
           logger.debug "Stopping command dispatcher and closing socket"
           @closed = true
+          @disconnect_error ||= DisconnectedError.new("Connection is closed")
+          disconnect_pending_commands
           @healthcheck_timer&.cancel!
 
           begin
@@ -140,19 +142,25 @@ module Freeswitch
         # pending command with the same error and then invoke the disconnect
         # callback once teardown has completed.
         def disconnect!(error)
+          # Closing the socket in stop wakes a blocked reader with EOF/IOError.
+          # That is local teardown, not a new remote disconnect/reconnect signal.
+          return if closed?
+
           @disconnect_error = error
           logger.debug "Disconnected: #{error.message}"
 
-          # Deliver DisconnectedError to all pending in-flight command executions
+          stop
+          @on_disconnect&.call(error)
+        end
+
+        # Local teardown must wake pending commands too, without triggering reconnect.
+        def disconnect_pending_commands
           loop do
             cmd = pop_command(non_block: true)
             break unless cmd
 
-            cmd.disconnected!(error)
+            cmd.disconnected!(@disconnect_error)
           end
-
-          stop
-          @on_disconnect&.call(error)
         end
 
         # Enqueue and write the command while the caller holds +@write_mutex+ so

data/lib/freeswitch/esl/connection.rb

@@ -99,14 +99,14 @@ module Freeswitch
       # removed together with the dispatcher instances, so a reconnect path must
       # rebuild them through {#initialize_socket}.
       def close
-        return if @closed
-
+        # A remote disconnect sets @closed before explicit cleanup. Dispatchers
+        # still need to be stopped even when the transport is already closed.
         @closed = true
         @command_dispatcher&.stop
         @event_dispatcher&.stop
 
-        send(:remove_instance_variable, :@command_dispatcher)
-        send(:remove_instance_variable, :@event_dispatcher)
+        @command_dispatcher = nil
+        @event_dispatcher = nil
       end
 
       protected
@@ -114,12 +114,15 @@ module Freeswitch
       # (Re-)initialise all per-connection state for the given socket.
       # Called by subclasses on initial connect and on reconnect.
       def initialize_socket(socket, debug: false)
+        # Failed authentication/subscription may leave the previous reader alive.
+        # Retire it before publishing a replacement dispatcher.
+        @command_dispatcher&.stop
         @socket = socket
         @closed = false
 
         # Keep dispatcher data across reconnects so existing handlers still work
         # after a new socket is created.
-        unless instance_variable_defined?(:@event_dispatcher)
+        unless @event_dispatcher
           @event_dispatcher = EventDispatcher.new
           @event_dispatcher.start
         end

data/lib/freeswitch/esl/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: freeswitch-esl
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Demetra Opinioni.net Srl
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-26 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: configatron
@@ -151,9 +150,9 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.22'
 description: |
-  A thread-safe Ruby client for the FreeSWITCH Event Socket Library.
-  Supports inbound (client→FreeSWITCH) and outbound (FreeSWITCH→client) socket modes,
-  API commands, background API, event subscriptions, call control and DTMF handling.
+  A thread-safe Ruby client for FreeSWITCH Event Socket Library connections.
+  Focused on inbound mod_event_socket integration with command execution,
+  bgapi jobs, JSON event handling, and reconnect support.
 email:
 - developers@opinioni.net
 executables: []
@@ -175,12 +174,11 @@ files:
 - lib/freeswitch/esl/protocol/event.rb
 - lib/freeswitch/esl/protocol/message.rb
 - lib/freeswitch/esl/version.rb
-homepage: https://gitlab.opinioni.net/demetra-opinioni/rubygems/freeswitch-esl
+homepage: https://gitlab.opinioni.net/demetra-developers/rubygems/freeswitch-esl
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -195,8 +193,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key: 
+rubygems_version: 4.0.16
 specification_version: 4
-summary: Ruby client for FreeSWITCH Event Socket Library (ESL)
+summary: Inbound Ruby client for FreeSWITCH ESL
 test_files: []