tracepath 0.1.0

data/lib/tracepath/cli/privileges.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require_relative "privilege_check"
+
+module Tracepath
+  class CLI
+    # Only the executable opts into this process policy. No probes have been
+    # sent when prepare runs, so re-execution cannot replay a partial trace.
+    class Privileges
+      class Error < StandardError; end
+
+      def initialize(executable:, check: PrivilegeCheck.new, executor: Process.method(:exec),
+                     uid: -> { Process.euid }, terminal: nil, sudo: "/usr/bin/sudo")
+        @executable = File.expand_path(executable)
+        @check, @executor, @uid, @sudo = check, executor, uid, sudo
+        @terminal = terminal || method(:controlling_terminal?)
+      end
+
+      def prepare(options:, arguments:, err:)
+        return if @uid.call.zero? || !@check.required?(options)
+
+        unless File.executable?(@sudo)
+          raise Error, "probe sockets need additional privileges, but sudo is unavailable; run with the required privileges or use --no-sudo"
+        end
+
+        interactive = @terminal.call
+        message = "tracepath: probe sockets require privileges; restarting with sudo"
+        message += " (non-interactive; no password prompt)" unless interactive
+        err.puts message
+        err.flush
+        @executor.call(*command(arguments, interactive: interactive))
+      rescue SystemCallError => error
+        raise Error, "could not start sudo (#{error.class}); run with the required privileges or use --no-sudo"
+      end
+
+      private
+
+      def command(arguments, interactive:)
+        # Preserve dependency selection, including bundle exec, without passing
+        # Ruby startup hooks or the user's entire environment into root Ruby.
+        environment = ENV.keys.grep(/\ABUNDLE_/).to_h { |name| [name, nil] }
+        environment.merge!("RUBYOPT" => nil, "RUBYLIB" => nil)
+        specifications = runtime_specifications
+        bootstrap = File.expand_path("elevated.rb", __dir__)
+        [environment, @sudo, *(interactive ? [] : ["-n"]), "--", "/usr/bin/env",
+         "GEM_HOME=#{Gem.dir}", "GEM_PATH=#{Gem.path.join(File::PATH_SEPARATOR)}",
+         RbConfig.ruby, "--disable=rubyopt", bootstrap, specifications.length.to_s,
+         *specifications, @executable, "--no-sudo", *arguments]
+      end
+
+      def runtime_specifications
+        seen = {}
+        paths = []
+        visit = lambda do |name|
+          specification = Gem.loaded_specs[name]
+          return unless specification && !seen[name]
+
+          seen[name] = true
+          specification.runtime_dependencies.each { |dependency| visit.call(dependency.name) }
+          paths << File.expand_path(specification.loaded_from)
+        end
+        # Runtime gem dependencies; the entrypoint loads tracepath itself from
+        # its own installation or checkout, not another installed version.
+        %w[fiddle json resolv].each { |name| visit.call(name) }
+        paths
+      end
+
+      def controlling_terminal?
+        File.open("/dev/tty", "r+") { |terminal| terminal.tty? }
+      rescue SystemCallError, IOError
+        false
+      end
+    end
+  end
+end

