signalk-underkeel 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to signalk-underkeel are documented here.
 
+## [0.6.0] - 2026-11-10
+
+### Changed
+
+- Charts Provider sharing its store after this plugin started, as it does at every server
+  start once its charts are loaded, no longer restarts the plugin when the store holds the
+  cells read at start; only the note that it was not running goes.
+- The first chart box is built as soon as the first position arrives, not at the next 10 s
+  check. Until it is in use the reason says the box is being built and how far it has come,
+  for example `building the chart box around the vessel: reading cells 3/7`, and the cells
+  phase counts each cell as it is read instead of jumping from 0 to all.
+- A charts provider still starting, or one that does not download an area, goes to the debug
+  log instead of the error log; one too old to be asked, or whose answer failed, stays an
+  error.
+- Once a chart box is in use, the cells the next box can reach are read into the cell cache by
+  a child process at the lowest CPU priority, so moving the box over them reads none during the
+  rebuild: after a 6 km move the Waddenzee box rebuilt in 8.6 s against 34 s for its first
+  build (x86).
+
 ## [0.5.1] - 2026-11-10
 
 ### Changed

package/README.md

@@ -144,8 +144,10 @@ phase, start and the last build's duration. At speed the box grows past its radi
 **Largest index box at speed** (0 sizes it from the RAM), so the vessel cannot reach the edge
 before the next box is built (docs/HOW-IT-WORKS.md §12). A radius under 2 km is raised to 2.
 Until the first position arrives the engine is `off`
-with the reason `waiting for the vessel position to build the chart box`. Set the box to 0 to
-index every cell.
+with the reason `waiting for the vessel position to build the chart box`; the box is built
+as soon as one does, and meanwhile the reason says how far it has come, for example
+`building the chart box around the vessel: reading cells 3/7`. Set the box to 0 to index every
+cell.
 
 At the first start the plugin builds a chart index from the cells in a child process and saves
 it under the plugin data directory, `~/.signalk/plugin-config-data/signalk-underkeel/index`
@@ -157,8 +159,11 @@ changed; `GET /status` names the cells that caused the rebuild. **Rebuild index
 forces a rebuild on every start. A cell folder may be a symbolic link. What the build read
 from each cell is kept, compressed, in `cell-cache` in the plugin data directory (at most 512 MB), so a
 chart box refresh reads again only the cells whose files changed: the 10 km Waddenzee box
-rebuilds in 12–15 s instead of 30–34 s on x86. Deleting the folder is safe; the cells are then
-read again.
+rebuilds in 12–15 s instead of 30–34 s on x86. Once a box is in use, a child process at the
+lowest CPU priority reads into it the cells the next box can reach, so a box moved over cells it
+had not met reads none during the rebuild: after a 6 km move the Waddenzee box was rebuilt in
+8.6 s against 34 s for its first build (x86). A rebuild ends that process first. Deleting the
+folder is safe; the cells are then read again.
 
 Folders of GeoJSON layers exported by `scripts/enc-to-geojson.sh` for earlier versions are no
 longer read: convert the original `.000` cells in the charts provider instead. Such a folder

package/lib/box-status.js

@@ -1,9 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPending = void 0;
 exports.rebuildStatus = rebuildStatus;
+exports.noIndexReason = noIndexReason;
+exports.phaseText = phaseText;
 exports.boxSummary = boxSummary;
 const box_sizing_1 = require("./box-sizing");
 const chart_box_1 = require("./engine/chart-box");
