nl 0.2.4 → 0.3.0

data/lib/nl/blocking_transport.rb

@@ -0,0 +1,131 @@
+# rbs_inline: enabled
+
+require_relative 'datagram'
+require_relative 'exchange'
+require_relative 'notification_router'
+require_relative 'sequence_allocator'
+
+module Nl
+  # Drives one exchange at a time with blocking socket operations.
+  class BlockingTransport
+    class ConcurrentOperationError < StandardError; end
+
+    class UnexpectedSequenceError < StandardError
+      attr_reader :expected, :actual
+
+      def initialize(expected, actual)
+        @expected = expected
+        @actual = actual
+        super("expected Netlink sequence and port ID #{expected.inspect}, got #{actual.inspect}")
+      end
+    end
+
+    def initialize(socket, notifications:)
+      @socket = socket
+      @sequences = SequenceAllocator.new
+      @mutex = Mutex.new
+      @notifications = notifications
+    end
+
+    def exchange(protocol, kind, request_class, reply_class, args)
+      unless locked = @mutex.try_lock
+        raise ConcurrentOperationError, 'BlockingTransport supports only one active operation'
+      end
+
+      request = protocol.build_request(kind, request_class, args)
+      seq = @sequences.next
+      pid = @socket.local_port_id
+      key = [seq, pid]
+      protocol.send_message(@socket, request, seq:, pid:)
+      exchange = Exchange.new(kind:, expects_reply: !reply_class.nil?)
+      result = [] unless block_given?
+
+      until exchange.complete?
+        receive(protocol, key, reply_class) do |message|
+          case outcome = exchange.accept(message)
+          when Exchange::Item
+            block_given? ? yield(outcome.value) : result << outcome.value
+          when Exchange::Failure
+            raise outcome.exception
+          end
+        end
+      end
+
+      return if block_given?
+
+      kind == :dump ? result : exchange.result
+    ensure
+      @mutex.unlock if locked
+    end
+
+    def async_capable? #: false
+      false
+    end
+
+    def receive_notification(protocol, timeout: nil)
+      channel = @notifications.channel(protocol)
+      return channel.pop(timeout: 0)
+    rescue TimeoutError
+      unless locked = @mutex.try_lock
+        raise ConcurrentOperationError, 'BlockingTransport supports only one active operation'
+      end
+
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout if timeout
+      loop do
+        begin
+          return channel.pop(timeout: 0)
+        rescue TimeoutError
+          # Read another datagram below.
+        end
+
+        remaining = deadline && deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise TimeoutError, 'notification receive timed out' if remaining && remaining <= 0
+        if remaining && !@socket.wait_readable(remaining)
+          raise TimeoutError, 'notification receive timed out'
+        end
+
+        receive_notifications
+      end
+    ensure
+      @mutex.unlock if locked
+    end
+
+    def close #: void
+      @socket.close unless @socket.closed?
+      nil
+    end
+
+    private def receive(protocol, expected_key, reply_class)
+      Datagram.each_frame(receive_datagram) do |header, payload|
+        actual_key = [header.seq, header.pid]
+        if actual_key == expected_key
+          yield protocol.decode_frame(header, payload, reply_class)
+        elsif header.seq.zero?
+          @notifications.route(header, payload)
+        else
+          raise UnexpectedSequenceError.new(expected_key, actual_key)
+        end
+      end
+    rescue Errno::ENOBUFS
+      @notifications.lose_all(NotificationLossError.new('kernel receive buffer overflowed'))
+      raise
+    end
+
+    private def receive_notifications
+      Datagram.each_frame(receive_datagram) do |header, payload|
+        if header.seq.zero?
+          @notifications.route(header, payload)
+        else
+          raise UnexpectedSequenceError.new(nil, [header.seq, header.pid])
+        end
+      end
+    rescue Errno::ENOBUFS
+      @notifications.lose_all(NotificationLossError.new('kernel receive buffer overflowed'))
+    end
+
+    private def receive_datagram
+      data, = @socket.recvmsg
+      IO::Buffer.for(data)
+    end
+  end
+end

data/lib/nl/connection.rb

