rble 0.7.0

data/lib/rble/bluez/dbus_session.rb

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+require_relative 'async_call'
+require_relative 'async_introspection'
+require_relative 'async_gatt_operations'
+require_relative 'async_connection_operations'
+
+module RBLE
+  module BlueZ
+    # Encapsulates a D-Bus connection and event loop lifecycle for a single BLE session.
+    #
+    # Each DBusSession provides an isolated D-Bus communication channel with its own
+    # event loop. This design eliminates state corruption issues that occur when a
+    # shared D-Bus connection is used across multiple operations (scan, connect, notify).
+    #
+    # Key design decisions:
+    # - Composition over inheritance: DBusSession composes DBusConnection + EventLoop
+    # - Event loop uses the session's connection.bus
+    # - Session tracks its own lifecycle (connected/running state)
+    # - Thread::Queue is owned by EventLoop (already implemented there)
+    #
+    # @example Basic usage
+    #   session = RBLE::BlueZ::DBusSession.new
+    #   session.connect
+    #   session.start_event_loop
+    #   # ... use session.bus for D-Bus operations ...
+    #   session.disconnect  # stops event loop and closes connection
+    #
+    class DBusSession
+      include AsyncCall
+      include AsyncIntrospection
+      include AsyncGattOperations
+      include AsyncConnectionOperations
+
+      # Create a new DBusSession (not yet connected)
+      def initialize
+        @connection = nil
+        @event_loop = nil
+        @mutex = Mutex.new
+        @introspection_cache = {}
+        @registered_handlers = []  # Array of [proxy_iface, signal_name] tuples
+        @pending_queues = []       # Array of Thread::Queue for pending async calls
+        @closed = false            # Track closed state for idempotent close
+      end
+
+      # Get the D-Bus service
+      # Required by AsyncIntrospection module
+      # @return [DBus::Service, nil]
+      def service
+        @mutex.synchronize { @connection&.service }
+      end
+
+      # Register a signal handler with tracking for cleanup
+      # @param proxy_iface [DBus::ProxyObjectInterface] The interface
+      # @param signal_name [String] Signal name (e.g., 'PropertiesChanged')
+      # @yield Signal handler block
+      # @return [void]
+      def register_signal_handler(proxy_iface, signal_name, &block)
+        proxy_iface.on_signal(signal_name, &block)
+        @registered_handlers << [proxy_iface, signal_name]
+      end
+
+      # Check if session is closed
+      # @return [Boolean]
+      def closed?
+        @mutex.synchronize { @closed }
+      end
+
+      # Connect to the D-Bus system bus
+      # Creates a new DBusConnection and establishes connection to BlueZ
+      # @return [void]
+      # @raise [PermissionError] if permission denied
+      # @raise [Error] if BlueZ service not available
+      def connect
+        @mutex.synchronize do
+          return if @connection&.connected?
+
+          @connection = DBusConnection.new
+          @connection.connect
+        end
+      end
+
+      # Start the event loop in a background thread
+      # The event loop processes D-Bus signals and enqueues events for the main thread
+      # @return [void]
+      # @raise [Error] if not connected
+      def start_event_loop
+        @mutex.synchronize do
+          raise Error, 'Cannot start event loop: not connected' unless @connection&.connected?
+          return if @event_loop&.running?
+
+          # Register handlers BEFORE starting event loop — avoids synchronous
+          # AddMatch deadlock with the event loop reading the same socket.
+          setup_cache_invalidation_handler
+
+          @event_loop = EventLoop.new
+          @event_loop.start(@connection.bus)
+        end
+      end
+
+      # Stop the event loop
+      # Waits for the background thread to finish
+      # @param timeout [Numeric] Maximum seconds to wait for thread
+      # @return [void]
+      def stop_event_loop(timeout: 1)
+        @mutex.synchronize do
+          @event_loop&.stop(timeout: timeout)
+        end
+      end
+
+      # Close the session (idempotent)
+      # Stops event loop, unregisters signal handlers, closes connection
+      # Safe teardown order: notify pending -> stop loop -> unregister handlers -> close connection
+      # @return [void]
+      def close
+        @mutex.synchronize do
+          return if @closed
+          @closed = true
+
+          # Notify pending async callers they won't get results
+          @pending_queues.each { |q| q.push([:session_closed, nil]) }
+          @pending_queues.clear
+
+          # Stop event loop FIRST (critical - prevents RemoveMatch deadlock)
+          @event_loop&.stop(timeout: 1)
+          @event_loop = nil
+
+          # NOW safe to unregister signal handlers (no Main loop = no deadlock)
+          unregister_signal_handlers
+
+          # Close D-Bus connection last
+          @connection&.disconnect
+          @connection = nil
+
+          RBLE.logger&.debug('[RBLE] Session closed')
+        end
+      end
+
+      # Backward compatibility alias
+      alias disconnect close
+
+      # Check if connected to D-Bus
+      # @return [Boolean]
+      def connected?
+        @mutex.synchronize { !@closed && (@connection&.connected? || false) }
+      end
+
+      # Check if event loop is running
+      # @return [Boolean]
+      def running?
+        @mutex.synchronize { @event_loop&.running? || false }
+      end
+
+      # Get the event loop's raw queue for signal-safe direct push
+      # Returns nil if no event loop is active
+      # Reads @event_loop directly (no mutex) which is safe for reading a single
+      # instance variable - used from signal trap context where mutex is unsafe
+      # @return [Thread::Queue, nil]
+      def event_loop_queue
+        @event_loop&.queue
+      end
+
+      # Get the D-Bus bus for signal registration
+      # @return [DBus::SystemBus, nil]
+      def bus
+        @mutex.synchronize { @connection&.bus }
+      end
+
+      # Get a D-Bus object by path
+      # @param path [String] D-Bus object path
+      # @return [DBus::ProxyObject]
+      # @raise [Error] if not connected
+      def object(path)
+        conn = @mutex.synchronize { @connection }
+        raise Error, 'Not connected' unless conn&.connected?
+
+        conn.object(path)
+      end
+
+      # Get the ObjectManager interface
+      # @return [DBus::ProxyObjectInterface]
+      # @raise [Error] if not connected
+      def object_manager
+        conn = @mutex.synchronize { @connection }
+        raise Error, 'Not connected' unless conn&.connected?
+
+        conn.object_manager
+      end
+
+      # Enqueue an event for processing
+      # Thread-safe - can be called from D-Bus signal handlers
+      # @param type [Symbol] Event type (:device_found, :notification, etc.)
+      # @param path [String, nil] D-Bus object path
+      # @param data [Hash, nil] Event-specific data
+      # @return [void]
+      def enqueue(type, path, data)
+        event_loop = @mutex.synchronize { @event_loop }
+        event_loop&.enqueue(type, path, data)
+      end
+
+      # Process events from the queue with a timeout
+      # Yields each event to the block until shutdown or timeout
+      # @param timeout [Numeric, nil] Timeout in seconds (nil = block forever)
+      # @yield [Event] Called for each event
+      # @return [Boolean] true if shutdown received, false if timeout
+      def process_events(timeout: nil, &block)
+        event_loop = @mutex.synchronize { @event_loop }
+        return false unless event_loop
+
+        event_loop.process_events(timeout: timeout, &block)
+      end
+
+      # Non-blocking drain of all pending events
+      # @yield [Event] Called for each event
+      # @return [Integer] Number of events processed
+      def drain_events(&block)
+        event_loop = @mutex.synchronize { @event_loop }
+        return 0 unless event_loop
+
+        event_loop.drain_events(&block)
+      end
+
+      # Register a signal handler asynchronously (safe while event loop is running).
+      #
+      # Splits on_signal into two steps:
+      # 1. Local handler registration (immediate, no D-Bus I/O)
+      # 2. D-Bus AddMatch message (async via event loop)
+      #
+      # @param proxy_iface [DBus::ProxyObjectInterface] The interface to watch
+      # @param signal_name [String] Signal name (e.g., 'PropertiesChanged')
+      # @param timeout [Numeric] Timeout for AddMatch acknowledgement
+      # @yield [*params] Called when matching signal arrives
+      # @return [void]
+      def async_register_signal_handler(proxy_iface, signal_name, timeout: 5, &block)
+        bus = proxy_iface.object.bus
+        mr = DBus::MatchRule.new.from_signal(proxy_iface, signal_name)
+        mrs = mr.to_s
+
+        # Step 1: Register handler locally (no D-Bus I/O)
+        # Call Connection#add_match directly, bypassing BusConnection's synchronous override
+        DBus::Connection.instance_method(:add_match).bind_call(bus, mrs) do |msg|
+          block.call(*msg.params)
+        end
+
+        # Step 2: Send AddMatch to D-Bus daemon asynchronously
+        async_call("AddMatch(#{signal_name})", timeout: timeout) do |queue, _request_id, cancelled|
+          msg = DBus::Message.new(DBus::Message::METHOD_CALL)
+          msg.path = '/org/freedesktop/DBus'
+          msg.interface = 'org.freedesktop.DBus'
+          msg.destination = 'org.freedesktop.DBus'
+          msg.member = 'AddMatch'
+          msg.sender = bus.unique_name
+          msg.add_param('s', mrs)
+
+          bus.send_sync_or_async(msg) do |reply|
+            next if cancelled[0]
+            if reply.is_a?(DBus::Error)
+              queue.push([reply, nil])
+            else
+              queue.push([nil, :ok])
+            end
+          end
+        end
+
+        @registered_handlers << [proxy_iface, signal_name]
+      end
+
+      # Unregister a signal handler asynchronously (safe while event loop is running).
+      #
+      # @param proxy_iface [DBus::ProxyObjectInterface] The interface
+      # @param signal_name [String] Signal name
+      # @param timeout [Numeric] Timeout for RemoveMatch acknowledgement
+      # @return [void]
+      def async_unregister_signal_handler(proxy_iface, signal_name, timeout: 5)
+        bus = proxy_iface.object.bus
+        mr = DBus::MatchRule.new.from_signal(proxy_iface, signal_name)
+        mrs = mr.to_s
+
+        # Step 1: Remove handler locally (no D-Bus I/O)
+        DBus::Connection.instance_method(:remove_match).bind_call(bus, mrs)
+
+        # Step 2: Send RemoveMatch to D-Bus daemon asynchronously
+        async_call("RemoveMatch(#{signal_name})", timeout: timeout) do |queue, _request_id, cancelled|
+          msg = DBus::Message.new(DBus::Message::METHOD_CALL)
+          msg.path = '/org/freedesktop/DBus'
+          msg.interface = 'org.freedesktop.DBus'
+          msg.destination = 'org.freedesktop.DBus'
+          msg.member = 'RemoveMatch'
+          msg.sender = bus.unique_name
+          msg.add_param('s', mrs)
+
+          bus.send_sync_or_async(msg) do |reply|
+            next if cancelled[0]
+            if reply.is_a?(DBus::Error)
+              queue.push([reply, nil])
+            else
+              queue.push([nil, :ok])
+            end
+          end
+        end
+
+        @registered_handlers.delete_if { |pi, sn| pi == proxy_iface && sn == signal_name }
+      rescue StandardError => e
+        RBLE.logger&.debug("[RBLE] async_unregister_signal_handler error: #{e.message}")
+      end
+
+      private
+
+      # Setup handler to clear introspection cache when devices are removed
+      # Called when event loop starts to ensure stale introspection data is cleared
+      # when BlueZ removes devices
+      # Must be called within @mutex.synchronize
+      def setup_cache_invalidation_handler
+        return unless @connection&.connected?
+
+        root = @connection.root_object
+        om = root[OBJECT_MANAGER_INTERFACE]
+
+        register_signal_handler(om, 'InterfacesRemoved') do |path, _interfaces|
+          # Clear the removed path
+          clear_introspection(path)
+
+          # Clear all child paths (e.g., /dev_XX/service0001 when /dev_XX removed)
+          @introspection_cache.keys.each do |cached_path|
+            clear_introspection(cached_path) if cached_path.start_with?("#{path}/")
+          end
+        end
+      end
+
+      # Unregister all tracked signal handlers
+      # Must be called AFTER event loop is stopped to avoid RemoveMatch deadlock
+      def unregister_signal_handlers
+        @registered_handlers.each do |proxy_iface, signal_name|
+          begin
+            proxy_iface.on_signal(signal_name)  # No block = unregister
+          rescue StandardError => e
+            RBLE.logger&.debug("[RBLE] Signal cleanup ignored: #{e.message}")
+          end
+        end
+        @registered_handlers.clear
+      end
+    end
+  end
+end