data/lib/tracepath/cli/text_output.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Tracepath
+  class CLI
+    # Keep console state separate from probe evidence. Replies can finish out of
+    # order; columns always follow probe order, and cancellation is not a timeout.
+    class TextOutput
+      # Hostnames and diagnostics may contain untrusted terminal controls.
+      # Escape only their display form; observations keep their original bytes.
+      def self.escape(value)
+        value.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+             .gsub(/[[:cntrl:]]/) { |character| format('\\x%02x', character.ord) }
+      end
+
+      def initialize(out)
+        @out = out
+      end
+
+      def header(target, options, packet_size: nil)
+        destination = target.address ? "#{target.original} (#{target.address})" : target.original
+        size = packet_size ? ", #{packet_size} byte packets" : ""
+        @out.puts "tracepath to #{self.class.escape(destination)}, #{options.protocol.to_s.upcase}, #{options.max_hops} hops max#{size}"
+        @out.flush
+      end
+
+      def start_hop(ttl)
+        return if @ttl == ttl
+
+        close_hop
+        @ttl, @next_index, @last_address, @pending = ttl, 0, nil, {}
+        write(ttl.to_s.rjust(2))
+      end
+
+      def probe_finished(result)
+        start_hop(result.probe.ttl)
+        add_probe(result.probe.index, result)
+      end
+
+      def hop(hop)
+        # An unstarted, wholly cancelled hop has no observation to display.
+        return if !@ttl && hop.probes.all? { |probe| probe.status == :cancelled }
+
+        start_hop(hop.ttl)
+        hop.probes.each_with_index { |probe, index| add_probe(index, probe) }
+        close_hop
+      end
+
+      def close_hop
+        return unless @ttl
+
+        @out.puts
+        @out.flush
+        @ttl = nil
+      end
+
+      def footer(result)
+        close_hop
+        if result.stop_reason == :cancelled
+          @out.puts "Trace interrupted; #{format('%.3f', result.duration)} s"
+        else
+          address = result.target.address
+          @out.puts "#{result.stop_reason}#{address ? " (#{self.class.escape(address)})" : ''}; #{format('%.3f', result.duration)} s"
+        end
+        @out.flush
+      end
+
+      private
+
+      def add_probe(index, result)
+        return if index < @next_index
+
+        @pending[index] = result
+        while (probe = @pending.delete(@next_index))
+          render_probe(probe)
+          @next_index += 1
+        end
+      end
+
+      def render_probe(probe)
+        case probe.status
+        when :timed_out then write("  *")
+        when :cancelled then nil
+        when :send_error then write("  !send_error#{probe.error ? "(#{self.class.escape(probe.error.code)})" : ''}")
+        when :reply
+          if probe.address != @last_address
+            write("\n  ") if @last_address
+            name = probe.hostname ? "#{Values.serialize_hostname(probe.hostname)} (#{probe.address})" : probe.address.to_s
+            write("  #{self.class.escape(name)}")
+            @last_address = probe.address
+          end
+          write("  #{format('%.3f', probe.rtt_ms)} ms#{reply_marker(probe.reply || {})}")
+        else
+          write("  (#{probe.status})")
+        end
+      end
+
+      def write(text)
+        @out.print(text)
+        @out.flush
+      end
+
+      def reply_marker(reply)
+        mtu = reply[:mtu] || reply["mtu"]
+        kind = reply[:kind] || reply["kind"]
+        return " !F#{mtu ? "(mtu=#{mtu})" : ''}" if mtu || %w[packet_too_big fragmentation_needed].include?(kind.to_s)
+
+        type = reply[:icmp_type] || reply["icmp_type"]
+        code = reply[:icmp_code] || reply["icmp_code"]
+        family = reply[:family] || reply["family"]
+        marker = if family.to_s == "ipv4" && type == 3
+                   { 0 => "!N", 1 => "!H", 2 => "!P", 4 => "!F", 5 => "!S", 9 => "!X", 10 => "!X", 13 => "!X" }[code]
+                 elsif family.to_s == "ipv6" && type == 1
+                   { 0 => "!N", 1 => "!X", 2 => "!S", 3 => "!H", 5 => "!X", 6 => "!X" }[code]
+                 elsif family.to_s == "ipv6" && type == 2
+                   "!F"
+                 end
+
+        marker ? " #{marker}" : ""
+      end
+    end
+  end
+end

data/lib/tracepath/cli.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "tracepath"
+require_relative "cli/text_output"
+require_relative "cli/privileges"
+
+module Tracepath
+  # Process policy belongs here; loading the library never installs signal handlers.
+  class CLI
+    def initialize(argv, out: $stdout, err: $stderr, input: $stdin, runner: Tracepath, signals: Signal, privileges: nil)
+      @argv = argv.dup
+      @out = out
+      @err = err
+      @input = input
+      @runner = runner
+      @signals = signals
+      @privileges = privileges
+      @auto_sudo = true
+      @options = {}
+      @target_sources = []
+      @format = :text
+      @concurrency = 4
+      @rate_limit = 50.0
+      @interrupted = false
+    end
+
+    def run
+      parser = build_parser
+      parser.order!(@argv) { |target| @target_sources << [:target, target] }
+      # OptionParser leaves arguments after -- in argv, without yielding them.
+      @argv.each { |target| @target_sources << [:target, target] }
+      @argv.clear
+      return 0 if @early_exit
+
+      targets = read_targets
+      raise OptionParser::MissingArgument, "HOST or --targets-file is required" if targets.empty?
+
+      validate_batch_options!
+      settings = Options.new(**@options)
+      targets.each { |target| Request.new(target) }
+      if @privileges && @auto_sudo
+        @privileges.prepare(options: settings, arguments: elevation_arguments(targets), err: @err)
+      end
+      token = CancellationToken.new
+      previous_handler = @signals.trap("INT") do
+        @interrupted = true
+        token.cancel
+      end
+      handler_installed = true
+      @options[:cancellation] = token
+
+      results = targets.one? ? run_single(targets.first) : run_batch(targets)
+      return 130 if @interrupted || results.any? { |result| result.stop_reason == :cancelled }
+      return 2 if results.any? { |result| result.error || result.stop_reason == :error }
+
+      results.all?(&:reached?) ? 0 : 1
+    rescue OptionParser::ParseError, ArgumentError => error
+      @text_output&.close_hop
+      @err.puts TextOutput.escape("tracepath: #{error.message}")
+      @err.puts "Try 'tracepath --help' for usage."
+      2
+    rescue Privileges::Error => error
+      @err.puts TextOutput.escape("tracepath: #{error.message}")
+      2
+    rescue StandardError => error
+      @text_output&.close_hop
+      @err.puts TextOutput.escape("tracepath: #{error.class}: #{error.message}")
+      @interrupted ? 130 : 2
+    ensure
+      @signals.trap("INT", previous_handler) if handler_installed
+    end
+
+    private
+
+    def build_parser
+      OptionParser.new do |parser|
+        parser.banner = "Usage: tracepath [options] HOST [HOST ...]"
+        parser.separator "Native IPv4/IPv6 traceroute. Multiple targets use a bounded worker pool."
+        parser.on("-4", "--ipv4", "Use IPv4") { @options[:family] = :ipv4 }
+        parser.on("-6", "--ipv6", "Use IPv6") { @options[:family] = :ipv6 }
+        parser.on("--family FAMILY", %w[auto ipv4 ipv6], "Address family (default: auto)") { |value| @options[:family] = value.to_sym }
+        parser.on("-U", "--udp", "Use UDP (default)") { @options[:protocol] = :udp }
+        parser.on("-I", "--icmp", "Use ICMP echo") { @options[:protocol] = :icmp }
+        parser.on("-T", "--tcp", "Use TCP SYN") { @options[:protocol] = :tcp }
+        parser.on("--protocol PROTOCOL", %w[udp icmp tcp], "Probe protocol") { |value| @options[:protocol] = value.to_sym }
+        parser.on("-p", "--port PORT", Integer, "Destination/base port (UDP: 33434; TCP: 443)") { |value| @options[:port] = value }
+        parser.on("-f", "--first-ttl TTL", Integer, "First TTL/hop limit (default: 1)") { |value| @options[:first_ttl] = value }
+        parser.on("-m", "--max-hops TTL", Integer, "Last TTL/hop limit (default: 30)") { |value| @options[:max_hops] = value }
+        parser.on("-q", "--probes COUNT", Integer, "Probes per hop (default: 3)") { |value| @options[:probes] = value }
+        parser.on("--max-inflight COUNT", Integer, "Outstanding probes per target (default: 3)") { |value| @options[:max_inflight] = value }
+        parser.on("-w", "--timeout SECONDS", Float, "Reply timeout per probe (default: 3)") { |value| @options[:timeout] = value }
+        parser.on("--max-duration SECONDS", Float, "Deadline per target (default: 120)") { |value| @options[:max_duration] = value }
+        parser.on("--dns-timeout SECONDS", Float, "Forward DNS timeout (default: 3)") { |value| @options[:dns_timeout] = value }
+        parser.on("--reverse-dns", "Resolve responder names (off by default)") { @options[:reverse_dns] = true }
+        parser.on("-n", "--numeric", "Show numeric addresses without reverse DNS") { @options[:reverse_dns] = false }
+        parser.on("--ptr-timeout SECONDS", Float, "Reverse DNS timeout (default: 1)") { |value| @options[:ptr_timeout] = value }
+        parser.on("-z", "--send-interval SECONDS", Float, "Minimum probe spacing per target (default: 0.05)") { |value| @options[:send_interval] = value }
+        parser.on("-s", "--source ADDRESS", "Bind the source address") { |value| @options[:source] = value }
+        parser.on("-i", "--interface NAME", "Bind the outgoing interface") { |value| @options[:interface] = value }
+        parser.on("--traffic-class NUMBER", Integer, "IPv4 TOS / IPv6 traffic class (default: 0)") { |value| @options[:traffic_class] = value }
+        parser.on("--packet-size BYTES", Integer, "IP packet size in bytes") { |value| @options[:packet_size] = value }
+        parser.on("-F", "--dont-fragment", "Request no fragmentation") { @options[:dont_fragment] = true }
+        parser.on("--concurrency COUNT", Integer, "Active batch targets (default: 4)") { |value| @concurrency = value }
+        parser.on("--rate-limit PPS", Float, "Probe rate, shared across batch targets (default: 50)") { |value| @rate_limit = value }
+        parser.on("--no-sudo", "Disable automatic CLI privilege elevation") { @auto_sudo = false }
+        parser.on("--targets-file FILE", "Read one target per line; '-' reads standard input") { |value| @target_sources << [:file, value] }
+        parser.on("--json", "Write one final JSON result/batch") { select_format!(:json) }
+        parser.on("--jsonl", "Write {index, result} JSON lines as targets finish") { select_format!(:jsonl) }
+        parser.on("-h", "--help", "Show this help") do
+          @out.puts parser
+          @early_exit = true
+        end
+        parser.on("--version", "Show version") do
+          @out.puts "tracepath #{Tracepath::VERSION}"
+          @early_exit = true
+        end
+      end
+    end
+
+    def select_format!(format)
+      raise OptionParser::InvalidOption, "--json and --jsonl cannot be combined" if @format != :text && @format != format
+
+      @format = format
+    end
+
+    def read_targets
+      @target_sources.flat_map do |kind, value|
+        next [value] if kind == :target
+
+        if value == "-"
+          target_lines(@input)
+        else
+          File.open(value, "r:utf-8") { |file| target_lines(file) }
+        end
+      end
+    end
+
+    def target_lines(input)
+      input.each_line.filter_map do |line|
+        target = line.strip
+        target unless target.empty? || target.start_with?("#")
+      end
+    end
+
+    def validate_batch_options!
+      raise ArgumentError, "concurrency must be in 1..256" unless (1..256).cover?(@concurrency)
+      raise ArgumentError, "rate_limit must be finite and positive" unless @rate_limit.finite? && @rate_limit.positive?
+    end
+
+    def elevation_arguments(targets)
+      arguments = @options.flat_map do |name, value|
+        case name
+        when :reverse_dns then [value ? "--reverse-dns" : "--numeric"]
+        when :dont_fragment then value ? ["--dont-fragment"] : []
+        else ["--#{name.to_s.tr('_', '-')}", value.to_s]
+        end
+      end
+      arguments.concat(["--concurrency", @concurrency.to_s, "--rate-limit", @rate_limit.to_s])
+      arguments << "--#{@format}" unless @format == :text
+      # stdin and target files have already been read as the original user.
+      # Passing the validated targets also prevents a second file read as root.
+      arguments.concat(["--", *targets])
+    end
+
+    def run_single(target)
+      rendered_hops = {}
+      progress = @format == :text ? { on_event: method(:render_event) } : {}
+      result = @runner.trace(target, rate_limit: @rate_limit, **progress, **@options) do |hop|
+        next unless @format == :text && @header_rendered
+
+        render_hop(hop)
+        rendered_hops[hop.ttl] = true
+      end
+      case @format
+      when :json then @out.puts JSON.generate(result.to_h)
+      when :jsonl then render_json_line(result, 0)
+      else
+        unless @header_rendered
+          text_output.header(result.target, Options.new(**@options.except(:cancellation)))
+        end
+        result.hops.each { |hop| render_hop(hop) unless rendered_hops[hop.ttl] }
+        render_footer(result)
+      end
+      render_error(result)
+      [result]
+    end
+
+    def run_batch(targets)
+      rendered = {}
+      batch = @runner.trace_many(targets, concurrency: @concurrency, rate_limit: @rate_limit, **@options) do |result, index|
+        render_batch_result(result, index, targets.length)
+        rendered[index] = true
+      end
+      batch.results.each_with_index do |result, index|
+        render_batch_result(result, index, targets.length) unless rendered[index]
+      end
+      if @format == :json
+        @out.puts JSON.generate(batch.to_h)
+      elsif @format == :text
+        counts = batch.counts.map { |reason, count| "#{reason}=#{count}" }.join(" ")
+        @out.puts "batch: #{counts}; #{format('%.3f', batch.duration)} s"
+      end
+      batch.results
+    end
+
+    def render_batch_result(result, index, total)
+      if @format == :jsonl
+        render_json_line(result, index)
+      elsif @format == :text
+        @out.puts "[#{index + 1}/#{total}] #{TextOutput.escape(result.target.original)}"
+        result.hops.each { |hop| render_hop(hop) }
+        render_footer(result)
+      end
+      render_error(result)
+    end
+
+    def render_json_line(result, index)
+      @out.puts JSON.generate(index: index, result: result.to_h)
+      @out.flush
+    end
+
+    def render_hop(hop)
+      text_output.hop(hop)
+    end
+
+    def render_event(event)
+      case event.fetch(:type)
+      when :trace_started
+        text_output.header(event.fetch(:target), event.fetch(:options), packet_size: event.fetch(:packet_size))
+        @header_rendered = true
+      when :hop_started
+        text_output.start_hop(event.fetch(:ttl))
+      when :probe_finished
+        # PTR resolution stays outside the receive loop. Named output is
+        # rendered once the completed Hop contains its resolved names.
+        text_output.probe_finished(event.fetch(:result)) unless @options[:reverse_dns]
+      end
+    end
+
+    def text_output = (@text_output ||= TextOutput.new(@out))
+
+    def render_footer(result)
+      text_output.footer(result)
+    end
+
+    def render_error(result)
+      return unless result.error
+
+      @err.puts TextOutput.escape("tracepath: #{result.target.original}: #{result.error.code}: #{result.error.message}")
+    end
+  end
+end

data/lib/tracepath/errors.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Tracepath
+  # Only expected environmental failures use this exception. Programming errors
+  # and exceptions raised by callers must retain their original identity.
+  class NetworkError < StandardError
+    attr_reader :code, :details, :replies
+
+    def initialize(code, message, details: {}, replies: [])
+      @code = code.to_sym
+      @details = details
+      # A later I/O failure must not discard observations already collected.
+      @replies = replies.dup.freeze
+      super(message)
+    end
+  end
+
+  module Clock
+    def self.now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+
+  class CancellationToken
+    def initialize(parent: nil)
+      @parent = parent
+      @cancelled = false
+    end
+
+    # Deliberately trap-safe: no mutex, allocation, or network operation.
+    def cancel = (@cancelled = true)
+
+    def cancelled? = @cancelled || !!@parent&.cancelled?
+  end
+end

data/lib/tracepath/models.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Tracepath
+  module Values
+    def self.copy(value)
+      case value
+      when Hash then value.to_h { |key, item| [copy(key), copy(item)] }.freeze
+      when Array then value.map { |item| copy(item) }.freeze
+      when String, Time then value.dup.freeze
+      else value
+      end
+    end
+
+    def self.serialize(value)
+      case value
+      when Hash then value.to_h { |key, item| [key, serialize(item)] }
+      when Array then value.map { |item| serialize(item) }
+      when Time then value.iso8601(6)
+      else value.respond_to?(:to_h) && !value.nil? ? value.to_h : value
+      end
+    end
+
+    # DNS labels are octets, not necessarily UTF-8. Decimal escapes retain
+    # invalid octets; escaping literal backslashes makes that form reversible.
+    def self.serialize_hostname(hostname)
+      return if hostname.nil?
+
+      hostname.b.gsub("\\") { "\\092" }.force_encoding(Encoding::UTF_8).scrub do |bytes|
+        bytes.bytes.map { |byte| format("\\%03d", byte) }.join
+      end
+    end
+
+    def to_h = self.class.members.to_h { |member| [member, Values.serialize(public_send(member))] }
+
+    def to_json(*args) = to_h.to_json(*args)
+  end
+
+  ErrorInfo = Data.define(:code, :message, :details) do
+    include Values
+
+    def initialize(code:, message:, details: {})
+      super(code: code, message: Values.copy(message), details: Values.copy(details))
+    end
+
+    def self.from(error) = new(code: error.code, message: error.message, details: error.details)
+  end
+
+  Target = Data.define(:original, :address, :family, :scope_id) do
+    include Values
+
+    def initialize(original:, address: nil, family: nil, scope_id: nil)
+      super(original: Values.copy(original), address: Values.copy(address), family: family, scope_id: scope_id)
+    end
+  end
+
+  Probe = Data.define(:family, :protocol, :source_address, :destination_address,
+                      :source_port, :destination_port, :identifier, :sequence, :tcp_sequence,
+                      :ttl, :index, :sent_at, :deadline, :payload_size) do
+    include Values
+
+    def initialize(family:, protocol:, source_address:, destination_address:, ttl:, index:,
+                   sent_at:, deadline:, source_port: nil, destination_port: nil, identifier: nil,
+                   sequence: nil, tcp_sequence: nil, payload_size: 0)
+      super(family: family, protocol: protocol, source_address: Values.copy(source_address),
+            destination_address: Values.copy(destination_address), source_port: source_port,
+            destination_port: destination_port, identifier: identifier, sequence: sequence,
+            tcp_sequence: tcp_sequence, ttl: ttl, index: index, sent_at: sent_at,
+            deadline: deadline, payload_size: payload_size)
+    end
+  end
+
+  ProbeResult = Data.define(:probe, :status, :reply, :rtt, :error, :hostname) do
+    include Values
+
+    def initialize(probe:, status:, reply: nil, rtt: nil, error: nil, hostname: nil)
+      super(probe: probe, status: status, reply: Values.copy(reply), rtt: rtt,
+            error: error, hostname: Values.copy(hostname))
+    end
+
+    def address = reply&.fetch(:source, nil)
+
+    def rtt_ms = rtt && rtt * 1_000.0
+
+    def replied? = status == :reply
+
+    def to_h = super.merge(hostname: Values.serialize_hostname(hostname))
+  end
+
+  Hop = Data.define(:ttl, :probes) do
+    include Values
+
+    def initialize(ttl:, probes:)
+      super(ttl: ttl, probes: probes.dup.freeze)
+    end
+
+    def addresses = probes.filter_map(&:address).uniq.freeze
+
+    def rtts = probes.filter_map(&:rtt)
+
+    def rtt_min = rtts.min
+
+    def rtt_max = rtts.max
+
+    def rtt_avg = (values = rtts).empty? ? nil : values.sum / values.size
+
+    # Cancelled and unsent attempts are not evidence of packet loss.
+    def response_rate
+      completed = probes.count { |probe| %i[reply timed_out].include?(probe.status) }
+      completed.zero? ? nil : probes.count(&:replied?).fdiv(completed)
+    end
+  end
+
+  Result = Data.define(:target, :options, :hops, :started_at, :duration, :stop_reason, :error) do
+    include Values
+
+    def initialize(target:, options:, hops: [], started_at:, duration:, stop_reason:, error: nil)
+      super(target: target, options: options, hops: hops.dup.freeze,
+            started_at: Values.copy(started_at), duration: duration, stop_reason: stop_reason, error: error)
+    end
+
+    def reached? = stop_reason == :reached
+  end
+
+  BatchResult = Data.define(:results, :duration) do
+    include Values
+
+    def initialize(results:, duration:)
+      super(results: results.dup.freeze, duration: duration)
+    end
+
+    def counts = results.each_with_object(Hash.new(0)) { |result, counts| counts[result.stop_reason] += 1 }.freeze
+
+    def to_h = super.merge(counts: counts)
+  end
+end