wrolpi/wrolpi/speedtest.py
lrnselfreliance 91f92683ba
Speed Test calculator: ping, download, and upload against the API (#708)
* Speed Test calculator: ping, download, and upload against the API

Users asking whether the hotspot is fast enough, or how many people can
stream video at once, had no objective tool that works offline.  This
adds one under Calculators > Tools & Reference.

Backend (wrolpi/speedtest.py, /api/speedtest):
* ping: tiny no-store JSON the browser times for round trip latency.
* download: streams slices of a pre-built random buffer for a clamped
  number of seconds (0.1-15).  Random so no proxy or compression can
  flatter the result; slices so no bytes are generated per request.
* upload: streaming-body handler that reads and discards the body and
  reports bytes and elapsed time.  Requests over 8 MiB are refused.
* info: the client address Caddy forwarded plus how many tests are in
  flight.  Sanic now trusts one proxy hop (PROXIES_COUNT = 1) so
  request.remote_addr is the browser, not Caddy.  Nothing else read
  that field before.

There is deliberately no one-test-at-a-time lock.  Several people
testing at once is how a user learns how the link shares between
streamers, so the server only counts in-flight tests (a shared_ctx
Value created pre-fork so every worker sees the same number) and the
UI reports how many others ran alongside.

Both Caddyfiles route /api/speedtest/* unbuffered, as the SSE chat
route already is, so throughput is measured live rather than in bursts.

Frontend:
* speedtest.js holds the logic with no React in it (bucketed
  throughput, steady-state average that drops the first second, ping
  stats, stream-capacity tiers, hotspot address check) so Jest drives
  it with fake fetch and streams.
* SpeedTestCalculator runs 20 pings, a 10 s download, and a 10 s upload
  with a live figure and rolling trace, then shows Mbps and MB/s, ping
  verdict, the client address with a hotspot badge, and a table of how
  many 480p..4K streams the download speed supports.  Upload is
  sequential POSTs of one 4 MiB Blob because Safari cannot stream a
  request body.  Nothing is saved.
* Sparkline is a new inline-SVG ui component (no chart dependency),
  added to /theme-sample and checked in all four themes.  A missing
  sample is a gap, not a plunge to zero.

The page states that it measures the network path, not the drive that
actually serves video files.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* speedtest: bound uploads in time, close the Start race, address review

Review on #708 found three bugs and some polish:

* Start could be clicked again while the first fetchInfo() was still
  pending, because the phase only left `idle` after that await.  A
  second click made a second AbortController and a second concurrent
  run, and Cancel only reached the later one.  start() now refuses when
  a controller already exists and enters a `starting` phase
  synchronously, so the button is Cancel before the first await.

* The upload phase could overrun the advertised 10 s by however long
  the in-flight 4 MiB POST took: on a slow hotspot, the very link this
  tool exists for, that is tens of seconds.  runUpload() now aborts the
  in-flight request at the phase deadline (counting only completed
  requests) and uses 1 MiB bodies so a few-Mbps link still completes
  several inside the phase.

* The server upload sink was capped by size only, so a slow or paused
  body could hold a worker until 8 MiB eventually arrived.  It now also
  enforces MAX_UPLOAD_SECONDS (15 s, matching download) and answers
  408 when exceeded.  Both caps together are what "cannot hold a
  worker" actually requires.

Also: a NaN `seconds` now gets a NaN message instead of "must not be
negative"; the module, Sparkline, and gallery docstrings are trimmed
to purpose; and the upload counter is covered for the mid-stream 413,
the 408, and a broken body.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-13 18:47:18 -06:00

173 lines
5.9 KiB
Python

"""Speed test endpoints: ping, a bounded download stream, a bounded upload sink, and context.
Nothing is stored. Several clients may test at once; the server only counts tests in flight.
"""
import os
import time
from http import HTTPStatus
from typing import Iterator, Optional
from sanic import Blueprint
from sanic.request import Request
from sanic_ext.extensions.openapi import openapi
from wrolpi.api_utils import json_response, api_app
from wrolpi.common import logger
from wrolpi.errors import ValidationError, APIError
logger = logger.getChild(__name__)
speedtest_bp = Blueprint('SpeedTest', url_prefix='/api/speedtest')
# Bounds on how long a download stream may hold a worker.
MIN_DOWNLOAD_SECONDS = 0.1
DEFAULT_DOWNLOAD_SECONDS = 10.0
MAX_DOWNLOAD_SECONDS = 15.0
# Bytes sent per `await response.send()`. Large enough that Python overhead does not cap a fast
# LAN, small enough that the loop yields often.
CHUNK_SIZE = 256 * 1024
# The browser uploads in sequential POSTs of a few MiB. Both caps exist so a request cannot hold a
# worker: size alone does not, a slow or paused body could trickle in for minutes.
MAX_UPLOAD_CHUNK = 8 * 1024 * 1024
MAX_UPLOAD_SECONDS = 15.0
# One random buffer built at import; chunks are slices of it so no bytes are generated per
# request. Random so no proxy or compression can flatter the result. A whole multiple of
# CHUNK_SIZE so every slice is a full chunk.
_RANDOM = os.urandom(CHUNK_SIZE * 16)
NO_STORE_HEADERS = {
'Cache-Control': 'no-store',
# Ask proxies not to buffer the stream.
'X-Accel-Buffering': 'no',
}
class UploadTooLarge(APIError):
code = 'UPLOAD_TOO_LARGE'
summary = f'Speed test upload requests are limited to {MAX_UPLOAD_CHUNK} bytes'
status_code = HTTPStatus.REQUEST_ENTITY_TOO_LARGE
class UploadTooSlow(APIError):
code = 'UPLOAD_TOO_SLOW'
summary = f'Speed test upload requests must finish within {MAX_UPLOAD_SECONDS} seconds'
status_code = HTTPStatus.REQUEST_TIMEOUT
def clamp_seconds(value: Optional[str]) -> float:
"""Parse the requested download duration and keep it within the server's bounds."""
if value is None or value == '':
return DEFAULT_DOWNLOAD_SECONDS
try:
seconds = float(value)
except (TypeError, ValueError):
raise ValidationError(f'seconds must be a number, got {value!r}')
if seconds != seconds: # NaN
raise ValidationError('seconds must be a number, got NaN')
if seconds < 0:
raise ValidationError('seconds must not be negative')
return max(MIN_DOWNLOAD_SECONDS, min(seconds, MAX_DOWNLOAD_SECONDS))
def iter_chunks() -> Iterator[bytes]:
"""Yield full CHUNK_SIZE slices of the random buffer forever, wrapping around."""
offset = 0
while True:
yield _RANDOM[offset:offset + CHUNK_SIZE]
offset = (offset + CHUNK_SIZE) % len(_RANDOM)
def _counter():
"""The cross-worker count of speed tests in flight (created pre-fork in wrolpi.contexts)."""
return api_app.shared_ctx.speedtest_active
def _adjust_active(delta: int):
counter = _counter()
with counter.get_lock():
counter.value = max(0, counter.value + delta)
def get_client_ip(request: Request) -> str:
"""The address Caddy forwarded, falling back to the socket peer for direct requests."""
return request.remote_addr or request.ip
@speedtest_bp.get('/ping')
@openapi.definition(
summary='Tiny response the browser times to measure round trip latency.',
)
async def ping(_: Request):
return json_response(dict(now=time.monotonic() * 1000), headers=NO_STORE_HEADERS)
@speedtest_bp.get('/info')
@openapi.definition(
summary='Context for a speed test: the client address the server saw and how many tests are running.',
)
async def info(request: Request):
return json_response(dict(
client_ip=get_client_ip(request),
active_tests=_counter().value,
max_download_seconds=MAX_DOWNLOAD_SECONDS,
max_upload_chunk=MAX_UPLOAD_CHUNK,
max_upload_seconds=MAX_UPLOAD_SECONDS,
), headers=NO_STORE_HEADERS)
@speedtest_bp.get('/download')
@openapi.definition(
summary='Stream random bytes for `seconds` (clamped) so the browser can measure download throughput.',
)
async def download(request: Request):
seconds = clamp_seconds(request.args.get('seconds'))
response = await request.respond(content_type='application/octet-stream', headers=NO_STORE_HEADERS)
_adjust_active(1)
try:
deadline = time.monotonic() + seconds
for chunk in iter_chunks():
if time.monotonic() >= deadline:
break
await response.send(chunk)
await response.eof()
except Exception as e:
# The browser aborts the fetch when its own timer ends; that is normal.
logger.debug(f'speed test download ended early: {e!r}')
finally:
_adjust_active(-1)
async def drain_upload(request: Request) -> int:
"""Read and discard the request body, enforcing both the size and the time cap."""
deadline = time.monotonic() + MAX_UPLOAD_SECONDS
total = 0
while True:
body = await request.stream.read()
if body is None:
return total
total += len(body)
if total > MAX_UPLOAD_CHUNK:
raise UploadTooLarge()
if time.monotonic() > deadline:
raise UploadTooSlow()
@speedtest_bp.post('/upload', stream=True)
@openapi.definition(
summary='Read and discard the request body, reporting how many bytes arrived and how long it took.',
)
async def upload(request: Request):
declared = request.headers.get('content-length')
if declared and declared.isdigit() and int(declared) > MAX_UPLOAD_CHUNK:
raise UploadTooLarge()
_adjust_active(1)
try:
start = time.monotonic()
total = await drain_upload(request)
seconds = time.monotonic() - start
finally:
_adjust_active(-1)
return json_response(dict(bytes=total, seconds=seconds), headers=NO_STORE_HEADERS)