Preserve responder identity for traceroute and MTR timings

[MartinKolarik]

Traceroute and MTR may receive replies from different IP addresses for probes sent with the same TTL, for example because of ECMP or route changes.

The current public API represents each hop with one resolvedAddress and one resolvedHostname, while timings may contain several packet RTTs. MTR additionally exposes one hop-level asn array. This model cannot associate each timing with the address that produced it when multiple responders are observed at the same hop.

For example, native traceroute may return:

4  2a01:db8::1  2.245 ms  2a01:db8::2  2.175 ms

The current structured result can only return one address alongside both timings:

{
  "resolvedAddress": "2a01:db8::1",
  "resolvedHostname": "first.example",
  "timings": [
    { "rtt": 2.245 },
    { "rtt": 2.175 }
  ]
}

Clients cannot determine that the second RTT belongs to 2a01:db8::2. The same ambiguity applies to hostnames and, for MTR, ASNs.

Expected behavior

• Preserve the original packet-response order.
• Associate each received RTT with the address that produced it.
• Keep each hostname and ASN associated with the corresponding address.
• Keep MTR statistics at hop level, aggregated across all probes sent with that TTL.
• Represent a hop with no responses using an empty timings or responses array, depending on the selected proposal.
• Define how the existing hop-level identity fields behave and whether they should eventually be deprecated.

Proposal A: add responder identity to timings

Extend each existing timing object with the identity of the responder. Array order continues to represent packet-response order.

Traceroute:

{
  "resolvedAddress": "2a01:db8::1",
  "resolvedHostname": "first.example",
  "timings": [
    {
      "rtt": 2.245,
      "resolvedAddress": "2a01:db8::1",
      "resolvedHostname": "first.example"
    },
    {
      "rtt": 2.175,
      "resolvedAddress": "2a01:db8::2",
      "resolvedHostname": "second.example"
    }
  ]
}

MTR:

{
  "resolvedAddress": "192.0.2.1",
  "resolvedHostname": "first.example",
  "asn": [64500],
  "stats": {
    "min": 10,
    "avg": 15,
    "max": 20,
    "total": 2,
    "rcv": 2,
    "drop": 0,
    "loss": 0
  },
  "timings": [
    {
      "rtt": 10,
      "resolvedAddress": "192.0.2.1",
      "resolvedHostname": "first.example",
      "asn": [64500]
    },
    {
      "rtt": 20,
      "resolvedAddress": "192.0.2.2",
      "resolvedHostname": "second.example",
      "asn": [64501]
    }
  ]
}

Advantages:

• Additive change to the existing packet array.
• No duplicate timings and responses representations.
• Keeps response identity directly associated with its RTT.

Trade-offs:

• Responder metadata is repeated when several packets receive replies from the same address.
• The existing hop-level address, hostname, and ASN remain ambiguous unless their semantics are changed or they are deprecated.

Proposal B: replace timings with an ordered responses array in API v2

Replace the hop-level timings array with an array in which each item represents one received packet response. Array order represents packet-response order.

This would be a breaking change made as part of a future v2 response schema together with the other response changes tracked in jsdelivr/globalping#824.

Traceroute:

{
  "resolvedAddress": "2a01:db8::1",
  "resolvedHostname": "first.example",
  "responses": [
    {
      "rtt": 2.245,
      "resolvedAddress": "2a01:db8::1",
      "resolvedHostname": "first.example"
    },
    {
      "rtt": 2.175,
      "resolvedAddress": "2a01:db8::2",
      "resolvedHostname": "second.example"
    }
  ]
}

MTR response items additionally contain asn:

{
  "rtt": 20,
  "resolvedAddress": "192.0.2.2",
  "resolvedHostname": "second.example",
  "asn": [64501]
}

Advantages:

• Makes the distinction between a packet response and aggregate hop information explicit.
• Provides a natural place for response metadata.
• Avoids retaining ambiguous or duplicate packet arrays in the v2 schema.

Trade-offs:

• Requires clients to migrate from timings to responses when adopting API v2.
• Cannot be introduced as a compatible change to the current response schema.

Decision required

Choose between extending timings in the current response schema and replacing it with responses in API v2. At the same time, decide whether the existing hop-level resolvedAddress, resolvedHostname, and MTR asn fields should remain representative fields or be removed from the v2 schema in favor of packet-level identity.