nl 0.2.4 → 0.4.1

data/lib/nl/attribute_set.rb

@@ -0,0 +1,173 @@
+require_relative 'datatypes'
+
+module Nl
+  class AttributeSet
+    Attribute = Struct.new(:value)
+    class Attribute
+      MULTI = false
+      ORDER = nil
+      SELECTOR_SLOT = nil
+
+      def self.multi?
+        self::MULTI
+      end
+
+      def self.decode(decoder, context: nil, nlattr_type_flags: 0)
+        new(self::DATATYPE.decode(decoder, context:, nlattr_type_flags:))
+      end
+
+      def encode(encoder, context: nil)
+        self.class::DATATYPE.encode(encoder, self.value, context:)
+      end
+    end
+
+    def initialize(attributes)
+      attr_class = self.class::Attribute
+
+      attributes.each do |attr|
+        unless attr.kind_of?(attr_class)
+          raise TypeError, "attribute must be an instance of #{attr_class}"
+        end
+      end
+
+      @attributes = Array(attributes)
+    end
+
+    def [](type)
+      case type
+      when Symbol
+        attr_class = self.class.by_name(type)
+      when Integer
+        attr_class = self.class.by_type(type)
+      else
+        raise TypeError, "attribute type must be a Symbol or an Integer"
+      end
+
+      attributes = @attributes.select { it.kind_of?(attr_class) }
+      attr_class.multi? ? attributes : attributes.first
+    end
+
+    def <<(attr)
+      attr_class = self.class::Attribute
+      unless attr.kind_of?(attr_class)
+        raise TypeError, "attribute must be an instance of #{attr_class}"
+      end
+
+      @attributes << attr
+    end
+
+    SELECTOR_NAMES = {local: [].freeze, external: [].freeze}.freeze
+
+    private def encode1(encoder, attr, context)
+      datatype = attr.class::DATATYPE
+      flags = datatype.nlattr_type_flags(attr.value, context:)
+      type = attr.class::TYPE | flags
+      nlattr = Raw::NlAttr.new(0, type)
+      encoder.measure(Endian::Host::U16) do
+        nlattr.encode(encoder)
+        attr.encode(encoder, context:)
+      end
+      encoder.align_to(Raw::NLA_ALIGNTO)
+    end
+
+    def encode(encoder, external_selectors: [])
+      context = Selector::State.new(self.class::SELECTOR_NAMES.fetch(:local).length, external_selectors)
+      @attributes.each do |attr|
+        if slot = attr.class::SELECTOR_SLOT
+          context.set_local(slot, attr.value)
+        end
+      end
+
+      attributes = @attributes.sort_by { it.class::ORDER }
+      attributes.each do |attr|
+        encode1(encoder, attr, context)
+      end
+    rescue Selector::MissingSelectorValueError => error
+      raise ArgumentError, "selector #{selector_name(error).inspect} is required by a dependent attribute"
+    rescue Selector::UnknownSelectorValueError => error
+      raise ArgumentError, "unknown sub-message selector value: #{error.value.inspect}"
+    end
+
+    private def selector_name(error)
+      self.class::SELECTOR_NAMES.fetch(error.scope).fetch(error.index)
+    end
+
+    class << self
+      private def decode1(decoder, context)
+        nlattr = Raw::NlAttr.decode(decoder)
+        flags = nlattr.type & (Raw::NLA_F_NESTED | Raw::NLA_F_NET_BYTEORDER)
+        attr = decoder.limit(nlattr.len - Raw::NLA_HDRLEN) do
+          if attr_class = self::BY_TYPE[nlattr.type & Raw::NLA_TYPE_MASK]
+            attr_class.decode(decoder, context:, nlattr_type_flags: flags)
+          else
+            decoder.skip
+            nil
+          end
+        end
+        decoder.align_to(Raw::NLA_ALIGNTO)
+        if attr && (slot = attr.class::SELECTOR_SLOT)
+          context.set_local(slot, attr.value)
+        end
+        attr
+      end
+
+      def decode(decoder, external_selectors: [])
+        context = Selector::State.new(self::SELECTOR_NAMES.fetch(:local).length, external_selectors)
+        attrs = []
+        while decoder.available?
+          attr = decode1(decoder, context)
+          attrs << attr
+        end
+        new(attrs.compact)
+      rescue Selector::MissingSelectorValueError => error
+        raise Decoder::Error,
+          "selector #{selector_name(error).inspect} must precede the dependent attribute"
+      rescue Selector::UnknownSelectorValueError => error
+        raise Decoder::Error, "unknown sub-message selector value: #{error.value.inspect}"
+      end
+
+      def build_attributes(params = nil, external_selectors: [], **keywords)
+        params = (params || {}).merge(keywords)
+        unknown = params.keys - self::BY_NAME.keys
+        raise ArgumentError, "unknown attributes: #{unknown.join(', ')}" unless unknown.empty?
+
+        context = Selector::State.new(self::SELECTOR_NAMES.fetch(:local).length, external_selectors)
+        coerced_selectors = {}
+        self::SELECTOR_NAMES.fetch(:local).each_with_index do |name, slot|
+          next unless params.key?(name)
+          attr_class = self::BY_NAME.fetch(name)
+          value = attr_class::DATATYPE.coerce(params.fetch(name))
+          coerced_selectors[name] = value
+          context.set_local(slot, value)
+        end
+
+        attrs = params.sort_by { |name, _| self::BY_NAME.fetch(name)::ORDER }.flat_map do |name, value|
+          attr_class = self::BY_NAME[name] or raise "Unknown attribute #{name}"
+          if attr_class.multi?
+            unless value.is_a?(Array)
+              raise TypeError, "value for multi-attribute #{name} must be an Array"
+            end
+            value.map { attr_class.new(coerce(attr_class::DATATYPE, it, context)) }
+          else
+            value = coerced_selectors.fetch(name) { coerce(attr_class::DATATYPE, value, context) }
+            attr_class.new(value)
+          end
+        end
+        new(attrs)
+      rescue Selector::MissingSelectorValueError => error
+        raise ArgumentError, "selector #{selector_name(error).inspect} is required by a dependent attribute"
+      rescue Selector::UnknownSelectorValueError => error
+        raise ArgumentError, "unknown sub-message selector value: #{error.value.inspect}"
+      end
+
+      private def coerce(datatype, value, context)
+        datatype.coerce(value, context:)
+      end
+
+      private def selector_name(error)
+        self::SELECTOR_NAMES.fetch(error.scope).fetch(error.index)
+      end
+
+    end
+  end
+end

