rble 0.7.0

data/lib/rble/bluez/async_gatt_operations.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require 'dbus'
+require_relative 'async_call'
+require_relative 'async_introspection'
+require_relative 'retry_policy'
+
+module RBLE
+  module BlueZ
+    # Provides async GATT operations using AsyncCall + AsyncIntrospection patterns.
+    # Use this to perform GATT read/write/notify 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 GATT 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 AsyncGattOperations
+    #
+    #   value = async_read_value("/org/bluez/hci0/.../char0011")
+    #   async_write_value("/org/bluez/hci0/.../char0011", [0x01, 0x02])
+    #   async_start_notify("/org/bluez/hci0/.../char0011")
+    #   async_stop_notify("/org/bluez/hci0/.../char0011")
+    #
+    module AsyncGattOperations
+      include RetryPolicy
+      GATT_CHARACTERISTIC_INTERFACE = 'org.bluez.GattCharacteristic1'
+      PROPERTIES_INTERFACE = 'org.freedesktop.DBus.Properties'
+
+      # Default timeouts (Claude's discretion per CONTEXT.md)
+      DEFAULT_READ_TIMEOUT = 5
+      DEFAULT_WRITE_TIMEOUT = 5
+      DEFAULT_NOTIFY_TIMEOUT = 5
+      WRITE_NO_RESPONSE_TIMEOUT = 1
+
+      # Async read characteristic value
+      #
+      # @param char_path [String] D-Bus characteristic path
+      # @param timeout [Numeric] Total timeout in seconds for the entire read operation (default: 5)
+      # @return [String] Binary string (ASCII-8BIT encoding)
+      # @raise [TimeoutError] if read times out
+      # @raise [ReadError] if read fails
+      # @raise [NotConnectedError] if device disconnected
+      # @raise [OperationInProgressError] if retries exhausted
+      def async_read_value(char_path, timeout: DEFAULT_READ_TIMEOUT)
+        uuid = extract_uuid_from_path(char_path)
+        deadline = Time.now + timeout
+
+        proxy = async_introspect(char_path, timeout: gatt_remaining_timeout(deadline, timeout, 'ReadValue'))
+        char_iface = proxy[GATT_CHARACTERISTIC_INTERFACE]
+
+        result = with_inprogress_retry do
+          async_call("ReadValue(#{uuid})", timeout: gatt_remaining_timeout(deadline, timeout, 'ReadValue')) do |queue, _request_id, cancelled|
+            char_iface.ReadValue({}) 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 - ReadValue returns [Array<Byte>]
+                params = reply.respond_to?(:params) ? reply.params : [reply]
+                queue.push([nil, params.first])
+              end
+            end
+          end
+        end
+
+        # Convert D-Bus byte array to binary string
+        bytes = result || []
+        bytes.map(&:to_i).pack('C*')
+      rescue DBus::Error => e
+        translate_gatt_error(e, char_path, 'Read')
+      end
+
+      # Async write characteristic value
+      #
+      # @param char_path [String] D-Bus characteristic path
+      # @param bytes [Array<Integer>] Byte array to write
+      # @param response [Boolean] Wait for write response (default: true)
+      # @param timeout [Numeric] Total timeout in seconds for the entire write operation (default: 5)
+      # @return [Boolean] true on success
+      # @raise [TimeoutError] if write times out
+      # @raise [WriteError] if write fails
+      # @raise [NotConnectedError] if device disconnected
+      # @raise [OperationInProgressError] if retries exhausted
+      def async_write_value(char_path, bytes, response: true, timeout: DEFAULT_WRITE_TIMEOUT)
+        uuid = extract_uuid_from_path(char_path)
+
+        # Write-without-response uses minimal timeout (CONTEXT.md decision)
+        effective_timeout = response ? timeout : WRITE_NO_RESPONSE_TIMEOUT
+        deadline = Time.now + effective_timeout
+
+        proxy = async_introspect(char_path, timeout: gatt_remaining_timeout(deadline, effective_timeout, 'WriteValue'))
+        char_iface = proxy[GATT_CHARACTERISTIC_INTERFACE]
+
+        # Build write options
+        type_value = response ? 'request' : 'command'
+        options = {
+          'type' => DBus::Data::Variant.new(type_value, member_type: DBus::Type::STRING)
+        }
+
+        with_inprogress_retry do
+          async_call("WriteValue(#{uuid})", timeout: gatt_remaining_timeout(deadline, effective_timeout, 'WriteValue')) do |queue, _request_id, cancelled|
+            char_iface.WriteValue(bytes, options) 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
+
+        true
+      rescue DBus::Error => e
+        translate_gatt_error(e, char_path, 'Write')
+      end
+
+      # Async start notifications (idempotent)
+      #
+      # @param char_path [String] D-Bus characteristic path
+      # @param timeout [Numeric] Total timeout in seconds for the entire operation (default: 5)
+      # @return [Boolean] true on success
+      # @raise [TimeoutError] if call times out
+      # @raise [NotifyNotSupported] if characteristic doesn't support notifications
+      # @raise [NotConnectedError] if device disconnected
+      # @raise [OperationInProgressError] if retries exhausted
+      def async_start_notify(char_path, timeout: DEFAULT_NOTIFY_TIMEOUT)
+        uuid = extract_uuid_from_path(char_path)
+        deadline = Time.now + timeout
+
+        proxy = async_introspect(char_path, timeout: gatt_remaining_timeout(deadline, timeout, 'StartNotify'))
+        char_iface = proxy[GATT_CHARACTERISTIC_INTERFACE]
+
+        # Check flags before calling (use async to avoid deadlock)
+        flags = async_get_property(char_path, GATT_CHARACTERISTIC_INTERFACE, 'Flags', timeout: gatt_remaining_timeout(deadline, timeout, 'StartNotify'))
+        unless flags.include?('notify') || flags.include?('indicate')
+          raise NotifyNotSupported.new(uuid, flags)
+        end
+
+        # Idempotent: return early if already notifying (use async to avoid deadlock)
+        notifying = async_get_property(char_path, GATT_CHARACTERISTIC_INTERFACE, 'Notifying', timeout: gatt_remaining_timeout(deadline, timeout, 'StartNotify'))
+        return true if notifying
+
+        with_inprogress_retry do
+          async_call("StartNotify(#{uuid})", timeout: gatt_remaining_timeout(deadline, timeout, 'StartNotify')) do |queue, _request_id, cancelled|
+            char_iface.StartNotify 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
+
+        true
+      rescue DBus::Error => e
+        translate_gatt_error(e, char_path, 'StartNotify')
+      end
+
+      # Async stop notifications
+      #
+      # @param char_path [String] D-Bus characteristic path
+      # @param timeout [Numeric] Total timeout in seconds for the entire operation (default: 5)
+      # @return [Boolean] true on success
+      # @raise [TimeoutError] if call times out
+      # @raise [NotConnectedError] if device disconnected
+      def async_stop_notify(char_path, timeout: DEFAULT_NOTIFY_TIMEOUT)
+        uuid = extract_uuid_from_path(char_path)
+        deadline = Time.now + timeout
+
+        proxy = async_introspect(char_path, timeout: gatt_remaining_timeout(deadline, timeout, 'StopNotify'))
+        char_iface = proxy[GATT_CHARACTERISTIC_INTERFACE]
+
+        async_call("StopNotify(#{uuid})", timeout: gatt_remaining_timeout(deadline, timeout, 'StopNotify')) do |queue, _request_id, cancelled|
+          char_iface.StopNotify 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_gatt_error(e, char_path, 'StopNotify')
+      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
+      # @param operation [String] Operation name for error message
+      # @return [Numeric] Remaining seconds (minimum 0.1 to allow one more attempt)
+      # @raise [TimeoutError] if deadline has passed
+      def gatt_remaining_timeout(deadline, original_timeout, operation)
+        remaining = deadline - Time.now
+        raise TimeoutError.new(operation, original_timeout) if remaining <= 0
+        [remaining, 0.1].max
+      end
+
+      # Translate D-Bus errors to RBLE errors with UUID
+      # CONTEXT.md decision: error messages must include characteristic UUID
+      def translate_gatt_error(error, char_path, operation)
+        uuid = extract_uuid_from_path(char_path) || char_path
+
+        case error.name
+        when 'org.bluez.Error.NotSupported'
+          raise NotSupportedError, "#{operation} on #{uuid}"
+        when 'org.bluez.Error.NotPermitted'
+          raise NotPermittedError, "#{operation} on #{uuid}"
+        when 'org.bluez.Error.NotAuthorized'
+          raise NotAuthorizedError, "#{operation} on #{uuid}"
+        when 'org.bluez.Error.AuthenticationFailed'
+          raise AuthenticationError.new
+        when 'org.bluez.Error.NotConnected'
+          raise ConnectionLostError.new(nil, "#{operation} on #{uuid}")
+        when 'org.bluez.Error.InProgress'
+          raise OperationInProgressError.new("#{operation} on #{uuid}")
+        when 'org.bluez.Error.InvalidValueLength'
+          raise WriteError, "Invalid data length for #{uuid} (org.bluez.Error.InvalidValueLength)"
+        when 'org.bluez.Error.InvalidOffset'
+          raise ReadError, "Invalid offset for #{uuid} (org.bluez.Error.InvalidOffset)"
+        when 'org.bluez.Error.Failed'
+          raise GATTError, "#{operation} failed on #{uuid}: #{error.message} (org.bluez.Error.Failed)"
+        else
+          raise GATTError, "#{operation} failed on #{uuid}: #{error.message} (#{error.name})"
+        end
+      end
+
+      # Extract UUID from characteristic path for error messages
+      # Path format: /org/bluez/hci0/dev_XX_XX_XX_XX_XX_XX/serviceXXXX/charYYYY
+      def extract_uuid_from_path(char_path)
+        char_path.split('/').last
+      end
+    end
+  end
+end

