rble 0.7.0

data/lib/rble/bluez/gatt_operation_queue.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module RBLE
+  module BlueZ
+    # Per-connection queue for serializing GATT operations.
+    #
+    # BlueZ can behave unpredictably when multiple GATT operations (read, write,
+    # start_notify) are executed concurrently on the same connection. This queue
+    # ensures operations are executed sequentially with a small delay between them.
+    #
+    # @example
+    #   queue = GattOperationQueue.new
+    #   queue.enqueue { session.async_read_value(char_path) }
+    #   queue.enqueue { session.async_write_value(char_path, [0x01]) }
+    #   queue.stop  # Call on disconnect
+    #
+    class GattOperationQueue
+      # Delay between GATT operations to prevent BlueZ contention
+      INTER_OPERATION_DELAY = 0.05
+
+      def initialize
+        @queue = Thread::Queue.new
+        @worker_thread = nil
+        @running = false
+        @mutex = Mutex.new
+        @active_result_queue = nil
+      end
+
+      # Enqueue a GATT operation for sequential execution
+      #
+      # @yield Block containing the GATT operation to execute
+      # @return [Object] Result from the block execution
+      # @raise [RuntimeError] if queue is stopped
+      # @raise Re-raises any exception from the block
+      def enqueue(&block)
+        raise 'GattOperationQueue is stopped' unless running?
+
+        result_queue = Thread::Queue.new
+        @queue.push([block, result_queue])
+
+        # Wait for result (blocking)
+        result, error = result_queue.pop
+        raise error if error
+
+        result
+      end
+
+      # Start the worker thread if not already running
+      # @return [void]
+      def start
+        @mutex.synchronize do
+          return if @running
+
+          @running = true
+          @worker_thread = Thread.new { worker_loop }
+          @worker_thread.name = 'rble-gatt-queue'
+        end
+      end
+
+      # Stop the worker thread and clear pending operations
+      # @return [void]
+      def stop
+        @mutex.synchronize do
+          return unless @running
+
+          @running = false
+          @queue.push(:shutdown)
+        end
+
+        # Wait for worker thread to finish
+        @worker_thread&.join(2)
+        @worker_thread&.kill if @worker_thread&.alive?
+        @worker_thread = nil
+
+        # Unblock caller of the currently-executing operation (if any)
+        active_rq = @active_result_queue
+        @active_result_queue = nil
+        active_rq&.push([nil, RuntimeError.new('GATT queue stopped')])
+
+        # Drain remaining operations and unblock waiting callers
+        drain_pending_operations
+      end
+
+      # Check if queue is running
+      # @return [Boolean]
+      def running?
+        @mutex.synchronize { @running }
+      end
+
+      private
+
+      # Drain pending operations, notifying callers with an error
+      # @return [void]
+      def drain_pending_operations
+        while (item = @queue.pop(true) rescue nil)
+          next if item == :shutdown
+
+          _block, result_queue = item
+          result_queue.push([nil, RuntimeError.new('GATT queue stopped')])
+        end
+      end
+
+      def worker_loop
+        RBLE.logger&.debug('[RBLE] GATT operation queue started')
+
+        while @running
+          item = @queue.pop
+          break if item == :shutdown
+
+          block, result_queue = item
+          @active_result_queue = result_queue
+          begin
+            result = block.call
+            result_queue.push([result, nil])
+          rescue StandardError => e
+            result_queue.push([nil, e])
+          ensure
+            @active_result_queue = nil
+          end
+
+          # Inter-operation delay to prevent BlueZ contention
+          sleep(INTER_OPERATION_DELAY) if @running
+        end
+
+        RBLE.logger&.debug('[RBLE] GATT operation queue stopped')
+      end
+    end
+  end
+end

