nl 0.3.0 → 0.4.2

data/lib/nl/notification_router.rb

@@ -1,64 +1,70 @@
-require_relative 'core'
+require_relative 'raw/wire'
 require_relative 'notification'
 
 module Nl
   # Routes unsolicited frames to per-family notification channels.
   class NotificationRouter
-    Entry = Struct.new(:protocol, :classes, :channel)
+    Entry = Struct.new(:endpoint, :classes, :channel)
     private_constant :Entry
 
-    def initialize(routing:, capacity:)
-      @routing = routing
+    def initialize(protocol:, capacity:)
+      @protocol = protocol
       @capacity = capacity
       @mutex = Mutex.new
       @entries = {}
+      @routes = {}
       @closed = false
     end
 
-    def register(protocol, classes)
+    def register(endpoint, 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
+        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(protocol)
+    def channel(endpoint)
       @mutex.synchronize do
-        @entries.fetch(@routing.family_key(protocol)).channel
+        @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 == Core::NLMSG_OVERRUN
+      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
-        @entries[@routing.frame_key(header)]
+        @routes[@protocol.notification_frame_key(header)]
       end
       return false unless entry
-      return false unless entry.protocol.notification_frame?(header, payload)
+      return false unless @protocol.notification_frame?(entry.endpoint, 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
+      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 Exception => error
+    rescue => error
       entry&.channel&.fail(error)
       true
     end
@@ -70,6 +76,7 @@ module Nl
         @closed = true
         old = @entries.values
         @entries.clear
+        @routes.clear
         old
       end
       entries.each { it.channel.close }

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,147 @@
+# 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

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

data/lib/nl/socket.rb

@@ -1,15 +1,15 @@
-# Netlink sockets
-
 require 'socket'
 
 module Nl
   # Netlink socket
   class Socket < ::Socket
     module Constants
-      # From include/linux/socket.h
+      # From linux/socket.h
+      #-
       PF_NETLINK = AF_NETLINK = 16
 
-      # From include/uapi/linux/netlink.h
+      # From linux/netlink.h
+      #-
       SOL_NETLINK = 270
       NETLINK_ADD_MEMBERSHIP = 1
       NETLINK_DROP_MEMBERSHIP = 2
@@ -17,17 +17,28 @@ module Nl
     include Constants
 
     class << self
+      # Packs Netlink socket address
+      #
+      # @rbs (Integer pid, Integer groups) -> String
       def pack_sockaddr_nl(pid, groups) = [Socket::AF_NETLINK, 0, pid, groups].pack('S!S!LL')
       alias sockaddr_nl pack_sockaddr_nl
 
+      # Unpacks Netlink socket address
+      #
+      # @rbs (String) -> [Integer, Integer]
       def unpack_sockaddr_nl(sockaddr) = sockaddr.unpack('S!S!LL')[2..3]
     end
 
-    # @param protonum [Integer] Netlink protocol number
+    # @param [Integer] protonum Netlink protocol number
+    # @rbs (Integer) -> void
     def initialize(protonum)
       super(PF_NETLINK, SOCK_RAW, protonum)
     end
 
+    # Opens a Netlink socket for the specified protocol number.
+    #
+    # @rbs (Integer protonum) -> instance
+    #    | [R] (Integer protonum) { (instance) -> R } -> R
     def self.open(protonum)
       return new(protonum) unless block_given?
       begin
@@ -39,16 +50,21 @@ module Nl
     end
 
     # @return [Integer] Local Netlink port ID assigned to this socket
+    # @rbs () -> Integer
     def local_port_id
       Socket.unpack_sockaddr_nl(local_address.to_sockaddr).first
     end
 
     # Adds this socket to a Netlink multicast group.
+    #
+    # @rbs (Integer group_id) -> void
     def add_membership(group_id)
       setsockopt(SOL_NETLINK, NETLINK_ADD_MEMBERSHIP, group_id)
     end
 
     # Removes this socket from a Netlink multicast group.
+    #
+    # @rbs (Integer group_id) -> void
     def drop_membership(group_id)
       setsockopt(SOL_NETLINK, NETLINK_DROP_MEMBERSHIP, group_id)
     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