nl 0.2.4 → 0.4.1

data/lib/nl/notification_router.rb

@@ -0,0 +1,92 @@
+require_relative 'raw/wire'
+require_relative 'notification'
+
+module Nl
+  # Routes unsolicited frames to per-family notification channels.
+  class NotificationRouter
+    Entry = Struct.new(:endpoint, :classes, :channel)
+    private_constant :Entry
+
+    def initialize(protocol:, capacity:)
+      @protocol = protocol
+      @capacity = capacity
+      @mutex = Mutex.new
+      @entries = {}
+      @routes = {}
+      @closed = false
+    end
+
+    def register(endpoint, classes)
+      @mutex.synchronize do
+        raise ClosedError, 'notification router is closed' if @closed
+
+        channel_key = @protocol.notification_channel_key(endpoint)
+        entry = @entries[channel_key]
+        merged_classes = entry ? entry.classes.merge(classes) : classes.dup
+        route_keys = @protocol.notification_route_keys(endpoint, merged_classes)
+        if route_key = route_keys.find { @routes[it] && !@routes[it].equal?(entry) }
+          raise ArgumentError, "notification route #{route_key.inspect} is already registered"
+        end
+
+        unless entry
+          entry = Entry.new(endpoint, merged_classes, NotificationChannel.new(capacity: @capacity))
+          @entries[channel_key] = entry
+        end
+        entry.classes.replace(merged_classes)
+        route_keys.each { @routes[it] = entry }
+        entry.channel
+      end
+    end
+
+    def channel(endpoint)
+      @mutex.synchronize do
+        @entries.fetch(@protocol.notification_channel_key(endpoint)).channel
+      end
+    end
+
+    # Returns true if the frame belongs to a registered notification family.
+    def route(header, payload)
+      if header.type == Raw::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
+        @routes[@protocol.notification_frame_key(header)]
+      end
+      return false unless entry
+      return false unless @protocol.notification_frame?(entry.endpoint, header, payload)
+
+      message_class = @protocol.notification_class(entry.endpoint, header, payload, entry.classes)
+      return true unless message_class
+
+      notification = @protocol.decode_notification(entry.endpoint, header, payload, message_class)
+      entry.channel.push(notification)
+      true
+    rescue => error
+      entry&.channel&.fail(error)
+      true
+    end
+
+    def close
+      entries = @mutex.synchronize do
+        return nil if @closed
+
+        @closed = true
+        old = @entries.values
+        @entries.clear
+        @routes.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/raw/client.rb

