Explain the factoring phases and input edge cases, and make the DNS
fixture and session-reuse timeout intent easier to read.
Move site-name guidance to the queues reference with an inline release
marker, and link to it from lookup_mx and the traffic-shaping guide.
Add a breaking-change note with an observed collision pair.
Normalize, deduplicate and sort MX destinations before deriving site
names. Use per-label alternatives only when their expansion matches
the destination set; otherwise factor complete hostname branches.
Keep MX preferences in connection plans rather than site identity.
Keep asterisks literal and percent-encode other special label bytes
so names remain distinct without introducing metric-label escapes.
Cover collisions, normalization, ports, shaping and queue/session
sharing, and document the naming and preference semantics.
A message received via inter-node transfer, on systems hosted on AWS, could
end up with a wildly incorrect far-future timestamp. The underlying mac_address
crate would pick a NIC with the same MAC address as other AWS instances in the
cluster, and that triggered a code path where the collision resolving logic
misinterpreted the timestamp portion of the incoming spool id.
The thing that made this painful was the logic in spool_id.rs: it
misinterpreted the subsecond portion of the timestamp extracted from
the uuid, and due to the way that that field wraps, could produce wildly
inaccurate deltas with a huge multiplier.
As a belt and suspenders treatment, allow the user to influence which
MAC address is selected via the new KUMO_MAC_INTERFACE and
KUMO_MAC_ADDRESS environment variables.
I factored out the sample outputs and used an include to pull
in that content.
In the future, we could automate creating those sample data files
based on the live instance, however, it will need some thought
as many metrics are instantiated dynamically. That means that
simply launching the server to dump the initial counters could
miss a large number of the main production counters that are
the most interesting. Likely we'll need something smarter than
that approach. But that is an issue for the future!
A number of manually authored HTTP api docs can now be replaced
by the versions generated from code, making them more accurate
and less likely to drift away from the implementation as
future changes are made, so that's what this commit does.