sailkick-boat 0.14.4 → 0.14.5

package/README.md

@@ -63,10 +63,19 @@ comes from the cloud **announcing bakes**, not from a clock:
 `X-Sailkick-Cache` reports `HIT` / `MISS` / `UPDATED` / `STALE` / `LIVE` per response.
 
 **Static vs dynamic — two strategies.** Tiles and app assets are **cache-first**
-(pinned, offline forever). Dynamic `/api/*` data (AIS, weather) is **network-first**:
-fetched live every time online (so AIS/weather never go stale), with the last
-response kept only as an **offline fallback** (`STALE`). Local `/api/history` and the
-patched `/api/config` are served specially (above).
+(pinned, offline forever). Dynamic `/api/*` data (AIS, weather, lightning) is
+**network-first**: fetched live every time online (so it never goes stale), with the
+last response kept only as an **offline fallback** (`STALE`). Local `/api/history` and
+the patched `/api/config` are served specially (above).
+
+**Exception — velocity tiles are pinned.** The app serves its wind/current field from
+`/api/velocity/tiles/<layer>/<runId>/<z>/<x>/<y>/<hour>.f32`. The forecast **run id is
+in the path**, so a URL's bytes never change — a new run means new URLs. Those are
+cache-first like map tiles: each tile downloads once instead of on every pan, and the
+wind particles + storm field keep rendering **offline**. The velocity *manifest*
+(`?run=latest`) stays network-first, or the boat would pin itself to a stale run
+forever. Nothing prefetches velocity tiles yet, so offline wind covers only what you
+have panned over, and old runs are not pruned.
 
 **Offline circuit breaker.** Some boat routers return errors (or hang) for outbound
 requests when the uplink is down, instead of failing cleanly. Once a fetch fails, the

package/lib/proxy/index.js

@@ -18,6 +18,20 @@ const { countBboxTiles, bboxTiles, boxAround } = require('./tiles')
 // get its live data from the boat's local SignalK and its charts/weather cached.
 // Also exposes the auth'd /plugins/sailkick-boat/p/* router handlers.
 
+// Everything under /api/ is dynamic and network-first — EXCEPT paths whose URL is
+// immutable by construction. Velocity tiles embed the forecast run id
+// (/api/velocity/tiles/<layer>/<runId>/<z>/<x>/<y>/<hour>.f32, see the app's
+// public/engine/velocity-client.js), so a given URL's bytes never change: a new
+// forecast run produces new URLs. Treating them as network-first re-downloaded the
+// whole wind field on every pan while online, and left nothing usable offline —
+// pinning them is what makes wind particles and the storm field work with no uplink.
+//
+// The velocity *manifest* is deliberately NOT in here: it resolves `run=latest` and
+// must stay live, otherwise the boat pins itself to a stale forecast run forever.
+const IMMUTABLE_API_PREFIXES = ['/api/velocity/tiles/']
+const isImmutableApi = (p) => IMMUTABLE_API_PREFIXES.some((x) => p.startsWith(x))
+const isNetworkFirst = (p) => p.startsWith('/api/') && !isImmutableApi(p)
+
 function createProxy (app, options) {
   const log = (m) => (app.debug ? app.debug('[proxy] ' + m) : console.log('[sailkick-boat:proxy]', m))
   let cfg = null
@@ -138,8 +152,10 @@ function createProxy (app, options) {
       if (req.method === 'GET' || req.method === 'HEAD') {
         const { buffer, contentType, cacheState } = await getResource({
           storeDir: cfg.storeDir, upstream: cfg.upstream, reqPath: req.url, timeoutMs: cfg.timeoutMs,
-          invalidatedAt: manifest ? manifest.invalidatedAtFor(req.url) : 0,
-          networkFirst: req.url.startsWith('/api/'), // live data (AIS, weather): fresh online, cache-fallback offline
+          // An immutable URL needs no invalidation: a bake announcement can't change
+          // bytes that are keyed by run id, so don't let an app rebuild churn them.
+          invalidatedAt: isImmutableApi(req.url) ? 0 : (manifest ? manifest.invalidatedAtFor(req.url) : 0),
+          networkFirst: isNetworkFirst(req.url), // live data (AIS, weather, lightning): fresh online, cache-fallback offline
           health
         })
         res.setHeader('Content-Type', contentType)
@@ -242,8 +258,8 @@ function createProxy (app, options) {
     try {
       const { buffer, contentType, cacheState } = await getResource({
         storeDir: cfg.storeDir, upstream: cfg.upstream, reqPath, timeoutMs: cfg.timeoutMs,
-        invalidatedAt: manifest ? manifest.invalidatedAtFor(reqPath) : 0,
-        networkFirst: reqPath.startsWith('/api/'), health
+        invalidatedAt: isImmutableApi(reqPath) ? 0 : (manifest ? manifest.invalidatedAtFor(reqPath) : 0),
+        networkFirst: isNetworkFirst(reqPath), health
       })
       res.set('Content-Type', contentType)
       res.set('X-Sailkick-Cache', cacheState)
@@ -390,4 +406,4 @@ function createProxy (app, options) {
   return { start, stop, status, handleGet, handlePrefetch, handlePrefetchRegion, handleClear, _serveMirror: serveMirror, _serveConfig: serveConfig, _manifest: () => manifest, _seeder: () => seeder, _startAreaPrefetch: startAreaPrefetch, _area: () => area }
 }
 
-module.exports = { createProxy }
+module.exports = { createProxy, isNetworkFirst, isImmutableApi }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sailkick-boat",
-  "version": "0.14.4",
+  "version": "0.14.5",
   "description": "EARLY ALPHA — cloud telemetry + offline maps for sailkick boats (www.sailkick.io; register on the web, paste the write token). Gapless boat→cloud telemetry sync to InfluxDB, and a local proxy that keeps the sailkick app and its charts/maps working fully offline on board.",
   "main": "index.js",
   "scripts": {