freeswitch-esl 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1f837d66f54cb1b978273c193f63ae772a2c967943b330130e77bd56335d6dd5
+  data.tar.gz: 3e71ae84d554456aa359483b3d8a2923cba563904e03ecb1780cf94c440745bc
+SHA512:
+  metadata.gz: 742e626b3428f49a9a3e0bc5bb10e85ce284baa6a57ce7cd13157351ad3475201548028c0e124d37d56f428d3a6b3e03dd5eaedd908a24e7795ec17d4cb2b3c2
+  data.tar.gz: d4a46398d82a476311a0508780d6a15275b73b664657d22bd1236d488faaea62973992223a81d20b3fed29064a1f5e9d860040c0643307ee129f576e471d7dbf

data/README.md

@@ -0,0 +1,265 @@
+# 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`.
+
+The implementation keeps the public API small and groups protocol concerns separately:
+
+- `Freeswitch::ESL::Client`
+- `Freeswitch::ESL::Connection`
+- `Freeswitch::ESL::Protocol::Message`
+- `Freeswitch::ESL::Protocol::Event`
+
+## Why ESL
+
+For FreeSWITCH, ESL is still the most complete and stable integration surface for external control.
+Other interfaces exist, but they are generally less complete:
+
+- `mod_xml_rpc`: useful for some management operations, but not a replacement for event streaming and call control
+- custom REST/gRPC wrappers: possible, but usually built on top of ESL rather than replacing it
+
+If you need event subscriptions, command execution and background jobs, ESL remains the right interface.
+
+## Installation
+
+Choose one installation mode based on your environment.
+
+### Local path (development)
+
+Use this while developing the gem and application together:
+
+```ruby
+gem 'freeswitch-esl', path: '/path/to/freeswitch-esl'
+```
+
+### Git source (production)
+
+Use this when you want to pin a tag or commit from your repository:
+
+```ruby
+gem 'freeswitch-esl', git: 'https://gitlab.example.com/your-group/freeswitch-esl.git', tag: 'v0.1.0'
+```
+
+### RubyGems style (for future releases)
+
+When the gem is published on RubyGems, the classic entry is:
+
+```ruby
+gem 'freeswitch-esl'
+```
+
+Then require it:
+
+```ruby
+require 'freeswitch-esl'
+```
+
+## Configuration
+
+Configure the library once and then use the shared client:
+
+```ruby
+require 'logger'
+require 'freeswitch-esl'
+
+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.retry_delay = 1.0
+  config.freeswitch.max_retries = 5
+  config.logger = Logger.new($stdout)
+end
+```
+
+Defaults:
+
+- `config.freeswitch.host = '127.0.0.1'`
+- `config.freeswitch.port = 8021`
+- `config.freeswitch.password = 'ClueCon'`
+- `config.freeswitch.timeout = 5`
+- `config.freeswitch.retry_delay = 1.0`
+- `config.freeswitch.max_retries = 5`
+- `config.logger = nil`
+
+## FreeSWITCH Configuration
+
+### Inbound ESL (`mod_event_socket`)
+
+FreeSWITCH must expose `mod_event_socket`.
+For local development, a minimal configuration looks like this:
+
+```xml
+<configuration name="event_socket.conf" description="Socket Client">
+  <settings>
+    <param name="listen-ip" value="0.0.0.0"/>
+    <param name="listen-port" value="8021"/>
+    <param name="password" value="ClueCon"/>
+    <param name="apply-inbound-acl" value="lan"/>
+  </settings>
+</configuration>
+```
+
+For production, tighten the ACL further and do not expose port `8021` publicly.
+In the included Docker setup, `lan` is intentional because it allows both loopback and Docker private-network traffic while still avoiding a fully open event socket.
+
+## Usage
+
+### Shared client
+
+```ruby
+require 'freeswitch-esl'
+
+Freeswitch::ESL.configure do |config|
+  config.freeswitch.host = '127.0.0.1'
+  config.freeswitch.port = 8021
+  config.freeswitch.password = 'ClueCon'
+end
+
+client = Freeswitch::ESL.client
+
+client.subscribe('CHANNEL_CREATE', 'CHANNEL_HANGUP', 'DTMF')
+client.on('CHANNEL_CREATE') do |event|
+  puts "new channel: #{event.uuid}"
+end
+
+client.on('DTMF') do |event|
+  puts "digit=#{event['DTMF-Digit']} duration=#{event['DTMF-Duration']}"
+end
+
+response = client.api('status')
+puts response.body
+
+Freeswitch::ESL.reset_client!
+```
+
+### Background API
+
+```ruby
+require 'freeswitch-esl'
+
+client = Freeswitch::ESL.client
+
+job_uuid = client.bgapi('originate', 'sofia/default/1000 &park') do |event|
+  puts "job #{event.job_uuid} finished"
+  puts event.body
+end
+
+puts "submitted job=#{job_uuid}"
+```
+
+### Auto reconnect
+
+Event handlers remain registered across reconnects. After reconnect, re-subscribe to events:
+
+```ruby
+require 'freeswitch-esl'
+
+client = Freeswitch::ESL.client
+
+client.on('CHANNEL_HANGUP') do |event|
+  puts "hangup cause=#{event['Hangup-Cause']}"
+end
+
+client.on_reconnect do
+  client.subscribe('CHANNEL_HANGUP')
+end
+
+client.subscribe('CHANNEL_HANGUP')
+```
+
+## Docker Compose Test Lab
+
+This repository includes a local FreeSWITCH environment for ESL experimentation.
+It is intended for development and manual testing, and it can later serve as a base for realistic integration tests.
+
+Files included:
+
+- `docker-compose.yml`
+- `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.
+
+### Start FreeSWITCH
+
+```bash
+docker compose up -d
+```
+
+If you change image or base distro later, verify that the configuration directory is still `/etc/freeswitch`.
+
+### Check that FreeSWITCH is up
+
+```bash
+docker compose exec freeswitch fs_cli -x 'status'
+```
+
+### Test inbound ESL connectivity
+
+```ruby
+require 'freeswitch-esl'
+
+Freeswitch::ESL.configure do |config|
+  config.freeswitch.host = '127.0.0.1'
+  config.freeswitch.port = 8021
+  config.freeswitch.password = 'ClueCon'
+end
+
+puts Freeswitch::ESL.client.api('status').body
+Freeswitch::ESL.reset_client!
+```
+
+Or run the ready-made example:
+
+```bash
+ruby examples/inbound_status.rb
+```
+
+## Production Notes
+
+- keep ESL bound to a private interface whenever possible
+- protect the event socket with ACLs and a non-default password
+- do not use the included Docker configuration as-is in production
+- prefer explicit event subscriptions instead of `ALL` unless you really need global event traffic
+
+## Development
+
+Run style checks:
+
+```bash
+bundle exec rubocop
+```
+
+Run tests:
+
+```bash
+bundle exec rspec
+```
+
+### GitLab CI local
+
+Run the full local pipeline:
+
+```bash
+gitlab-ci-local
+```
+
+Run only the test job:
+
+```bash
+gitlab-ci-local rspec
+```
+
+Run only lint:
+
+```bash
+gitlab-ci-local rubocop
+```
+
+### Test stability note
+
+Some client specs use reconnect threads. To avoid order-dependent failures in random runs,
+the test teardown always closes created clients. This makes sure reconnect-related activity
+is stopped before the next example starts.

data/lib/freeswitch/esl/client.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Freeswitch
+  module ESL
+    # Inbound ESL client: connects to FreeSWITCH mod_event_socket.
+    class Client < Connection
+      include Freeswitch::ESL::Logger
+
+      def config
+        @config ||= Freeswitch::ESL.configuration
+      end
+
+      def configure(**)
+        close if instance_variable_defined?(:@socket) && @socket && !closed?
+        @config = Freeswitch::ESL::Configuration.build(**)
+        @intentionally_closed = false
+        establish_connection
+        self
+      end
+
+      def initialize(freeswitch: {}, logger: nil) # rubocop:disable Lint/MissingSuper
+        @reconnect_handlers = []
+        @intentionally_closed = false
+
+        configure(freeswitch:, logger:)
+      end
+
+      def close
+        logger.info "Closing FreeSWITCH ESL client connection"
+        @intentionally_closed = true
+        if @reconnect_thread
+          # Stop reconnect thread now so it cannot keep running after close.
+          @reconnect_thread.kill
+          @reconnect_thread.join(0.1)
+        end
+        super
+      end
+
+      def on_reconnect(&block)
+        logger.debug "Registering FreeSWITCH ESL client reconnect handler"
+        @reconnect_handlers << block
+        self
+      end
+
+      private
+
+      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"
+      end
+
+      def build_socket
+        socket = TCPSocket.new(config.freeswitch.host, config.freeswitch.port)
+        socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+        socket
+      end
+
+      def authenticate_with_config!
+        authenticate!(config.freeswitch.password, timeout: config.freeswitch.timeout)
+      end
+
+      def on_disconnect(error)
+        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
+        @reconnect_thread = Thread.new do
+          reconnect_with_backoff
+        end
+        @reconnect_thread.name = "esl-reconnect"
+      end
+
+      def reconnect_with_backoff
+        retries = 0
+        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
+
+          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
+
+      def reconnect_once
+        establish_connection
+        @reconnect_handlers.each(&:call)
+        true
+      rescue StandardError => e
+        # Return false so the outer loop can try again.
+        logger.warn "Reconnect attempt failed: #{e.message}"
+        false
+      end
+
+      def stop_reconnect?(retries)
+        retries >= config.freeswitch.max_retries || @intentionally_closed
+      end
+    end
+  end
+end

data/lib/freeswitch/esl/configuration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "configatron"
+
+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
+
+      class << self
+        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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Freeswitch
+  module ESL
+    class Connection
+      # Manages event dispatching from a queue to registered handlers.
+      # Runs in a dedicated thread and handles both event handlers and bgapi callbacks.
+      class EventDispatcher
+        def initialize
+          @event_queue = Queue.new
+          @event_handlers = Hash.new { |h, k| h[k] = [] }
+          @bgapi_handlers = {}
+          @bgapi_mutex = Mutex.new
+          @handlers_mutex = Mutex.new
+          @dispatcher_thread = nil
+        end
+
+        # Enqueue an event for async dispatch.
+        def enqueue_event(event)
+          @event_queue << event
+        end
+
+        # Register a handler block for an event name.
+        # Use "ALL" to handle every event. Multiple handlers per event are supported.
+        # Returns self for chaining.
+        def on(event_name, &block)
+          @handlers_mutex.synchronize do
+            @event_handlers[event_name.to_s.upcase] << block
+          end
+          self
+        end
+
+        # Register a handler for a background job result (by job UUID).
+        def register_bgapi_handler(job_uuid, block)
+          @bgapi_mutex.synchronize { @bgapi_handlers[job_uuid] = block }
+        end
+
+        # Start the dispatcher thread.
+        def start
+          return if @dispatcher_thread
+
+          @dispatcher_thread = Thread.new do
+            loop do
+              event = @event_queue.pop
+              break if event.nil? # Queue closed (Ruby 3.x returns nil on closed empty queue)
+
+              dispatch(event)
+            end
+          end
+          @dispatcher_thread.name = "esl-dispatcher"
+          @dispatcher_thread.abort_on_exception = false
+        end
+
+        # Stop the dispatcher thread (close queue and join).
+        def stop
+          @event_queue&.close
+          @dispatcher_thread&.join
+        end
+
+        private
+
+        def dispatch(event)
+          handle_bgapi_result(event) if event.name == "BACKGROUND_JOB"
+
+          handlers = @handlers_mutex.synchronize do
+            # Copy handlers before looping, so handlers can update registration
+            # without changing the list we are reading now.
+            (@event_handlers[event.name.to_s] + @event_handlers["ALL"]).dup
+          end
+
+          handlers.each do |handler|
+            handler.call(event)
+          rescue StandardError
+            nil # never crash the dispatcher thread
+          end
+        end
+
+        def handle_bgapi_result(event)
+          job_uuid = event.job_uuid
+          return unless job_uuid
+
+          # A bgapi handler should run once, so remove it on first match.
+          handler = @bgapi_mutex.synchronize { @bgapi_handlers.delete(job_uuid) }
+          handler&.call(event)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# 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

data/lib/freeswitch/esl/connection.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+require "freeswitch/esl/protocol/event"
+require "freeswitch/esl/protocol/message"
+require "freeswitch/esl/connection/message_reader"
+require "freeswitch/esl/connection/event_dispatcher"
+
+module Freeswitch
+  module ESL
+    # Base ESL connection that handles the wire protocol.
+    #
+    # Subclasses are responsible for providing an open +socket+ and calling
+    # {#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 *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.
+    class Connection
+      MSG_TERMINATOR = "\n\n"
+      DEFAULT_TIMEOUT = 5
+
+      def initialize(socket)
+        initialize_socket(socket)
+      end
+
+      # Send a raw ESL command and return the {Message} reply.
+      def send_command(command, timeout: DEFAULT_TIMEOUT)
+        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
+      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
+
+        @event_dispatcher.register_bgapi_handler(job_uuid, block) if block && job_uuid
+        job_uuid
+      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}")
+      end
+
+      # Cancel subscriptions.  Without arguments cancels all events.
+      def unsubscribe(*event_names)
+        if event_names.empty?
+          send_command("noevents")
+        else
+          event_names.each { |e| send_command("nixevent #{e}") }
+        end
+      end
+
+      # Add an event-header filter so FreeSWITCH only sends matching events.
+      def filter(header, value)
+        send_command("filter #{header} #{value}")
+      end
+
+      # Register a handler block for an event name.  Use +"ALL"+ to handle
+      # every event.  Multiple handlers per event name are supported.
+      # Returns +self+ for chaining.
+      def on(event_name, &)
+        @event_dispatcher.on(event_name, &)
+        self
+      end
+
+      def closed?
+        @closed
+      end
+
+      def close
+        return if @closed
+
+        @closed = true
+        begin
+          @socket.close
+        rescue StandardError
+          nil
+        end
+        @message_reader&.stop
+        @event_dispatcher&.stop
+      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
+
+        # Keep dispatcher data across reconnects so existing handlers still work
+        # after a new socket is created.
+        unless instance_variable_defined?(:@event_dispatcher)
+          @event_dispatcher = EventDispatcher.new
+          @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}"
+      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
+      end
+
+      private
+
+      # Called by MessageReader when socket is disconnected or closed.
+      def on_disconnect(_error)
+        @closed = true
+      end
+    end
+  end
+end

data/lib/freeswitch/esl/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Freeswitch
+  module ESL
+    class Error < StandardError; end
+
+    class AuthenticationError < Error; end
+
+    class CommandError < Error; end
+
+    class ConnectionError < Error; end
+
+    class TimeoutError < Error; end
+
+    class DisconnectedError < Error; end
+  end
+end

data/lib/freeswitch/esl/logger.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Freeswitch
+  module ESL
+    # Shared logger helpers for ESL classes.
+    module Logger
+      def self.default_logger
+        ::Logger.new(IO::NULL)
+      end
+
+      def logger
+        return @logger if defined?(@logger) && @logger
+
+        @logger = Freeswitch::ESL.configuration.logger
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Freeswitch
+  module ESL
+    module Protocol
+      # Represents a FreeSWITCH event received in JSON format.
+      class Event
+        attr_reader :data
+
+        def initialize(raw_json)
+          @data = JSON.parse(raw_json).freeze
+        end
+
+        def [](key)
+          data[key]
+        end
+
+        def name
+          data["Event-Name"]
+        end
+
+        def subclass
+          data["Event-Subclass"]
+        end
+
+        def uuid
+          data["Unique-ID"]
+        end
+
+        def job_uuid
+          data["Job-UUID"]
+        end
+
+        def body
+          data["_body"]
+        end
+
+        def channel_variable(name)
+          data["variable_#{name}"]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Freeswitch
+  module ESL
+    module Protocol
+      # Represents a raw ESL protocol message (headers + optional body).
+      class Message
+        attr_reader :headers, :body
+
+        def initialize(headers, body = nil)
+          @headers = headers.freeze
+          @body = body&.freeze
+        end
+
+        def [](key)
+          headers[key]
+        end
+
+        def content_type
+          headers["Content-Type"]
+        end
+
+        def reply_text
+          headers["Reply-Text"]
+        end
+
+        def successful?
+          if content_type == "api/response"
+            body&.start_with?("+OK")
+          else
+            reply_text&.start_with?("+OK")
+          end
+        end
+
+        def error_message
+          text = content_type == "api/response" ? body : reply_text
+          text&.start_with?("-ERR") ? text.sub(/\A-ERR\s*/, "").strip : nil
+        end
+      end
+    end
+  end
+end

data/lib/freeswitch/esl/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Freeswitch
+  module ESL
+    VERSION = "0.1.0"
+  end
+end

data/lib/freeswitch/esl.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "logger"
+
+require "freeswitch/esl/version"
+require "freeswitch/esl/errors"
+require "freeswitch/esl/logger"
+require "freeswitch/esl/configuration"
+require "freeswitch/esl/protocol/message"
+require "freeswitch/esl/protocol/event"
+require "freeswitch/esl/connection"
+require "freeswitch/esl/client"
+
+module Freeswitch
+  module ESL
+    Message = Protocol::Message
+    Event = Protocol::Event
+
+    class << self
+      def configure
+        yield(configuration)
+      end
+
+      def configuration
+        @configuration ||= Configuration.build
+      end
+
+      def reset!
+        @configuration = nil
+      end
+    end
+  end
+end

data/lib/freeswitch-esl.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "freeswitch/esl"

metadata

@@ -0,0 +1,144 @@
+--- !ruby/object:Gem::Specification
+name: freeswitch-esl
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Demetra Opinioni.net Srl
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-06-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: configatron
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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.
+email:
+- developers@opinioni.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/freeswitch-esl.rb
+- lib/freeswitch/esl.rb
+- lib/freeswitch/esl/client.rb
+- lib/freeswitch/esl/configuration.rb
+- lib/freeswitch/esl/connection.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
+- lib/freeswitch/esl/protocol/message.rb
+- lib/freeswitch/esl/version.rb
+homepage: https://gitlab.opinioni.net/demetra-opinioni/rubygems/freeswitch-esl
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key: 
+specification_version: 4
+summary: Ruby client for FreeSWITCH Event Socket Library (ESL)
+test_files: []