nl 0.2.4 → 0.3.0

data/lib/nl/notification.rb

@@ -0,0 +1,115 @@
+# rbs_inline: enabled
+
+require_relative 'error'
+
+module Nl
+  # A multicast group. `name` is the kernel-facing name.
+  # `id` is the fixed ID when the specification provides one.
+  McastGroup = Data.define(:name, :id)
+
+  # An unsolicited message whose wire type is not present in the loaded spec.
+  UnknownNotification = Data.define(:header, :payload)
+
+  # Thread-safe queue shared by a family's blocking and asynchronous facades.
+  class NotificationChannel
+    def initialize(capacity:)
+      raise ArgumentError, 'notification capacity must be positive' if capacity && capacity <= 0
+
+      @capacity = capacity
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @queue = []
+      @error = nil
+      @closed = false
+    end
+
+    # Adds a notification without ever blocking the socket receive loop.
+    # Returns false after the channel has been closed.
+    def push(notification)
+      @mutex.synchronize do
+        return false if @closed
+
+        if @capacity && @queue.length >= @capacity
+          lose!(NotificationLossError.new('notification queue capacity exceeded'))
+        else
+          wake = @queue.empty? && !@error
+          @queue << notification
+          @condition.signal if wake
+        end
+      end
+      true
+    end
+
+    # Records a broken notification boundary while allowing later delivery to
+    # resume after the consumer observes the error and resynchronizes state.
+    def fail(error)
+      @mutex.synchronize do
+        return false if @closed
+
+        lose!(error)
+      end
+      true
+    end
+
+    def pop(timeout: nil)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout if timeout
+
+      @mutex.synchronize do
+        loop do
+          if error = @error
+            @error = nil
+            raise error
+          end
+          return @queue.shift unless @queue.empty?
+          raise ClosedError, 'notification channel is closed' if @closed
+
+          remaining = deadline && deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise TimeoutError, 'notification receive timed out' if remaining && remaining <= 0
+
+          @condition.wait(@mutex, remaining)
+        end
+      end
+    end
+
+    def empty?
+      @mutex.synchronize { @queue.empty? && !@error }
+    end
+
+    def close
+      @mutex.synchronize do
+        return nil if @closed
+
+        @closed = true
+        @queue.clear
+        @error = nil
+        @condition.broadcast
+      end
+      nil
+    end
+
+    private def lose!(error)
+      @queue.clear
+      @error = error
+      @condition.signal
+    end
+  end
+
+  # An unbounded-in-time, single-family view of unsolicited messages.
+  class NotificationStream
+    include Enumerable
+
+    def initialize(&receive)
+      @receive = receive
+    end
+
+    def next(timeout: nil)
+      @receive.call(timeout)
+    end
+
+    def each
+      return enum_for(__method__) unless block_given?
+
+      loop { yield self.next }
+    end
+  end
+end

data/lib/nl/notification_router.rb

@@ -0,0 +1,85 @@
+require_relative 'core'
+require_relative 'notification'
+
+module Nl
+  # Routes unsolicited frames to per-family notification channels.
+  class NotificationRouter
+    Entry = Struct.new(:protocol, :classes, :channel)
+    private_constant :Entry
+
+    def initialize(routing:, capacity:)
+      @routing = routing
+      @capacity = capacity
+      @mutex = Mutex.new
+      @entries = {}
+      @closed = false
+    end
+
+    def register(protocol, classes)
+      @mutex.synchronize do
+        raise ClosedError, 'notification router is closed' if @closed
+
+        key = @routing.family_key(protocol)
+        if entry = @entries[key]
+          entry.classes.merge!(classes)
+        else
+          entry = Entry.new(protocol, classes.dup, NotificationChannel.new(capacity: @capacity))
+          @entries[key] = entry
+        end
+        entry.channel
+      end
+    end
+
+    def channel(protocol)
+      @mutex.synchronize do
+        @entries.fetch(@routing.family_key(protocol)).channel
+      end
+    end
+
+    # Returns true if the frame belongs to a registered notification family.
+    def route(header, payload)
+      if header.type == Core::NLMSG_OVERRUN
+        entries = @mutex.synchronize { @entries.values.dup }
+        entries.each { it.channel.fail(NotificationLossError.new('kernel reported Netlink overrun')) }
+        return true
+      end
+
+      entry = @mutex.synchronize do
+        @entries[@routing.frame_key(header)]
+      end
+      return false unless entry
+      return false unless entry.protocol.notification_frame?(header, payload)
+
+      message_class = entry.protocol.notification_class(header, payload, entry.classes)
+      notification = if message_class
+        entry.protocol.decode_notification(header, payload, message_class)
+      else
+        UnknownNotification.new(header:, payload: payload.get_string)
+      end
+      entry.channel.push(notification)
+      true
+    rescue Exception => error
+      entry&.channel&.fail(error)
+      true
+    end
+
+    def close
+      entries = @mutex.synchronize do
+        return nil if @closed
+
+        @closed = true
+        old = @entries.values
+        @entries.clear
+        old
+      end
+      entries.each { it.channel.close }
+      nil
+    end
+
+    def lose_all(error)
+      entries = @mutex.synchronize { @entries.values.dup }
+      entries.each { it.channel.fail(error) }
+      nil
+    end
+  end
+end