data/lib/rble/bluez/device.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module RBLE
+  module BlueZ
+    # Wrapper for BlueZ Device1 D-Bus interface
+    # Provides connection lifecycle management
+    class Device
+      attr_reader :path, :address
+
+      # Create a Device from a DBusSession
+      # @param session [DBusSession] Active D-Bus session
+      # @param device_path [String] D-Bus object path (e.g., /org/bluez/hci0/dev_XX_XX_XX_XX_XX_XX)
+      # @return [Device]
+      def self.new_from_session(session, device_path)
+        device = allocate
+        device.instance_variable_set(:@session, session)
+        device.instance_variable_set(:@path, device_path)
+        device.instance_variable_set(:@address, device.send(:extract_address_from_path, device_path))
+        # Async introspect for non-blocking setup
+        proxy = session.async_introspect(device_path, timeout: 5)
+        device.instance_variable_set(:@object, proxy)
+        device.instance_variable_set(:@device_iface, proxy[DEVICE_INTERFACE])
+        device.instance_variable_set(:@props_iface, proxy[PROPERTIES_INTERFACE])
+        device
+      end
+
+      # Check if device is currently connected
+      # @return [Boolean] true if connected
+      def connected?
+        @session.async_get_property(@path, DEVICE_INTERFACE, 'Connected', timeout: 5)
+      end
+
+      # Check if GATT services have been resolved
+      # @return [Boolean] true if services are resolved
+      def services_resolved?
+        @session.async_get_property(@path, DEVICE_INTERFACE, 'ServicesResolved', timeout: 5)
+      end
+
+      # Get device name from adapter cache
+      # @return [String, nil] device name or nil if not known
+      def name
+        @session.async_get_property(@path, DEVICE_INTERFACE, 'Name', timeout: 5)
+      rescue DBus::Error
+        nil
+      end
+
+      # Connect to device
+      # Waits for connection and optionally for services to resolve
+      # @param wait_for_services [Boolean] Wait for GATT services to be discovered (default: true)
+      # @param timeout [Numeric] Connection timeout in seconds (default: 30)
+      # @return [Boolean] true on success
+      # @raise [ConnectionError] if connection fails
+      # @raise [TimeoutError] if connection times out
+      def connect(wait_for_services: true, timeout: 30)
+        # Async path: handles waiting for connection and services
+        @session.async_connect(@path, wait_for_services: wait_for_services, timeout: timeout)
+      rescue DBus::Error => e
+        raise ConnectionError, "Failed to initiate connection: #{e.message}"
+      end
+
+      # Disconnect from device
+      # @param timeout [Numeric] Timeout in seconds (default: 5)
+      # @return [Boolean] true on success
+      # @raise [ConnectionError] if disconnect fails
+      def disconnect(timeout: 5)
+        # Async path: idempotent disconnect
+        @session.async_disconnect(@path, timeout: timeout)
+      rescue DBus::Error => e
+        raise ConnectionError, "Failed to disconnect: #{e.message}"
+      end
+
+      private
+
+      # Extract MAC address from D-Bus object path
+      # @param path [String] e.g., /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF
+      # @return [String] MAC address (e.g., AA:BB:CC:DD:EE:FF) or 'UNKNOWN'
+      def extract_address_from_path(path)
+        if 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('_', ':').upcase
+        else
+          'UNKNOWN'
+        end
+      end
+    end
+  end
+end

