nl 0.3.0 → 0.4.1

data/lib/nl/family.rb

@@ -1,5 +1,3 @@
-#--
-# rbs_inline: enabled
 require_relative 'connection'
 require_relative 'notification'
 
@@ -9,14 +7,14 @@ module Nl
   #
   #   interface _Connection
   #     def exchange: (
-  #       Protocols::Raw protocol,
+  #       Raw::Endpoint endpoint,
   #       Symbol kind,
   #       Class request_class,
   #       Class reply_class,
   #       Hash[Symbol, untyped] args
   #     ) ?{ (untyped) -> void } -> untyped
   #     def exchange_async: (
-  #       Protocols::Raw protocol,
+  #       Raw::Endpoint endpoint,
   #       Symbol kind,
   #       Class request_class,
   #       Class reply_class,
@@ -24,12 +22,16 @@ module Nl
   #       ?stream_capacity: Integer?
   #     ) -> (Async::Future[untyped] | Async::Stream[untyped])
   #     def async_capable?: () -> bool
-  #     def register_notifications: (Protocols::Raw, Hash[Integer, Class]) -> NotificationChannel
+  #     def register_notifications: (Raw::Endpoint, Hash[Integer, Class]) -> NotificationChannel
   #     def add_memberships: (Array[Integer]) -> nil
   #     def drop_memberships: (Array[Integer]) -> nil
-  #     def receive_notification: (Protocols::Raw, ?timeout: Numeric?) -> untyped
+  #     def receive_notification: (Raw::Endpoint, ?timeout: Numeric?) -> untyped
   #     def close: () -> nil
   #   end
+  #
+  #   interface _FamilyClass[out F]
+  #     def new: (_Connection, endpoint: Raw::Endpoint) -> F
+  #   end
 
   class Family
     DEFAULT_NOTIFICATION_CAPACITY = Connection::DEFAULT_NOTIFICATION_CAPACITY
@@ -42,45 +44,19 @@ module Nl
 
     #--
     # @rbs connection: _Connection
-    # @rbs protocol: Protocol
+    # @rbs endpoint: Raw::Endpoint
     # @rbs return: instance
-    def initialize(connection, protocol: self.class::PROTOCOL)
-      @protocol = protocol
+    def initialize(connection, endpoint:)
+      @endpoint = endpoint
       @connection = connection
-      @connection.register_notifications(@protocol, notification_classes)
+      @connection.register_notifications(@endpoint, notification_classes)
       @notification_stream = NotificationStream.new do |timeout|
-        @connection.receive_notification(@protocol, timeout:)
-      end
-    end
-
-    #--
-    # @rbs (?executor: executor?, ?notification_capacity: Integer?) -> (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
-      # @rbs (?executor: executor?, notification_capacity: Integer) -> (Session & instance)
-      private def build_session(executor: nil, notification_capacity:)
-        protocol = self::PROTOCOL
-        connection = Connection.new(protocol:, executor:, notification_capacity:)
-        new(connection).extend(Session)
-      rescue Exception
-        connection&.close
-        raise
+        @connection.receive_notification(@endpoint, timeout:)
       end
     end
 
     private def exchange_message(kind, request_class, reply_class, args, &block)
-      @connection.exchange(@protocol, kind, request_class, reply_class, args, &block)
+      @connection.exchange(@endpoint, kind, request_class, reply_class, args, &block)
     end
 
     def async_capable? #: bool
@@ -126,7 +102,7 @@ module Nl
     end
 
     private def exchange_message_async(kind, request_class, reply_class, args, stream_capacity: nil)
-      @connection.exchange_async(@protocol, kind, request_class, reply_class, args, stream_capacity:)
+      @connection.exchange_async(@endpoint, kind, request_class, reply_class, args, stream_capacity:)
     end
 
     private def notification_classes
@@ -145,10 +121,11 @@ module Nl
       names.map do |name|
         key = name.to_sym
         group = multicast_groups.fetch(key) do