data/lib/nl/bitfield32.rb

@@ -0,0 +1,86 @@
+module Nl
+  # A 32-bit value paired with a mask selecting the meaningful bits.
+  class Bitfield32
+    UINT32_RANGE = (0...2**32)
+
+    # A 32-bit flags
+    # @return [Integer]
+    attr_reader :value #: Integer
+
+    # A 32-bit mask selecting the meaningful bits
+    # @return [Integer]
+    attr_reader :selector #: Integer
+
+    # @param [Integer] value
+    # @param [Integer] selector
+    # @rbs (Integer value, Integer selector) -> void
+    def initialize(value, selector)
+      validate_uint32(value, :value)
+      validate_uint32(selector, :selector)
+      if value & ~selector != 0
+        raise ArgumentError, 'value contains bits which are not selected'
+      end
+
+      @value = value
+      @selector = selector
+    end
+
+    # Returns 1 or 0 for a selected bit, or nil for an unselected bit.
+    # @param [Integer] index Bits are indexed from the least significant bit, starting at zero.
+    # @return [0, 1, nil]
+    # @rbs (Integer index) -> (0 | 1 | nil)
+    def [](index)
+      mask = bit_mask(index)
+      return nil if selector & mask == 0
+
+      value & mask == 0 ? 0 : 1
+    end
+
+    # Selects and sets or clears a bit. Assigning nil unselects it.
+    # @param [Integer] index Bits are indexed from the least significant bit, starting at zero.
+    # @param [0, 1, nil] state
+    # @rbs (Integer index, (0 | 1 | nil) state) -> (0 | 1 | nil)
+    def []=(index, state)
+      mask = bit_mask(index)
+      case state
+      when 1
+        @selector |= mask
+        @value |= mask
+      when 0
+        @selector |= mask
+        @value &= ~mask
+      when nil
+        @selector &= ~mask
+        @value &= ~mask
+      else
+        raise TypeError, 'bit state must be 0, 1, or nil'
+      end
+
+      state
+    end
+
+    # Converts a bit index to a bit mask
+    # @rbs (Integer index) -> Integer
+    private def bit_mask(index)
+      unless index.is_a?(Integer)
+        raise TypeError, 'bit index must be an Integer'
+      end
+      unless (0...32).cover?(index)
+        raise RangeError, "bit index #{index.inspect} is outside the 0...32 range"
+      end
+
+      1 << index
+    end
+
+    # Validates if an Integer fits in uint32
+    # @rbs (Integer integer, Symbol name) -> void
+    private def validate_uint32(integer, name)
+      unless integer.is_a?(Integer)
+        raise TypeError, "#{name} must be an Integer"
+      end
+      unless UINT32_RANGE.cover?(integer)
+        raise RangeError, "#{name} #{integer.inspect} is outside the #{UINT32_RANGE} range"
+      end
+    end
+  end
+end

