sailkick-boat 0.13.4

package/lib/proxy/index.js

@@ -0,0 +1,393 @@
+'use strict'
+
+const path = require('path')
+const http = require('http')
+const net = require('net')
+const { getResource, clearStore } = require('./cache')
+const { createManifest } = require('./manifest')
+const { createSeeder } = require('./seed')
+const { countBboxTiles, bboxTiles, boxAround } = require('./tiles')
+
+// Caching proxy module. The standalone server (origin root, `proxyPort`) is what
+// the browser points at. It routes by path:
+//   - localPaths (default /signalk) -> LOCAL SignalK (live telemetry, no cache),
+//     including the WebSocket stream (transparent upgrade relay);
+//   - everything else -> mirror the sailkick host, GET cached (offline-first),
+//     non-GET live pass-through.
+// This makes the app (served from the mirror, connecting same-origin to SignalK)
+// 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.
+
+function createProxy (app, options) {
+  const log = (m) => (app.debug ? app.debug('[proxy] ' + m) : console.log('[sailkick-boat:proxy]', m))
+  let cfg = null
+  let server = null
+  let manifest = null
+  let seeder = null
+  let area = null // "download around the boat" progress
+  let stopping = false
+  // Shared upstream circuit breaker: once a fetch fails offline, uncached requests
+  // fast-fail for cooldownMs instead of each hanging on the fetch timeout (which
+  // would starve the browser's ~6-connection pool and block cached tiles too).
+  const health = { downUntil: 0, cooldownMs: 15000 }
+
+  function start () {
+    if (!options.sailkickUrl) { log('not started — no sailkickUrl configured'); return }
+    stopping = false
+    const dataDir = (app.getDataDirPath && app.getDataDirPath()) || '.'
+    cfg = {
+      upstream: options.sailkickUrl.replace(/\/+$/, ''),
+      storeDir: options.storeDir || path.join(dataDir, 'store'),
+      timeoutMs: options.requestTimeoutMs || 20000,
+      localSignalk: (options.localSignalkUrl || 'http://127.0.0.1:3000').replace(/\/+$/, ''),
+      localPaths: (options.localPaths && options.localPaths.length) ? options.localPaths : ['/signalk'],
+      telemetryPath: options.telemetryPath || '/ws/telemetry',
+      history: options.history || null,
+      openAccess: options.openAccess !== false
+    }
+    log(`mirroring ${cfg.upstream}; local SignalK ${cfg.localSignalk}; store ${cfg.storeDir}`)
+
+    // Cache-manifest poller: auto-refresh a dataset lazily when the cloud
+    // announces a new bake. Tiles are otherwise pinned (no time-based expiry).
+    if (!options.manifest || options.manifest.enabled !== false) {
+      try {
+        manifest = createManifest(app, {
+          upstream: cfg.upstream,
+          storeDir: cfg.storeDir,
+          manifestPath: options.manifest && options.manifest.path,
+          pollIntervalSec: options.manifest && options.manifest.pollIntervalSec,
+          timeoutMs: cfg.timeoutMs
+        })
+        manifest.start()
+      } catch (e) { log('manifest poller start failed: ' + e.message); manifest = null }
+    }
+
+    // Global offline base seeder (coastline + seabed). Fire-and-forget; self-throttles
+    // offline via the shared `health` breaker.
+    if (!options.seed || options.seed.enabled !== false) {
+      try {
+        seeder = createSeeder(app, {
+          upstream: cfg.upstream,
+          storeDir: cfg.storeDir,
+          timeoutMs: cfg.timeoutMs,
+          health,
+          manifest,
+          coastlineMaxZoom: options.seed && options.seed.coastlineMaxZoom,
+          seabedMaxZoom: options.seed && options.seed.seabedMaxZoom,
+          concurrency: options.seed && options.seed.concurrency
+        })
+        seeder.start()
+      } catch (e) { log('seeder start failed: ' + e.message); seeder = null }
+    }
+
+    // "Download around the boat" — config-driven region prefetch (fire-and-forget).
+    try { startAreaPrefetch() } catch (e) { log('area prefetch start failed: ' + e.message) }
+
+    const port = options.proxyPort == null ? 8080 : Number(options.proxyPort)
+    if (port > 0) {
+      server = http.createServer(serveMirror)
+      server.on('upgrade', relayUpgrade) // WebSocket stream -> local SignalK
+      server.on('error', (e) => log('mirror server error: ' + e.message))
+      server.listen(port, () => log(`mirror on :${port} (local:${cfg.localPaths.join(',')} -> ${cfg.localSignalk}; else -> ${cfg.upstream})`))
+      cfg.port = port
+    }
+  }
+
+  function stop () {
+    stopping = true
+    area = null
+    try { if (seeder) seeder.stop() } catch {}
+    seeder = null
+    try { if (manifest) manifest.stop() } catch {}
+    manifest = null
+    if (server) {
+      try { if (server.closeAllConnections) server.closeAllConnections() } catch {}
+      try { server.close() } catch {}
+      server = null
+    }
+    cfg = null
+  }
+  function status () {
+    if (!cfg) return 'proxy: off'
+    const m = manifest ? '; ' + manifest.status() : ''
+    const s = seeder ? '; ' + seeder.status() : ''
+    return `proxy: mirror ${cfg.upstream}${cfg.port ? ' :' + cfg.port : ''}; live -> ${cfg.localSignalk}${m}${s}${areaStatus()}`
+  }
+
+  const isLocal = (p) => cfg.localPaths.some((lp) => p === lp || p.startsWith(lp + '/') || p.startsWith(lp + '?'))
+
+  async function serveMirror (req, res) {
+    if (!cfg) { res.statusCode = 503; res.end('proxy disabled'); return }
+    // Local history endpoints, served from the boat's InfluxDB (offline-first, full
+    // local dataset). When history isn't configured they fall through to the mirror,
+    // so an online boat still gets history from the cloud — never worse than today.
+    if (req.method === 'GET' && cfg.history && cfg.history.available()) {
+      const pathname = req.url.split('?')[0]
+      if (pathname === '/api/history/series') return cfg.history.handleSeries(req, res)
+      if (pathname === '/api/history/track') return cfg.history.handleTrack(req, res)
+    }
+    // /api/config drives the app's login gate + Trends toggle. On the single-tenant
+    // boat we serve it with auth turned off (no cloud login over the offline HTTP
+    // mirror) and history forced on when we serve it locally. All other config passes
+    // through untouched.
+    if (req.method === 'GET' && cfg.openAccess && req.url.split('?')[0] === '/api/config') {
+      return serveConfig(req, res)
+    }
+    if (isLocal(req.url)) { return passThrough(req, res, cfg.localSignalk + req.url) } // live SignalK, no cache
+    try {
+      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
+          health
+        })
+        res.setHeader('Content-Type', contentType)
+        res.setHeader('X-Sailkick-Cache', cacheState)
+        res.end(req.method === 'HEAD' ? undefined : buffer)
+      } else {
+        return passThrough(req, res, cfg.upstream + req.url)
+      }
+    } catch (e) {
+      res.statusCode = e.offline ? 504 : (e.status || 502)
+      res.end(e.offline ? 'offline and not cached' : 'proxy error')
+    }
+  }
+
+  // Serve /api/config with the login gate neutralized for the boat. Reuses the
+  // normal cache path (online fetch / offline cached copy), then rewrites just the
+  // auth flag (and historyAvailable when we serve history locally) before sending.
+  async function serveConfig (req, res) {
+    try {
+      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, health
+      })
+      let out = buffer
+      let ct = contentType
+      try {
+        const j = JSON.parse(buffer.toString('utf8'))
+        if (j && typeof j === 'object') {
+          j.auth = { ...(j.auth || {}), required: false } // single-tenant boat: no cloud login
+          if (cfg.history && cfg.history.available()) j.historyAvailable = true // served locally (InfluxDB or ring)
+          out = Buffer.from(JSON.stringify(j))
+          ct = 'application/json'
+        }
+      } catch { /* not JSON — serve as fetched */ }
+      res.setHeader('Content-Type', ct)
+      res.setHeader('X-Sailkick-Cache', cacheState)
+      res.end(req.method === 'HEAD' ? undefined : out)
+    } catch (e) {
+      res.statusCode = e.offline ? 504 : (e.status || 502)
+      res.end(e.offline ? 'offline and not cached' : 'proxy error')
+    }
+  }
+
+  // transparent HTTP relay (no cache) — forwards method/body + key headers
+  async function passThrough (req, res, target) {
+    const chunks = []
+    if (req.method !== 'GET' && req.method !== 'HEAD') { for await (const c of req) chunks.push(c) }
+    const fwd = {}
+    for (const h of ['content-type', 'authorization', 'cookie', 'accept', 'accept-language', 'user-agent']) {
+      if (req.headers[h]) fwd[h] = req.headers[h]
+    }
+    let r
+    try {
+      r = await fetch(target, { method: req.method, headers: fwd, body: chunks.length ? Buffer.concat(chunks) : undefined })
+    } catch (e) { res.statusCode = 502; res.end('upstream unreachable'); return }
+    res.statusCode = r.status
+    r.headers.forEach((v, k) => {
+      const kl = k.toLowerCase()
+      if (!['content-encoding', 'content-length', 'transfer-encoding', 'connection'].includes(kl)) {
+        try { res.setHeader(k, v) } catch {}
+      }
+    })
+    const buf = Buffer.from(await r.arrayBuffer())
+    res.end(req.method === 'HEAD' ? undefined : buf)
+  }
+
+  // WebSocket (or any HTTP upgrade) on a local path -> transparent TCP relay to
+  // the local SignalK server (so the SignalK live stream works through :8080).
+  function relayUpgrade (req, clientSocket, head) {
+    if (!cfg) { clientSocket.destroy(); return }
+    // /ws/telemetry -> the local telemetry provider (served from local SignalK)
+    if (options.telemetryUpgrade && req.url.startsWith(cfg.telemetryPath)) {
+      options.telemetryUpgrade(req, clientSocket, head); return
+    }
+    if (!isLocal(req.url)) { clientSocket.destroy(); return }
+    let u
+    try { u = new URL(cfg.localSignalk) } catch { clientSocket.destroy(); return }
+    const upstream = net.connect(Number(u.port || 80), u.hostname, () => {
+      let raw = `${req.method} ${req.url} HTTP/1.1\r\n`
+      for (let i = 0; i < req.rawHeaders.length; i += 2) raw += `${req.rawHeaders[i]}: ${req.rawHeaders[i + 1]}\r\n`
+      raw += '\r\n'
+      upstream.write(raw)
+      if (head && head.length) upstream.write(head)
+      upstream.pipe(clientSocket)
+      clientSocket.pipe(upstream)
+    })
+    // tear down both sides together so a disconnect never leaks a socket
+    const kill = () => { upstream.destroy(); clientSocket.destroy() }
+    upstream.on('error', kill); upstream.on('close', kill)
+    clientSocket.on('error', kill); clientSocket.on('close', kill)
+  }
+
+  // --- auth'd plugin router handlers (mounted at /plugins/sailkick-boat) ---
+  async function handleGet (req, res) {
+    if (!cfg) { res.status(503).send('proxy disabled'); return }
+    const rest = req.params[0] || ''
+    const qi = req.originalUrl.indexOf('?')
+    const qs = qi >= 0 ? req.originalUrl.slice(qi) : ''
+    const reqPath = '/' + rest + qs
+    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
+      })
+      res.set('Content-Type', contentType)
+      res.set('X-Sailkick-Cache', cacheState)
+      res.send(buffer)
+    } catch (e) {
+      if (e.offline) res.status(504).send('offline and not cached')
+      else res.status(e.status || 502).send('upstream error')
+    }
+  }
+
+  // POST /plugins/sailkick-boat/cache/clear — manual force-refresh. Query:
+  //   ?prefix=tiles/osm-standard   delete one tileset subtree
+  //   ?keep=tiles,terrain          delete everything except these (default)
+  async function handleClear (req, res) {
+    if (!cfg) { res.status(503).send('proxy disabled'); return }
+    const prefix = (req.query && req.query.prefix) ? String(req.query.prefix) : ''
+    const keep = (req.query && req.query.keep != null)
+      ? String(req.query.keep).split(',').map((s) => s.trim()).filter(Boolean)
+      : ['tiles', 'terrain', 'history'] // 'history' = the persistent ring log lives under storeDir
+    try {
+      const r = await clearStore({ storeDir: cfg.storeDir, keep, prefix })
+      res.json({ ok: true, ...r })
+    } catch (e) {
+      res.status(400).json({ ok: false, message: e.message })
+    }
+  }
+
+  // Warm a list of paths into the cache, bounded-concurrency, reusing the circuit
+  // breaker (so it fast-fails/goes quiet offline). 404s count as `empty` (negative-
+  // cached), not failures. Returns { cached, empty, failed }.
+  async function warmMany (paths, { concurrency = 6, onProgress } = {}) {
+    const arr = Array.isArray(paths) ? paths : [...paths]
+    let cached = 0; let empty = 0; let failed = 0; let i = 0
+    const worker = async () => {
+      while (i < arr.length && !stopping) {
+        const p = arr[i++]
+        const reqPath = p.startsWith('/') ? p : '/' + p
+        try {
+          await getResource({ storeDir: cfg.storeDir, upstream: cfg.upstream, reqPath, timeoutMs: cfg.timeoutMs, health, invalidatedAt: manifest ? manifest.invalidatedAtFor(reqPath) : 0 })
+          cached++
+        } catch (e) { if (e.status === 404) empty++; else failed++ }
+        if (onProgress) onProgress()
+      }
+    }
+    await Promise.all(Array.from({ length: Math.max(1, concurrency) }, worker))
+    return { cached, empty, failed }
+  }
+
+  const readBody = (req) => new Promise((resolve) => {
+    let raw = ''
+    req.setEncoding('utf8')
+    req.on('data', (c) => { raw += c; if (raw.length > 1e6) req.destroy() })
+    req.on('end', () => resolve(raw))
+  })
+
+  function handlePrefetch (req, res) {
+    if (!cfg) { res.status(503).send('proxy disabled'); return }
+    readBody(req).then(async (raw) => {
+      let paths = []
+      try { paths = JSON.parse(raw).paths || [] } catch { paths = raw.split(/\s+/).filter(Boolean) }
+      const r = await warmMany(paths)
+      res.json({ requested: paths.length, ...r })
+    })
+  }
+
+  // POST /plugins/sailkick-boat/prefetch/region — warm a bbox×zoom×layers rectangle
+  // for offline passage coverage. Estimates first and refuses > cap unless force.
+  function handlePrefetchRegion (req, res) {
+    if (!cfg) { res.status(503).send('proxy disabled'); return }
+    const clampInt = (v, def, lo, hi) => { const n = parseInt(v, 10); return Number.isFinite(n) ? Math.max(lo, Math.min(hi, n)) : def }
+    readBody(req).then(async (raw) => {
+      let body = {}
+      try { body = JSON.parse(raw) } catch { res.status(400).json({ ok: false, message: 'invalid JSON body' }); return }
+      const bbox = body.bbox
+      if (!Array.isArray(bbox) || bbox.length !== 4 || !bbox.every((n) => Number.isFinite(n))) {
+        res.status(400).json({ ok: false, message: 'bbox [w,s,e,n] (numbers) required' }); return
+      }
+      const minZoom = clampInt(body.minZoom, 0, 0, 20)
+      const maxZoom = Math.max(minZoom, clampInt(body.maxZoom, 15, 0, 20))
+      const layers = (Array.isArray(body.layers) && body.layers.length) ? body.layers : ['osm-standard', 'bathy', 'seamap', 'coastline']
+      const CAP = 50000
+      const estimate = countBboxTiles(bbox, minZoom, maxZoom) * layers.length
+      if (estimate > CAP && !body.force) {
+        res.json({ ok: true, capped: true, estimate, cap: CAP, message: `~${estimate} tiles exceeds ${CAP}; narrow bbox/zoom or pass force:true` })
+        return
+      }
+      const ext = (layer) => (layer === 'coastline' ? 'pbf' : 'png')
+      const paths = []
+      for (const layer of layers) {
+        for (const { z, x, y } of bboxTiles(bbox, minZoom, maxZoom)) paths.push(`/tiles/${layer}/${z}/${x}/${y}.${ext(layer)}`)
+      }
+      const r = await warmMany(paths, { concurrency: body.concurrency || 6 })
+      res.json({ ok: true, requested: paths.length, ...r })
+    })
+  }
+
+  // --- "download around the boat" (config-driven region prefetch) ---
+  function getBoatPos () {
+    try {
+      const p = app.getSelfPath && app.getSelfPath('navigation.position')
+      const v = p && (p.value || p)
+      if (v && Number.isFinite(v.latitude) && Number.isFinite(v.longitude)) return v
+    } catch {}
+    return null
+  }
+
+  // Kicks off a background prefetch of a radius around the boat's current position at
+  // the chosen detail zoom. Retries for a position fix (from local SignalK) for a
+  // while, then gives up. Idempotent (cached tiles are skipped). Returns the warming
+  // promise (or null) so tests can await it.
+  function startAreaPrefetch (attempt = 0) {
+    const pf = options.prefetch || {}
+    const radius = Number(pf.radiusNm) || 0
+    if (radius <= 0 || stopping) return null
+    const maxZoom = Number(pf.detailZoom) || 13
+    const minZoom = Math.min(6, maxZoom)
+    const layers = (Array.isArray(pf.layers) && pf.layers.length) ? pf.layers : ['osm-standard', 'bathy', 'seamap', 'coastline']
+    const pos = getBoatPos()
+    if (!pos) {
+      if (attempt < 30 && !stopping) { const t = setTimeout(() => startAreaPrefetch(attempt + 1), 10000); if (t.unref) t.unref() } else log('area prefetch: no boat position — skipped')
+      return null
+    }
+    const bbox = boxAround(pos.latitude, pos.longitude, radius)
+    const CAP = 150000
+    const total = countBboxTiles(bbox, minZoom, maxZoom) * layers.length
+    if (total > CAP) { area = { capped: true, total, radius, maxZoom }; log(`area prefetch: ~${total} tiles too large — reduce radius/detail`); return null }
+    const ext = (l) => (l === 'coastline' ? 'pbf' : 'png')
+    const paths = []
+    for (const l of layers) { for (const { z, x, y } of bboxTiles(bbox, minZoom, maxZoom)) paths.push(`/tiles/${l}/${z}/${x}/${y}.${ext(l)}`) }
+    area = { done: 0, total: paths.length, running: true, radius, maxZoom }
+    log(`area prefetch: ${radius}nm around ${pos.latitude.toFixed(2)},${pos.longitude.toFixed(2)} to z${maxZoom} — ${paths.length} tiles`)
+    area.promise = warmMany(paths, { concurrency: pf.concurrency || 4, onProgress: () => { area.done++ } })
+      .then((r) => { area.running = false; area.result = r; log(`area prefetch done: ${r.cached} cached, ${r.empty} empty, ${r.failed} failed`); return r })
+      .catch((e) => { area.running = false; log('area prefetch error: ' + e.message) })
+    return area.promise
+  }
+
+  function areaStatus () {
+    if (!area) return ''
+    if (area.capped) return `; area: too large (~${area.total}) — reduce radius/detail`
+    return `; area(${area.radius}nm z${area.maxZoom}): ${area.done}/${area.total}${area.running ? '' : ' done'}`
+  }
+
+  return { start, stop, status, handleGet, handlePrefetch, handlePrefetchRegion, handleClear, _serveMirror: serveMirror, _serveConfig: serveConfig, _manifest: () => manifest, _seeder: () => seeder, _startAreaPrefetch: startAreaPrefetch, _area: () => area }
+}
+
+module.exports = { createProxy }