@@ -0,0 +1,83 @@
+# Raw Netlink client handling
+
+require_relative '../connection'
+require_relative 'protocol'
+
+module Nl
+  module Raw
+    # Owns one raw Netlink connection shared by compatible families.
+    class Client
+      # Opens a client for a raw Netlink protocol.
+      #
+      # @overload open(protonum:, executor: nil, notification_capacity: Nl::Connection::DEFAULT_NOTIFICATION_CAPACITY)
+      #   The caller is responsible for closing the client.
+      #   @param [Integer] protonum the Netlink protocol number
+      #   @param [:thread, :fiber, nil] executor the asynchronous executor, or `nil` for blocking operation
+      #   @param [Integer] notification_capacity the maximum number of queued notifications
+      #   @return [Client] the opened client
+      # @overload open(protonum:, executor: nil, notification_capacity: Nl::Connection::DEFAULT_NOTIFICATION_CAPACITY, &block)
+      #   The client is automatically closed after the block returns.
+      #   @param [Integer] protonum the Netlink protocol number
+      #   @param [:thread, :fiber, nil] executor the asynchronous executor, or `nil` for blocking operation
+      #   @param [Integer] notification_capacity the maximum number of queued notifications
+      #   @yieldparam [Client] client the opened client
+      #   @return [Object] the value returned from the block
+      # @rbs (protonum: Integer, ?executor: executor?, ?notification_capacity: Integer?) -> instance
+      #    | [R] (protonum: Integer, ?executor: executor?, ?notification_capacity: Integer?) { (instance) -> R } -> R
+      def self.open(protonum:, executor: nil, notification_capacity: Nl::Connection::DEFAULT_NOTIFICATION_CAPACITY)
+        client = new(protonum:, executor:, notification_capacity:)
+        return client unless block_given?
+
+        begin
+          yield client
+        ensure
+          client.close
+        end
+      end
+
+      # @param [Integer] protonum the Netlink protocol number
+      # @param [:thread, :fiber, nil] executor the asynchronous executor, or `nil` for blocking operation
+      # @param [Integer] notification_capacity the maximum number of queued notifications
+      # @rbs (protonum: Integer, ?executor: executor?, ?notification_capacity: Integer?) -> void
+      def initialize(protonum:, executor: nil, notification_capacity: Nl::Connection::DEFAULT_NOTIFICATION_CAPACITY)
+        @protonum = protonum
+        @connection = Nl::Connection.new(
+          protocol: Protocol.new(protonum),
+          executor:,
+          notification_capacity:,
+        )
+      end
+
+      # Builds a family backed by this client's connection.
+      #
+      # @param [Class<Family>] family_class a raw Netlink family class
+      # @return [Family] an instance of `family_class`
+      # @raise [TypeError] if +family_class+ does not inherit from {Family}
+      # @raise [ArgumentError] if the family's protocol number differs from the client's protocol number
+      # @rbs [F < Family] (_FamilyClass[F] family_class) -> F
+      def family(family_class)
+        unless family_class <= Family
+          raise TypeError, "family class must inherit from #{Family}"
+        end
+        unless family_class::PROTONUM == @protonum
+          raise ArgumentError,
+            "family protonum #{family_class::PROTONUM} does not match client protonum #{@protonum}"
+        end
+
+        family_class.new(
+          @connection,
+          endpoint: Endpoint.new(family_class),
+        )
+      end
+
+      # Closes the underlying Netlink connection.
+      #
+      # @return [void]
+      #--
+      # @rbs () -> void
+      def close
+        @connection.close
+      end
+    end
+  end
+end

data/lib/nl/raw/protocol.rb

@@ -0,0 +1,112 @@
+require_relative 'wire'
+require_relative '../decoder'
+require_relative '../encoder'
+require_relative '../error'
+require_relative '../socket'
+
+module Nl
+  module Raw
+    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)
+
+    # A generated raw Netlink family bound to its fixed wire identity.
+    class Endpoint
+      attr_reader :definition
+
+      def initialize(definition)
+        @definition = definition
+      end
+
+      def name = @definition::NAME
+      def frame_type(message_class) = message_class::TYPE
+
+      def multicast_group_id(name, value)
+        value or raise UnresolvedMulticastGroupError,
+          "multicast group #{name.inspect} has no fixed ID"
+      end
+    end
+
+    # Socket-wide wire behavior for a classic (netlink-raw) protocol.
+    class Protocol
+      attr_reader :protonum
+
+      def initialize(protonum)
+        @protonum = protonum
+      end
+
+      def encode_message(encoder, _endpoint, request, seq:, pid:)
+        header = Raw::NlMsgHdr.new(0, request.type, request.flags, seq, pid)
+        encoder.measure(Endian::Host::U16) do
+          header.encode(encoder)
+          request.message.encode(encoder)
+        end
+      end
+
+      # Decodes one frame using the reply class associated with its sequence.
+      def decode_frame(_endpoint, header, payload, message_class)
+        decoder = Decoder.new(payload)
+        if header.type < Raw::NLMSG_MIN_TYPE
+          case header.type
+          when Raw::NLMSG_ERROR
+            errno = decoder.get_value(Endian::Host::SINT)
+            if errno.positive?
+              raise ProtocolViolation, "expected zero or negative NLMSG_ERROR errno, got #{errno}"
+            end
+
+            errno.zero? ? AckFrame.new(header:) : ErrorFrame.new(header:, errno: -errno)
+          when Raw::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
+            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
+
+      def send_message(socket, endpoint, request, seq:, pid:)
+        encoder = Encoder.new
+        encode_message(encoder, endpoint, request, seq:, pid:)
+        socket.sendmsg(encoder.buffer.get_string, 0, Socket.sockaddr_nl(0, 0))
+        nil
+      end
+
+      def build_request(endpoint, kind, request_class, args)
+        flags = Raw::NLM_F_REQUEST
+        flags |= kind == :dump ? Raw::NLM_F_DUMP : Raw::NLM_F_ACK
+
+        message = request_class.from_params(args)
+        Request.new(type: endpoint.frame_type(request_class), flags:, message:)
+      end
+
+      def notification_channel_key(endpoint) = endpoint.definition
+      def notification_route_keys(_endpoint, classes) = classes.keys
+      def notification_frame_key(header) = header.type
+
+      def notification_frame?(_endpoint, header, _payload)
+        header.type >= Raw::NLMSG_MIN_TYPE
+      end
+
+      def notification_class(_endpoint, header, _payload, classes)
+        classes[header.type]
+      end
+
+      def decode_notification(endpoint, header, payload, message_class)
+        decode_frame(endpoint, header, payload, message_class).message
+      end
+    end
+  end
+end

