nl 0.2.4 → 0.4.1

data/lib/nl/datatypes.rb

@@ -0,0 +1,454 @@
+require_relative 'raw/wire'
+require_relative 'bitfield32'
+
+module Nl
+  # @rbs!
+  #   interface _DataType
+  #     def encode: (Encoder, untyped, ?context: untyped) -> void
+  #     def decode: (Decoder, ?context: untyped, ?nlattr_type_flags: Integer) -> untyped
+  #     def nlattr_type_flags: (?untyped, ?context: untyped) -> Integer
+  #     def coerce: (untyped, ?context: untyped) -> untyped
+  #   end
+
+  module DataTypes
+    class Base
+      def initialize(check: nil)
+        @check = check
+      end
+
+      def nlattr_type_flags(_value = nil, context: nil)
+        0
+      end
+
+      def coerce(value, context: nil)
+        value
+      end
+
+      private def checked(value)
+        @check&.call(value)
+        value
+      end
+    end
+
+    class Scalar < Base
+      def initialize(type, check:)
+        super(check:)
+        @type = type
+      end
+
+      def encode(encoder, value, context: nil)
+        encoder.put_value(@type, checked(value || 0))
+      end
+
+      def decode(decoder, context: nil, nlattr_type_flags: 0)
+        checked(decoder.get_value(@type))
+      end
+    end
+
+    class VariableInteger < Base
+      UINT32_RANGE = (0...2**32)
+      UINT64_RANGE = (0...2**64)
+      SINT32_RANGE = (-(2**31)...2**31)
+      SINT64_RANGE = (-(2**63)...2**63)
+
+      def initialize(byte_order, signed:, check:)
+        super(check:)
+        prefix = signed ? 'S' : 'U'
+        @type32 = byte_order.const_get("#{prefix}32")
+        @type64 = byte_order.const_get("#{prefix}64")
+        @range32 = signed ? SINT32_RANGE : UINT32_RANGE
+        @range64 = signed ? SINT64_RANGE : UINT64_RANGE
+      end
+
+      def encode(encoder, value, context: nil)
+        value = checked(value || 0)
+        unless @range64.cover?(value)
+          raise RangeError, "integer #{value.inspect} is outside the #{@range64.begin}...#{@range64.end} range"
+        end
+
+        type = @range32.cover?(value) ? @type32 : @type64
+        encoder.put_value(type, value)
+      end
+
+      def decode(decoder, context: nil, nlattr_type_flags: 0)
+        type = case decoder.remaining
+        when 4 then @type32
+        when 8 then @type64
+        else
+          raise Decoder::Error, "variable integer payload must be 4 or 8 bytes, got #{decoder.remaining}"
+        end
+        checked(decoder.get_value(type))
+      end
+    end
+
+    class String < Base
+      def initialize(check:)
+        super(check:)
+      end
+
+      def encode(encoder, value, context: nil)
+        encoder.put_zstring(checked(value))
+      end
+
+      def decode(decoder, context: nil, nlattr_type_flags: 0)
+        checked(decoder.get_zstring)
+      end
+    end
+
+    class Binary < Base
+      def initialize(length: nil, check:)
+        super(check:)
+        @length = length
+      end
+
+      def encode(encoder, value, context: nil)
+        value = checked(value)
+        if @length && value.bytesize != @length
+          raise ArgumentError, "binary value must be exactly #{@length} bytes, got #{value.bytesize}"
+        end
+        encoder.put_string(value)
+      end
+
+      def decode(decoder, context: nil, nlattr_type_flags: 0)
+        checked(decoder.get_string(@length || decoder.remaining))
+      end
+    end
+
+    # An array whose elements are packed consecutively without per-element
+    # headers or alignment padding.
+    class PackedArray < Base
+      def initialize(sub_type, check: nil)
+        super(check:)
+        @sub_type = sub_type
+      end
+
+      def encode(encoder, values, context: nil)
+        values = coerce(values, context:)
+        if @check
+          temporary = Encoder.new
+          values.each { @sub_type.encode(temporary, it, context:) }
+          encoder.put_string(checked(temporary.buffer.get_string))
+        else
+          values.each { @sub_type.encode(encoder, it, context:) }
+        end
+      end
+
+      def coerce(values, context: nil)
+        values.map { @sub_type.coerce(it, context:) }
+      end
+
+      def decode(decoder, context: nil, nlattr_type_flags: 0)
+        if @check
+          payload = checked(decoder.get_string)
+          decoder = Decoder.new(IO::Buffer.for(payload))
+        end
+
+        result = []
+        result << @sub_type.decode(decoder, context:, nlattr_type_flags: 0) while decoder.available?
+        result
+      end
+    end
+
+    class Struct < Base
+      def initialize(type, check: nil, consume_remaining: false)
+        super(check:)
+        @type = type
+        @consume_remaining = consume_remaining
+      end
+
+      def coerce(value, context: nil)
+        return value unless value.is_a?(Hash)
+
+        unknown = value.keys - @type::MEMBERS.keys
+        raise ArgumentError, "unknown struct members: #{unknown.join(', ')}" unless unknown.empty?
+
+        @type.new(*@type::MEMBERS.map { |name, datatype| datatype.coerce(value[name], context:) })
+      end
+
+      def encode(encoder, value, context: nil)
+        unless value.is_a?(@type)
+          raise TypeError, "value must be an instance of #{@type}"
+        end
+
+        if @check
+          temporary = Encoder.new
+          value.encode(temporary)
+          encoder.put_string(checked(temporary.buffer.get_string))
+        else
+          value.encode(encoder)
+        end
+      end
+
+      def decode(decoder, context: nil, nlattr_type_flags: 0)
+        unless @check
+          value = @type.decode(decoder)
+          decoder.skip if @consume_remaining
+          return value
+        end
+
+        payload = checked(decoder.get_string)
+        nested = Decoder.new(IO::Buffer.for(payload))
+        nested.limit(payload.bytesize) do
+          value = @type.decode(it)
+          it.skip if @consume_remaining
+          value
+        end
+      end
+    end
+
+    class Flag < Base
+      def encode(encoder, value, context: nil)
+        # flag attribute has no payload; presence encodes true
+      end
+
+      def decode(decoder, context: nil, nlattr_type_flags: 0)
+        true
+      end
+    end
+
+    class Bitfield32 < Base
+      def encode(encoder, value, context: nil)
+        unless value.is_a?(Nl::Bitfield32)
+          raise TypeError, 'bitfield32 value must be an Nl::Bitfield32'
+        end
+
+        encoder.put_value(Endian::Host::U32, value.value)
+        encoder.put_value(Endian::Host::U32, value.selector)
+      end
+
+      def decode(decoder, context: nil, nlattr_type_flags: 0)
+        value = decoder.get_value(Endian::Host::U32)
+        selector = decoder.get_value(Endian::Host::U32)
+        Nl::Bitfield32.new(value, selector)
+      end
+    end
+
+    class Pad < Base
+      def initialize(length = nil)
+        @length = length
+      end
+
+      def encode(encoder, _value, context: nil)
+        encoder.put_string(?\0.b * @length) if @length
+      end
+
+      def decode(decoder, context: nil, nlattr_type_flags: 0)
+        @length ? decoder.skip(@length) : decoder.skip
+        nil
+      end
+    end
+
+    class NestedAttributes < Base
+      def initialize(attribute_set, selector_bindings: [])
+        @attribute_set = attribute_set
+        @selector_bindings = selector_bindings
+      end
+
+      def nlattr_type_flags(_value = nil, context: nil)
+        Raw::NLA_F_NESTED
+      end
+
+      def coerce(value, context: nil)
+        value.is_a?(Hash) ? @attribute_set.build_attributes(value, external_selectors: selectors(context)) : value
+      end
+
+      def encode(encoder, value, context: nil)
+        unless value.is_a?(@attribute_set)
+          raise TypeError, "value must be an instance of #{@attribute_set}"
+        end
+
+        value.encode(encoder, external_selectors: selectors(context))
+      end
+
+      def decode(decoder, context: nil, nlattr_type_flags: 0)
+        @attribute_set.decode(decoder, external_selectors: selectors(context))
+      end
+
+      private def selectors(context)
+        @selector_bindings.map { it.read(context) }
+      end
+    end
+
+    class SubMessage < Base
+      Format = Data.define(:type, :selector_bindings, :nested)
+
+      def initialize(selector, formats)
+        @selector = selector
+        @formats = formats.transform_values do |format|
+          format.is_a?(Format) ? format : Format.new(*format)
+        end.freeze
+      end
+
+      def nlattr_type_flags(value = nil, context:)
+        if value.is_a?(RawSubMessage)
+          @selector.read(context)
+          return value.nlattr_type_flags
+        end
+
+        format = @selector.select(context, @formats)
+        unless value.is_a?(format.type)
+          raise TypeError, "value must be an instance of #{format.type}"
+        end
+        format.nested ? Raw::NLA_F_NESTED : 0
+      end
+
+      def coerce(value, context:)
+        if value.is_a?(RawSubMessage)
+          @selector.read(context)  # ensure selector value is present
+          return value
+        end
+
+        format = @selector.select(context, @formats)
+        return value if value.is_a?(format.type)
+        return format.type.from_params(value, external_selectors: selectors(format, context)) if value.is_a?(Hash)
+
+        raise TypeError, "value must be a Hash or an instance of #{format.type}"
+      end
+
+      def encode(encoder, value, context: nil)
+        if value.is_a?(RawSubMessage)
+          @selector.read(context)
+          return value.encode(encoder)
+        end
+
+        format = @selector.select(context, @formats)
+        unless value.is_a?(format.type)
+          raise TypeError, "value must be an instance of #{format.type}"
+        end
+        value.encode(encoder, external_selectors: selectors(format, context))
+      end
+
+      def decode(decoder, context:, nlattr_type_flags: 0)
+        format = @selector.select(context, @formats) do
+          return RawSubMessage.new(
+            decoder.get_string,
+            nlattr_type_flags:,
+          )
+        end
+        format.type.decode(decoder, external_selectors: selectors(format, context))
+      end
+
+      private def selectors(format, context)
+        format.selector_bindings.map { it.read(context) }
+      end
+    end
+
+    # Nested attributes whose type numbers are keys rather than members of
+    # an attribute set. Each level is returned as an Integer-keyed Hash;
+    # values at the innermost level are decoded as @attribute_set.
+    class NestTypeValue < Base
+      def initialize(attribute_set, levels, selector_bindings: [])
+        raise ArgumentError, 'levels must be positive' unless levels.positive?
+
+        @attribute_set = attribute_set
+        @levels = levels
+        @selector_bindings = selector_bindings
+      end
+
+      def encode(encoder, value, context: nil)
+        encode_level(encoder, value, @levels, selectors(context))
+      end
+
+      def coerce(value = nil, context: nil, **keywords)
+        value = keywords unless keywords.empty?
+        coerce_level(value, @levels, selectors(context))
+      end
+
+      def decode(decoder, context: nil, nlattr_type_flags: 0)
+        decode_level(decoder, @levels, selectors(context))
+      end
+
+      private def encode_level(encoder, values, levels, external_selectors)
+        values.each do |type, value|
+          nlattr = Raw::NlAttr.new(0, type | Raw::NLA_F_NESTED)
+          encoder.measure(Endian::Host::U16) do
+            nlattr.encode(encoder)
+            if levels == 1
+              if external_selectors.empty?
+                value.encode(encoder)
+              else
+                value.encode(encoder, external_selectors:)
+              end
+            else
+              encode_level(encoder, value, levels - 1, external_selectors)
+            end
+          end
+          encoder.align_to(Raw::NLA_ALIGNTO)
+        end
+      end
+
+      private def coerce_level(values, levels, external_selectors)
+        values.transform_values do |value|
+          if levels == 1
+            if value.is_a?(Hash)
+              external_selectors.empty? ? @attribute_set.build_attributes(value) :
+                @attribute_set.build_attributes(value, external_selectors:)
+            else
+              value
+            end
+          else
+            coerce_level(value, levels - 1, external_selectors)
+          end
+        end
+      end
+
+      private def decode_level(decoder, levels, external_selectors)
+        result = {}
+        while decoder.available?(Raw::NLA_HDRLEN)
+          nlattr = Raw::NlAttr.decode(decoder)
+          type = nlattr.type & Raw::NLA_TYPE_MASK
+          value = decoder.limit(nlattr.len - Raw::NLA_HDRLEN) do
+            if levels == 1
+              external_selectors.empty? ? @attribute_set.decode(decoder) :
+                @attribute_set.decode(decoder, external_selectors:)
+            else
+              decode_level(decoder, levels - 1, external_selectors)
+            end
+          end
+          decoder.align_to(Raw::NLA_ALIGNTO)
+          result[type] = value
+        end
+        result
+      end
+
+      private def selectors(context)
+        @selector_bindings.map { it.read(context) }
+      end
+    end
+
+    class IndexedArray < Base
+      def initialize(sub_type)
+        @sub_type = sub_type
+      end
+
+      def encode(encoder, values, context: nil)
+        values.each_with_index do |value, i|
+          nlattr = Raw::NlAttr.new(0, i + 1)
+          encoder.measure(Endian::Host::U16) do
+            nlattr.encode(encoder)
+            @sub_type.encode(encoder, value, context:)
+          end
+          encoder.align_to(Raw::NLA_ALIGNTO)
+        end
+      end
+
+      def coerce(values, context: nil)
+        values.map { @sub_type.coerce(it, context:) }
+      end
+
+      def decode(decoder, context: nil, nlattr_type_flags: 0)
+        result = []
+        while decoder.available?
+          nlattr = Raw::NlAttr.decode(decoder)
+          flags = nlattr.type & (Raw::NLA_F_NESTED | Raw::NLA_F_NET_BYTEORDER)
+          element = decoder.limit(nlattr.len - Raw::NLA_HDRLEN) do
+            @sub_type.decode(decoder, context:, nlattr_type_flags: flags)
+          end
+          decoder.align_to(Raw::NLA_ALIGNTO)
+          result << element
+        end
+        result
+      end
+    end
+  end
+end