data/lib/rble/bluez/pairing_agent.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'dbus'
+
+module RBLE
+  module BlueZ
+    # D-Bus object implementing the org.bluez.Agent1 interface for BLE pairing.
+    #
+    # BlueZ invokes Agent1 methods during pairing to handle security prompts
+    # (PIN entry, passkey confirmation, authorization). This class exports those
+    # methods on the system bus so BlueZ can call back into the Ruby process.
+    #
+    # @example
+    #   agent = PairingAgent.new(io_handler: handler, force: false)
+    #   bus.object_server.export(agent)
+    #
+    class PairingAgent < DBus::Object
+      AGENT_INTERFACE = 'org.bluez.Agent1'
+      AGENT_PATH = '/org/rble/agent'
+
+      # @param io_handler [#display, #prompt, #confirm] IO handler for user interaction
+      # @param force [Boolean] Skip interactive prompts (auto-accept)
+      def initialize(io_handler:, force: false)
+        super(AGENT_PATH)
+        @io_handler = io_handler
+        @force = force
+      end
+
+      dbus_interface AGENT_INTERFACE do
+        # Called when the agent is unregistered
+        dbus_method :Release do
+          # no-op
+        end
+
+        # Request a PIN code from the user
+        # @param device [String] D-Bus object path of the device
+        # @return [String] PIN code
+        dbus_method :RequestPinCode, 'in device:o, out pincode:s' do |device|
+          if @force
+            @io_handler.display("Auto-accepting PIN for #{device_label(device)}")
+            ['0000']
+          else
+            pin = @io_handler.prompt("Enter PIN for #{device_label(device)}: ")
+            [pin.to_s.strip]
+          end
+        end
+
+        # Display a PIN code to the user
+        # @param device [String] D-Bus object path of the device
+        # @param pincode [String] PIN code to display
+        dbus_method :DisplayPinCode, 'in device:o, in pincode:s' do |device, pincode|
+          @io_handler.display("PIN for #{device_label(device)}: #{pincode}")
+        end
+
+        # Request a passkey (numeric) from the user
+        # @param device [String] D-Bus object path of the device
+        # @return [Integer] Passkey (0-999999)
+        dbus_method :RequestPasskey, 'in device:o, out passkey:u' do |device|
+          if @force
+            @io_handler.display("Auto-accepting passkey for #{device_label(device)}")
+            [0]
+          else
+            input = @io_handler.prompt("Enter passkey (0-999999) for #{device_label(device)}: ")
+            passkey = input.to_s.strip.to_i
+            passkey = passkey.clamp(0, 999_999)
+            [passkey]
+          end
+        end
+
+        # Display a passkey with the number of digits entered so far
+        # @param device [String] D-Bus object path of the device
+        # @param passkey [Integer] Passkey being entered
+        # @param entered [Integer] Number of digits entered
+        dbus_method :DisplayPasskey, 'in device:o, in passkey:u, in entered:q' do |device, passkey, entered|
+          @io_handler.display("Passkey for #{device_label(device)}: #{format('%06d', passkey)} (#{entered} digits entered)")
+        end
+
+        # Request confirmation of a passkey
+        # @param device [String] D-Bus object path of the device
+        # @param passkey [Integer] Passkey to confirm
+        dbus_method :RequestConfirmation, 'in device:o, in passkey:u' do |device, passkey|
+          if @force
+            @io_handler.display("Auto-confirming passkey #{format('%06d', passkey)} for #{device_label(device)}")
+          else
+            accepted = @io_handler.confirm("Confirm passkey #{format('%06d', passkey)} for #{device_label(device)}? [Y/n] ")
+            unless accepted
+              raise DBus.error('org.bluez.Error.Rejected'), "Passkey rejected by user for #{device_label(device)}"
+            end
+          end
+        end
+
+        # Request authorization for the device
+        # @param device [String] D-Bus object path of the device
+        dbus_method :RequestAuthorization, 'in device:o' do |device|
+          if @force
+            @io_handler.display("Auto-authorizing #{device_label(device)}")
+          else
+            accepted = @io_handler.confirm("Authorize #{device_label(device)}? [Y/n] ")
+            unless accepted
+              raise DBus.error('org.bluez.Error.Rejected'), "Authorization rejected by user for #{device_label(device)}"
+            end
+          end
+        end
+
+        # Authorize a service (auto-authorize, no prompt needed)
+        # @param device [String] D-Bus object path of the device
+        # @param uuid [String] Service UUID
+        dbus_method :AuthorizeService, 'in device:o, in uuid:s' do |device, uuid|
+          @io_handler.display("Authorizing service #{uuid} for #{device_label(device)}")
+        end
+
+        # Called when a pairing request is cancelled
+        dbus_method :Cancel do
+          @io_handler.display('Pairing cancelled')
+        end
+      end
+
+      private
+
+      # Extract a human-readable label from a D-Bus device path
+      # @param device_path [String] D-Bus object path like /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF
+      # @return [String] MAC address or the raw path
+      def device_label(device_path)
+        if device_path =~ /dev_([0-9A-F]{2}_[0-9A-F]{2}_[0-9A-F]{2}_[0-9A-F]{2}_[0-9A-F]{2}_[0-9A-F]{2})/i
+          ::Regexp.last_match(1).tr('_', ':')
+        else
+          device_path
+        end
+      end
+    end
+  end
+end