data/lib/nl/raw/wire.rb

@@ -0,0 +1,146 @@
+# Netlink wire definitions
+
+require_relative '../endian'
+
+module Nl
+  module Raw
+    # Constants from <linux/netlink.h>
+    module Constants
+      NETLINK_ROUTE = 0
+      NETLINK_NETFILTER = 12
+      NETLINK_GENERIC = 16
+
+      NLM_F_REQUEST = 1
+      NLM_F_MULTI = 2
+      NLM_F_ACK = 4
+      NLM_F_ECHO = 8
+      NLM_F_DUMP_INTR = 16
+      NLM_F_DUMP_FILTERED = 32
+      NLM_F_ROOT = 0x100
+      NLM_F_MATCH = 0x200
+      NLM_F_ATOMIC = 0x400
+      NLM_F_DUMP = NLM_F_ROOT | NLM_F_MATCH
+      NLM_F_REPLACE = 0x100
+      NLM_F_EXCL = 0x200
+      NLM_F_CREATE = 0x400
+      NLM_F_APPEND = 0x800
+
+      NLMSG_ALIGNTO = 4
+      NLMSG_HDRLEN = 16
+
+      NLMSG_NOOP = 0x1
+      NLMSG_ERROR = 0x2
+      NLMSG_DONE = 0x3
+      NLMSG_OVERRUN = 0x4
+
+      NLMSG_MIN_TYPE = 0x10
+
+      NLA_F_NESTED = 1 << 15
+      NLA_F_NET_BYTEORDER = 1 << 14
+      NLA_TYPE_MASK = ~(NLA_F_NESTED | NLA_F_NET_BYTEORDER)
+
+      NLA_ALIGNTO = 4
+      NLA_HDRLEN = 4
+    end
+    include Constants
+
+    # Fixed-format metadata header prepended to every Netlink message.
+    #
+    # This corresponds to Linux's +struct nlmsghdr+.
+    #
+    # @!attribute [rw] len
+    #   @return [Integer] message length in bytes, including this header
+    # @!attribute [rw] type
+    #   @return [Integer] message content type
+    # @!attribute [rw] flags
+    #   @return [Integer] bitwise combination of +NLM_F_+ flags
+    # @!attribute [rw] seq
+    #   @return [Integer] sequence number used to correlate requests and replies
+    # @!attribute [rw] pid
+    #   @return [Integer] sender's Netlink port ID
+    NlMsgHdr = Struct.new(
+      :len, #: Integer
+      :type, #: Integer
+      :flags, #: Integer
+      :seq, #: Integer
+      :pid, #: Integer
+    )
+
+    class NlMsgHdr
+      FORMAT = Ractor.make_shareable([
+        Endian::Host::U32,
+        Endian::Host::U16,
+        Endian::Host::U16,
+        Endian::Host::U32,
+        Endian::Host::U32,
+      ])
+      private_constant :FORMAT
+
+      # Decodes a header from the decoder's current position.
+      #
+      # @param [Decoder] decoder the source decoder
+      # @return [NlMsgHdr] the decoded header
+      # @rbs (Decoder decoder) -> instance
+      def self.decode(decoder)
+        obj = new(*decoder.get_values(FORMAT))
+        decoder.align_to(Constants::NLMSG_ALIGNTO)
+        obj
+      end
+
+      # Encodes this header at the encoder's current position.
+      #
+      # @param [Encoder] encoder the destination encoder
+      # @return [void]
+      # @rbs (Encoder encoder) -> void
+      def encode(encoder)
+        encoder.reserve(Constants::NLMSG_HDRLEN)
+        encoder.put_values(FORMAT, to_a)
+        encoder.align_to(Constants::NLMSG_ALIGNTO)
+      end
+    end
+
+    # Fixed-format header prepended to every Netlink attribute.
+    #
+    # This corresponds to Linux's +struct nlattr+.
+    #
+    # @!attribute [rw] len
+    #   @return [Integer] attribute length in bytes, including this header but
+    #     excluding trailing alignment padding
+    # @!attribute [rw] type
+    #   @return [Integer] attribute type combined with optional +NLA_F_+ flags
+    NlAttr = Struct.new(
+      :len, #: Integer
+      :type, #: Integer
+    )
+
+    class NlAttr
+      FORMAT = Ractor.make_shareable([
+        Endian::Host::U16,
+        Endian::Host::U16,
+      ])
+      private_constant :FORMAT
+
+      # Decodes an attribute header from the decoder's current position.
+      #
+      # @param [Decoder] decoder the source decoder
+      # @return [NlAttr] the decoded header
+      # @rbs (Decoder decoder) -> instance
+      def self.decode(decoder)
+        obj = new(*decoder.get_values(FORMAT))
+        decoder.align_to(Constants::NLA_ALIGNTO)
+        obj
+      end
+
+      # Encodes this attribute header at the encoder's current position.
+      #
+      # @param [Encoder] encoder the destination encoder
+      # @return [void]
+      # @rbs (Encoder encoder) -> void
+      def encode(encoder)
+        encoder.reserve(Constants::NLA_HDRLEN)
+        encoder.put_values(FORMAT, to_a)
+        encoder.align_to(Constants::NLA_ALIGNTO)
+      end
+    end
+  end
+end