@@ -0,0 +1,63 @@
+# rbs_inline: enabled
+
+require_relative 'async'
+require_relative 'blocking_transport'
+require_relative 'notification_router'
+require_relative 'socket'
+
+module Nl
+  # Owns one Netlink socket and the facilities shared by families using it.
+  class Connection
+    DEFAULT_NOTIFICATION_CAPACITY = 1_024
+
+    def initialize(protocol:, executor: nil, notification_capacity: DEFAULT_NOTIFICATION_CAPACITY)
+      socket = Socket.new(protocol.protonum)
+      socket.bind(Socket.sockaddr_nl(0, 0))
+      notifications = NotificationRouter.new(
+        routing: protocol.notification_routing,
+        capacity: notification_capacity,
+      )
+
+      @socket = socket
+      @notifications = notifications
+      @transport = if executor
+        Async::Dispatcher.new(socket, executor:, notifications:)
+      else
+        BlockingTransport.new(socket, notifications:)
+      end
+    rescue Exception
+      @transport ? @transport.close : socket&.close
+      notifications&.close
+      raise
+    end
+
+    def exchange(...) = @transport.exchange(...)
+    def exchange_async(...) = @transport.exchange_async(...)
+    def async_capable? = @transport.async_capable?
+
+    def register_notifications(protocol, classes)
+      @notifications.register(protocol, classes)
+    end
+
+    def add_memberships(group_ids)
+      group_ids.each { @socket.add_membership(it) }
+      nil
+    end
+
+    def drop_memberships(group_ids)
+      group_ids.each { @socket.drop_membership(it) }
+      nil
+    end
+
+    def receive_notification(protocol, timeout: nil)
+      @transport.receive_notification(protocol, timeout:)
+    end
+
+    def close
+      @transport.close
+      nil
+    ensure
+      @notifications.close
+    end
+  end
+end

data/lib/nl/core.rb

@@ -1,4 +1,4 @@
-# Data types and message handling
+# Netlink wire definitions
 
 require_relative 'endian'
 

data/lib/nl/datagram.rb

@@ -0,0 +1,24 @@
+# rbs_inline: enabled
+
+require_relative 'core'
+require_relative 'decoder'
+
+module Nl
+  # Splits Netlink datagrams into aligned header/payload frames.
+  module Datagram
+    # @rbs (IO::Buffer buffer) { (Core::NlMsgHdr, IO::Buffer) -> void } -> nil
+    #    | (IO::Buffer buffer) -> Enumerator[[Core::NlMsgHdr, IO::Buffer], nil]
+    def self.each_frame(buffer)
+      return enum_for(__method__, buffer) unless block_given?
+
+      decoder = Decoder.new(buffer)
+      while decoder.available?(Core::NLMSG_HDRLEN)
+        header = Core::NlMsgHdr.decode(decoder)
+        payload_size = header.len - Core::NLMSG_HDRLEN
+        payload = decoder.get_buffer(payload_size)
+        decoder.align_to(Core::NLMSG_ALIGNTO)
+        yield header, payload
+      end
+    end
+  end
+end

data/lib/nl/decoder.rb

@@ -38,12 +38,20 @@ module Nl
 
     def get_string(length = @limit - @position)
       nposition = @position + length
-      raise OutOfBounds if nposition > @limit
+      raise OutOfBounds if length.negative? || nposition > @limit
       value = @buffer.get_string(@position, length)
       @position = nposition
       value
     end
 
+    def get_buffer(length = @limit - @position)
+      nposition = @position + length
+      raise OutOfBounds if length.negative? || nposition > @limit
+      value = @buffer.slice(@position, length)
+      @position = nposition
+      value
+    end
+
     def get_zstring(unterminated_ok: false)
       nposition = @position
       nul_found = false

data/lib/nl/error.rb

@@ -0,0 +1,10 @@
+module Nl
+  class Error < StandardError; end
+  class ProtocolViolation < Error; end
+  class ExhaustedSequenceNumber < Error; end
+  class TimeoutError < Error; end
+  class ClosedError < Error; end
+  class NotificationLossError < Error; end
+  class UnknownMulticastGroupError < Error; end
+  class UnresolvedMulticastGroupError < Error; end
+end

data/lib/nl/exchange.rb