data/lib/rble/bluez/async_introspection.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'dbus'
+require 'securerandom'
+require_relative 'async_call'
+
+module RBLE
+  module BlueZ
+    # Provides async D-Bus introspection with caching.
+    # Use this to introspect D-Bus objects without blocking the event loop.
+    #
+    # This module builds on AsyncCall to provide async introspection and
+    # GetManagedObjects calls. Results are cached for session lifetime.
+    #
+    # Including class must:
+    # - Include AsyncCall module (provides async_call method)
+    # - Provide a `service` method returning the D-Bus service
+    #
+    # @example
+    #   include AsyncCall
+    #   include AsyncIntrospection
+    #
+    #   proxy = async_introspect("/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF")
+    #   managed = async_get_managed_objects
+    #
+    module AsyncIntrospection
+      INTROSPECTABLE_INTERFACE = 'org.freedesktop.DBus.Introspectable'
+      OBJECT_MANAGER_INTERFACE = 'org.freedesktop.DBus.ObjectManager'
+      ROOT_PATH = '/'
+
+      # Asynchronously introspect a D-Bus object by path
+      #
+      # Returns cached ProxyObject if available, otherwise performs async
+      # introspection and caches the result.
+      #
+      # @param path [String] D-Bus object path to introspect
+      # @param timeout [Numeric] Timeout in seconds (default: 5)
+      # @return [DBus::ProxyObject] Introspected proxy object
+      # @raise [TimeoutError] if introspection times out
+      # @raise [DBus::Error] if D-Bus call fails
+      def async_introspect(path, timeout: 5)
+        @introspection_cache ||= {}
+
+        # Return cached result if present
+        return @introspection_cache[path] if @introspection_cache.key?(path)
+
+        # Perform async introspection
+        proxy = perform_async_introspect(path, timeout: timeout)
+
+        # Cache and return
+        @introspection_cache[path] = proxy
+        proxy
+      end
+
+      # Asynchronously get all managed objects from ObjectManager
+      #
+      # Creates the D-Bus message directly to avoid triggering synchronous
+      # introspection when accessing proxy interfaces.
+      #
+      # @param timeout [Numeric] Timeout in seconds (default: 10)
+      # @return [Hash] path => { interface_name => { property => value } }
+      # @raise [TimeoutError] if call times out
+      # @raise [DBus::Error] if D-Bus call fails
+      def async_get_managed_objects(timeout: 10)
+        result = async_call('GetManagedObjects', timeout: timeout) do |queue, _request_id, cancelled|
+          # Create message directly to avoid sync introspection
+          msg = DBus::Message.new(DBus::Message::METHOD_CALL)
+          msg.path = ROOT_PATH
+          msg.interface = OBJECT_MANAGER_INTERFACE
+          msg.destination = service.name
+          msg.member = 'GetManagedObjects'
+          msg.sender = service.connection.unique_name
+
+          service.connection.send_sync_or_async(msg) do |reply, *params|
+            next if cancelled[0]  # Discard late callback
+            if reply.is_a?(DBus::Error)
+              queue.push([reply, nil])
+            else
+              # params contains the method return values (first is the Hash)
+              queue.push([nil, params.first])
+            end
+          end
+        end
+
+        result
+      end
+
+      # Clear cache and re-introspect a path
+      #
+      # Forces a fresh introspection even if the path is cached.
+      #
+      # @param path [String] D-Bus object path to refresh
+      # @param timeout [Numeric] Timeout in seconds (default: 5)
+      # @return [DBus::ProxyObject] Fresh introspected proxy object
+      # @raise [TimeoutError] if introspection times out
+      # @raise [DBus::Error] if D-Bus call fails
+      def refresh_introspection(path, timeout: 5)
+        @introspection_cache ||= {}
+
+        # Clear cache entry
+        @introspection_cache.delete(path)
+
+        # Perform fresh introspection (will be cached by async_introspect)
+        async_introspect(path, timeout: timeout)
+      end
+
+      # Remove a path from the introspection cache
+      #
+      # Call this when a device is removed to clean up stale cache entries.
+      #
+      # @param path [String] D-Bus object path to remove from cache
+      # @return [void]
+      def clear_introspection(path)
+        @introspection_cache ||= {}
+        @introspection_cache.delete(path)
+      end
+
+      private
+
+      # Perform the actual async introspection
+      #
+      # Uses connection.introspect_data with a block to avoid triggering
+      # synchronous introspection when accessing proxy interfaces.
+      #
+      # @param path [String] D-Bus object path
+      # @param timeout [Numeric] Timeout in seconds
+      # @return [DBus::ProxyObject] Introspected proxy object
+      def perform_async_introspect(path, timeout:)
+        # Create proxy without triggering auto-introspection
+        proxy = service.object(path)
+
+        # Use async_call with direct introspect_data call (supports async via block)
+        xml = async_call('Introspect', timeout: timeout) do |queue, _request_id, cancelled|
+          service.connection.introspect_data(service.name, path) do |xml_result|
+            next if cancelled[0]  # Discard late callback
+            if xml_result.is_a?(DBus::Error)
+              queue.push([xml_result, nil])
+            else
+              queue.push([nil, xml_result])
+            end
+          end
+        end
+
+        # Parse introspection XML into proxy object
+        DBus::ProxyObjectFactory.introspect_into(proxy, xml)
+
+        proxy
+      end
+    end
+  end
+end

