rble 0.7.0

data/lib/rble/backend.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require_relative 'backend/base'
+require_relative 'errors'
+
+module RBLE
+  module Backend
+    @backend_mutex = Mutex.new
+    @backend_symbol = nil        # :bluez, :corebluetooth
+    @backend_instance = nil      # The actual backend object
+    @backend_frozen = false      # Locked after first BLE operation
+
+    # Returns the current backend symbol
+    # @return [Symbol] :bluez or :corebluetooth
+    def self.backend
+      @backend_mutex.synchronize do
+        ensure_backend_selected
+        @backend_symbol
+      end
+    end
+
+    # Set the backend to use (before first BLE operation)
+    # @param value [Symbol, String] Backend name (:bluez, :corebluetooth)
+    # @raise [BackendAlreadySelectedError] if backend already frozen
+    # @raise [ArgumentError] if backend is invalid for platform
+    # @raise [BackendUnavailableError] if backend is unavailable
+    def self.backend=(value)
+      @backend_mutex.synchronize do
+        if @backend_frozen
+          raise BackendAlreadySelectedError,
+                "Cannot change backend after BLE operations. Current: #{@backend_symbol}"
+        end
+        perform_backend_selection(value)
+      end
+    end
+
+    # Get backend information
+    # @return [Hash] { name: Symbol, version: String, capabilities: Array }
+    def self.backend_info
+      {
+        name: backend,
+        version: backend_version,
+        capabilities: backend_capabilities
+      }
+    end
+
+    # List available backends for the current platform
+    # @return [Array<Symbol>] Available backend symbols
+    def self.available_backends
+      case RUBY_PLATFORM
+      when /darwin/
+        [:corebluetooth]
+      when /linux/
+        [:bluez]
+      else
+        []
+      end
+    end
+
+    # Returns the appropriate backend for the current platform (singleton)
+    # @return [Backend::Base] Platform-specific backend instance
+    # @raise [Error] if platform is not supported
+    def self.for_platform
+      backend_instance
+    end
+
+    # Reset the singleton instance (for testing)
+    # @api private
+    def self.reset!
+      @backend_mutex.synchronize do
+        @backend_instance&.shutdown if @backend_instance.respond_to?(:shutdown)
+        @backend_instance = nil
+        @backend_symbol = nil
+        @backend_frozen = false
+      end
+    end
+
+    class << self
+      private
+
+      # Ensure a backend is selected (lazy selection)
+      # Must be called within @backend_mutex.synchronize
+      def ensure_backend_selected
+        return if @backend_symbol
+
+        # Check ENV override first (highest priority)
+        env_backend = ENV['RBLE_BACKEND']
+        if env_backend && !env_backend.empty?
+          perform_backend_selection(env_backend)
+        else
+          perform_backend_selection(platform_default)
+        end
+      end
+
+      # Get the default backend for the current platform
+      # @return [Symbol] Default backend symbol
+      # @raise [Error] if platform is not supported
+      def platform_default
+        case RUBY_PLATFORM
+        when /darwin/
+          :corebluetooth
+        when /linux/
+          :bluez
+        else
+          raise Error, "Unsupported platform: #{RUBY_PLATFORM}"
+        end
+      end
+
+      # Perform backend selection with validation
+      # Must be called within @backend_mutex.synchronize
+      # @param value [Symbol, String] Backend name
+      def perform_backend_selection(value)
+        sym = normalize_backend(value)
+        validate_platform_compatibility!(sym)
+        validate_backend_availability!(sym)
+        @backend_symbol = sym
+        @backend_instance = nil # Lazy load
+      end
+
+      # Normalize backend value to symbol
+      # @param value [Symbol, String] Backend name
+      # @return [Symbol] Normalized backend symbol
+      def normalize_backend(value)
+        value.to_s.downcase.to_sym
+      end
+
+      # Validate backend is compatible with current platform
+      # @param sym [Symbol] Backend symbol
+      # @raise [ArgumentError] if backend is invalid for platform
+      def validate_platform_compatibility!(sym)
+        available = available_backends
+        return if available.include?(sym)
+
+        platform_name = case RUBY_PLATFORM
+                        when /darwin/ then 'macOS'
+                        when /linux/ then 'Linux'
+                        else RUBY_PLATFORM
+                        end
+
+        raise ArgumentError,
+              "Backend :#{sym} not available on #{platform_name}. Available: #{available.map { |b| ":#{b}" }.join(', ')}"
+      end
+
+      # Validate backend can be used
+      # @param sym [Symbol] Backend symbol
+      # @raise [BackendUnavailableError] if backend is unavailable
+      def validate_backend_availability!(sym)
+        # :bluez and :corebluetooth validated at use time
+      end
+
+      # Get or create backend instance
+      # @return [Backend::Base] Backend instance
+      def backend_instance
+        @backend_mutex.synchronize do
+          ensure_backend_selected
+          @backend_instance ||= load_backend(@backend_symbol)
+          @backend_frozen = true
+          @backend_instance
+        end
+      end
+
+      # Create backend instance
+      # @param sym [Symbol] Backend symbol
+      # @return [Backend::Base] Backend instance
+      def load_backend(sym)
+        case sym
+        when :bluez
+          require_relative 'backend/bluez'
+          BlueZ.new
+        when :corebluetooth
+          require_relative 'backend/corebluetooth'
+          CoreBluetooth.new
+        else
+          raise Error, "Unknown backend: #{sym}"
+        end
+      end
+
+      # Get backend version
+      # @return [String] Version string or 'unknown'
+      def backend_version
+        inst = backend_instance
+        inst.respond_to?(:version) ? inst.version : 'unknown'
+      end
+
+      # Get backend capabilities
+      # @return [Array] Capabilities array or empty array
+      def backend_capabilities
+        inst = backend_instance
+        inst.respond_to?(:capabilities) ? inst.capabilities : []
+      end
+    end
+  end
+end

