nl 0.2.4 → 0.4.1

data/lib/nl/family.rb

@@ -1,37 +1,131 @@
-#--
-# rbs_inline: enabled
-require_relative 'socket'
+require_relative 'connection'
+require_relative 'notification'
 
 module Nl
+  # @rbs!
+  #   type executor = :thread | :fiber
+  #
+  #   interface _Connection
+  #     def exchange: (
+  #       Raw::Endpoint endpoint,
+  #       Symbol kind,
+  #       Class request_class,
+  #       Class reply_class,
+  #       Hash[Symbol, untyped] args
+  #     ) ?{ (untyped) -> void } -> untyped
+  #     def exchange_async: (
+  #       Raw::Endpoint endpoint,
+  #       Symbol kind,
+  #       Class request_class,
+  #       Class reply_class,
+  #       Hash[Symbol, untyped] args,
+  #       ?stream_capacity: Integer?
+  #     ) -> (Async::Future[untyped] | Async::Stream[untyped])
+  #     def async_capable?: () -> bool
+  #     def register_notifications: (Raw::Endpoint, Hash[Integer, Class]) -> NotificationChannel
+  #     def add_memberships: (Array[Integer]) -> nil
+  #     def drop_memberships: (Array[Integer]) -> nil
+  #     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
+
+    module Session
+      def close #: nil
+        @connection.close
+      end
+    end
+
     #--
-    # @rbs socket: Socket
-    # @rbs protocol: Protocol
+    # @rbs connection: _Connection
+    # @rbs endpoint: Raw::Endpoint
     # @rbs return: instance
-    def initialize(socket, protocol: self.class::PROTOCOL)
-      @socket = socket
-      @protocol = protocol
+    def initialize(connection, endpoint:)
+      @endpoint = endpoint
+      @connection = connection
+      @connection.register_notifications(@endpoint, notification_classes)
+      @notification_stream = NotificationStream.new do |timeout|
+        @connection.receive_notification(@endpoint, timeout:)
+      end
+    end
+
+    private def exchange_message(kind, request_class, reply_class, args, &block)
+      @connection.exchange(@endpoint, kind, request_class, reply_class, args, &block)
+    end
+
+    def async_capable? #: bool
+      @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.
+    def subscribe(*groups)
+      @connection.add_memberships(multicast_group_ids(groups))
+      self
+    end
+
+    def unsubscribe(*groups)
+      @connection.drop_memberships(multicast_group_ids(groups))
+      self
+    end
+
+    def receive_notification(timeout: nil)
+      @notification_stream.next(timeout:)
     end
 
+    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 () -> instance
-    #  | [R] () { (instance) -> R } -> R
-    def self.open
-      begin
-        socket = Socket.new(self::PROTOCOL.protonum)
-        socket.bind(Socket.sockaddr_nl(0, 0))
-        if block_given?
-          yield new(socket)
-        else
-          return new(socket)
-        end
-      ensure
-        socket&.close if block_given?
+    # @rbs operations_class: Class
+    # @rbs stream_capacity: Integer?
+    # @rbs return: untyped
+    private def build_async_facade(operations_class, stream_capacity: nil)
+      unless async_capable?
+        raise Async::UnavailableError, 'async operations require an executor'
       end
+
+      operations_class.new do |kind, request_class, reply_class, args|
+        exchange_message_async(kind, request_class, reply_class, args, stream_capacity:)
+      end
+    end
+
+    private def exchange_message_async(kind, request_class, reply_class, args, stream_capacity: nil)
+      @connection.exchange_async(@endpoint, kind, request_class, reply_class, args, stream_capacity:)
     end
 
-    private def exchange_message(type, request_class, reply_class, args, &block)
-      @protocol.exchange_message(@socket, type, request_class, reply_class, args, &block)
+    private def notification_classes
+      self.class.const_get(:NOTIFICATIONS, false)
+    rescue NameError
+      {}
+    end
+
+    private def multicast_groups
+      self.class.const_get(:MCAST_GROUPS, false)
+    rescue NameError
+      {}
+    end
+
+    private def multicast_group_ids(names)
+      names.map do |name|
+        key = name.to_sym
+        group = multicast_groups.fetch(key) do
+          raise UnknownMulticastGroupError, "unknown multicast group #{name.inspect} for #{@endpoint.name}"
+        end
+        @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,87 +1,74 @@
-# General Netlink message handling
+# 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
-
-      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
-
-    class Connection
-      def self.open(resolver:)
-        conn = new(resolver:)
-        if block_given?
-          begin
-            yield conn
-          ensure
-            conn.close
-          end
-        else
-          conn
+      # 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
-      end
-
-      def initialize(resolver:)
-        @socket = Socket.new(Core::NETLINK_GENERIC)
-        @socket.bind(Socket.sockaddr_nl(0, 0))
-        @resolver = resolver
-        @id_cache = {}
-      end
+        return session unless block_given?
 
-      def open(family_class)
-        proto = family_class::PROTOCOL
-        id = @id_cache[proto.name] ||= begin
-          proto.family_id
-        rescue NotImplementedError
-          @resolver.call(@socket, proto.name)
+        begin
+          yield session
+        ensure
+          session.close
         end
-        family_class.new(@socket, protocol: Protocols::Genl.new(proto.name, family_id: id))
       end
+    end
 
-      def close
-        @socket.close
+    # 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/client'

data/lib/nl/notification.rb

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