The basemap user agent is one an operator can actually answer

`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) <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5 committed 2026-09-07 00:48:41 -04:00
1 parent 40ecf5151d
commit 8d8c8b0f2b
2 files changed
+83 -2

No files matched your search

+11 -2
View File
@@ -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
+72
View File
@@ -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