data/lib/rble/bluez/adapter.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module RBLE
+  module BlueZ
+    # Wraps a BlueZ Bluetooth adapter (org.bluez.Adapter1)
+    class Adapter
+      attr_reader :path, :name
+
+      # Create an Adapter from a DBusSession
+      # @param session [DBusSession] Active D-Bus session
+      # @param path [String] D-Bus object path (e.g., "/org/bluez/hci0")
+      # @return [Adapter]
+      def self.new_from_session(session, path)
+        adapter = allocate
+        adapter.instance_variable_set(:@session, session)
+        adapter.instance_variable_set(:@path, path)
+        adapter.instance_variable_set(:@name, path.split('/').last)
+        # Async introspect for non-blocking setup
+        proxy = session.async_introspect(path, timeout: 5)
+        adapter.instance_variable_set(:@object, proxy)
+        adapter.instance_variable_set(:@adapter_iface, proxy[ADAPTER_INTERFACE])
+        adapter.instance_variable_set(:@properties_iface, proxy[PROPERTIES_INTERFACE])
+        adapter
+      end
+
+      # Get adapter MAC address
+      # @return [String]
+      def address
+        @session.async_get_property(@path, ADAPTER_INTERFACE, 'Address', timeout: 5)
+      end
+
+      # Check if adapter is powered on
+      # @return [Boolean]
+      def powered?
+        @session.async_get_property(@path, ADAPTER_INTERFACE, 'Powered', timeout: 5)
+      end
+
+      # Check if discovery is in progress
+      # @return [Boolean]
+      def discovering?
+        @session.async_get_property(@path, ADAPTER_INTERFACE, 'Discovering', timeout: 5)
+      end
+
+      # Check if adapter is discoverable
+      # @return [Boolean]
+      def discoverable?
+        @session.async_get_property(@path, ADAPTER_INTERFACE, 'Discoverable', timeout: 5)
+      end
+
+      # Check if adapter is pairable
+      # @return [Boolean]
+      def pairable?
+        @session.async_get_property(@path, ADAPTER_INTERFACE, 'Pairable', timeout: 5)
+      end
+
+      # Get adapter alias (friendly name)
+      # @return [String]
+      def alias_name
+        @session.async_get_property(@path, ADAPTER_INTERFACE, 'Alias', timeout: 5)
+      end
+
+      # Set adapter power state
+      # @param value [Boolean] true to power on, false to power off
+      def set_powered(value)
+        @session.async_set_property(@path, ADAPTER_INTERFACE, 'Powered', value, timeout: 5)
+      end
+
+      # Set adapter discoverable mode
+      # @param value [Boolean] true to enable, false to disable
+      def set_discoverable(value)
+        @session.async_set_property(@path, ADAPTER_INTERFACE, 'Discoverable', value, timeout: 5)
+      end
+
+      # Set adapter pairable mode
+      # @param value [Boolean] true to enable, false to disable
+      def set_pairable(value)
+        @session.async_set_property(@path, ADAPTER_INTERFACE, 'Pairable', value, timeout: 5)
+      end
+
+      # Set adapter alias (friendly name)
+      # @param name [String] New alias
+      def set_alias(name)
+        @session.async_set_property(@path, ADAPTER_INTERFACE, 'Alias', name, timeout: 5)
+      end
+
+      # Set discovery filter before starting scan
+      # @param service_uuids [Array<String>, nil] Filter by these UUIDs
+      # @param allow_duplicates [Boolean] Receive every advertisement
+      # @param rssi [Integer, nil] Minimum RSSI value
+      # @param pathloss [Integer, nil] Maximum path loss
+      def set_discovery_filter(service_uuids: nil, allow_duplicates: false, rssi: nil, pathloss: nil)
+        # Build filter options for async method
+        filter_options = {
+          transport: 'le',
+          duplicate_data: allow_duplicates
+        }
+
+        # Add optional filters
+        if service_uuids && !service_uuids.empty?
+          filter_options[:uuids] = service_uuids.map { |uuid| normalize_uuid(uuid) }
+        end
+        filter_options[:rssi] = rssi if rssi
+        filter_options[:pathloss] = pathloss if pathloss
+
+        # Store filter for application in start_discovery via async_start_discovery
+        @pending_filter = filter_options
+      rescue DBus::Error => e
+        raise ScanError, "Failed to set discovery filter: #{e.message}"
+      end
+
+      # Start BLE discovery
+      def start_discovery
+        # Async path: idempotent, handles powered? check internally
+        filter = @pending_filter || { transport: 'le' }
+        @session.async_start_discovery(@path, filter: filter, timeout: 10)
+        @pending_filter = nil
+      rescue DBus::Error => e
+        if e.message.include?('InProgress')
+          raise ScanInProgressError
+        elsif e.message.include?('NotReady') || e.message.include?('NotPowered')
+          raise AdapterDisabledError.new(@name)
+        end
+        raise ScanError, "Failed to start discovery: #{e.message}"
+      end
+
+      # Stop BLE discovery
+      def stop_discovery
+        # Async path: idempotent, no need to check discovering?
+        @session.async_stop_discovery(@path, timeout: 10)
+      rescue DBus::Error => e
+        # Ignore "not discovering" errors during cleanup
+        unless e.message.include?('NotAuthorized') || e.message.include?('NotDiscovering')
+          raise ScanError, "Failed to stop discovery: #{e.message}"
+        end
+      end
+
+      # Get adapter info as hash
+      # @return [Hash] with adapter properties
+      def to_h
+        {
+          name: @name,
+          address: address,
+          powered: powered?,
+          discoverable: discoverable?,
+          pairable: pairable?,
+          alias: alias_name,
+          discovering: discovering?
+        }
+      end
+
+      private
+
+      # Normalize UUID to BlueZ format (lowercase, with hyphens for 128-bit)
+      def normalize_uuid(uuid)
+        uuid = uuid.to_s.downcase.delete('-')
+
+        # 16-bit UUIDs (4 hex chars) stay short
+        return uuid if uuid.length == 4
+
+        # 32-bit and 128-bit get full format with hyphens
+        if uuid.length == 32
+          "#{uuid[0..7]}-#{uuid[8..11]}-#{uuid[12..15]}-#{uuid[16..19]}-#{uuid[20..31]}"
+        else
+          uuid
+        end
+      end
+    end
+  end
+end

