usbkit 0.1.0

data/lib/usbkit/device.rb

@@ -0,0 +1,479 @@
+# frozen_string_literal: true
+
+require "set"
+
+module UsbKit
+  ##
+  # WebUSB-style USB device wrapper.
+  #
+  class Device
+    SETUP_KEYS = %i[request_type recipient request value index].freeze
+
+    # @return [Configuration, nil] currently selected configuration
+    # @return [Array<Configuration>] all known configurations
+    # @return [Integer] device class code
+    # @return [Integer] device subclass code
+    # @return [Integer] device protocol code
+    # @return [Integer] device version components
+    # @return [String, nil] string descriptors
+    # @return [Boolean] whether the device is currently opened
+    # @return [Integer] product identifier
+    # @return [Integer] vendor identifier
+    # @return [Integer, nil] USB bus number
+    # @return [Integer, nil] USB address on the bus
+    attr_reader :configuration,
+                :configurations,
+                :device_class,
+                :device_subclass,
+                :device_protocol,
+                :device_version_major,
+                :device_version_minor,
+                :device_version_subminor,
+                :manufacturer_name,
+                :opened,
+                :product_id,
+                :product_name,
+                :serial_number,
+                :usb_version_major,
+                :usb_version_minor,
+                :usb_version_subminor,
+                :vendor_id,
+                :bus_number,
+                :device_address
+    alias opened? opened
+
+    # @param attrs [Hash]
+    # @return [void]
+    def initialize(attrs)
+      @raw_device = attrs[:raw_device]
+      @vendor_id = attrs.fetch(:vendor_id)
+      @product_id = attrs.fetch(:product_id)
+      @device_class = attrs.fetch(:device_class)
+      @device_subclass = attrs.fetch(:device_subclass)
+      @device_protocol = attrs.fetch(:device_protocol)
+      @device_version_major = attrs.fetch(:device_version_major, 0)
+      @device_version_minor = attrs.fetch(:device_version_minor, 0)
+      @device_version_subminor = attrs.fetch(:device_version_subminor, 0)
+      @manufacturer_name = attrs[:manufacturer_name]
+      @product_name = attrs[:product_name]
+      @serial_number = attrs[:serial_number]
+      @usb_version_major = attrs.fetch(:usb_version_major, 0)
+      @usb_version_minor = attrs.fetch(:usb_version_minor, 0)
+      @usb_version_subminor = attrs.fetch(:usb_version_subminor, 0)
+      @bus_number = attrs[:bus_number]
+      @device_address = attrs[:device_address]
+      @configuration_sources = deep_copy(Array(attrs[:configurations])).freeze
+      @selected_configuration_value = attrs[:configuration_value]
+      @selected_alternates = {}
+      @claimed_interfaces = Set.new
+      @device_handle = nil
+      @opened = false
+      @forgotten = false
+      rebuild_configurations!
+    end
+
+    # Open the device session.
+    #
+    # @raise [DeviceNotFoundError] when the device was forgotten
+    # @return [Device]
+    def open
+      raise DeviceNotFoundError, "Device has been forgotten" if @forgotten
+      return self if opened?
+
+      @device_handle = UsbKit.backend.open_device(@raw_device)
+      @opened = true
+      hydrate_string_descriptors!
+      self
+    end
+
+    # Close the device session and release claimed interfaces.
+    #
+    # @return [nil]
+    def close
+      return nil unless opened?
+
+      @claimed_interfaces.to_a.each do |interface_number|
+        UsbKit.backend.release_interface(@device_handle, interface_number)
+      rescue Error
+        nil
+      end
+
+      UsbKit.backend.close_device(@device_handle)
+      nil
+    ensure
+      @device_handle = nil
+      @opened = false
+      @claimed_interfaces.clear
+      rebuild_configurations!
+    end
+
+    # Forget the device and clear local references.
+    #
+    # @return [Device]
+    def forget
+      close
+      @forgotten = true
+      @raw_device = nil
+      @selected_configuration_value = nil
+      @selected_alternates = {}
+      @configuration_sources = [].freeze
+      rebuild_configurations!
+      self
+    end
+
+    # Run a block with an open device session.
+    #
+    # @yieldparam device [Device]
+    # @raise [ArgumentError] when no block is provided
+    # @return [Object]
+    def with_session
+      raise ArgumentError, "A block is required" unless block_given?
+
+      already_open = opened?
+      open unless already_open
+      yield self
+    ensure
+      close unless already_open
+    end
+
+    # Select a device configuration.
+    #
+    # @param configuration_value [Integer]
+    # @raise [DeviceNotOpenedError, ConfigurationError]
+    # @return [nil]
+    def select_configuration(configuration_value)
+      ensure_open!
+      find_configuration_source!(configuration_value)
+      UsbKit.backend.set_configuration(@device_handle, configuration_value)
+      @selected_configuration_value = configuration_value
+      @claimed_interfaces.clear
+      @selected_alternates = {}
+      rebuild_configurations!
+      nil
+    end
+
+    # Claim an interface for exclusive access.
+    #
+    # @param interface_number [Integer]
+    # @raise [DeviceNotOpenedError, InterfaceError]
+    # @return [nil]
+    def claim_interface(interface_number)
+      ensure_open!
+      find_interface_source!(interface_number)
+      UsbKit.backend.claim_interface(@device_handle, interface_number)
+      @claimed_interfaces.add(interface_number)
+      rebuild_configurations!
+      nil
+    end
+
+    # Release a previously claimed interface.
+    #
+    # @param interface_number [Integer]
+    # @raise [DeviceNotOpenedError, InterfaceError]
+    # @return [nil]
+    def release_interface(interface_number)
+      ensure_open!
+      find_interface_source!(interface_number)
+      UsbKit.backend.release_interface(@device_handle, interface_number)
+      @claimed_interfaces.delete(interface_number)
+      rebuild_configurations!
+      nil
+    end
+
+    # Select an alternate interface setting.
+    #
+    # @param interface_number [Integer]
+    # @param alternate_setting [Integer]
+    # @raise [DeviceNotOpenedError, InterfaceError]
+    # @return [nil]
+    def select_alternate_interface(interface_number, alternate_setting)
+      ensure_open!
+      interface_source = find_interface_source!(interface_number)
+      unless interface_source.fetch(:alternates, []).any? { |alternate| alternate[:alternate_setting] == alternate_setting }
+        raise InterfaceError, "Unknown alternate setting: #{alternate_setting}"
+      end
+
+      UsbKit.backend.set_alternate_interface(@device_handle, interface_number, alternate_setting)
+      @selected_alternates[interface_number] = alternate_setting
+      rebuild_configurations!
+      nil
+    end
+
+    # Perform a control IN transfer.
+    #
+    # @param setup [Hash]
+    # @param length [Integer]
+    # @raise [DeviceNotOpenedError, ArgumentError]
+    # @return [InTransferResult]
+    def control_transfer_in(setup, length)
+      ensure_open!
+      validate_setup!(setup)
+      build_in_transfer_result(UsbKit.backend.control_transfer_in(@device_handle, setup, length))
+    end
+
+    # Perform a control OUT transfer.
+    #
+    # @param setup [Hash]
+    # @param data [String, nil]
+    # @raise [DeviceNotOpenedError, ArgumentError]
+    # @return [OutTransferResult]
+    def control_transfer_out(setup, data = nil)
+      ensure_open!
+      validate_setup!(setup)
+      build_out_transfer_result(UsbKit.backend.control_transfer_out(@device_handle, setup, data))
+    end
+
+    # Perform a bulk or interrupt IN transfer.
+    #
+    # @param endpoint_number [Integer]
+    # @param length [Integer]
+    # @raise [DeviceNotOpenedError]
+    # @return [InTransferResult]
+    def transfer_in(endpoint_number, length)
+      ensure_open!
+      build_in_transfer_result(
+        UsbKit.backend.bulk_transfer_in(@device_handle, endpoint_number, length, timeout: UsbKit.config.transfer_timeout)
+      )
+    end
+
+    # Perform a bulk or interrupt OUT transfer.
+    #
+    # @param endpoint_number [Integer]
+    # @param data [String]
+    # @raise [DeviceNotOpenedError]
+    # @return [OutTransferResult]
+    def transfer_out(endpoint_number, data)
+      ensure_open!
+      build_out_transfer_result(
+        UsbKit.backend.bulk_transfer_out(@device_handle, endpoint_number, data, timeout: UsbKit.config.transfer_timeout)
+      )
+    end
+
+    # Perform an isochronous IN transfer.
+    #
+    # @param endpoint_number [Integer]
+    # @param packet_lengths [Array<Integer>]
+    # @raise [DeviceNotOpenedError, Error]
+    # @return [IsochronousInTransferResult]
+    def isochronous_transfer_in(endpoint_number, packet_lengths)
+      ensure_open!
+      build_isochronous_in_transfer_result(
+        UsbKit.backend.isochronous_transfer_in(@device_handle, endpoint_number, packet_lengths)
+      )
+    rescue NotImplementedError => error
+      raise Error, error.message
+    end
+
+    # Perform an isochronous OUT transfer.
+    #
+    # @param endpoint_number [Integer]
+    # @param data [String]
+    # @param packet_lengths [Array<Integer>]
+    # @raise [DeviceNotOpenedError, Error]
+    # @return [IsochronousOutTransferResult]
+    def isochronous_transfer_out(endpoint_number, data, packet_lengths)
+      ensure_open!
+      build_isochronous_out_transfer_result(
+        UsbKit.backend.isochronous_transfer_out(@device_handle, endpoint_number, data, packet_lengths)
+      )
+    rescue NotImplementedError => error
+      raise Error, error.message
+    end
+
+    # Clear a halted endpoint.
+    #
+    # @param direction [Symbol]
+    # @param endpoint_number [Integer]
+    # @raise [DeviceNotOpenedError, ArgumentError]
+    # @return [nil]
+    def clear_halt(direction, endpoint_number)
+      ensure_open!
+      raise ArgumentError, "Invalid direction: #{direction.inspect}" unless Direction.valid?(direction)
+
+      UsbKit.backend.clear_halt(@device_handle, endpoint_address(direction, endpoint_number))
+      nil
+    end
+
+    # Reset the device.
+    #
+    # @raise [DeviceNotOpenedError]
+    # @return [nil]
+    def reset
+      ensure_open!
+      UsbKit.backend.reset_device(@device_handle)
+      nil
+    end
+
+    # Build an async proxy bound to this device.
+    #
+    # @return [Async::AsyncProxy]
+    def async
+      require_relative "async"
+      Async::AsyncProxy.new(self)
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        configuration: configuration&.to_h,
+        configurations: configurations.map(&:to_h),
+        device_class: device_class,
+        device_subclass: device_subclass,
+        device_protocol: device_protocol,
+        device_version_major: device_version_major,
+        device_version_minor: device_version_minor,
+        device_version_subminor: device_version_subminor,
+        manufacturer_name: manufacturer_name,
+        opened: opened?,
+        product_id: product_id,
+        product_name: product_name,
+        serial_number: serial_number,
+        usb_version_major: usb_version_major,
+        usb_version_minor: usb_version_minor,
+        usb_version_subminor: usb_version_subminor,
+        vendor_id: vendor_id,
+        bus_number: bus_number,
+        device_address: device_address
+      }
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} vendor_id=0x#{vendor_id.to_s(16).rjust(4, '0')} " \
+        "product_id=0x#{product_id.to_s(16).rjust(4, '0')} opened=#{opened?.inspect}>"
+    end
+
+    private
+
+    def ensure_open!
+      return if opened?
+
+      raise DeviceNotOpenedError, "Device must be opened before performing USB operations"
+    end
+
+    def rebuild_configurations!
+      @configurations = @configuration_sources.map { |source| build_configuration(source) }.freeze
+      @configuration = @configurations.find do |candidate|
+        candidate.configuration_value == @selected_configuration_value
+      end
+    end
+
+    def build_configuration(source)
+      Configuration.new(
+        {
+          configuration_value: source[:configuration_value],
+          configuration_name: source[:configuration_name],
+          interfaces: Array(source[:interfaces]).map { |interface| build_interface(interface) }
+        },
+        device: self
+      )
+    end
+
+    def build_interface(source)
+      Interface.new(
+        interface_number: source[:interface_number],
+        alternates: Array(source[:alternates]).map { |alternate| build_alternate(alternate) },
+        alternate_setting: selected_alternate_for(source),
+        claimed: @claimed_interfaces.include?(source[:interface_number])
+      )
+    end
+
+    def build_alternate(source)
+      AlternateInterface.new(
+        alternate_setting: source[:alternate_setting],
+        interface_class: source.fetch(:interface_class, 0),
+        interface_subclass: source.fetch(:interface_subclass, 0),
+        interface_protocol: source.fetch(:interface_protocol, 0),
+        interface_name: source[:interface_name],
+        endpoints: Array(source[:endpoints]).map { |endpoint| endpoint.is_a?(Endpoint) ? endpoint : Endpoint.new(endpoint) }
+      )
+    end
+
+    def selected_alternate_for(source)
+      @selected_alternates.fetch(source[:interface_number], source[:alternate_setting])
+    end
+
+    def find_configuration_source!(configuration_value)
+      @configuration_sources.find { |source| source[:configuration_value] == configuration_value } ||
+        raise(ConfigurationError, "Unknown configuration value: #{configuration_value}")
+    end
+
+    def find_interface_source!(interface_number)
+      configuration_source = @configuration_sources.find do |source|
+        source[:configuration_value] == @selected_configuration_value
+      end || @configuration_sources.first
+
+      interfaces = Array(configuration_source&.fetch(:interfaces, []))
+      interfaces.find { |source| source[:interface_number] == interface_number } ||
+        raise(InterfaceError, "Unknown interface number: #{interface_number}")
+    end
+
+    def validate_setup!(setup)
+      raise ArgumentError, "setup must be a Hash" unless setup.is_a?(Hash)
+
+      missing_keys = SETUP_KEYS - setup.keys
+      raise ArgumentError, "Missing setup keys: #{missing_keys.inspect}" unless missing_keys.empty?
+
+      extra_keys = setup.keys - SETUP_KEYS
+      raise ArgumentError, "Unknown setup keys: #{extra_keys.inspect}" unless extra_keys.empty?
+      raise ArgumentError, "Invalid request type: #{setup[:request_type].inspect}" unless RequestType.valid?(setup[:request_type])
+      raise ArgumentError, "Invalid recipient: #{setup[:recipient].inspect}" unless Recipient.valid?(setup[:recipient])
+
+      %i[request value index].each do |key|
+        raise ArgumentError, "#{key} must be an Integer" unless setup[key].is_a?(Integer)
+      end
+    end
+
+    def endpoint_address(direction, endpoint_number)
+      endpoint_number | (direction == :in ? 0x80 : 0x00)
+    end
+
+    def build_in_transfer_result(result)
+      return result if result.is_a?(InTransferResult)
+      return InTransferResult.new(status: TransferStatus.OK, data: result) if result.is_a?(String)
+
+      InTransferResult.new(result)
+    end
+
+    def build_out_transfer_result(result)
+      return result if result.is_a?(OutTransferResult)
+      return OutTransferResult.new(status: TransferStatus.OK, bytes_written: result) if result.is_a?(Integer)
+
+      OutTransferResult.new(result)
+    end
+
+    def build_isochronous_in_transfer_result(result)
+      return result if result.is_a?(IsochronousInTransferResult)
+
+      IsochronousInTransferResult.new(result)
+    end
+
+    def build_isochronous_out_transfer_result(result)
+      return result if result.is_a?(IsochronousOutTransferResult)
+
+      IsochronousOutTransferResult.new(result)
+    end
+
+    def hydrate_string_descriptors!
+      return unless @device_handle
+
+      %i[manufacturer_name product_name serial_number].each do |attribute|
+        next unless @device_handle.respond_to?(attribute)
+        next if instance_variable_get(:"@#{attribute}")
+
+        instance_variable_set(:"@#{attribute}", @device_handle.public_send(attribute))
+      end
+    end
+
+    def deep_copy(value)
+      case value
+      when Array
+        value.map { |item| deep_copy(item) }
+      when Hash
+        value.each_with_object({}) { |(key, item), copy| copy[key] = deep_copy(item) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/usbkit/endpoint.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module UsbKit
+  ##
+  # Immutable USB endpoint descriptor.
+  #
+  class Endpoint
+    # @return [Integer] endpoint number without direction bit
+    # @return [Symbol] transfer direction
+    # @return [Symbol] endpoint type
+    # @return [Integer] packet size in bytes
+    attr_reader :endpoint_number, :direction, :type, :packet_size
+
+    # @param attrs [Hash]
+    # @raise [ArgumentError] when direction or type is invalid
+    # @return [void]
+    def initialize(attrs)
+      @endpoint_number = attrs.fetch(:endpoint_number)
+      @direction = validate_direction(attrs.fetch(:direction))
+      @type = validate_type(attrs.fetch(:type))
+      @packet_size = attrs.fetch(:packet_size)
+      freeze
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        endpoint_number: endpoint_number,
+        direction: direction,
+        type: type,
+        packet_size: packet_size
+      }
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} #{to_h.map { |key, value| "#{key}=#{value.inspect}" }.join(' ')}>"
+    end
+
+    private
+
+    def validate_direction(direction)
+      return direction if Direction.valid?(direction)
+
+      raise ArgumentError, "Invalid direction: #{direction.inspect}"
+    end
+
+    def validate_type(type)
+      return type if EndpointType.valid?(type)
+
+      raise ArgumentError, "Invalid endpoint type: #{type.inspect}"
+    end
+  end
+end