data/lib/nl/protocols/genl.rb

@@ -1,52 +1,71 @@
+require_relative '../genl'
+require_relative 'raw'
+
 module Nl
   module Protocols
     # The Generic Netlink protocol
     class Genl < Raw
-      GenlMsgHdr = ::Struct.new(:cmd, :version, :reserved)
-      class GenlMsgHdr
-        FORMAT = Ractor.make_shareable([
-          Endian::Host::U8,
-          Endian::Host::U8,
-          Endian::Host::U16,
-        ])
-
-        def self.decode(decoder)
-          new(*decoder.get_values(FORMAT))
-        end
-
-        def encode(encoder)
-          encoder.put_values(FORMAT, to_a)
-        end
+      class NotificationRouting
+        def family_key(protocol) = protocol.family_key
+        def frame_key(header) = header.type
       end
 
-      def initialize(name, family_id: nil)
-        super(name, Core::NETLINK_GENERIC)
+      NOTIFICATION_ROUTING = NotificationRouting.new.freeze
+
+      def self.protonum = Core::NETLINK_GENERIC
+
+      def initialize(name, family_id: nil, multicast_groups: {})
+        super(name, self.class.protonum)
         @family_id = family_id || default_family_id(name)
+        @multicast_groups = multicast_groups.transform_keys(&:to_sym).freeze
       end
 
       def family_id
         @family_id or raise NotImplementedError, "Genetlink family ID for '#{name}' must be resolved via nlctrl"
       end
 
-      def encode_message(encoder, message)
-        cmd = message.nlmsg_header.type
+      def encode_message(encoder, request, seq:, pid:)
+        message = request.message
+        header = Core::NlMsgHdr.new(0, request.type, request.flags, seq, pid)
         encoder.measure(Endian::Host::U16) do
-          message.nlmsg_header.type = family_id
-          message.nlmsg_header.encode(encoder)
-          message.nlmsg_header.type = cmd
-          GenlMsgHdr.new(cmd, 1, 0).encode(encoder)
-          message.fixed_header&.encode(encoder)
-          message.attributes.encode(encoder)
+          header.encode(encoder)
+          Nl::Genl::GenlMsgHdr.new(message.class::TYPE, 1, 0).encode(encoder)
+          message.encode(encoder)
         end
       end
 
       class Message < Raw::Message
-        def self.decode(decoder, header)
-          genlhdr = GenlMsgHdr.decode(decoder)
-          super(decoder, header, type: genlhdr.cmd)
+        def self.decode(decoder, type:)
+          genlhdr = Nl::Genl::GenlMsgHdr.decode(decoder)
+          super(decoder, type: genlhdr.cmd)
         end
       end
 
+      def family_key = family_id
+
+      def self.notification_routing = NOTIFICATION_ROUTING
+      def notification_routing = self.class.notification_routing
+
+      def notification_frame?(header, _payload)
+        header.type == family_id
+      end
+
+      def notification_class(header, payload, classes)
+        return unless notification_frame?(header, payload)
+
+        command = Nl::Genl::GenlMsgHdr.decode(Decoder.new(payload)).cmd
+        classes[command]
+      end
+
+      def multicast_group_id(name, _value)
+        @multicast_groups.fetch(name.to_sym) do
+          raise UnresolvedMulticastGroupError,
+            "Generic Netlink multicast group #{name.inspect} was not resolved"
+        end
+      end
+
+      private def frame_type(_message_class) = family_id
+
       private def default_family_id(name)
         Nl::Genl::GENL_ID_CTRL if name == 'nlctrl'
       end

