A traceroute, one TTL at a time

• 1
  I/O seam
  Everything reaches the network through ISocket. The TTL loop itself opens nothing.
• 33434+
  One port per probe
  The destination port is bumped every probe — it is the only thing tying a reply back to its sender.
• 11 · 3/3
  The two replies that matter
  Time Exceeded reveals a hop; Destination Unreachable / Port ends the trace.
• 0
  Sockets in the test suite
  A FakeSocket scripts the ICMP replies, so the whole algorithm is tested without root or a network.

Watch a trace

Each round sends n probes with the same TTL and waits for each one in turn. The probe travels along the top of the wire with its TTL counting down; where it reaches zero the router drops it and answers along the bottom. Every control below is a flag the real CLI accepts, and is validated by the same rules parse_args() applies.

What the tool prints

What the printed line leaves out

One line per hop is the whole point of the output, but it hides the bookkeeping underneath: the port each probe was sent to, and the replies that arrived and were thrown away because their quoted port belonged to a different probe.

How a reply is matched to its probe

An ICMP error quotes the packet that caused it: the original IPv4 header plus its first eight bytes — which, for a UDP probe, is the entire UDP header. So the reply carries back the destination port we chose. Because every probe uses a different one, a reply can be tied to the exact probe that triggered it, even when replies arrive out of order. Below is the packet the visualiser last handed to the parser, byte for byte.

No reply inspected yet

• Outer IPv4
• ICMP
• Quoted IPv4
• Quoted UDP
• The destination port everything hinges on

The loop, as it is actually written

The interesting part of Tracer::run() is not sending the probe — it is the wait. A raw ICMP socket sees every ICMP message the host receives, so the reply we want may well arrive behind one we do not. The inner loop keeps reading until the deadline, discarding anything whose recovered port is not ours.

// Wait for the reply to *this* probe, identified by its destination port.
// Replies for other probes (or unparseable packets) are skipped, not counted.
const auto deadline = sent_at + opts_.timeout;
for (;;) {
  const auto remaining = deadline - sock_.now();
  if (remaining <= std::chrono::steady_clock::duration::zero()) break;

  auto pkt = sock_.recv(std::chrono::duration_cast<std::chrono::milliseconds>(remaining));
  if (!pkt) break;  // timed out

  const auto parsed = parse_icmp_error(pkt->data.data(), pkt->data.size());
  if (!parsed) continue;
  // Require a recovered destination port that matches this probe. A reply whose embedded
  // port can't be read (truncated quote) is not ours — never attribute it.
  if (!parsed->has_probe_port || parsed->probe_port != dport) continue;

  probe.responded = true;
  probe.addr = pkt->source_addr;
  probe.rtt_ms = to_ms(sock_.now() - sent_at);
  if (parsed->kind == IcmpKind::PortUnreachable) hop.reached_dest = true;
  break;
}

From src/tracer.cpp. Nothing in it names a socket type, an address family or a system call.

Why the core is testable at all

The whole design turns on one decision: the TTL loop never talks to the operating system. It talks to ISocket — three methods, send_probe, recv and now. On Linux those are a UDP socket with IP_TTL set and a raw ICMP socket. In the tests they are a FakeSocket holding a script of replies and a clock that advances on demand.

That is what makes the trace verifiable: TTL sequencing, port matching, round-trip times, timeouts and the stop condition are all exercised with no privileges, no network and no timing flakiness. It is also why the parsers define their own IPv4 and ICMP structs instead of including <netinet/ip.h> — the core compiles anywhere, and CI proves it by building the full CLI on Linux and the core plus tests on Windows.

The same seam is what let this page exist. The visualiser is a fourth implementation of the same interface: a scenario in place of a network, feeding bytes to a parser that does not know or care where they came from.

Scope, stated plainly