nl 0.2.4 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 125daafb96b4c4e1147421c6482219e9158ad31d0827859a61c86d97f506c62a
-  data.tar.gz: ed544d00ae8fa14525e75e913bf3e6e36931c520d9dbdc86d79a10dcbf859310
+  metadata.gz: 8fbd6064a908ddacbadbb65eaa2f7c7ab862baf91478804f1915ba988271b759
+  data.tar.gz: f49043a50d47c82da9f1f818f02948a12f386df091b7041e4ae1b7d755780b23
 SHA512:
-  metadata.gz: d9af220cb3e60bb8a30124c50304a8916679ca5f2b559ecc17828312a522ad73244e5ab9ff22b337641be93a9907f86790b0c6a9e2118533abd853e687d77349
-  data.tar.gz: d35efcdb26611ca0eba7d422280c96caafee84b39e988a453dd3c3ef23a05294a5d767e1b9f0cd515e0d3224ba04ff8a345b7edd759348dbd095d20d47cc2506
+  metadata.gz: 0f162b7c19214639fdd277bea5fdedb1ef4661a8747de0458b08dd85fefa94ec36dfbbd71b039ef5143069ca903e54d133029528dd4a75cee865d6b409db7251
+  data.tar.gz: c538d2a693926047576fc49bd82fd0bf435cbe19e3c61c21536826a0d873f260b87f2b6544dec4dac73e5385c11baa1da741c901bd81f2711eadb827cf34f356

data/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## Unreleased
 
+## v0.4.1 (2026-09-08)
+
+## v0.4.0 (2026-09-08)
+
+- Represent `bitfield32` values with mutable `Bitfield32` objects.
+- Support fixed-length binary values and structured binary values.
+- Encode Generic Netlink requests with the protocol version.
+- Support building and reading attributes declared as repeatable.
+- Add `Raw::Client` for using raw families with the same protocol number over one connection.
+- Rename `Genl::Connection` to `Genl::Client`.
+- Remove `UnknownNotification`; unsolicited messages without a registered decoder are now ignored.
+- Add context-aware encoding and decoding support for polymorphic sub-messages.
+
+## v0.3.0 (2026-09-01)
+
+- Fix encoding of nested attributes and mark them with `NLA_F_NESTED`.
+- Support encoding and decoding of nested type-value attributes.
+- Support multiplexing requests via `Family.async`
+- Support receiving notifications (unsolicited messages).
+- Rename `Genl::Connection#open` to `Genl::Connection#family`.
+
 ## v0.2.4 (2026-08-22)
 
 ## v0.2.3 (2026-03-24)

data/Rakefile

@@ -2,4 +2,11 @@ require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
+desc 'Generate RBS signatures from inline annotations'
+task :rbs do
+  sh '../bin/rbs-inline', '--output=sig/generated', '--opt-out', 'lib'
+end
+
+task :build => :rbs
+
 task default: :spec

data/lib/nl/async/dispatcher.rb

