tracepath 0.1.0

data/lib/tracepath/pcap.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Tracepath
+  # A small libpcap boundary. It captures replies; it never sends packets.
+  class Pcap
+    MAX_PACKETS = 64
+    MAX_CAPTURE_LENGTH = 65_535 + 256
+    ERROR_BUFFER_SIZE = 256
+
+    attr_reader :io, :datalink
+
+    def initialize(interface:, source:, destination:, native: nil)
+      @native = native || Native.new
+      @closed = false
+      opened = false
+      begin
+        source_ip = IPAddr.new(source.split("%", 2).first)
+        destination_ip = IPAddr.new(destination.split("%", 2).first)
+        @handle = @native.create(interface)
+        @native.configure(@handle)
+        # An IPv6 extension header can precede TCP. A plain "tcp" BPF
+        # predicate would miss these packets, so decode the IP payload later.
+        protocol_filter = source_ip.ipv4? ? "ip and tcp" : "ip6"
+        filter = "#{protocol_filter} and src host #{destination_ip} and dst host #{source_ip}"
+        @native.filter(@handle, filter)
+        @datalink = @native.datalink(@handle)
+        unless [0, 1, 12, 101, 108, 228, 229].include?(@datalink)
+          raise NetworkError.new(:unsupported_feature, "Unsupported capture link type #{@datalink}",
+                                 details: { datalink: @datalink, interface: interface })
+        end
+        descriptor = @native.selectable_fd(@handle)
+        if descriptor.negative?
+          raise NetworkError.new(:unsupported_feature, "Capture does not expose a selectable descriptor",
+                                 details: { interface: interface })
+        end
+        # libpcap owns this descriptor. Ruby must not close it during GC.
+        @io = IO.for_fd(descriptor, autoclose: false)
+        opened = true
+      ensure
+        unless opened
+          primary_error = $!
+          begin
+            close
+          rescue NetworkError, SystemCallError, IOError
+            raise unless primary_error
+          end
+        end
+      end
+    end
+
+    # Never blocks: the handle is configured in nonblocking mode. The caller
+    # owns the select/deadline loop, including cancellation responsiveness.
+    def read(limit: MAX_PACKETS)
+      return [] if @closed
+
+      packets = []
+      maximum = [limit, MAX_PACKETS].min
+      maximum.times do
+        packet = @native.next_packet(@handle)
+        break unless packet
+
+        observation = { data: packet, datalink: @datalink, received_at: Clock.now }
+        packets << observation
+        # Deliver each copied frame before a later native read can fail.
+        yield observation if block_given?
+      end
+      # libpcap can retain unread packets after draining the underlying BPF
+      # descriptor. A full batch means select alone cannot decide readiness.
+      @buffered = maximum.positive? && packets.length == maximum
+      packets
+    end
+
+    def buffered? = !!@buffered
+
+    def close
+      return if @closed
+
+      @closed = true
+      @buffered = false
+      begin
+        @native.close(@handle) if @handle
+      ensure
+        @handle = nil
+        @io = nil
+      end
+      nil
+    end
+
+    # Load only when macOS TCP capture is requested. No C compiler or pcap gem
+    # is required, and no global Fiddle pointers escape this object.
+    class Native
+      SIGNATURES = {
+        "pcap_create" => [:pointer, [:pointer, :pointer]],
+        "pcap_set_snaplen" => [:int, [:pointer, :int]],
+        "pcap_set_promisc" => [:int, [:pointer, :int]],
+        "pcap_set_timeout" => [:int, [:pointer, :int]],
+        "pcap_set_immediate_mode" => [:int, [:pointer, :int]],
+        "pcap_activate" => [:int, [:pointer]],
+        "pcap_setnonblock" => [:int, [:pointer, :int, :pointer]],
+        "pcap_compile" => [:int, [:pointer, :pointer, :pointer, :int, :int]],
+        "pcap_setfilter" => [:int, [:pointer, :pointer]],
+        "pcap_freecode" => [:void, [:pointer]],
+        "pcap_datalink" => [:int, [:pointer]],
+        "pcap_get_selectable_fd" => [:int, [:pointer]],
+        "pcap_next_ex" => [:int, [:pointer, :pointer, :pointer]],
+        "pcap_geterr" => [:pointer, [:pointer]],
+        "pcap_close" => [:void, [:pointer]]
+      }.freeze
+
+      def initialize(library: "/usr/lib/libpcap.A.dylib")
+        require "fiddle"
+        @library = Fiddle.dlopen(library)
+        @functions = SIGNATURES.to_h do |name, (result, arguments)|
+          types = { pointer: Fiddle::TYPE_VOIDP, int: Fiddle::TYPE_INT, void: Fiddle::TYPE_VOID }
+          [name, Fiddle::Function.new(@library[name], arguments.map { |type| types.fetch(type) }, types.fetch(result))]
+        end
+        # pcap_pkthdr is two native longs (timeval), followed by two uint32s.
+        # bpf_program is uint32 length, padding, then a native pointer.
+        @header_size = (2 * Fiddle::SIZEOF_LONG) + 8
+        @bpf_size = ((4 + Fiddle::SIZEOF_VOIDP - 1) / Fiddle::SIZEOF_VOIDP + 1) * Fiddle::SIZEOF_VOIDP
+      rescue LoadError => error
+        raise NetworkError.new(:unsupported_feature, "TCP capture requires the fiddle gem", details: { cause: error.message })
+      rescue Fiddle::DLError => error
+        raise NetworkError.new(:unsupported_feature, "Cannot load the system libpcap", details: { cause: error.message })
+      end
+
+      def create(interface)
+        error_buffer = buffer(ERROR_BUFFER_SIZE)
+        handle = call("pcap_create", interface, error_buffer)
+        if handle.null?
+          raise NetworkError.new(:capture_error, "Cannot create capture: #{error_buffer.to_s}")
+        end
+        handle
+      end
+
+      def configure(handle)
+        {
+          "pcap_set_snaplen" => MAX_CAPTURE_LENGTH,
+          "pcap_set_promisc" => 0,
+          "pcap_set_timeout" => 1,
+          "pcap_set_immediate_mode" => 1
+        }.each { |name, value| check(call(name, handle, value), handle) }
+        check(call("pcap_activate", handle), handle)
+        error_buffer = buffer(ERROR_BUFFER_SIZE)
+        status = call("pcap_setnonblock", handle, 1, error_buffer)
+        if status.negative?
+          raise NetworkError.new(:capture_error, "Cannot make capture nonblocking: #{error_buffer.to_s}")
+        end
+      end
+
+      def filter(handle, expression)
+        program = buffer(@bpf_size)
+        compiled = false
+        begin
+          check(call("pcap_compile", handle, program, expression, 1, -1), handle)
+          compiled = true
+          check(call("pcap_setfilter", handle, program), handle)
+        ensure
+          call("pcap_freecode", program) if compiled
+        end
+      end
+
+      def datalink(handle)
+        call("pcap_datalink", handle)
+      end
+
+      def selectable_fd(handle)
+        call("pcap_get_selectable_fd", handle)
+      end
+
+      def next_packet(handle)
+        header_pointer = buffer(Fiddle::SIZEOF_VOIDP)
+        data_pointer = buffer(Fiddle::SIZEOF_VOIDP)
+        status = call("pcap_next_ex", handle, header_pointer, data_pointer)
+        return nil if status.zero? || status == -2
+
+        check(status, handle)
+        header_address = header_pointer[0, Fiddle::SIZEOF_VOIDP].unpack1("J")
+        data_address = data_pointer[0, Fiddle::SIZEOF_VOIDP].unpack1("J")
+        if header_address.zero? || data_address.zero?
+          raise NetworkError.new(:capture_error, "Capture returned an invalid packet pointer")
+        end
+        header = Fiddle::Pointer.new(header_address)[0, @header_size]
+        captured_length, original_length = header.byteslice(2 * Fiddle::SIZEOF_LONG, 8).unpack("LL")
+        unless captured_length <= MAX_CAPTURE_LENGTH && captured_length <= original_length
+          raise NetworkError.new(:capture_error, "Capture returned an invalid packet length")
+        end
+        # Copy before another pcap read invalidates the borrowed buffer.
+        Fiddle::Pointer.new(data_address)[0, captured_length]
+      end
+
+      def close(handle)
+        call("pcap_close", handle)
+      end
+
+      private
+
+      def buffer(size)
+        pointer = Fiddle::Pointer.malloc(size, Fiddle::RUBY_FREE)
+        pointer[0, size] = "\0" * size
+        pointer
+      end
+
+      def call(name, *arguments)
+        @functions.fetch(name).call(*arguments)
+      end
+
+      def check(status, handle)
+        return status unless status.negative?
+
+        code = [-8, -11].include?(status) ? :permission_denied : :capture_error
+        message = call("pcap_geterr", handle).to_s
+        raise NetworkError.new(code, "Capture failed: #{message}", details: { pcap_status: status })
+      end
+    end
+  end
+end

