usbkit 0.1.0

data/lib/usbkit/constants.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module UsbKit
+  ##
+  # Direction enum used by endpoints and transfers.
+  #
+  module Direction
+    IN = :in
+    OUT = :out
+
+    ALL = [IN, OUT].freeze
+
+    # @param value [Object]
+    # @return [Boolean]
+    def self.valid?(value)
+      ALL.include?(value)
+    end
+  end
+
+  ##
+  # Endpoint transfer type enum.
+  #
+  module EndpointType
+    BULK = :bulk
+    INTERRUPT = :interrupt
+    ISOCHRONOUS = :isochronous
+
+    ALL = [BULK, INTERRUPT, ISOCHRONOUS].freeze
+
+    # @param value [Object]
+    # @return [Boolean]
+    def self.valid?(value)
+      ALL.include?(value)
+    end
+  end
+
+  ##
+  # Control transfer request type enum.
+  #
+  module RequestType
+    STANDARD = :standard
+    CLASS = :class
+    VENDOR = :vendor
+
+    ALL = [STANDARD, CLASS, VENDOR].freeze
+
+    # @param value [Object]
+    # @return [Boolean]
+    def self.valid?(value)
+      ALL.include?(value)
+    end
+  end
+
+  ##
+  # Control transfer recipient enum.
+  #
+  module Recipient
+    DEVICE = :device
+    INTERFACE = :interface
+    ENDPOINT = :endpoint
+    OTHER = :other
+
+    ALL = [DEVICE, INTERFACE, ENDPOINT, OTHER].freeze
+
+    # @param value [Object]
+    # @return [Boolean]
+    def self.valid?(value)
+      ALL.include?(value)
+    end
+  end
+
+  ##
+  # Transfer status enum.
+  #
+  module TransferStatus
+    OK = :ok
+    STALL = :stall
+    BABBLE = :babble
+
+    ALL = [OK, STALL, BABBLE].freeze
+
+    # @param value [Object]
+    # @return [Boolean]
+    def self.valid?(value)
+      ALL.include?(value)
+    end
+  end
+end

data/lib/usbkit/context.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module UsbKit
+  ##
+  # Entry point for WebUSB-style device discovery and monitoring.
+  #
+  class Context
+    EVENT_TYPES = %i[connect disconnect].freeze
+
+    # @param backend [Backend::Base]
+    # @param config [GemConfiguration]
+    # @return [void]
+    def initialize(backend: UsbKit.backend, config: UsbKit.config)
+      @backend = backend
+      @config = config
+      @callbacks = Hash.new { |hash, key| hash[key] = [] }
+      @mutex = Mutex.new
+      @monitoring = false
+      @monitor_thread = nil
+      @snapshot = {}
+    end
+
+    # Enumerate visible devices.
+    #
+    # @param filters [Array<Hash>, nil]
+    # @return [Array<Device>]
+    def get_devices(filters: nil)
+      devices = enumerate_visible_devices
+      return devices if filters.nil?
+
+      matcher = Filter.new(filters)
+      devices.select { |device| matcher.match?(device.to_h) }
+    end
+
+    # Return the first device that matches the provided filters.
+    #
+    # @param filters [Array<Hash>]
+    # @raise [ArgumentError] when filters are missing
+    # @raise [DeviceNotFoundError] when no device matches
+    # @return [Device]
+    def request_device(filters:)
+      raise ArgumentError, "filters are required" if filters.nil? || Array(filters).empty?
+
+      matcher = Filter.new(filters)
+      device = enumerate_visible_devices.find { |candidate| matcher.match?(candidate.to_h) }
+      return device if device
+
+      raise DeviceNotFoundError, "No USB device matched the provided filters"
+    end
+
+    # Register a connection lifecycle callback.
+    #
+    # @param event_type [Symbol] :connect or :disconnect
+    # @yieldparam event [ConnectionEvent]
+    # @raise [ArgumentError] when the event type or block is invalid
+    # @return [Context]
+    def on(event_type, &block)
+      raise ArgumentError, "Unsupported event type: #{event_type.inspect}" unless EVENT_TYPES.include?(event_type)
+      raise ArgumentError, "A block is required" unless block
+
+      @mutex.synchronize do
+        @callbacks[event_type] << block
+      end
+
+      self
+    end
+
+    # Start polling for device changes in a background thread.
+    #
+    # @param interval [Float] polling interval in seconds
+    # @return [Thread]
+    def start_event_monitoring(interval: 1.0)
+      @mutex.synchronize do
+        return @monitor_thread if @monitor_thread&.alive?
+
+        @snapshot = build_snapshot(enumerate_visible_devices)
+        @monitoring = true
+        @monitor_thread = Thread.new do
+          monitor_devices(interval)
+        end
+      end
+    end
+
+    # Stop the event-monitoring thread.
+    #
+    # @return [nil]
+    def stop_event_monitoring
+      thread = @mutex.synchronize do
+        @monitoring = false
+        thread = @monitor_thread
+        @monitor_thread = nil
+        thread
+      end
+
+      thread&.join unless thread == Thread.current
+      nil
+    end
+
+    private
+
+    def enumerate_visible_devices
+      Array(@backend.enumerate_devices).filter_map do |attributes|
+        next if blocked_device?(attributes)
+
+        Device.new(attributes)
+      end
+    end
+
+    def blocked_device?(attributes)
+      @config.blocked_classes.include?(attributes[:device_class])
+    end
+
+    def build_snapshot(devices)
+      devices.each_with_object({}) do |device, snapshot|
+        snapshot[device_identifier(device)] = device
+      end
+    end
+
+    def device_identifier(device)
+      attrs = device.to_h
+      [
+        attrs[:vendor_id],
+        attrs[:product_id],
+        attrs[:serial_number],
+        attrs[:bus_number],
+        attrs[:device_address]
+      ]
+    end
+
+    def monitor_devices(interval)
+      loop do
+        break unless monitoring?
+
+        current_devices = enumerate_visible_devices
+        current_snapshot = build_snapshot(current_devices)
+        dispatch_snapshot_changes(current_snapshot)
+        @mutex.synchronize do
+          @snapshot = current_snapshot
+        end
+        sleep interval
+      rescue StandardError
+        sleep interval
+      end
+    end
+
+    def dispatch_snapshot_changes(current_snapshot)
+      previous_snapshot = @mutex.synchronize { @snapshot.dup }
+
+      (current_snapshot.keys - previous_snapshot.keys).each do |identifier|
+        dispatch(:connect, current_snapshot.fetch(identifier))
+      end
+
+      (previous_snapshot.keys - current_snapshot.keys).each do |identifier|
+        dispatch(:disconnect, previous_snapshot.fetch(identifier))
+      end
+    end
+
+    def dispatch(event_type, device)
+      callbacks = @mutex.synchronize { @callbacks[event_type].dup }
+      event = ConnectionEvent.new(type: event_type, device: device)
+      callbacks.each { |callback| callback.call(event) }
+    end
+
+    def monitoring?
+      @mutex.synchronize { @monitoring }
+    end
+  end
+end