data/lib/rble/bluez/pairing_session.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require 'dbus'
+
+module RBLE
+  module BlueZ
+    # Manages the lifecycle of a PairingAgent during pair/unpair operations.
+    #
+    # Each PairingSession creates a dedicated D-Bus bus connection, exports a
+    # PairingAgent on it, registers the agent with BlueZ's AgentManager1, and
+    # drives the Pair() call with a DBus::Main event loop so agent callbacks
+    # are processed in the same thread context.
+    #
+    # The agent MUST be on the SAME bus as RegisterAgent and Pair() calls.
+    # A dedicated bus per session avoids conflicts with the shared DBusSession.
+    #
+    # @example
+    #   session = PairingSession.new(io_handler: handler, force: false, capability: "KeyboardDisplay")
+    #   result = session.pair("/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF", timeout: 30)
+    #   # => :paired or :already_paired
+    #
+    class PairingSession
+      CAPABILITY_MAP = {
+        'low' => 'NoInputNoOutput',
+        'medium' => 'DisplayYesNo',
+        'high' => 'KeyboardDisplay',
+        nil => 'KeyboardDisplay'
+      }.freeze
+
+      # @param io_handler [#display, #prompt, #confirm] IO handler for user interaction
+      # @param force [Boolean] Skip interactive prompts (auto-accept)
+      # @param capability [String] Agent capability from CAPABILITY_MAP values
+      def initialize(io_handler:, force: false, capability: 'KeyboardDisplay')
+        @io_handler = io_handler
+        @force = force
+        @capability = capability
+        @bus = nil
+        @agent = nil
+        @main_loop = nil
+      end
+
+      # Pair with a device by exporting an agent and calling Device1.Pair()
+      #
+      # Creates a dedicated D-Bus bus, exports the PairingAgent, registers it
+      # with AgentManager1, then calls Pair() with an event loop to process
+      # agent callbacks.
+      #
+      # @param device_path [String] D-Bus device path (e.g., /org/bluez/hci0/dev_AA_BB_...)
+      # @param timeout [Numeric] Timeout in seconds for the pairing operation
+      # @return [Symbol] :paired on success, :already_paired if already paired
+      # @raise [RBLE::AuthenticationError] if authentication fails
+      # @raise [RBLE::ConnectionFailed] if connection to device fails
+      # @raise [RBLE::TimeoutError] if pairing times out
+      # @raise [RBLE::Error] on other failures
+      def pair(device_path, timeout: 30)
+        setup_bus_and_agent
+        register_agent
+        call_pair(device_path, timeout: timeout)
+      ensure
+        cleanup
+      end
+
+      private
+
+      # Create dedicated D-Bus bus and export the agent
+      def setup_bus_and_agent
+        @bus = DBus::ASystemBus.new
+        @agent = PairingAgent.new(io_handler: @io_handler, force: @force)
+        @bus.object_server.export(@agent)
+      end
+
+      # Register the agent with BlueZ's AgentManager1
+      def register_agent
+        bluez = @bus.service(BLUEZ_SERVICE)
+        bluez_root = bluez.object('/')
+        bluez_root.introspect
+
+        agent_manager = bluez_root[AGENT_MANAGER_INTERFACE]
+        agent_manager.RegisterAgent(PairingAgent::AGENT_PATH, @capability)
+        agent_manager.RequestDefaultAgent(PairingAgent::AGENT_PATH)
+      end
+
+      # Call Device1.Pair() with an event loop for agent callback processing
+      #
+      # Uses a Thread::Queue to communicate the result from the async callback
+      # back to the calling thread. DBus::Main runs in a background thread to
+      # process agent method invocations from BlueZ.
+      #
+      # @param device_path [String] D-Bus device path
+      # @param timeout [Numeric] Timeout in seconds
+      # @return [Symbol] :paired or :already_paired
+      def call_pair(device_path, timeout: 30)
+        result_queue = Thread::Queue.new
+
+        # Introspect device to get Device1 interface
+        device_obj = @bus.service(BLUEZ_SERVICE).object(device_path)
+        device_obj.introspect
+        device_iface = device_obj[DEVICE_INTERFACE]
+
+        # Start event loop in background thread for agent callbacks
+        @main_loop = DBus::Main.new
+        @main_loop << @bus
+
+        loop_thread = Thread.new do
+          @main_loop.run
+        rescue StandardError => e
+          RBLE.logger&.debug("[RBLE] PairingSession event loop error: #{e.message}")
+        end
+
+        # Call Pair() asynchronously - result delivered via callback
+        device_iface.Pair do |reply|
+          if reply.is_a?(DBus::Error)
+            result_queue.push([:error, reply])
+          else
+            result_queue.push([:success, nil])
+          end
+        end
+
+        # Wait for result with timeout
+        result = result_queue.pop(timeout: timeout)
+
+        # Stop the event loop
+        @main_loop&.quit
+        loop_thread&.join(2)
+
+        if result.nil?
+          raise RBLE::TimeoutError.new('Pair', timeout)
+        end
+
+        status, error = result
+
+        if status == :error
+          translate_pair_error(error, device_path)
+        else
+          :paired
+        end
+      end
+
+      # Translate D-Bus errors from Pair() into RBLE exceptions
+      #
+      # @param error [DBus::Error] The D-Bus error
+      # @param device_path [String] Device path for error context
+      # @return [Symbol] :already_paired if device is already paired
+      # @raise [RBLE::AuthenticationError] on auth failures
+      # @raise [RBLE::ConnectionFailed] on connection failures
+      # @raise [RBLE::Error] on other failures
+      def translate_pair_error(error, device_path)
+        address = extract_address(device_path)
+
+        case error.name
+        when 'org.bluez.Error.AlreadyExists'
+          :already_paired
+        when 'org.bluez.Error.AuthenticationFailed',
+             'org.bluez.Error.AuthenticationCanceled',
+             'org.bluez.Error.AuthenticationRejected',
+             'org.bluez.Error.AuthenticationTimeout'
+          raise RBLE::AuthenticationError.new(address)
+        when 'org.bluez.Error.ConnectionAttemptFailed'
+          raise RBLE::ConnectionFailed.new(address, 'device not reachable (out of range?)')
+        else
+          raise RBLE::Error, "Pairing failed for #{address}: #{error.message}"
+        end
+      end
+
+      # Extract MAC address from D-Bus device path
+      # @param device_path [String] D-Bus path like /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF
+      # @return [String] MAC address or 'unknown'
+      def extract_address(device_path)
+        if device_path =~ /dev_([0-9A-F]{2}_[0-9A-F]{2}_[0-9A-F]{2}_[0-9A-F]{2}_[0-9A-F]{2}_[0-9A-F]{2})/i
+          ::Regexp.last_match(1).tr('_', ':')
+        else
+          'unknown'
+        end
+      end
+
+      # Clean up D-Bus resources
+      # Unregisters agent, unexports it, and closes the bus connection.
+      # All errors during cleanup are silently ignored.
+      def cleanup
+        # Stop event loop if still running
+        @main_loop&.quit rescue nil
+
+        # Unregister agent from AgentManager1
+        if @bus
+          begin
+            bluez = @bus.service(BLUEZ_SERVICE)
+            bluez_root = bluez.object('/')
+            bluez_root.introspect
+            agent_manager = bluez_root[AGENT_MANAGER_INTERFACE]
+            agent_manager.UnregisterAgent(PairingAgent::AGENT_PATH)
+          rescue StandardError
+            # Ignore errors during cleanup
+          end
+        end
+
+        # Unexport agent from bus
+        if @bus && @agent
+          begin
+            @bus.object_server.unexport(@agent)
+          rescue StandardError
+            # Ignore errors during cleanup
+          end
+        end
+
+        # Close the dedicated bus
+        @bus = nil
+        @agent = nil
+        @main_loop = nil
+      end
+    end
+  end
+end