data/lib/nl/protocols/raw.rb

@@ -5,11 +5,20 @@ module Nl
   module Protocols
     # The raw Netlink protocol
     class Raw
-      class Done
-      end
-      class Ack
+      class NotificationRouting
+        def family_key(_protocol) = nil
+        def frame_key(_header) = nil
       end
 
+      NOTIFICATION_ROUTING = NotificationRouting.new.freeze
+
+      AckFrame = Data.define(:header)
+      ErrorFrame = Data.define(:header, :errno)
+      DoneFrame = Data.define(:header, :errno)
+      UnknownFrame = Data.define(:header)
+      DataFrame = Data.define(:header, :message)
+      Request = Data.define(:type, :flags, :message)
+
       attr_reader :name, :protonum
 
       def initialize(name, protonum)
@@ -17,99 +26,91 @@ module Nl
         @protonum = protonum
       end
 
-      def encode_message(encoder, message)
-        message.encode(encoder)
+      def encode_message(encoder, request, seq:, pid:)
+        header = Core::NlMsgHdr.new(0, request.type, request.flags, seq, pid)
+        encoder.measure(Endian::Host::U16) do
+          header.encode(encoder)
+          request.message.encode(encoder)
+        end
       end
 
       def decode_message(decoder, message_class)
         header = NlMsgHdr.decode(decoder)
         decoder.limit(header.len - Core::NLMSG_HDRLEN) do
-          message_class.decode(decoder, header)
+          DataFrame.new(header:, message: message_class.decode(decoder, type: header.type))
         end
       end
 
-      def send_message(socket, message)
-        seq_pid = socket.complete(message.nlmsg_header)
-        encoder = Encoder.new
-        encode_message(encoder, message)
-        socket.sendmsg(encoder.buffer.get_string, 0, Socket.sockaddr_nl(0, 0))
-        seq_pid
-      end
+      # Decodes one frame using the reply class associated with its sequence.
+      def decode_frame(header, payload, message_class)
+        decoder = Decoder.new(payload)
+        if header.type < Core::NLMSG_MIN_TYPE
+          case header.type
+          when Core::NLMSG_ERROR
+            errno = decoder.get_value(Endian::Host::SINT)
+            if errno.positive?
+              raise ProtocolViolation, "expected zero or negative NLMSG_ERROR errno, got #{errno}"
+            end
 
-      def recv_message(socket, seq_pid, message_class)
-        data, = socket.recvmsg
-
-        decoder = Decoder.new(IO::Buffer.for(data))
-        while decoder.available?(Core::NLMSG_HDRLEN)
-          header = Core::NlMsgHdr.decode(decoder)
-          decoder.align_to(Core::NLMSG_ALIGNTO)
-          raise binding.irb unless [header.seq, header.pid] == seq_pid
-          if header.type < Core::NLMSG_MIN_TYPE
-            # Control messages
-            case header.type
-            when Core::NLMSG_ERROR
-              errno = decoder.get_value(Endian::Host::SINT)
-              if errno == 0
-                yield Ack.new
-              else
-                yield SystemCallError.new(-errno)
-              end
-              decoder.skip(header.len - Core::NLMSG_HDRLEN - 4)
-            when Core::NLMSG_DONE
-              yield Done.new
-              decoder.skip(header.len - Core::NLMSG_HDRLEN)
-            else
-              # just ignore NLMSG_NOOP and other unknown control messages
-              decoder.skip(header.len - Core::NLMSG_HDRLEN)
+            errno.zero? ? AckFrame.new(header:) : ErrorFrame.new(header:, errno: -errno)
+          when Core::NLMSG_DONE
+            return DoneFrame.new(header:, errno: nil) unless decoder.available?
+
+            errno = decoder.get_value(Endian::Host::SINT)
+            if errno.positive?
+              raise ProtocolViolation, "expected zero or negative NLMSG_DONE errno, got #{errno}"
             end
+
+            DoneFrame.new(header:, errno: errno.negative? ? -errno : nil)
           else
