signalk-chiplog 2.0.0 → 2.2.0

package/index.js

@@ -2,13 +2,16 @@ const { registerRoutes } = require('./lib/api');
 const { openDatabase } = require('./lib/database');
 const { createPassageDetector, DETECTION_DEFAULTS, TICK_INTERVAL_MS } = require('./lib/detection');
 const { ApiError } = require('./lib/errors');
+const { createBackgroundSchedule } = require('./lib/background-schedule');
 const { createEventWatcher, CHECK_INTERVAL_MS, EVENT_DEFAULTS } = require('./lib/event-watcher');
 const { INFLUX_DEFAULTS } = require('./lib/influx-history');
+const { createLandmarkFinder, LANDMARK_DEFAULTS } = require('./lib/landmark-finder');
 const { OBSERVATION_DEFAULTS } = require('./lib/observation-recorder');
 const { createPlaceNamer, GEOCODING_DEFAULTS } = require('./lib/place-names');
 const { PROPULSION_DEFAULTS } = require('./lib/propulsion-detector');
 const { createReplayJob } = require('./lib/replay-job');
 const { createTideForecaster, TIDE_DEFAULTS } = require('./lib/tide-forecaster');
+const { createWeatherForecaster, WEATHER_DEFAULTS } = require('./lib/weather-forecaster');
 const { createTrackRecorder, SAMPLE_INTERVAL_MS, TRACK_DEFAULTS } = require('./lib/track-recorder');
 const {
   createUsbExportScheduler,
@@ -23,8 +26,10 @@ const { version } = require('./package.json');
 const DEFAULT_PLACE_MATCH_RADIUS = 200;
 const FIRST_NAMING_DELAY_MS = 5 * 1000;
 const NAMING_ERROR_RETRY_MS = 5 * 60 * 1000;
-const FIRST_TIDE_DELAY_MS = 5 * 1000;
-const TIDE_ERROR_RETRY_MS = 5 * 60 * 1000;
+const FIRST_FORECAST_DELAY_MS = 5 * 1000;
+// Landmarks are not needed for the passage under way, only for reading it back,
+// so the first lookup waits for the busier start-up work to be done.
+const FIRST_LANDMARK_DELAY_MS = 30 * 1000;
 
 const MOTION_LABELS = { underway: 'Under way', stopped: 'Stopped', unknown: 'Waiting for data' };
 const MODE_LABELS = { autostate: 'navigation.state', fallback: 'speed fallback' };
@@ -55,11 +60,12 @@ module.exports = function (app) {
   let settings = null;
   let detector = null;
   let namer = null;
-  let tideForecaster = null;
+  let schedules = [];
+  // The open passage detection last reported, to notice a new one.
+  let lastActiveEntryId = null;
   let usbExport = null;
   let replayJob = null;
   let namingTimer = null;
-  let tideTimer = null;
   let timers = [];
   let lastStatus = null;
 
@@ -72,9 +78,9 @@ module.exports = function (app) {
     properties: {
       stopClosureMinutes: {
         type: 'number',
-        title: 'Stop duration that ends a passage (minutes)',
+        title: 'Stop duration within which a new departure continues the passage (minutes)',
         description:
-          'Shorter stops, such as waiting for a lock or a lunch anchorage, stay within the same logbook entry',
+          'A passage closes as soon as the boat stops; leaving again sooner than this, after waiting for a lock or a lunch anchorage, reopens it and keeps the stop as a stopover',
         default: DETECTION_DEFAULTS.stopClosureMinutes,
         minimum: 1
       },
@@ -130,6 +136,19 @@ module.exports = function (app) {
         description: 'The public OpenStreetMap instance by default, or a self-hosted Nominatim',
         default: GEOCODING_DEFAULTS.geocodingUrl
       },
+      landmarksEnabled: {
+        type: 'boolean',
+        title: 'Read each journal line against the nearest landmark',
+        description:
+          'Fetches the lighthouses, capes, towers and harbours of the areas sailed through from OpenStreetMap, so every position in the logbook is also given as a bearing and distance from the nearest one (© OpenStreetMap contributors, ODbL). Without it, only the coordinates are shown',
+        default: LANDMARK_DEFAULTS.landmarksEnabled
+      },
+      overpassUrl: {
+        type: 'string',
+        title: 'Landmark service (Overpass API)',
+        description: 'The public Overpass instance by default, or a self-hosted one',
+        default: LANDMARK_DEFAULTS.overpassUrl
+      },
       tidesEnabled: {
         type: 'boolean',
         title: 'Fetch the tide forecast at departure',
@@ -139,10 +158,24 @@ module.exports = function (app) {
       },
       tideUrl: {
         type: 'string',
-        title: 'Tide service (Open-Meteo Marine-compatible)',
-        description: 'The public Open-Meteo instance by default, or a self-hosted one',
+        title: 'Marine service (Open-Meteo Marine-compatible)',
+        description:
+          'Tides, and waves, swell, sea temperature and current for the weather forecast. The public Open-Meteo instance by default, or a self-hosted one',
         default: TIDE_DEFAULTS.tideUrl
       },
+      weatherEnabled: {
+        type: 'boolean',
+        title: 'Fetch the marine weather forecast at departure',
+        description:
+          'Sends the departure position to the weather service below and to the marine service above for the next 24 hours of wind, sky, sea state and current. Data comes from Open-Meteo (CC BY 4.0)',
+        default: WEATHER_DEFAULTS.weatherEnabled
+      },
+      weatherUrl: {
+        type: 'string',
+        title: 'Weather service (Open-Meteo-compatible)',
+        description: 'The public Open-Meteo instance by default, or a self-hosted one',
+        default: WEATHER_DEFAULTS.weatherUrl
+      },
       usbExportPath: {
         type: 'string',
         title: 'USB export directory',
@@ -236,6 +269,13 @@ module.exports = function (app) {
     try {
       const outcome = detector.tick();
       usbExport.afterDetection(outcome);
+      // A passage just opened: fetch its forecasts and the landmarks of where
+      // it is starting from now, not at the next idle poll or at the end of a
+      // retry delay left from an earlier failure.
+      if (outcome.activeEntryId !== null && outcome.activeEntryId !== lastActiveEntryId) {
+        schedules.forEach((schedule) => schedule.nudge());
+      }
+      lastActiveEntryId = outcome.activeEntryId;
       const usbError = usbExport.status().lastError;
       const status = `${describeDetection(outcome)}${usbError ? ` — USB copy failing: ${usbError.message}` : ''}`;
       if (status !== lastStatus) {
@@ -284,29 +324,6 @@ module.exports = function (app) {
     namingTimer = setTimeout(runNaming, result.retryInMs);
   }
 
-  // Same idea as geocoding: a network call fetching the tide forecast near a
-  // recent departure, on its own chain rather than inside detection.
-  async function runTides() {
-    const current = tideForecaster;
-    let result;
-    try {
-      result = await current.resolveNext();
-    } catch (err) {
-      app.error(`Tide forecast failed: ${err.stack ?? err}`);
-      result = { retryInMs: TIDE_ERROR_RETRY_MS };
-    }
-    if (tideForecaster !== current || result.outcome === 'stopped') {
-      return;
-    }
-    if (result.outcome === 'failed') {
-      // Expected whenever the boat is out of reach of a network.
-      app.debug(
-        `Tide forecast unavailable, retrying in ${Math.round(result.retryInMs / 60000)} min: ${result.error.message}`
-      );
-    }
-    tideTimer = setTimeout(runTides, result.retryInMs);
-  }
-
   // For work that runs every second: log a failure once, not on every run.
   function guarded(label, work) {
     let failing = false;
@@ -345,8 +362,12 @@ module.exports = function (app) {
         placeMatchRadius: config.placeMatchRadius ?? DEFAULT_PLACE_MATCH_RADIUS,
         geocodingEnabled: config.geocodingEnabled ?? GEOCODING_DEFAULTS.geocodingEnabled,
         geocodingUrl: config.geocodingUrl || GEOCODING_DEFAULTS.geocodingUrl,
+        landmarksEnabled: config.landmarksEnabled ?? LANDMARK_DEFAULTS.landmarksEnabled,
+        overpassUrl: config.overpassUrl || LANDMARK_DEFAULTS.overpassUrl,
         tidesEnabled: config.tidesEnabled ?? TIDE_DEFAULTS.tidesEnabled,
         tideUrl: config.tideUrl || TIDE_DEFAULTS.tideUrl,
+        weatherEnabled: config.weatherEnabled ?? WEATHER_DEFAULTS.weatherEnabled,
+        weatherUrl: config.weatherUrl || WEATHER_DEFAULTS.weatherUrl,
         usbExportPath: config.usbExportPath || null,
         usbExportIntervalMinutes:
           config.usbExportIntervalMinutes ?? USB_EXPORT_DEFAULTS.usbExportIntervalMinutes,
@@ -395,11 +416,6 @@ module.exports = function (app) {
       settings,
       userAgent: `signalk-chiplog/${version}`
     });
-    tideForecaster = createTideForecaster({
-      db: database,
-      settings,
-      userAgent: `signalk-chiplog/${version}`
-    });
     usbExport = createUsbExportScheduler({
       db: database,
       settings,
@@ -414,7 +430,32 @@ module.exports = function (app) {
       onDone: nudgeNaming
     });
     namingTimer = setTimeout(runNaming, FIRST_NAMING_DELAY_MS);
-    tideTimer = setTimeout(runTides, FIRST_TIDE_DELAY_MS);
+    // Same idea as geocoding: network calls fetching the tide and weather
+    // forecasts near a recent departure, and the landmarks of the areas
+    // sailed through, each on its own chain rather than inside detection.
+    const networkOptions = { db: database, settings, userAgent: `signalk-chiplog/${version}` };
+    const log = (level, message) => (level === 'error' ? app.error(message) : app.debug(message));
+    lastActiveEntryId = null;
+    schedules = [
+      createBackgroundSchedule({
+        label: 'Tide forecast',
+        resolver: createTideForecaster(networkOptions),
+        log,
+        firstDelayMs: FIRST_FORECAST_DELAY_MS
+      }),
+      createBackgroundSchedule({
+        label: 'Weather forecast',
+        resolver: createWeatherForecaster(networkOptions),
+        log,
+        firstDelayMs: FIRST_FORECAST_DELAY_MS
+      }),
+      createBackgroundSchedule({
+        label: 'Landmark lookup',
+        resolver: createLandmarkFinder(networkOptions),
+        log,
+        firstDelayMs: FIRST_LANDMARK_DELAY_MS
+      })
+    ];
     lastStatus = null;
     runDetection();
     timers = [
@@ -440,9 +481,8 @@ module.exports = function (app) {
     clearTimeout(namingTimer);
     namer?.stop();
     namer = null;
-    clearTimeout(tideTimer);
-    tideForecaster?.stop();
-    tideForecaster = null;
+    schedules.forEach((schedule) => schedule.stop());
+    schedules = [];
     usbExport?.stop();
     usbExport = null;
     replayJob?.cancel();

package/lib/api.js

@@ -1,14 +1,17 @@
 const { getSchemaVersion } = require('./database');
+const crew = require('./crew');
 const { ApiError, badRequest, conflict, notFound } = require('./errors');
 const entries = require('./entries');
 const events = require('./events');
 const { renderExport } = require('./export');
+const { listEntryLandmarks } = require('./landmarks');
 const { isTimeZone, PDF_LANGUAGES } = require('./logbook-pdf');
 const { toGeoJson, toGpx } = require('./formats');
 const manoeuvreTypes = require('./manoeuvre-types');
 const places = require('./places');
 const propulsion = require('./propulsion');
 const { getTideForecast } = require('./tide-forecaster');
+const { getWeatherForecast } = require('./weather-forecaster');
 const track = require('./track');
 const v = require('./validation');
 
@@ -227,6 +230,20 @@ function registerRoutes(router, { getContext, logError }) {
     })
   );
 
+  // The amers a line of this passage's journal can be read against (SPEC
+  // §4.13); which one each line takes, and the bearing, is worked out where
+  // the line is shown. Empty until the area's landmarks have been fetched.
+  readonly.get(
+    '/api/entries/:id/landmarks',
+    handle(({ db }, req) => {
+      const id = entryId(req);
+      entries.requireEntryRow(db, id);
+      const { limit, offset } = v.parsePagination(req.query);
+      const items = listEntryLandmarks(db, id);
+      return { total: items.length, limit, offset, items: items.slice(offset, offset + limit) };
+    })
+  );
+
   readonly.get(
     '/api/entries/:id/tide',
     handle(({ db }, req) => {
@@ -240,6 +257,19 @@ function registerRoutes(router, { getContext, logError }) {
     })
   );
 
+  readonly.get(
+    '/api/entries/:id/weather',
+    handle(({ db }, req) => {
+      const id = entryId(req);
+      entries.requireEntryRow(db, id);
+      const forecast = getWeatherForecast(db, id);
+      if (!forecast) {
+        throw notFound('weather', id);
+      }
+      return forecast;
+    })
+  );
+
   // Events
 
   readonly.get(
@@ -304,7 +334,8 @@ function registerRoutes(router, { getContext, logError }) {
       const outcome = events.logCrewEvent(db, input, {
         now: now(),
         vesselPosition: vesselPosition(),
-        placeMatchRadius: config.placeMatchRadius
+        placeMatchRadius: config.placeMatchRadius,
+        stopClosureMinutes: config.stopClosureMinutes
       });
       observeLiveEvent(context, input, outcome);
       res.status(outcome.created ? 201 : 200);
@@ -405,6 +436,83 @@ function registerRoutes(router, { getContext, logError }) {
     })
   );
 
+  // Crew
+
+  readonly.get(
+    '/api/crew',
+    handle(({ db }, req) => crew.listCrewMembers(db, v.parsePagination(req.query)))
+  );
+
+  readwrite.post(
+    '/api/crew',
+    handle(({ db, now }, req, res) => {
+      const body = v.requireBody(req.body, ['name', 'role']);
+      const member = crew.createCrewMember(
+        db,
+        {
+          name: v.parseString(body.name, 'name', { maxLength: 100 }),
+          role: optional(body, 'role', nullableString(100)) ?? null
+        },
+        now()
+      );
+      res.status(201);
+      return member;
+    })
+  );
+
+  readwrite.patch(
+    '/api/crew/:id',
+    handle(({ db, now }, req) => {
+      const id = v.parseId(req.params.id);
+      const body = v.requireBody(req.body, ['name', 'role']);
+      return crew.updateCrewMember(
+        db,
+        id,
+        {
+          name: optional(body, 'name', requiredString(100)),
+          role: optional(body, 'role', nullableString(100))
+        },
+        now()
+      );
+    })
+  );
+
+  readwrite.delete(
+    '/api/crew/:id',
+    handle(({ db }, req) => {
+      crew.deleteCrewMember(db, v.parseId(req.params.id));
+    })
+  );
+
+  readwrite.put(
+    '/api/entries/:id/crew',
+    handle(({ db, now }, req) => {
+      const id = entryId(req);
+      entries.requireEntryRow(db, id);
+      const body = v.requireBody(req.body, ['members']);
+      if (!Array.isArray(body.members)) {
+        throw badRequest('members must be an array');
+      }
+      const members = body.members.map((item, index) => {
+        if (!v.isPlainObject(item)) {
+          throw badRequest(`members[${index}] must be an object`);
+        }
+        if ('crewMemberId' in item) {
+          const member = v.requireBody(item, ['crewMemberId']);
+          return {
+            crewMemberId: v.parseId(member.crewMemberId, `members[${index}].crewMemberId`)
+          };
+        }
+        const member = v.requireBody(item, ['name', 'role']);
+        return {
+          name: v.parseString(member.name, `members[${index}].name`, { maxLength: 100 }),
+          role: optional(member, 'role', nullableString(100))
+        };
+      });
+      return crew.setEntryCrew(db, id, members, now());
+    })
+  );
+
   // Export
 
   readonly.get(

package/lib/background-schedule.js

@@ -0,0 +1,67 @@
+// Runs a background resolver -- a departure forecast, a landmark lookup -- as
+// its own chain of timeouts: each `resolveNext()` says when the next is due.
+// `nudge()` runs it now -- when a passage opens, rather than leaving it to the
+// idle poll or a retry delay. A nudge during a fetch runs it again as soon as
+// that one ends, never a second chain alongside.
+
+const ERROR_RETRY_MS = 5 * 60 * 1000;
+
+function createBackgroundSchedule({ label, resolver, log, firstDelayMs }) {
+  let timer = null;
+  let running = false;
+  let nudged = false;
+  let stopped = false;
+
+  function schedule(delayMs) {
+    clearTimeout(timer);
+    timer = setTimeout(run, delayMs);
+  }
+
+  async function run() {
+    timer = null;
+    running = true;
+    nudged = false;
+    let result;
+    try {
+      result = await resolver.resolveNext();
+    } catch (err) {
+      log('error', `${label} failed: ${err.stack ?? err}`);
+      result = { retryInMs: ERROR_RETRY_MS };
+    }
+    running = false;
+    if (stopped || result.outcome === 'stopped') {
+      return;
+    }
+    if (result.outcome === 'failed') {
+      // Expected whenever the boat is out of reach of a network.
+      log(
+        'debug',
+        `${label} unavailable, retrying in ${Math.round(result.retryInMs / 60000)} min: ${result.error.message}`
+      );
+    }
+    schedule(nudged ? 0 : result.retryInMs);
+  }
+
+  schedule(firstDelayMs);
+
+  return {
+    nudge() {
+      if (stopped) {
+        return;
+      }
+      if (running) {
+        nudged = true;
+      } else {
+        schedule(0);
+      }
+    },
+
+    stop() {
+      stopped = true;
+      clearTimeout(timer);
+      resolver.stop();
+    }
+  };
+}
+
+module.exports = { createBackgroundSchedule };

package/lib/crew.js

@@ -0,0 +1,185 @@
+const { notFound } = require('./errors');
+
+const nameCollator = new Intl.Collator(undefined, { sensitivity: 'base', numeric: true });
+
+function toCrewMember(row) {
+  return {
+    id: row.id,
+    name: row.name,
+    role: row.role,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+
+function requireCrewMemberRow(db, id) {
+  const row = db.prepare('SELECT * FROM crew_members WHERE id = ?').get(id);
+  if (!row) {
+    throw notFound('crew_member', id);
+  }
+  return row;
+}
+
+// Sorted in JavaScript, same reasoning as listPlaces: SQLite's NOCASE only
+// folds ASCII, and a boat's crew roster stays small enough.
+function listCrewMembers(db, { limit, offset }) {
+  const rows = db.prepare('SELECT * FROM crew_members').all();
+  rows.sort((a, b) => nameCollator.compare(a.name, b.name) || a.id - b.id);
+  return {
+    total: rows.length,
+    limit,
+    offset,
+    items: rows.slice(offset, offset + limit).map(toCrewMember)
+  };
+}
+
+function createCrewMember(db, { name, role }, now) {
+  const { lastInsertRowid } = db
+    .prepare('INSERT INTO crew_members (name, role, created_at, updated_at) VALUES (?, ?, ?, ?)')
+    .run(name, role ?? null, now, now);
+  return toCrewMember(requireCrewMemberRow(db, Number(lastInsertRowid)));
+}
+
+function updateCrewMember(db, id, patch, now) {
+  const row = requireCrewMemberRow(db, id);
+  db.prepare('UPDATE crew_members SET name = ?, role = ?, updated_at = ? WHERE id = ?').run(
+    patch.name ?? row.name,
+    patch.role !== undefined ? patch.role : row.role,
+    now,
+    id
+  );
+  return toCrewMember(requireCrewMemberRow(db, id));
+}
+
+function deleteCrewMember(db, id) {
+  requireCrewMemberRow(db, id);
+  db.prepare('DELETE FROM crew_members WHERE id = ?').run(id);
+}
+
+// Reuses an existing roster member by name (case- and accent-insensitive,
+// like listCrewMembers' sort), the way an unrecognised place name becomes a
+// new place: a role given now fills one the existing member did not have,
+// but never overwrites one already set -- that goes through updateCrewMember.
+function findOrCreateCrewMember(db, name, role, now) {
+  const existing = db
+    .prepare('SELECT * FROM crew_members')
+    .all()
+    .find((row) => nameCollator.compare(row.name, name) === 0);
+  if (!existing) {
+    return createCrewMember(db, { name, role }, now);
+  }
+  if (role !== null && existing.role === null) {
+    db.prepare('UPDATE crew_members SET role = ?, updated_at = ? WHERE id = ?').run(
+      role,
+      now,
+      existing.id
+    );
+    return toCrewMember(requireCrewMemberRow(db, existing.id));
+  }
+  return toCrewMember(existing);
+}
+
+// Who was aboard a passage, in the order they were added.
+function listEntryCrew(db, entryId) {
+  return db
+    .prepare('SELECT * FROM log_entry_crew WHERE entry_id = ? ORDER BY id')
+    .all(entryId)
+    .map((row) => ({
+      id: row.id,
+      crewMemberId: row.crew_member_id,
+      name: row.name,
+      role: row.role
+    }));
+}
+
+// Replaces entryId's crew with exactly `members`: each item is either
+// { crewMemberId } (an existing roster member, 404 if it doesn't exist) or
+// { name, role } (extends the roster via findOrCreateCrewMember).
+// name/role are denormalised onto the junction row at assignment time.
+function setEntryCrew(db, entryId, members, now) {
+  db.prepare('DELETE FROM log_entry_crew WHERE entry_id = ?').run(entryId);
+  const insert = db.prepare(
+    `INSERT INTO log_entry_crew (entry_id, crew_member_id, name, role, created_at)
+     VALUES (?, ?, ?, ?, ?)`
+  );
+  const seen = new Set();
+  for (const member of members) {
+    const row =
+      member.crewMemberId !== undefined
+        ? requireCrewMemberRow(db, member.crewMemberId)
+        : findOrCreateCrewMemberRow(db, member.name, member.role ?? null, now);
+    if (seen.has(row.id)) {
+      continue; // the same roster member picked twice in one request
+    }
+    seen.add(row.id);
+    insert.run(entryId, row.id, row.name, row.role, now);
+  }
+  return listEntryCrew(db, entryId);
+}
+
+function findOrCreateCrewMemberRow(db, name, role, now) {
+  const member = findOrCreateCrewMember(db, name, role, now);
+  return requireCrewMemberRow(db, member.id);
+}
+
+// A new passage starts with the same crew as the one immediately before it
+// (SPEC §4.11), still adjustable from there. Called right after INSERT in
+// openPassage/openEntryByHand, inside the same transaction.
+function copyCrewFromPreviousEntry(db, newEntryId, now) {
+  const previous = db
+    .prepare('SELECT id FROM log_entries WHERE id <> ? ORDER BY start_time DESC, id DESC LIMIT 1')
+    .get(newEntryId);
+  if (!previous) {
+    return;
+  }
+  const insert = db.prepare(
+    `INSERT INTO log_entry_crew (entry_id, crew_member_id, name, role, created_at)
+     VALUES (?, ?, ?, ?, ?)`
+  );
+  for (const member of listEntryCrew(db, previous.id)) {
+    insert.run(newEntryId, member.crewMemberId, member.name, member.role, now);
+  }
+}
+
+// Called from mergeEntries before the later entry's row is deleted: unions
+// laterId's crew onto earlierId's, skipping anyone already aboard -- carry-
+// over means the two lists usually overlap heavily, and the partial unique
+// index forbids assigning the same roster member to one entry twice.
+function absorbCrewOnMerge(db, earlierId, laterId, now) {
+  const earlierCrew = listEntryCrew(db, earlierId);
+  const knownIds = new Set(earlierCrew.map((m) => m.crewMemberId).filter((id) => id !== null));
+  const knownNames = new Set(
+    earlierCrew.filter((m) => m.crewMemberId === null).map((m) => m.name.toLocaleLowerCase())
+  );
+  const insert = db.prepare(
+    `INSERT INTO log_entry_crew (entry_id, crew_member_id, name, role, created_at)
+     VALUES (?, ?, ?, ?, ?)`
+  );
+  for (const member of listEntryCrew(db, laterId)) {
+    if (member.crewMemberId !== null) {
+      if (knownIds.has(member.crewMemberId)) {
+        continue;
+      }
+      knownIds.add(member.crewMemberId);
+    } else {
+      const key = member.name.toLocaleLowerCase();
+      if (knownNames.has(key)) {
+        continue;
+      }
+      knownNames.add(key);
+    }
+    insert.run(earlierId, member.crewMemberId, member.name, member.role, now);
+  }
+}
+
+module.exports = {
+  listCrewMembers,
+  createCrewMember,
+  updateCrewMember,
+  deleteCrewMember,
+  requireCrewMemberRow,
+  listEntryCrew,
+  setEntryCrew,
+  copyCrewFromPreviousEntry,
+  absorbCrewOnMerge
+};