tracepath 0.1.0

data/lib/tracepath/transport.rb

@@ -0,0 +1,705 @@
+# frozen_string_literal: true
+
+require "socket"
+require "ipaddr"
+require "securerandom"
+require_relative "pcap"
+
+module Tracepath
+  # Socket policy and operating-system differences live here, outside the
+  # scheduler and packet codecs. This object belongs to one trace.
+  class Transport
+    MAX_PACKETS = 64
+    LINUX_IP_RECVERR = 11
+    LINUX_IPV6_RECVERR = 25
+    LINUX_MSG_ERRQUEUE = 0x2000
+    LINUX_SOL_PACKET = 263
+    LINUX_PACKET_AUXDATA = 8
+    LINUX_CSUM_NOT_READY = 1 << 3
+    LINUX_CSUM_VALID = 1 << 7
+    IDENTIFIER_MUTEX = Mutex.new
+    IDENTIFIERS = {}
+
+    def self.allocate_identifier
+      IDENTIFIER_MUTEX.synchronize do
+        start = SecureRandom.random_number(1..65_535)
+        65_535.times do |offset|
+          identifier = ((start + offset - 1) % 65_535) + 1
+          next if IDENTIFIERS.key?(identifier)
+
+          IDENTIFIERS[identifier] = true
+          return identifier
+        end
+      end
+      raise NetworkError.new(:resource_exhausted, "All ICMP identifiers are in use")
+    end
+
+    def self.release_identifier(identifier)
+      IDENTIFIER_MUTEX.synchronize { IDENTIFIERS.delete(identifier) }
+    end
+
+    attr_reader :source_address, :source_port, :identifier, :payload_size
+
+    def self.open(target:, options:)
+      new(target: target, options: options)
+    end
+
+    def initialize(target:, options:)
+      @target = target
+      @options = options
+      @family = target.family
+      @socket_family = @family == :ipv4 ? Socket::AF_INET : Socket::AF_INET6
+      @platform = RUBY_PLATFORM.include?("linux") ? :linux : (RUBY_PLATFORM.include?("darwin") ? :darwin : nil)
+      @resources = []
+      @readers = {}
+      @udp_probes = {}
+      @pending_replies = []
+      @reader_cursor = 0
+      @closed = false
+      opened = false
+      begin
+        unless @platform
+          raise NetworkError.new(:unsupported_feature, "Native tracing supports Linux and macOS")
+        end
+        @interfaces = Socket.getifaddrs
+        validate_interface!
+        choose_source!
+        @payload_size = payload_length
+        @payload = "\0".b * @payload_size
+        open_sender
+        open_receivers
+        opened = true
+      rescue SystemCallError, SocketError => error
+        raise network_error(error)
+      ensure
+        unless opened
+          primary_error = $!
+          begin
+            close
+          rescue NetworkError
+            raise unless primary_error
+          end
+        end
+      end
+    end
+
+    def send_probe(probe)
+      raise NetworkError.new(:closed, "Transport is closed") if @closed
+
+      level, option = @family == :ipv4 ? [Socket::IPPROTO_IP, Socket::IP_TTL] : [Socket::IPPROTO_IPV6, Socket::IPV6_UNICAST_HOPS]
+      @sender.setsockopt(level, option, probe.ttl)
+      data = case @options.protocol
+             when :udp
+               @payload
+             when :icmp
+               Packet.icmp_echo(family: @family, identifier: probe.identifier, sequence: probe.sequence, payload: @payload)
+             when :tcp
+               Packet.tcp_syn(family: @family, source: @source_address, destination: @target.address,
+                              source_port: probe.source_port, destination_port: probe.destination_port,
+                              sequence: probe.tcp_sequence, payload: @payload)
+             end
+      destination_port = @options.protocol == :udp ? probe.destination_port : 0
+      read_error_queue(@sender, @pending_replies, MAX_PACKETS) if @error_queue
+      destination = sockaddr(@target.address, destination_port, @target.scope_id || @scope_id)
+      attempts = 0
+      begin
+        attempts += 1
+        sent = @sender.sendmsg_nonblock(data, 0, destination, exception: false)
+      rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::EACCES, Errno::EMSGSIZE
+        # An asynchronous UDP error can arrive between draining the error
+        # queue and sending. Preserve its reply, then retry this unsent probe
+        # once. Local errors in the queue still raise normally.
+        raise unless @error_queue && attempts == 1 && read_error_queue(@sender, @pending_replies, MAX_PACKETS).positive?
+
+        retry
+      end
+      unless sent == data.bytesize
+        raise NetworkError.new(:send_error, "Probe could not be sent without blocking")
+      end
+      @udp_probes[probe.destination_port] = probe if @error_queue
+      nil
+    rescue NetworkError, SystemCallError, SocketError => error
+      raise network_error(error, replies: @pending_replies.shift(@pending_replies.length))
+    end
+
+    def receive(timeout)
+      return [] if @closed
+      # The I/O budget limits new reads, not delivery of records already read.
+      # Leaving these behind would lose them if the next loop is cancelled.
+      return @pending_replies.shift(@pending_replies.length) unless @pending_replies.empty?
+
+      deadline = Clock.now + [Float(timeout), 0.0].max
+      buffered = @pcap&.buffered?
+      wait = buffered ? 0.0 : [deadline - Clock.now, 0.0].max
+      readable = IO.select(@readers.keys, nil, nil, wait)
+      ready = readable ? readable.first : []
+      ready |= [@pcap.io] if buffered
+      return [] if ready.empty?
+
+      replies = []
+      remaining = MAX_PACKETS
+      # Rotate ready descriptors so continuous ICMP traffic cannot starve a
+      # TCP terminal response waiting on another descriptor.
+      ready = ready.rotate(@reader_cursor % ready.length)
+      @reader_cursor += 1
+      ready.each do |io|
+        break if remaining.zero?
+
+        type = @readers.fetch(io)
+        if type == :pcap
+          @pcap.read(limit: remaining) do |packet|
+            remaining -= 1
+            reply = Packet.decode_link(packet.fetch(:data), datalink: packet.fetch(:datalink),
+                                       local_capture: !!@local_capture)
+            if reply
+              reply = with_interface_context(reply, interface_index: @capture_interface_index)
+              replies << reply.merge(received_at: packet.fetch(:received_at))
+            end
+          end
+        elsif type == :error_queue
+          read_error_queue(io, replies, remaining).then { |count| remaining -= count }
+        elsif type == :packet
+          read_packet_socket(io, replies, remaining).then { |count| remaining -= count }
+        else
+          read_socket(io, type, replies, remaining).then { |count| remaining -= count }
+        end
+      end
+      replies
+    rescue Errno::EINTR
+      replies || []
+    rescue NetworkError, SystemCallError, SocketError => error
+      raise network_error(error, replies: replies || [])
+    end
+
+    def close
+      return if @closed
+
+      @closed = true
+      begin
+        error = close_resources([@pcap, *@resources.reverse].compact)
+      ensure
+        self.class.release_identifier(@identifier) if @identifier
+        @resources.clear
+        @readers.clear
+        @udp_probes.clear
+        @pending_replies.clear
+      end
+      raise error if error
+
+      nil
+    end
+
+    private
+
+    # Recursion is bounded by the handful of descriptors owned by one trace.
+    # ensure also closes later resources when an unexpected programming error
+    # escapes, while expected close errors are reported after cleanup finishes.
+    def close_resources(resources)
+      resource, *remaining = resources
+      return unless resource
+
+      error = nil
+      begin
+        resource.close unless resource.respond_to?(:closed?) && resource.closed?
+      rescue NetworkError => failure
+        error = failure
+      rescue SystemCallError, IOError => failure
+        error = network_error(failure)
+      ensure
+        later_error = close_resources(remaining)
+      end
+      error || later_error
+    end
+
+    def validate_interface!
+      @interface = @options.interface
+      @interface_index = interface_index(@interface) if @interface
+      if @interface && !@interface_index
+        raise NetworkError.new(:invalid_interface, "Unknown interface #{@interface}")
+      end
+      if @target.scope_id && @interface_index && @target.scope_id != @interface_index
+        raise NetworkError.new(:invalid_interface, "Destination scope and interface disagree")
+      end
+      if @target.scope_id && !@interfaces.any? { |entry| entry.ifindex == @target.scope_id }
+        raise NetworkError.new(:invalid_interface, "Unknown destination scope #{@target.scope_id}")
+      end
+    end
+
+    def interface_index(name)
+      @interfaces.find { |entry| entry.name == name }&.ifindex
+    end
+
+    def local_addresses
+      @interfaces.select { |entry| entry.addr&.ip? && entry.addr.afamily == @socket_family }
+    end
+
+    def choose_source!
+      source, zone = @options.source&.split("%", 2)
+      source_scope = if zone
+                       zone.match?(/\A\d+\z/) ? zone.to_i : interface_index(zone)
+                     end
+      if zone && (!source_scope || !@interfaces.any? { |entry| entry.ifindex == source_scope })
+        raise NetworkError.new(:invalid_source, "Unknown source scope #{zone}")
+      end
+      if source_scope && @interface_index && source_scope != @interface_index
+        raise NetworkError.new(:invalid_source, "Source scope and interface disagree")
+      end
+      if source_scope && @target.scope_id && source_scope != @target.scope_id
+        raise NetworkError.new(:invalid_source, "Source and destination scopes disagree")
+      end
+      @scope_id = source_scope || @target.scope_id || @interface_index
+      if source
+        source = IPAddr.new(source).to_s
+        candidates = local_addresses.select do |entry|
+          IPAddr.new(entry.addr.ip_address.split("%", 2).first).to_s == source &&
+            (!@interface_index || entry.ifindex == @interface_index) &&
+            (!source_scope || entry.ifindex == source_scope)
+        end
+        if candidates.empty?
+          raise NetworkError.new(:invalid_source, "Source address is not assigned to the selected local interface")
+        end
+      end
+      route_socket = Socket.new(@socket_family, Socket::SOCK_DGRAM, Socket::IPPROTO_UDP)
+      begin
+        bind_interface(route_socket)
+        route_socket.bind(sockaddr(source, 0, @scope_id)) if source
+        route_socket.connect(sockaddr(@target.address, @options.port || 33_434, @target.scope_id || @scope_id))
+        @source_address = route_socket.local_address.ip_address.split("%", 2).first
+      ensure
+        route_socket.close
+      end
+      @source_interfaces = local_addresses.select do |entry|
+        IPAddr.new(entry.addr.ip_address.split("%", 2).first).to_s == @source_address &&
+          (!@interface_index || entry.ifindex == @interface_index) &&
+          (!@scope_id || !IPAddr.new(@source_address).link_local? || entry.ifindex == @scope_id)
+      end
+    end
+
+    def sockaddr(address, port, scope = nil)
+      scoped = address
+      if @family == :ipv6 && scope && !address.include?("%") && IPAddr.new(address).link_local?
+        scoped = "#{address}%#{scope}"
+      end
+      Socket.sockaddr_in(port, scoped)
+    end
+
+    def payload_length
+      return @options.protocol == :tcp ? 0 : 32 unless @options.packet_size
+
+      ip_length = @family == :ipv4 ? 20 : 40
+      protocol_length = @options.protocol == :tcp ? 20 : 8
+      length = @options.packet_size - ip_length - protocol_length
+      if length.negative?
+        raise NetworkError.new(:invalid_packet_size, "Packet size is smaller than its IP and protocol headers")
+      end
+      length
+    end
+
+    def socket(type, protocol)
+      resource = Socket.new(@socket_family, type, protocol)
+      @resources << resource
+      resource
+    end
+
+    def icmp_protocol
+      @family == :ipv4 ? Socket::IPPROTO_ICMP : Socket::IPPROTO_ICMPV6
+    end
+
+    def open_sender
+      case @options.protocol
+      when :udp
+        @sender = socket(Socket::SOCK_DGRAM, Socket::IPPROTO_UDP)
+      when :icmp
+        @sender = socket(Socket::SOCK_RAW, icmp_protocol)
+        @identifier = self.class.allocate_identifier
+      when :tcp
+        # Reserve the source port across concurrent traces without making a
+        # connection or allowing the kernel to retransmit our SYN probes.
+        reservation = socket(Socket::SOCK_STREAM, Socket::IPPROTO_TCP)
+        bind_interface(reservation)
+        reservation.bind(sockaddr(@source_address, 0, @scope_id))
+        @source_port = reservation.local_address.ip_port
+        @sender = socket(Socket::SOCK_RAW, Socket::IPPROTO_TCP)
+      end
+      bind_interface(@sender)
+      @sender.bind(sockaddr(@source_address, 0, @scope_id))
+      @source_port = @sender.local_address.ip_port if @options.protocol == :udp
+      configure_sender
+    end
+
+    def configure_sender
+      if @options.traffic_class
+        level, option = @family == :ipv4 ? [Socket::IPPROTO_IP, Socket::IP_TOS] : [Socket::IPPROTO_IPV6, Socket::IPV6_TCLASS]
+        @sender.setsockopt(level, option, @options.traffic_class)
+      end
+      return unless @options.dont_fragment
+
+      if @family == :ipv6
+        @sender.setsockopt(Socket::IPPROTO_IPV6, Socket::IPV6_DONTFRAG, 1)
+      elsif @platform == :linux
+        # Linux IP_MTU_DISCOVER / IP_PMTUDISC_DO, not BSD IP_DONTFRAG.
+        @sender.setsockopt(Socket::IPPROTO_IP, 10, 2)
+      else
+        @sender.setsockopt(Socket::IPPROTO_IP, Socket::IP_DONTFRAG, 1)
+      end
+    end
+
+    def bind_interface(resource)
+      index = @interface_index || @scope_id
+      return unless index
+
+      if @platform == :linux
+        name = @interfaces.find { |entry| entry.ifindex == index }&.name
+        resource.setsockopt(Socket::SOL_SOCKET, Socket::SO_BINDTODEVICE, "#{name}\0")
+      else
+        level, option = @family == :ipv4 ? [Socket::IPPROTO_IP, 25] : [Socket::IPPROTO_IPV6, 125]
+        resource.setsockopt(level, option, index)
+      end
+    end
+
+    def open_receivers
+      if @platform == :linux && @options.protocol == :udp
+        @error_queue = true
+        level, option = @family == :ipv4 ? [Socket::IPPROTO_IP, LINUX_IP_RECVERR] : [Socket::IPPROTO_IPV6, LINUX_IPV6_RECVERR]
+        @sender.setsockopt(level, option, 1)
+        @readers[@sender] = :error_queue
+        return
+      end
+
+      receiver = socket(Socket::SOCK_RAW, icmp_protocol)
+      bind_interface(receiver)
+      receiver.bind(sockaddr(@source_address, 0, @scope_id))
+      receiver.setsockopt(Socket::IPPROTO_IPV6, Socket::IPV6_RECVPKTINFO, 1) if @family == :ipv6
+      @readers[receiver] = :icmp
+      return unless @options.protocol == :tcp
+
+      if @platform == :linux
+        open_linux_tcp_receiver
+      else
+        interfaces = @source_interfaces.map(&:name).uniq
+        # A route to an address assigned to this host is delivered through
+        # loopback, even when that address belongs to a physical interface.
+        local_target = local_addresses.any? do |entry|
+          IPAddr.new(entry.addr.ip_address.split("%", 2).first).to_s == @target.address
+        end
+        if local_target && !@interface
+          interfaces = @interfaces.select { |entry| (entry.flags & Socket::IFF_LOOPBACK) != 0 }.map(&:name).uniq
+        end
+        unless interfaces.length == 1
+          raise NetworkError.new(:invalid_interface, "TCP capture requires an unambiguous source interface",
+                                 details: { interfaces: interfaces })
+        end
+        loopback_capture = @interfaces.any? do |entry|
+          entry.name == interfaces.first && (entry.flags & Socket::IFF_LOOPBACK) != 0
+        end
+        @local_capture = loopback_capture && local_target && !@source_interfaces.empty?
+        @capture_interface_index = interface_index(interfaces.first)
+        @pcap = Pcap.new(interface: interfaces.first, source: @source_address, destination: @target.address)
+        @readers[@pcap.io] = :pcap
+      end
+    end
+
+    def open_linux_tcp_receiver
+      ether_type = @family == :ipv4 ? 0x0800 : 0x86dd
+      network_protocol = [ether_type].pack("n").unpack1("S")
+      receiver = Socket.new(Socket::AF_PACKET, Socket::SOCK_DGRAM, network_protocol)
+      @resources << receiver
+      receiver.setsockopt(LINUX_SOL_PACKET, LINUX_PACKET_AUXDATA, 1)
+      @capture_interface_index = @interface_index || @scope_id || 0
+      # sockaddr_ll has a native family/index and a network-order protocol.
+      address = [Socket::AF_PACKET, ether_type, @capture_interface_index, 0, 0, 0, "\0" * 8].pack("SniSCCa8")
+      receiver.bind(address)
+      @capture_source = IPAddr.new(@target.address).hton
+      @capture_destination = IPAddr.new(@source_address).hton
+      @packet_receiver = LinuxPacketReceiver.new
+      @readers[receiver] = :packet
+    end
+
+    def read_packet_socket(resource, replies, limit)
+      count = 0
+      limit.times do
+        message = @packet_receiver.read_nonblock(resource)
+        break if message == :wait_readable
+
+        received_at = Clock.now
+        count += 1
+        data, sender, flags, *controls = message
+        next if (flags & (Socket::MSG_TRUNC | Socket::MSG_CTRUNC)) != 0
+
+        link_address = sender.to_sockaddr
+        next unless link_address.bytesize >= 20 && link_address.getbyte(10).zero? # PACKET_HOST
+        incoming_interface = link_address.byteslice(4, 4).unpack1("i")
+        next if @capture_interface_index.positive? && incoming_interface != @capture_interface_index
+        next unless captured_endpoints_match?(data)
+
+        control = controls.find { |item| item.level == LINUX_SOL_PACKET && item.type == LINUX_PACKET_AUXDATA }
+        status = control && control.data.bytesize >= 20 ? control.data.unpack1("L") : 0
+        checksum_status = if (status & LINUX_CSUM_NOT_READY) != 0
+                            :kernel_offload
+                          elsif (status & LINUX_CSUM_VALID) != 0
+                            :kernel_verified
+                          end
+        reply = Packet.decode(data, family: @family, ip_header: true, protocol: :tcp,
+                              checksum_offloaded: !checksum_status.nil?)
+        next unless reply && reply[:kind] == :tcp_reply
+
+        reply = reply.merge(checksum_status: checksum_status) if checksum_status
+        reply = with_interface_context(reply, interface_index: incoming_interface)
+        replies << reply.merge(received_at: received_at)
+      end
+      count
+    end
+
+    def captured_endpoints_match?(data)
+      if @family == :ipv4
+        data.bytesize >= 20 && data.getbyte(0) >> 4 == 4 && data.getbyte(9) == 6 &&
+          data.byteslice(12, 4) == @capture_source && data.byteslice(16, 4) == @capture_destination
+      else
+        data.bytesize >= 40 && data.getbyte(0) >> 4 == 6 &&
+          data.byteslice(8, 16) == @capture_source && data.byteslice(24, 16) == @capture_destination
+      end
+    end
+
+    def read_socket(resource, protocol, replies, limit)
+      count = 0
+      limit.times do
+        message = resource.recvmsg_nonblock(65_535, 0, 4096, exception: false)
+        break if message == :wait_readable
+
+        count += 1
+        data, sender, flags, *controls = message
+        next if (flags & Socket::MSG_TRUNC) != 0
+
+        received_at = Clock.now
+        data = normalize_darwin_ipv4(data) if @platform == :darwin && @family == :ipv4
+        reply = Packet.decode(data, family: @family, source: sender.ip_address.split("%", 2).first,
+                              destination: @source_address, ip_header: @family == :ipv4, protocol: protocol)
+        if reply
+          packet_info = controls.find do |control|
+            control.level == Socket::IPPROTO_IPV6 && control.type == Socket::IPV6_PKTINFO && control.data.bytesize >= 20
+          end
+          incoming_interface = packet_info&.data&.byteslice(16, 4)&.unpack1("I")
+          reply = with_interface_context(reply, source: sender, interface_index: incoming_interface)
+          replies << reply.merge(received_at: received_at)
+        end
+      end
+      count
+    end
+
+    def read_error_queue(resource, replies, limit)
+      count = 0
+      limit.times do
+        message = resource.recvmsg_nonblock(65_535, LINUX_MSG_ERRQUEUE, 4096, exception: false)
+        break if message == :wait_readable
+
+        count += 1
+        data, destination, flags, *controls = message
+        next if (flags & (Socket::MSG_TRUNC | Socket::MSG_CTRUNC)) != 0
+
+        level, type = @family == :ipv4 ? [Socket::IPPROTO_IP, LINUX_IP_RECVERR] : [Socket::IPPROTO_IPV6, LINUX_IPV6_RECVERR]
+        control = controls.find { |item| item.level == level && item.type == type }
+        next unless control && control.data.bytesize >= 16
+
+        reply = decode_extended_error(control.data, destination, data)
+        replies << reply.merge(received_at: Clock.now) if reply
+      end
+      # Unexpected UDP application data must not leave select permanently
+      # readable. It does not prove receipt of any particular traceroute probe.
+      (limit - count).times do
+        begin
+          message = resource.recvmsg_nonblock(65_535, 0, 0, exception: false)
+        rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::EACCES, Errno::EMSGSIZE
+          # Read network failures through the extended queue. SO_ERROR may
+          # represent an error already decoded, or one arriving between the
+          # two reads; its queued record will be handled on the next poll.
+          break
+        end
+        break if message == :wait_readable
+
+        count += 1
+      end
+      count
+    end
+
+    def decode_extended_error(data, destination, _payload)
+      errno, origin, type, code, _padding, info, = data.unpack("LCCCCLL")
+      if origin == 1
+        name = errno == Errno::EMSGSIZE::Errno ? :packet_too_large : :network_error
+        raise NetworkError.new(name, "Local socket error #{errno}", details: { errno: errno, mtu: info.zero? ? nil : info })
+      end
+      expected_origin = @family == :ipv4 ? 2 : 3
+      return unless origin == expected_origin && destination.ip?
+
+      probe = @udp_probes[destination.ip_port]
+      return unless probe && destination.ip_address.split("%", 2).first == @target.address
+
+      address_length = @family == :ipv4 ? 16 : 28
+      return unless data.bytesize >= 16 + address_length
+
+      offender = Addrinfo.new(data.byteslice(16, address_length))
+      return unless offender.ip?
+
+      kind = if @family == :ipv4
+               { 3 => (code == 4 ? :packet_too_big : :unreachable), 11 => :time_exceeded, 12 => :parameter_problem }[type]
+             else
+               { 1 => :unreachable, 2 => :packet_too_big, 3 => :time_exceeded, 4 => :parameter_problem }[type]
+             end
+      return unless kind
+
+      reply = {
+        kind: kind, family: @family, source: offender.ip_address.split("%", 2).first, destination: @source_address,
+        icmp_type: type, icmp_code: code, mtu: kind == :packet_too_big && info.positive? ? info : nil,
+        quoted: { family: @family, source: @source_address, destination: @target.address, protocol: :udp,
+                  source_port: @source_port, destination_port: probe.destination_port }
+      }
+      with_interface_context(reply, source: offender, interface_index: @interface_index || @scope_id)
+    end
+
+    def with_interface_context(reply, source: nil, interface_index: nil)
+      context = {}
+      context[:interface_index] = interface_index if interface_index&.positive?
+      if @family == :ipv6 && reply[:source] && IPAddr.new(reply[:source]).link_local?
+        scope = source.to_sockaddr.byteslice(24, 4)&.unpack1("I") if source&.ipv6?
+        scope = interface_index || @scope_id if !scope || scope.zero?
+        context[:source_scope_id] = scope if scope&.positive?
+      end
+      reply.merge(context)
+    end
+
+    # BSD raw IPv4 reception exposes ip_len/ip_off in host byte order, and
+    # ip_len excludes the outer header. Packet codecs consume wire format.
+    def normalize_darwin_ipv4(data)
+      return data if data.bytesize < 20
+
+      length = (data.getbyte(0) & 0x0f) * 4
+      return data unless length >= 20 && length <= data.bytesize
+
+      normalized = data.dup
+      normalized[2, 2] = [data.bytesize].pack("n")
+      normalized[6, 2] = [data.byteslice(6, 2).unpack1("S")].pack("n")
+      restore_darwin_icmp_quote!(normalized, length)
+      normalized[10, 2] = "\0\0"
+      checksum = normalized.byteslice(0, length).unpack("n*").sum
+      checksum = (checksum & 0xffff) + (checksum >> 16) while checksum > 0xffff
+      normalized[10, 2] = [~checksum & 0xffff].pack("n")
+      normalized
+    end
+
+    def restore_darwin_icmp_quote!(packet, header_length)
+      return unless packet.getbyte(9) == Socket::IPPROTO_ICMP
+
+      type = packet.getbyte(header_length)
+      code = packet.getbyte(header_length + 1)
+      delivered = case type
+                  when 3 then code && (0..15).cover?(code)
+                  when 11, 12 then code && (0..1).cover?(code)
+                  else false
+                  end
+      return unless delivered
+
+      offset = header_length + 8
+      return if packet.bytesize < offset + 28 || packet.getbyte(offset) >> 4 != 4
+
+      quoted_header_length = (packet.getbyte(offset) & 0x0f) * 4
+      return if quoted_header_length < 20 || packet.bytesize < offset + quoted_header_length + 8
+
+      # XNU icmp_input's deliver path applies NTOHS to the quoted ip_len
+      # before rip_input. The quote's ip_off remains in network order. Restore
+      # only that length; retain the original ICMP/quoted-header checksums so
+      # Packet still rejects damaged replies instead of blessing their bytes.
+      packet[offset + 2, 2] = [packet.byteslice(offset + 2, 2).unpack1("S")].pack("n")
+    end
+
+    def network_error(error, replies: [])
+      if error.is_a?(NetworkError)
+        return error if replies.empty?
+
+        return NetworkError.new(error.code, error.message, details: error.details, replies: replies + error.replies)
+      end
+      code = case error
+             when Errno::EPERM, Errno::EACCES then :permission_denied
+             when Errno::EPROTONOSUPPORT, Errno::EAFNOSUPPORT, Errno::ENOPROTOOPT, Errno::EOPNOTSUPP then :unsupported_feature
+             when Errno::EMSGSIZE then :packet_too_large
+             when Errno::EADDRNOTAVAIL then :invalid_source
+             when Errno::ENETUNREACH, Errno::EHOSTUNREACH then :no_route
+             else :network_error
+             end
+      NetworkError.new(code, error.message,
+                       details: { operation: error.class.name, protocol: @options.protocol, family: @family }, replies: replies)
+    end
+
+    # Ruby's recvmsg adds MSG_CMSG_CLOEXEC unconditionally on Linux, while
+    # AF_PACKET rejects that flag with EINVAL. This small, nonblocking libc
+    # boundary preserves the kernel's PACKET_AUXDATA checksum evidence.
+    class LinuxPacketReceiver
+      DATA_SIZE = 65_575
+      CONTROL_SIZE = 4096
+      ADDRESS_SIZE = 128
+
+      def initialize
+        require "fiddle/import"
+        types = Module.new.extend(Fiddle::Importer)
+        iovec_type = types.struct(["void* iov_base", "size_t iov_len"])
+        message_type = types.struct([
+                                      "void* msg_name", "unsigned int msg_namelen", "void* msg_iov", "size_t msg_iovlen",
+                                      "void* msg_control", "size_t msg_controllen", "int msg_flags"
+                                    ])
+        @iovec = iovec_type.malloc(Fiddle::RUBY_FREE)
+        @message = message_type.malloc(Fiddle::RUBY_FREE)
+        @data = Fiddle::Pointer.malloc(DATA_SIZE, Fiddle::RUBY_FREE)
+        @address = Fiddle::Pointer.malloc(ADDRESS_SIZE, Fiddle::RUBY_FREE)
+        @control = Fiddle::Pointer.malloc(CONTROL_SIZE, Fiddle::RUBY_FREE)
+        @recvmsg = Fiddle::Function.new(Fiddle::Handle::DEFAULT["recvmsg"],
+                                        [Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT], Fiddle::TYPE_SSIZE_T)
+      rescue LoadError => error
+        raise NetworkError.new(:unsupported_feature, "Linux TCP capture requires the fiddle gem", details: { cause: error.message })
+      rescue Fiddle::DLError => error
+        raise NetworkError.new(:unsupported_feature, "Cannot load recvmsg", details: { cause: error.message })
+      end
+
+      def read_nonblock(socket)
+        @iovec.iov_base = @data
+        @iovec.iov_len = DATA_SIZE
+        @message.msg_name = @address
+        @message.msg_namelen = ADDRESS_SIZE
+        @message.msg_iov = @iovec.to_ptr
+        @message.msg_iovlen = 1
+        @message.msg_control = @control
+        @message.msg_controllen = CONTROL_SIZE
+        @message.msg_flags = 0
+        length = @recvmsg.call(socket.fileno, @message.to_ptr, Socket::MSG_DONTWAIT)
+        if length.negative?
+          errno = Fiddle.last_error
+          return :wait_readable if [Errno::EAGAIN::Errno, Errno::EWOULDBLOCK::Errno].include?(errno)
+
+          raise SystemCallError.new("recvmsg(2)", errno)
+        end
+        unless length <= DATA_SIZE && @message.msg_namelen <= ADDRESS_SIZE && @message.msg_controllen <= CONTROL_SIZE
+          raise NetworkError.new(:capture_error, "Packet socket returned an invalid buffer length")
+        end
+        sender = Addrinfo.new(@address[0, @message.msg_namelen])
+        controls = decode_controls(@control[0, @message.msg_controllen], sender.afamily)
+        [@data[0, length], sender, @message.msg_flags, *controls]
+      end
+
+      private
+
+      def decode_controls(data, family)
+        alignment = Fiddle::SIZEOF_SIZE_T
+        header_length = alignment + 8
+        offset = 0
+        controls = []
+        while offset + header_length <= data.bytesize
+          length = data.byteslice(offset, alignment).unpack1("J")
+          break if length < header_length || offset + length > data.bytesize
+
+          level, type = data.byteslice(offset + alignment, 8).unpack("ii")
+          payload = data.byteslice(offset + header_length, length - header_length)
+          controls << Socket::AncillaryData.new(family, level, type, payload)
+          offset += (length + alignment - 1) & ~(alignment - 1)
+        end
+        controls
+      end
+    end
+  end
+end