-            # Subsystem-specific messages
-            decoder.limit(header.len - Core::NLMSG_HDRLEN) do
-              decoder.align_to(Core::NLMSG_ALIGNTO)
-              yield message_class.decode(decoder, header)
-            end
+            UnknownFrame.new(header:)
           end
+        else
+          raise ArgumentError, 'reply class is required for a data message' unless message_class
+
+          DataFrame.new(header:, message: message_class.decode(decoder, type: header.type))
         end
       end
 
-      # @param socket [Socket] Netlink socket
-      # @param type [:do, :dump] Request type
-      # @param request_class [Class] Request message class
-      # @param reply_class [Class] Reply message class
-      # @param args [Hash] Request arguments
-      def exchange_message(socket, type, request_class, reply_class, args)
+      def send_message(socket, request, seq:, pid:)
+        encoder = Encoder.new
+        encode_message(encoder, request, seq:, pid:)
+        socket.sendmsg(encoder.buffer.get_string, 0, Socket.sockaddr_nl(0, 0))
+        nil
+      end
+
+      def build_request(kind, request_class, args)
         flags = Core::NLM_F_REQUEST
-        flags |= type == :dump ? Core::NLM_F_DUMP : Core::NLM_F_ACK
-
-        request = request_class.from_params(args)
-        request.nlmsg_header.flags = flags
-        seq_pid = send_message(socket, request)
-
-        result = [] unless block_given?
-
-        done = false
-        begin
-          recv_message(socket, seq_pid, reply_class) do |message|
-            case message
-            when Done, Ack
-              done = true
-            when Exception
-              raise message
-            else
-              if block_given?
-                yield message
-              else
-                result << message
-              end
-            end
-          end
-        end until done
+        flags |= kind == :dump ? Core::NLM_F_DUMP : Core::NLM_F_ACK
 
-        unless block_given?
-          type == :dump ? result : result.first
-        end
+        message = request_class.from_params(args)
+        Request.new(type: frame_type(request_class), flags:, message:)
+      end
+
+      # Raw Netlink sockets carry a single protocol family.
+      def notification_routing = NOTIFICATION_ROUTING
+
+      # Whether an unsolicited data frame belongs to this protocol.
+      def notification_frame?(header, _payload)
+        header.type >= Core::NLMSG_MIN_TYPE
       end
 
+      # Looks up the generated notification class for an unsolicited frame.
+      def notification_class(header, _payload, classes)
+        classes[header.type]
+      end
+
+      def decode_notification(header, payload, message_class)
+        decode_frame(header, payload, message_class).message
+      end
+
+      def multicast_group_id(name, value)
+        value or raise UnresolvedMulticastGroupError,
+          "multicast group #{name.inspect} has no fixed ID"
+      end
+
+      private def frame_type(message_class) = message_class::TYPE
+
       class AttributeSet
         Attribute = Struct.new(:value)
         class Attribute
@@ -159,7 +160,9 @@ module Nl
         end
 
         private def encode1(encoder, attr)
-          nlattr = Core::NlAttr.new(0, attr.class::TYPE)
+          datatype = attr.class::DATATYPE
+          type = attr.class::TYPE | datatype.nlattr_type_flags
+          nlattr = Core::NlAttr.new(0, type)
           encoder.measure(Endian::Host::U16) do
             nlattr.encode(encoder)
             attr.encode(encoder)
@@ -208,10 +211,9 @@ module Nl
       end
 
       class Message
-        attr_accessor :nlmsg_header, :fixed_header, :attributes
+        attr_accessor :fixed_header, :attributes
 
-        def initialize(header, fixed_header = nil, attributes = self.class::ATTRIBUTE_SET.new)
-          @nlmsg_header = header
+        def initialize(fixed_header = nil, attributes = self.class::ATTRIBUTE_SET.new)
           @fixed_header = fixed_header
           @attributes = attributes
         end
@@ -230,8 +232,7 @@ module Nl
             raise ArgumentError, "unknown parameters: #{unknown.join(', ')}"
           end
 
-          header = Core::NlMsgHdr.new(0, self::TYPE, nil, nil, nil)
-          new(header, fixed_header, attributes)
+          new(fixed_header, attributes)
         end
 
         def append_attribute(attribute)
@@ -239,14 +240,11 @@ module Nl
         end
 
         def encode(encoder)