data/lib/nl/decoder.rb

@@ -18,6 +18,10 @@ module Nl
       @position + size <= @limit
     end
 
+    def remaining
+      @limit - @position
+    end
+
     def limit(size)
       orig_limit = @limit
       @limit = @position + size
@@ -38,12 +42,20 @@ module Nl
 
     def get_string(length = @limit - @position)
       nposition = @position + length
-      raise OutOfBounds if nposition > @limit
+      raise OutOfBounds if length.negative? || nposition > @limit
       value = @buffer.get_string(@position, length)
       @position = nposition
       value
     end
 
+    def get_buffer(length = @limit - @position)
+      nposition = @position + length
+      raise OutOfBounds if length.negative? || nposition > @limit
+      value = @buffer.slice(@position, length)
+      @position = nposition
+      value
+    end
+
     def get_zstring(unterminated_ok: false)
       nposition = @position
       nul_found = false

data/lib/nl/endian.rb

@@ -1,17 +1,27 @@
+# Byte-order helpers
+
 module Nl
   module Endian
+    # sizeof(int)
     SIZEOF_INT = [1].pack('i!').bytesize
+    # sizeof(long)
     SIZEOF_LONG = [1].pack('l!').bytesize
+    # sizeof(long long)
     SIZEOF_LLONG = [1].pack('q!').bytesize
 