data/lib/usbkit/errors.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module UsbKit
+  ##
+  # Base UsbKit error.
+  #
+  class Error < StandardError; end
+
+  ##
+  # Raised when no device matches the requested filters.
+  #
+  class DeviceNotFoundError < Error; end
+
+  ##
+  # Raised for permissions and access failures.
+  #
+  class DeviceAccessError < Error; end
+
+  ##
+  # Raised when a device or interface is already in use.
+  #
+  class DeviceBusyError < Error; end
+
+  ##
+  # Raised when an operation requires an open device session.
+  #
+  class DeviceNotOpenedError < Error; end
+
+  ##
+  # Raised for USB transfer failures.
+  #
+  class TransferError < Error
+    # @return [Symbol, nil] transfer failure status
+    attr_reader :status
+
+    # @param message [String]
+    # @param status [Symbol, nil]
+    # @return [void]
+    def initialize(message = "Transfer failed", status: nil)
+      @status = status
+      super(message)
+    end
+  end
+
+  ##
+  # Raised when selecting a configuration fails.
+  #
+  class ConfigurationError < Error; end
+
+  ##
+  # Raised when claiming or selecting interfaces fails.
+  #
+  class InterfaceError < Error; end
+
+  ##
+  # Raised when no backend can satisfy the request.
+  #
+  class BackendNotAvailableError < Error; end
+
+  ##
+  # Raised when a transfer exceeds its timeout budget.
+  #
+  class TimeoutError < TransferError
+    # @param message [String]
+    # @param status [Symbol]
+    # @return [void]
+    def initialize(message = "Transfer timed out", status: :timeout)
+      super(message, status: status)
+    end
+  end
+end