-          raise UnknownMulticastGroupError, "unknown multicast group #{name.inspect} for #{@protocol.name}"
+          raise UnknownMulticastGroupError, "unknown multicast group #{name.inspect} for #{@endpoint.name}"
         end
-        @protocol.multicast_group_id(group.name, group.id)
+        @endpoint.multicast_group_id(group.name, group.id)
       end
     end
   end
+
 end

data/lib/nl/genl/client.rb

@@ -0,0 +1,104 @@
+# Generic Netlink client handling
+
+require_relative '../connection'
+require_relative 'wire'
+
+module Nl
+  module Genl
+    # Dynamically resolved information for a generic Netlink family.
+    #
+    # @!attribute [r] id
+    #   @return [Integer] the assigned family ID
+    # @!attribute [r] multicast_groups
+    #   @return [Hash<String, Integer>] multicast group names mapped to their IDs
+    FamilyInfo = Data.define(
+      :id, #: Integer
+      :multicast_groups, #: Hash[String, Integer]
+    )
+
+    # Owns one generic Netlink connection shared by compatible families.
+    class Client
+      # Opens a generic Netlink client.
+      #
+      # @overload open(resolver:, executor: nil, notification_capacity: Nl::Connection::DEFAULT_NOTIFICATION_CAPACITY)
+      #   The caller is responsible for closing the client.
+      #   @param [#call] resolver a callable that resolves a family name to {FamilyInfo}
+      #   @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(resolver:, executor: nil, notification_capacity: Nl::Connection::DEFAULT_NOTIFICATION_CAPACITY, &block)
+      #   The client is automatically closed after the block returns.
+      #   @param [#call] resolver a callable that resolves a family name to {FamilyInfo}
+      #   @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 (resolver: ^(instance, ::String) -> FamilyInfo, ?executor: executor?, ?notification_capacity: Integer?) -> instance
+      #    | [R] (resolver: ^(instance, ::String) -> FamilyInfo, ?executor: executor?, ?notification_capacity: Integer?) { (instance) -> R } -> R
+      def self.open(resolver:, executor: nil, notification_capacity: Nl::Connection::DEFAULT_NOTIFICATION_CAPACITY)
+        client = new(resolver:, executor:, notification_capacity:)
+        return client unless block_given?
+
+        begin
+          yield client
+        ensure
+          client.close
+        end
+      end
+
+      # @param [#call] resolver a callable that resolves a family name to {FamilyInfo}
+      # @param [:thread, :fiber, nil] executor the asynchronous executor, or `nil` for blocking operation
+      # @param [Integer] notification_capacity the maximum number of queued notifications
+      # @rbs (resolver: ^(instance, ::String) -> FamilyInfo, ?executor: executor?, ?notification_capacity: Integer?) -> void
+      def initialize(resolver:, executor: nil, notification_capacity: Nl::Connection::DEFAULT_NOTIFICATION_CAPACITY)
+        @resolver = resolver
+        @family_cache = {}
+        @family_cache_mutex = Mutex.new
+        @connection = Nl::Connection.new(
+          protocol: Protocol.new,
+          executor:,
+          notification_capacity:,
+        )
+      end
+
+      # Builds a family backed by this client's connection.
+      #
+      # @param [Class<Family>] family_class a generic Netlink family class
+      # @return [Family] an instance of `family_class`
+      # @raise [TypeError] if +family_class+ does not inherit from {Family}
+      # @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
+
+        info = family_info(family_class::NAME)
+        family_class.new(
+          @connection,
+          endpoint: Endpoint.new(family_class, info),
+        )
+      end
+
+      # Closes the underlying Netlink connection.
+      #
+      # @return [void]
+      # @rbs () -> void
+      def close
+        @connection.close
+      end
+
+      # Resolves and caches information for a family by name.
+      #
+      # @param [String] name the generic Netlink family name
+      # @return [FamilyInfo] the resolved family information
+      # @rbs (String name) -> FamilyInfo
+      private def family_info(name)
+        cached_info = @family_cache_mutex.synchronize { @family_cache[name] }
+        return cached_info if cached_info
+
+        info = @resolver.call(self, name)
+        @family_cache_mutex.synchronize { @family_cache[name] ||= info }
+      end
+    end
+  end
+end