@@ -0,0 +1,199 @@
+require_relative '../datagram'
+require_relative '../error'
+require_relative '../exchange'
+require_relative '../notification_router'
+require_relative '../sequence_allocator'
+
+module Nl
+  module Async
+    # Owns the single receive loop for a socket and routes replies by sequence.
+    class Dispatcher
+      Pending = Data.define(:exchange, :endpoint, :reply_class, :sink)
+      private_constant :Pending
+
+      def initialize(socket, protocol:, executor: :thread, notifications:)
+        @socket = socket
+        @protocol = protocol
+        @sequences = SequenceAllocator.new
+        @notifications = notifications
+        @driver = executor.respond_to?(:start) ? executor : Async.driver(executor)
+        @mutex = Mutex.new
+        @send_mutex = Mutex.new
+        @pending = {}
+        @closed = false
+        @task = @driver.start { receive_loop }
+      end
+
+      def exchange(endpoint, kind, request_class, reply_class, args, &block)
+        operation = exchange_async(endpoint, kind, request_class, reply_class, args)
+        if kind == :dump
+          if block
+            operation.each(&block)
+            nil
+          else
+            operation.to_a
+          end
+        else
+          operation.await
+        end
+      end
+
+      def exchange_async(endpoint, kind, request_class, reply_class, args, stream_capacity: nil)
+        request = @protocol.build_request(endpoint, kind, request_class, args)
+
+        key = nil
+        seq = pid = nil
+        operation = sink = nil
+        @send_mutex.synchronize do
+          @mutex.synchronize do
+            raise ClosedError, 'dispatcher is closed' if @closed
+
+            pid = @socket.local_port_id
+            seq = @sequences.next { @pending.key?([it, pid]) }
+            key = [seq, pid]
+            mailbox = Mailbox.new(capacity: stream_capacity)
+            operation, sink = if kind == :dump
+              Stream.build(mailbox:, on_close: -> { discard(key) })
+            else
+              Future.build(mailbox:, on_close: -> { discard(key) })
+            end
+            mode = kind == :dump ? :dump : (reply_class ? :reply : :no_reply)
+            exchange = Exchange.new(mode:)
+            @pending[key] = Pending.new(exchange:, endpoint:, reply_class:, sink:)
+          end
+
+          begin
+            @protocol.send_message(@socket, endpoint, request, seq:, pid:)
+          rescue Exception => error
+            fail_pending(key, error)
+            raise
+          end
+        end
+        operation
+      end
+
+      def async_capable? #: true
+        true
+      end
+
+      def receive_notification(endpoint, timeout: nil)
+        @notifications.channel(endpoint).pop(timeout:)
+      end
+
+      def close
+        task = @mutex.synchronize do
+          next if @closed
+
+          @closed = true
+          @socket.close unless @socket.closed?
+          @task
+        end
+        fail_all(ClosedError.new('dispatcher is closed'))
+        @driver.stop(task) if task && !task.equal?(::Thread.current)
+        nil
+      end
+
+      private def receive_loop
+        loop do
+          break if @mutex.synchronize { @closed }
+
+          @socket.wait_readable
+          data = @socket.recvmsg_nonblock(exception: false)
+          next if data == :wait_readable
+
+          dispatch_datagram(IO::Buffer.for(data.first))
+        rescue Errno::ENOBUFS => e
+          @notifications.lose_all(NotificationLossError.new('kernel receive buffer overflowed'))
+          fail_all(e)
+        end
+      rescue Exception => e
+        fail_receive_loop(e)
+      end
+
+      private def fail_receive_loop(error)
+        failed = @mutex.synchronize do
+          next false if @closed
+
+          @closed = true
+          @socket.close unless @socket.closed?
+          true
+        end
+        return unless failed
+
+        fail_all(error)
+        @notifications.close
+      end
+
+      private def dispatch_datagram(buffer)
+        Datagram.each_frame(buffer) do |header, payload|
+          key = [header.seq, header.pid]
+          pending = @mutex.synchronize { @pending[key] }
+          unless pending
+            @notifications.route(header, payload) if header.seq.zero?
+            next
+          end
+
+          begin
+            message = @protocol.decode_frame(pending.endpoint, header, payload, pending.reply_class)
+            dispatch_outcome(key, pending, pending.exchange.accept(message))
+          rescue Exception => error
+            fail_pending(key, error) if pending
+          end
+        end
+      end
+
+      private def dispatch_outcome(key, pending, outcome)
+        return unless outcome
+
+        case outcome
+        when Exchange::Item
+          begin
+            pending.sink.push(outcome.value)
+          rescue Mailbox::FullError
+            fail_pending(key, StreamOverflowError.new("reply buffer exceeded for sequence #{key.first}"))
+          end
+        when Exchange::Complete
+          complete_pending(key, pending, pending.exchange.result)
+        when Exchange::Failure
+          fail_pending(key, outcome.exception)
+        end
+      end
+
+      private def complete_pending(key, pending, value)
+        removed = @mutex.synchronize { @pending.delete(key) }
+        return unless removed
+        return if pending.exchange.cancelled?
+
+        if pending.exchange.mode == :dump
+          pending.sink.finish
+        elsif pending.exchange.mode == :reply
+          pending.sink.succeed(value)
+        else
+          pending.sink.finish
+        end
+      end
+
+      private def discard(key)
+        @mutex.synchronize do
+          if pending = @pending[key]
+            pending.exchange.cancel
+          end
+        end
+      end
+
+      private def fail_pending(key, error)
+        pending = @mutex.synchronize { @pending.delete(key) }
+        pending&.sink&.fail(error) unless pending&.exchange&.cancelled?
+      end
+
+      private def fail_all(error)
+        pending = @mutex.synchronize do
+          old = @pending.values
+          @pending.clear
+          old
+        end
+        pending.each { it.sink.fail(error) unless it.exchange.cancelled? }
+      end
+    end
+  end
+end

data/lib/nl/async/driver.rb

@@ -0,0 +1,37 @@
+module Nl
+  module Async
+    module Drivers
+      class Thread
+        def start(&block)
+          ::Thread.new(&block)
+        end
+
+        def stop(task)
+          task.join
+        end
+      end
+
+      class Fiber
+        def start(&block)
+          raise ArgumentError, 'Fiber.scheduler is not installed' unless ::Fiber.scheduler
+
+          ::Fiber.schedule(&block)
+        end
+
+        def stop(_task)
+          # Scheduled fibers have no general join operation. Closing the socket
+          # makes the receive loop terminate at its next scheduling point.
+        end
+      end
+    end
+
+    def self.driver(name)
+      case name
+      when :thread then Drivers::Thread.new
+      when :fiber then Drivers::Fiber.new
+      else
+        raise ArgumentError, "unknown async executor: #{name.inspect}"
+      end
+    end
+  end
+end