data/lib/rble/bluez/retry_policy.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RBLE
+  module BlueZ
+    # Retry policy for handling transient BlueZ errors with exponential backoff.
+    #
+    # BlueZ can return org.bluez.Error.InProgress when operations are attempted
+    # too quickly or when the stack is busy. This module provides retry logic
+    # with exponential backoff to handle these cases gracefully.
+    #
+    # @example
+    #   include RetryPolicy
+    #
+    #   with_inprogress_retry do
+    #     session.async_read_value(char_path)
+    #   end
+    #
+    module RetryPolicy
+      # Maximum number of retry attempts for InProgress errors
+      MAX_RETRIES = 3
+
+      # Initial delay before first retry (50ms)
+      INITIAL_DELAY = 0.05
+
+      # Maximum delay between retries (500ms)
+      MAX_DELAY = 0.5
+
+      # Execute a block with retry logic for InProgress errors
+      #
+      # @yield Block containing the operation to execute
+      # @return [Object] Result from the block
+      # @raise [OperationInProgressError] if all retries exhausted
+      # @raise Re-raises any other exception
+      def with_inprogress_retry
+        attempts = 0
+        delay = INITIAL_DELAY
+
+        begin
+          yield
+        rescue DBus::Error => e
+          if e.name == 'org.bluez.Error.InProgress' && attempts < MAX_RETRIES
+            attempts += 1
+            RBLE.logger&.debug("[RBLE] InProgress error, retry #{attempts}/#{MAX_RETRIES} after #{(delay * 1000).round}ms")
+            sleep(delay)
+            delay = [delay * 2, MAX_DELAY].min  # Exponential backoff with cap
+            retry
+          end
+
+          # Re-raise if not InProgress or retries exhausted
+          raise
+        end
+      end
+    end
+  end
+end