package/lib/proxy/manifest.js

@@ -0,0 +1,121 @@
+'use strict'
+
+// Cache-manifest poller. The cloud sailkick host publishes a small manifest that
+// announces the current bake id per dataset:
+//
+//   { "app": "2026-07-19a",
+//     "bakes": { "tiles/osm-standard": "v3", "tiles/seamap": "2026-06", "terrain": "2026-01" } }
+//
+// We poll it (only when online — a fetch failure is a no-op), and remember the
+// last-seen id per family plus the moment we first learned a NEW id
+// (invalidatedAt). cache.js treats any cached file older than its family's
+// invalidatedAt as stale → lazy refetch when online, serve-stale when offline.
+// Tiles are otherwise PINNED forever, so there is no per-tile time revalidation.
+//
+// Families come from the `bakes` keys (path prefixes); everything else (the app
+// shell, cached /api GETs) belongs to a synthetic `app` family keyed on `app`.
+
+const fs = require('fs')
+const fsp = fs.promises
+const path = require('path')
+
+function createManifest (app, options) {
+  const log = (m) => (app.debug ? app.debug('[manifest] ' + m) : console.log('[sailkick-boat:manifest]', m))
+  let cfg = null
+  let timer = null
+  let known = {} // family -> { id, invalidatedAt }
+  let lastOk = 0
+
+  function start () {
+    cfg = {
+      upstream: options.upstream.replace(/\/+$/, ''),
+      path: options.manifestPath || '/api/cache-manifest',
+      stateFile: path.join(options.storeDir, '.cache-manifest.json'),
+      intervalMs: Math.max(30000, (options.pollIntervalSec || 300) * 1000),
+      timeoutMs: options.timeoutMs || 15000
+    }
+    load()
+    poll() // immediate first check
+    timer = setInterval(poll, cfg.intervalMs)
+    if (timer.unref) timer.unref()
+    log(`polling ${cfg.upstream}${cfg.path} every ${Math.round(cfg.intervalMs / 1000)}s`)
+  }
+
+  function stop () {
+    if (timer) clearInterval(timer)
+    timer = null
+    cfg = null
+  }
+
+  function load () {
+    try { known = JSON.parse(fs.readFileSync(cfg.stateFile, 'utf8')) || {} } catch { known = {} }
+  }
+  async function save () {
+    try {
+      await fsp.mkdir(path.dirname(cfg.stateFile), { recursive: true })
+      await fsp.writeFile(cfg.stateFile, JSON.stringify(known))
+    } catch {}
+  }
+
+  async function poll () {
+    if (!cfg) return
+    let m
+    try {
+      const resp = await fetch(cfg.upstream + cfg.path, { signal: AbortSignal.timeout(cfg.timeoutMs) })
+      if (!resp.ok) return
+      m = await resp.json()
+    } catch { return } // offline / bad JSON → no-op, nothing invalidated
+    lastOk = Date.now()
+
+    const families = { ...((m && m.bakes) || {}) }
+    if (m && m.app != null) families.app = m.app
+
+    let changed = false
+    const now = Date.now()
+    for (const [fam, id] of Object.entries(families)) {
+      const sid = String(id)
+      const prev = known[fam]
+      if (!prev) {
+        // First sight of a family: record the id but DON'T invalidate — the boat's
+        // pre-populated store is valid for whatever it already has.
+        known[fam] = { id: sid, invalidatedAt: 0 }
+        changed = true
+      } else if (prev.id !== sid) {
+        known[fam] = { id: sid, invalidatedAt: now }
+        changed = true
+        log(`bake changed: ${fam} ${prev.id} -> ${sid} (older files refresh lazily)`)
+      }
+    }
+    if (changed) await save()
+  }
+
+  // Family of a request path = the longest matching bake prefix, else 'app'.
+  function familyFor (reqPath) {
+    const p = reqPath.replace(/^\/+/, '').split('?')[0]
+    let best = null
+    for (const fam of Object.keys(known)) {
+      if (fam === 'app') continue
+      const pref = fam.replace(/\/+$/, '')
+      if (p === pref || p.startsWith(pref + '/')) {
+        if (!best || pref.length > best.length) best = pref
+      }
+    }
+    return best || 'app'
+  }
+
+  function invalidatedAtFor (reqPath) {
+    const fam = familyFor(reqPath)
+    return (known[fam] && known[fam].invalidatedAt) || 0
+  }
+
+  function status () {
+    if (!cfg) return 'manifest: off'
+    const n = Object.keys(known).length
+    const age = lastOk ? Math.round((Date.now() - lastOk) / 1000) + 's ago' : 'never'
+    return `manifest: ${n} families, synced ${age}`
+  }
+
+  return { start, stop, status, invalidatedAtFor, familyFor, _poll: poll, _known: () => known }
+}
+
+module.exports = { createManifest }

