signalk-chiplog 2.0.0 → 2.2.0

package/lib/events.js

@@ -1,6 +1,13 @@
 const { withTransaction } = require('./database');
 const { ApiError, badRequest, conflict, notFound } = require('./errors');
-const { activeEntryId, entryNearArrival, openEntryByHand, requireEntryRow } = require('./entries');
+const {
+  DEPARTURE_MANOEUVRES,
+  activeEntryId,
+  entryNearArrival,
+  openEntryByHand,
+  reopenableEntry,
+  requireEntryRow
+} = require('./entries');
 const { toPosition, paginate } = require('./rows');
 const { isPlainObject } = require('./validation');
 
@@ -20,8 +27,10 @@ const EVENT_TYPES = [
 // or from corrections, never posted by a client.
 const CLIENT_EVENT_TYPES = ['manoeuvre', 'text_annotation', 'handwritten_annotation'];
 
-// Logged with no passage open, these open one: the crew is leaving.
-const DEPARTURE_MANOEUVRES = new Set(['cast_off', 'anchor_up']);
+// A `sk_alarm` event reaching one of these states is the alarm itself; any
+// other state (usually `normal`) is what cleared it. Shared with
+// event-watcher.js, which decides what is worth logging in the first place.
+const CRITICAL_STATES = new Set(['alarm', 'emergency']);
 
 // An entry logged after the fact — typically replayed from the tablet's offline
 // queue — takes the position the track recorded at its time.
@@ -197,8 +206,9 @@ function createEvent(db, entryId, input, context) {
 }
 
 // An entry from the crew, attached to the passage it belongs to: the open one;
-// failing that, a departure manoeuvre opens one; failing that, the last
-// passage while the vessel is still at its arrival.
+// failing that, a departure manoeuvre goes to the passage that just ended if
+// a departure now would carry it on, and opens one otherwise; failing that,
+// the last passage while the vessel is still at its arrival.
 function logCrewEvent(db, input, context) {
   validateContent(db, input);
   return withTransaction(db, () => {
@@ -212,14 +222,22 @@ function logCrewEvent(db, input, context) {
 
     let entryId = activeEntryId(db);
     let openedEntry = false;
-    if (entryId === null && input.type === 'manoeuvre' && DEPARTURE_MANOEUVRES.has(input.subtype)) {
-      entryId = openEntryByHand(db, {
-        time,
-        position,
-        placeMatchRadius: context.placeMatchRadius,
-        now: context.now
-      });
-      openedEntry = true;
+    if (
+      entryId === null &&
+      input.type === 'manoeuvre' &&
+      DEPARTURE_MANOEUVRES.includes(input.subtype)
+    ) {
+      // Detection reopens that passage once the vessel moves.
+      entryId = reopenableEntry(db, time, context.stopClosureMinutes * 60 * 1000)?.id ?? null;
+      if (entryId === null) {
+        entryId = openEntryByHand(db, {
+          time,
+          position,
+          placeMatchRadius: context.placeMatchRadius,
+          now: context.now
+        });
+        openedEntry = true;
+      }
     }
     entryId ??= entryNearArrival(db, position);
     if (entryId === null) {
@@ -264,10 +282,35 @@ function updateEvent(db, id, patch) {
   return toEvent(requireEventRow(db, id));
 }
 
+// An alarm is logged as two lines — the notification reaching `alarm` or
+// `emergency`, and the one that later cleared it (SPEC §4.6) — so deleting
+// either alone would leave the other referring to nothing. Its pair is the
+// adjacent `sk_alarm` line for the same notification whose criticality
+// differs: an escalation (`alarm` to `emergency`) is not a pair, both being
+// critical, and is left alone.
+function pairedAlarmEvent(db, row) {
+  if (row.type !== 'sk_alarm') {
+    return null;
+  }
+  const siblings = db
+    .prepare(
+      `SELECT * FROM events WHERE entry_id = ? AND type = 'sk_alarm' AND subtype = ?
+       ORDER BY time, id`
+    )
+    .all(row.entry_id, row.subtype);
+  const index = siblings.findIndex((sibling) => sibling.id === row.id);
+  const critical = CRITICAL_STATES.has(JSON.parse(row.payload).state);
+  const neighbour = critical ? siblings[index + 1] : siblings[index - 1];
+  if (!neighbour || CRITICAL_STATES.has(JSON.parse(neighbour.payload).state) === critical) {
+    return null;
+  }
+  return neighbour;
+}
+
 // Undoing the departure that opened a passage, before the vessel moved and
 // before anything else was logged in it, takes the passage away too.
 function deleteEvent(db, id) {
-  requireEventRow(db, id);
+  const row = requireEventRow(db, id);
   withTransaction(db, () => {
     const opened = db
       .prepare(
@@ -278,15 +321,20 @@ function deleteEvent(db, id) {
       .get(id, id);
     if (opened) {
       db.prepare('DELETE FROM log_entries WHERE id = ?').run(opened.id);
-    } else {
-      db.prepare('DELETE FROM events WHERE id = ?').run(id);
+      return;
+    }
+    const paired = pairedAlarmEvent(db, row);
+    if (paired) {
+      db.prepare('DELETE FROM events WHERE id = ?').run(paired.id);
     }
+    db.prepare('DELETE FROM events WHERE id = ?').run(id);
   });
 }
 
 module.exports = {
   EVENT_TYPES,
   CLIENT_EVENT_TYPES,
+  CRITICAL_STATES,
   listEvents,
   allEvents,
   createEvent,

package/lib/export.js

@@ -2,13 +2,17 @@ const crypto = require('node:crypto');
 const fs = require('node:fs/promises');
 const path = require('node:path');
 const { getSchemaVersion } = require('./database');
+const { listEntryCrew } = require('./crew');
 const { conflict } = require('./errors');
 const { toEntry } = require('./entries');
 const { allEvents } = require('./events');
 const { toCsv, toGpx } = require('./formats');
+const { listEntryLandmarks } = require('./landmarks');
 const { renderLogbookPdf } = require('./logbook-pdf');
 const { allSegments } = require('./propulsion');
 const { allTrackPoints, allObservations } = require('./track');
+const { getTideForecast } = require('./tide-forecaster');
+const { getWeatherForecast } = require('./weather-forecaster');
 
 const EXPORT_FORMATS = {
   json: {
@@ -30,7 +34,11 @@ function bundleOf(db, row) {
     trackPoints: allTrackPoints(db, row.id),
     observations: allObservations(db, row.id),
     propulsion: allSegments(db, row.id),
-    events: allEvents(db, row.id)
+    events: allEvents(db, row.id),
+    landmarks: listEntryLandmarks(db, row.id),
+    tide: getTideForecast(db, row.id),
+    weather: getWeatherForecast(db, row.id),
+    crew: listEntryCrew(db, row.id)
   };
 }
 
@@ -126,6 +134,17 @@ function passageFingerprint(db, row, pdf) {
   // version does not count: upgrading does not rewrite the whole drive.
   hash.update(JSON.stringify([pdf.language, pdf.timeZone, pdf.vesselName]));
   hash.update(JSON.stringify([summary('track_points'), summary('observations')]));
+  // The tide and weather forecasts each arrive once, after departure, and are printed.
+  for (const table of ['tide_forecasts', 'weather_forecasts']) {
+    const forecast = db.prepare(`SELECT fetched_at FROM ${table} WHERE entry_id = ?`).get(row.id);
+    hash.update(JSON.stringify(forecast?.fetched_at ?? null));
+  }
+  // The landmarks a passage is read against arrive area by area, well after
+  // the sailing, and the PDF prints them: a copy already on the drive is worth
+  // rewriting once they do.
+  for (const landmark of listEntryLandmarks(db, row.id)) {
+    hash.update(JSON.stringify([landmark.id, landmark.updatedAt]));
+  }
   for (const table of ['propulsion_segments', 'events']) {
     for (const item of db
       .prepare(`SELECT * FROM ${table} WHERE entry_id = ? ORDER BY id`)

package/lib/landmark-finder.js

@@ -0,0 +1,209 @@
+const { cellBounds, nextPendingArea, saveArea } = require('./landmarks');
+
+// Fills the gazetteer of amers (SPEC §4.13) from OpenStreetMap, one area at a
+// time, on the same pattern as place names and the forecasts: `resolveNext()`
+// does at most one request and says when the next is due. Offline is the
+// normal state at sea, so a failure is retried patiently; an area already
+// fetched is never asked for again.
+
+const LANDMARK_DEFAULTS = {
+  landmarksEnabled: true,
+  overpassUrl: 'https://overpass-api.de/api/interpreter'
+};
+
+const METRES_PER_NM = 1852;
+
+// Overpass is a shared, often busy service: ask it for one area at a time and
+// leave room between requests.
+const QUERY_TIMEOUT_S = 60;
+const REQUEST_TIMEOUT_MS = 90 * 1000;
+const NEXT_FETCH_MS = 10 * 1000;
+const IDLE_MS = 5 * 60 * 1000;
+const FIRST_RETRY_MS = 5 * 60 * 1000;
+const MAX_RETRY_MS = 60 * 60 * 1000;
+
+// What counts as an amer, in OpenStreetMap's tags. Deliberately narrow: the
+// lateral and cardinal marks of a channel are named "6 c" or "L1" on the
+// chart, which says nothing in a logbook, so only the features a position is
+// traditionally read against are kept.
+const SEAMARK_TYPES = [
+  'light_major',
+  'light_minor',
+  'light_vessel',
+  'landmark',
+  'harbour',
+  'beacon_isolated_danger',
+  'beacon_safe_water'
+];
+
+function kindOf(tags) {
+  const seamark = tags['seamark:type'];
+  if (tags.man_made === 'lighthouse' || seamark === 'light_major' || seamark === 'light_vessel') {
+    return 'lighthouse';
+  }
+  if (seamark === 'light_minor') {
+    return 'light';
+  }
+  if (tags.natural === 'cape') {
+    return 'cape';
+  }
+  if (seamark === 'landmark') {
+    return 'landmark';
+  }
+  if (seamark === 'beacon_isolated_danger' || seamark === 'beacon_safe_water') {
+    return 'beacon';
+  }
+  if (seamark === 'harbour' || tags.leisure === 'marina') {
+    return 'harbour';
+  }
+  return null;
+}
+
+// A sectored light carries one range per sector ("seamark:light:2:range"); the
+// greatest is how far the light is seen at all.
+function lightRangeOf(tags) {
+  const ranges = Object.entries(tags)
+    .filter(([key]) => /^seamark:light(:\d+)?:range$/.test(key))
+    .map(([, value]) => Number.parseFloat(value))
+    .filter((range) => Number.isFinite(range) && range > 0);
+  return ranges.length === 0 ? null : Math.max(...ranges) * METRES_PER_NM;
+}
+
+// The name the crew would use: OpenStreetMap's own ("Phare du Cap-Ferret")
+// rather than the chart's abbreviation in `seamark:name` ("Cap Ferret").
+// A feature with neither is not an amer anyone can be told about.
+function landmarkFrom(element) {
+  const tags = element.tags ?? {};
+  const name = (tags.name ?? tags['seamark:name'] ?? '').trim();
+  const kind = kindOf(tags);
+  // Ways and relations -- a lighthouse drawn as a building, a harbour as an
+  // area -- are asked for with their centre.
+  const position = element.type === 'node' ? element : element.center;
+  if (name === '' || !kind || !position) {
+    return null;
+  }
+  return {
+    osmType: element.type,
+    osmId: element.id,
+    name,
+    kind,
+    lat: position.lat,
+    lon: position.lon,
+    lightRange: lightRangeOf(tags)
+  };
+}
+
+function parseElements(elements = []) {
+  return elements.map(landmarkFrom).filter(Boolean);
+}
+
+function overpassQuery({ south, west, north, east }) {
+  const box = `(${south.toFixed(4)},${west.toFixed(4)},${north.toFixed(4)},${east.toFixed(4)})`;
+  return [
+    `[out:json][timeout:${QUERY_TIMEOUT_S}];`,
+    '(',
+    `  nwr["man_made"="lighthouse"]${box};`,
+    `  nwr["seamark:type"~"^(${SEAMARK_TYPES.join('|')})$"]${box};`,
+    `  nwr["natural"="cape"]${box};`,
+    `  nwr["leisure"="marina"]${box};`,
+    ');',
+    'out tags center;'
+  ].join('\n');
+}
+
+function createLandmarkFinder({ db, settings, userAgent, fetch = globalThis.fetch }) {
+  const stopping = new AbortController();
+  let failures = 0;
+
+  // Overpass reports a busy dispatcher or a query timeout in the body, with
+  // HTTP 200 -- as an HTML page, or as a "remark" beside empty elements. Both
+  // mean "ask again later", not "there is nothing there".
+  async function lookup(cell) {
+    const response = await fetch(settings.overpassUrl, {
+      method: 'POST',
+      headers: {
+        'User-Agent': userAgent,
+        Accept: 'application/json',
+        'Content-Type': 'application/x-www-form-urlencoded'
+      },
+      body: new URLSearchParams({ data: overpassQuery(cellBounds(cell)) }).toString(),
+      signal: AbortSignal.any([stopping.signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)])
+    });
+    if (response.status === 429 || response.status === 504 || response.status >= 500) {
+      throw new Error(`Overpass answered HTTP ${response.status}`);
+    }
+    if (!response.ok) {
+      return null;
+    }
+    let result;
+    try {
+      result = await response.json();
+    } catch {
+      throw new Error('Overpass answered something other than JSON');
+    }
+    if (typeof result?.remark === 'string' && /error|timeout/i.test(result.remark)) {
+      throw new Error(`Overpass reported: ${result.remark}`);
+    }
+    return Array.isArray(result?.elements) ? result.elements : [];
+  }
+
+  return {
+    async resolveNext() {
+      if (!settings.landmarksEnabled) {
+        return { outcome: 'disabled', retryInMs: IDLE_MS };
+      }
+      const pending = nextPendingArea(db);
+      if (!pending) {
+        failures = 0;
+        return { outcome: 'idle', retryInMs: IDLE_MS };
+      }
+
+      let elements;
+      try {
+        elements = await lookup(pending.cell);
+      } catch (error) {
+        if (stopping.signal.aborted) {
+          return { outcome: 'stopped' };
+        }
+        failures += 1;
+        return {
+          outcome: 'failed',
+          error,
+          retryInMs: Math.min(FIRST_RETRY_MS * 2 ** (failures - 1), MAX_RETRY_MS)
+        };
+      }
+      if (stopping.signal.aborted) {
+        return { outcome: 'stopped' };
+      }
+      failures = 0;
+
+      // A refusal Overpass will not answer differently (a rejected query) is
+      // final for this area: record it as covered rather than blocking every
+      // other one behind it.
+      const landmarks = elements === null ? [] : parseElements(elements);
+      saveArea(db, pending.cell, landmarks, new Date().toISOString());
+      return {
+        outcome: elements === null ? 'refused' : 'fetched',
+        count: landmarks.length,
+        areasLeft: pending.remaining - 1,
+        // Whatever is left to cover waits for the next slot: Overpass is not a
+        // service to run through as fast as it will answer.
+        retryInMs: NEXT_FETCH_MS
+      };
+    },
+
+    stop() {
+      stopping.abort();
+    }
+  };
+}
+
+module.exports = {
+  createLandmarkFinder,
+  kindOf,
+  landmarkFrom,
+  lightRangeOf,
+  overpassQuery,
+  parseElements,
+  LANDMARK_DEFAULTS
+};

package/lib/landmarks.js

@@ -0,0 +1,210 @@
+const { withTransaction } = require('./database');
+
+// The gazetteer of amers (SPEC §4.13) and the bookkeeping of which areas it
+// covers. Reading a position against a landmark -- the bearing and distance a
+// logbook line shows -- happens in `public/js/landmarks.mjs`, shared with the
+// webapp and the PDF; this module only stores and hands out the landmarks.
+
+const METRES_PER_NM = 1852;
+const METRES_PER_DEGREE = 111320;
+
+// The widest range any kind of amer is named from, and so the margin a cell is
+// fetched with. Kept in step with the largest entry of KIND_RANGE_M in
+// public/js/landmarks.mjs, which a test checks.
+const MAX_RELEVANT_M = 15 * METRES_PER_NM;
+
+// Landmarks are fetched by half-degree cell -- about 30 nm of latitude, a
+// day's sailing across, so a coastal cruise costs a handful of requests.
+const CELL_DEGREES = 0.5;
+
+// SQLite's CAST truncates towards zero, which is not FLOOR for a negative
+// latitude or longitude; the offsets keep the value positive so it is. They
+// are wide enough for any coordinate (lat / 0.5 >= -180, lon / 0.5 >= -360).
+const LAT_OFFSET = 400;
+const LON_OFFSET = 800;
+
+function toRadians(degrees) {
+  return (degrees * Math.PI) / 180;
+}
+
+function toLandmark(row) {
+  return {
+    id: row.id,
+    name: row.name,
+    kind: row.kind,
+    position: { lat: row.lat, lon: row.lon },
+    lightRange: row.light_range,
+    osm: { type: row.osm_type, id: row.osm_id },
+    updatedAt: row.updated_at
+  };
+}
+
+// Every position a passage's journal shows a line for: its track, the readings
+// and events on it, and its departure and arrival.
+const POSITIONS = `
+  SELECT lat, lon FROM track_points WHERE entry_id = ?
+  UNION ALL
+  SELECT lat, lon FROM observations WHERE entry_id = ? AND lat IS NOT NULL
+  UNION ALL
+  SELECT lat, lon FROM events WHERE entry_id = ? AND lat IS NOT NULL
+  UNION ALL
+  SELECT start_lat, start_lon FROM log_entries WHERE id = ? AND start_lat IS NOT NULL
+  UNION ALL
+  SELECT end_lat, end_lon FROM log_entries WHERE id = ? AND end_lat IS NOT NULL
+`;
+
+function entryParams(entryId) {
+  return [entryId, entryId, entryId, entryId, entryId];
+}
+
+// The cells a passage has been in. Its bounding box would do for a coastal
+// hop, but a long passage's box covers cells it never came near -- each of
+// which would cost a request.
+function entryCells(db, entryId) {
+  return db
+    .prepare(
+      `SELECT DISTINCT
+         CAST(lat / ${CELL_DEGREES} + ${LAT_OFFSET} AS INTEGER) - ${LAT_OFFSET} AS cell_lat,
+         CAST(lon / ${CELL_DEGREES} + ${LON_OFFSET} AS INTEGER) - ${LON_OFFSET} AS cell_lon
+       FROM (${POSITIONS})
+       ORDER BY cell_lat, cell_lon`
+    )
+    .all(...entryParams(entryId))
+    .map((row) => ({ cellLat: row.cell_lat, cellLon: row.cell_lon }));
+}
+
+function entryBounds(db, entryId) {
+  const row = db
+    .prepare(
+      `SELECT MIN(lat) AS min_lat, MAX(lat) AS max_lat, MIN(lon) AS min_lon, MAX(lon) AS max_lon
+       FROM (${POSITIONS})`
+    )
+    .get(...entryParams(entryId));
+  return row?.min_lat === null || row?.min_lat === undefined
+    ? null
+    : { minLat: row.min_lat, maxLat: row.max_lat, minLon: row.min_lon, maxLon: row.max_lon };
+}
+
+// How many degrees MAX_RELEVANT_M is, at the latitude it is measured from:
+// a degree of longitude shortens towards the poles.
+function margins(latitude) {
+  const latMargin = MAX_RELEVANT_M / METRES_PER_DEGREE;
+  const cosLat = Math.cos(toRadians(Math.min(89, Math.abs(latitude))));
+  return { latMargin, lonMargin: cosLat > 0.02 ? latMargin / cosLat : 180 };
+}
+
+// The area one cell is fetched for: the cell itself plus the margin, so a
+// position anywhere inside it has every amer within range.
+function cellBounds({ cellLat, cellLon }) {
+  const south = cellLat * CELL_DEGREES;
+  const north = south + CELL_DEGREES;
+  const west = cellLon * CELL_DEGREES;
+  const east = west + CELL_DEGREES;
+  const { latMargin, lonMargin } = margins(Math.max(Math.abs(south), Math.abs(north)));
+  return {
+    south: Math.max(-90, south - latMargin),
+    north: Math.min(90, north + latMargin),
+    west: Math.max(-180, west - lonMargin),
+    east: Math.min(180, east + lonMargin)
+  };
+}
+
+// The landmarks any line of a passage's journal could be read against: the
+// area it sailed through, widened by the range an amer is named from. Near the
+// antimeridian the longitude window would wrap, so latitude alone filters
+// there and the distance test -- which runs at read time -- stays exact.
+function listEntryLandmarks(db, entryId) {
+  const bounds = entryBounds(db, entryId);
+  if (!bounds) {
+    return [];
+  }
+  const { latMargin, lonMargin } = margins(
+    Math.max(Math.abs(bounds.minLat), Math.abs(bounds.maxLat))
+  );
+  const south = bounds.minLat - latMargin;
+  const north = bounds.maxLat + latMargin;
+  const west = bounds.minLon - lonMargin;
+  const east = bounds.maxLon + lonMargin;
+  const rows =
+    west < -180 || east > 180
+      ? db.prepare('SELECT * FROM landmarks WHERE lat BETWEEN ? AND ?').all(south, north)
+      : db
+          .prepare('SELECT * FROM landmarks WHERE lat BETWEEN ? AND ? AND lon BETWEEN ? AND ?')
+          .all(south, north, west, east);
+  return rows.map(toLandmark);
+}
+
+function isAreaFetched(db, { cellLat, cellLon }) {
+  return (
+    db
+      .prepare('SELECT 1 FROM landmark_areas WHERE cell_lat = ? AND cell_lon = ?')
+      .get(cellLat, cellLon) !== undefined
+  );
+}
+
+// One fetched area, with the landmarks it found: written together, so a cell
+// is only ever recorded as covered once its landmarks are in the table.
+function saveArea(db, cell, landmarks, now) {
+  withTransaction(db, () => {
+    for (const landmark of landmarks) {
+      db.prepare(
+        `INSERT INTO landmarks
+           (osm_type, osm_id, name, kind, lat, lon, light_range, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT (osm_type, osm_id) DO UPDATE SET
+           name = excluded.name,
+           kind = excluded.kind,
+           lat = excluded.lat,
+           lon = excluded.lon,
+           light_range = excluded.light_range,
+           updated_at = excluded.updated_at`
+      ).run(
+        landmark.osmType,
+        landmark.osmId,
+        landmark.name,
+        landmark.kind,
+        landmark.lat,
+        landmark.lon,
+        landmark.lightRange,
+        now,
+        now
+      );
+    }
+    db.prepare(
+      `INSERT INTO landmark_areas (cell_lat, cell_lon, fetched_at) VALUES (?, ?, ?)
+       ON CONFLICT (cell_lat, cell_lon) DO UPDATE SET fetched_at = excluded.fetched_at`
+    ).run(cell.cellLat, cell.cellLon, now);
+  });
+}
+
+// The next cell to fetch, newest passage first, and the passage that wants it.
+// A passage whose cells are all covered is no longer pending -- unless it is
+// still open, since it may yet sail into a new cell.
+function nextPendingArea(db) {
+  const pending = db
+    .prepare('SELECT id, state FROM log_entries WHERE landmarks_pending = 1 ORDER BY id DESC')
+    .all();
+  for (const entry of pending) {
+    const missing = entryCells(db, entry.id).filter((cell) => !isAreaFetched(db, cell));
+    if (missing.length > 0) {
+      return { entryId: entry.id, cell: missing[0], remaining: missing.length };
+    }
+    if (entry.state !== 'active') {
+      db.prepare('UPDATE log_entries SET landmarks_pending = 0 WHERE id = ?').run(entry.id);
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  CELL_DEGREES,
+  MAX_RELEVANT_M,
+  cellBounds,
+  entryBounds,
+  entryCells,
+  isAreaFetched,
+  listEntryLandmarks,
+  nextPendingArea,
+  saveArea,
+  toLandmark
+};