diff --git a/app/src/components/Map.js b/app/src/components/Map.js index 08d39a3f..6e4bd932 100644 --- a/app/src/components/Map.js +++ b/app/src/components/Map.js @@ -51,21 +51,34 @@ async function getPreviewMapSource() { return {type: 'vector', url: `pmtiles://${MAP_OVERVIEW_URL}`}; } +/* + * The container is a piece of state set by a callback ref, not a `useRef` read in the effect. + * + * A modal body is not in the DOM on the render that opens the modal -- Mantine mounts it a + * commit later -- so an effect gated on `open` that reads `ref.current` finds null, returns, + * and never runs again, because nothing it depends on changes after that. Both previews were + * silently blank for exactly this reason. A callback ref re-runs the effect when the node + * arrives, whenever that is, so this does not depend on any modal's mounting schedule. + */ function RegionPreviewModal({bbox, name, open, onClose}) { - const mapContainer = React.useRef(null); + const [mapContainer, setMapContainer] = useState(null); React.useEffect(() => { - if (!open || !mapContainer.current || !bbox) return; + if (!open || !mapContainer || !bbox) return; const [minLon, minLat, maxLon, maxLat] = bbox.split(',').map(Number); const centerLon = (minLon + maxLon) / 2; const centerLat = (minLat + maxLat) / 2; let map; + // The source lookup is async, so the modal can close before it resolves. Without this + // the cleanup below runs while `map` is still undefined and the map built afterwards + // is never removed -- a leaked WebGL context on every quick open-and-close. + let cancelled = false; getPreviewMapSource().then(source => { - if (!mapContainer.current) return; + if (cancelled) return; map = new maplibregl.Map({ - container: mapContainer.current, + container: mapContainer, style: { version: 8, sources: {'basemap': source}, @@ -79,6 +92,9 @@ function RegionPreviewModal({bbox, name, open, onClose}) { }); map.on('load', () => { + // The flag again: cleanup can land between construction and `load`, and this + // body draws into a map `remove()` has already torn down. + if (cancelled) return; map.addSource('bbox', { type: 'geojson', data: { @@ -109,16 +125,19 @@ function RegionPreviewModal({bbox, name, open, onClose}) { }); map.fitBounds([[minLon, minLat], [maxLon, maxLat]], {padding: 40}); }); - }); + }).catch(e => console.error('Could not build the region preview map:', e)); - return () => { if (map) map.remove(); }; - }, [open, bbox]); + return () => { + cancelled = true; + if (map) map.remove(); + }; + }, [open, bbox, mapContainer]); return {/* No `.media` here: the bbox highlight is drawn as a map layer on the canvas itself (see the `bbox` source/layers above), so the automatic `canvas` element-type filter already covers it. There is no separate DOM overlay to wrap. */} -
+
; } @@ -129,17 +148,19 @@ const REGION_COLORS = [ '#a333c8', '#21ba45', '#db2828', '#fbbd08', '#a5673f', '#767676', ]; +// See RegionPreviewModal for why the container is state set by a callback ref. function AllRegionsPreviewModal({catalog, open, onClose}) { - const mapContainer = React.useRef(null); + const [mapContainer, setMapContainer] = useState(null); React.useEffect(() => { - if (!open || !mapContainer.current) return; + if (!open || !mapContainer) return; let map; + let cancelled = false; getPreviewMapSource().then(source => { - if (!mapContainer.current) return; + if (cancelled) return; map = new maplibregl.Map({ - container: mapContainer.current, + container: mapContainer, style: { version: 8, sources: {'basemap': source}, @@ -153,6 +174,8 @@ function AllRegionsPreviewModal({catalog, open, onClose}) { }); map.on('load', () => { + // See RegionPreviewModal: cleanup can land between construction and `load`. + if (cancelled) return; const regions = catalog.filter(r => r.bbox); regions.forEach((region, i) => { const [minLon, minLat, maxLon, maxLat] = region.bbox.split(',').map(Number); @@ -197,14 +220,17 @@ function AllRegionsPreviewModal({catalog, open, onClose}) { }); }); }); - }); + }).catch(e => console.error('Could not build the all-regions preview map:', e)); - return () => { if (map) map.remove(); }; - }, [open, catalog]); + return () => { + cancelled = true; + if (map) map.remove(); + }; + }, [open, catalog, mapContainer]); return {/* No `.media` here either — same reasoning as RegionPreviewModal. */} -
+
; } diff --git a/app/src/components/MapPreview.test.js b/app/src/components/MapPreview.test.js new file mode 100644 index 00000000..a3a6b70c --- /dev/null +++ b/app/src/components/MapPreview.test.js @@ -0,0 +1,308 @@ +/** + * The map preview modals must actually build a map. + * + * `RegionPreviewModal` (the eye button on a catalog row) and `AllRegionsPreviewModal` (the + * "View All Regions" button) each render a `
` into a Modal and hand it to MapLibre. They + * did that by reading a `useRef` inside an effect gated on `open`: + * + * React.useEffect(() => { + * if (!open || !mapContainer.current) return; // <-- ref is null here + * + * Mantine's Modal mounts its body one commit AFTER `opened` flips true, so on the render that + * opens the modal the ref is still null, the effect returns, and -- because neither `open` nor + * the other deps change again -- it never runs a second time. The div sits in the DOM, empty, + * with no console error and no rejected promise to point at any of this. + * + * It worked before the Mantine migration because Semantic UI's Portal put the modal body in + * the DOM in the same commit that opened it, so the ref was attached by the time effects ran. + * The effect bodies are byte-identical across that change; the modal library is the only + * variable. Confirmed on hardware still running the older build, where both previews render. + * + * So these tests assert the outcome -- a map got constructed against a node that is really in + * the document -- rather than the mechanism, which is the part that quietly changed under it. + */ +import React from 'react'; +import {act, screen, waitFor} from '@testing-library/react'; +import userEvent from '@testing-library/user-event'; +import {Route, Routes} from 'react-router'; +import {renderWithProviders as render} from '../test-utils'; +import {MapRoute} from './Map'; + +/* + * MapLibre cannot run in jsdom -- it wants WebGL -- so it is mocked down to the surface Map.js + * uses. Every constructed map records the container it was given, which is the whole claim. + */ +const constructed = []; + +jest.mock('maplibre-gl', () => { + class FakeMap { + constructor(options) { + this.options = options; + this.container = options.container; + this.handlers = {}; + // Recorded on the instance rather than watched with a spy installed after the + // fact: a spy attached post-construction misses whatever the real `load` already + // drew, which is the only thing worth asserting about. + this.sources = []; + constructed.push(this); + } + + on(event, callback) { + this.handlers[event] = callback; + // MapLibre fires `load` asynchronously once the style resolves. + if (event === 'load') setTimeout(() => callback(), 0); + return this; + } + + addSource(id) { + this.sources.push(id); + return this; + } + + addLayer() { + return this; + } + + addControl() { + return this; + } + + fitBounds() { + return this; + } + + remove() { + this.removed = true; + } + } + + return {__esModule: true, default: {Map: FakeMap, addProtocol: jest.fn(), Marker: FakeMap}}; +}); + +jest.mock('pmtiles', () => ({ + __esModule: true, + Protocol: class { + tile = jest.fn(); + }, +})); + +// The real one returns the full protomaps layer list; nothing here depends on its contents. +jest.mock('protomaps-themes-base', () => ({__esModule: true, default: () => []})); + +// Map.js imports the viewer, which pulls in the contour worker. The previews do not use it. +jest.mock('./MapViewer', () => ({__esModule: true, default: () => null})); + +const CATALOG = [ + {name: 'United States (West)', region: 'us-west', bbox: '-125.0,24.4,-104.0,49.4', size_estimate: 5e9}, + {name: 'Alaska', region: 'us-alaska', bbox: '-180.0,51.0,-129.0,72.0', size_estimate: 1.3e9}, + // A region with no bbox, as the terrain subscription really is -- it must not be drawn, + // and must not throw while the others are. + {name: 'Terrain (Global Hillshade & Contours)', region: 'terrain', bbox: null, size_estimate: 12e9}, +]; + +jest.mock('../api', () => ({ + ...jest.requireActual('../api'), + getMapFiles: jest.fn(), + fetchMapSubscriptions: jest.fn(), + getMapPins: jest.fn(), + deleteMapFile: jest.fn(), + deleteMapPin: jest.fn(), + updateMapPin: jest.fn(), + mapSubscribe: jest.fn(), + mapUnsubscribe: jest.fn(), + rebuildMapSearchIndex: jest.fn(), +})); + +const api = require('../api'); + +/** Render the Manage tab with a catalog and the given map files. */ +const renderManage = async ({files = []} = {}) => { + api.getMapFiles.mockResolvedValue({files}); + api.fetchMapSubscriptions.mockResolvedValue({catalog: CATALOG, subscriptions: []}); + api.getMapPins.mockResolvedValue({pins: []}); + /* + * Mounted under `/map/*` as App.js does, not bare. MapRoute's own `` + * is relative, so rendering it at the root resolves that to `/manage` and the Manage tab + * never matches -- the page renders its tab bar and nothing else. + */ + const result = render( + }/>, + {route: '/map/manage'}, + ); + /* + * Wait on a catalog row, not on the "View All Regions" button. That button renders as + * soon as the file list arrives, which is a separate request from the catalog -- waiting + * on it let a test reach the eye buttons before the rows existed. + */ + await screen.findByRole('button', {name: 'View All Regions'}); + await screen.findByRole('button', {name: 'Preview Alaska'}); + return result; +}; + +beforeEach(() => { + constructed.length = 0; + jest.clearAllMocks(); +}); + +describe('the "View All Regions" preview', () => { + it('renders the button at all', async () => { + // The premise. Everything below waits on a click, and a test that could not find the + // button would fail for a reason that has nothing to do with the map. + await renderManage(); + expect(screen.getByRole('button', {name: 'View All Regions'})).toBeInTheDocument(); + }); + + it('builds a map when opened', async () => { + await renderManage(); + expect(constructed).toHaveLength(0); + + await userEvent.click(screen.getByRole('button', {name: 'View All Regions'})); + + // This is the assertion that fails on the original code: the modal opens, the div is + // rendered, and no map is ever constructed against it. + await waitFor(() => expect(constructed).toHaveLength(1)); + }); + + it('builds the map against a node that is in the document', async () => { + /* + * Not merely "a map was constructed". A fix that passed a detached node -- one held + * from a previous render, say -- would satisfy the test above and still draw nothing a + * user can see, which is the failure being guarded against. + */ + await renderManage(); + await userEvent.click(screen.getByRole('button', {name: 'View All Regions'})); + + await waitFor(() => expect(constructed).toHaveLength(1)); + const {container} = constructed[0]; + expect(container).toBeInstanceOf(HTMLElement); + expect(document.body.contains(container)).toBe(true); + }); + + it('draws a source for every region that has a bbox, and only those', async () => { + /* + * The component's own `load` handler does the drawing -- FakeMap fires it as MapLibre + * does, and nothing here fires it a second time. An earlier version spied on + * `addSource` after construction and then re-invoked `load` by hand, which meant the + * count came entirely from that manual call and said nothing about the real path. + */ + await renderManage(); + await userEvent.click(screen.getByRole('button', {name: 'View All Regions'})); + await waitFor(() => expect(constructed).toHaveLength(1)); + + const withBbox = CATALOG.filter(r => r.bbox); + expect(withBbox.length).toBeLessThan(CATALOG.length); // the premise: one has no bbox + + const map = constructed[0]; + await waitFor(() => expect(map.sources).toHaveLength(withBbox.length)); + // Exactly once each, in catalog order -- a handler that ran twice would double these. + expect(map.sources).toEqual(withBbox.map((_, i) => `region-${i}`)); + }); +}); + +describe('a single region preview', () => { + it('builds a map when the eye button is clicked', async () => { + await renderManage(); + expect(constructed).toHaveLength(0); + + await userEvent.click(screen.getByRole('button', {name: 'Preview Alaska'})); + + await waitFor(() => expect(constructed).toHaveLength(1)); + expect(document.body.contains(constructed[0].container)).toBe(true); + }); +}); + +describe('the basemap source', () => { + it("uses the user's planet file when they have one", async () => { + await renderManage({files: [{name: '20260329.pmtiles', size: 134e9}]}); + await userEvent.click(screen.getByRole('button', {name: 'View All Regions'})); + await waitFor(() => expect(constructed).toHaveLength(1)); + + const {sources} = constructed[0].options.style; + expect(sources.basemap.url).toBe('pmtiles:///media/map/20260329.pmtiles'); + }); + + it('falls back to the overview blob when there is no planet file', async () => { + await renderManage({files: [{name: 'us-west-20260329.pmtiles', size: 5e9}]}); + await userEvent.click(screen.getByRole('button', {name: 'View All Regions'})); + await waitFor(() => expect(constructed).toHaveLength(1)); + + const {sources} = constructed[0].options.style; + expect(sources.basemap.url).toBe('pmtiles:///blobs/map-overview.pmtiles'); + }); +}); + +describe('closing a preview', () => { + it('removes the map', async () => { + /* + * MapLibre holds a WebGL context; the browser caps how many may exist at once, so a + * preview that leaks one on every open eventually takes the whole page's maps down. + */ + await renderManage(); + await userEvent.click(screen.getByRole('button', {name: 'View All Regions'})); + await waitFor(() => expect(constructed).toHaveLength(1)); + + // Escape rather than the close control: Mantine's close button carries no accessible + // name of its own, so a query for it is a query for markup rather than for behavior. + await userEvent.keyboard('{Escape}'); + + await waitFor(() => expect(constructed[0].removed).toBe(true)); + }); + + + /* + * The two below are a matched pair, and neither means anything alone. + * + * A first attempt at the cancel test closed the modal immediately after the click and + * passed with the `cancelled` guard deleted -- because Mantine had not mounted the modal + * body yet, so the effect had never run and there was nothing to cancel. It asserted that + * nothing happened in a test where nothing could have happened. The control is what makes + * the cancel test falsifiable: it proves this exact setup DOES build a map when the modal + * stays open, so a zero in the other test is the flag working rather than the harness + * never having started. + */ + const openWithHeldSource = async () => { + let releaseFiles; + const before = api.getMapFiles.mock.calls.length; + api.getMapFiles.mockReturnValue(new Promise(resolve => { + releaseFiles = resolve; + })); + await userEvent.click(screen.getByRole('button', {name: 'View All Regions'})); + // Wait for the effect to actually reach the source lookup. Waiting on the click alone + // is too early: the modal body mounts a commit later, which is the whole bug this file + // exists for. + await waitFor(() => expect(api.getMapFiles.mock.calls.length).toBe(before + 1)); + expect(constructed).toHaveLength(0); // in flight, nothing built yet + return releaseFiles; + }; + + it('builds the map when the held source resolves while still open', async () => { + // The control. See the note above. + await renderManage(); + const releaseFiles = await openWithHeldSource(); + + await act(async () => { + releaseFiles({files: []}); + }); + + expect(constructed).toHaveLength(1); + }); + + it('builds no map when closed before the source resolves', async () => { + /* + * The race the `cancelled` flag exists for, and the one "removes the map" does NOT + * cover: that one waits for the map before closing, so cleanup always finds a map to + * remove. Here cleanup runs while `map` is still undefined; without the flag the + * promise then resolves and builds a map nothing will ever remove -- a WebGL context + * leaked on every quick open-and-close. + */ + await renderManage(); + const releaseFiles = await openWithHeldSource(); + + await userEvent.keyboard('{Escape}'); + await act(async () => { + releaseFiles({files: []}); + }); + + expect(constructed).toHaveLength(0); + }); +}); diff --git a/docker-compose.yml b/docker-compose.yml index b21d37bd..6de09e1c 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -121,7 +121,10 @@ services: - './icon.png:/etc/caddy/icon.png' - './test:/opt/media' - './modules/map/static:/opt/wrolpi/modules/map/static:ro' - - './blobs:/opt/wrolpi-blobs:ro' + # No mount over /opt/wrolpi-blobs. A bind mount REPLACES the image's directory rather + # than merging with it, and the host './blobs' this used to mount is git-ignored -- so + # it was empty on every clone and hid the blobs the image provides. The web image bakes + # map-overview.pmtiles in; see docker/web/Dockerfile. environment: - MEDIA_DIRECTORY=/opt/media # Set EXTRA_SANS to include the host's LAN IP in the TLS certificate. diff --git a/docker/web/Dockerfile b/docker/web/Dockerfile index 79dbb5e5..f5d07b0d 100644 --- a/docker/web/Dockerfile +++ b/docker/web/Dockerfile @@ -1,7 +1,26 @@ # Pinned to the Caddy that Debian 13 devices run, so Docker matches hardware. FROM caddy:2.11.4 -RUN apk add --no-cache openssl bash +RUN apk add --no-cache openssl bash curl + +# The planet overview blob, which Caddy serves at /blobs/map-overview.pmtiles. +# +# It is the world at zoom 0-6, and it is what a regional map extract sits on top of: without +# it a user who subscribes to, say, three US regions gets those regions floating on an empty +# background at every zoom level that does not have their data. Only a full planet file (134 +# GB) makes it unnecessary. +# +# Raspberry Pi and Debian installs get this from pi-gen, the live-build config, and +# upgrade.sh. Docker had no equivalent and shipped without it -- see +# modules/map/test/test_map_overview_blob.py. 42 MB. +# +# `curl -f` so an HTTP error fails this layer rather than writing the error body to the file +# and exiting 0; an image that builds without the blob is the bug all over again, except now +# it is silent at build time too. +RUN mkdir -p /opt/wrolpi-blobs && \ + curl -fsSL https://wrolpi.nyc3.cdn.digitaloceanspaces.com/maps/map-overview.pmtiles \ + -o /opt/wrolpi-blobs/map-overview.pmtiles && \ + [ -s /opt/wrolpi-blobs/map-overview.pmtiles ] # Copy scripts and static files. COPY docker/web/Caddyfile /etc/caddy/Caddyfile diff --git a/modules/map/test/test_map_overview_blob.py b/modules/map/test/test_map_overview_blob.py new file mode 100644 index 00000000..4038ac40 --- /dev/null +++ b/modules/map/test/test_map_overview_blob.py @@ -0,0 +1,118 @@ +""" +The map overview blob must reach `/opt/wrolpi-blobs` in the Docker deployment. + +The React map viewer draws the world at zoom 0-6 from `/blobs/map-overview.pmtiles`, which +Caddy serves out of `/opt/wrolpi-blobs`. A user who subscribes to regional extracts -- the +normal case, since the planet file is 134GB -- gets that blob and nothing else underneath +their regions, so when it is missing the regions float on an empty background and the map +reads as broken. + +Raspberry Pi and Debian installs get the blob from pi-gen, the live-build config, and +upgrade.sh. Docker had no equivalent: the compose file bind-mounted a git-ignored (and +therefore empty) host directory over `/opt/wrolpi-blobs`, so the path existed and was empty +on every Docker WROLPi. Verified on a running deployment -- `/blobs/map-overview.pmtiles` +returned 404 while the same URL returned 206 on hardware. + +These read the deployment files rather than a running container: building the image to check +takes a CDN download and several minutes, and the two things that actually broke -- nothing +fetches the blob, and a mount hides it -- are both visible in the source. +""" +from pathlib import Path + +import pytest +import yaml + +from wrolpi.vars import PROJECT_DIR + +BLOBS_DIR = '/opt/wrolpi-blobs' +OVERVIEW_NAME = 'map-overview.pmtiles' + +WEB_DOCKERFILE = PROJECT_DIR / 'docker/web/Dockerfile' +COMPOSE_FILE = PROJECT_DIR / 'docker-compose.yml' +WEB_CADDYFILE = PROJECT_DIR / 'docker/web/Caddyfile' + + +@pytest.fixture +def web_dockerfile() -> str: + return WEB_DOCKERFILE.read_text() + + +@pytest.fixture +def compose() -> dict: + return yaml.safe_load(COMPOSE_FILE.read_text()) + + +def test_files_exist(): + """The premise. A missing file would read exactly like a passing test below.""" + for path in (WEB_DOCKERFILE, COMPOSE_FILE, WEB_CADDYFILE): + assert path.is_file(), f'{path} is missing' + + +def test_web_caddy_serves_blobs_from_the_blobs_directory(): + """The premise for the rest: `/blobs/*` really is `/opt/wrolpi-blobs`.""" + caddyfile = WEB_CADDYFILE.read_text() + assert 'handle_path /blobs/*' in caddyfile + assert BLOBS_DIR in caddyfile + + +def test_web_image_provisions_the_map_overview_blob(web_dockerfile): + """The web image must put the overview blob at the path Caddy serves.""" + assert OVERVIEW_NAME in web_dockerfile, \ + f'docker/web/Dockerfile never provisions {OVERVIEW_NAME}; a Docker WROLPi with only ' \ + f'regional map files will have no world basemap' + assert f'{BLOBS_DIR}/{OVERVIEW_NAME}' in web_dockerfile + + +def test_web_image_fails_the_build_when_the_blob_is_missing(web_dockerfile): + """ + A silent failure here is the whole bug: an image that builds without the blob ships and + the map is broken at runtime, where nothing explains why. pi-gen and the live-build + config both hard-fail on this, so the Docker build does too. + """ + fetch = [line for line in web_dockerfile.splitlines() if OVERVIEW_NAME in line] + assert fetch, 'no line mentions the overview blob' + # `curl -f` turns an HTTP error into a non-zero exit, which fails the RUN layer. Without + # it curl writes the error body to the output file and exits 0. + assert any('curl -f' in line or 'curl --fail' in line for line in fetch), \ + 'the blob download must use curl -f so an HTTP error fails the build' + + +def test_compose_does_not_shadow_the_blobs_directory(compose): + """ + A bind mount over `/opt/wrolpi-blobs` replaces what the image provides -- it does not + merge with it. The compose file mounted a git-ignored host directory there, so the blob + baked into the image would be invisible even once the Dockerfile fetches it. This is the + assertion that fails on the original code. + """ + volumes = compose['services']['web'].get('volumes') or [] + for volume in volumes: + # Entries are "source:target" or "source:target:mode". + target = volume.split(':')[1] if ':' in volume else '' + assert target != BLOBS_DIR, \ + f'docker-compose.yml mounts {volume!r} over {BLOBS_DIR}, hiding the ' \ + f'{OVERVIEW_NAME} baked into the web image' + + +def test_no_git_ignored_blobs_directory_is_relied_upon(): + """ + The host `./blobs` directory this used to mount is in .gitignore, so it is empty on every + fresh clone. Nothing in the deployment should depend on a user populating it by hand. + """ + gitignore = (PROJECT_DIR / '.gitignore').read_text() + if '/blobs/' not in gitignore: + pytest.skip('./blobs is no longer git-ignored') + compose_text = COMPOSE_FILE.read_text() + assert './blobs:' not in compose_text, \ + './blobs is git-ignored and therefore empty; the compose file must not depend on it' + + +def test_pi_and_docker_agree_on_the_blob_location(): + """ + Hardware and Docker must serve the same URL from the same path, or a fix to one silently + leaves the other broken -- which is exactly how this shipped. + """ + pi_caddyfile = (PROJECT_DIR / 'etc/raspberrypios/Caddyfile').read_text() + docker_caddyfile = WEB_CADDYFILE.read_text() + for caddyfile in (pi_caddyfile, docker_caddyfile): + assert 'handle_path /blobs/*' in caddyfile + assert f'root * {BLOBS_DIR}' in caddyfile