@@ -0,0 +1,102 @@
+# rbs_inline: enabled
+
+require_relative 'error'
+require_relative 'protocols/raw'
+
+module Nl
+  # State machine for one Netlink request/reply exchange.
+  class Exchange
+    Item = Data.define(:value)
+    Complete = Data.define
+    COMPLETE = Complete.new
+    Failure = Data.define(:exception)
+
+    attr_reader :kind
+
+    def initialize(kind:, expects_reply:)
+      @kind = kind
+      @expects_reply = expects_reply
+      @reply = nil
+      @state = kind == :dump ? :multi : :initial
+      @acked = false
+      @cancelled = false
+      @complete = false
+      @result = nil
+      @mutex = Mutex.new
+    end
+
+    def accept(frame)
+      @mutex.synchronize do
+        return if @complete
+
+        case frame
+        when Protocols::Raw::UnknownFrame
+          nil
+        when Protocols::Raw::ErrorFrame
+          @cancelled ? complete(nil) : fail_with(SystemCallError.new(frame.errno))
+        when Protocols::Raw::DoneFrame
+          if frame.errno && !@cancelled
+            fail_with(SystemCallError.new(frame.errno))
+          else
+            complete(@reply)
+          end
+        when Protocols::Raw::AckFrame
+          accept_ack
+        when Protocols::Raw::DataFrame
+          accept_reply(frame)
+        else
+          raise ArgumentError, "unexpected exchange input: #{frame.inspect}"
+        end
+      end
+    end
+
+    def cancel
+      @mutex.synchronize { @cancelled = true unless @complete }
+      nil
+    end
+
+    def cancelled? = @mutex.synchronize { @cancelled }
+    def complete? = @mutex.synchronize { @complete }
+    def result = @mutex.synchronize { @result }
+    def expects_reply? = @expects_reply
+
+    private def accept_ack
+      @acked = true
+      if @cancelled || !@expects_reply || @state == :single
+        complete(@reply)
+      end
+    end
+
+    private def accept_reply(frame)
+      return if @cancelled
+
+      multipart = (frame.header.flags.to_i & Core::NLM_F_MULTI) != 0
+      case @state
+      when :initial
+        @state = multipart ? :multi : :single
+      when :single
+        return fail_with(ProtocolViolation.new('more than one data message in a non-multipart Netlink response'))
+      when :multi
+        unless multipart
+          return fail_with(ProtocolViolation.new('multipart Netlink response contains data without NLM_F_MULTI'))
+        end
+      end
+
+      return Item.new(frame.message) if @kind == :dump
+
+      @reply ||= frame.message
+      complete(frame.message) if @acked && @state == :single
+    end
+
+    private def complete(value)
+      @complete = true
+      @result = value
+      COMPLETE
+    end
+
+    private def fail_with(exception)
+      @complete = true
+      Failure.new(exception)
+    end
+  end
+end

data/lib/nl/family.rb

@@ -1,37 +1,154 @@
 #--
 # rbs_inline: enabled
-require_relative 'socket'
+require_relative 'connection'
+require_relative 'notification'
 
 module Nl
+  # @rbs!
+  #   type executor = :thread | :fiber
+  #
+  #   interface _Connection
+  #     def exchange: (
+  #       Protocols::Raw protocol,
+  #       Symbol kind,
+  #       Class request_class,
+  #       Class reply_class,
+  #       Hash[Symbol, untyped] args
+  #     ) ?{ (untyped) -> void } -> untyped
+  #     def exchange_async: (
+  #       Protocols::Raw protocol,
+  #       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: (Protocols::Raw, 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 close: () -> nil
+  #   end
+
   class Family
+    DEFAULT_NOTIFICATION_CAPACITY = Connection::DEFAULT_NOTIFICATION_CAPACITY
+
+    module Session
+      def close #: nil
+        @connection.close
+      end
+    end
+
     #--
-    # @rbs socket: Socket
+    # @rbs connection: _Connection
     # @rbs protocol: Protocol
     # @rbs return: instance
-    def initialize(socket, protocol: self.class::PROTOCOL)
-      @socket = socket
+    def initialize(connection, protocol: self.class::PROTOCOL)
       @protocol = protocol
+      @connection = connection
+      @connection.register_notifications(@protocol, notification_classes)
+      @notification_stream = NotificationStream.new do |timeout|
+        @connection.receive_notification(@protocol, timeout:)
+      end
     end
 
     #--
-    # @rbs () -> instance
-    #  | [R] () { (instance) -> R } -> R
-    def self.open
+    # @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
-        socket = Socket.new(self::PROTOCOL.protonum)
-        socket.bind(Socket.sockaddr_nl(0, 0))
-        if block_given?
-          yield new(socket)
-        else
-          return new(socket)
-        end
+        yield session
       ensure