data/lib/nl/blocking_transport.rb

@@ -0,0 +1,131 @@
+require_relative 'datagram'
+require_relative 'exchange'
+require_relative 'notification_router'
+require_relative 'sequence_allocator'
+
+module Nl
+  # Drives one exchange at a time with blocking socket operations.
+  class BlockingTransport
+    class ConcurrentOperationError < StandardError; end
+
+    class UnexpectedSequenceError < StandardError
+      attr_reader :expected, :actual
+
+      def initialize(expected, actual)
+        @expected = expected
+        @actual = actual
+        super("expected Netlink sequence and port ID #{expected.inspect}, got #{actual.inspect}")
+      end
+    end
+
+    def initialize(socket, protocol:, notifications:)
+      @socket = socket
+      @protocol = protocol
+      @sequences = SequenceAllocator.new
+      @mutex = Mutex.new
+      @notifications = notifications
+    end
+
+    def exchange(endpoint, kind, request_class, reply_class, args)
+      unless locked = @mutex.try_lock
+        raise ConcurrentOperationError, 'BlockingTransport supports only one active operation'
+      end
+
+      request = @protocol.build_request(endpoint, kind, request_class, args)
+      seq = @sequences.next
+      pid = @socket.local_port_id
+      key = [seq, pid]
+      @protocol.send_message(@socket, endpoint, request, seq:, pid:)
+      mode = kind == :dump ? :dump : (reply_class ? :reply : :no_reply)
+      exchange = Exchange.new(mode:)
+      result = [] unless block_given?
+
+      until exchange.complete?
+        receive(endpoint, key, reply_class) do |message|
+          case outcome = exchange.accept(message)
+          when Exchange::Item
+            block_given? ? yield(outcome.value) : result << outcome.value
+          when Exchange::Failure
+            raise outcome.exception
+          end
+        end
+      end
+
+      return if block_given?
+
+      kind == :dump ? result : exchange.result
+    ensure
+      @mutex.unlock if locked
+    end
+
+    def async_capable? #: false
+      false
+    end
+
+    def receive_notification(endpoint, timeout: nil)
+      channel = @notifications.channel(endpoint)
+      return channel.pop(timeout: 0)
+    rescue TimeoutError
+      unless locked = @mutex.try_lock
+        raise ConcurrentOperationError, 'BlockingTransport supports only one active operation'
+      end
+
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout if timeout
+      loop do
+        begin
+          return channel.pop(timeout: 0)
+        rescue TimeoutError
+          # Read another datagram below.
+        end
+
+        remaining = deadline && deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise TimeoutError, 'notification receive timed out' if remaining && remaining <= 0
+        if remaining && !@socket.wait_readable(remaining)
+          raise TimeoutError, 'notification receive timed out'
+        end
+
+        receive_notifications
+      end
+    ensure
+      @mutex.unlock if locked
+    end
+
+    def close #: void
+      @socket.close unless @socket.closed?
+      nil
+    end
+
+    private def receive(endpoint, expected_key, reply_class)
+      Datagram.each_frame(receive_datagram) do |header, payload|
+        actual_key = [header.seq, header.pid]
+        if actual_key == expected_key
+          yield @protocol.decode_frame(endpoint, header, payload, reply_class)
+        elsif header.seq.zero?
+          @notifications.route(header, payload)
+        else
+          raise UnexpectedSequenceError.new(expected_key, actual_key)
+        end
+      end
+    rescue Errno::ENOBUFS
+      @notifications.lose_all(NotificationLossError.new('kernel receive buffer overflowed'))
+      raise
+    end
+
+    private def receive_notifications
+      Datagram.each_frame(receive_datagram) do |header, payload|
+        if header.seq.zero?
+          @notifications.route(header, payload)
+        else
+          raise UnexpectedSequenceError.new(nil, [header.seq, header.pid])
+        end
+      end
+    rescue Errno::ENOBUFS
+      @notifications.lose_all(NotificationLossError.new('kernel receive buffer overflowed'))
+    end
+
+    private def receive_datagram
+      data, = @socket.recvmsg
+      IO::Buffer.for(data)
+    end
+  end
+end