+    # Little-endian scalar types.
     module Little
       U8, S8, U16, S16, U32, S32, U64, S64, F32, F64 = :U8, :S8, :u16, :s16, :u32, :s32, :u64, :s64, :f32, :f64
     end
 
+    # Big-endian scalar types.
     module Big
       U8, S8, U16, S16, U32, S32, U64, S64, F32, F64 = :U8, :S8, :U16, :S16, :U32, :S32, :U64, :S64, :F32, :F64
     end
 
+    # Host-endian scalar types.
+    #
+    # This module includes either {Little} or {Big} depending on the host's native byte order.
     module Host
       include (IO::Buffer::HOST_ENDIAN == IO::Buffer::LITTLE_ENDIAN ? Little : Big)
 

data/lib/nl/error.rb

@@ -0,0 +1,10 @@
+module Nl
+  class Error < StandardError; end
+  class ProtocolViolation < Error; end
+  class ExhaustedSequenceNumber < Error; end
+  class TimeoutError < Error; end
+  class ClosedError < Error; end
+  class NotificationLossError < Error; end
+  class UnknownMulticastGroupError < Error; end
+  class UnresolvedMulticastGroupError < Error; end
+end

data/lib/nl/exchange.rb

@@ -0,0 +1,124 @@
+require_relative 'error'
+require_relative 'raw/protocol'
+
+module Nl
+  # State machine for one Netlink request/reply exchange.
+  #
+  # Dump exchanges are known to be multipart from the request and remain open
+  # through NLMSG_DONE. Some Linux Generic Netlink dump handlers construct
+  # replies with genlmsg_iput(), which leaves NLM_F_MULTI unset despite that
+  # multipart lifetime. Dump mode therefore accepts data with or without the
+  # flag; reply mode still uses it to detect a multipart do response.
+  #
+  # Some operations also return multipart data for a do request, although YNL
+  # cannot declare such a reply. Reply mode handles this kernel behavior by
+  # retaining the first data message, draining the remainder, and completing
+  # on NLMSG_DONE instead of ACK.
+  class Exchange
+    Item = Data.define(:value)
+    Complete = Data.define
+    COMPLETE = Complete.new
+    Failure = Data.define(:exception)
+
+    MODES = %i[dump no_reply reply].freeze
+    private_constant :MODES
+
+    attr_reader :mode
+
+    # @rbs (mode: :dump | :no_reply | :reply) -> void
+    def initialize(mode:)
+      raise ArgumentError, "unknown exchange mode: #{mode.inspect}" unless MODES.include?(mode)
+
+      @mode = mode
+      @reply = nil
+      # Receive states:
+      # - :dump accepts and emits every data message, then completes on DONE.
+      # - :no_reply rejects data and completes on ACK.
+      # - :initial waits for the first data message of a reply operation.
+      # - :single retains that message and completes once ACK is received.
+      # - :multi retains the first message, drains the rest, and
+      #   completes on DONE. Every data message must carry NLM_F_MULTI.
+      @state = mode == :reply ? :initial : mode
+      @acked = false
+      @cancelled = false
+      @complete = false
+      @result = nil
+      @mutex = Mutex.new
+    end
+
+    def accept(frame)
+      @mutex.synchronize do
+        return if @complete
+
+        case frame
+        when Raw::UnknownFrame
+          nil
+        when Raw::ErrorFrame
+          @cancelled ? complete(nil) : fail_with(SystemCallError.new(frame.errno))
+        when Raw::DoneFrame
+          if frame.errno && !@cancelled
+            fail_with(SystemCallError.new(frame.errno))
+          else
+            complete(@reply)
+          end
+        when Raw::AckFrame
+          accept_ack
+        when Raw::DataFrame
+          accept_reply(frame)
+        else
+          raise ArgumentError, "unexpected exchange input: #{frame.inspect}"
+        end
+      end
+    end
+
+    def cancel
+      @mutex.synchronize { @cancelled = true unless @complete }
+      nil
+    end
+
+    def cancelled? = @mutex.synchronize { @cancelled }
+    def complete? = @mutex.synchronize { @complete }
+    def result = @mutex.synchronize { @result }
+
+    private def accept_ack
+      @acked = true
+      if @cancelled || @state == :no_reply || @state == :single
+        complete(@reply)
+      end
+    end
+
+    private def accept_reply(frame)
+      return if @cancelled
+
+      multipart = (frame.header.flags.to_i & Raw::NLM_F_MULTI) != 0
+      case @state
+      when :dump
+        return Item.new(frame.message)
+      when :no_reply
+        return fail_with(ProtocolViolation.new('unexpected data message in a no-reply Netlink response'))
+      when :initial
+        @state = multipart ? :multi : :single
+      when :single
+        return fail_with(ProtocolViolation.new('more than one data message in a non-multipart Netlink response'))
+      when :multi
+        unless multipart
+          return fail_with(ProtocolViolation.new('multipart Netlink response contains data without NLM_F_MULTI'))
+        end
+      end
+
+      @reply ||= frame.message
+      complete(frame.message) if @acked && @state == :single
+    end
+
+    private def complete(value)
+      @complete = true
+      @result = value
+      COMPLETE
+    end
+
+    private def fail_with(exception)
+      @complete = true
+      Failure.new(exception)
+    end
+  end
+end