-          encoder.measure(Endian::Host::U16) do
-            @nlmsg_header.encode(encoder)
-            @fixed_header&.encode(encoder)
-            @attributes.encode(encoder)
-          end
+          @fixed_header&.encode(encoder)
+          @attributes.encode(encoder)
         end
 
-        def self.decode(decoder, header, type: header.type)
+        def self.decode(decoder, type:)
           unless self::TYPE == type
             raise "Expected message type #{self::TYPE}, got #{type}"
           end
@@ -257,12 +255,18 @@ module Nl
 
           attributes = self::ATTRIBUTE_SET.decode(decoder)
 
-          new(header, fixed_header, attributes)
+          new(fixed_header, attributes)
         end
       end
 
       module DataTypes
-        class Scalar
+        class Base
+          def nlattr_type_flags
+            0
+          end
+        end
+
+        class Scalar < Base
           def initialize(type, check)
             @type = type
             @check = check
@@ -278,7 +282,7 @@ module Nl
           end
         end
 
-        class String
+        class String < Base
           def initialize(check)
             @check = check
           end
@@ -292,7 +296,7 @@ module Nl
           end
         end
 
-        class Binary
+        class Binary < Base
           def initialize(check)
             @check = check
           end
@@ -306,7 +310,7 @@ module Nl
           end
         end
 
-        class Flag
+        class Flag < Base
           def encode(encoder, value)
             # flag attribute has no payload; presence encodes true
           end
@@ -317,7 +321,7 @@ module Nl
         end
 
         # A 32-bit value paired with a selector mask (8 bytes total: value u32 + selector u32)
-        class Bitfield32
+        class Bitfield32 < Base
           def encode(encoder, value)
             v, selector = value.is_a?(Array) ? value : [value, 0xFFFFFFFF]
             encoder.put_value(Endian::Host::U32, v)
@@ -331,7 +335,7 @@ module Nl
           end
         end
 
-        class Pad
+        class Pad < Base
           def initialize(length = nil)
             @length = length
           end
@@ -346,13 +350,21 @@ module Nl
           end
         end
 
-        class NestedAttributes
+        class NestedAttributes < Base
           def initialize(attribute_set)
             @attribute_set = attribute_set
           end
 
+          def nlattr_type_flags
+            Core::NLA_F_NESTED
+          end
+
           def encode(encoder, value)
-            @attribute_set.encode(encoder, value)
+            unless value.is_a?(@attribute_set)
+              raise TypeError, "value must be an instance of #{@attribute_set}"
+            end
+
+            value.encode(encoder)
           end
 
           def decode(decoder)
@@ -360,7 +372,60 @@ module Nl
           end
         end
 
-        class IndexedArray
+        # 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)
+            raise ArgumentError, 'levels must be positive' unless levels.positive?
+
+            @attribute_set = attribute_set
+            @levels = levels
+          end
+
+          def encode(encoder, value)
+            encode_level(encoder, value, @levels)
+          end
+
+          def decode(decoder)
+            decode_level(decoder, @levels)
+          end
+
+          private def encode_level(encoder, values, levels)
+            values.each do |type, value|
+              nlattr = Core::NlAttr.new(0, type | Core::NLA_F_NESTED)
+              encoder.measure(Endian::Host::U16) do
+                nlattr.encode(encoder)
+                if levels == 1
+                  value.encode(encoder)
+                else
+                  encode_level(encoder, value, levels - 1)
+                end
+              end
+              encoder.align_to(Core::NLA_ALIGNTO)
+            end
+          end
+
+          private def decode_level(decoder, levels)
+            result = {}
+            while decoder.available?(Core::NLA_HDRLEN)
+              nlattr = Core::NlAttr.decode(decoder)
+              type = nlattr.type & Core::NLA_TYPE_MASK
+              value = decoder.limit(nlattr.len - Core::NLA_HDRLEN) do
+                if levels == 1
+                  @attribute_set.decode(decoder)
+                else
+                  decode_level(decoder, levels - 1)
+                end
+              end
+              decoder.align_to(Core::NLA_ALIGNTO)
+              result[type] = value
+            end
+            result
+          end
+        end
+
+        class IndexedArray < Base
           def initialize(sub_type)
             @sub_type = sub_type
           end