nl 0.3.0 → 0.4.1

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

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

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

data/lib/nl/sub_message.rb

@@ -0,0 +1,94 @@
+require_relative 'structured_payload'
+
+module Nl
+  module Selector
+    class MissingSelectorValueError < StandardError
+      attr_reader :scope, :index
+
+      def initialize(scope, index)
+        @scope = scope
+        @index = index
+        super()
+      end
+    end
+
+    class UnknownSelectorValueError < StandardError
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+        super()
+      end
+    end
+
+    module Reference
+      def select(context, formats)
+        value = read(context)
+        formats.fetch(value) do
+          return yield(value) if block_given?
+          raise UnknownSelectorValueError.new(value)
+        end
+      end
+    end
+
+    Local = Data.define(:index) do
+      include Reference
+
+      def read(context)
+        context.fetch_local(index)
+      end
+    end
+
+    External = Data.define(:index) do
+      include Reference
+
+      def read(context)
+        context.fetch_external(index)
+      end
+    end
+
+    class State
+      def initialize(local_count, external)
+        @local = Array.new(local_count)
+        @external = external
+      end
+
+      def set_local(index, value)
+        @local[index] = value
+      end
+
+      def fetch_local(index)
+        fetch(@local, index) { raise MissingSelectorValueError.new(:local, index) }
+      end
+
+      def fetch_external(index)
+        fetch(@external, index) { raise MissingSelectorValueError.new(:external, index) }
+      end
+
+      def fetch(values, key)
+        value = values[key]
+        value.nil? ? yield : value
+      end
+    end
+  end
+
+  # A selector-specific payload containing an optional fixed header followed by
+  # an optional set of Netlink attributes.
+  class SubMessage
+    include StructuredPayload
+  end
+
+  # An unrecognized selector-specific payload retained without interpretation.
+  class RawSubMessage < SubMessage
+    attr_reader :payload, :nlattr_type_flags
+
+    def initialize(payload, nlattr_type_flags:)
+      @payload = payload
+      @nlattr_type_flags = nlattr_type_flags
+    end
+
+    def encode(encoder, external_selectors: [])
+      encoder.put_string(payload)
+    end
+  end
+end

data/lib/nl/version.rb

@@ -1,3 +1,3 @@
 module Nl
-  VERSION = '0.3.0'
+  VERSION = '0.4.1'
 end

data/lib/nl.rb

@@ -1,13 +1,12 @@
 require_relative 'nl/error'
-require_relative 'nl/core'
+require_relative 'nl/bitfield32'
+require_relative 'nl/raw/wire'
+require_relative 'nl/structured_payload'
+require_relative 'nl/sub_message'
 require_relative 'nl/notification'
 require_relative 'nl/connection'
 require_relative 'nl/family'
+require_relative 'nl/raw'
 require_relative 'nl/genl'
 require_relative 'nl/socket'
 require_relative 'nl/version'
-
-module Nl
-  include Core
-  include Genl
-end

data/sig/generated/nl/async/dispatcher.rbs

@@ -0,0 +1,53 @@
+# Generated from lib/nl/async/dispatcher.rb with RBS::Inline
+
+module Nl
+  module Async
+    # Owns the single receive loop for a socket and routes replies by sequence.
+    class Dispatcher
+      class Pending < Data
+        attr_reader exchange(): untyped
+
+        attr_reader endpoint(): untyped
+
+        attr_reader reply_class(): untyped
+
+        attr_reader sink(): untyped
+
+        def self.new: (untyped exchange, untyped endpoint, untyped reply_class, untyped sink) -> instance
+                    | (exchange: untyped, endpoint: untyped, reply_class: untyped, sink: untyped) -> instance
+
+        def self.members: () -> [ :exchange, :endpoint, :reply_class, :sink ]
+
+        def members: () -> [ :exchange, :endpoint, :reply_class, :sink ]
+      end
+
+      def initialize: (untyped socket, protocol: untyped, notifications: untyped, ?executor: untyped) -> untyped
+
+      def exchange: (untyped endpoint, untyped kind, untyped request_class, untyped reply_class, untyped args) ?{ (?) -> untyped } -> untyped
+
+      def exchange_async: (untyped endpoint, untyped kind, untyped request_class, untyped reply_class, untyped args, ?stream_capacity: untyped) -> untyped
+
+      def async_capable?: () -> true
+
+      def receive_notification: (untyped endpoint, ?timeout: untyped) -> untyped
+
+      def close: () -> untyped
+
+      private def receive_loop: () -> untyped
+
+      private def fail_receive_loop: (untyped error) -> untyped
+
+      private def dispatch_datagram: (untyped buffer) -> untyped
+
+      private def dispatch_outcome: (untyped key, untyped pending, untyped outcome) -> untyped
+
+      private def complete_pending: (untyped key, untyped pending, untyped value) -> untyped
+
+      private def discard: (untyped key) -> untyped
+
+      private def fail_pending: (untyped key, untyped error) -> untyped
+
+      private def fail_all: (untyped error) -> untyped
+    end
+  end
+end