rble 0.7.0

data/lib/rble/bluez/async_connection_operations.rb

@@ -0,0 +1,492 @@
+# frozen_string_literal: true
+
+require 'dbus'
+require_relative 'async_call'
+require_relative 'async_introspection'
+
+module RBLE
+  module BlueZ
+    # Provides async connection operations using AsyncCall + AsyncIntrospection patterns.
+    # Use this to perform device connection lifecycle operations without blocking the event loop.
+    #
+    # This module is part of the v0.4.0 async architecture. It builds on AsyncCall
+    # and AsyncIntrospection to provide non-blocking connection operations.
+    #
+    # Including class must:
+    # - Include AsyncCall module (provides async_call method)
+    # - Include AsyncIntrospection module (provides async_introspect method)
+    # - Have @service attribute pointing to D-Bus service
+    #
+    # @example
+    #   include AsyncCall
+    #   include AsyncIntrospection
+    #   include AsyncConnectionOperations
+    #
+    #   async_connect("/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF")
+    #   async_disconnect("/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF")
+    #   async_start_discovery("/org/bluez/hci0", filter: { transport: 'le' })
+    #   async_stop_discovery("/org/bluez/hci0")
+    #   value = async_get_property("/org/bluez/hci0", "org.bluez.Adapter1", "Powered")
+    #   async_set_property("/org/bluez/hci0", "org.bluez.Adapter1", "Powered", true)
+    #
+    module AsyncConnectionOperations
+      DEVICE_INTERFACE = 'org.bluez.Device1'
+      ADAPTER_INTERFACE = 'org.bluez.Adapter1'
+      PROPERTIES_INTERFACE = 'org.freedesktop.DBus.Properties'
+
+      # Timeouts from CONTEXT.md
+      DEFAULT_CONNECT_TIMEOUT = 30
+      DEFAULT_DISCONNECT_TIMEOUT = 5
+      DEFAULT_DISCOVERY_TIMEOUT = 10
+      DEFAULT_PROPERTY_TIMEOUT = 5
+
+      # Delay after ServicesResolved to allow BlueZ to fully export GATT services to D-Bus.
+      # BlueZ signals ServicesResolved=true slightly before all service/characteristic
+      # objects are available via GetManagedObjects. This delay prevents race conditions.
+      SERVICES_RESOLVED_DELAY = 0.15
+
+      # Async connect to a BLE device
+      #
+      # @param device_path [String] D-Bus device path
+      # @param wait_for_services [Boolean] Wait for GATT services to be discovered (default: true)
+      # @param timeout [Numeric] Total timeout in seconds for the entire connection process (default: 30)
+      # @return [Boolean] true on success
+      # @raise [TimeoutError] if connection times out
+      # @raise [ConnectionFailed] if connection fails
+      # @raise [AdapterNotFoundError] if adapter not ready
+      def async_connect(device_path, wait_for_services: true, timeout: DEFAULT_CONNECT_TIMEOUT)
+        address = extract_address_from_path(device_path)
+        deadline = Time.now + timeout
+        warn "      [RBLE] async_connect timeout=#{timeout}s deadline=#{deadline.strftime('%H:%M:%S')}" if RBLE.trace
+
+        proxy = async_introspect(device_path, timeout: remaining_timeout(deadline, timeout))
+        device_iface = proxy[DEVICE_INTERFACE]
+        props_iface = proxy[PROPERTIES_INTERFACE]
+
+        # Idempotent: check if already connected (use async to avoid deadlock)
+        connected = async_get_property(device_path, DEVICE_INTERFACE, 'Connected', timeout: remaining_timeout(deadline, timeout))
+        if connected
+          # If waiting for services and not resolved, wait
+          if wait_for_services
+            services_resolved = async_get_property(device_path, DEVICE_INTERFACE, 'ServicesResolved', timeout: remaining_timeout(deadline, timeout))
+            unless services_resolved
+              wait_for_services_resolved(props_iface, timeout: remaining_timeout(deadline, timeout))
+              # Delay to allow BlueZ to fully export GATT services to D-Bus
+              sleep(SERVICES_RESOLVED_DELAY)
+            end
+          end
+          return true
+        end
+
+        # Setup ServicesResolved watcher BEFORE calling Connect (avoid race per RESEARCH.md)
+        # Use async signal registration to avoid deadlock with running event loop
+        services_queue = nil
+        if wait_for_services
+          services_queue = Thread::Queue.new
+          async_register_signal_handler(props_iface, 'PropertiesChanged') do |interface, changed, _invalidated|
+            next unless interface == DEVICE_INTERFACE
+            if changed.key?('ServicesResolved') && changed['ServicesResolved'] == true
+              services_queue.push(true)
+            end
+          end
+        end
+
+        begin
+          # Call Connect asynchronously
+          connect_timeout = remaining_timeout(deadline, timeout)
+          async_call("Connect(#{address})", timeout: connect_timeout) do |queue, _request_id, cancelled|
+            device_iface.Connect do |reply|
+              next if cancelled[0]  # Discard late callback
+              if reply.is_a?(DBus::Error)
+                queue.push([reply, nil])
+              else
+                queue.push([nil, :ok])
+              end
+            end
+          end
+
+          # Wait for ServicesResolved if requested
+          if wait_for_services && services_queue
+            # Check if already resolved (race condition protection)
+            # Use async_get_property to avoid deadlock
+            services_resolved = async_get_property(device_path, DEVICE_INTERFACE, 'ServicesResolved', timeout: remaining_timeout(deadline, timeout))
+            unless services_resolved
+              services_timeout = remaining_timeout(deadline, timeout)
+              result = services_queue.pop(timeout: services_timeout)
+              raise TimeoutError.new('ServicesResolved', timeout) if result.nil?
+            end
+            # Delay to allow BlueZ to fully export GATT services to D-Bus
+            sleep(SERVICES_RESOLVED_DELAY)
+          end
+
+          true
+        ensure
+          # Unsubscribe signal handler asynchronously (safe while event loop runs)
+          async_unregister_signal_handler(props_iface, 'PropertiesChanged') if wait_for_services
+        end
+      rescue DBus::Error => e
+        translate_connection_error(e, device_path)
+      end
+
+      # Async disconnect from a BLE device
+      #
+      # @param device_path [String] D-Bus device path
+      # @param timeout [Numeric] Total timeout in seconds for the entire disconnect operation (default: 5)
+      # @return [Boolean] true on success
+      # @raise [TimeoutError] if disconnect times out
+      def async_disconnect(device_path, timeout: DEFAULT_DISCONNECT_TIMEOUT)
+        address = extract_address_from_path(device_path)
+        deadline = Time.now + timeout
+
+        proxy = async_introspect(device_path, timeout: remaining_timeout(deadline, timeout, 'Disconnect'))
+        device_iface = proxy[DEVICE_INTERFACE]
+
+        # Idempotent: check if not connected (use async to avoid deadlock)
+        connected = async_get_property(device_path, DEVICE_INTERFACE, 'Connected', timeout: remaining_timeout(deadline, timeout, 'Disconnect'))
+        return true unless connected
+
+        async_call("Disconnect(#{address})", timeout: remaining_timeout(deadline, timeout, 'Disconnect')) do |queue, _request_id, cancelled|
+          device_iface.Disconnect do |reply|
+            next if cancelled[0]  # Discard late callback
+            if reply.is_a?(DBus::Error)
+              queue.push([reply, nil])
+            else
+              queue.push([nil, :ok])
+            end
+          end
+        end
+
+        true
+      rescue DBus::Error => e
+        translate_connection_error(e, device_path)
+      end
+
+      # Async start discovery on an adapter
+      #
+      # @param adapter_path [String] D-Bus adapter path
+      # @param filter [Hash] Discovery filter options
+      # @option filter [String] :transport Transport type ('auto', 'bredr', 'le')
+      # @option filter [Array<String>] :uuids Service UUIDs to filter
+      # @option filter [Integer] :rssi Minimum RSSI value
+      # @option filter [Integer] :pathloss Maximum path loss
+      # @option filter [Boolean] :duplicate_data Report duplicate advertisements
+      # @param timeout [Numeric] Total timeout in seconds for the entire operation (default: 10)
+      # @return [Boolean] true on success
+      # @raise [TimeoutError] if operation times out
+      # @raise [ScanError] if discovery fails
+      # @raise [AdapterNotFoundError] if adapter not ready
+      def async_start_discovery(adapter_path, filter: {}, timeout: DEFAULT_DISCOVERY_TIMEOUT)
+        deadline = Time.now + timeout
+
+        proxy = async_introspect(adapter_path, timeout: remaining_timeout(deadline, timeout, 'StartDiscovery'))
+        adapter_iface = proxy[ADAPTER_INTERFACE]
+
+        # Idempotent: check if already discovering (use async to avoid deadlock)
+        discovering = async_get_property(adapter_path, ADAPTER_INTERFACE, 'Discovering', timeout: remaining_timeout(deadline, timeout, 'StartDiscovery'))
+        return true if discovering
+
+        # Set discovery filter first if any options provided
+        unless filter.empty?
+          async_set_discovery_filter(adapter_path, adapter_iface, filter, timeout: remaining_timeout(deadline, timeout, 'StartDiscovery'))
+        end
+
+        async_call("StartDiscovery(#{adapter_path})", timeout: remaining_timeout(deadline, timeout, 'StartDiscovery')) do |queue, _request_id, cancelled|
+          adapter_iface.StartDiscovery do |reply|
+            next if cancelled[0]  # Discard late callback
+            if reply.is_a?(DBus::Error)
+              queue.push([reply, nil])
+            else
+              queue.push([nil, :ok])
+            end
+          end
+        end
+
+        true
+      rescue DBus::Error => e
+        # Idempotent: "InProgress" means discovery already started (race condition)
+        # This can happen if another process starts discovery between our check and the call
+        return true if e.name == 'org.bluez.Error.InProgress'
+
+        translate_discovery_error(e, adapter_path)
+      end
+
+      # Async stop discovery on an adapter
+      #
+      # @param adapter_path [String] D-Bus adapter path
+      # @param timeout [Numeric] Total timeout in seconds for the entire operation (default: 10)
+      # @return [Boolean] true on success
+      # @raise [TimeoutError] if operation times out
+      def async_stop_discovery(adapter_path, timeout: DEFAULT_DISCOVERY_TIMEOUT)
+        deadline = Time.now + timeout
+
+        proxy = async_introspect(adapter_path, timeout: remaining_timeout(deadline, timeout, 'StopDiscovery'))
+        adapter_iface = proxy[ADAPTER_INTERFACE]
+
+        # Idempotent: check if not discovering (use async to avoid deadlock)
+        discovering = async_get_property(adapter_path, ADAPTER_INTERFACE, 'Discovering', timeout: remaining_timeout(deadline, timeout, 'StopDiscovery'))
+        return true unless discovering
+
+        async_call("StopDiscovery(#{adapter_path})", timeout: remaining_timeout(deadline, timeout, 'StopDiscovery')) do |queue, _request_id, cancelled|
+          adapter_iface.StopDiscovery do |reply|
+            next if cancelled[0]  # Discard late callback
+            if reply.is_a?(DBus::Error)
+              queue.push([reply, nil])
+            else
+              queue.push([nil, :ok])
+            end
+          end
+        end
+
+        true
+      rescue DBus::Error => e
+        # Idempotent: "No discovery started" means discovery already stopped (race condition)
+        # This can happen if BlueZ auto-stops discovery between our check and the call
+        return true if e.message.include?('No discovery started')
+
+        translate_discovery_error(e, adapter_path)
+      end
+
+      # Async get any D-Bus property value
+      #
+      # @param object_path [String] D-Bus object path
+      # @param interface [String] D-Bus interface name
+      # @param property [String] Property name
+      # @param timeout [Numeric] Timeout in seconds (default: 5)
+      # @return [Object] Property value (unwrapped from variant)
+      # @raise [TimeoutError] if operation times out
+      def async_get_property(object_path, interface, property, timeout: DEFAULT_PROPERTY_TIMEOUT)
+        proxy = async_introspect(object_path, timeout: timeout)
+        props_iface = proxy[PROPERTIES_INTERFACE]
+
+        # Validate introspection succeeded - Properties interface must have Get method
+        # This can fail if introspection returned truncated/corrupt XML
+        # Note: Don't call refresh_introspection here as it can invalidate proxies
+        # that other code is using (e.g., async_start_notify gets char_iface before
+        # calling async_get_property for Flags check)
+        unless props_iface.respond_to?(:Get)
+          raise RBLE::Error, "Introspection incomplete for #{object_path}: Properties interface has no Get method. " \
+                             "This may indicate corrupted D-Bus introspection data."
+        end
+
+        result = async_call("Get(#{interface}.#{property})", timeout: timeout) do |queue, _request_id, cancelled|
+          props_iface.Get(interface, property) do |reply|
+            next if cancelled[0]  # Discard late callback
+            if reply.is_a?(DBus::Error)
+              queue.push([reply, nil])
+            else
+              # Extract params from DBus::Message - Get returns [Variant]
+              params = reply.respond_to?(:params) ? reply.params : [reply]
+              queue.push([nil, params.first])
+            end
+          end
+        end
+
+        # D-Bus Properties.Get returns value (already extracted from params)
+        result
+      rescue DBus::Error => e
+        raise TimeoutError.new("Get #{interface}.#{property}", timeout) if e.message.include?('timeout')
+        raise e
+      end
+
+      # Async set any writable D-Bus property
+      #
+      # @param object_path [String] D-Bus object path
+      # @param interface [String] D-Bus interface name
+      # @param property [String] Property name
+      # @param value [Object] Value to set
+      # @param timeout [Numeric] Timeout in seconds (default: 5)
+      # @return [Boolean] true on success
+      # @raise [TimeoutError] if operation times out
+      def async_set_property(object_path, interface, property, value, timeout: DEFAULT_PROPERTY_TIMEOUT)
+        proxy = async_introspect(object_path, timeout: timeout)
+        props_iface = proxy[PROPERTIES_INTERFACE]
+
+        # Wrap value in DBus::Data::Variant with inferred type
+        variant_value = create_variant(value)
+
+        async_call("Set(#{interface}.#{property})", timeout: timeout) do |queue, _request_id, cancelled|
+          props_iface.Set(interface, property, variant_value) do |reply|
+            next if cancelled[0]  # Discard late callback
+            if reply.is_a?(DBus::Error)
+              queue.push([reply, nil])
+            else
+              queue.push([nil, :ok])
+            end
+          end
+        end
+
+        true
+      rescue DBus::Error => e
+        raise TimeoutError.new("Set #{interface}.#{property}", timeout) if e.message.include?('timeout')
+        raise e
+      end
+
+      private
+
+      # Calculate remaining timeout from deadline, raising TimeoutError if expired
+      # @param deadline [Time] Absolute deadline
+      # @param original_timeout [Numeric] Original timeout for error message
+      # @return [Numeric] Remaining seconds (minimum 0.1 to allow one more attempt)
+      # @raise [TimeoutError] if deadline has passed
+      def remaining_timeout(deadline, original_timeout, operation = 'Connect')
+        remaining = deadline - Time.now
+        raise TimeoutError.new(operation, original_timeout) if remaining <= 0
+        [remaining, 0.1].max
+      end
+
+      # Wait for ServicesResolved property to become true
+      def wait_for_services_resolved(props_iface, timeout:)
+        queue = Thread::Queue.new
+
+        # Use async signal registration to avoid deadlock with running event loop
+        async_register_signal_handler(props_iface, 'PropertiesChanged') do |interface, changed, _invalidated|
+          next unless interface == DEVICE_INTERFACE
+          if changed.key?('ServicesResolved') && changed['ServicesResolved'] == true
+            queue.push(true)
+          end
+        end
+
+        begin
+          result = queue.pop(timeout: timeout)
+          raise TimeoutError.new('ServicesResolved', timeout) if result.nil?
+        ensure
+          async_unregister_signal_handler(props_iface, 'PropertiesChanged')
+        end
+      end
+
+      # Set discovery filter with correct D-Bus variant types
+      def async_set_discovery_filter(adapter_path, adapter_iface, options, timeout:)
+        filter = {}
+
+        # Transport: STRING
+        if options[:transport]
+          filter['Transport'] = DBus::Data::Variant.new(
+            options[:transport].to_s,
+            member_type: DBus::Type::STRING
+          )
+        end
+
+        # UUIDs: Array[STRING]
+        if options[:uuids] && !options[:uuids].empty?
+          filter['UUIDs'] = DBus::Data::Variant.new(
+            options[:uuids],
+            member_type: DBus::Type::Array[DBus::Type::STRING]
+          )
+        end
+
+        # RSSI: INT16
+        if options[:rssi]
+          filter['RSSI'] = DBus::Data::Variant.new(
+            options[:rssi].to_i,
+            member_type: DBus::Type::INT16
+          )
+        end
+
+        # Pathloss: UINT16
+        if options[:pathloss]
+          filter['Pathloss'] = DBus::Data::Variant.new(
+            options[:pathloss].to_i,
+            member_type: DBus::Type::UINT16
+          )
+        end
+
+        # DuplicateData: BOOLEAN
+        if options.key?(:duplicate_data)
+          filter['DuplicateData'] = DBus::Data::Variant.new(
+            !!options[:duplicate_data],
+            member_type: DBus::Type::BOOLEAN
+          )
+        end
+
+        async_call("SetDiscoveryFilter(#{adapter_path})", timeout: timeout) do |queue, _request_id, cancelled|
+          adapter_iface.SetDiscoveryFilter(filter) do |reply|
+            next if cancelled[0]  # Discard late callback
+            if reply.is_a?(DBus::Error)
+              queue.push([reply, nil])
+            else
+              queue.push([nil, :ok])
+            end
+          end
+        end
+      end
+
+      # Create DBus::Data::Variant with inferred type
+      def create_variant(value)
+        type = case value
+               when TrueClass, FalseClass then DBus::Type::BOOLEAN
+               when Integer then DBus::Type::INT32
+               when Float then DBus::Type::DOUBLE
+               when String then DBus::Type::STRING
+               when Array then DBus::Type::Array[DBus::Type::STRING]
+               else DBus::Type::VARIANT
+               end
+
+        DBus::Data::Variant.new(value, member_type: type)
+      end
+
+      # Translate D-Bus errors to RBLE errors for connection operations
+      def translate_connection_error(error, device_path)
+        address = extract_address_from_path(device_path)
+
+        case error.name
+        when 'org.bluez.Error.AlreadyConnected'
+          raise AlreadyConnectedError
+        when 'org.bluez.Error.NotConnected'
+          raise NotConnectedError
+        when 'org.bluez.Error.AuthenticationFailed'
+          raise AuthenticationError.new(address)
+        when 'org.bluez.Error.Failed'
+          # Parse message for more context
+          if error.message.include?('le-connection-abort') ||
+             error.message.include?('Software caused connection abort') ||
+             error.message.include?('br-connection-abort')
+            raise ConnectionAbortedError.new(address, 'connection aborted by stack')
+          elsif error.message.include?('Host is down')
+            raise ConnectionFailed.new(address, 'device not reachable (out of range?)')
+          else
+            raise ConnectionFailed.new(address, error.message)
+          end
+        when 'org.bluez.Error.NotReady'
+          raise AdapterNotReadyError.new
+        when 'org.bluez.Error.InProgress'
+          raise OperationInProgressError.new("connect to #{address}")
+        when 'org.freedesktop.DBus.Error.UnknownObject'
+          raise DeviceNotFoundError.new(address)
+        else
+          raise ConnectionError, "Connection failed: #{error.message} (#{error.name})"
+        end
+      end
+
+      # Translate D-Bus errors to RBLE errors for discovery operations
+      def translate_discovery_error(error, adapter_path)
+        adapter_name = adapter_path.split('/').last
+
+        case error.name
+        when 'org.bluez.Error.NotReady'
+          raise AdapterNotReadyError.new(adapter_name)
+        when 'org.bluez.Error.Failed'
+          raise ScanError, "Discovery failed on #{adapter_name}: #{error.message}"
+        when 'org.bluez.Error.InProgress'
+          raise ScanInProgressError
+        when 'org.bluez.Error.NotAuthorized'
+          raise PermissionError, "Discovery on #{adapter_name}"
+        when 'org.bluez.Error.NotSupported'
+          raise ScanError, "Discovery filter not supported: #{error.message}"
+        else
+          raise ScanError, "Discovery error: #{error.message} (#{error.name})"
+        end
+      end
+
+      # Extract MAC address from device path
+      # Path format: /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF
+      def extract_address_from_path(path)
+        segments = path.split('/')
+        dev_segment = segments.find { |s| s.start_with?('dev_') }
+        return path unless dev_segment
+
+        # Convert dev_AA_BB_CC_DD_EE_FF to AA:BB:CC:DD:EE:FF
+        dev_segment.sub('dev_', '').tr('_', ':')
+      end
+    end
+  end
+end