data/lib/rble/bluez.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+begin
+  require 'dbus'
+rescue LoadError
+  raise LoadError,
+    "The ruby-dbus gem is required for the BlueZ backend on Linux. " \
+    "Install it with: gem install ruby-dbus"
+end
+
+module RBLE
+  module BlueZ
+    BLUEZ_SERVICE = 'org.bluez'
+    ADAPTER_INTERFACE = 'org.bluez.Adapter1'
+    DEVICE_INTERFACE = 'org.bluez.Device1'
+    GATT_SERVICE_INTERFACE = 'org.bluez.GattService1'
+    GATT_CHARACTERISTIC_INTERFACE = 'org.bluez.GattCharacteristic1'
+    GATT_DESCRIPTOR_INTERFACE = 'org.bluez.GattDescriptor1'
+    PROPERTIES_INTERFACE = 'org.freedesktop.DBus.Properties'
+    OBJECT_MANAGER_INTERFACE = 'org.freedesktop.DBus.ObjectManager'
+    AGENT_MANAGER_INTERFACE = 'org.bluez.AgentManager1'
+  end
+end
+
+require_relative 'bluez/dbus_connection'
+require_relative 'bluez/adapter'
+require_relative 'bluez/event_loop'
+require_relative 'bluez/dbus_session'
+require_relative 'bluez/device'
+require_relative 'bluez/gatt_operation_queue'
+require_relative 'bluez/retry_policy'
+require_relative 'bluez/pairing_agent'
+require_relative 'bluez/pairing_session'