ruby-asterisk 0.2.0 → 1.0.0

data/lib/ruby-asterisk/ari/client.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require 'ruby-asterisk/ari/resources/base'
+require 'ruby-asterisk/ari/resources/channel'
+require 'ruby-asterisk/ari/resources/bridge'
+require 'ruby-asterisk/ari/resources/playback'
+require 'ruby-asterisk/ari/resources/endpoint'
+require 'ruby-asterisk/ari/resources/collection'
+
+module RubyAsterisk
+  module ARI
+    # HTTP client for the Asterisk REST Interface (ARI).
+    # Wraps Faraday to provide authenticated GET, POST, and DELETE requests
+    # and maps HTTP error responses to RubyAsterisk::Error exceptions.
+    class Client
+      attr_reader :base_url, :app_name
+
+      def initialize(base_url, api_key, app_name)
+        @base_url = base_url
+        @api_key = api_key
+        @app_name = app_name
+        # ARI credentials may be supplied as "user:password" (the standard
+        # api_key form). Split on the first colon; a bare key means empty password.
+        user, pass = api_key.to_s.split(':', 2)
+        pass ||= ''
+        @connection = Faraday.new(url: base_url) do |conn|
+          conn.request :authorization, :basic, user, pass
+          conn.headers['Content-Type'] = 'application/json'
+          conn.headers['Accept'] = 'application/json'
+        end
+      end
+
+      def get(path, params = {})
+        response = @connection.get(path, params)
+        handle_response(response)
+      end
+
+      def post(path, body = {})
+        response = @connection.post(path, body.to_json)
+        handle_response(response)
+      end
+
+      def delete(path, params = {})
+        response = @connection.delete(path, params)
+        handle_response(response)
+      end
+
+      def asterisk_info
+        get('/ari/asterisk/info')
+      end
+
+      def channels
+        Resources::Collection.new(Resources::Channel, '/ari/channels', self)
+      end
+
+      def bridges
+        Resources::Collection.new(Resources::Bridge, '/ari/bridges', self)
+      end
+
+      def playbacks
+        Resources::Collection.new(Resources::Playback, '/ari/playbacks', self)
+      end
+
+      def endpoints
+        Resources::Collection.new(Resources::Endpoint, '/ari/endpoints', self)
+      end
+
+      private
+
+      def handle_response(response)
+        raise Error, error_message(response) if response.status >= 400
+
+        parse_body(response.body)
+      end
+
+      def error_message(response)
+        parsed = parse_body(response.body)
+        parsed.is_a?(Hash) ? parsed['message'] || response.reason_phrase : response.reason_phrase
+      rescue StandardError
+        response.reason_phrase
+      end
+
+      def parse_body(body)
+        return nil if body.nil? || body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        body
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ari/resources/base.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module ARI
+    module Resources
+      # Base class providing shared data access for ARI resource objects.
+      # Subclasses receive raw JSON data and a client reference, then expose
+      # domain-specific action methods that delegate HTTP calls to the client.
+      class Base
+        attr_reader :data, :client
+
+        def initialize(data, client)
+          @data = data
+          @client = client
+        end
+
+        def id
+          data['id']
+        end
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ari/resources/bridge.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module ARI
+    module Resources
+      # Represents an ARI Bridge resource with channel-mixing action methods.
+      class Bridge < Base
+        def add_channel(channel_id)
+          client.post("/ari/bridges/#{id}/addChannel", { channel: channel_id })
+        end
+
+        def remove_channel(channel_id)
+          client.post("/ari/bridges/#{id}/removeChannel", { channel: channel_id })
+        end
+
+        def destroy
+          client.delete("/ari/bridges/#{id}")
+        end
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ari/resources/channel.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module ARI
+    module Resources
+      # Represents an ARI Channel resource with call-control action methods.
+      class Channel < Base
+        def ring
+          client.post("/ari/channels/#{id}/ring")
+        end
+
+        def answer
+          client.post("/ari/channels/#{id}/answer")
+        end
+
+        def hangup
+          client.delete("/ari/channels/#{id}")
+        end
+
+        def play(media, params = {})
+          client.post("/ari/channels/#{id}/play", { media: media }.merge(params))
+        end
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ari/resources/collection.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module ARI
+    module Resources
+      # Provides a typed collection interface for fetching ARI resources.
+      # Enables the Active Record-style pattern: client.channels.get(id).
+      class Collection
+        def initialize(resource_class, base_path, client)
+          @resource_class = resource_class
+          @base_path = base_path
+          @client = client
+        end
+
+        def get(id)
+          data = @client.get("#{@base_path}/#{id}")
+          @resource_class.new(data, @client)
+        end
+
+        def list(params = {})
+          data = @client.get(@base_path, params)
+          (data || []).map { |item| @resource_class.new(item, @client) }
+        end
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ari/resources/endpoint.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module ARI
+    module Resources
+      # Represents an ARI Endpoint resource (a SIP/PJSIP/DAHDI endpoint).
+      class Endpoint < Base
+        def technology
+          data['technology']
+        end
+
+        def resource
+          data['resource']
+        end
+
+        def state
+          data['state']
+        end
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ari/resources/playback.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module ARI
+    module Resources
+      # Represents an ARI Playback resource with media-control action methods.
+      class Playback < Base
+        def stop
+          client.delete("/ari/playbacks/#{id}")
+        end
+
+        def control(operation)
+          client.post("/ari/playbacks/#{id}/control", { operation: operation })
+        end
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ari/websocket/connection.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module ARI
+    class WebSocket
+      # Connection management for ARI WebSocket
+      module Connection
+        private
+
+        # Build the WebSocket URL
+        #
+        # @return [String]
+        def build_url
+          uri = URI.parse(@base_url)
+          ws_scheme = uri.scheme == 'https' ? 'wss' : 'ws'
+          user, pass = @api_key.to_s.split(':', 2)
+          auth = "#{encode_userinfo(user)}:#{encode_userinfo(pass)}@"
+          app = URI.encode_www_form_component(@app_name)
+
+          "#{ws_scheme}://#{auth}#{uri.host}:#{uri.port}/ari/events?app=#{app}"
+        end
+
+        # URL-encode a userinfo component (user or password), leaving nil as ''
+        def encode_userinfo(component)
+          URI::DEFAULT_PARSER.escape(component.to_s, /[^A-Za-z0-9\-._~]/)
+        end
+
+        # Run a single connection: establish it and read until it drops.
+        def run_connection
+          establish_connection
+        rescue StandardError => e
+          @logger.error "Failed to establish connection: #{e.message}"
+        else
+          read_loop
+        ensure
+          cleanup_connection
+        end
+
+        # Establish WebSocket connection
+        def establish_connection
+          @logger.info "Connecting to ARI WebSocket: app=#{@app_name}"
+
+          @socket = open_socket(URI.parse(@base_url))
+          @driver = ::WebSocket::Driver.client(SocketAdapter.new(build_url, @socket))
+
+          setup_event_handlers
+          @driver.start
+        end
+
+        # Open a TCP socket, wrapped in TLS when the base URL is https
+        def open_socket(uri)
+          tcp = TCPSocket.new(uri.host, uri.port)
+          tcp.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+          tcp.setsockopt(Socket::SOL_SOCKET, Socket::SO_KEEPALIVE, true)
+          return tcp unless uri.scheme == 'https'
+
+          context = OpenSSL::SSL::SSLContext.new
+          context.set_params
+          ssl = OpenSSL::SSL::SSLSocket.new(tcp, context)
+          ssl.hostname = uri.host
+          ssl.sync_close = true
+          ssl.connect
+          ssl
+        end
+
+        # Setup WebSocket event handlers
+        def setup_event_handlers
+          @driver.on(:open) { |_event| handle_open }
+          @driver.on(:message) { |event| handle_message(event) }
+          @driver.on(:close) { |event| handle_close(event) }
+          @driver.on(:error) { |event| handle_error(event) }
+        end
+
+        # Feed incoming bytes to the driver until the socket closes.
+        #
+        # driver.parse dispatches :open/:message synchronously (under
+        # @driver_monitor); handlers only enqueue closures via #defer so user
+        # callbacks run here, after the monitor is released.
+        def read_loop
+          loop do
+            chunk = @socket.readpartial(4096)
+            pending = []
+            @driver_monitor.synchronize do
+              @pending_dispatch = pending
+              begin
+                @driver.parse(chunk)
+              ensure
+                @pending_dispatch = nil
+              end
+            end
+            dispatch_pending(pending)
+          end
+        rescue IOError, SystemCallError
+          handle_connection_lost
+        end
+
+        # Run deferred callbacks, containing any exception so it never kills the loop.
+        def dispatch_pending(callbacks)
+          callbacks.each do |callback|
+            callback.call
+          rescue StandardError => e
+            @logger.error "Error dispatching WebSocket event: #{e.message}"
+          end
+        end
+
+        # Enqueue a closure to run after the driver monitor is released. When
+        # invoked outside an active parse (no dispatch buffer), run immediately.
+        def defer(&block)
+          if @pending_dispatch
+            @pending_dispatch << block
+          else
+            yield
+          end
+        end
+
+        # Release per-connection resources after the read loop exits
+        def cleanup_connection
+          stop_ping_timer
+          close_socket
+          @driver = nil
+          @socket = nil
+          @connected = false
+        end
+
+        # Send a close frame (if the connection is open) and close the socket
+        def close_connection
+          driver = @driver
+          @driver_monitor.synchronize { driver.close } if driver && driver.state == :open
+        rescue StandardError
+          nil
+        ensure
+          close_socket
+        end
+
+        def close_socket
+          @socket&.close
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ari/websocket/event_handlers.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module ARI
+    class WebSocket
+      # Event handling for ARI WebSocket
+      module EventHandlers
+        private
+
+        # Handle WebSocket open event
+        def handle_open
+          @connected = true
+          @reconnect_attempts = 0
+          @awaiting_pong = false
+          @logger.info 'WebSocket connected successfully'
+
+          start_ping_timer
+          # Runs after the driver monitor is released (see Connection#read_loop).
+          defer { @on_connect_callback&.call(self) }
+        end
+
+        # Handle incoming WebSocket message
+        #
+        # @param event [WebSocket::Driver::MessageEvent]
+        def handle_message(event)
+          data = JSON.parse(event.data)
+          event_type = data['type']
+
+          @logger.debug "Received event: #{event_type}"
+
+          # Dispatch to registered callbacks after the driver monitor is released
+          # (see Connection#read_loop) so user handlers never run under the monitor.
+          defer { dispatch_event(event_type, data) }
+        rescue JSON::ParserError => e
+          @logger.error "Failed to parse message: #{e.message}"
+        end
+
+        # Handle WebSocket close event. Reconnection is handled by the
+        # connection thread once the read loop unblocks.
+        #
+        # @param event [WebSocket::Driver::CloseEvent]
+        def handle_close(event)
+          @connected = false
+          stop_ping_timer
+
+          @logger.warn "WebSocket closed: code=#{event.code}, reason=#{event.reason}"
+
+          close_socket
+        end
+
+        # Handle WebSocket error event
+        #
+        # @param event [WebSocket::Driver::ProtocolError]
+        def handle_error(event)
+          @logger.error "WebSocket error: #{event.message}"
+        end
+
+        # Dispatch event to registered callbacks
+        #
+        # @param event_type [String] Event type
+        # @param data [Hash] Event data
+        def dispatch_event(event_type, data)
+          # Call specific event handlers
+          @callbacks[event_type]&.each do |callback|
+            callback.call(data)
+          rescue StandardError => e
+            @logger.error "Error in event handler for #{event_type}: #{e.message}"
+          end
+
+          # Call wildcard handlers (if registered with '*')
+          @callbacks['*']&.each do |callback|
+            callback.call(data)
+          rescue StandardError => e
+            @logger.error "Error in wildcard event handler: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ari/websocket/heartbeat.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module ARI
+    class WebSocket
+      # Ping keep-alive timer and interruptible waits for ARI WebSocket
+      module Heartbeat
+        private
+
+        # Start the ping timer to keep connection alive
+        def start_ping_timer
+          stop_ping_timer
+
+          token = @ping_token = Object.new
+          @ping_thread = Thread.new { ping_loop(token) }
+        end
+
+        # Send a ping every @ping_interval seconds until the token is revoked.
+        # If the previous ping was never answered by a pong, treat the connection
+        # as dead (half-open) and close the socket so the read loop unblocks and
+        # auto-reconnect can take over.
+        def ping_loop(token)
+          loop do
+            wait_or_wake(@ping_interval)
+            break unless token.equal?(@ping_token)
+            next unless connected?
+
+            if @awaiting_pong
+              @logger.warn 'No pong received within ping interval; closing dead connection'
+              close_socket
+              break
+            end
+
+            @awaiting_pong = true
+            @logger.debug 'Sending ping'
+            send_ping
+          end
+        end
+
+        def send_ping
+          driver = @driver
+          @driver_monitor.synchronize { driver&.ping('') { @awaiting_pong = false } }
+        rescue IOError, SystemCallError
+          nil
+        end
+
+        # Stop the ping timer
+        def stop_ping_timer
+          @ping_token = nil
+          @ping_thread = nil
+          wake_sleepers
+        end
+
+        # Interruptible sleep: returns early when wake_sleepers is called
+        def wait_or_wake(seconds)
+          @wake_mutex.synchronize { @wake_cv.wait(@wake_mutex, seconds) }
+        end
+
+        def wake_sleepers
+          @wake_mutex.synchronize { @wake_cv.broadcast }
+        end
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ari/websocket/reconnect.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module ARI
+    class WebSocket
+      # Reconnection lifecycle for ARI WebSocket: the connection-thread loop and
+      # the exponential backoff between attempts.
+      module Reconnect
+        private
+
+        # Main loop of the connection thread: connect, read until the
+        # connection drops, then reconnect while auto-reconnect is enabled.
+        def connection_loop
+          loop do
+            run_connection
+            break unless @should_reconnect
+            break unless wait_before_reconnect
+          end
+        end
+
+        # The socket dropped without a WebSocket close frame
+        def handle_connection_lost
+          return unless @connected
+
+          @connected = false
+          stop_ping_timer
+          @logger.warn 'WebSocket connection lost'
+        end
+
+        # Wait before the next reconnection attempt.
+        #
+        # @return [Boolean] false when reconnection must stop
+        def wait_before_reconnect
+          if MAX_RECONNECT_ATTEMPTS && @reconnect_attempts >= MAX_RECONNECT_ATTEMPTS
+            @logger.error 'Max reconnection attempts reached, giving up'
+            return false
+          end
+
+          @reconnect_attempts += 1
+          delay = reconnect_backoff_delay
+          @logger.info "Scheduling reconnection attempt #{@reconnect_attempts} in #{delay} seconds"
+
+          wait_or_wake(delay)
+          @should_reconnect
+        end
+
+        # Exponential backoff capped at MAX_RECONNECT_DELAY
+        def reconnect_backoff_delay
+          [@reconnect_delay * (2**(@reconnect_attempts - 1)), MAX_RECONNECT_DELAY].min
+        end
+      end
+    end
+  end
+end

data/lib/ruby-asterisk/ari/websocket/socket_adapter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RubyAsterisk
+  module ARI
+    class WebSocket
+      # Minimal socket wrapper handed to WebSocket::Driver.client: the driver
+      # reads #url to build the handshake request (including Basic auth from
+      # the URL userinfo) and calls #write to emit outgoing bytes.
+      class SocketAdapter
+        attr_reader :url
+
+        def initialize(url, io)
+          @url = url
+          @io = io
+        end
+
+        def write(data)
+          @io.write(data)
+        end
+      end
+    end
+  end
+end