Files
gandalf/modem.py
jaredandClaude Opus 5.5 3afd85626b
Lint / JS (eslint) (push) Successful in 8s
Lint / Python (flake8) (push) Successful in 1m2s
Lint / Notify on failure (push) Skipped
Lint / Deploy (push) Skipped
Security / Python Security (bandit) (push) Successful in 1m3s
Lint / Python (flake8) (pull_request) Successful in 2m7s
Test / Python Tests (pytest) (push) Successful in 2m20s
Lint / JS (eslint) (pull_request) Successful in 15s
Lint / Notify on failure (pull_request) Skipped
Lint / Deploy (pull_request) Skipped
Security / Python Security (bandit) (pull_request) Successful in 57s
Test / Python Tests (pytest) (pull_request) Successful in 1m28s
Modem restart: load restarting.ha, which is what starts it
Tried on the real BGW320 (firmware 6.40.4): posting the Restart form only
answers 302 to /cgi-bin/restarting.ha, and the modem keeps running (its
uptime carried on). Loading that page, as a browser does, starts the
restart ("restarting ... approximately 155 seconds"). restart() now
follows the redirect and only reports 'accepted' when that page says it
is restarting.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 20:34:50 -05:00

604 lines
27 KiB
Python

"""Client for AT&T BGW-series fiber gateways (tested on BGW320-505).
The gateway has no API, but its status pages are served without a login, so
ModemClient scrapes them over HTTP with GET requests only: it cannot change
anything on the gateway.
With an access code configured, ModemAdmin (at the end) also logs in to read the
NAT session counts, the firewall log and speed test history, and to run the
Troubleshoot page's ping from the gateway. None of that changes a setting. Its
restart() is the one call that does something to the gateway, and it runs only
when an admin presses Restart modem.
Units come from the gateway's own help text, checked against live readings:
Rx/Tx power tenths of a dBm (-169 -> -16.9 dBm)
Temperature degrees C
Uptime D:HH:MM:SS on firmware 6.40 (older firmware sent plain seconds;
both are accepted)
Deliberately not used, because the page disagrees with itself:
Vcc / Tx Bias readings values do not match the documented scales, so only
their alarm/warning flags are kept
Rx LOS State reads 1 on a healthy link; "Optical WAN Operational
Status" is the reliable signal
Last Change does not count up, despite the help text
"""
import hashlib
import html
import logging
import re
import time
from datetime import datetime, timezone
from typing import Dict, List, Optional
import requests
logger = logging.getLogger('gandalf.modem')
_FIBER_PAGE = '/cgi-bin/fiberstat.ha'
_BROADBAND_PAGE = '/cgi-bin/broadbandstatistics.ha'
_SYSINFO_PAGE = '/cgi-bin/sysinfo.ha'
_ROW_RE = re.compile(r'<th\b[^>]*>(.*?)</th>\s*<td\b[^>]*>(.*?)</td>', re.I | re.S)
_TAG_RE = re.compile(r'<[^>]+>')
# e.g. "0 (Threshold -292)": alarm flag, then the limit
_DOM_CELL_RE = re.compile(r'<td\b[^>]*>\s*(\d+)\s*\(Threshold\s+(-?\d+)\)\s*</td>', re.I)
# Page heading -> (result key, scale to real units; None = reading is unusable)
_DOM_METRICS = {
'Temperature': ('temperature', 1.0),
'Vcc': ('vcc', None),
'Tx Bias': ('tx_bias', None),
'Tx Power': ('tx_power', 0.1),
'Rx Power': ('rx_power', 0.1),
}
_COUNTERS = {
'rx_bytes': 'Receive Bytes',
'tx_bytes': 'Transmit Bytes',
'rx_errors': 'Receive Errors',
'tx_errors': 'Transmit Errors',
'rx_drops': 'Receive Drops',
'tx_drops': 'Transmit Drops',
}
class ModemUnreachable(Exception):
"""The gateway did not answer (power, cabling, or routing problem)."""
class ModemDataInvalid(Exception):
"""The gateway answered but the page was not what we can parse.
AT&T pushes firmware automatically, so this is how a layout change or a
newly login-protected page shows up.
"""
def parse_rows(page: str) -> Dict[str, str]:
"""Return {label: value} for the page's <th>/<td> rows; the first label wins.
First wins because labels repeat: "Transmit Packets" appears under both
IPv4 and IPv6, and the IPv4 block comes first.
"""
rows: Dict[str, str] = {}
for label, value in _ROW_RE.findall(page):
key = html.unescape(_TAG_RE.sub('', label)).strip()
if key:
rows.setdefault(key, ' '.join(html.unescape(_TAG_RE.sub('', value)).split()))
return rows
def parse_dom_metrics(page: str) -> Dict[str, dict]:
"""Parse the fiber page's Temperature / Vcc / Tx Bias / Tx Power / Rx Power tables."""
metrics: Dict[str, dict] = {}
for heading, (key, scale) in _DOM_METRICS.items():
m = re.search(
rf'<h1>\s*{re.escape(heading)}(?:&nbsp;|\s)+Currently\s+(-?\d+)\s*</h1>(.*?)</table>',
page, re.I | re.S,
)
if not m:
continue
cells = _DOM_CELL_RE.findall(m.group(2))
if len(cells) != 4: # alarm low, alarm high, warning low, warning high
continue
def limit(raw: str, scale: Optional[float] = scale) -> Optional[float]:
return round(int(raw) * scale, 1) if scale is not None else None
metrics[key] = {
'value': limit(m.group(1)),
'alarm_low': limit(cells[0][1]),
'alarm_high': limit(cells[1][1]),
'warn_low': limit(cells[2][1]),
'warn_high': limit(cells[3][1]),
'alarm_flag': cells[0][0] != '0' or cells[1][0] != '0',
'warn_flag': cells[2][0] != '0' or cells[3][0] != '0',
}
return metrics
def metric_status(metric: dict) -> str:
"""Classify a DOM metric as 'alarm', 'warning', or 'ok'.
Trusts the module's own flags, and also compares the reading to its limits
in case the flags are latched off.
"""
value = metric.get('value')
def outside(low: Optional[float], high: Optional[float]) -> bool:
if value is None:
return False
return (low is not None and value <= low) or (high is not None and value >= high)
if metric.get('alarm_flag') or outside(metric.get('alarm_low'), metric.get('alarm_high')):
return 'alarm'
if metric.get('warn_flag') or outside(metric.get('warn_low'), metric.get('warn_high')):
return 'warning'
return 'ok'
def _to_int(raw: Optional[str]) -> Optional[int]:
try:
return int(raw) # type: ignore[arg-type]
except (TypeError, ValueError):
return None
def parse_uptime(raw: Optional[str]) -> Optional[int]:
"""Seconds since the gateway restarted, from 'D:HH:MM:SS' (e.g. 03:06:29:34) or plain seconds."""
raw = (raw or '').strip()
if re.fullmatch(r'\d+', raw):
return int(raw)
m = re.fullmatch(r'(\d+):(\d{1,2}):(\d{1,2}):(\d{1,2})', raw)
if not m:
return None
d, h, mi, sec = (int(x) for x in m.groups())
return ((d * 24 + h) * 60 + mi) * 60 + sec
def wan_problems(data: dict) -> List[str]:
"""Return human-readable reasons the WAN is down; empty when it looks healthy."""
problems = []
if (data.get('broadband_state') or '').lower() != 'up':
problems.append(f'broadband connection is {data.get("broadband_state") or "unknown"}')
if (data.get('optical_state') or '').lower() != 'up':
problems.append(f'optical WAN is {data.get("optical_state") or "unknown"}')
pon = data.get('pon_state')
if pon and 'O5' not in pon: # O5 is the PON "operation" state; older firmware may omit the field
problems.append(f'PON link state is {pon}')
return problems
def build_status(fiber_page: str, broadband_page: str, sysinfo_page: str = '') -> dict:
"""Combine the status pages into one dict. Raises ModemDataInvalid if unusable."""
fiber = parse_rows(fiber_page)
broadband = parse_rows(broadband_page)
sysinfo = parse_rows(sysinfo_page)
if 'Optical WAN Operational Status' not in fiber:
raise ModemDataInvalid('fiber page is missing "Optical WAN Operational Status"')
if 'Broadband Connection' not in broadband:
raise ModemDataInvalid('broadband page is missing "Broadband Connection"')
metrics = parse_dom_metrics(fiber_page)
data = {
'model': sysinfo.get('Model Number', ''),
'firmware': sysinfo.get('Software Version', ''),
'uptime_s': parse_uptime(sysinfo.get('Time Since Last Reboot')),
'broadband_state': broadband.get('Broadband Connection', ''),
'source': broadband.get('Broadband Connection Source', ''),
'wan_ip': broadband.get('Broadband IPv4 Address', ''),
'pon_state': broadband.get('PON Link Status', ''),
'uni_state': broadband.get('UNI Status', ''),
'line_speed_mbps': _to_int(broadband.get('Current Speed (Mbps)')),
'optical_state': fiber.get('Optical WAN Operational Status', ''),
'wavelength': fiber.get('Wave Length', ''),
'optics_part_no': fiber.get('Vendor PN', ''),
'optics': metrics,
'counters': {k: _to_int(broadband.get(label)) for k, label in _COUNTERS.items()},
}
# With a healthy link the optics must be readable; if not, the layout changed.
# With a cut fiber they may legitimately be blank, so don't report that as invalid.
if not wan_problems(data) and 'rx_power' not in metrics:
raise ModemDataInvalid('link is up but no Rx power reading was found')
return data
def counter_rates(current: dict, previous: Optional[dict], elapsed_s: float) -> Dict[str, Optional[float]]:
"""Return per-second rates between counter snapshots.
A rate is None rather than a bogus value on the first poll, or when a counter
goes backwards because the gateway rebooted.
"""
rates: Dict[str, Optional[float]] = {}
for key, now_val in current.items():
then = (previous or {}).get(key)
if now_val is None or then is None or elapsed_s <= 0 or now_val < then:
rates[key] = None
else:
rates[key] = (now_val - then) / elapsed_s
return rates
class ModemClient:
def __init__(self, cfg: dict):
self.base_url = cfg['url'].rstrip('/')
self.timeout = cfg.get('timeout', 10)
self.session = requests.Session()
def _get(self, path: str) -> str:
try:
# Protected pages redirect or render a login form, so never follow redirects.
resp = self.session.get(f'{self.base_url}{path}', timeout=self.timeout, allow_redirects=False)
except requests.RequestException as e:
raise ModemUnreachable(f'{path}: {e}') from e
if resp.status_code != 200:
raise ModemDataInvalid(f'{path} returned HTTP {resp.status_code}')
if re.search(r'<title>\s*Login', resp.text, re.I):
raise ModemDataInvalid(f'{path} now requires a login')
return resp.text
def poll(self) -> dict:
"""Return gateway status. Raises ModemUnreachable or ModemDataInvalid."""
fiber = self._get(_FIBER_PAGE)
broadband = self._get(_BROADBAND_PAGE)
try:
sysinfo = self._get(_SYSINFO_PAGE)
except (ModemUnreachable, ModemDataInvalid) as e:
# Model and uptime are nice to have, not worth failing the poll over.
logger.warning(f'Modem system info unavailable: {e}')
sysinfo = ''
data = build_status(fiber, broadband, sysinfo)
data['updated'] = datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M:%S UTC')
return data
# ---------------------------------------------------------------------------
# WAN history: outages and gateway restarts, which are too brief to catch by polling
# ---------------------------------------------------------------------------
LOG_WAN_FAILED = 'NETWORK_WAN_FAILED_2'
LOG_WAN_RESTORED = 'NETWORK_WAN_RESTORED_2'
LOG_WAN_UNSTABLE = 'NETWORK_WAN_FAILED_MULTIPLE_TIMES_2'
LOG_MODEM_RESTARTED = 'SMART_POWER_MODEM_RESTARTED'
WAN_LOG_KEYS = (LOG_WAN_FAILED, LOG_WAN_RESTORED, LOG_WAN_UNSTABLE, LOG_MODEM_RESTARTED)
# An app or firmware update finishing. The UDM often drops its WAN while the Network app
# updates, and Smart Power may then power-cycle a modem that was fine.
LOG_NETWORK_UPDATED = 'NETWORK_UPDATED'
LOG_FIRMWARE_UPDATED = 'FIRMWARE_UPDATED_V2'
_UPDATE_KEY_RE = re.compile(r'[A-Z_]+_(?:UPDATED|UPGRADED)(?:_V\d+)?')
def is_update_key(key: str) -> bool:
"""True for log keys that mean an update finished (other app names follow the same pattern)."""
return key in (LOG_NETWORK_UPDATED, LOG_FIRMWARE_UPDATED) or (
bool(_UPDATE_KEY_RE.fullmatch(key or '')) and 'AVAILABLE' not in key
and not key.startswith('MADE_CHANGES'))
def wanted_log_key(key: str) -> bool:
return key in WAN_LOG_KEYS or is_update_key(key)
def update_label(event: dict) -> str:
"""'UniFi Network 11.0.97 to 11.0.99' from an update log event."""
what = event.get('app') or event.get('device') or 'UniFi'
before, after = event.get('previous') or '', event.get('version') or ''
if before and after:
return f'{what} {before} to {after}'
return f'{what} {after}'.strip()
_HISTORY_LIMIT = 50
# The RPDU's log entry and the gateway's calculated boot time can differ by this much.
_RESTART_MATCH_WINDOW_S = 600
def apply_wan_events(history: dict, events: List[dict]) -> List[dict]:
"""Fold UniFi log events into *history* in place and return the ones worth a ticket.
Each event is {'key', 'ts' (epoch seconds), 'device', 'wan'}.
"""
outages = history.setdefault('outages', [])
restarts = history.setdefault('restarts', [])
actionable = []
for e in sorted(events, key=lambda ev: ev['ts']):
key = e['key']
if key == LOG_WAN_FAILED:
if not any(o.get('restored_at') is None for o in outages):
outages.append({'failed_at': e['ts'], 'restored_at': None, 'wan': e.get('wan', '')})
elif key == LOG_WAN_RESTORED:
for o in reversed(outages):
if o.get('restored_at') is None:
o['restored_at'] = e['ts']
break
elif key == LOG_MODEM_RESTARTED:
restarts.append({'at': e['ts'], 'by': e.get('device') or 'smart power', 'confirmed': False})
actionable.append(e)
elif key == LOG_WAN_UNSTABLE:
actionable.append(e)
del outages[:-_HISTORY_LIMIT]
del restarts[:-_HISTORY_LIMIT]
return actionable
def record_uptime_reset(history: dict, boot_ts: float) -> None:
"""Note that the gateway's uptime went backwards, attributing it to a logged restart if possible."""
restarts = history.setdefault('restarts', [])
for r in reversed(restarts):
if abs(r['at'] - boot_ts) <= _RESTART_MATCH_WINDOW_S:
r['confirmed'] = True
return
restarts.append({'at': boot_ts, 'by': None, 'confirmed': True})
del restarts[:-_HISTORY_LIMIT]
# ---------------------------------------------------------------------------
# WAN quality: UniFi's own 5 minute health timeline (high latency, packet loss, down),
# the same data its Network app charts. Read only; Gandalf doesn't measure it again.
# ---------------------------------------------------------------------------
QUALITY_STATES = ('ok', 'latency', 'loss', 'down') # mildest to worst
QUALITY_PERIOD_S = 300
def wan_quality(dashboard: dict, now: float) -> Optional[dict]:
"""The primary WAN's health timeline from UniFi's aggregated dashboard, or None.
Returns {'wan', 'periods': [{'ts', 'state'}], 'downtime': [{'ts', 'seconds'}],
'latencies': {service: ms}, 'updated'}. Each period is 5 minutes; its state is the
worst flag UniFi set for it.
"""
details = ((dashboard or {}).get('wan_history') or {}).get('wan_history_details') or []
if not details:
return None
primary = next((d for d in details if d.get('network_group') == 'WAN'), details[0])
periods = []
for h in primary.get('health_history') or []:
if not isinstance(h.get('timestamp'), (int, float)):
continue
state = ('down' if h.get('wan_downtime') else 'loss' if h.get('packet_loss')
else 'latency' if h.get('high_latency') else 'ok')
periods.append({'ts': h['timestamp'] / 1000, 'state': state})
periods.sort(key=lambda p: p['ts'])
downtime = sorted(
({'ts': d['timestamp'] / 1000, 'seconds': d.get('downtime_in_seconds') or 0}
for d in primary.get('downtime_history') or [] if isinstance(d.get('timestamp'), (int, float))),
key=lambda d: d['ts'])
latencies = {}
for w in ((dashboard.get('wan') or {}).get('wan_details') or []):
if w.get('network_group') == primary.get('network_group'):
for s in (w.get('stats') or {}).get('service_latencies') or []:
if s.get('service_name') and isinstance(s.get('latency'), (int, float)):
latencies[s['service_name']] = s['latency']
return {'wan': primary.get('network_group') or '', 'periods': periods, 'downtime': downtime,
'latencies': latencies, 'updated': now}
def quality_counts(periods: List[dict], since: float) -> Dict[str, int]:
"""How many periods starting at or after *since* were in each state."""
counts = {s: 0 for s in QUALITY_STATES}
for p in periods:
if p['ts'] >= since and p['state'] in counts:
counts[p['state']] += 1
return counts
# ---------------------------------------------------------------------------
# Logged-in checks, used only when an access code is configured. Two pages are
# read: the NAT table's session counts, and the Troubleshoot page's ping test,
# which runs a ping from the gateway itself. Neither changes any setting.
# ---------------------------------------------------------------------------
_LOGIN_PAGE = '/cgi-bin/login.ha'
_NAT_PAGE = '/cgi-bin/nattable.ha'
_DIAG_PAGE = '/cgi-bin/diag.ha'
_LOGS_PAGE = '/cgi-bin/logs.ha'
_SPEED_PAGE = '/cgi-bin/speed.ha'
_RESTART_PAGE = '/cgi-bin/restart.ha'
_RESTARTING_PAGE = '/cgi-bin/restarting.ha'
# Firewall log row: number, ISO time (gateway's local clock), source, destination, protocol, reason
_FW_ROW_RE = re.compile(r'<tr[^>]*>\s*<td[^>]*>\s*\d+\s*</td>\s*<td>\s*([^<]+?)\s*</td>\s*<td>\s*([^<]*?)\s*</td>'
r'\s*<td>\s*([^<]*?)\s*</td>\s*<td>\s*([^<]*?)\s*</td>\s*<td>\s*([^<]*?)\s*</td>\s*</tr>', re.I)
_CELL_RE = re.compile(r'<td\b[^>]*>(.*?)</td>', re.I | re.S)
_NONCE_RE = re.compile(r'name="nonce"\s+value="([0-9a-f]+)"', re.I)
_PROGRESS_RE = re.compile(r'<textarea[^>]*name="ProgressWindow"[^>]*>(.*?)</textarea>', re.I | re.S)
_PING_STATS_RE = re.compile(r'(\d+) packets transmitted, (\d+) (?:packets )?received')
_PING_RTT_RE = re.compile(r'min/avg/max\S* = ([\d.]+)/([\d.]+)/([\d.]+)')
# After a failed login, leave the gateway alone for this long (it may lock the account)
LOGIN_BACKOFF_S = 1800
class ModemLoginFailed(Exception):
"""The access code was refused, or the login page wasn't what we expect."""
def login_hash(code: str, nonce: str) -> str:
"""What the login page's script posts: md5 of the access code followed by the nonce."""
# The gateway's login protocol dictates md5; it isn't used to protect anything here
return hashlib.md5((code + nonce).encode(), usedforsecurity=False).hexdigest() # nosec B303 B324
def is_login_page(page: str) -> bool:
return 'Access Code Required' in page or bool(re.search(r'<title>\s*Login', page, re.I))
def parse_nat_summary(page: str) -> Optional[Dict[str, int]]:
"""{'in_use', 'available'} from the NAT table page, or None if the counts are missing."""
rows = {_TAG_RE.sub('', k).strip(): _TAG_RE.sub('', v).strip() for k, v in _ROW_RE.findall(page)}
try:
return {'in_use': int(rows['Total sessions in use']),
'available': int(rows['Total sessions available'])}
except (KeyError, ValueError):
return None
def parse_ping_output(text: str) -> Optional[dict]:
"""{'sent', 'received', 'loss_pct', 'min_ms', 'avg_ms', 'max_ms'} from busybox ping output,
or None until the test has finished. Times are None when every packet was lost."""
stats = _PING_STATS_RE.search(text or '')
if not stats:
return None
sent, received = int(stats.group(1)), int(stats.group(2))
rtt = _PING_RTT_RE.search(text)
lo, avg, hi = (float(x) for x in rtt.groups()) if rtt else (None, None, None)
return {'sent': sent, 'received': received,
'loss_pct': round(100 * (sent - received) / sent) if sent else 100,
'min_ms': lo, 'avg_ms': avg, 'max_ms': hi}
def parse_firewall_log(page: str) -> List[dict]:
"""Rows of the gateway's firewall log (Logs page): {'ts', 'src', 'dst', 'proto', 'reason'}.
'ts' is the gateway's local time as ISO text, so rows sort by it."""
rows = [dict(zip(('ts', 'src', 'dst', 'proto', 'reason'), m.groups())) for m in _FW_ROW_RE.finditer(page)]
return sorted((r for r in rows if re.match(r'\d{4}-\d\d-\d\dT', r['ts'])), key=lambda r: r['ts'])
def firewall_kind(reason: str) -> str:
"""'flood' (new connections over the gateway's fixed rate limit), 'invalid', or 'other'."""
reason = reason.lower()
return 'flood' if 'flood' in reason else 'invalid' if 'invalid' in reason else 'other'
def parse_speed_tests(page: str) -> List[dict]:
"""The gateway's own speed test history, newest first:
{'at' (as the page shows it), 'direction', 'mbps', 'latency_ms', 'ok'}."""
i = page.find('Test History')
out = []
for row in re.findall(r'<tr\b[^>]*>(.*?)</tr>', page[i:] if i >= 0 else '', re.I | re.S):
cells = [_TAG_RE.sub('', c).strip() for c in _CELL_RE.findall(row)]
if len(cells) < 6 or cells[1] not in ('upstream', 'downstream'):
continue
try:
out.append({'at': cells[0], 'direction': cells[1], 'mbps': round(float(cells[2]), 1),
'latency_ms': round(float(cells[4]), 1), 'ok': cells[5].lower() == 'success'})
except ValueError:
continue
return out
class ModemAdmin:
"""Logged-in session on the gateway, kept between checks and renewed when it expires.
Logs in at most once per call, and not at all for LOGIN_BACKOFF_S after a refusal.
Raises ModemUnreachable, ModemDataInvalid or ModemLoginFailed.
"""
def __init__(self, cfg: dict, clock=None, sleep=None):
self.base_url = cfg['url'].rstrip('/')
self._code = cfg['access_code']
self.timeout = cfg.get('timeout', 10)
self.session = requests.Session()
self._clock = clock or time.time
self._sleep = sleep or time.sleep
self.login_failed_at: Optional[float] = None
def _request(self, method: str, path: str, timeout: Optional[float] = None, **kw) -> requests.Response:
try:
return self.session.request(method, f'{self.base_url}{path}', allow_redirects=False,
timeout=timeout or self.timeout, **kw)
except requests.RequestException as e:
raise ModemUnreachable(f'{path}: {e}') from e
def _login(self) -> None:
if self.login_failed_at and self._clock() - self.login_failed_at < LOGIN_BACKOFF_S:
raise ModemLoginFailed('waiting after a refused login')
page = self._request('GET', _LOGIN_PAGE).text
nonce = _NONCE_RE.search(page)
if not nonce: # the first visit only sets the session cookie
nonce = _NONCE_RE.search(self._request('GET', _LOGIN_PAGE).text)
if not nonce:
raise ModemDataInvalid('login page has no nonce')
resp = self._request('POST', _LOGIN_PAGE, data={
'nonce': nonce.group(1), 'password': '*' * len(self._code), 'Continue': 'Continue',
'hashpassword': login_hash(self._code, nonce.group(1)),
})
if resp.status_code != 302 or is_login_page(resp.text):
self.login_failed_at = self._clock()
raise ModemLoginFailed('the gateway refused the access code')
self.login_failed_at = None
def _page(self, path: str, timeout: Optional[float] = None) -> str:
"""A protected page, logging in first if the session has expired."""
resp = self._request('GET', path, timeout)
if resp.status_code != 200 or is_login_page(resp.text):
self._login()
resp = self._request('GET', path, timeout)
if resp.status_code != 200 or is_login_page(resp.text):
raise ModemDataInvalid(f'{path} returned HTTP {resp.status_code} after logging in')
return resp.text
def nat_sessions(self) -> Dict[str, int]:
# The page lists every session too, so it can be large (hundreds of KB)
counts = parse_nat_summary(self._page(_NAT_PAGE, timeout=max(self.timeout, 30)))
if counts is None:
raise ModemDataInvalid('NAT table page has no session counts')
return counts
def firewall_log(self) -> List[dict]:
return parse_firewall_log(self._page(_LOGS_PAGE))
def speed_tests(self) -> List[dict]:
return parse_speed_tests(self._page(_SPEED_PAGE))
def restart(self) -> str:
"""Restart the gateway from its Restart Device page: the one change this client makes,
and only when an admin asks.
Two steps, as in a browser: posting the form only answers with a redirect to
restarting.ha, and loading that page is what starts the restart (firmware 6.40; a
post alone leaves the gateway running). Returns 'accepted' once that page says it is
restarting, or 'unconfirmed' when the gateway dropped the connection first.
"""
nonce = _NONCE_RE.search(self._page(_RESTART_PAGE))
if not nonce:
raise ModemDataInvalid('Restart page has no nonce')
timeout = max(self.timeout, 30)
try:
resp = self.session.post(f'{self.base_url}{_RESTART_PAGE}', allow_redirects=False,
timeout=timeout, data={'nonce': nonce.group(1), 'Restart': 'Restart'})
if resp.status_code == 302 and _RESTARTING_PAGE in (resp.headers.get('Location') or ''):
resp = self.session.get(f'{self.base_url}{_RESTARTING_PAGE}', allow_redirects=False,
timeout=timeout)
except (requests.ConnectionError, requests.Timeout):
return 'unconfirmed'
if resp.status_code != 200 or is_login_page(resp.text) or 'restarting' not in resp.text.lower():
raise ModemDataInvalid(f'Restart was not started (HTTP {resp.status_code})')
return 'accepted'
def ping(self, target: str, wait_s: float = 30) -> dict:
"""Ping *target* from the gateway (its Troubleshoot page; 5 packets) and return the result."""
nonce = _NONCE_RE.search(self._page(_DIAG_PAGE))
if not nonce:
raise ModemDataInvalid('Troubleshoot page has no nonce')
resp = self._request('POST', _DIAG_PAGE, timeout=max(self.timeout, 30), data={
'nonce': nonce.group(1), 'WebAddress': target, 'protopref': 'IPv4', 'Ping': 'Ping'})
deadline = self._clock() + wait_s
page = resp.text
while True:
window = _PROGRESS_RE.search(page)
result = parse_ping_output(html.unescape(window.group(1)) if window else '')
if result is not None:
return dict(result, target=target)
if self._clock() >= deadline:
raise ModemDataInvalid(f'ping to {target} from the gateway did not finish')
self._sleep(3)
page = self._page(_DIAG_PAGE)
SLOW_MS = 150 # a ping slower than this, on a link that normally answers in ~15 ms, is "slow"
def ping_verdict(gateway: dict, ours_ms: Optional[float]) -> str:
"""Where the delay is, from the gateway's own ping and ours through it at the same time.
'upstream': the gateway's ping is slow or lossy too, so it's past the gateway (the ISP).
'gateway': the gateway's ping is fine but ours through it is slow, so the delay is in
the gateway or between it and the router.
'clear': both fine; the slow spell had passed by the time of the test.
"""
avg = gateway.get('avg_ms')
if avg is None or avg >= SLOW_MS or (gateway.get('loss_pct') or 0) >= 20:
return 'upstream'
if ours_ms is not None and ours_ms >= SLOW_MS:
return 'gateway'
return 'clear'