data/lib/usbkit/filter.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module UsbKit
+  ##
+  # WebUSB-style device filter matcher.
+  #
+  class Filter
+    ALLOWED_KEYS = %i[vendor_id product_id class_code subclass_code protocol_code serial_number].freeze
+
+    KEY_MAP = {
+      vendor_id: :vendor_id,
+      product_id: :product_id,
+      class_code: :device_class,
+      subclass_code: :device_subclass,
+      protocol_code: :device_protocol,
+      serial_number: :serial_number
+    }.freeze
+
+    # @param filters [Array<Hash>]
+    # @raise [ArgumentError] when a filter contains unsupported keys
+    # @return [void]
+    def initialize(filters)
+      @filters = Array(filters).map { |filter| validate_and_normalize(filter) }.freeze
+    end
+
+    # @param device_attrs [Hash]
+    # @return [Boolean]
+    def match?(device_attrs)
+      return true if @filters.empty?
+
+      @filters.any? { |filter| filter_matches?(filter, device_attrs) }
+    end
+
+    private
+
+    def validate_and_normalize(filter)
+      raise ArgumentError, "Filter must be a Hash" unless filter.is_a?(Hash)
+
+      unknown_keys = filter.keys - ALLOWED_KEYS
+      raise ArgumentError, "Unknown filter keys: #{unknown_keys.inspect}" unless unknown_keys.empty?
+
+      filter.each_with_object({}) do |(key, value), normalized|
+        normalized[KEY_MAP.fetch(key)] = value
+      end.freeze
+    end
+
+    def filter_matches?(filter, attrs)
+      filter.all? { |key, value| attrs[key] == value }
+    end
+  end
+end