data/lib/nl/raw.rb

@@ -0,0 +1,104 @@
+require_relative 'family'
+require_relative 'raw/protocol'
+require_relative 'raw/client'
+require_relative 'attribute_set'
+require_relative 'structured_payload'
+
+module Nl
+  # Classic (Raw) Netlink families.
+  module Raw
+    # Base class for Raw Netlink families.
+    class Family < Nl::Family
+      # Opens a session for this raw Netlink family.
+      #
+      # @overload open(executor: nil, notification_capacity: DEFAULT_NOTIFICATION_CAPACITY)
+      #   The caller is responsible for closing the session.
+      #   @param [:thread, :fiber, nil] executor the asynchronous executor, or `nil` for blocking operation
+      #   @param [Integer] notification_capacity the maximum number of queued notifications
+      #   @return [Family] the opened family session
+      # @overload open(executor: nil, notification_capacity: DEFAULT_NOTIFICATION_CAPACITY, &block)
+      #   The session is automatically closed after the block returns.
+      #   @param [:thread, :fiber, nil] executor the asynchronous executor, or `nil` for blocking operation
+      #   @param [Integer] notification_capacity the maximum number of queued notifications
+      #   @yieldparam [Family] session the opened family session
+      #   @return [Object] the value returned from the block
+      # @rbs (?executor: executor?, ?notification_capacity: Integer?) -> (Nl::Family::Session & instance)
+      #    | [R] (?executor: executor?, ?notification_capacity: Integer?) { (instance) -> R } -> R
+      def self.open(executor: nil, notification_capacity: DEFAULT_NOTIFICATION_CAPACITY)
+        session = build_session(executor:, notification_capacity:)
+        return session unless block_given?
+
+        begin
+          yield session
+        ensure
+          session.close
+        end
+      end
+
+      class << self
+        # Builds a session that owns its underlying client.
+        #
+        # @param [:thread, :fiber, nil] executor the asynchronous executor, or `nil` for blocking operation
+        # @param [Integer] notification_capacity the maximum number of queued notifications
+        # @return [Family] the opened family session
+        # @rbs (executor: executor?, notification_capacity: Integer) -> (Nl::Family::Session & instance)
+        private def build_session(executor:, notification_capacity:)
+          owner = Client.new(protonum: self::PROTONUM, executor:, notification_capacity:)
+          owner.family(self).extend(Nl::Family::Session)
+        rescue Exception
+          owner&.close
+          raise
+        end
+      end
+    end
+
+    # Base class for raw Netlink messages.
+    #
+    # A message may contain a fixed header followed by a set of Netlink
+    # attributes.
+    class Message
+      include Nl::StructuredPayload
+
+      # @param [Object, nil] fixed_header the family-specific fixed header
+      # @param [AttributeSet, nil] attributes the message's attributes
+      # @rbs (?untyped fixed_header, ?AttributeSet? attributes) -> void
+      def initialize(fixed_header = nil, attributes = self.class::ATTRIBUTE_SET.new)
+        super
+      end
+
+      # Appends an attribute to the message.
+      #
+      # @param [AttributeSet::Attribute] attribute the attribute to append
+      # @return [void]
+      # @rbs (AttributeSet::Attribute attribute) -> void
+      def append_attribute(attribute)
+        @attributes << attribute
+      end
+
+      # Decodes a raw Netlink message payload.
+      #
+      # @param [Decoder] decoder the source decoder
+      # @param [Integer] type the message type from its Netlink header
+      # @return [Message] the decoded message
+      # @raise [RuntimeError] if +type+ does not match the message class's type
+      # @rbs (Decoder decoder, type: Integer) -> instance
+      def self.decode(decoder, type:)
+        unless self::TYPE == type
+          raise "Expected message type #{self::TYPE}, got #{type}"
+        end
+
+        super(decoder)
+      end
+
+      class << self
+        # Returns the attribute names accepted by this message.
+        #
+        # @return [Array<Symbol>] the attribute names
+        # @rbs () -> Array[Symbol]
+        private def attribute_names
+          self::ATTRIBUTES
+        end
+      end
+    end
+  end
+end