data/lib/nl/connection.rb

@@ -0,0 +1,61 @@
+require_relative 'async'
+require_relative 'blocking_transport'
+require_relative 'notification_router'
+require_relative 'socket'
+
+module Nl
+  # Owns one Netlink socket and the facilities shared by families using it.
+  class Connection
+    DEFAULT_NOTIFICATION_CAPACITY = 1_024
+
+    def initialize(protocol:, executor: nil, notification_capacity: DEFAULT_NOTIFICATION_CAPACITY)
+      socket = Socket.new(protocol.protonum)
+      socket.bind(Socket.sockaddr_nl(0, 0))
+      notifications = NotificationRouter.new(
+        protocol:,
+        capacity: notification_capacity,
+      )
+
+      @socket = socket
+      @notifications = notifications
+      @transport = if executor
+        Async::Dispatcher.new(socket, protocol:, executor:, notifications:)
+      else
+        BlockingTransport.new(socket, protocol:, notifications:)
+      end
+    rescue Exception
+      @transport ? @transport.close : socket&.close
+      notifications&.close
+      raise
+    end
+
+    def exchange(...) = @transport.exchange(...)
+    def exchange_async(...) = @transport.exchange_async(...)
+    def async_capable? = @transport.async_capable?
+
+    def register_notifications(endpoint, classes)
+      @notifications.register(endpoint, classes)
+    end
+
+    def add_memberships(group_ids)
+      group_ids.each { @socket.add_membership(it) }
+      nil
+    end
+
+    def drop_memberships(group_ids)
+      group_ids.each { @socket.drop_membership(it) }
+      nil
+    end
+
+    def receive_notification(endpoint, timeout: nil)
+      @transport.receive_notification(endpoint, timeout:)
+    end
+
+    def close
+      @transport.close
+      nil
+    ensure
+      @notifications.close
+    end
+  end
+end

data/lib/nl/datagram.rb

@@ -0,0 +1,22 @@
+require_relative 'raw/wire'
+require_relative 'decoder'
+
+module Nl
+  # Splits Netlink datagrams into aligned header/payload frames.
+  module Datagram
+    # @rbs (IO::Buffer buffer) { (Raw::NlMsgHdr, IO::Buffer) -> void } -> nil
+    #    | (IO::Buffer buffer) -> Enumerator[[Raw::NlMsgHdr, IO::Buffer], nil]
+    def self.each_frame(buffer)
+      return enum_for(__method__, buffer) unless block_given?
+
+      decoder = Decoder.new(buffer)
+      while decoder.available?(Raw::NLMSG_HDRLEN)
+        header = Raw::NlMsgHdr.decode(decoder)
+        payload_size = header.len - Raw::NLMSG_HDRLEN
+        payload = decoder.get_buffer(payload_size)
+        decoder.align_to(Raw::NLMSG_ALIGNTO)
+        yield header, payload
+      end
+    end
+  end
+end