package/lib/proxy/seed.js

@@ -0,0 +1,139 @@
+'use strict'
+
+// Global offline base seeder. Warms two worldwide layers into the mirror cache so a
+// usable map exists offline everywhere (not just where you browsed):
+//   - seabed  = the `bathy` raster (dense global): enumerate z0..seabedMaxZoom fully.
+//   - coastline = sparse vector .pbf: parent-guided descent from z0 — only descend
+//     into non-empty tiles (empty tiles 404 → negative-cached, not descended). Coast
+//     is continuous across zoom, so every non-empty child has a non-empty parent, so
+//     the descent is complete while probing ~4x the real tiles (not the full pyramid).
+//
+// Warms via getResource (cache-first) so it is idempotent/resumable: already-cached
+// tiles and negative-cached empties cost no network. Reuses the shared `health`
+// breaker — goes quiet when offline and resumes when back online. Fire-and-forget.
+
+const { getResource } = require('./cache')
+
+const sleep = (ms) => new Promise((r) => { const t = setTimeout(r, ms); if (t.unref) t.unref() })
+
+function createSeeder (app, opts) {
+  const log = (m) => (app.debug ? app.debug('[seed] ' + m) : console.log('[sailkick-boat:seed]', m))
+  let cfg = null
+  let running = false
+  let stopped = false
+  let runPromise = null
+  const counts = { coastline: 0, coastEmpty: 0, seabed: 0, seabedEmpty: 0, failed: 0 }
+
+  function start () {
+    cfg = {
+      upstream: opts.upstream.replace(/\/+$/, ''),
+      storeDir: opts.storeDir,
+      timeoutMs: opts.timeoutMs || 20000,
+      health: opts.health || null,
+      manifest: opts.manifest || null,
+      coastlineMaxZoom: opts.coastlineMaxZoom == null ? 8 : opts.coastlineMaxZoom,
+      seabedMaxZoom: opts.seabedMaxZoom == null ? 6 : opts.seabedMaxZoom,
+      concurrency: Math.max(1, opts.concurrency || 4),
+      offlinePollMs: opts.offlinePollMs || 2000
+    }
+    stopped = false
+    runPromise = run().catch((e) => log('seed error: ' + e.message))
+    return runPromise
+  }
+
+  function stop () { stopped = true }
+
+  function status () {
+    if (!cfg) return 'seed: off'
+    return `seed: coastline ${counts.coastline}, seabed ${counts.seabed} (${running ? 'running' : 'done'})`
+  }
+
+  async function waitIfOffline () {
+    while (!stopped && cfg.health && Date.now() < cfg.health.downUntil) await sleep(cfg.offlinePollMs)
+  }
+
+  // Warm one tile. Retries indefinitely while offline (circuit open) so the seed
+  // survives connectivity gaps. Returns {ok} | {empty} (404) | {failed} | {stopped}.
+  async function warm (reqPath) {
+    for (;;) {
+      await waitIfOffline()
+      if (stopped) return { stopped: true }
+      try {
+        await getResource({
+          storeDir: cfg.storeDir,
+          upstream: cfg.upstream,
+          reqPath,
+          timeoutMs: cfg.timeoutMs,
+          health: cfg.health,
+          invalidatedAt: cfg.manifest ? cfg.manifest.invalidatedAtFor(reqPath) : 0
+        })
+        return { ok: true }
+      } catch (e) {
+        if (e.status === 404) return { empty: true }
+        if (e.offline) { await sleep(cfg.offlinePollMs); continue } // went offline mid-flight → wait + retry
+        return { failed: true } // e.g. a 5xx — skip this tile
+      }
+    }
+  }
+
+  async function pool (worker) {
+    await Promise.all(Array.from({ length: cfg.concurrency }, () => worker()))
+  }
+
+  async function seedSeabed () {
+    const tiles = []
+    for (let z = 0; z <= cfg.seabedMaxZoom; z++) {
+      const n = 2 ** z
+      for (let x = 0; x < n; x++) for (let y = 0; y < n; y++) tiles.push([z, x, y])
+    }
+    let i = 0
+    await pool(async () => {
+      while (!stopped && i < tiles.length) {
+        const [z, x, y] = tiles[i++]
+        const r = await warm(`/tiles/bathy/${z}/${x}/${y}.png`)
+        if (r.stopped) return
+        if (r.ok) counts.seabed++; else if (r.empty) counts.seabedEmpty++; else counts.failed++
+      }
+    })
+  }
+
+  async function seedCoastline () {
+    const queue = [[0, 0, 0]]
+    let active = 0
+    await pool(async () => {
+      while (!stopped) {
+        const t = queue.shift() // shift + active++ are synchronous (no await between) → atomic
+        if (!t) { if (active === 0) return; await sleep(50); continue }
+        active++
+        const [z, x, y] = t
+        const r = await warm(`/tiles/coastline/${z}/${x}/${y}.pbf`)
+        if (r.stopped) { active--; return }
+        if (r.ok) {
+          counts.coastline++
+          if (z < cfg.coastlineMaxZoom) {
+            const nz = z + 1; const nx = x * 2; const ny = y * 2
+            queue.push([nz, nx, ny], [nz, nx + 1, ny], [nz, nx, ny + 1], [nz, nx + 1, ny + 1])
+          }
+        } else if (r.empty) counts.coastEmpty++
+        else counts.failed++
+        active--
+      }
+    })
+  }
+
+  async function run () {
+    running = true
+    log(`seeding: coastline z0-${cfg.coastlineMaxZoom}, seabed z0-${cfg.seabedMaxZoom}, concurrency ${cfg.concurrency}`)
+    try {
+      await seedSeabed()
+      await seedCoastline()
+      if (!stopped) log(`seed complete: coastline ${counts.coastline} (+${counts.coastEmpty} empty), seabed ${counts.seabed} (+${counts.seabedEmpty} empty), failed ${counts.failed}`)
+    } finally {
+      running = false
+    }
+  }
+
+  return { start, stop, status, _wait: () => runPromise, _counts: () => counts }
+}
+
+module.exports = { createSeeder }