data/lib/nl/sequence_allocator.rb

@@ -0,0 +1,34 @@
+require_relative 'error'
+
+module Nl
+  # Allocates nonzero 32-bit Netlink sequence numbers.
+  class SequenceAllocator
+    MAX = 0xFFFFFFFF
+    private_constant :MAX
+
+    def initialize
+      @last = 0
+    end
+
+    # Returns the next sequence number not rejected by the optional block.
+    def next
+      first = advance
+      candidate = first
+
+      loop do
+        return candidate unless block_given? && yield(candidate)
+
+        candidate = advance
+        if candidate == first
+          raise ExhaustedSequenceNumber, 'all Netlink sequence numbers are in use'
+        end
+      end
+    end
+
+    private def advance
+      @last = @last == MAX ? 1 : @last + 1
+    end
+  end
+
+  private_constant :SequenceAllocator
+end

data/lib/nl/socket.rb

@@ -8,6 +8,11 @@ module Nl
     module Constants
       # From include/linux/socket.h
       PF_NETLINK = AF_NETLINK = 16
+
+      # From include/uapi/linux/netlink.h
+      SOL_NETLINK = 270
+      NETLINK_ADD_MEMBERSHIP = 1
+      NETLINK_DROP_MEMBERSHIP = 2
     end
     include Constants
 