data/lib/nl/async/mailbox.rb

@@ -0,0 +1,81 @@
+require_relative '../error'
+
+module Nl
+  module Async
+    # A thread-safe, scheduler-aware, single-consumer mailbox.
+    class Mailbox
+      class FullError < StandardError; end
+
+      def initialize(capacity: nil)
+        raise ArgumentError, 'capacity must be positive' if capacity && capacity <= 0
+
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @queue = []
+        @closed = false
+        @capacity = capacity
+      end
+
+      # Adds a value without executing consumer code.
+      # @rbs (untyped) -> bool
+      def push(value)
+        push_value(value, enforce_capacity: true)
+      end
+
+      # Adds a completion/error event even when the value capacity is full.
+      def push_terminal(value)
+        push_value(value, enforce_capacity: false)
+      end
+
+      private def push_value(value, enforce_capacity:)
+        @mutex.synchronize do
+          return false if @closed
+          if enforce_capacity && @capacity && @queue.length >= @capacity
+            raise FullError, 'mailbox capacity exceeded'
+          end
+
+          wake = @queue.empty?
+          @queue << value
+          @condition.signal if wake
+        end
+        true
+      end
+
+      # Removes the next value, suspending through the current thread or Fiber scheduler if empty.
+      # @rbs (?timeout: Numeric?) -> untyped
+      def pop(timeout: nil)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout if timeout
+
+        @mutex.synchronize do
+          loop do
+            return @queue.shift unless @queue.empty?
+            raise ClosedError if @closed
+
+            remaining = deadline && deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            raise TimeoutError if remaining && remaining <= 0
+
+            @condition.wait(@mutex, remaining)
+          end
+        end
+      end
+
+      def close
+        @mutex.synchronize do
+          return nil if @closed
+
+          @closed = true
+          @condition.broadcast
+        end
+        nil
+      end
+
+      def closed?
+        @mutex.synchronize { @closed }
+      end
+
+      def empty?
+        @mutex.synchronize { @queue.empty? }
+      end
+    end
+  end
+end

data/lib/nl/async/operation.rb