data/lib/usbkit/interface.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module UsbKit
+  ##
+  # Immutable USB interface descriptor.
+  #
+  class Interface
+    # @return [Integer] interface number
+    # @return [AlternateInterface, nil] currently selected alternate
+    # @return [Array<AlternateInterface>] available alternates
+    # @return [Boolean] whether the interface is claimed
+    attr_reader :interface_number, :alternate, :alternates, :claimed
+    alias claimed? claimed
+
+    # @param attrs [Hash]
+    # @return [void]
+    def initialize(attrs)
+      @interface_number = attrs.fetch(:interface_number)
+      @alternates = Array(attrs.fetch(:alternates, [])).map { |alternate| build_alternate(alternate) }.freeze
+      @alternate = resolve_alternate(attrs[:alternate_setting])
+      @claimed = attrs.fetch(:claimed, false)
+      freeze
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        interface_number: interface_number,
+        claimed: claimed,
+        alternate_setting: alternate&.alternate_setting,
+        alternates: alternates.map(&:to_h)
+      }
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} interface_number=#{interface_number.inspect} claimed=#{claimed.inspect}>"
+    end
+
+    private
+
+    def build_alternate(alternate)
+      alternate.is_a?(AlternateInterface) ? alternate : AlternateInterface.new(alternate)
+    end
+
+    def resolve_alternate(selected_setting)
+      return alternates.first if selected_setting.nil?
+
+      alternates.find { |alternate| alternate.alternate_setting == selected_setting } || alternates.first
+    end
+  end
+end