data/lib/tracepath/resolver.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "socket"
+require "timeout"
+
+module Tracepath
+  class Resolver
+    class LookupTimeout < StandardError; end
+
+    def initialize(clock: Clock)
+      @clock = clock
+      @reverse_cache = {}
+    end
+
+    def resolve(original, options, deadline:)
+      budget = [options.dns_timeout, deadline - @clock.now].min
+      raise NetworkError.new(:resolution_timeout, "name resolution deadline exceeded") unless budget.positive?
+      family = { auto: Socket::AF_UNSPEC, ipv4: Socket::AF_INET, ipv6: Socket::AF_INET6 }.fetch(options.family)
+      address_text, zone = original.split("%", 2)
+      numeric = begin
+                  IPAddr.new(address_text)
+                rescue IPAddr::InvalidAddressError
+                  nil
+                end
+      raise NetworkError.new(:invalid_address, "a scope is only valid for a numeric IPv6 address") if zone && !numeric&.ipv6?
+      address = Addrinfo.getaddrinfo(original, nil, family, Socket::SOCK_DGRAM, 0, 0, timeout: budget).first
+      raise NetworkError.new(:resolution_error, "no address available for #{original}") unless address
+      selected = address.ip_address.split("%", 2).first
+      ip = IPAddr.new(selected)
+      if ip.to_i.zero? || ip.ipv4? && (ip.to_i >= 0xe0000000) || ip.ipv6? && (ip.to_i >> 120) == 0xff
+        raise NetworkError.new(:invalid_address, "target must be a unicast address")
+      end
+      resolved_zone = address.ip_address.split("%", 2)[1]
+      scope_id = (zone || resolved_zone) ? interface_index(zone || resolved_zone) : nil
+      if ip.ipv6? && IPAddr.new("fe80::/10").include?(ip)
+        scope_id ||= options.interface && interface_index(options.interface)
+        raise NetworkError.new(:invalid_address, "link-local IPv6 targets require a scope or interface") unless scope_id
+      end
+      if options.interface && scope_id && interface_index(options.interface) != scope_id
+        raise NetworkError.new(:invalid_address, "target scope and interface disagree")
+      end
+      chosen_family = address.ipv4? ? :ipv4 : :ipv6
+      if chosen_family == :ipv6 && options.dont_fragment
+        raise NetworkError.new(:unsupported_feature, "dont_fragment only applies to IPv4")
+      end
+      Target.new(original: original, address: selected, family: chosen_family, scope_id: scope_id)
+    rescue SocketError => error
+      raise NetworkError.new(:resolution_error, error.message)
+    rescue Errno::ETIMEDOUT
+      raise NetworkError.new(:resolution_timeout, "name resolution timed out for #{original}")
+    rescue SystemCallError => error
+      raise NetworkError.new(:resolution_error, error.message)
+    end
+
+    def reverse(address, timeout:, deadline:)
+      require "resolv"
+      return @reverse_cache[address] if @reverse_cache.key?(address)
+      budget = [timeout, deadline - @clock.now].min
+      return nil unless budget.positive?
+      hostname = Timeout.timeout(budget, LookupTimeout) do
+        Resolv::Hosts.new.getname(address)
+      rescue Resolv::ResolvError
+        Resolv::DNS.open do |dns|
+          dns.timeouts = [budget]
+          dns.getname(address).to_s
+        end
+      end
+      @reverse_cache[address] = hostname.to_s.freeze
+    rescue LookupTimeout, Resolv::ResolvError, Resolv::ResolvTimeout, IOError, SystemCallError
+      @reverse_cache[address] = nil
+    end
+
+    private
+
+    def interface_index(value)
+      return Integer(value, 10) if value.match?(/\A[1-9]\d*\z/)
+      entry = Socket.getifaddrs.find { |item| item.name == value }
+      raise NetworkError.new(:invalid_interface, "interface #{value.inspect} does not exist") unless entry
+      entry.ifindex
+    end
+  end
+end