data/lib/nl/genl/protocol.rb

@@ -0,0 +1,59 @@
+require_relative 'wire'
+require_relative '../raw'
+
+module Nl
+  module Genl
+    # A generated Generic Netlink family bound to nlctrl-provided information.
+    class Endpoint < Raw::Endpoint
+      attr_reader :info
+
+      def initialize(definition, info)
+        super(definition)
+        @info = info
+      end
+
+      def family_id = @info.id
+      def version = @definition.version
+      def frame_type(_message_class) = family_id
+
+      def multicast_group_id(name, _value)
+        @info.multicast_groups.fetch(name) do
+          raise UnresolvedMulticastGroupError,
+            "Generic Netlink multicast group #{name.inspect} was not resolved"
+        end
+      end
+    end
+
+    # Socket-wide Generic Netlink wire behavior.
+    class Protocol < Raw::Protocol
+      def initialize
+        super(Raw::NETLINK_GENERIC)
+      end
+
+      def encode_message(encoder, endpoint, request, seq:, pid:)
+        message = request.message
+        header = Raw::NlMsgHdr.new(0, request.type, request.flags, seq, pid)
+        encoder.measure(Endian::Host::U16) do
+          header.encode(encoder)
+          Nl::Genl::GenlMsgHdr.new(message.class::TYPE, endpoint.version, 0).encode(encoder)
+          message.encode(encoder)
+        end
+      end
+
+      def notification_channel_key(endpoint) = endpoint.family_id
+      def notification_route_keys(endpoint, _classes) = [endpoint.family_id]
+      def notification_frame_key(header) = header.type
+
+      def notification_frame?(endpoint, header, _payload)
+        header.type == endpoint.family_id
+      end
+
+      def notification_class(endpoint, header, payload, classes)
+        return unless notification_frame?(endpoint, header, payload)
+
+        command = Nl::Genl::GenlMsgHdr.decode(Decoder.new(payload)).cmd
+        classes[command]
+      end
+    end
+  end
+end

data/lib/nl/genl/wire.rb

@@ -0,0 +1,94 @@
+# Generic Netlink wire definitions
+
+require_relative '../raw/wire'
+require_relative '../endian'
+
+module Nl
+  module Genl
+    # Constants from <linux/genetlink.h>
+    module Constants
+      GENL_NAMSIZ = 16
+      GENL_MIN_ID = Raw::NLMSG_MIN_TYPE
+      GENL_MAX_ID = 1023
+
+      GENL_HDRLEN = 4
+
+      GENL_ID_GENERATE = 0
+      GENL_ID_CTRL = Raw::NLMSG_MIN_TYPE
+      GENL_ID_VFS_DQUOT = Raw::NLMSG_MIN_TYPE + 1
+      GENL_ID_PMCRAID = Raw::NLMSG_MIN_TYPE + 2
+
+      CTRL_CMD_UNSPEC = 0
+      CTRL_CMD_NEWFAMILY = 1
+      CTRL_CMD_DELFAMILY = 2
+      CTRL_CMD_GETFAMILY = 3
+      CTRL_CMD_NEWOPS = 4
+      CTRL_CMD_DELOPS = 5
+      CTRL_CMD_GETOPS = 6
+      CTRL_CMD_NEWMCAST_GRP = 7
+      CTRL_CMD_DELMCAST_GRP = 8
+      CTRL_CMD_GETMCAST_GRP = 9
+
+      CTRL_ATTR_UNSPEC = 0
+      CTRL_ATTR_FAMILY_ID = 1
+      CTRL_ATTR_FAMILY_NAME = 2
+      CTRL_ATTR_VERSION = 3
+      CTRL_ATTR_HDRSIZE = 4
+      CTRL_ATTR_MAXATTR = 5
+      CTRL_ATTR_OPS = 6
+      CTRL_ATTR_MCAST_GROUPS = 7
+
+      CTRL_ATTR_OP_UNSPEC = 0
+      CTRL_ATTR_OP_ID = 1
+      CTRL_ATTR_OP_FLAGS = 2
+
+      CTRL_ATTR_MCAST_GRP_UNSPEC = 0
+      CTRL_ATTR_MCAST_GRP_NAME = 1
+      CTRL_ATTR_MCAST_GRP_ID = 2
+    end
+    include Constants
+
+    # Header prepended to a Generic Netlink payload after the Netlink header.
+    #
+    # This corresponds to Linux's +struct genlmsghdr+.
+    #
+    # @!attribute [rw] cmd
+    #   @return [Integer] family-specific command identifier
+    # @!attribute [rw] version
+    #   @return [Integer] family-specific protocol version
+    # @!attribute [rw] reserved
+    #   @return [Integer] reserved field, which must be zero
+    GenlMsgHdr = Struct.new(
+      :cmd, #: Integer
+      :version, #: Integer
+      :reserved, #: Integer
+    )
+
+    class GenlMsgHdr
+      FORMAT = Ractor.make_shareable([
+        Endian::Host::U8,
+        Endian::Host::U8,
+        Endian::Host::U16,
+      ])
+      private_constant :FORMAT
+
+      # Decodes a header from the decoder's current position.
+      #
+      # @param [Decoder] decoder the source decoder
+      # @return [GenlMsgHdr] the decoded header
+      # @rbs (Decoder decoder) -> instance
+      def self.decode(decoder)
+        new(*decoder.get_values(FORMAT))
+      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.put_values(FORMAT, to_a)
+      end
+    end
+  end
+end

