nl 0.3.0 → 0.4.2

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,97 +22,93 @@ 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
+    DEFAULT_NOTIFICATION_CAPACITY = Connection::DEFAULT_NOTIFICATION_CAPACITY #: Integer
 
+    # Socket-owning family.
+    #
+    # {Family} instances that owns sockets are extended with this module.
     module Session
-      def close #: nil
+      # Closes the Netlink socket owned by this {Family}.
+      # @rbs () -> void
+      def close
         @connection.close
       end
     end
 
-    #--
-    # @rbs connection: _Connection
-    # @rbs protocol: Protocol
-    # @rbs return: instance
-    def initialize(connection, protocol: self.class::PROTOCOL)
-      @protocol = protocol
+    # @rbs (_Connection connection, endpoint: Raw::Endpoint) -> instance
+    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
+    # Returns if this family supports asynchronous operations.
+    #
+    # @rbs () -> bool
+    def async_capable?
       @connection.async_capable?
     end
 
-    # Adds multicast memberships to the existing family socket. Membership is
-    # additive and remains active until explicitly removed or the owner closes.
+    # Adds multicast memberships to the netlink socket.
+    #
+    # Membership is additive and remains active until explicitly removed or the owner closes.
+    #
+    # @param [Array<Symbol>] groups
+    # @return [Family] self
+    # @rbs (Symbol *groups) -> self
     def subscribe(*groups)
       @connection.add_memberships(multicast_group_ids(groups))
       self
     end
 
+    # Removes multicast memberships from the netlink socket.
+    #
+    # @param [Array<Symbol>] groups
+    # @return [Family] self
+    # @rbs (Symbol *groups) -> self
     def unsubscribe(*groups)
       @connection.drop_memberships(multicast_group_ids(groups))
       self
     end
 
+    # Receives the next unsolicited message.
+    #
+    # @rbs (?timeout: Integer?) -> Message
     def receive_notification(timeout: nil)
       @notification_stream.next(timeout:)
     end
 
+    # Receives unsolicited messages.
+    #
+    # @rbs () { (Message) -> void } -> void
     def each_notification(&block)
       return @notification_stream.each unless block
 
       @notification_stream.each(&block)
     end
 
-    # Builds a generated asynchronous-operation facade with a narrowly scoped
-    # callback, so the facade does not need access to Family's private API.
-    #--
-    # @rbs operations_class: Class
-    # @rbs stream_capacity: Integer?
-    # @rbs return: untyped
+    # Builds a asynchronous-operation facade.
+    #
+    # @rbs (Class operations_class, ?stream_capacity: Integer?) -> untyped
     private def build_async_facade(operations_class, stream_capacity: nil)
       unless async_capable?
         raise Async::UnavailableError, 'async operations require an executor'
@@ -126,7 +120,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 +139,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,105 @@
+# 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,95 @@
+# 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,72 @@
-# Generic Netlink wire definitions
-#--
-# rbs_inline: enabled
-
-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
-
-      GENL_HDRLEN = 4
-
-      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
+    # 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
 
-      CTRL_ATTR_OP_UNSPEC = 0
-      CTRL_ATTR_OP_ID = 1
-      CTRL_ATTR_OP_FLAGS = 2
+      # 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?
 
-      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?