+const index_loader_1 = require("./index-loader");
 function rebuildStatus(r, now) {
     return {
         startedAt: new Date(r.startedAt).toISOString(),
@@ -13,6 +17,21 @@ function rebuildStatus(r, now) {
         ...(r.estimateMs === undefined ? {} : { estimateMs: r.estimateMs })
     };
 }
+/** Whether `reason` is one of PENDING_REASONS, maybe with a note (`; …`) or detail (`: …`). */
+const isPending = (reason) => [...index_loader_1.PENDING_REASONS].some((p) => reason.startsWith(p) && /^(?:$|[;:] )/.test(reason.slice(p.length)));
+exports.isPending = isPending;
+/**
+ * Why there is no index: `reason`, or what the first chart box build is doing while it runs,
+ * as the vessel position it waited for has come.
+ */
+function noIndexReason(reason, box) {
+    const why = reason ?? "no chart index loaded";
+    if (box?.rebuilding && why.startsWith(index_loader_1.BOX_WAITING_REASON)) {
+        return box.phase ? `${index_loader_1.BOX_BUILDING_REASON}: ${box.phase}` : index_loader_1.BOX_BUILDING_REASON;
+    }
+    return why;
+}
+/** What a box build in progress is doing, with its count where it gave one. */
 function phaseText(r) {
     const of = r.done !== undefined && r.total !== undefined ? ` ${r.done}/${r.total}` : "";
     switch (r.phase) {

package/lib/cell-warm.js

@@ -0,0 +1,110 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.warmCells = warmCells;
+exports.startWarming = startWarming;
+exports.boxWarmer = boxWarmer;
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const worker_threads_1 = require("worker_threads");
+const child_process_1 = require("./foundation/child-process");
+const index_loader_1 = require("./index-loader");
+const cell_cache_1 = require("./ingest/cell-cache");
+const cell_source_1 = require("./ingest/cell-source");
+const enc_read_process_1 = require("./ingest/enc-read-process");
+const build_box_1 = require("./spatial/build-box");
+/** Reads the cells of `job.around` the cache lacks into it; resolves with how many were read. */
+async function warmCells(job, reader = enc_read_process_1.readInProcess) {
+    const cells = (0, index_loader_1.cellSources)(job.cellsDir).filter(cell_source_1.isEncFile);
+    const cache = cell_cache_1.LayerCache.open(job.cacheDir, cells);
+    if (!cache) {
+        return 0;
+    }
+    cache.hold((0, build_box_1.boxCells)(cells, job.hold, job.cacheDir));
+    const want = (0, build_box_1.boxCells)(cells, job.around, job.cacheDir).filter((f) => !cache.has(f));
+    let read = 0;
+    for (const file of want) {
+        const layers = (await reader([file])).get(file);
+        if (layers) {
+            cache.put(file, layers);
+            read++;
+        }
+        // One cell's layers held at a time.
+        await cache.flush();
+    }
+    return read;
+}
+/**
+ * Runs `job` in a child process from the compiled `script`, its heap capped at `heapMb`;
+ * `done` gets its reply, or why it ended without one, unless it was stopped.
+ */
+function startWarming(job, heapMb, done, script = path_1.default.join(__dirname, "cell-warm.js")) {
+    const { child, stderr } = (0, child_process_1.forkLimited)(script, heapMb, true);
+    let stopped = false;
+    let reply;
+    const closed = new Promise((resolve) => {
+        child.once("close", (code) => {
+            if (!stopped) {
+                done(reply ?? { error: `cell cache warming exited with ${code ?? "a signal"}: ${stderr()}` });
+            }
+            resolve();
+        });
+    });
+    child.once("error", () => undefined);
+    child.on("message", (m) => (reply = m));
+    child.send(job, () => undefined);
+    return {
+        stop: () => {
+            stopped = true;
+            (0, child_process_1.killGroup)(child);
+            return closed;
+        }
+    };
+}
+/** One run at a time through `start`; a run that cannot start is reported to `error`. */
+function boxWarmer(start, error) {
+    let running;
+    let stopped = false;
+    const end = () => {
+        const r = running;
+        running = undefined;
+        return r ? r.stop() : Promise.resolve();
+    };
+    return {
+        boxInUse: (bbox, reachKm) => {
+            if (stopped) {
+                return;
+            }
+            void end();
+            try {
+                running = start((0, build_box_1.growBbox)(bbox, reachKm), bbox);
+            }
+            catch (err) {
+                error(`filling the cell cache failed: ${err.message}`);
+            }
+        },
+        beforeBuild: end,
+        stop: () => {
+            stopped = true;
+            void end();
+        }
+    };
+}
+if (worker_threads_1.isMainThread && require.main === module && process.send) {
+    (0, child_process_1.exitWithParent)();
+    try {
+        // Behind the server and the look-ahead, whatever the cores.
+        os_1.default.setPriority(19);
+    }
+    catch {
+        // Not permitted: it runs at the server's priority.
+    }
+    process.once("message", (job) => {
+        warmCells(job)
+            .then((read) => ({ read }), (err) => ({ error: err.message }))
+            .then(child_process_1.sendToParent)
+            .finally(() => process.exit(0));
+    });
+}

package/lib/index-loader.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.failedLoad = exports.cellCacheDir = exports.SYNC_LOAD_BYTES = exports.PENDING_REASONS = exports.BOX_WAITING_REASON = exports.WFS_WAITING_REASON = exports.LOADING_REASON = exports.BUILDING_REASON = void 0;
+exports.failedLoad = exports.cellCacheDir = exports.SYNC_LOAD_BYTES = exports.PENDING_REASONS = exports.BOX_BUILDING_REASON = exports.BOX_WAITING_REASON = exports.WFS_WAITING_REASON = exports.LOADING_REASON = exports.BUILDING_REASON = void 0;
 exports.cellSources = cellSources;
 exports.cellsMissing = cellsMissing;
 exports.savedCatalogue = savedCatalogue;
@@ -27,12 +27,15 @@ exports.BUILDING_REASON = "building chart index";
 exports.LOADING_REASON = "loading chart index";
 exports.WFS_WAITING_REASON = "waiting for the first Traficom WFS download";
 exports.BOX_WAITING_REASON = "waiting for the vessel position to build the chart box";
+/** Why there is no index while the first chart box around the vessel is built. */
+exports.BOX_BUILDING_REASON = "building the chart box around the vessel";
 /** Reasons that mean the index is on its way, not that loading it failed. */
 exports.PENDING_REASONS = new Set([
     exports.BUILDING_REASON,
     exports.LOADING_REASON,
     exports.WFS_WAITING_REASON,
-    exports.BOX_WAITING_REASON
+    exports.BOX_WAITING_REASON,
+    exports.BOX_BUILDING_REASON
 ]);
 /**
  * A saved pyramid.bin larger than this is read and inflated off the event

package/lib/index.js

@@ -66,7 +66,7 @@ function stopPlugin(app, clock, state) {
  * Restarts the plugin once the shared ENC cells it reads changed: a start compares them with the
  * saved index and rebuilds it when they did. A server without a restart callback logs instead.
  */
-function watchShared(app, clock, collection, restart) {
+function watchShared(app, clock, collection, restart, sameCells) {
     return (0, shared_enc_1.watchSharedCells)(collection, clock, () => {
         if (restart) {
             restart();
@@ -74,7 +74,64 @@ function watchShared(app, clock, collection, restart) {
         else {
             app.error("the shared ENC cells changed; restart the plugin to index them");
         }
-    });
+    }, sameCells ? { sameCells } : {});
+}
+/** The stamps of the S-57 cells under `dir`, as one string; undefined when it cannot be read. */
+function cellsStamp(dir) {
+    try {
+        return (0, index_loader_1.sourceKeys)((0, index_loader_1.cellSources)(dir)).join("\n");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Watches the charts provider's cells in use (`watchShared`). A provider publishing later the
+ * cells read at start restarts nothing: the reason shown loses its note that it had not started.
+ */
+function watchAtStart(app, clock, state, plan, restart) {
+    const { config, load } = state;
+    const collection = config?.chartsProviderEnc;
+    if (!config || collection === undefined) {
+        return undefined;
+    }
+    const same = sameCellsAsStart(config.cellsDir, collection);
+    const renote = () => {
+        if ("load" in plan && state.load === load && load?.reason !== undefined) {
+            const fresh = (0, shared_enc_1.noteSharedCells)(plan.load, config);
+            state.load = fresh;
+            if (!fresh.index && fresh.reason !== undefined) {
+                state.monitor?.noIndex(fresh.reason);
+            }
+        }
+    };
+    const quiet = same &&
+        ((root) => {
+            const unchanged = same(root);
+            if (unchanged) {
+                renote();
+            }
+            return unchanged;
+        });
+    return watchShared(app, clock, collection, restart, quiet);
+}
+/**
+ * Whether a charts provider that publishes its store later than this plugin starts, as it does
+ * once its charts are loaded, publishes the cells read at start: the same directory, the same
+ * cells. Undefined when the provider was there at start, or nothing was read.
+ */
+function sameCellsAsStart(cellsDir, collection) {
+    if ((0, shared_enc_1.sharedEncApi)() !== undefined || cellsDir === undefined) {
+        return undefined;
+    }
+    const stamp = cellsStamp(cellsDir);
+    if (stamp === undefined) {
+        return undefined;
+    }
+    return (root) => {
+        const dir = collection === shared_enc_1.ALL_COLLECTIONS ? root : path_1.default.join(root, collection);
+        return path_1.default.resolve(dir) === path_1.default.resolve(cellsDir) && cellsStamp(dir) === stamp;
+    };
 }
 /**
  * The admin form for this server: the essentials with expert settings
@@ -145,9 +202,7 @@ module.exports = function underkeel(app, clock = monitor_1.SYSTEM_CLOCK, fetch =
                 state.zoneErrors = errors;
                 errors.forEach((e) => app.error(e));
             });
-            shared = config.chartsProviderEnc
-                ? watchShared(app, clock, config.chartsProviderEnc, restart && (() => restart(migration.config)))
-                : undefined;
+            shared = watchAtStart(app, clock, state, plan, restart && (() => restart(migration.config)));
             (0, assets_1.mountAssets)(app);
             app.registerResourceProvider((0, manifest_1.manifestProvider)(VERSION));
         },

package/lib/ingest/cell-cache.js

@@ -68,8 +68,8 @@ function writeQuietly(file, data) {
         fs_1.default.rmSync(tmp, { force: true });
     }
 }
-/** The layers in `bytes` filed under `key`; "stale" for another key, "corrupt" for a damaged entry. */
-function decodeEntry(bytes, key) {
+/** The entry's header and where its body lies; "corrupt" for a damaged entry. */
+function entryHead(bytes) {
     const end = bytes.length - SUM_BYTES;
     const headAt = MAGIC.length + 4;
     if (end < headAt || !bytes.subarray(0, MAGIC.length).equals(MAGIC)) {
@@ -79,16 +79,27 @@ function decodeEntry(bytes, key) {
         return "corrupt";
     }
     const bodyAt = headAt + bytes.readUInt32LE(MAGIC.length);
-    let head;
+    try {
+        return bodyAt > end
+            ? "corrupt"
+            : { head: JSON.parse(bytes.toString("utf8", headAt, bodyAt)), bodyAt, end };
+    }
+    catch {
+        return "corrupt";
+    }
+}
+/** The layers in `bytes` filed under `key`; "stale" for another key, "corrupt" for a damaged entry. */
+function decodeEntry(bytes, key) {
+    const entry = entryHead(bytes);
+    if (entry === "corrupt") {
+        return entry;
+    }
+    const { head, bodyAt, end } = entry;
+    if (head.key !== key) {
+        return "stale";
+    }
     let raw;
     try {
-        if (bodyAt > end) {
-            return "corrupt";
-        }
-        head = JSON.parse(bytes.toString("utf8", headAt, bodyAt));
-        if (head.key !== key) {
-            return "stale";
-        }
         raw = zlib_1.default.brotliDecompressSync(bytes.subarray(bodyAt, end));
     }
     catch {
@@ -188,6 +199,36 @@ class LayerCache {
         }
         return typeof layers === "string" ? undefined : layers;
     }
+    /**
+     * Whether an entry for `file` as its files are now is kept, checked whole but not
+     * decompressed; a damaged one is removed.
+     */
+    has(file) {
+        try {
+            const { name, key } = this.identify(file, (0, enc_wasm_1.encStamp)(file));
+            const entry = path_1.default.join(this.dir, name);
+            const found = entryHead(fs_1.default.readFileSync(entry));
+            if (found === "corrupt") {
+                fs_1.default.rmSync(entry, { force: true });
+                return false;
+            }
+            return found.head.key === key;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Keeps the entries of `files` from being dropped to make room, as if this build used them. */
+    hold(files) {
+        for (const file of files) {
+            try {
+                this.used.add(entryName(fs_1.default.realpathSync(file)));
+            }
+            catch {
+                // Gone: nothing to keep.
+            }
+        }
+    }
     /**
      * Files the layers just read from `file`, compressed off the event loop; `flush` waits for
      * the write. Layers of a cell whose files changed while it was read are not kept: they are
@@ -276,19 +317,20 @@ exports.LayerCache = LayerCache;
  * from, and filing those it reads. With every cell kept, gdal3.js is not started.
  */
 function cachedReader(reader, cache) {
-    return async (files) => {
+    return async (files, onRead) => {
         const out = new Map();
         const read = [];
         for (const file of new Set(files)) {
             const layers = cache.get(file);
             if (layers) {
                 out.set(file, layers);
+                onRead?.(file);
             }
             else {
                 read.push(file);
             }
         }
-        for (const [file, layers] of await reader(read)) {
+        for (const [file, layers] of await reader(read, onRead)) {
             out.set(file, layers);
             cache.put(file, layers);
         }

package/lib/ingest/enc-read-process.js

@@ -6,10 +6,11 @@ const worker_threads_1 = require("worker_threads");
 const child_process_1 = require("../foundation/child-process");
 const enc_wasm_1 = require("./enc-wasm");
 /** Reads on the calling thread; the WebAssembly memory stays with it. */
-const readInProcess = async (files) => {
+const readInProcess = async (files, onRead) => {
     const out = new Map();
-    for (const file of files) {
+    for (const file of new Set(files)) {
         out.set(file, await (0, enc_wasm_1.readEncLayers)(file));
+        onRead?.(file);
     }
     return out;
 };
@@ -20,7 +21,7 @@ exports.readInProcess = readInProcess;
  * that exits before every cell has come back fails the read.
  */
 function readInChild(heapMb, script = __filename) {
-    return (files) => {
+    return (files, onRead) => {
         const want = [...new Set(files)];
         if (want.length === 0) {
             return Promise.resolve(new Map());
@@ -35,6 +36,7 @@ function readInChild(heapMb, script = __filename) {
                 }
                 else if (m.file !== undefined && m.layers) {
                     out.set(m.file, (0, enc_wasm_1.sharedLayers)(new Map(Object.entries(m.layers))));
+                    onRead?.(m.file);
                 }
             });
             child.once("error", (err) => (failure ??= err));

package/lib/monitor.js

@@ -11,7 +11,7 @@ const notify_1 = require("./engine/notify");
 const state_1 = require("./foundation/state");
 const integrity_1 = require("./model/integrity");
 const vessel_1 = require("./model/vessel");
-const index_loader_1 = require("./index-loader");
+const box_status_1 = require("./box-status");
 const wfs_1 = require("./ingest/wfs");
 const water_level_service_1 = require("./water-level-service");
 const notifications_1 = require("./notifications");
@@ -262,7 +262,7 @@ class Monitor {
         if (!this.index) {
             return {
                 state: "off",
-                reason: this.indexReason ?? "no chart index loaded",
+                reason: (0, box_status_1.noIndexReason)(this.indexReason, this.chartBox?.()),
                 clearance: null,
                 clearanceSigma: null,
                 risk: null,
@@ -331,8 +331,8 @@ class Monitor {
         const now = this.clock.now();
         if (!this.index) {
             // The engine is off either way; a pending reason is a status, any other an error.
-            const reason = this.indexReason ?? "no chart index loaded";
-            if (index_loader_1.PENDING_REASONS.has(reason)) {
+            const reason = (0, box_status_1.noIndexReason)(this.indexReason, this.chartBox?.());
+            if ((0, box_status_1.isPending)(reason)) {
                 this.status.status(boxNote ? `${reason} · ${boxNote}` : reason, now);
             }
             else {

package/lib/shared-enc.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AREA_ERROR_RETRY_MS = exports.ALL_COLLECTIONS = exports.CHARTS_PROVIDER_ID = void 0;
+exports.AREA_ERROR_RETRY_MS = exports.PROVIDER_ABSENT = exports.ALL_COLLECTIONS = exports.CHARTS_PROVIDER_ID = void 0;
 exports.sharedEncApi = sharedEncApi;
 exports.sharedEncRoot = sharedEncRoot;
 exports.sharedCellsDir = sharedCellsDir;
@@ -97,14 +97,20 @@ function collectionsHint(api = sharedEncApi()) {
             .map((c) => `${c.id} (${c.kind === "chart-set" ? "chart set" : "converted chart"}, ${c.cellCount} cells)`)
             .join(", ")}.`;
 }
+/**
+ * What is said of a charts provider whose store is not published: at a server start it is
+ * published only once the provider's charts are loaded, after this plugin has started.
+ */
+exports.PROVIDER_ABSENT = "Charts Provider is not running or still starting";
 /**
  * Why the charts provider's `collection` holds no cells to read, as it tells it, or that it is
  * not running; undefined when it is ready, or cannot tell. A provider started later restarts
- * the plugin (`watchShared`), so the note is read again then.
+ * the plugin (`watchShared`) unless it shares the cells read at start; then only this note is
+ * read again (`watchAtStart` in index.ts).
  */
 function sharedCellsNote(collection, api = sharedEncApi()) {
     if (!api) {
-        return "Charts Provider is not running";
+        return exports.PROVIDER_ABSENT;
     }
     if (collection === exports.ALL_COLLECTIONS) {
         return collectionsHint(api)?.startsWith("Charts Provider shares no")
@@ -166,18 +172,28 @@ function requestSharedArea(bbox, api = sharedEncApi()) {
             accepted: false,
             started: false,
             reason: err.message,
-            retryAfterMs: exports.AREA_ERROR_RETRY_MS
+            retryAfterMs: exports.AREA_ERROR_RETRY_MS,
+            failed: true
         };
     }
 }
+/** A comparison that throws counts as cells changed, so the plugin restarts rather than keep them. */
+function safely(f) {
+    try {
+        return f();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Calls `onChange` once the cells of `collection` (any, for ALL_COLLECTIONS) changed and
  * settled. While the charts provider has not published its API, looks for it every `pollMs`,
  * and after `waitMs` every `slowPollMs` for as long as the watch runs, since it may start any
  * time; meanwhile the cells are read as found at start. An API that appears later counts as
- * a change: the provider may have written cells meanwhile, or keep its store elsewhere than
- * the default path the cells were read from, and the restart rebuilds the index only when
- * the cells it finds differ.
+ * a change, unless `sameCells` finds its store holds the cells read at start: the provider
+ * may have written cells meanwhile, or keep its store elsewhere than the default path the
+ * cells were read from. It is asked once subscribed, so a write after it is heard.
  */
 function watchSharedCells(collection, clock, onChange, opts = {}) {
     const settleMs = opts.settleMs ?? 5_000;
@@ -185,6 +201,7 @@ function watchSharedCells(collection, clock, onChange, opts = {}) {
     const pollMs = opts.pollMs ?? 5_000;
     const slowPollMs = opts.slowPollMs ?? 60_000;
     const started = clock.now();
+    const sameAsStart = (root) => safely(() => opts.sameCells?.(root) ?? false);
     let unsubscribe;
     let changedAt;
     let timer;
@@ -212,7 +229,9 @@ function watchSharedCells(collection, clock, onChange, opts = {}) {
         });
         if (late) {
             stopTimer();
-            changed();
+            if (!sameAsStart(api.root)) {
+                changed();
+            }
         }
         return true;
     };

package/lib/spatial/build-survey.js

@@ -28,9 +28,14 @@ class EncReads {
         if (files.length === 0) {
             return;
         }
-        const done = this.layers.size;
-        (0, build_progress_1.reportProgress)({ phase: "cells", done, total: done + files.length });
-        for (const [file, layers] of await this.reader(files)) {
+        const total = this.layers.size + new Set(files).size;
+        let done = this.layers.size;
+        (0, build_progress_1.reportProgress)({ phase: "cells", done, total });
+        const read = await this.reader(files, () => {
+            done = Math.min(total, done + 1);
+            (0, build_progress_1.reportProgress)({ phase: "cells", done, total });
+        });
+        for (const [file, layers] of read) {
             this.layers.set(file, layers);
         }
         (0, build_progress_1.reportProgress)({ phase: "cells", done: this.layers.size, total: this.layers.size });

package/lib/status-report.js

@@ -3,12 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.statusReport = statusReport;
 const public_text_1 = require("./foundation/public-text");
 /** Body of `GET /status`: engine state, index provenance and look-ahead summary; `?summary` without the per-cell lists. */
-function indexSection(load, summary) {
+function indexSection(load, monitor, summary) {
     const index = load?.index;
+    // Without an index the engine's reason is why, and follows a first box build as it runs.
+    const reason = !index && monitor?.last.state === "off" ? monitor.last.reason : load?.reason;
     return {
         loaded: index !== undefined,
         built: load?.built ?? false,
-        reason: (0, public_text_1.publicReason)(load?.reason),
+        reason: (0, public_text_1.publicReason)(reason),
         nodes: index?.pyramid.count ?? 0,
         hazards: index?.hazards.size ?? 0,
         ...(summary ? {} : { cells: index?.catalogue.cells ?? [] })
@@ -38,7 +40,7 @@ function statusReport(s) {
     const wfs = s.wfs?.status();
     return {
         ...(s.monitor ? monitorSection(s.monitor, summary) : { engine: s.stopped, vessel: [] }),
-        index: indexSection(s.load, summary),
+        index: indexSection(s.load, s.monitor, summary),
         livechart: s.livechart?.status() ?? null,
         wfs: wfs && s.wfs?.downloads ? { ...wfs, lastError: (0, public_text_1.publicReason)(wfs.lastError) } : null,
         chartBox: s.wfs ? boxSection(s.wfs) : null,

package/lib/wfs-service.js

@@ -9,6 +9,7 @@ const path_1 = __importDefault(require("path"));
 const fan_1 = require("./engine/fan");
 const geo_1 = require("./foundation/geo");
 const box_sizing_1 = require("./box-sizing");
+const wfs_worker_1 = require("./wfs-worker");
 const box_status_1 = require("./box-status");
 const cell_reader_1 = require("./ingest/cell-reader");
 const wfs_1 = require("./ingest/wfs");
@@ -24,6 +25,8 @@ Object.defineProperty(exports, "workerHeapLimitMb", { enumerable: true, get: fun
 Object.defineProperty(exports, "workerRefresher", { enumerable: true, get: function () { return build_process_1.workerRefresher; } });
 /** Position checks; a download is due only when the vessel has left the inner half of the box. */
 const CHECK_EVERY_MS = 10_000;
+/** How often a service started before the first position looks for it, ms. */
+const FIRST_FIX_EVERY_MS = 1000;
 /** No two downloads start closer together than this, and after a failure the wait is longer. */
 const MIN_INTERVAL_MS = 60_000;
 const RETRY_AFTER_ERROR_MS = 300_000;
@@ -62,6 +65,8 @@ class WfsService {
     lastAttempt = -Infinity;
     lastError;
     timer;
+    /** Looks for the first position while none has come. */
+    firstFix;
     controller;
     rebuild;
     /** Lowered for this run when a box ran its build out of memory. */
@@ -108,14 +113,41 @@ class WfsService {
     start() {
         const check = () => void this.check().catch((err) => this.deps.error(`${this.label}: ${err.message}`));
         this.timer = this.deps.clock.setInterval(check, CHECK_EVERY_MS);
+        // A server starts this plugin before the position arrives: the first box is checked once
+        // one does, not up to CHECK_EVERY_MS later.
+        if (!this.hasPosition()) {
+            this.firstFix = this.deps.clock.setInterval(() => {
+                if (this.hasPosition()) {
+                    this.stopFirstFix();
+                    check();
+                }
+            }, FIRST_FIX_EVERY_MS);
+        }
         check();
     }
+    /** Whether a position is known; one that cannot be read is reported by the check. */
+    hasPosition() {
+        try {
+            return this.deps.position() !== undefined;
+        }
+        catch {
+            return true;
+        }
+    }
+    stopFirstFix() {
+        if (this.firstFix !== undefined) {
+            this.deps.clock.clearInterval(this.firstFix);
+            this.firstFix = undefined;
+        }
+    }
     stop() {
         if (this.timer !== undefined) {
             this.deps.clock.clearInterval(this.timer);
             this.timer = undefined;
         }
+        this.stopFirstFix();
         this.controller?.abort();
+        this.deps.warm?.stop();
     }
     status() {
         const rebuild = this.rebuild && (0, box_status_1.rebuildStatus)(this.rebuild, this.deps.clock.now());
@@ -138,9 +170,11 @@ class WfsService {
         const bbox = this.handed ?? this.box?.bbox;
         const lastMs = this.box?.durationMs;
         const note = this.deps.area?.note();
+        const run = this.rebuild;
         return {
             ...(bbox ? { bbox } : {}),
             rebuilding: this.busy,
+            ...(this.busy && run ? { phase: (0, box_status_1.phaseText)((0, box_status_1.rebuildStatus)(run, this.deps.clock.now())) } : {}),
             failed: !this.busy && this.lastError !== undefined,
             ...(lastMs === undefined ? {} : { lastMs }),
             summary: this.status().summary,
@@ -311,37 +345,11 @@ class WfsService {
         const run = this.begin(now, controller);
         const { radiusKm } = run;
         try {
+            await this.deps.warm?.beforeBuild();
             const centre = this.centreAhead(pos, radiusKm, run.estimateMs ?? this.refreshMs());
             const bbox = (0, wfs_1.boxAround)(centre, radiusKm);
             this.announce(bbox, now);
-            const config = this.deps.config;
-            const { inBox, cellsDir } = this.deps;
-            // With WFS depths alone in use an empty cells directory loses nothing.
-            const cells = this.deps.index()?.catalogue.cells.some((c) => c.source !== wfs_1.WFS_SOURCE);
-            const { index, features } = await this.deps.refresh({
-                download: "url" in config
-                    ? {
-                        url: config.url,
-                        bbox,
-                        dir: this.cellDir,
-                        now: new Date(now).toISOString(),
-                        catzoc: config.catzoc
-                    }
-                    : undefined,
-                cellsDir,
-                // WFS depths are built whatever ENC the charts provider has, but an index of
-                // charted hazards is kept while its cells are away, not replaced by depths alone.
-                cellsRequired: !("url" in config) || cells === true,
-                box: inBox ? bbox : undefined,
-                build: {
-                    dirs: "url" in config ? [this.cellDir] : [],
-                    leafZoom: this.deps.leafZoom,
-                    indexDir: this.deps.indexDir,
-                    ...(this.deps.cacheDir === undefined ? {} : { cacheDir: this.deps.cacheDir }),
-                    source: this.deps.source,
-                    ...(inBox ? {} : { changed: [this.cellDir] })
-                }
-            }, controller.signal, (progress) => {
+            const { index, features } = await this.deps.refresh((0, wfs_worker_1.refreshJob)(this.deps, this.cellDir, bbox, now), controller.signal, (progress) => {
                 if (this.rebuild === run) {
                     run.progress = progress;
                 }
@@ -359,6 +367,8 @@ class WfsService {
             this.box = box;
             this.lastError = undefined;
             await this.handOver(index, bbox);
+            // The next box is centred inside this one, at most MAX_LEAD of its radius ahead.
+            this.deps.warm?.boxInUse(bbox, radiusKm * (1 + MAX_LEAD));
         }
         catch (err) {
             if (controller.signal.aborted) {

package/lib/wfs-wiring.js

@@ -18,6 +18,7 @@ const wfs_1 = require("./ingest/wfs");
 const livechart_service_1 = require("./livechart-service");
 const rebind_1 = require("./livechart/rebind");
 const box_sizing_1 = require("./box-sizing");
+const cell_warm_1 = require("./cell-warm");
 const wfs_service_1 = require("./wfs-service");
 const pause = () => new Promise((resolve) => setImmediate(resolve));
 /** The catalogues list the same cells in the same order, the WFS cell aside. */
@@ -94,7 +95,9 @@ function areaRequests(config, app) {
 /** How soon, and how late, a box is asked about again: Charts Provider starting, or busy. */
 exports.AREA_ASK_MIN_MS = 60_000;
 exports.AREA_ASK_MAX_MS = 30 * 60_000;
-const ASK_STARTING_MS = 5 * 60_000;
+/** A charts provider not running yet is most likely starting: at a server start it publishes
+ * its store once its charts are loaded, after this plugin started. */
+const ASK_STARTING_MS = exports.AREA_ASK_MIN_MS;
 /**
  * What the provider said of a box, as the status gives it when the vessel has no chart
  * coverage: from its answer to the area request and the cells it has stored there (`cells`,
@@ -124,7 +127,7 @@ function areaNote(answer, cells, running = (0, shared_enc_1.sharedEncApi)() !==
 function unaskedNote(running) {
     return running
         ? "Charts Provider is too old to be asked for the ENC around the vessel: update it"
-        : "Charts Provider is not running";
+        : shared_enc_1.PROVIDER_ABSENT;
 }
 /**
  * Asks the charts provider for each box's cells, logging its answer when it changes, and says
@@ -133,11 +136,18 @@ function unaskedNote(running) {
 function askForArea(app) {
     let last;
     let note;
+    /** Whether the last ask found no charts provider running. */
+    let askedAbsent = false;
     return {
-        // A provider stopped since its answer leaves that answer stale: it is not running now.
-        note: () => ((0, shared_enc_1.sharedEncApi)() === undefined ? unaskedNote(false) : note),
+        // A provider stopped since its answer leaves that answer stale: it is not running now. One
+        // started since it was found absent has not been asked yet: it is asked again shortly.
+        note: () => {
+            const running = (0, shared_enc_1.sharedEncApi)() !== undefined;
+            return !running ? unaskedNote(false) : askedAbsent ? undefined : note;
+        },
         ask: (bbox) => {
             const api = (0, shared_enc_1.sharedEncApi)();
+            askedAbsent = api === undefined;
             const answer = (0, shared_enc_1.requestSharedArea)(bbox, api);
             note = areaNote(answer, answer === undefined ? undefined : (0, shared_enc_1.sharedCellsIn)(bbox, api), !!api);
             const line = answer === undefined
@@ -145,11 +155,15 @@ function askForArea(app) {
                 : `Charts Provider, asked for the ENC around the vessel: ${answer.reason}`;
             if (line !== last) {
                 last = line;
-                if (answer?.accepted === true) {
-                    app.debug(line);
+                // A refusal follows the provider's own setting, and a provider not running yet is most
+                // likely starting; the status says both where the vessel lacks coverage. A provider too
+                // old to be asked, or one whose answer threw, needs the user.
+                const fault = answer === undefined ? api !== undefined : answer.failed === true;
+                if (fault) {
+                    app.error(line);
                 }
                 else {
-                    app.error(line);
+                    app.debug(line);
                 }
             }
             const ms = answer === undefined ? ASK_STARTING_MS : answer.retryAfterMs;
@@ -159,15 +173,28 @@ function askForArea(app) {
         }
     };
 }
+/** Fills the cell cache around the box, saying in the debug log how many cells it read. */
+function warmAround(w, job) {
+    return (0, cell_warm_1.startWarming)(job, (0, wfs_service_1.workerHeapLimitMb)(), (reply) => {
+        if (reply.error !== undefined) {
+            w.app.debug(`cell cache: filling it around the chart box failed: ${reply.error}`);
+        }
+        else if (reply.read) {
+            w.app.debug(`cell cache: read ${reply.read} cells around the chart box`);
+        }
+    });
+}
 function startWfs(w, config, dirName = "wfs") {
     const dir = path_1.default.join(w.app.getDataDirPath(), dirName);
     fs_1.default.mkdirSync(dir, { recursive: true });
     const area = areaRequests(w.config, w.app);
+    const cacheDir = (0, index_loader_1.cellCacheDir)(w.app.getDataDirPath());
+    const { cellsDir } = w.config;
     return new wfs_service_1.WfsService({
         config,
         dir,
         indexDir: w.config.indexDir ?? path_1.default.join(w.app.getDataDirPath(), "index"),
-        cacheDir: (0, index_loader_1.cellCacheDir)(w.app.getDataDirPath()),
+        cacheDir,
         leafZoom: w.config.leafZoom,
         source: (0, index_source_1.indexSource)(w.config),
         area,
@@ -183,6 +210,12 @@ function startWfs(w, config, dirName = "wfs") {
         lookahead: w.config.lookahead,
         maxRadiusKm: w.config.boxMaxRadiusKm || (0, box_sizing_1.autoCapKm)((0, wfs_service_1.workerHeapLimitMb)()),
         onIndex: (index, changed) => useIndex(w, index, changed),
+        // In processes of their own, as the builds are; an injected builder, as in the tests, gets none.
+        ...(w.build === wfs_service_1.workerBuilder && cellsDir !== undefined && w.config.boxRadiusKm > 0
+            ? {
+                warm: (0, cell_warm_1.boxWarmer)((around, hold) => warmAround(w, { cellsDir, cacheDir, around, hold }), (m) => w.app.error(m))
+            }
+            : {}),
         error: (m) => {
             w.app.error(m);
             // With no index in use the failure is why the look-ahead is off: an error, not "waiting",

package/lib/wfs-worker.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NO_FEATURES = void 0;
+exports.refreshJob = refreshJob;
 exports.refreshCells = refreshCells;
 exports.refreshBuild = refreshBuild;
 exports.runWfsJob = runWfsJob;
@@ -10,6 +11,35 @@ const wfs_1 = require("./ingest/wfs");
 const build_box_1 = require("./spatial/build-box");
 const build_progress_1 = require("./spatial/build-progress");
 const build_worker_1 = require("./spatial/build-worker");
+/** The refresh of the box `bbox`, started at `now`, with its WFS cell kept in `cellDir`. */
+function refreshJob(deps, cellDir, bbox, now) {
+    const { config, inBox, cellsDir } = deps;
+    const wfs = "url" in config ? config : undefined;
+    // With WFS depths alone in use an empty cells directory loses nothing.
+    const cells = deps.index()?.catalogue.cells.some((c) => c.source !== wfs_1.WFS_SOURCE);
+    return {
+        download: wfs && {
+            url: wfs.url,
+            bbox,
+            dir: cellDir,
+            now: new Date(now).toISOString(),
+            catzoc: wfs.catzoc
+        },
+        cellsDir,
+        // WFS depths are built whatever ENC the charts provider has, but an index of charted
+        // hazards is kept while its cells are away, not replaced by depths alone.
+        cellsRequired: !wfs || cells === true,
+        box: inBox ? bbox : undefined,
+        build: {
+            dirs: wfs ? [cellDir] : [],
+            leafZoom: deps.leafZoom,
+            indexDir: deps.indexDir,
+            ...(deps.cacheDir === undefined ? {} : { cacheDir: deps.cacheDir }),
+            source: deps.source,
+            ...(inBox ? {} : { changed: [cellDir] })
+        }
+    };
+}
 exports.NO_FEATURES = { depthAreas: 0, dredgedAreas: 0, soundings: 0 };
 /**
  * The S-57 cells under `cellsDir`, found before the download. Scanning and stamping the 698

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-underkeel",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Under-keel clearance awareness for Signal K: look-ahead grounding risk, route checks and a living chart.",
   "main": "lib/index.js",
   "files": [