@signalk/charts-plugin 3.7.0 → 3.8.0

package/plugin/index.js

@@ -42,12 +42,17 @@ const charts_1 = require("./charts");
 const constants_1 = require("./constants");
 const pluginStatus_1 = require("./pluginStatus");
 const chartDownloader_1 = require("./chartDownloader");
+const chartDownloaderMBTilesHelpers_1 = require("./chartDownloaderMBTilesHelpers");
+const tokenProvider_1 = require("./tokenProvider");
+const cacheLayout_1 = require("./cacheLayout");
 const tileServer_1 = require("./tileServer");
 const chartTilesPath = '/signalk/chart-tiles';
 // Debounce window used to collapse FSWatcher bursts during rename / atomic-save
 // sequences into one reload. Overridable via env var so tests don't have to
-// wait the full 5s on every watcher assertion.
-const RELOAD_DEBOUNCE_MS = Number(process.env.SK_CHARTS_RELOAD_DEBOUNCE_MS) || 5000;
+// wait the full 5s on every watcher assertion. Read at call time rather than
+// captured at module load so a test can set the env var after importing this
+// module.
+const reloadDebounceMs = () => Number(process.env.SK_CHARTS_RELOAD_DEBOUNCE_MS) || 5000;
 const createPlugin = (app) => {
     let chartProviders = {};
     // Pre-computed per-version views of chartProviders, rebuilt on every reload.
@@ -56,6 +61,13 @@ const createPlugin = (app) => {
     let sanitizedV1 = {};
     let sanitizedV2 = {};
     let pluginStarted = false;
+    // pluginStarted vs pluginActive: pluginStarted is "registerRoutes has run"
+    // (sticky for the lifetime of the plugin closure — Express routes
+    // shouldn't double-register on a stop/start cycle). pluginActive is "is
+    // the plugin currently running" — flipped to true at the end of
+    // doStartup, false at the start of stop(). Watcher reloads check the
+    // latter so a queued reload from before stop() is harmless after stop().
+    let pluginActive = false;
     let providerRegistered = false;
     let props = {
         chartPaths: [],
@@ -76,17 +88,29 @@ const createPlugin = (app) => {
     let reloadTimer;
     let activeChartPaths = [];
     let activeOnlineProviders = {};
+    // Built from props.tokenProviders during doStartup; merged into
+    // chartProviders alongside the online providers. The ChartProvider value
+    // here holds an `_tokenProvider` handle so the proxy fetch path can call
+    // ensureFreshToken() before reading remoteUrl / headers.
+    let activeTokenProviders = {};
+    const migrationStatuses = new Map();
+    // Cooldown after a migration completes — protects against an admin
+    // client polling `migrate` and re-firing on completion. Re-running
+    // before the cooldown returns 429.
+    const MIGRATION_COOLDOWN_MS = 60_000;
     // Last scan result, surfaced in the config schema description so the admin
-    // UI shows per-path counts when the user reopens the plugin config. Issue #8.
+    // UI shows per-path counts when the user reopens the plugin config.
     let lastChartPathCounts = [];
     // Check Node version for schema
     const nodeVersion = process.versions.node;
     const nodeMajorVersion = parseInt(nodeVersion.split('.')[0] ?? '0');
-    // Builds the `chartPaths` description, appending the latest per-path chart
-    // counts when available. The admin UI re-fetches the schema every time the
-    // plugin config page opens, so this text refreshes on reload. Issue #8.
-    const chartPathsDescription = () => {
-        const base = `Add one or more paths to find charts. Defaults to "${defaultChartsPath}"`;
+    // Builds the chart-path field description, appending the latest per-path
+    // chart counts when available. The admin UI re-fetches the schema every time
+    // the plugin config page opens, so this text refreshes on reload. Applied to
+    // the array's items (not the array) because the admin UI renders an array
+    // field's own description twice.
+    const chartPathItemDescription = () => {
+        const base = `Path to find charts, relative to "${configBasePath}". Defaults to "${defaultChartsPath}"`;
         if (lastChartPathCounts.length === 0)
             return base;
         const parts = lastChartPathCounts.map((p) => `${p.chartPath} (${p.count} ${p.count === 1 ? 'chart' : 'charts'})`);
@@ -111,11 +135,14 @@ const createPlugin = (app) => {
             chartPaths: {
                 type: 'array',
                 title: 'Chart paths',
-                description: chartPathsDescription(),
+                // Description on the items, not the array: the admin UI renders an
+                // array field's own description twice. The per-path scan counts that
+                // used to live here are already surfaced in the plugin status banner
+                // (see composeStatus), so nothing is lost.
                 items: {
                     type: 'string',
                     title: 'Path',
-                    description: `Path for chart files, relative to "${configBasePath}"`
+                    description: chartPathItemDescription()
                 }
             },
             cachePath: {
@@ -171,8 +198,8 @@ const createPlugin = (app) => {
                             type: 'string',
                             title: 'Format',
                             default: 'png',
-                            enum: ['png', 'jpg', 'pbf'],
-                            description: 'Format of map tiles: raster (png, jpg, etc.) / vector (pbf).'
+                            enum: ['png', 'jpg', 'pbf', 'mvt', 'webp'],
+                            description: 'Format of map tiles: raster (png, jpg, webp, etc.) / vector (pbf, mvt).'
                         },
                         url: {
                             type: 'string',
@@ -182,16 +209,18 @@ const createPlugin = (app) => {
                         proxy: {
                             type: 'boolean',
                             title: 'Proxy through signalk server',
-                            description: 'Create a proxy to serve remote tiles and cache fetched tiles from the remote server, to serve them locally on subsequent requests. Use webapp to configure seeding jobs to prefetch tiles to local cache.',
+                            description: 'Create a proxy to serve remote tiles and cache fetched tiles from the remote server, to serve them locally on subsequent requests. Use webapp to configure seeding jobs to prefetch tiles to local cache. Only meaningful for tilelayer / WMS / WMTS providers; mapstyleJSON and tileJSON providers describe style/source manifests and have no per-tile cache to seed.',
                             default: false
                         },
                         headers: {
                             type: 'array',
                             title: 'Headers',
-                            description: 'List of http headers to be sent to the remote server when requesting map tiles through proxy.',
                             items: {
                                 title: 'Header Name: Value',
-                                description: 'Name and Value of the HTTP header separated by colon',
+                                // Help text on the items, not the array: the admin UI renders
+                                // an array field's own description twice.
+                                description: 'HTTP header sent to the remote server when proxying tiles, ' +
+                                    'as Name: Value (e.g. "User-Agent: MyApp/1.0").',
                                 type: 'string'
                             }
                         },
@@ -203,15 +232,118 @@ const createPlugin = (app) => {
                         layers: {
                             type: 'array',
                             title: 'Layers',
-                            description: 'List of map layer ids to display. (Use with WMS / WMTS types.)',
                             items: {
                                 title: 'Layer Name',
-                                description: 'Name of layer to display',
+                                // Help text on the items, not the array: the admin UI renders
+                                // an array field's own description twice.
+                                description: 'Map layer id to display (use with WMS / WMTS types).',
                                 type: 'string'
                             }
                         }
                     }
                 }
+            },
+            tokenProviders: {
+                type: 'array',
+                title: 'Token providers',
+                items: {
+                    type: 'object',
+                    title: 'Token provider',
+                    // The array's items carry the help text rather than the array field
+                    // itself: the admin UI's form renderer prints an array-of-objects
+                    // `description` twice (once for the array, once for the object
+                    // items), so keeping it only here renders it once.
+                    description: 'Declarative configs for chart providers that need a token ' +
+                        'fetched from a separate URL. The token is cached for ttlSeconds ' +
+                        'and templated into the tile URL/headers as {token.<field>}. ' +
+                        'Use {a-b} in URLs for sharded hostnames (random integer in [a,b]).',
+                    required: ['identifier', 'name', 'tokenEndpoint', 'tile'],
+                    properties: {
+                        identifier: {
+                            type: 'string',
+                            title: 'Identifier',
+                            description: 'Stable ID used in tile URLs (URL-safe; e.g. "navionics").'
+                        },
+                        name: { type: 'string', title: 'Name' },
+                        description: { type: 'string', title: 'Description' },
+                        type: {
+                            type: 'string',
+                            title: 'Map source type',
+                            default: 'tilelayer',
+                            enum: ['tilelayer', 'WMTS']
+                        },
+                        format: {
+                            type: 'string',
+                            title: 'Format',
+                            default: 'png',
+                            enum: ['png', 'jpg', 'webp', 'pbf', 'mvt']
+                        },
+                        scale: { type: 'number', title: 'Scale', default: 250000 },
+                        minzoom: {
+                            type: 'number',
+                            title: 'Min zoom',
+                            minimum: tileServer_1.MIN_ZOOM,
+                            maximum: tileServer_1.MAX_ZOOM
+                        },
+                        maxzoom: {
+                            type: 'number',
+                            title: 'Max zoom',
+                            minimum: tileServer_1.MIN_ZOOM,
+                            maximum: tileServer_1.MAX_ZOOM
+                        },
+                        bounds: {
+                            type: 'array',
+                            title: 'Bounds [minLon, minLat, maxLon, maxLat]',
+                            items: { type: 'number' },
+                            minItems: 4,
+                            maxItems: 4
+                        },
+                        tokenEndpoint: {
+                            type: 'object',
+                            title: 'Token endpoint',
+                            required: ['url', 'ttlSeconds'],
+                            properties: {
+                                url: { type: 'string', title: 'URL' },
+                                method: {
+                                    type: 'string',
+                                    title: 'Method',
+                                    default: 'GET',
+                                    enum: ['GET', 'POST']
+                                },
+                                headers: {
+                                    type: 'object',
+                                    title: 'Request headers',
+                                    additionalProperties: { type: 'string' }
+                                },
+                                body: { type: 'string', title: 'Request body' },
+                                ttlSeconds: {
+                                    type: 'number',
+                                    title: 'TTL (seconds)',
+                                    description: 'How long a fetched token is reused before re-fetching.',
+                                    minimum: 1
+                                }
+                            }
+                        },
+                        tile: {
+                            type: 'object',
+                            title: 'Tile request template',
+                            required: ['url'],
+                            properties: {
+                                url: {
+                                    type: 'string',
+                                    title: 'URL template',
+                                    description: 'Tile URL with {z}/{x}/{y}, {token.<field>}, and {a-b}.'
+                                },
+                                headers: {
+                                    type: 'object',
+                                    title: 'Request headers',
+                                    description: 'Header template (values may reference {token.<field>}).',
+                                    additionalProperties: { type: 'string' }
+                                }
+                            }
+                        }
+                    }
+                }
             }
         }
     });
@@ -230,10 +362,20 @@ const createPlugin = (app) => {
             // (config reload, server shutdown, error cascade) is visible in logs
             // instead of silently emptying chartProviders.
             console.log(`Signal K Charts: stop() called (${Object.keys(chartProviders).length} provider(s) will be released)`);
+            pluginActive = false;
             stopWatchers();
             // Cancel any running seeding jobs so a disabled plugin doesn't keep
             // pulling tiles from remote providers in the background.
             chartDownloader_1.ChartSeedingManager.cancelAll();
+            // Cancel any in-flight legacy migration. Without this, the walk
+            // keeps calling putTile against a handle we're about to close —
+            // every call errors-and-counts-as-failed for thousands of remaining
+            // tiles, and a quick restart can race the orphan loop against a
+            // freshly opened connection on the same file.
+            for (const status of migrationStatuses.values()) {
+                if (status.state === 'running')
+                    status.controller?.abort();
+            }
             // Close open SQLite connections so the user can move or delete chart
             // files while the plugin is stopped (Windows blocks deletion on open
             // handles). Restart re-opens fresh via findCharts.
@@ -272,6 +414,10 @@ const createPlugin = (app) => {
         if (cachePath !== defaultChartsPath) {
             await ensureDirectoryExists(cachePath);
         }
+        // Migrate any flat-layout proxy / export files into the .working/
+        // and exports/ subdirs the scanner expects. Idempotent and
+        // failure-tolerant: a file we can't move is logged and the rest carry on.
+        await (0, cacheLayout_1.migrateLegacyCacheLayout)(cachePath, app);
         activeOnlineProviders = {};
         for (const data of props.onlineChartProviders ?? []) {
             const provider = convertOnlineProviderConfig(data);
@@ -282,13 +428,33 @@ const createPlugin = (app) => {
             }
             activeOnlineProviders[provider.identifier] = provider;
         }
-        app.debug(`Start charts plugin. Chart paths: ${activeChartPaths.join(', ')}, online charts: ${Object.keys(activeOnlineProviders).length}`);
+        // Build token providers. A bad config entry shouldn't take the whole
+        // plugin out — log and skip the offender so the rest still load.
+        activeTokenProviders = {};
+        for (let i = 0; i < (props.tokenProviders ?? []).length; i++) {
+            const raw = (props.tokenProviders ?? [])[i];
+            try {
+                const cfg = (0, tokenProvider_1.validateTokenProviderConfig)(raw, i);
+                const provider = (0, tokenProvider_1.chartProviderFromTokenConfig)(cfg);
+                if (activeTokenProviders[provider.identifier]) {
+                    app.debug(`Duplicate token provider identifier "${provider.identifier}"; ` +
+                        `the later entry wins. Rename one to avoid the collision.`);
+                }
+                activeTokenProviders[provider.identifier] = provider;
+            }
+            catch (err) {
+                console.warn(`Skipping ${err.message}`);
+            }
+        }
+        app.debug(`Start charts plugin. Chart paths: ${activeChartPaths.join(', ')}, online charts: ${Object.keys(activeOnlineProviders).length}, ` +
+            `token providers: ${Object.keys(activeTokenProviders).length}`);
         // Routes and the v2 provider registration are idempotent — Signal K can
         // call start() again after a config change, but re-registering would
         // either throw or duplicate the handler.
         if (!pluginStarted)
             registerRoutes();
         pluginStarted = true;
+        pluginActive = true;
         if (serverMajorVersion === 2 && !providerRegistered) {
             app.debug('** Registering v2 API paths **');
             registerAsProvider();
@@ -357,17 +523,51 @@ const createPlugin = (app) => {
             app.setPluginStatus((0, pluginStatus_1.composeStatus)(perPath, Object.keys(activeOnlineProviders).length));
             return;
         }
-        reconcileMbtilesHandles(chartProviders);
-        // Shallow assign is enough: newCharts and activeOnlineProviders both
-        // have unique ids per entry; the values themselves are used by reference.
-        chartProviders = { ...newCharts };
+        // Build the next chartProviders dict locally first so request handlers
+        // never see a half-populated state. Atomic publish at the end of the
+        // function keeps `_mbtilesHandle` invariants intact: a request reading
+        // chartProviders[id] for a proxy provider should always find a handle
+        // open, never a transient null between the dict-swap and the handle-open.
+        const nextChartProviders = {
+            ...newCharts
+        };
         for (const [id, provider] of Object.entries(activeOnlineProviders)) {
-            if (chartProviders[id]) {
+            if (nextChartProviders[id]) {
                 app.debug(`Online provider identifier "${id}" collides with a local chart; ` +
                     `the online provider wins.`);
             }
-            chartProviders[id] = provider;
+            nextChartProviders[id] = provider;
         }
+        // Token providers (declarative token-rotating configs) merge in last
+        // and win over a colliding online or local entry: the admin took the
+        // explicit step of configuring one, so a stale auto-discovered chart
+        // shouldn't shadow it.
+        for (const [id, provider] of Object.entries(activeTokenProviders)) {
+            if (nextChartProviders[id]) {
+                app.debug(`Token provider identifier "${id}" collides with another ` +
+                    `provider; the token provider wins.`);
+            }
+            nextChartProviders[id] = provider;
+        }
+        // Open / create the working mbtiles cache for every proxy provider.
+        // Path lives under `.working/<id>/cache.mbtiles` (excluded from the
+        // scanner so it isn't read-opened concurrently with our writes).
+        // Failure to open doesn't take the provider out — tile requests will
+        // just always go remote.
+        for (const provider of Object.values(nextChartProviders)) {
+            if (provider.proxy === true) {
+                try {
+                    provider._mbtilesHandle = await (0, chartDownloaderMBTilesHelpers_1.openOrCreateMbtiles)((0, cacheLayout_1.workingMbtilesPath)(cachePath, provider.identifier), provider);
+                }
+                catch (err) {
+                    app.debug(`Could not open mbtiles cache for ${provider.identifier}: ${err.message}`);
+                }
+            }
+        }
+        // Now publish: close handles on the previous set we're replacing, then
+        // swap in the fully-populated next set in one assignment.
+        reconcileMbtilesHandles(chartProviders);
+        chartProviders = nextChartProviders;
         buildSanitizedCache();
         app.setPluginStatus((0, pluginStatus_1.composeStatus)(perPath, Object.keys(activeOnlineProviders).length));
     };
@@ -392,6 +592,13 @@ const createPlugin = (app) => {
     const MBTILES_CLOSE_DELAY_MS = 1000;
     const reconcileMbtilesHandles = (oldSet) => {
         for (const old of Object.values(oldSet)) {
+            // Skip providers that were only in the old set if they were proxy providers
+            //  we want to keep serving tiles from their existing mbtiles handle until
+            // the new one is ready, and a missing handle means the new config failed
+            // to open the file, so there's no new handle to wait for.
+            if (old.proxy === true) {
+                continue;
+            }
             if (old?._mbtilesHandle) {
                 const handle = old._mbtilesHandle;
                 setTimeout(() => closeMbtilesHandle(handle), MBTILES_CLOSE_DELAY_MS);
@@ -414,14 +621,37 @@ const createPlugin = (app) => {
     // Chart folders are watched so new/renamed/deleted files become visible
     // without a plugin restart. FSWatcher bursts events during rename and
     // atomic-save sequences; the debounce collapses a burst into one reload.
+    // Set while loadChartProviders is running so a watcher event during a
+    // reload doesn't kick off a parallel one. Combined with the debounce
+    // and the pluginActive check, this means at most one
+    // loadChartProviders is in-flight at a time.
+    let loadInFlight = false;
     const scheduleReload = () => {
         if (reloadTimer)
             clearTimeout(reloadTimer);
         reloadTimer = setTimeout(() => {
             reloadTimer = undefined;
+            // Guards against the stop()-during-debounce race: a watcher event
+            // queues a reload, then the admin disables the plugin during the
+            // debounce window. Without this check the reload fires after stop()
+            // has cleared chartProviders, opens fresh mbtiles handles, and the
+            // next stop() doesn't know about them.
+            if (!pluginActive)
+                return;
+            if (loadInFlight) {
+                // Reschedule rather than drop: the in-flight reload may have
+                // captured pre-event state.
+                scheduleReload();
+                return;
+            }
             app.debug('Reloading charts after filesystem change');
-            loadChartProviders();
-        }, RELOAD_DEBOUNCE_MS);
+            loadInFlight = true;
+            loadChartProviders()
+                .catch((e) => console.warn(`[charts-plugin] reload failed: ${e.message}`))
+                .finally(() => {
+                loadInFlight = false;
+            });
+        }, reloadDebounceMs());
     };
     const startWatchers = () => {
         stopWatchers();
@@ -496,28 +726,236 @@ const createPlugin = (app) => {
                 }
             }
         });
+        // Hard cap on the persisted regions.json size. The webapp posts the
+        // full FeatureCollection on every save; allowing arbitrary growth
+        // would let an admin (or a misbehaving client) fill the data dir.
+        const MAX_REGIONS_BYTES = 1024 * 1024; // 1 MB; thousands of detailed polygons
+        app.post(`${chartTilesPath}/cache/regions`, async (req, res) => {
+            // Validate the body shape: we expect a GeoJSON FeatureCollection.
+            // Without this, anything JSON-shaped lands in regions.json and
+            // breaks the GET handler / the webapp on next read.
+            const body = req.body;
+            if (typeof body !== 'object' ||
+                body === null ||
+                body.type !== 'FeatureCollection' ||
+                !Array.isArray(body.features)) {
+                return res
+                    .status(400)
+                    .send('expected a GeoJSON FeatureCollection with a features array');
+            }
+            const serialised = JSON.stringify(body, null, 2);
+            if (Buffer.byteLength(serialised, 'utf8') > MAX_REGIONS_BYTES) {
+                return res
+                    .status(413)
+                    .send(`regions payload exceeds ${MAX_REGIONS_BYTES} bytes`);
+            }
+            // Async write so a slow SD card on a Pi doesn't stall the event
+            // loop, and a try/catch so an EACCES / ENOSPC produces a useful
+            // 500 instead of an uncaught throw.
+            const p = path_1.default.join(app.getDataDirPath(), 'regions.json');
+            try {
+                await fs_1.default.promises.writeFile(p, serialised, 'utf8');
+            }
+            catch (err) {
+                console.warn(`[charts-plugin] failed to write ${p}: ${err.message}`);
+                return res
+                    .status(500)
+                    .send(`failed to persist regions: ${err.message}`);
+            }
+            return res.send({ status: 'ok' });
+        });
+        app.get(`${chartTilesPath}/cache/regions`, async (_req, res) => {
+            const p = path_1.default.join(app.getDataDirPath(), 'regions.json');
+            try {
+                const raw = await fs_1.default.promises.readFile(p, 'utf8');
+                const data = JSON.parse(raw);
+                return res.json(data);
+            }
+            catch (_e) {
+                return res.json({ type: 'FeatureCollection', features: [] });
+            }
+        });
+        app.get(`${chartTilesPath}/cache/stats`, (_req, res) => {
+            const data = chartDownloader_1.ChartDownloader.getStatistics();
+            return res.json(data);
+        });
+        // Migrate a per-file PNG cache (`<sourceName>/<z>/<x>/<y>.<ext>`) into
+        // the provider's working mbtiles. Body fields (all optional):
+        //   sourceName    legacy directory name (default: provider.name)
+        //   deleteSource  remove tile files after successful insert
+        // Returns 202 immediately and runs the walk in the background — large
+        // caches (>100k tiles) can take minutes and would time out a sync
+        // response. State is recorded in `migrationStatuses` so the admin can
+        // poll GET /cache/:id/migrate for progress and the final counts. The
+        // migration itself is idempotent so re-running is safe.
+        app.post(`${chartTilesPath}/cache/:identifier/migrate`, async (req, res) => {
+            const { identifier } = req.params;
+            const provider = chartProviders[identifier];
+            if (!provider)
+                return res.status(404).send('Provider not found');
+            if (!provider._mbtilesHandle) {
+                return res
+                    .status(400)
+                    .send(`Provider "${identifier}" has no working mbtiles cache. ` +
+                    `Configure proxy:true and ensure cachePath is writable.`);
+            }
+            const existing = migrationStatuses.get(identifier);
+            if (existing && existing.state === 'running') {
+                return res
+                    .status(409)
+                    .send(`Migration for "${identifier}" is already running. ` +
+                    `Wait for it to complete or check GET /cache/${identifier}/migrate.`);
+            }
+            // Cooldown after completion: a flapping admin client polling
+            // GET .../migrate and re-firing on completion would otherwise
+            // walk the directory continuously.
+            if (existing &&
+                existing.state !== 'running' &&
+                existing.completedAt &&
+                Date.now() - existing.completedAt < MIGRATION_COOLDOWN_MS) {
+                return res
+                    .status(429)
+                    .header('Retry-After', String(Math.ceil((MIGRATION_COOLDOWN_MS -
+                    (Date.now() - existing.completedAt)) /
+                    1000)))
+                    .send(`Migration for "${identifier}" recently ${existing.state}; ` +
+                    `wait ${Math.ceil(MIGRATION_COOLDOWN_MS / 1000)}s before re-running. ` +
+                    `Previous result: ${JSON.stringify(existing.counts)}`);
+            }
+            const body = (req.body ?? {});
+            const sourceName = typeof body.sourceName === 'string' && body.sourceName.length > 0
+                ? body.sourceName
+                : provider.name;
+            const legacyDir = path_1.default.resolve(cachePath, sourceName);
+            // path.resolve guards against `../` escape, but a naive prefix
+            // startsWith check has a false-negative when a sibling directory
+            // happens to share the cachePath prefix (e.g. cachePath
+            // `/var/lib/sk/charts` + sourceName `../charts-shared` resolves
+            // to `/var/lib/sk/charts-shared` which startsWith `/var/lib/sk/charts`).
+            // Require the resolved path to equal cachePath OR start with
+            // `cachePath + sep`.
+            const cacheBase = path_1.default.resolve(cachePath);
+            if (legacyDir !== cacheBase &&
+                !legacyDir.startsWith(cacheBase + path_1.default.sep)) {
+                return res.status(400).send('sourceName must not escape cachePath');
+            }
+            const handle = provider._mbtilesHandle;
+            const deleteSource = body.deleteSource === true;
+            // The default cachePath IS the chart-scan path, and a directory-format
+            // chart is stored as the same <z>/<x>/<y>.<fmt> tree this migration
+            // walks (and, with deleteSource, unlinks). Without this guard a request
+            // like { sourceName: "<installed-chart-dir>", deleteSource: true }
+            // would drain and delete a user's installed chart. Refuse when the
+            // source resolves onto an installed chart.
+            const installedChart = resolveInstalledChartCollision(legacyDir);
+            if (installedChart) {
+                return res
+                    .status(409)
+                    .send(`sourceName "${sourceName}" resolves onto installed chart data ` +
+                    `(${installedChart}). Refusing to migrate it as a legacy cache.`);
+            }
+            const controller = new AbortController();
+            const status = {
+                state: 'running',
+                startedAt: Date.now(),
+                legacyDir,
+                deleteSource,
+                counts: { migrated: 0, skipped: 0, failed: 0 },
+                controller
+            };
+            migrationStatuses.set(identifier, status);
+            console.log(`[charts-plugin] migration for "${identifier}" started ` +
+                `legacyDir=${legacyDir} deleteSource=${deleteSource}`);
+            // Fire and forget: log on completion / failure and update the
+            // shared status entry so GET ../migrate can surface progress.
+            // The onProgress callback updates counts every 500 processed
+            // entries, giving the admin a way to confirm forward progress
+            // without grepping logs.
+            const promise = (0, cacheLayout_1.migrateLegacyTileCache)(legacyDir, handle, {
+                deleteSource,
+                signal: controller.signal,
+                onProgress: (counts) => {
+                    status.counts = { ...counts };
+                    // Surface progress in the SignalK plugin list so an admin
+                    // who started a multi-hour migration before bed can see it
+                    // running on the dashboard without grepping logs.
+                    const total = counts.migrated + counts.skipped + counts.failed;
+                    app.setPluginStatus(`Migrating "${identifier}": ${counts.migrated} migrated, ` +
+                        `${total} processed`);
+                }
+            })
+                .then((counts) => {
+                status.counts = counts;
+                status.state = controller.signal.aborted ? 'cancelled' : 'completed';
+                status.completedAt = Date.now();
+                console.log(`[charts-plugin] migration for "${identifier}" ${status.state}: ` +
+                    `${counts.migrated} migrated, ${counts.skipped} skipped, ` +
+                    `${counts.failed} failed`);
+                app.setPluginStatus(`Migration for "${identifier}" ${status.state}: ` +
+                    `${counts.migrated} migrated, ${counts.skipped} skipped, ` +
+                    `${counts.failed} failed`);
+            })
+                .catch((err) => {
+                status.state = 'failed';
+                status.completedAt = Date.now();
+                status.error = err.message;
+                console.warn(`[charts-plugin] migration for "${identifier}" failed: ${err.message}`);
+                app.setPluginStatus(`Migration for "${identifier}" failed: ${err.message}`);
+            });
+            status.promise = promise;
+            return res.status(202).json({
+                status: 'started',
+                provider: identifier,
+                legacyDir,
+                deleteSource
+            });
+        });
+        // Poll the state of a previously-started legacy migration. Returns 404
+        // if no migration has been kicked off for this provider in this plugin
+        // session — the state is plugin-scoped, so a stop()/start() cycle
+        // clears it.
+        app.get(`${chartTilesPath}/cache/:identifier/migrate`, (req, res) => {
+            const { identifier } = req.params;
+            const status = migrationStatuses.get(identifier);
+            if (!status) {
+                return res
+                    .status(404)
+                    .send(`No migration recorded for "${identifier}" in this session.`);
+            }
+            return res.status(200).json({ provider: identifier, ...status });
+        });
         app.post(`${chartTilesPath}/cache/:identifier`, async (req, res) => {
             const { identifier } = req.params;
             if (!identifier) {
                 return res.sendStatus(404);
             }
-            const { regionGUID, tile, bbox, maxZoom } = req.body;
+            const { feature, bbox, minZoom, maxZoom, action, options } = req.body;
             const provider = chartProviders[identifier];
             if (!provider) {
                 return res.status(404).send('Provider not found');
             }
+            // Reject providers that can't be tile-seeded (non-proxy, or a style /
+            // vector type such as mapstyleJSON) with a clear 400 rather than
+            // creating a job that fails every tile. The webapp already hides these
+            // from the picker; this guards direct API callers.
+            const seedableError = (0, tileServer_1.validateSeedableProvider)(provider);
+            if (seedableError) {
+                return res.status(400).send(seedableError);
+            }
             if (!maxZoom) {
                 return res.status(400).send('maxZoom parameter is required');
             }
-            if (!regionGUID && !bbox && !tile) {
-                return res
-                    .status(400)
-                    .send('Request must include regionGUID, bbox, or tile');
+            if (!feature && !bbox) {
+                return res.status(400).send('Request must include feature or bbox');
             }
+            const minZoomParsed = parseInt(minZoom ?? '1');
             const maxZoomParsed = parseInt(maxZoom);
-            const zoomError = (0, tileServer_1.validateMaxZoom)(maxZoomParsed);
-            if (zoomError) {
-                return res.status(400).send(zoomError);
+            const maxZoomError = (0, tileServer_1.validateMaxZoom)(maxZoomParsed);
+            if (maxZoomError) {
+                return res.status(400).send(maxZoomError);
+            }
+            if (Number.isFinite(minZoomParsed) && (0, tileServer_1.validateMaxZoom)(minZoomParsed)) {
+                return res.status(400).send(`Invalid minZoom ${minZoomParsed}`);
             }
             if (bbox) {
                 const bboxError = (0, tileServer_1.validateBBox)(bbox);
@@ -525,16 +963,16 @@ const createPlugin = (app) => {
                     return res.status(400).send(bboxError);
                 }
             }
-            if (tile) {
-                const tileError = (0, tileServer_1.validateTileCoords)(tile.z, tile.x, tile.y);
-                if (tileError) {
-                    return res.status(400).send(tileError);
-                }
-            }
             try {
-                const job = await chartDownloader_1.ChartSeedingManager.createJob(app.resourcesApi, cachePath, provider, maxZoomParsed, regionGUID, bbox
+                const job = await chartDownloader_1.ChartSeedingManager.createJob(cachePath, provider, options ?? { refetch: false, mbtiles: false, vacuum: false }, minZoomParsed, maxZoomParsed, feature, bbox
                     ? [bbox.minLon, bbox.minLat, bbox.maxLon, bbox.maxLat]
-                    : undefined, tile);
+                    : undefined);
+                if (action === 'start') {
+                    runJobInBackground(job, job.seedCache());
+                }
+                else if (action === 'delete') {
+                    runJobInBackground(job, job.deleteCache());
+                }
                 // Job is registered and its tile set is known, but nothing has been
                 // downloaded yet — the caller starts it with
                 // POST /cache/jobs/:id { action: 'start' }.
@@ -570,15 +1008,30 @@ const createPlugin = (app) => {
                 return res.status(400).send('action parameter is required');
             }
             if (action === 'start') {
-                job.seedCache();
+                // Reject restart of jobs that already ran. seedCache itself is a
+                // no-op while Running, but a Completed (or Cancelled) job would
+                // happily reset its counters and run again. The admin should
+                // remove the completed job and create a fresh one to refresh
+                // tiles, so the intent is explicit and doesn't get lost in a
+                // counter reset.
+                if (job.info().status !== 'Idle') {
+                    return res
+                        .status(409)
+                        .send(`Job ${parsedId} cannot be started (status: ${job.info().status}). ` +
+                        `Remove and recreate the job to seed again.`);
+                }
+                runJobInBackground(job, job.seedCache());
             }
             else if (action === 'stop') {
                 job.cancelJob();
             }
             else if (action === 'delete') {
-                job.deleteCache();
+                runJobInBackground(job, job.deleteCache());
             }
             else if (action === 'remove') {
+                // Cancel first so an in-flight seed doesn't mutate the entry
+                // after we drop it from the registry.
+                job.cancelJob();
                 delete chartDownloader_1.ChartSeedingManager.ActiveJobs[parsedId];
             }
             else {
@@ -645,6 +1098,37 @@ const resolveUniqueChartPaths = (chartPaths, configBasePath) => {
     const paths = chartPaths.map((chartPath) => path_1.default.resolve(configBasePath, chartPath));
     return [...new Set(paths)];
 };
+// Returns the candidate path if it is an installed directory-format chart, or
+// null if it is safe to migrate as a legacy proxy cache. The discriminator is
+// the same marker the scanner uses (tilemapresource.xml / metadata.json): a
+// legacy PNG cache is a bare <z>/<x>/<y> tree with no marker, whereas an
+// installed TMS/XYZ chart has one. This stops the legacy-cache migration —
+// which walks and (with deleteSource) unlinks a <z>/<x>/<y> tree — from
+// cannibalising a user's installed chart, a real risk because the default
+// cachePath and the default chart path are the same directory and a directory
+// chart has the identical on-disk tile layout.
+const INSTALLED_CHART_MARKERS = ['tilemapresource.xml', 'metadata.json'];
+// seedCache() and deleteCache() are fire-and-forget: the HTTP handler returns
+// 202 immediately and the work continues in the background. Both methods record
+// a failure on the job and reset its state internally, but the returned promise
+// still rejects on error — and an un-awaited rejected promise is an unhandled
+// rejection, which on Node 22+ terminates the whole Signal K server. This
+// attaches the terminal .catch() so a failed seed/delete degrades the job, not
+// the process.
+const runJobInBackground = (job, work) => {
+    work.catch((err) => {
+        console.error(`[charts-plugin] background job ${job.info().id} failed: ${err.message}`);
+    });
+};
+const resolveInstalledChartCollision = (candidate) => {
+    const resolved = path_1.default.resolve(candidate);
+    for (const marker of INSTALLED_CHART_MARKERS) {
+        if (fs_1.default.existsSync(path_1.default.join(resolved, marker))) {
+            return resolved;
+        }
+    }
+    return null;
+};
 const convertOnlineProviderConfig = (provider) => {
     const id = _.kebabCase(_.deburr(provider.name));
     const parseHeaders = (arr) => {
@@ -693,14 +1177,43 @@ const convertOnlineProviderConfig = (provider) => {
 // Builds the outward-facing view of a provider for either the v1 or v2 API.
 // Copies non-private top-level fields, then overlays the version-specific
 // block (v1 has tilemapUrl/chartLayers, v2 has url/layers), rewriting the
-// tile-path placeholder. Intentionally a single shallow walk — the previous
-// implementation did three deep clones per call and ran per metadata request.
+// tile-path placeholder. Intentionally a single shallow walk to keep
+// per-metadata-request cost bounded.
+//
+// `name` and `description` go through stripHtml first: the webapp's
+// Leaflet L.Control.Layers writes them into innerHTML, so a malicious
+// .mbtiles shipping a metadata.name like
+// `<img src=x onerror="..."> ` would execute in the admin's session.
+// Server-side sanitisation lets the (vendored) UI keep its rendering
+// path without per-call escaping.
+const stripHtml = (s) => s
+    // Drop tags entirely. We don't try to preserve any HTML — this is
+    // chart metadata from a SQLite blob, not rich text.
+    .replace(/<[^>]*>/g, '')
+    // Belt-and-braces: collapse any standalone & < > so an unbalanced
+    // input doesn't produce something the browser still treats as markup.
+    .replace(/[<>]/g, '');
 const sanitizeProvider = (provider, version = 1) => {
     const out = {};
     for (const [key, value] of Object.entries(provider)) {
         if (key.startsWith('_') || key === 'v1' || key === 'v2')
             continue;
-        out[key] = value;
+        // remoteUrl / headers are the upstream proxy target and its request
+        // headers — for token providers these are getters that resolve a live
+        // bearer token. Clients fetch tiles through the proxy path (~tilePath~),
+        // never the upstream directly, so these must not appear in the public
+        // resources view; emitting them would leak the rotating credential.
+        if (key === 'remoteUrl' || key === 'headers')
+            continue;
+        // Defang any string field that the webapp might later render via
+        // innerHTML (Leaflet L.Control.Layers, custom tooltips, etc).
+        if ((key === 'name' || key === 'description') &&
+            typeof value === 'string') {
+            out[key] = stripHtml(value);
+        }
+        else {
+            out[key] = value;
+        }
     }
     const v = version === 1 ? provider.v1 : provider.v2;
     if (v) {