data/lib/rble/bluez/async_call.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'dbus'
+require 'securerandom'
+
+module RBLE
+  module BlueZ
+    # Provides async D-Bus call wrapper with Queue-based result delivery.
+    # Use this to make D-Bus method calls without blocking the event loop.
+    #
+    # This module is the foundation for the v0.4.0 async architecture. By routing
+    # D-Bus method call results through Thread::Queue instead of blocking on the
+    # D-Bus socket, we eliminate the conflict between DBus::Main and synchronous calls.
+    #
+    # @example
+    #   include AsyncCall
+    #
+    #   result = async_call('ReadValue', timeout: 5) do |queue, request_id, cancelled|
+    #     proxy.ReadValue({}) do |reply, *params|
+    #       next if cancelled[0]  # Discard late callback
+    #       if reply.is_a?(DBus::Error)
+    #         queue.push([reply, nil])
+    #       else
+    #         queue.push([reply, params])
+    #       end
+    #     end
+    #   end
+    #
+    module AsyncCall
+      # Count of late callbacks received after timeout (for metrics)
+      attr_reader :late_callback_count
+      # Execute a D-Bus call asynchronously with Queue-based result delivery
+      #
+      # @param operation [String] Operation name for logging/errors
+      # @param timeout [Numeric] Timeout in seconds (default: 5)
+      # @yield [queue, request_id, cancelled] Block that performs async D-Bus call
+      # @yieldparam queue [Thread::Queue] Push [reply, params] to deliver result
+      # @yieldparam request_id [String] Request ID for log correlation
+      # @yieldparam cancelled [Array<Boolean>] Mutable container - check cancelled[0] before pushing
+      # @return [Array, nil] Method call result params
+      # @raise [TimeoutError] if timeout exceeded
+      # @raise [SessionClosedError] if session closed while operation pending
+      # @raise [DBus::Error] propagated from D-Bus (for caller to translate)
+      def async_call(operation, timeout: 5)
+        queue = Thread::Queue.new
+        request_id = SecureRandom.hex(4)
+        start_time = Time.now
+        cancelled = [false]  # Mutable container for cancellation state
+
+        # Track queue for shutdown notification (if @pending_queues exists)
+        @pending_queues&.push(queue)
+
+        RBLE.logger&.debug("[RBLE] #{request_id} Starting #{operation}")
+        warn "      [RBLE] #{request_id} #{operation} timeout=#{timeout.round(2)}s" if RBLE.trace
+
+        yield(queue, request_id, cancelled)
+
+        result = queue.pop(timeout: timeout)
+        elapsed = Time.now - start_time
+        warn "      [RBLE] #{request_id} #{operation} -> #{result.nil? ? 'TIMEOUT' : 'ok'} (#{elapsed.round(2)}s)" if RBLE.trace
+
+        if result.nil?
+          cancelled[0] = true
+          @late_callback_count = (@late_callback_count || 0) + 1
+          RBLE.logger&.warn("[RBLE] #{request_id} #{operation} timed out after #{elapsed.round(3)}s (late callbacks: #{@late_callback_count})")
+          raise TimeoutError.new(operation, timeout)
+        end
+
+        # Check for session close marker
+        if result.is_a?(Array) && result.first == :session_closed
+          raise SessionClosedError.new
+        end
+
+        RBLE.logger&.debug("[RBLE] #{request_id} #{operation} completed in #{elapsed.round(3)}s")
+
+        reply, params = result
+        raise reply if reply.is_a?(DBus::Error)
+
+        params
+      ensure
+        @pending_queues&.delete(queue)
+      end
+    end
+  end
+end