data/lib/nl/genl.rb

@@ -1,74 +1,74 @@
-# Generic Netlink wire definitions
-#--
-# rbs_inline: enabled
+# Generic Netlink family support
 
-require_relative 'core'
-require_relative 'endian'
+require_relative 'genl/wire'
+require_relative 'family'
+require_relative 'raw'
+require_relative 'genl/protocol'
 
 module Nl
+  # Generic Netlink families.
   module Genl
-    module Constants
-      # From include/uapi/linux/genetlink.
-      GENL_NAMSIZ = 16
-      GENL_MIN_ID = Core::NLMSG_MIN_TYPE
-      GENL_MAX_ID = 1023
+    # Base class for Generic Netlink families.
+    class Family < Nl::Family
+      # Returns the family-specific protocol version.
+      #
+      # @return [Integer] the protocol version
+      # @rbs () -> Integer
+      def self.version = self::VERSION
 
-      GENL_HDRLEN = 4
+      # Opens a session for this Generic Netlink family.
+      #
+      # @overload open(resolver:, executor: nil, notification_capacity: DEFAULT_NOTIFICATION_CAPACITY)
+      #   The caller is responsible for closing the session.
+      #   @param [#call] resolver a callable that resolves a family name to {FamilyInfo}
+      #   @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(resolver:, executor: nil, notification_capacity: DEFAULT_NOTIFICATION_CAPACITY, &block)
+      #   The session is automatically closed after the block returns.
+      #   @param [#call] resolver a callable that resolves a family name to {FamilyInfo}
+      #   @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 (resolver: ^(Client, ::String) -> FamilyInfo, ?executor: executor?, ?notification_capacity: Integer?) -> (Nl::Family::Session & instance)
+      #    | [R] (resolver: ^(Client, ::String) -> FamilyInfo, ?executor: executor?, ?notification_capacity: Integer?) { (instance) -> R } -> R
+      def self.open(resolver:, executor: nil, notification_capacity: DEFAULT_NOTIFICATION_CAPACITY)
+        begin
+          owner = Client.new(resolver:, executor:, notification_capacity:)
+          session = owner.family(self).extend(Nl::Family::Session)
+        rescue Exception
+          owner&.close
+          raise
+        end
+        return session unless block_given?
 
