nl 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06d7f10231a9e4b6ce47149f17099f6c72eaad8c72101ac768d3413ee1a8b12b
-  data.tar.gz: 9ecf3d32020db7cebc41de402a6e47b524aa3146db8d935cdba467d31faeda6d
+  metadata.gz: 8fbd6064a908ddacbadbb65eaa2f7c7ab862baf91478804f1915ba988271b759
+  data.tar.gz: f49043a50d47c82da9f1f818f02948a12f386df091b7041e4ae1b7d755780b23
 SHA512:
-  metadata.gz: 4ec97708c16968c722830441a0755419ebb38e5740c11a996d4ea7e6f9f07dec1803877159eb248096b069c4c1808398777fd13aff5c6aa92a8dafc47d901bf7
-  data.tar.gz: 112cfdc2829d1e6f135995315cf1fa3ef3b3aa81e1ba5ac47da3011e029113bb04a6a6c2e4a369346a38cb08a8735bb021d52b1eba0a0d540d31559f6337e71c
+  metadata.gz: 0f162b7c19214639fdd277bea5fdedb1ef4661a8747de0458b08dd85fefa94ec36dfbbd71b039ef5143069ca903e54d133029528dd4a75cee865d6b409db7251
+  data.tar.gz: c538d2a693926047576fc49bd82fd0bf435cbe19e3c61c21536826a0d873f260b87f2b6544dec4dac73e5385c11baa1da741c901bd81f2711eadb827cf34f356

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## v0.4.1 (2026-09-08)
+
+## v0.4.0 (2026-09-08)
+
+- Represent `bitfield32` values with mutable `Bitfield32` objects.
+- Support fixed-length binary values and structured binary values.
+- Encode Generic Netlink requests with the protocol version.
+- Support building and reading attributes declared as repeatable.
+- Add `Raw::Client` for using raw families with the same protocol number over one connection.
+- Rename `Genl::Connection` to `Genl::Client`.
+- Remove `UnknownNotification`; unsolicited messages without a registered decoder are now ignored.
+- Add context-aware encoding and decoding support for polymorphic sub-messages.
+
 ## v0.3.0 (2026-09-01)
 
 - Fix encoding of nested attributes and mark them with `NLA_F_NESTED`.

data/Rakefile

@@ -2,4 +2,11 @@ require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
+desc 'Generate RBS signatures from inline annotations'
+task :rbs do
+  sh '../bin/rbs-inline', '--output=sig/generated', '--opt-out', 'lib'
+end
+
+task :build => :rbs
+
 task default: :spec

data/lib/nl/async/dispatcher.rb

@@ -1,5 +1,3 @@
-# rbs_inline: enabled
-
 require_relative '../datagram'
 require_relative '../error'
 require_relative '../exchange'
@@ -10,11 +8,12 @@ module Nl
   module Async
     # Owns the single receive loop for a socket and routes replies by sequence.
     class Dispatcher
-      Pending = Data.define(:exchange, :protocol, :reply_class, :sink)
+      Pending = Data.define(:exchange, :endpoint, :reply_class, :sink)
       private_constant :Pending
 
-      def initialize(socket, executor: :thread, notifications:)
+      def initialize(socket, protocol:, executor: :thread, notifications:)
         @socket = socket
+        @protocol = protocol
         @sequences = SequenceAllocator.new
         @notifications = notifications
         @driver = executor.respond_to?(:start) ? executor : Async.driver(executor)
@@ -25,8 +24,8 @@ module Nl
         @task = @driver.start { receive_loop }
       end
 
-      def exchange(protocol, kind, request_class, reply_class, args, &block)
-        operation = exchange_async(protocol, kind, request_class, reply_class, args)
+      def exchange(endpoint, kind, request_class, reply_class, args, &block)
+        operation = exchange_async(endpoint, kind, request_class, reply_class, args)
         if kind == :dump
           if block
             operation.each(&block)
@@ -39,8 +38,8 @@ module Nl
         end
       end
 
-      def exchange_async(protocol, kind, request_class, reply_class, args, stream_capacity: nil)
-        request = protocol.build_request(kind, request_class, args)
+      def exchange_async(endpoint, kind, request_class, reply_class, args, stream_capacity: nil)
+        request = @protocol.build_request(endpoint, kind, request_class, args)
 
         key = nil
         seq = pid = nil
@@ -58,12 +57,13 @@ module Nl
             else
               Future.build(mailbox:, on_close: -> { discard(key) })
             end
-            exchange = Exchange.new(kind:, expects_reply: !reply_class.nil?)
-            @pending[key] = Pending.new(exchange:, protocol:, reply_class:, sink:)
+            mode = kind == :dump ? :dump : (reply_class ? :reply : :no_reply)
+            exchange = Exchange.new(mode:)
+            @pending[key] = Pending.new(exchange:, endpoint:, reply_class:, sink:)
           end
 
           begin
-            protocol.send_message(@socket, request, seq:, pid:)
+            @protocol.send_message(@socket, endpoint, request, seq:, pid:)
           rescue Exception => error
             fail_pending(key, error)
             raise
@@ -76,8 +76,8 @@ module Nl
         true
       end
 
-      def receive_notification(protocol, timeout: nil)
-        @notifications.channel(protocol).pop(timeout:)
+      def receive_notification(endpoint, timeout: nil)
+        @notifications.channel(endpoint).pop(timeout:)
       end
 
       def close
@@ -134,7 +134,7 @@ module Nl
           end
 
           begin
