From 8d8c8b0f2b0a7c0dfc330b9a31f705abf304274a Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Mon, 7 Sep 2026 00:48:41 -0400 Subject: [PATCH] The basemap user agent is one an operator can actually answer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `MeshTerm/0.1 (+https://github.com/; mesh node map)` went out on every OpenFreeMap tile request and was wrong twice over: the URL is a bare host nobody can visit, and `0.1` was a hand-written number that had already drifted from the package's `0.1.0` and would drift again on the next bump. OpenFreeMap issues no API key, so this header is the entire handle a tile operator has on a client — the difference between being emailed about traffic and being blocked for it. The URL now points at the real repository, and the version is the package's own `__version__`, which is what every other surface that shows a version already reads (the About page, the splash wordmark, the menu mark, a trace export). That is the single source of truth here, so reusing it is what keeps the string honest. Deliberately *not* `importlib.metadata.version("meshterm")`, despite that being the usual advice: MeshTerm is run straight from a checkout at least as often as from a wheel — this repo's own venv has no `meshterm` distribution installed, nor does the PicoCalc deploy — so the metadata lookup would raise `PackageNotFoundError` in exactly the setups it is developed and tested in, and a fallback around it would be a second version literal to keep in step with the first. Reading the package attribute has no failure mode at all, which is also why the value stays a module constant rather than becoming a function: it never changes, computing it cannot raise, and the tile fetch path is no place to discover either. Three tests in the basemap section of `test_map.py`: the string is exactly the repo, the live version and the descriptive tail; it rides the header of the request that actually leaves; and the module still imports with a real version in it when the metadata lookup is made to fail outright, which is the regression guard against someone reaching for `importlib.metadata` later without a fallback. Co-Authored-By: Claude Opus 5 (1M context) --- meshterm/services/basemap.py | 13 ++++++- tests/test_map.py | 72 ++++++++++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+), 2 deletions(-) diff --git a/meshterm/services/basemap.py b/meshterm/services/basemap.py index 1bd2a7d..dd0d8c1 100644 --- a/meshterm/services/basemap.py +++ b/meshterm/services/basemap.py @@ -52,13 +52,22 @@ from collections.abc import Container from pathlib import Path from typing import NamedTuple +from .. import __version__ from ..core.mvt import Layer, decode_tile, dumps_layers, loads_layers #: OpenFreeMap planet TileJSON — its ``tiles`` array holds the current versioned template. DEFAULT_TILEJSON_URL = "https://tiles.openfreemap.org/planet" -#: Sent on every request; identifies the client per common tile-usage etiquette. -_USER_AGENT = "MeshTerm/0.1 (+https://github.com/; mesh node map)" +#: Sent on every tile request. OpenFreeMap asks for no API key, so the user agent is the +#: only thing telling one client from another — which is how an operator reaches whoever is +#: costing them bandwidth, and why a stub URL or a version that has drifted is worse than +#: none at all. The version is the package's own :data:`~meshterm.__version__` rather than +#: an ``importlib.metadata`` lookup: MeshTerm is routinely run straight from a checkout +#: (this repo's venv, the PicoCalc's deploy) with no installed distribution to read, so the +#: metadata call would be the one that raises, and it would be a second version to keep in +#: step with the first. Built once at import because it never changes and cannot fail — +#: the tile path is no place to discover either. +_USER_AGENT = f"MeshTerm/{__version__} (+https://github.com/jpmartineau/MeshTerm; mesh node map)" #: Fallback max tile zoom if the TileJSON doesn't declare one (OpenFreeMap serves 14). _DEFAULT_MAX_ZOOM = 14 diff --git a/tests/test_map.py b/tests/test_map.py index 96f51db..a062014 100644 --- a/tests/test_map.py +++ b/tests/test_map.py @@ -12,6 +12,8 @@ import asyncio import io import os import re +import urllib.error +import urllib.request from pathlib import Path from time import monotonic from typing import TYPE_CHECKING @@ -726,6 +728,76 @@ def test_the_ghost_ground_is_dropped_once_it_says_nothing() -> None: # -- basemap source (offline behaviour) --------------------------------------- +def test_basemap_user_agent_is_contactable() -> None: + """The tile user agent names a repository that exists and the version actually running. + + OpenFreeMap issues no API key, so this string is the whole of what a tile operator has + to tell one client from another and to reach whoever is costing them bandwidth. It read + ``MeshTerm/0.1 (+https://github.com/; mesh node map)`` — a host nobody can visit, and a + number that was already wrong — which is the shape of traffic that gets a project + blocked rather than emailed. + """ + from meshterm import __version__ + from meshterm.services.basemap import _USER_AGENT + + assert _USER_AGENT == ( + f"MeshTerm/{__version__} (+https://github.com/jpmartineau/MeshTerm; mesh node map)" + ) + assert "https://github.com/;" not in _USER_AGENT, "the stub URL is back" + assert "mesh node map" in _USER_AGENT, "the operator can no longer tell what the traffic is" + + +def test_basemap_sends_its_user_agent_on_every_fetch(tmp_path: Path) -> None: + """The string is not decoration: it rides the header of the request that leaves.""" + from meshterm.services import basemap as basemap_mod + + src = _offline_source(tmp_path / "cache") + seen: list[urllib.request.Request] = [] + + def _urlopen(req: urllib.request.Request, timeout: float | None = None): + seen.append(req) + raise urllib.error.URLError("no network in tests") + + original = urllib.request.urlopen + urllib.request.urlopen = _urlopen # type: ignore[assignment] + try: + assert src._http_get("http://tiles.invalid/x") == basemap_mod._Response(False, b"") + finally: + urllib.request.urlopen = original # type: ignore[assignment] + + assert seen, "no request was ever built" + assert seen[0].get_header("User-agent") == basemap_mod._USER_AGENT + + +def test_basemap_user_agent_needs_no_installed_distribution() -> None: + """Importing the module must not depend on package metadata being on disk. + + MeshTerm is run straight from a checkout as often as from a wheel — this repo's own + venv and the PicoCalc's deploy both are — so a version read through + ``importlib.metadata`` would raise :class:`PackageNotFoundError` on the tile path in + exactly the setups it is developed in. The version comes from the package instead, and + this pins that: with the metadata lookup made to fail outright, the module still + imports and still carries a real version. + """ + import importlib + import importlib.metadata + + from meshterm import __version__ + from meshterm.services import basemap as basemap_mod + + def _raise(name: str) -> str: + raise importlib.metadata.PackageNotFoundError(name) + + original = importlib.metadata.version + importlib.metadata.version = _raise # type: ignore[assignment] + try: + reloaded = importlib.reload(basemap_mod) + assert f"MeshTerm/{__version__}" in reloaded._USER_AGENT + finally: + importlib.metadata.version = original # type: ignore[assignment] + importlib.reload(basemap_mod) + + def test_basemap_source_offline_is_graceful(tmp_path: Path) -> None: """An unreachable source reports unavailable and returns no tiles, never raising.""" from meshterm.services.basemap import BasemapSource