data/lib/tracepath/runner.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Tracepath
+  class RateLimiter
+    def initialize(rate, clock: Clock)
+      unless rate.is_a?(Numeric) && rate.real? && rate.finite? && rate.positive?
+        raise ArgumentError, "rate_limit must be a finite positive number"
+      end
+      @interval = 1.0 / rate
+      @next_send = -Float::INFINITY
+      @mutex = Mutex.new
+    end
+
+    def acquire(now)
+      @mutex.synchronize do
+        return false if now < @next_send
+        @next_send = now + @interval
+        true
+      end
+    end
+
+    def wait_time(now) = @mutex.synchronize { [@next_send - now, 0.0].max }
+  end
+
+  # One runner owns one transport. No socket option is shared between targets.
+  class Runner
+    WAIT_SLICE = 0.05
+
+    def initialize(request:, options:, cancellation:, limiter:, clock: Clock,
+                   resolver: nil, transport_factory: Transport, on_event: nil)
+      @request, @options, @cancellation = request, options, cancellation
+      @limiter, @clock, @transport_factory = limiter, clock, transport_factory
+      @resolver = resolver || Resolver.new(clock: clock)
+      @on_event = on_event
+    end
+
+    def run
+      outcome = nil
+      begin
+        outcome = execute { |hop| yield hop if block_given? }
+      ensure
+        primary_error = $!
+        begin
+          @transport&.close
+        rescue NetworkError => error
+          if !primary_error && outcome
+            reason = %i[cancelled deadline_exceeded].include?(outcome.stop_reason) ? outcome.stop_reason : :error
+            outcome = outcome.with(stop_reason: reason, error: outcome.error || ErrorInfo.from(error))
+          end
+        rescue Exception
+          raise unless primary_error
+        end
+      end
+      outcome
+    end
+
+    private
+
+    def execute
+      @started_at = Time.now.utc
+      @started = @clock.now
+      @deadline = @started + @options.max_duration
+      @target = Target.new(original: @request.target)
+      @hops = []
+      return result(:cancelled) if @cancellation.cancelled?
+      @target = @resolver.resolve(@request.target, @options, deadline: @deadline)
+      return result(:cancelled) if @cancellation.cancelled?
+      return result(:deadline_exceeded) if @clock.now >= @deadline
+      @transport = @transport_factory.open(target: @target, options: @options)
+      if @on_event
+        packet_size = (@target.family == :ipv6 ? 40 : 20) + (@options.protocol == :tcp ? 20 : 8) + @transport.payload_size
+        emit_event(:trace_started, target: @target, options: @options, packet_size: packet_size)
+      end
+      @next_send = @clock.now
+      @ordinal = 0
+      (@options.first_ttl..@options.max_hops).each do |ttl|
+        reason = interruption
+        return result(reason) if reason
+        emit_event(:hop_started, ttl: ttl) if @on_event
+        hop, reason = trace_hop(ttl)
+        hop = resolve_names(hop) if @options.reverse_dns && !@cancellation.cancelled?
+        @hops << hop
+        yield hop if block_given?
+        reason ||= interruption
+        return result(reason) if reason
+      end
+      result(:max_hops)
+    rescue NetworkError => error
+      result(interruption || :error, error: ErrorInfo.from(error))
+    end
+
+    def trace_hop(ttl)
+      results = Array.new(@options.probes)
+      pending = {}
+      next_index = 0
+      terminal_error = nil
+      interrupted = nil
+
+      loop do
+        now = @clock.now
+        interrupted = interruption
+        if interrupted
+          cancel_remaining_probes(results, pending, next_index, ttl)
+          break
+        end
+
+        pending.delete_if do |_sequence, probe|
+          expired = now >= probe.deadline
+          finish_probe(results, ProbeResult.new(probe: probe, status: :timed_out)) if expired
+          expired
+        end
+
+        while next_index < @options.probes && pending.size < @options.max_inflight && now >= @next_send && @limiter.acquire(now)
+          break if @cancellation.cancelled? || now >= @deadline
+          probe = build_probe(ttl, next_index, now)
+          begin
+            @transport.send_probe(probe)
+            pending[probe.sequence] = probe
+          rescue NetworkError => error
+            terminal_error = ErrorInfo.from(error)
+            record_replies(error.replies, results, pending)
+            finish_probe(results, ProbeResult.new(probe: probe, status: :send_error, error: terminal_error))
+          end
+          next_index += 1
+          @next_send = now + @options.send_interval
+          now = @clock.now
+          break if terminal_error
+        end
+
+        if terminal_error
+          cancel_remaining_probes(results, pending, next_index, ttl)
+          break
+        end
+        break if next_index == @options.probes && pending.empty?
+
+        waits = [WAIT_SLICE, @deadline - now]
+        waits.concat(pending.values.map { |probe| probe.deadline - now })
+        if next_index < @options.probes && pending.size < @options.max_inflight
+          waits << [@next_send - now, @limiter.wait_time(now)].max
+        end
+        replies = begin
+                    @transport.receive([waits.min, 0.0].max)
+                  rescue NetworkError => error
+                    terminal_error = ErrorInfo.from(error)
+                    record_replies(error.replies, results, pending)
+                    cancel_remaining_probes(results, pending, next_index, ttl)
+                    break
+                  end
+        record_replies(replies, results, pending)
+      end
+
+      @run_error = terminal_error if terminal_error
+      hop = Hop.new(ttl: ttl, probes: results)
+      # Evidence obtained before cancellation/deadline still proves arrival.
+      reason = if results.any? { |item| item.replied? && Packet.destination_reached?(item.reply, item.probe) }
+                 :reached
+               elsif interrupted
+                 interrupted
+               elsif terminal_error
+                 :error
+               else
+                 terminal_reason(results)
+               end
+      [hop, reason]
+    end
+
+    def record_replies(replies, results, pending)
+      replies.each do |reply|
+        received_at = reply.fetch(:received_at, @clock.now)
+        pair = pending.find { |_sequence, probe| Packet.match?(reply, probe) }
+        next unless pair
+
+        sequence, probe = pair
+        # Partial reads retain the same correlation and deadline checks.
+        next if received_at < probe.sent_at || received_at > probe.deadline || received_at > @deadline
+
+        finish_probe(results, ProbeResult.new(probe: probe, status: :reply,
+                                              reply: reply, rtt: received_at - probe.sent_at))
+        pending.delete(sequence)
+      end
+    end
+
+    def finish_probe(results, item)
+      results[item.probe.index] = item
+      emit_event(:probe_finished, result: item) if @on_event
+    end
+
+    def cancel_remaining_probes(results, pending, next_index, ttl)
+      pending.each_value { |probe| finish_probe(results, ProbeResult.new(probe: probe, status: :cancelled)) }
+      (next_index...@options.probes).each do |index|
+        finish_probe(results, ProbeResult.new(probe: build_probe(ttl, index, nil), status: :cancelled))
+      end
+    end
+
+    def emit_event(type, **attributes)
+      @on_event.call(Values.copy({ type: type, **attributes }))
+    end
+
+    def build_probe(ttl, index, now)
+      @ordinal += 1
+      Probe.new(family: @target.family, protocol: @options.protocol,
+                source_address: @transport.source_address, destination_address: @target.address,
+                source_port: @transport.source_port,
+                destination_port: @options.protocol == :udp ? @options.port + @ordinal - 1 : @options.port,
+                identifier: @transport.identifier, sequence: @ordinal,
+                tcp_sequence: @options.protocol == :tcp ? SecureRandom.random_number(1 << 32) : nil,
+                ttl: ttl, index: index, sent_at: now, deadline: now && [now + @options.timeout, @deadline].min,
+                payload_size: @transport.payload_size)
+    end
+
+    def terminal_reason(results)
+      replies = results.select(&:replied?).map(&:reply)
+      return nil if replies.any? { |reply| reply[:kind] == :time_exceeded && reply[:icmp_code] == 0 }
+      return :unreachable if replies.any? { |reply| reply[:kind] == :unreachable }
+      failure = replies.find { |reply| %i[packet_too_big parameter_problem time_exceeded].include?(reply[:kind]) }
+      return nil unless failure
+      code = if failure[:kind] == :time_exceeded
+               failure[:icmp_code] == 1 ? :reassembly_timeout : :icmp_error
+             else
+               failure[:kind]
+             end
+      @run_error = ErrorInfo.new(code: code, message: "probe rejected: #{code}",
+                                 details: failure.slice(:source, :icmp_type, :icmp_code, :mtu))
+      :error
+    end
+
+    def resolve_names(hop)
+      probes = hop.probes.map do |item|
+        next item unless item.address && !@cancellation.cancelled? && @clock.now < @deadline
+        name = @resolver.reverse(item.address, timeout: @options.ptr_timeout, deadline: @deadline)
+        name ? item.with(hostname: name) : item
+      end
+      Hop.new(ttl: hop.ttl, probes: probes)
+    end
+
+    def interruption
+      return :cancelled if @cancellation.cancelled?
+      :deadline_exceeded if @clock.now >= @deadline
+    end
+
+    def result(reason, error: @run_error)
+      Result.new(target: @target, options: @options, hops: @hops, started_at: @started_at,
+                 duration: @clock.now - @started, stop_reason: reason, error: error)
+    end
+  end
+end