data/lib/rble/bluez/event_loop.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module RBLE
+  module BlueZ
+    # Event types for queue communication
+    Event = Data.define(:type, :path, :data) do
+      def initialize(type:, path: nil, data: nil)
+        super
+      end
+    end
+
+    # Runs D-Bus main loop in background thread, marshals events via Queue
+    class EventLoop
+      attr_reader :queue
+
+      def initialize
+        @queue = Thread::Queue.new
+        @main_loop = nil
+        @thread = nil
+        @running = false
+        @mutex = Mutex.new
+      end
+
+      # Start the event loop in a background thread
+      # @param bus [DBus::SystemBus] The D-Bus bus to run
+      def start(bus)
+        @mutex.synchronize do
+          return if @running
+
+          @running = true
+        end
+
+        @main_loop = DBus::Main.new
+        @main_loop << bus
+
+        @thread = Thread.new do
+          Thread.current.name = 'rble-dbus-loop'
+          begin
+            # DBus::Main.run blocks until quit is called
+            # Signal handlers registered on the bus will be dispatched
+            @main_loop.run
+          rescue StandardError => e
+            enqueue(:error, nil, { exception: e })
+          ensure
+            @mutex.synchronize { @running = false }
+          end
+        end
+
+        # Give the thread a moment to start
+        sleep(0.05)
+      end
+
+      # Stop the event loop and wait for thread to finish
+      # @param timeout [Numeric] Maximum seconds to wait for thread
+      def stop(timeout: 1)
+        was_running = @mutex.synchronize do
+          return unless @running
+
+          @running = false
+          true
+        end
+
+        return unless was_running
+
+        # Tell DBus::Main to exit its run loop
+        @main_loop&.quit
+
+        # Signal any blocked queue readers
+        enqueue(:shutdown, nil, nil)
+
+        # Skip join if called from within the event loop thread itself
+        # (e.g., during disconnect callback handling)
+        if @thread&.alive? && @thread != Thread.current
+          @thread.join(timeout)
+          @thread.kill if @thread.alive? # Force kill if still running
+        end
+
+        @thread = nil
+        @main_loop = nil
+
+        # Drain the queue
+        @queue.clear
+      end
+
+      # Check if event loop is running
+      # @return [Boolean]
+      def running?
+        @mutex.synchronize { @running }
+      end
+
+      # Enqueue an event (called from D-Bus signal handlers)
+      # @param type [Symbol] Event type (:device_found, :device_removed, :properties_changed, :error, :shutdown)
+      # @param path [String, nil] D-Bus object path
+      # @param data [Hash, nil] Event-specific data
+      def enqueue(type, path, data)
+        @queue.push(Event.new(type: type, path: path, data: data))
+      end
+
+      # Process events from the queue with a timeout
+      # Yields each event to the block until shutdown or timeout
+      # @param timeout [Numeric, nil] Timeout in seconds (nil = block forever)
+      # @yield [Event] Called for each event
+      # @return [Boolean] true if shutdown received, false if timeout
+      def process_events(timeout: nil, &block)
+        deadline = timeout ? Time.now + timeout : nil
+
+        loop do
+          # Check deadline before waiting
+          if deadline
+            remaining = deadline - Time.now
+            return false if remaining <= 0
+          else
+            remaining = nil
+          end
+
+          begin
+            # pop with timeout returns nil on timeout (only in Ruby 3.2+)
+            event = if remaining
+                      @queue.pop(timeout: remaining)
+                    else
+                      @queue.pop
+                    end
+          rescue ThreadError
+            # Queue closed
+            return true
+          end
+
+          return false if event.nil? # Timeout
+          return true if event.type == :shutdown
+
+          yield event if block_given?
+        end
+      end
+
+      # Non-blocking drain of all pending events
+      # @yield [Event] Called for each event
+      # @return [Integer] Number of events processed
+      def drain_events(&block)
+        count = 0
+        while (event = @queue.pop(true))
+          break if event.nil? || event.type == :shutdown
+
+          yield event if block_given?
+          count += 1
+        end
+        count
+      rescue ThreadError
+        # Queue empty - expected when draining
+        count
+      end
+    end
+  end
+end