data/lib/rble/bluez/dbus_connection.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RBLE
+  module BlueZ
+    # Manages D-Bus system bus connection to BlueZ
+    class DBusConnection
+      attr_reader :bus, :service, :root_object
+
+      def initialize
+        @bus = nil
+        @service = nil
+        @root_object = nil
+      end
+
+      # Connect to D-Bus system bus
+      # Uses ASystemBus (non-singleton) to avoid state issues when switching between
+      # event loop processing (DBus::Main) and synchronous calls (send_sync)
+      # @raise [PermissionError] if permission denied
+      # @raise [Error] if BlueZ service not available
+      def connect
+        @bus = DBus::ASystemBus.new
+        @service = @bus.service(BLUEZ_SERVICE)
+
+        # Pre-introspect root for ObjectManager (REL-01: before async context)
+        # This ensures ObjectManager is available without async introspection
+        @root_object = @service.object('/')
+        @root_object.introspect
+      rescue DBus::Error => e
+        if e.message.include?('AccessDenied') || e.message.include?('Permission')
+          raise PermissionError.new('connect to D-Bus')
+        end
+        raise Error, "Failed to connect to BlueZ D-Bus service: #{e.message}"
+      end
+
+      # Get object manager interface
+      # @return [DBus::ProxyObjectInterface]
+      def object_manager
+        root_object[OBJECT_MANAGER_INTERFACE]
+      end
+
+      # Get a D-Bus object by path
+      # @param path [String] D-Bus object path
+      # @return [DBus::ProxyObject]
+      def object(path)
+        obj = @service.object(path)
+        obj.introspect
+        obj
+      end
+
+      # Check if connected
+      # @return [Boolean]
+      def connected?
+        !@bus.nil? && !@service.nil?
+      end
+
+      # Disconnect (cleanup)
+      def disconnect
+        @root_object = nil
+        @service = nil
+        @bus = nil
+      end
+    end
+  end
+end