@@ -0,0 +1,277 @@
+require_relative '../error'
+
+module Nl
+  module Async
+    module Events
+      Item = Data.define(:value)
+      Done = Data.define
+      Error = Data.define(:exception)
+    end
+    private_constant :Events
+
+    class ConcurrentConsumptionError < StandardError; end
+    class StreamOverflowError < StandardError; end
+
+    # Future for the result of an already-started, single-reply operation.
+    # @rbs generic out Result
+    class Future
+      def self.build(mailbox: Mailbox.new, on_close: nil)
+        operation = new(mailbox:, on_close:)
+        [operation, Sink.new(mailbox)]
+      end
+
+      def initialize(mailbox:, on_close:)
+        @mailbox = mailbox
+        @on_close = on_close
+        @mutex = Mutex.new
+        @state = :open
+        @value = nil
+        @error = nil
+      end
+
+      # @rbs (?timeout: Numeric?) -> Result
+      def await(timeout: nil)
+        return terminal_result unless @mutex.synchronize { @state == :open }
+
+        event = @mailbox.pop(timeout:)
+        case event
+        when Events::Item
+          settle_done(event.value)
+        when Events::Done
+          settle_done(nil)
+        when Events::Error
+          settle_failed(event.exception)
+        end
+        @mailbox.close
+        terminal_result
+      rescue ClosedError
+        terminal_result
+      end
+      alias value await
+
+      def ready? #: bool
+        @mutex.synchronize { @state != :open } || !@mailbox.empty?
+      end
+
+      # Stops local delivery. The dispatcher still drains the Netlink exchange.
+      def close #: nil
+        closed, callback = @mutex.synchronize do
+          next [false, nil] if @state != :open
+
+          @state = :closed
+          [true, @on_close]
+        end
+        if closed
+          callback&.call
+          @mailbox.close
+        end
+        nil
+      end
+
+      private def settle_done(value)
+        @mutex.synchronize do
+          if @state == :open
+            @state = :done
+            @value = value
+          end
+        end
+      end
+
+      private def settle_failed(error)
+        @mutex.synchronize do
+          if @state == :open
+            @state = :failed
+            @error = error
+          end
+        end
+      end
+
+      private def terminal_result
+        state, value, error = @mutex.synchronize { [@state, @value, @error] }
+        case state
+        when :done then value
+        when :failed then raise error
+        else raise ClosedError, 'future is closed'
+        end
+      end
+
+      class Sink
+        def initialize(mailbox)
+          @mailbox = mailbox
+        end
+
+        def succeed(value) = @mailbox.push(Events::Item.new(value))
+        def finish = @mailbox.push_terminal(Events::Done.new)
+        def fail(exception) = @mailbox.push_terminal(Events::Error.new(exception))
+      end
+    end
+
+    # Single-pass consumer handle for a multipart Netlink operation.
+    # @rbs generic out Item
+    class Stream
+      include Enumerable #[Item]
+
+      def self.build(mailbox: Mailbox.new, on_close: nil)
+        operation = new(mailbox:, on_close:)
+        [operation, Sink.new(mailbox)]
+      end
+
+      def initialize(mailbox:, on_close:)
+        @mailbox = mailbox
+        @on_close = on_close
+        @mutex = Mutex.new
+        @owner = nil
+        @state = :open
+        @error = nil
+      end
+
+      # @rbs () { (Item) -> void } -> self
+      #    | () -> Enumerator[Item, self]
+      def each
+        return enum_for(__method__) unless block_given?
+
+        state, error = current_state
+        case state
+        when :completed then return self
+        when :closed then raise ClosedError, 'stream is closed'
+        when :failed then raise error
+        end
+
+        claim_consumer!
+        begin
+          loop do
+            case event = @mailbox.pop
+            when Events::Item
+              yield event.value
+            when Events::Done
+              completed = mark_completed
+              @mailbox.close
+              terminal_result unless completed
+              break
+            when Events::Error
+              failed = mark_failed(event.exception)
+              @mailbox.close
+              raise event.exception if failed
+
+              terminal_result
+            end
+          end
+          self
+        rescue ClosedError
+          terminal_result
+        ensure
+          close if open?
+        end
+      end
+
+      # @rbs (?timeout: Numeric?) -> Item
+      def next(timeout: nil)
+        state, error = current_state
+        case state
+        when :completed then raise StopIteration
+        when :closed then raise ClosedError, 'stream is closed'
+        when :failed then raise error
+        end
+
+        claim_consumer!
+        case event = @mailbox.pop(timeout:)
+        when Events::Item
+          event.value
+        when Events::Done
+          completed = mark_completed
+          @mailbox.close
+          raise StopIteration if completed
+
+          terminal_result(next_item: true)
+        when Events::Error
+          failed = mark_failed(event.exception)
+          @mailbox.close
+          raise event.exception if failed
+
+          terminal_result(next_item: true)
+        end
+      rescue ClosedError
+        terminal_result(next_item: true)
+      end
+
+      # Stops local delivery. The dispatcher still drains the Netlink exchange.
+      def close #: nil
+        closed, callback = @mutex.synchronize do
+          next [false, nil] if @state != :open
+
+          @state = :closed
+          [true, @on_close]
+        end
+        if closed
+          callback&.call
+          @mailbox.close
+        end
+        nil
+      end
+
+      def closed? #: bool
+        @mutex.synchronize { @state != :open }
+      end
+
+      private def current_state
+        @mutex.synchronize { [@state, @error] }
+      end
+
+      private def open?
+        @mutex.synchronize { @state == :open }
+      end
+
+      private def claim_consumer!
+        owner = Fiber.current
+        @mutex.synchronize do
+          @owner ||= owner
+          unless @owner.equal?(owner)
+            raise ConcurrentConsumptionError, 'a stream can only be consumed by one fiber'
+          end
+        end
+      end
+
+      private def mark_completed
+        @mutex.synchronize do
+          next false unless @state == :open
+
+          @state = :completed
+          true
+        end
+      end
+
+      private def mark_failed(error)
+        @mutex.synchronize do
+          next false unless @state == :open
+
+          @state = :failed
+          @error = error
+          true
+        end
+      end
+
+      private def terminal_result(next_item: false)
+        state, error = current_state
+        case state
+        when :completed
+          raise StopIteration if next_item
+          self
+        when :failed
+          raise error
+        else
+          raise ClosedError, 'stream is closed'
+        end
+      end
+
+      class Sink
+        def initialize(mailbox)
+          @mailbox = mailbox
+        end
+
+        def push(value) = @mailbox.push(Events::Item.new(value))
+        def finish = @mailbox.push_terminal(Events::Done.new)
+        def fail(exception) = @mailbox.push_terminal(Events::Error.new(exception))
+      end
+    end
+  end
+end

data/lib/nl/async.rb

@@ -0,0 +1,13 @@
+require_relative 'error'
+
+module Nl
+  # Asynchronous request handling support.
+  module Async
+    class UnavailableError < StandardError; end
+  end
+end
+
+require_relative 'async/mailbox'
+require_relative 'async/operation'
+require_relative 'async/driver'
+require_relative 'async/dispatcher'