-      GENL_ID_GENERATE = 0
-      GENL_ID_CTRL = Core::NLMSG_MIN_TYPE
-      GENL_ID_VFS_DQUOT = Core::NLMSG_MIN_TYPE + 1
-      GENL_ID_PMCRAID = Core::NLMSG_MIN_TYPE + 2
-
-      CTRL_CMD_UNSPEC = 0
-      CTRL_CMD_NEWFAMILY = 1
-      CTRL_CMD_DELFAMILY = 2
-      CTRL_CMD_GETFAMILY = 3
-      CTRL_CMD_NEWOPS = 4
-      CTRL_CMD_DELOPS = 5
-      CTRL_CMD_GETOPS = 6
-      CTRL_CMD_NEWMCAST_GRP = 7
-      CTRL_CMD_DELMCAST_GRP = 8
-      CTRL_CMD_GETMCAST_GRP = 9
-
-      CTRL_ATTR_UNSPEC = 0
-      CTRL_ATTR_FAMILY_ID = 1
-      CTRL_ATTR_FAMILY_NAME = 2
-      CTRL_ATTR_VERSION = 3
-      CTRL_ATTR_HDRSIZE = 4
-      CTRL_ATTR_MAXATTR = 5
-      CTRL_ATTR_OPS = 6
-      CTRL_ATTR_MCAST_GROUPS = 7
-
-      CTRL_ATTR_OP_UNSPEC = 0
-      CTRL_ATTR_OP_ID = 1
-      CTRL_ATTR_OP_FLAGS = 2
-
-      CTRL_ATTR_MCAST_GRP_UNSPEC = 0
-      CTRL_ATTR_MCAST_GRP_NAME = 1
-      CTRL_ATTR_MCAST_GRP_ID = 2
-    end
-    include Constants
-
-    GenlMsgHdr = Struct.new(:cmd, :version, :reserved)
-    # Generic Netlink message header
-    class GenlMsgHdr
-      FORMAT = Ractor.make_shareable([
-        Endian::Host::U8,
-        Endian::Host::U8,
-        Endian::Host::U16,
-      ])
-      private_constant :FORMAT
-
-      def self.decode(decoder)
-        new(*decoder.get_values(FORMAT))
+        begin
+          yield session
+        ensure
+          session.close
+        end
       end
+    end
 
-      def encode(encoder)
-        encoder.put_values(FORMAT, to_a)
+    # Base class for Generic Netlink messages.
+    #
+    # A Generic Netlink message payload begins with a {GenlMsgHdr}, followed by
+    # the optional fixed header and attributes handled by {Raw::Message}.
+    class Message < Raw::Message
+      # Decodes a Generic Netlink message payload.
+      #
+      # @param [Decoder] decoder the source decoder
+      # @param [Integer] type the family ID from the Netlink message header
+      # @return [Message] the decoded message
+      # @raise [RuntimeError] if the command does not match the message class's type
+      # @rbs (Decoder decoder, type: Integer) -> instance
+      def self.decode(decoder, type:)
+        genlhdr = GenlMsgHdr.decode(decoder)
+        super(decoder, type: genlhdr.cmd)
       end
     end
   end
 end
 
-require_relative 'genl/connection'
+require_relative 'genl/client'

data/lib/nl/notification.rb

@@ -1,5 +1,3 @@
-# rbs_inline: enabled
-
 require_relative 'error'
 
 module Nl
@@ -7,9 +5,6 @@ module Nl
   # `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:)
@@ -96,7 +91,7 @@ module Nl
 
   # An unbounded-in-time, single-family view of unsolicited messages.
   class NotificationStream
-    include Enumerable
+    include Enumerable #[untyped]
 
     def initialize(&receive)
       @receive = receive
@@ -106,6 +101,8 @@ module Nl
       @receive.call(timeout)
     end
 
+    # @rbs () -> Enumerator[untyped, void]
+    #  | () { (untyped) -> void } -> void
     def each
       return enum_for(__method__) unless block_given?
 

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 }