pingerplot 1.6.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,456 @@
1
+ """ICMP echo on Linux and macOS, without root — the ``mtr`` technique.
2
+
3
+ The Windows backend (``icmp.py``) gets both halves of a traceroute from one
4
+ call: ``IcmpSendEcho`` returns the echo reply *or* the router's TTL-exceeded,
5
+ already decoded. POSIX has no such call, so this module assembles the same
6
+ thing from two different mechanisms:
7
+
8
+ * **The probe socket** is ``SOCK_DGRAM``/``IPPROTO_ICMP``, not ``SOCK_RAW``.
9
+ That is the whole reason no root is needed — on Linux the kernel owns the
10
+ identifier and the checksum and will only deliver replies to echoes *you*
11
+ sent, so it can safely hand the socket to an unprivileged process. Linux
12
+ gates it on ``net.ipv4.ping_group_range``; macOS allows it outright but
13
+ makes no such delivery guarantee, so every reply is matched to its probe
14
+ (:func:`reply_is_ours`) rather than trusted.
15
+
16
+ * **The router's TTL-exceeded** does not arrive on that socket on Linux,
17
+ because it is an *error* relating to the datagram we sent, not a message
18
+ addressed to us. It goes to the socket's error queue, read with
19
+ ``recvmsg(MSG_ERRQUEUE)`` after enabling ``IP_RECVERR``. macOS has neither;
20
+ there the error is delivered as an ordinary readable ICMP message. Both
21
+ paths are handled, because the alternative is a backend that traces on one
22
+ of the two platforms and silently reports every hop as ``*`` on the other.
23
+
24
+ Same signature and same :class:`PingResult` as the Windows backend, so the
25
+ engine above does not know or care which one it is talking to.
26
+
27
+ Status: the packet building, the error-queue decoding and the reply matching
28
+ are unit-tested against synthetic bytes, and the live path is exercised
29
+ wherever the platform actually permits an unprivileged ICMP socket. It has NOT
30
+ been run against real hardware on a real multi-hop path — smoke-test it on a
31
+ Linux box before trusting a trace from it.
32
+ """
33
+ from __future__ import annotations
34
+
35
+ import errno
36
+ import itertools
37
+ import os
38
+ import platform
39
+ import select
40
+ import socket
41
+ import struct
42
+ import sys
43
+ import threading
44
+ import time
45
+ from typing import Optional, Tuple
46
+
47
+ from .icmp import (
48
+ ERROR_INVALID_NETNAME,
49
+ IP_DEST_HOST_UNREACHABLE,
50
+ IP_DEST_NET_UNREACHABLE,
51
+ IP_DEST_PORT_UNREACHABLE,
52
+ IP_DEST_PROT_UNREACHABLE,
53
+ IP_REQ_TIMED_OUT,
54
+ IP_SUCCESS,
55
+ IP_TTL_EXPIRED_TRANSIT,
56
+ PingResult,
57
+ )
58
+
59
+ ICMP_ECHO_REQUEST = 8
60
+ ICMP_ECHO_REPLY = 0
61
+ ICMP_TIME_EXCEEDED = 11
62
+ ICMP_DEST_UNREACH = 3
63
+
64
+ # Linux, from <linux/errqueue.h> and <linux/in.h>. Absent from the socket
65
+ # module on some builds, so they are spelled out rather than imported.
66
+ IP_RECVERR = 11
67
+ SO_EE_ORIGIN_ICMP = 2
68
+ MSG_ERRQUEUE = getattr(socket, "MSG_ERRQUEUE", 0x2000)
69
+
70
+ _LINUX = sys.platform.startswith("linux")
71
+ _SUPPORTED_PLATFORM = _LINUX or sys.platform == "darwin"
72
+
73
+ # SO_TIMESTAMPNS: the kernel stamps each received packet, so an RTT does not
74
+ # include the time this thread spent waiting for the GIL before it could read
75
+ # the reply -- which, with anything else busy in the process (a Timeline
76
+ # redraw holds it for tens of ms), was being reported as network latency.
77
+ # Python's socket module does not export it. 35 is the asm-generic value;
78
+ # alpha, mips, parisc and sparc number it differently and are left on the
79
+ # user-space clock rather than guessed at. macOS has only the microsecond
80
+ # SO_TIMESTAMP and is likewise left as it was.
81
+ _SO_TIMESTAMPNS = getattr(socket, "SO_TIMESTAMPNS", None)
82
+ if _SO_TIMESTAMPNS is None and _LINUX and platform.machine().lower() in {
83
+ "x86_64", "amd64", "i386", "i686", "aarch64", "arm64", "armv6l", "armv7l",
84
+ "armv8l", "riscv64", "ppc64le", "ppc64", "s390x", "loongarch64"}:
85
+ _SO_TIMESTAMPNS = 35
86
+ _TIMESPEC = struct.Struct("@ll") # struct timespec: native long tv_sec, tv_nsec
87
+ _MAX_KERNEL_RTT_NS = 60 * 1_000_000_000
88
+
89
+ # ICMP dest-unreachable codes -> the IP_STATUS the rest of the app speaks, so
90
+ # one vocabulary covers both backends.
91
+ _UNREACH_STATUS = {
92
+ 0: IP_DEST_NET_UNREACHABLE,
93
+ 1: IP_DEST_HOST_UNREACHABLE,
94
+ 2: IP_DEST_PROT_UNREACHABLE,
95
+ 3: IP_DEST_PORT_UNREACHABLE,
96
+ }
97
+
98
+
99
+ # Sequence numbers are the one thing a reply provably echoes back unchanged,
100
+ # so each probe gets its own. Random start: another PingerPlot process on a
101
+ # macOS box shares the ICMP namespace with this one.
102
+ _seq_counter = itertools.count(int.from_bytes(os.urandom(2), "big"))
103
+ _seq_lock = threading.Lock()
104
+
105
+
106
+ def next_seq() -> int:
107
+ """A sequence number no other in-flight probe from this process holds. It
108
+ used to be the millisecond clock, which every probe submitted in the same
109
+ millisecond -- most of a 30-hop round -- shared."""
110
+ with _seq_lock:
111
+ return next(_seq_counter) & 0xFFFF
112
+
113
+
114
+ def checksum(data: bytes) -> int:
115
+ """The internet checksum (RFC 1071) over ``data``.
116
+
117
+ The kernel recomputes this for a SOCK_DGRAM ICMP socket, so it is not
118
+ load-bearing on the send path — but a correct one costs nothing and the
119
+ function is what verifies a *received* packet.
120
+ """
121
+ if len(data) % 2:
122
+ data += b"\x00"
123
+ total = 0
124
+ for i in range(0, len(data), 2):
125
+ total += (data[i] << 8) | data[i + 1]
126
+ total = (total >> 16) + (total & 0xFFFF)
127
+ total += total >> 16
128
+ return ~total & 0xFFFF
129
+
130
+
131
+ def build_echo(ident: int, seq: int, payload: bytes) -> bytes:
132
+ """An ICMP echo request. The kernel overwrites ``ident`` (and the checksum)
133
+ on a SOCK_DGRAM socket — that substitution is precisely what makes the
134
+ unprivileged socket safe — so nothing may depend on it coming back."""
135
+ header = struct.pack("!BBHHH", ICMP_ECHO_REQUEST, 0, 0,
136
+ ident & 0xFFFF, seq & 0xFFFF)
137
+ csum = checksum(header + payload)
138
+ return struct.pack("!BBHHH", ICMP_ECHO_REQUEST, 0, csum,
139
+ ident & 0xFFFF, seq & 0xFFFF) + payload
140
+
141
+
142
+ def strip_ip_header(data: bytes) -> bytes:
143
+ """Return the ICMP portion of ``data``.
144
+
145
+ Linux hands a SOCK_DGRAM ICMP socket the ICMP message alone; some BSD-derived
146
+ stacks include the IPv4 header. Rather than branch on platform — which would
147
+ be a guess on any stack not tested here — detect it: an IPv4 header starts
148
+ with version 4 and an IHL of at least 5, giving a first byte of 0x45-0x4F,
149
+ while an ICMP message starts with its type. None of the types this module
150
+ cares about (0, 3, 11) fall in that range, so the two cannot be confused.
151
+ """
152
+ if data and 0x45 <= data[0] <= 0x4F:
153
+ ihl = (data[0] & 0x0F) * 4
154
+ if len(data) > ihl:
155
+ return data[ihl:]
156
+ return data
157
+
158
+
159
+ def parse_icmp(data: bytes) -> Optional[Tuple[int, int, bytes]]:
160
+ """``(type, code, rest)`` from an ICMP message, or None if it is too short."""
161
+ body = strip_ip_header(data)
162
+ if len(body) < 8:
163
+ return None
164
+ return body[0], body[1], body[8:]
165
+
166
+
167
+ def reply_is_ours(data: bytes, dest_ip: str, ident: int, seq: int,
168
+ check_ident: bool) -> bool:
169
+ """Whether a message read from the probe socket answers *this* probe.
170
+
171
+ Linux already guarantees it: a ping socket only receives replies carrying
172
+ its kernel-assigned identifier, and router errors go to its own error
173
+ queue. macOS does not. Its ICMP datagram socket behaves like a raw one, so
174
+ with a round's probes in flight each could take another's reply -- or a
175
+ TTL-exceeded meant for another probe -- as its own.
176
+
177
+ * Echo reply: our sequence number, and our identifier when the kernel has
178
+ not rewritten it (``check_ident``; Linux rewrites it, so not there).
179
+ * TTL exceeded / unreachable: the quoted original must be an ICMP echo to
180
+ ``dest_ip`` with our sequence number. The quoted identifier is not
181
+ checked, because a NAT may rewrite it on the way back.
182
+ """
183
+ body = strip_ip_header(data)
184
+ if len(body) < 8:
185
+ return False
186
+ itype = body[0]
187
+ if itype == ICMP_ECHO_REPLY:
188
+ rid, rseq = struct.unpack_from("!HH", body, 4)
189
+ return rseq == seq and (not check_ident or rid == ident)
190
+ if itype in (ICMP_TIME_EXCEEDED, ICMP_DEST_UNREACH):
191
+ quoted = body[8:]
192
+ if len(quoted) < 20 or quoted[0] >> 4 != 4 or quoted[9] != socket.IPPROTO_ICMP:
193
+ return False
194
+ inner = quoted[(quoted[0] & 0x0F) * 4:]
195
+ if len(inner) < 8 or inner[0] != ICMP_ECHO_REQUEST:
196
+ return False
197
+ if socket.inet_ntoa(quoted[16:20]) != dest_ip:
198
+ return False
199
+ return struct.unpack_from("!H", inner, 6)[0] == seq
200
+ return False
201
+
202
+
203
+ def kernel_rtt_ms(ancdata, sent_ns: int) -> Optional[float]:
204
+ """RTT from a received packet's SO_TIMESTAMPNS control message, or None.
205
+
206
+ ``sent_ns`` is ``time.time_ns()`` taken just before sendto; the kernel's
207
+ stamp is the same clock (CLOCK_REALTIME). That clock can be stepped by NTP
208
+ mid-probe, so a negative or absurd difference is discarded and the caller
209
+ falls back to its own measurement.
210
+ """
211
+ if _SO_TIMESTAMPNS is None:
212
+ return None
213
+ for level, ctype, cdata in ancdata:
214
+ if level != socket.SOL_SOCKET or ctype != _SO_TIMESTAMPNS or len(cdata) < _TIMESPEC.size:
215
+ continue
216
+ sec, nsec = _TIMESPEC.unpack_from(cdata)
217
+ delta = sec * 1_000_000_000 + nsec - sent_ns
218
+ if 0 <= delta < _MAX_KERNEL_RTT_NS:
219
+ return delta / 1_000_000.0
220
+ return None
221
+
222
+
223
+ def parse_errqueue(cmsg_data: bytes) -> Optional[Tuple[int, int, Optional[str]]]:
224
+ """Decode a Linux ``IP_RECVERR`` control message.
225
+
226
+ Returns ``(icmp_type, icmp_code, offender_ip)``. The layout is a
227
+ ``struct sock_extended_err`` (16 bytes) followed by the offending host's
228
+ ``sockaddr_in`` — the router that sent the error, which is the one piece of
229
+ information a traceroute actually wants:
230
+
231
+ u32 ee_errno; u8 ee_origin; u8 ee_type; u8 ee_code; u8 ee_pad;
232
+ u32 ee_info; u32 ee_data;
233
+ struct sockaddr_in {u16 family; u16 port; u8 addr[4]; u8 zero[8];}
234
+
235
+ ``ee_origin`` must be SO_EE_ORIGIN_ICMP; a local error (origin 1) carries no
236
+ offender and is not a hop.
237
+ """
238
+ if len(cmsg_data) < 16:
239
+ return None
240
+ # Native byte order: this is a kernel structure, not a wire format.
241
+ _errno, origin, ee_type, ee_code = struct.unpack_from("=IBBB", cmsg_data, 0)
242
+ if origin != SO_EE_ORIGIN_ICMP:
243
+ return None
244
+ offender = None
245
+ if len(cmsg_data) >= 24:
246
+ # sin_addr sits 4 bytes into the sockaddr_in, which starts at offset 16.
247
+ offender = socket.inet_ntoa(cmsg_data[20:24])
248
+ return ee_type, ee_code, offender
249
+
250
+
251
+ def _status_for(icmp_type: int, icmp_code: int) -> int:
252
+ if icmp_type == ICMP_TIME_EXCEEDED:
253
+ return IP_TTL_EXPIRED_TRANSIT
254
+ if icmp_type == ICMP_DEST_UNREACH:
255
+ return _UNREACH_STATUS.get(icmp_code, IP_DEST_HOST_UNREACHABLE)
256
+ return IP_REQ_TIMED_OUT
257
+
258
+
259
+ def is_available() -> bool:
260
+ """True when an unprivileged ICMP socket can actually be opened here.
261
+
262
+ Linux gates SOCK_DGRAM/IPPROTO_ICMP on net.ipv4.ping_group_range, so the
263
+ platform being right is not enough — a distro that has not opened it up
264
+ gives EACCES. Ask the kernel rather than guess.
265
+ """
266
+ if not _SUPPORTED_PLATFORM:
267
+ return False
268
+ try:
269
+ s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_ICMP)
270
+ except (OSError, AttributeError):
271
+ return False
272
+ s.close()
273
+ return True
274
+
275
+
276
+ def unavailable_reason() -> str:
277
+ """Why is_available() said no — worth surfacing, because the Linux case has
278
+ a one-line fix and 'ICMP not available' does not hint at it."""
279
+ if not _SUPPORTED_PLATFORM:
280
+ return f"no unprivileged ICMP backend for {sys.platform}"
281
+ try:
282
+ socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_ICMP).close()
283
+ except OSError as exc:
284
+ if exc.errno in (errno.EACCES, errno.EPERM):
285
+ return ("unprivileged ICMP sockets are not permitted for this user. "
286
+ "On Linux: sysctl -w net.ipv4.ping_group_range=\"0 2147483647\" "
287
+ f"(or add this process's group, {os.getgid() if hasattr(os, 'getgid') else '?'}"
288
+ ", to the range)")
289
+ return f"cannot open an ICMP socket: {exc}"
290
+ return ""
291
+
292
+
293
+ def ping(
294
+ dest_ip: str,
295
+ ttl: int = 128,
296
+ timeout_ms: int = 1000,
297
+ payload: bytes = b"PingerPlot-probe..",
298
+ tos: int = 0,
299
+ source_ip: Optional[str] = None,
300
+ ) -> PingResult:
301
+ """One ICMP echo, matching :func:`pingerplot.icmp.ping`'s contract."""
302
+ if not _SUPPORTED_PLATFORM:
303
+ raise RuntimeError(f"no POSIX ICMP backend for {sys.platform}")
304
+
305
+ timeout = max(0.001, timeout_ms / 1000.0)
306
+ ident = os.getpid() & 0xFFFF
307
+ seq = next_seq()
308
+ sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_ICMP)
309
+ try:
310
+ sock.setsockopt(socket.IPPROTO_IP, socket.IP_TTL, max(1, min(int(ttl), 255)))
311
+ if tos:
312
+ try:
313
+ sock.setsockopt(socket.IPPROTO_IP, socket.IP_TOS, int(tos) & 0xFF)
314
+ except OSError:
315
+ pass # marking is best effort, the probe still goes
316
+ if _LINUX:
317
+ try:
318
+ sock.setsockopt(socket.IPPROTO_IP, IP_RECVERR, 1)
319
+ except OSError:
320
+ pass # without it intermediate hops read as timeouts
321
+ stamped = False
322
+ if _LINUX and _SO_TIMESTAMPNS is not None:
323
+ try:
324
+ sock.setsockopt(socket.SOL_SOCKET, _SO_TIMESTAMPNS, 1)
325
+ stamped = True
326
+ except OSError:
327
+ pass # falls back to timing in user space
328
+ if source_ip:
329
+ try:
330
+ sock.bind((source_ip, 0))
331
+ except OSError:
332
+ # Same contract as the Windows backend, which fails an address
333
+ # the machine does not hold with ERROR_INVALID_NETNAME rather
334
+ # than falling back to the default route. Raising instead would
335
+ # abort the trace with a bare errno 99, and inside a monitoring
336
+ # round _gather_range would swallow it into a timeout -- so a
337
+ # pinned interface going away mid-run would report 100% loss on
338
+ # a path that is fine. That silent-wrong-numbers outcome is the
339
+ # exact thing the setting exists to prevent.
340
+ return PingResult(ERROR_INVALID_NETNAME, None, None, False)
341
+ sock.setblocking(False)
342
+
343
+ packet = build_echo(ident, seq, payload)
344
+ start = time.perf_counter()
345
+ # Last thing before the send: from here to the syscall this thread
346
+ # holds the GIL throughout, so the stamp is not delayed by anyone.
347
+ sent_ns = time.time_ns() if stamped else None
348
+ try:
349
+ sock.sendto(packet, (dest_ip, 0))
350
+ except OSError as exc:
351
+ return PingResult(_send_failure_status(exc), None, None, False)
352
+
353
+ deadline = start + timeout
354
+ while True:
355
+ remaining = deadline - time.perf_counter()
356
+ if remaining <= 0:
357
+ return PingResult(IP_REQ_TIMED_OUT, None, None, False)
358
+
359
+ # Error queue first: on Linux the router's TTL-exceeded is here, and
360
+ # it is the only place the router's address exists.
361
+ hop = _read_errqueue(sock, start, sent_ns)
362
+ if hop is not None:
363
+ return hop
364
+
365
+ try:
366
+ select.select([sock], [], [sock], min(0.05, remaining))
367
+ except OSError:
368
+ return PingResult(IP_REQ_TIMED_OUT, None, None, False)
369
+
370
+ reply = _read_reply(sock, dest_ip, start, ident, seq, sent_ns)
371
+ if reply is not None:
372
+ return reply
373
+ finally:
374
+ sock.close()
375
+
376
+
377
+ def _send_failure_status(exc: OSError) -> int:
378
+ """A send that fails locally still has to become a PingResult, not an
379
+ exception — a single unroutable target must not abort the round."""
380
+ if exc.errno == errno.ENETUNREACH:
381
+ return IP_DEST_NET_UNREACHABLE
382
+ if exc.errno in (errno.EHOSTUNREACH, errno.EHOSTDOWN):
383
+ return IP_DEST_HOST_UNREACHABLE
384
+ return IP_REQ_TIMED_OUT
385
+
386
+
387
+ def _rtt_ms(ancdata, sent_ns: Optional[int], start: float) -> float:
388
+ """The kernel's figure when there is one, else the user-space clock."""
389
+ if sent_ns is not None:
390
+ rtt = kernel_rtt_ms(ancdata, sent_ns)
391
+ if rtt is not None:
392
+ return rtt
393
+ return (time.perf_counter() - start) * 1000.0
394
+
395
+
396
+ def _read_errqueue(sock: socket.socket, start: float,
397
+ sent_ns: Optional[int] = None) -> Optional[PingResult]:
398
+ if not _LINUX:
399
+ return None
400
+ try:
401
+ _data, ancdata, _flags, _addr = sock.recvmsg(512, 1024, MSG_ERRQUEUE)
402
+ except (BlockingIOError, InterruptedError):
403
+ return None
404
+ except OSError:
405
+ return None
406
+ for level, ctype, cdata in ancdata:
407
+ if level != socket.IPPROTO_IP or ctype != IP_RECVERR:
408
+ continue
409
+ parsed = parse_errqueue(cdata)
410
+ if parsed is None:
411
+ continue
412
+ icmp_type, icmp_code, offender = parsed
413
+ rtt = _rtt_ms(ancdata, sent_ns, start)
414
+ if icmp_type == ICMP_TIME_EXCEEDED:
415
+ return PingResult(IP_TTL_EXPIRED_TRANSIT, rtt, offender, False)
416
+ # An unreachable is a hop that answered, but not the destination. No
417
+ # RTT: the number would describe an error path, not a round trip.
418
+ return PingResult(_status_for(icmp_type, icmp_code), None, offender, False)
419
+ return None
420
+
421
+
422
+ def _read_reply(sock: socket.socket, dest_ip: str, start: float,
423
+ ident: int, seq: int, sent_ns: Optional[int] = None) -> Optional[PingResult]:
424
+ ancdata = []
425
+ try:
426
+ if sent_ns is not None: # timestamps on: they arrive as ancillary data
427
+ data, ancdata, _flags, addr = sock.recvmsg(2048, 1024)
428
+ else:
429
+ data, addr = sock.recvfrom(2048)
430
+ except (BlockingIOError, InterruptedError):
431
+ return None
432
+ except OSError:
433
+ return None
434
+ parsed = parse_icmp(data)
435
+ if parsed is None:
436
+ return None
437
+ if not reply_is_ours(data, dest_ip, ident, seq, check_ident=not _LINUX):
438
+ return None # another probe's reply; keep waiting for ours
439
+ icmp_type, icmp_code, _rest = parsed
440
+ responder = addr[0] if addr else None
441
+ rtt = _rtt_ms(ancdata, sent_ns, start)
442
+ if icmp_type == ICMP_ECHO_REPLY:
443
+ # The target's own answer, or not ours: on Linux the identifier isn't
444
+ # checked (the kernel rewrites it), so any host's echo reply carrying
445
+ # our sequence number was taken as the target reached, with that
446
+ # host's address as the target's (2026-11 review).
447
+ if responder is not None and responder != dest_ip:
448
+ return None
449
+ return PingResult(IP_SUCCESS, rtt, dest_ip, True)
450
+ if icmp_type == ICMP_TIME_EXCEEDED:
451
+ # The macOS path: the error arrives as an ordinary readable message
452
+ # rather than through an error queue.
453
+ return PingResult(IP_TTL_EXPIRED_TRANSIT, rtt, responder, False)
454
+ if icmp_type == ICMP_DEST_UNREACH:
455
+ return PingResult(_status_for(icmp_type, icmp_code), None, responder, False)
456
+ return None
@@ -0,0 +1,205 @@
1
+ """Questions asked of the history, for the History view and exports.
2
+
3
+ "Which route was slow?", "which router at hop 7 dropped probes on Tuesday?",
4
+ "what did the destination do while we were on the other path?" -- each is a
5
+ query over the per-minute summaries (kept a year by default) plus the route
6
+ segments, answered here as plain data. No Tk: the History page draws what
7
+ these return, the tests check them against hand-made histories, and an
8
+ export writes them out.
9
+
10
+ Loss at a hop in the middle of the path is usually that router ignoring
11
+ pings it has no reason to answer, not a fault: what matters is loss that
12
+ carries through to the destination. The numbers here are the measurements;
13
+ the page says which ones to trust.
14
+ """
15
+ from __future__ import annotations
16
+
17
+ import json
18
+ import math
19
+ from dataclasses import dataclass, field
20
+ from typing import Dict, List, Optional
21
+
22
+ from .history import Reader
23
+
24
+
25
+ @dataclass
26
+ class Point:
27
+ """One bucket of a time series."""
28
+ t: float # bucket start, epoch seconds
29
+ sent: int
30
+ recv: int
31
+ avg: Optional[float] # mean RTT of the replies, ms
32
+ rtt_min: Optional[float]
33
+ rtt_max: Optional[float]
34
+ jitter: Optional[float]
35
+
36
+ @property
37
+ def loss_pct(self) -> float:
38
+ return 100.0 * (self.sent - self.recv) / self.sent if self.sent else 0.0
39
+
40
+
41
+ @dataclass
42
+ class Router:
43
+ addr: str
44
+ recv: int
45
+ avg: Optional[float]
46
+ rtt_min: Optional[float]
47
+ rtt_max: Optional[float]
48
+ jitter: Optional[float]
49
+ name: Optional[str] = None # its DNS name, if it was resolved while recorded
50
+
51
+
52
+ @dataclass
53
+ class HopRow:
54
+ ttl: int
55
+ sent: int
56
+ recv: int
57
+ routers: List[Router] = field(default_factory=list) # busiest first
58
+
59
+ @property
60
+ def loss_pct(self) -> float:
61
+ return 100.0 * (self.sent - self.recv) / self.sent if self.sent else 0.0
62
+
63
+
64
+ @dataclass
65
+ class RouteRow:
66
+ id: int
67
+ hops: List[List[str]]
68
+ seconds: float # time on it within the range
69
+ share: float # of the range's recorded time, 0..1
70
+ first_seen: float
71
+ spans: List[tuple] # (start, end) within the range
72
+ dest_sent: int = 0
73
+ dest_recv: int = 0
74
+ dest_rtt_sum: float = 0.0
75
+
76
+ @property
77
+ def dest_avg(self) -> Optional[float]:
78
+ return self.dest_rtt_sum / self.dest_recv if self.dest_recv else None
79
+
80
+ @property
81
+ def dest_loss_pct(self) -> Optional[float]:
82
+ if not self.dest_sent:
83
+ return None
84
+ return 100.0 * (self.dest_sent - self.dest_recv) / self.dest_sent
85
+
86
+
87
+ def _point(t, sent, recv, rtt_sum, rtt_min, rtt_max, jit_sum, jit_n) -> Point:
88
+ return Point(t, sent, recv, rtt_sum / recv if recv else None, rtt_min, rtt_max,
89
+ jit_sum / jit_n if jit_n else None)
90
+
91
+
92
+ def series(reader: Reader, target: str, since: float, until: float,
93
+ buckets: int = 600, ttl: Optional[int] = None) -> List[Point]:
94
+ """One hop's latency and loss over the range, in at most ``buckets``
95
+ points. ``ttl`` None means the destination, whichever hop it was at the
96
+ time (the last hop probed in each minute, so a route that got longer or
97
+ shorter is followed)."""
98
+ db = reader._conn()
99
+ if db is None:
100
+ return []
101
+ lo, hi = int(since // 60), int(until // 60)
102
+ width = max(1, math.ceil((hi - lo + 1) / max(1, buckets)))
103
+ if ttl is None:
104
+ hop_filter = ("JOIN (SELECT m2.run, m2.minute, max(m2.ttl) AS ttl FROM minutes m2 "
105
+ "JOIN runs r2 ON r2.id = m2.run WHERE r2.target = ? AND m2.minute BETWEEN ? AND ? "
106
+ "GROUP BY m2.run, m2.minute) d ON d.run = m.run AND d.minute = m.minute "
107
+ "AND d.ttl = m.ttl")
108
+ args = [target, lo, hi]
109
+ else:
110
+ hop_filter, args = "", []
111
+ sql = (f"SELECT (m.minute - ?) / ? AS b, sum(m.sent), sum(m.recv), sum(m.rtt_sum), "
112
+ f"min(m.rtt_min), max(m.rtt_max), sum(m.jit_sum), sum(m.jit_n) "
113
+ f"FROM minutes m JOIN runs r ON r.id = m.run {hop_filter} "
114
+ f"WHERE r.target = ? AND m.minute BETWEEN ? AND ?"
115
+ f"{' AND m.ttl = ?' if ttl is not None else ''} GROUP BY b ORDER BY b")
116
+ params = [lo, width, *args, target, lo, hi] + ([ttl] if ttl is not None else [])
117
+ return [_point((lo + b * width) * 60.0, *rest) for b, *rest in db.execute(sql, params)]
118
+
119
+
120
+ def hops(reader: Reader, target: str, since: float, until: float) -> List[HopRow]:
121
+ """Every hop position in the range, with each router that answered there
122
+ and how it did. A hop whose router changed (a reroute, load balancing)
123
+ lists them all: the question "which router?" is answered here."""
124
+ db = reader._conn()
125
+ if db is None:
126
+ return []
127
+ rows = db.execute(
128
+ "SELECT m.ttl, a.addr, sum(m.sent), sum(m.recv), sum(m.rtt_sum), min(m.rtt_min), "
129
+ "max(m.rtt_max), sum(m.jit_sum), sum(m.jit_n), max(a.name) FROM minutes m "
130
+ "JOIN runs r ON r.id = m.run JOIN addrs a ON a.id = m.addr "
131
+ "WHERE r.target = ? AND m.minute BETWEEN ? AND ? GROUP BY m.ttl, a.addr ORDER BY m.ttl",
132
+ (target, int(since // 60), int(until // 60))).fetchall()
133
+ out: Dict[int, HopRow] = {}
134
+ for ttl, addr, sent, recv, rtt_sum, rmin, rmax, jsum, jn, name in rows:
135
+ hop = out.setdefault(ttl, HopRow(ttl, 0, 0))
136
+ hop.sent += sent
137
+ hop.recv += recv
138
+ if addr:
139
+ hop.routers.append(Router(addr, recv, rtt_sum / recv if recv else None, rmin, rmax,
140
+ jsum / jn if jn else None, name))
141
+ for hop in out.values():
142
+ hop.routers.sort(key=lambda r: -r.recv)
143
+ return [out[t] for t in sorted(out)]
144
+
145
+
146
+ ANCHOR_WINDOW = 3600.0 # seconds, at the end of a range: see named_routers
147
+
148
+
149
+ def named_routers(reader: Reader, since: float, until: float) -> List[tuple]:
150
+ """Every target's routers that had a name, as ``(name, best round
151
+ trip)``, over the last hour of the range: what locating.anchors checks
152
+ the IP database's answers against. An hour, because a week of every
153
+ target's minutes is millions of rows, and the anchors that matter are
154
+ the quick ones near this computer, seen in any hour."""
155
+ db = reader._conn()
156
+ if db is None:
157
+ return []
158
+ lo = int(max(since, until - ANCHOR_WINDOW) // 60)
159
+ return [tuple(r) for r in db.execute(
160
+ "SELECT max(a.name), min(m.rtt_min) FROM minutes m JOIN addrs a ON a.id = m.addr "
161
+ "WHERE m.minute BETWEEN ? AND ? AND m.rtt_min IS NOT NULL AND a.name IS NOT NULL "
162
+ "AND a.name != '' GROUP BY m.addr", (lo, int(until // 60)))]
163
+
164
+
165
+ def routes(reader: Reader, target: str, since: float, until: float,
166
+ now: Optional[float] = None) -> List[RouteRow]:
167
+ """Each route the target was on within the range: how long, what share,
168
+ and how the destination did meanwhile, so a bad path stands out."""
169
+ import time as _time
170
+ now = _time.time() if now is None else now
171
+ stored = {r["id"]: r for r in reader.routes(target)}
172
+ rows: Dict[int, RouteRow] = {}
173
+ for seg in reader.segments(target, since, until):
174
+ start = max(since, seg["start"])
175
+ end = min(until, seg["end"] if seg["end"] is not None else now)
176
+ if end <= start or seg["route"] not in stored:
177
+ continue
178
+ r = stored[seg["route"]]
179
+ row = rows.get(seg["route"])
180
+ if row is None:
181
+ row = rows[seg["route"]] = RouteRow(seg["route"], json.loads(r["hops"]), 0.0, 0.0,
182
+ r["first"], [])
183
+ row.seconds += end - start
184
+ row.spans.append((start, end))
185
+ total = sum(r.seconds for r in rows.values())
186
+ for row in rows.values():
187
+ row.share = row.seconds / total if total else 0.0
188
+ if rows:
189
+ # The destination, minute by minute, credited to the route in use.
190
+ for p in series(reader, target, since, until, buckets=10 ** 6):
191
+ mid = p.t + 30
192
+ for row in rows.values():
193
+ if any(a <= mid < b for a, b in row.spans):
194
+ row.dest_sent += p.sent
195
+ row.dest_recv += p.recv
196
+ row.dest_rtt_sum += (p.avg or 0.0) * p.recv
197
+ break
198
+ return sorted(rows.values(), key=lambda r: r.spans[0][0])
199
+
200
+
201
+ def describe_route(hops_: List[List[str]], names: Optional[Dict[str, str]] = None) -> str:
202
+ """A route on one line: routers in hop order, "/" between load-balanced
203
+ ones, "*" for a hop that never answered."""
204
+ names = names or {}
205
+ return " > ".join(" / ".join(names.get(a, a) for a in hop) or "*" for hop in hops_)