@@ -21,7 +26,6 @@ module Nl
     # @param protonum [Integer] Netlink protocol number
     def initialize(protonum)
       super(PF_NETLINK, SOCK_RAW, protonum)
-      @seq = 0  # last-used sequence number
     end
 
     def self.open(protonum)
@@ -34,20 +38,19 @@ module Nl
       end
     end
 
-    # XXX: Should Protocol manage next_seq?
+    # @return [Integer] Local Netlink port ID assigned to this socket
+    def local_port_id
+      Socket.unpack_sockaddr_nl(local_address.to_sockaddr).first
+    end
 
-    # @return [Integer] Get next sequence number
-    def next_seq
-      nseq = (@seq + 1) & 0xFFFFFFFF
-      nseq = 1 if nseq == 0  # seq=0 is for notification
-      @seq = nseq
+    # Adds this socket to a Netlink multicast group.
+    def add_membership(group_id)
+      setsockopt(SOL_NETLINK, NETLINK_ADD_MEMBERSHIP, group_id)
     end
 
-    def complete(hdr)
-      [
-        hdr.seq ||= next_seq,
-        hdr.pid ||= Socket.unpack_sockaddr_nl(local_address.to_sockaddr).first,
-      ]
+    # Removes this socket from a Netlink multicast group.
+    def drop_membership(group_id)
+      setsockopt(SOL_NETLINK, NETLINK_DROP_MEMBERSHIP, group_id)
     end
   end
 end

data/lib/nl/structured_payload.rb

@@ -0,0 +1,61 @@
+module Nl
+  # Shared handling for a payload containing an optional fixed header followed
+  # by an optional attribute set.
+  module StructuredPayload
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    attr_accessor :fixed_header, :attributes
+
+    def initialize(fixed_header = nil, attributes = nil)
+      @fixed_header = fixed_header
+      @attributes = attributes
+    end
+
+    module ClassMethods
+      def from_params(params = nil, external_selectors: [], **keywords)
+        params = (params || {}).merge(keywords).transform_keys(&:to_sym)
+
+        if self::FIXED_HEADER
+          header_params = params.slice(*self::FIXED_HEADER.members)
+          fixed_header = self::FIXED_HEADER.new(**header_params)
+        else
+          header_params = {}
+        end
+
+        if self::ATTRIBUTE_SET
+          attribute_params = params.slice(*attribute_names)
+          attributes = self::ATTRIBUTE_SET.build_attributes(
+            attribute_params,
+            external_selectors:,
+          )
+        else
+          attribute_params = {}
+        end
+
+        unknown = params.keys - header_params.keys - attribute_params.keys
+        unless unknown.empty?
+          raise ArgumentError, "unknown parameters: #{unknown.join(', ')}"
+        end
+
+        new(fixed_header, attributes)
+      end
+
+      def decode(decoder, external_selectors: [])
+        fixed_header = self::FIXED_HEADER&.decode(decoder)
+        attributes = self::ATTRIBUTE_SET&.decode(decoder, external_selectors:)
+        new(fixed_header, attributes)
+      end
+
+      private def attribute_names
+        self::ATTRIBUTE_SET::BY_NAME.keys
+      end
+    end
+
+    def encode(encoder, external_selectors: [])
+      fixed_header&.encode(encoder)
+      attributes&.encode(encoder, external_selectors:)
+    end
+  end
+end