-            message = pending.protocol.decode_frame(header, payload, pending.reply_class)
+            message = @protocol.decode_frame(pending.endpoint, header, payload, pending.reply_class)
             dispatch_outcome(key, pending, pending.exchange.accept(message))
           rescue Exception => error
             fail_pending(key, error) if pending
@@ -164,9 +164,9 @@ module Nl
         return unless removed
         return if pending.exchange.cancelled?
 
-        if pending.exchange.kind == :dump
+        if pending.exchange.mode == :dump
           pending.sink.finish
-        elsif pending.exchange.expects_reply?
+        elsif pending.exchange.mode == :reply
           pending.sink.succeed(value)
         else
           pending.sink.finish

data/lib/nl/async/driver.rb

@@ -1,5 +1,3 @@
-# rbs_inline: enabled
-
 module Nl
   module Async
     module Drivers

data/lib/nl/async/mailbox.rb

@@ -1,5 +1,3 @@
-# rbs_inline: enabled
-
 require_relative '../error'
 
 module Nl

data/lib/nl/async/operation.rb

@@ -1,5 +1,3 @@
-# rbs_inline: enabled
-
 require_relative '../error'
 
 module Nl

data/lib/nl/async.rb

@@ -1,5 +1,3 @@
-# rbs_inline: enabled
-
 require_relative 'error'
 
 module Nl

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

@@ -1,5 +1,3 @@
-# rbs_inline: enabled
-
 require_relative 'datagram'
 require_relative 'exchange'
 require_relative 'notification_router'
@@ -20,28 +18,30 @@ module Nl
       end
     end
 
-    def initialize(socket, notifications:)
+    def initialize(socket, protocol:, notifications:)
       @socket = socket
+      @protocol = protocol
       @sequences = SequenceAllocator.new
       @mutex = Mutex.new
       @notifications = notifications
     end
 
-    def exchange(protocol, kind, request_class, reply_class, args)
+    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(kind, request_class, args)
+      request = @protocol.build_request(endpoint, kind, request_class, args)
       seq = @sequences.next
       pid = @socket.local_port_id
       key = [seq, pid]
-      protocol.send_message(@socket, request, seq:, pid:)
-      exchange = Exchange.new(kind:, expects_reply: !reply_class.nil?)
+      @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(protocol, key, reply_class) do |message|
+        receive(endpoint, key, reply_class) do |message|
           case outcome = exchange.accept(message)
           when Exchange::Item
             block_given? ? yield(outcome.value) : result << outcome.value
@@ -62,8 +62,8 @@ module Nl
       false
     end
 
-    def receive_notification(protocol, timeout: nil)
-      channel = @notifications.channel(protocol)
+    def receive_notification(endpoint, timeout: nil)
+      channel = @notifications.channel(endpoint)
       return channel.pop(timeout: 0)
     rescue TimeoutError
       unless locked = @mutex.try_lock
@@ -95,11 +95,11 @@ module Nl
       nil
     end
 
-    private def receive(protocol, expected_key, reply_class)
+    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(header, payload, reply_class)
+          yield @protocol.decode_frame(endpoint, header, payload, reply_class)
         elsif header.seq.zero?
           @notifications.route(header, payload)
         else

data/lib/nl/connection.rb

@@ -1,5 +1,3 @@
-# rbs_inline: enabled
-
 require_relative 'async'
 require_relative 'blocking_transport'
 require_relative 'notification_router'
@@ -14,16 +12,16 @@ module Nl
       socket = Socket.new(protocol.protonum)
       socket.bind(Socket.sockaddr_nl(0, 0))
       notifications = NotificationRouter.new(
-        routing: protocol.notification_routing,
+        protocol:,
         capacity: notification_capacity,
       )
 
       @socket = socket
       @notifications = notifications
       @transport = if executor
-        Async::Dispatcher.new(socket, executor:, notifications:)
+        Async::Dispatcher.new(socket, protocol:, executor:, notifications:)
       else
-        BlockingTransport.new(socket, notifications:)
+        BlockingTransport.new(socket, protocol:, notifications:)
       end
     rescue Exception
       @transport ? @transport.close : socket&.close
@@ -35,8 +33,8 @@ module Nl
     def exchange_async(...) = @transport.exchange_async(...)
     def async_capable? = @transport.async_capable?
 
-    def register_notifications(protocol, classes)
-      @notifications.register(protocol, classes)
+    def register_notifications(endpoint, classes)
+      @notifications.register(endpoint, classes)
     end
 
     def add_memberships(group_ids)
@@ -49,8 +47,8 @@ module Nl
       nil
     end
 
-    def receive_notification(protocol, timeout: nil)
-      @transport.receive_notification(protocol, timeout:)
+    def receive_notification(endpoint, timeout: nil)
+      @transport.receive_notification(endpoint, timeout:)
     end
 
     def close

data/lib/nl/datagram.rb

@@ -1,22 +1,20 @@
-# rbs_inline: enabled
-
-require_relative 'core'
+require_relative 'raw/wire'
 require_relative 'decoder'
 
 module Nl
   # Splits Netlink datagrams into aligned header/payload frames.
   module Datagram
-    # @rbs (IO::Buffer buffer) { (Core::NlMsgHdr, IO::Buffer) -> void } -> nil
-    #    | (IO::Buffer buffer) -> Enumerator[[Core::NlMsgHdr, IO::Buffer], nil]
+    # @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?(Core::NLMSG_HDRLEN)
-        header = Core::NlMsgHdr.decode(decoder)
-        payload_size = header.len - Core::NLMSG_HDRLEN
+      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(Core::NLMSG_ALIGNTO)
+        decoder.align_to(Raw::NLMSG_ALIGNTO)
         yield header, payload
       end
     end