-        socket&.close if block_given?
+        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
+      end
+    end
+
+    private def exchange_message(kind, request_class, reply_class, args, &block)
+      @connection.exchange(@protocol, 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 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(@protocol, kind, request_class, reply_class, args, stream_capacity:)
+    end
+
+    private def notification_classes
+      self.class.const_get(:NOTIFICATIONS, false)
+    rescue NameError
+      {}
     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 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 #{@protocol.name}"
+        end
+        @protocol.multicast_group_id(group.name, group.id)
+      end
     end
   end
 end

data/lib/nl/genl/connection.rb

@@ -0,0 +1,89 @@
+# Generic Netlink connection handling
+#--
+# rbs_inline: enabled
+
+require_relative '../connection'
+require_relative '../core'
+require_relative '../protocols/genl'
+
+module Nl
+  module Genl
+    FamilyInfo = Data.define(:id, :multicast_groups) do
+      def self.from_reply(reply)
+        groups = (reply.mcast_groups || []).to_h do |attributes|
+          [attributes[:name].value.to_sym, attributes[:id].value]
+        end
+        new(id: reply.family_id, multicast_groups: groups.freeze)
+      end
+    end
+
+    class Connection
+      #--
+      # @rbs (resolver: ^(instance, ::String) -> (Integer | FamilyInfo | untyped), ?executor: executor?, ?notification_capacity: Integer?) -> instance
+      #  | [R] (resolver: ^(instance, ::String) -> (Integer | FamilyInfo | untyped), ?executor: executor?, ?notification_capacity: Integer?) { (instance) -> R } -> R
+      def self.open(resolver:, executor: nil, notification_capacity: Nl::Connection::DEFAULT_NOTIFICATION_CAPACITY)
+        conn = new(resolver:, executor:, notification_capacity:)
+        if block_given?
+          begin
+            yield conn
+          ensure
+            conn.close
+          end
+        else
+          conn
+        end
+      end
+
+      #--
+      # @rbs resolver: ^(instance, ::String) -> (Integer | FamilyInfo | untyped)
+      # @rbs executor: executor?
+      # @rbs return: instance
+      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: Protocols::Genl,
+          executor:,
+          notification_capacity:,
+        )
+      end
+
+      def family(family_class)
+        proto = family_class::PROTOCOL
+        info = family_info(proto)
+        family_class.new(
+          @connection,
+          protocol: Protocols::Genl.new(
+            proto.name,
+            family_id: info.id,
+            multicast_groups: info.multicast_groups,
+          ),
+        )
+      end
+
+      def close
+        @connection.close
+      end
+
+      private def family_info(protocol)
+        id = protocol.family_id
+        FamilyInfo.new(id:, multicast_groups: {}.freeze)
+      rescue NotImplementedError
+        cached_info = @family_cache_mutex.synchronize { @family_cache[protocol.name] }
+        return cached_info if cached_info
+
+        resolved = @resolver.call(self, protocol.name)
+        info = case resolved
+        when Integer
+          FamilyInfo.new(id: resolved, multicast_groups: {}.freeze)
+        when FamilyInfo
+          resolved
+        else
+          FamilyInfo.from_reply(resolved)
+        end
+        @family_cache_mutex.synchronize { @family_cache[protocol.name] ||= info }
+      end
+    end
+  end
+end

data/lib/nl/genl.rb

@@ -1,4 +1,6 @@
-# General Netlink message handling
+# Generic Netlink wire definitions
+#--
+# rbs_inline: enabled
 
 require_relative 'core'
 require_relative 'endian'
@@ -48,40 +50,25 @@ module Nl
     end
     include Constants
 
-    class Connection
-      def self.open(resolver:)
-        conn = new(resolver:)
-        if block_given?
-          begin
-            yield conn
-          ensure
-            conn.close
-          end
-        else
-          conn
-        end
-      end
-
-      def initialize(resolver:)
-        @socket = Socket.new(Core::NETLINK_GENERIC)
-        @socket.bind(Socket.sockaddr_nl(0, 0))
-        @resolver = resolver
-        @id_cache = {}
-      end
+    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 open(family_class)
-        proto = family_class::PROTOCOL
-        id = @id_cache[proto.name] ||= begin
-          proto.family_id
-        rescue NotImplementedError
-          @resolver.call(@socket, proto.name)
-        end
-        family_class.new(@socket, protocol: Protocols::Genl.new(proto.name, family_id: id))
+      def self.decode(decoder)
+        new(*decoder.get_values(FORMAT))
       end
 
-      def close
-        @socket.close
+      def encode(encoder)
+        encoder.put_values(FORMAT, to_a)
       end
     end
   end
 end
+
+require_relative 'genl/connection'