signalk-chiplog 2.7.0 → 2.9.0

package/index.js

@@ -10,6 +10,11 @@ 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 { createSummaryMailer, SUMMARY_MAIL_DEFAULTS } = require('./lib/summary-mailer');
+const { createCloudSync, CLOUD_SYNC_DEFAULTS } = require('./lib/cloud-sync');
+const { createCloudPairing } = require('./lib/cloud-pairing');
+const { createCloudRestore } = require('./lib/cloud-restore');
+const { SECURITIES } = require('./lib/smtp');
 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');
@@ -30,6 +35,12 @@ 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;
+// Likewise: a summary is never urgent, and the passage it is about has been
+// over for at least the reopening delay by the time it is due.
+const FIRST_SUMMARY_MAIL_DELAY_MS = 60 * 1000;
+// The first run after a start reads every passage to work out its hashes: not
+// while detection and the other chains are starting up.
+const FIRST_CLOUD_SYNC_DELAY_MS = 2 * 60 * 1000;
 
 const MOTION_LABELS = { underway: 'Under way', stopped: 'Stopped', unknown: 'Waiting for data' };
 const MODE_LABELS = { autostate: 'navigation.state', fallback: 'speed fallback' };
@@ -64,6 +75,13 @@ module.exports = function (app) {
   // The open passage detection last reported, to notice a new one.
   let lastActiveEntryId = null;
   let usbExport = null;
+  let summaryMailer = null;
+  let cloudSync = null;
+  let cloudSchedule = null;
+  let cloudPairing = null;
+  let cloudRestore = null;
+  // The configuration as saved, so pairing can add the token to it without losing the rest.
+  let savedConfig = {};
   let replayJob = null;
   let namingTimer = null;
   let timers = [];
@@ -195,19 +213,106 @@ module.exports = function (app) {
         title: 'Copy to the USB drive at each arrival',
         default: USB_EXPORT_DEFAULTS.usbExportOnArrival
       },
+      summaryMailEnabled: {
+        type: 'boolean',
+        title: 'Email a summary of each passage',
+        description:
+          'Once a passage is over for good — past the delay within which a new departure would carry it on — sends its map and figures to the addresses below',
+        default: SUMMARY_MAIL_DEFAULTS.summaryMailEnabled
+      },
+      summaryMailTo: {
+        type: 'string',
+        title: 'Summary recipients',
+        description: 'One or more email addresses, separated by commas'
+      },
+      summaryMailFrom: {
+        type: 'string',
+        title: 'Summary sender',
+        description:
+          'The address the summaries are sent from, e.g. logbook@example.org. Most relays insist it be one they are allowed to send for'
+      },
+      smtpHost: {
+        type: 'string',
+        title: 'SMTP server',
+        description: 'The mail relay the summaries are handed to. Leave empty to turn them off'
+      },
+      smtpPort: {
+        type: 'number',
+        title: 'SMTP port',
+        description: '587 for submission with STARTTLS, 465 for implicit TLS, 25 for a local relay',
+        default: SUMMARY_MAIL_DEFAULTS.smtpPort,
+        minimum: 1
+      },
+      smtpSecurity: {
+        type: 'string',
+        title: 'SMTP security',
+        enum: SECURITIES,
+        enumNames: ['STARTTLS (port 587)', 'TLS (port 465)', 'None (local relay only)'],
+        default: SUMMARY_MAIL_DEFAULTS.smtpSecurity
+      },
+      smtpUsername: {
+        type: 'string',
+        title: 'SMTP user name',
+        description: 'Leave empty if the relay needs no authentication'
+      },
+      smtpPassword: {
+        type: 'string',
+        title: 'SMTP password',
+        format: 'password'
+      },
+      summaryMailTileUrl: {
+        type: 'string',
+        title: 'Map tiles for the summary',
+        description:
+          'The tiles the summary map is drawn over. The public OpenStreetMap instance by default (© OpenStreetMap contributors, ODbL), or a self-hosted one; empty draws the track on a plain background',
+        default: SUMMARY_MAIL_DEFAULTS.summaryMailTileUrl
+      },
+      cloudSyncEnabled: {
+        type: 'boolean',
+        title: 'Back the logbook up online',
+        description:
+          'Sends each passage, with its track, events and readings, to the online service below as soon as there is a connection: new and changed passages, newest first, and the removal of those deleted here. Nothing is sent while this is off',
+        default: CLOUD_SYNC_DEFAULTS.cloudSyncEnabled
+      },
+      cloudSyncUrl: {
+        type: 'string',
+        title: 'Online service address',
+        description: 'The address of the Ti Bord service: https://app.tibord.com'
+      },
+      cloudSyncToken: {
+        type: 'string',
+        title: 'Device token',
+        description: 'The token the service gave this boat',
+        format: 'password'
+      },
+      cloudSyncIntervalMinutes: {
+        type: 'number',
+        title: 'Online backup interval (minutes)',
+        description:
+          'How often to check for passages to send; each departure and arrival is sent straight away',
+        default: CLOUD_SYNC_DEFAULTS.cloudSyncIntervalMinutes,
+        minimum: 1
+      },
+      cloudSyncCostlyLink: {
+        type: 'boolean',
+        title: 'Costly link (satellite, roaming)',
+        description:
+          'Sends only a summary of each passage and a thinned-out track, a few kilobytes, at departures and arrivals and every six hours. Full tracks, instrument readings, forecasts and places wait until this is turned off, or until Back up now is chosen on the Export page',
+        default: CLOUD_SYNC_DEFAULTS.cloudSyncCostlyLink
+      },
       logbookLanguage: {
         type: 'string',
-        title: 'Logbook language (PDF)',
+        title: 'Logbook language (PDF and summary emails)',
         description:
-          'Language of the PDF logbook written to the USB drive; downloads from the webapp use the webapp language',
+          'Language of the PDF logbook written to the USB drive and of the passage summary emails; downloads from the webapp use the webapp language',
         enum: PDF_LANGUAGES,
         default: 'en'
       },
       logbookTimeZone: {
         type: 'string',
-        title: 'Ship’s time zone (PDF)',
+        title: 'Ship’s time zone (PDF and summary emails)',
         description:
-          'IANA time zone the PDF logbook on the USB drive is kept in, e.g. Europe/Paris. Empty uses the server’s time zone; downloads from the webapp use the browser’s'
+          'IANA time zone the PDF logbook on the USB drive and the passage summary emails are kept in, e.g. Europe/Paris. Empty uses the server’s time zone; downloads from the webapp use the browser’s'
       },
       windSpeedThresholds: {
         type: 'array',
@@ -367,6 +472,9 @@ module.exports = function (app) {
       // retry delay left from an earlier failure.
       if (outcome.activeEntryId !== null && outcome.activeEntryId !== lastActiveEntryId) {
         schedules.forEach((schedule) => schedule.nudge());
+      } else if (outcome.activeEntryId !== lastActiveEntryId) {
+        // An arrival: back the finished passage up while the boat is in reach.
+        cloudSchedule?.nudge();
       }
       lastActiveEntryId = outcome.activeEntryId;
       const usbError = usbExport.status().lastError;
@@ -440,7 +548,57 @@ module.exports = function (app) {
     version
   });
 
+  // Saves what pairing brought into the plugin configuration, as if typed in the admin, and
+  // starts using it at once: the backup's settings are read on every run, so no restart.
+  function savePairing(url, token) {
+    const next = {
+      ...savedConfig,
+      cloudSyncEnabled: true,
+      cloudSyncUrl: url,
+      cloudSyncToken: token
+    };
+    return new Promise((resolve, reject) => {
+      app.savePluginOptions(next, (err) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        savedConfig = next;
+        if (settings) {
+          settings.cloudSyncEnabled = true;
+          settings.cloudSyncUrl = url;
+          settings.cloudSyncToken = token;
+        }
+        cloudSchedule?.nudge();
+        resolve();
+      });
+    });
+  }
+
+  // Declares the link costly or cheap from the Export page, saved like the rest of the
+  // configuration. Back to cheap, a run starts at once: full passages have been waiting.
+  function saveCostlyLink(costly) {
+    const next = { ...savedConfig, cloudSyncCostlyLink: costly };
+    return new Promise((resolve, reject) => {
+      app.savePluginOptions(next, (err) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        savedConfig = next;
+        if (settings) {
+          settings.cloudSyncCostlyLink = costly;
+        }
+        if (!costly) {
+          cloudSchedule?.nudge();
+        }
+        resolve();
+      });
+    });
+  }
+
   plugin.start = function (config = {}) {
+    savedConfig = config;
     try {
       const { db, migrated } = openDatabase(app.getDataDirPath());
       database = db;
@@ -465,6 +623,26 @@ module.exports = function (app) {
         usbExportIntervalMinutes:
           config.usbExportIntervalMinutes ?? USB_EXPORT_DEFAULTS.usbExportIntervalMinutes,
         usbExportOnArrival: config.usbExportOnArrival ?? USB_EXPORT_DEFAULTS.usbExportOnArrival,
+        summaryMailEnabled: config.summaryMailEnabled ?? SUMMARY_MAIL_DEFAULTS.summaryMailEnabled,
+        summaryMailTo: config.summaryMailTo || null,
+        summaryMailFrom: config.summaryMailFrom || null,
+        smtpHost: config.smtpHost || null,
+        smtpPort: config.smtpPort ?? SUMMARY_MAIL_DEFAULTS.smtpPort,
+        smtpSecurity: SECURITIES.includes(config.smtpSecurity)
+          ? config.smtpSecurity
+          : SUMMARY_MAIL_DEFAULTS.smtpSecurity,
+        smtpUsername: config.smtpUsername || null,
+        smtpPassword: config.smtpPassword || null,
+        summaryMailTileUrl:
+          config.summaryMailTileUrl === undefined
+            ? SUMMARY_MAIL_DEFAULTS.summaryMailTileUrl
+            : config.summaryMailTileUrl,
+        cloudSyncEnabled: config.cloudSyncEnabled ?? CLOUD_SYNC_DEFAULTS.cloudSyncEnabled,
+        cloudSyncUrl: config.cloudSyncUrl || null,
+        cloudSyncToken: config.cloudSyncToken || null,
+        cloudSyncIntervalMinutes:
+          config.cloudSyncIntervalMinutes ?? CLOUD_SYNC_DEFAULTS.cloudSyncIntervalMinutes,
+        cloudSyncCostlyLink: config.cloudSyncCostlyLink ?? CLOUD_SYNC_DEFAULTS.cloudSyncCostlyLink,
         logbookLanguage: PDF_LANGUAGES.includes(config.logbookLanguage)
           ? config.logbookLanguage
           : 'en',
@@ -542,8 +720,46 @@ module.exports = function (app) {
     // 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));
+    summaryMailer = createSummaryMailer({
+      db: database,
+      settings,
+      userAgent: `signalk-chiplog/${version}`,
+      vesselName: () => readVesselName(app),
+      log
+    });
+    cloudSync = createCloudSync({
+      db: database,
+      settings,
+      userAgent: `signalk-chiplog/${version}`,
+      log
+    });
+    // Nudged at departures and arrivals, apart from the forecasts which only
+    // care about departures.
+    cloudSchedule = createBackgroundSchedule({
+      label: 'Online backup',
+      resolver: cloudSync,
+      log,
+      firstDelayMs: FIRST_CLOUD_SYNC_DELAY_MS
+    });
+    cloudPairing = createCloudPairing({
+      db: database,
+      userAgent: `signalk-chiplog/${version}`,
+      log,
+      onPaired: ({ url, token }) => savePairing(url, token)
+    });
+    cloudRestore = createCloudRestore({
+      db: database,
+      settings,
+      userAgent: `signalk-chiplog/${version}`,
+      log,
+      // The backup held off while passages were coming back: it has places to send, at least.
+      onDone: () => cloudSchedule?.nudge()
+    });
+    // A restore the last run left unfinished carries on by itself.
+    cloudRestore.resume();
     lastActiveEntryId = null;
     schedules = [
+      cloudSchedule,
       createBackgroundSchedule({
         label: 'Tide forecast',
         resolver: createTideForecaster(networkOptions),
@@ -561,6 +777,14 @@ module.exports = function (app) {
         resolver: createLandmarkFinder(networkOptions),
         log,
         firstDelayMs: FIRST_LANDMARK_DELAY_MS
+      }),
+      // Nothing nudges this one: a passage becomes due a summary by growing
+      // old enough, not by anything detection reports (SPEC §4.16).
+      createBackgroundSchedule({
+        label: 'Passage summary email',
+        resolver: summaryMailer,
+        log,
+        firstDelayMs: FIRST_SUMMARY_MAIL_DELAY_MS
       })
     ];
     lastStatus = null;
@@ -600,6 +824,13 @@ module.exports = function (app) {
     schedules = [];
     usbExport?.stop();
     usbExport = null;
+    summaryMailer = null;
+    cloudSync = null;
+    cloudSchedule = null;
+    cloudPairing?.stop();
+    cloudPairing = null;
+    cloudRestore?.stop();
+    cloudRestore = null;
     replayJob?.cancel();
     replayJob = null;
     detector = null;
@@ -629,6 +860,12 @@ module.exports = function (app) {
           observeEvent: (entryId, time) => detector.observeEvent(entryId, time),
           noteDeparture: (entryId) => detector.noteDeparture(entryId),
           usbExport,
+          summaryMailer,
+          cloudSync,
+          nudgeCloudSync: () => cloudSchedule?.nudge(),
+          saveCostlyLink,
+          cloudPairing,
+          cloudRestore,
           replayJob,
           pdfOptions,
           detection: () => ({

package/lib/api.js

@@ -499,7 +499,7 @@ function registerRoutes(router, { getContext, logError }) {
 
   readwrite.patch(
     '/api/events/:id',
-    handle(({ db }, req) => {
+    handle(({ db, now }, req) => {
       const id = v.parseId(req.params.id);
       const body = v.requireBody(req.body, ['time', 'comment', 'subtype', 'payload']);
       const patch = withoutUndefined({
@@ -508,7 +508,7 @@ function registerRoutes(router, { getContext, logError }) {
         subtype: optional(body, 'subtype', nullableString(200)),
         payload: optional(body, 'payload', parsePayload)
       });
-      return events.updateEvent(db, id, patch);
+      return events.updateEvent(db, id, patch, { now: now() });
     })
   );
 
@@ -719,6 +719,127 @@ function registerRoutes(router, { getContext, logError }) {
     })
   );
 
+  readonly.get(
+    '/api/summary-mail',
+    handle(({ summaryMailer }) => summaryMailer.status())
+  );
+
+  // Sends one passage's summary now, whether or not it already went out: how
+  // the SMTP settings are tried without waiting for the next arrival.
+  admin.post(
+    '/api/entries/:id/summary-mail',
+    handle(async ({ db, summaryMailer }, req) => {
+      const id = entryId(req);
+      entries.requireEntryRow(db, id);
+      try {
+        return await summaryMailer.send(id);
+      } catch (err) {
+        throw conflict('summary_mail_failed', err.message);
+      }
+    })
+  );
+
+  readonly.get(
+    '/api/cloud-sync',
+    handle(({ cloudSync, cloudPairing, cloudRestore }) => ({
+      ...cloudSync.status(),
+      pairing: cloudPairing.status(),
+      restore: cloudRestore.status()
+    }))
+  );
+
+  // The earlier logbooks of this boat the service can give back, asked of the service now.
+  readonly.get(
+    '/api/cloud-sync/restore',
+    handle(async ({ cloudRestore }) => {
+      try {
+        return { ...cloudRestore.status(), logbooks: await cloudRestore.candidates() };
+      } catch (err) {
+        throw conflict('cloud_restore_failed', err.message);
+      }
+    })
+  );
+
+  // Starts bringing one of them back into this logbook, which must be empty; the restore
+  // goes on in the background and GET /cloud-sync follows it.
+  admin.post(
+    '/api/cloud-sync/restore',
+    handle(({ cloudRestore }, req) => {
+      const logbookId = req.body?.logbookId;
+      if (typeof logbookId !== 'string' || !/^[0-9a-f-]{36}$/i.test(logbookId)) {
+        throw badRequest('logbookId is required');
+      }
+      try {
+        cloudRestore.start(logbookId.toLowerCase());
+      } catch (err) {
+        throw conflict(err.code ?? 'cloud_restore_failed', err.message);
+      }
+      return cloudRestore.status();
+    })
+  );
+
+  // Asks the service for a pairing code, then waits in the background for someone to claim
+  // it; GET /cloud-sync follows the pairing.
+  admin.post(
+    '/api/cloud-sync/pairing',
+    handle(async ({ cloudPairing }, req) => {
+      if (typeof req.body?.url !== 'string' || req.body.url.trim() === '') {
+        throw badRequest('url is required');
+      }
+      try {
+        return await cloudPairing.start(req.body.url.trim());
+      } catch (err) {
+        if (err.code === 'invalid_url') {
+          throw badRequest(err.message);
+        }
+        throw conflict('cloud_pairing_failed', err.message);
+      }
+    })
+  );
+
+  admin.delete(
+    '/api/cloud-sync/pairing',
+    handle(({ cloudPairing }) => {
+      cloudPairing.cancel();
+      return cloudPairing.status();
+    })
+  );
+
+  // Starts a backup run now rather than at the next interval; the run itself
+  // goes on in the background, through its schedule, never alongside another.
+  admin.post(
+    '/api/cloud-sync',
+    handle(({ cloudSync, nudgeCloudSync }) => {
+      const status = cloudSync.status();
+      if (!status.enabled || !status.configured) {
+        throw conflict(
+          'cloud_sync_not_configured',
+          `Turn the online backup on and fill in its settings first${status.problem ? `: ${status.problem}` : ''}`
+        );
+      }
+      // Asked for by hand, the run sends everything in full, costly link or not.
+      cloudSync.requestFull();
+      nudgeCloudSync();
+      return status;
+    })
+  );
+
+  // Declares the link costly, or cheap again (SPEC §4.17).
+  admin.post(
+    '/api/cloud-sync/costly-link',
+    handle(async ({ cloudSync, saveCostlyLink }, req) => {
+      if (typeof req.body?.costly !== 'boolean') {
+        throw badRequest('costly must be true or false');
+      }
+      try {
+        await saveCostlyLink(req.body.costly);
+      } catch (err) {
+        throw conflict('cloud_sync_save_failed', err.message);
+      }
+      return cloudSync.status();
+    })
+  );
+
   readonly.get(
     '/api/replay',
     handle(({ replayJob }) => replayJob.status())

package/lib/cloud-pairing.js

@@ -0,0 +1,172 @@
+const { getLogbookId } = require('./cloud-sync');
+const { qrCode } = require('./qr');
+
+const REQUEST_TIMEOUT_MS = 30 * 1000;
+// When the service is out of reach mid-pairing: keep asking, as long as the code lives.
+const RETRY_MS = 10 * 1000;
+
+class PairingError extends Error {
+  constructor(message, { status = null, code = null } = {}) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+function serviceUrl(text) {
+  let url;
+  try {
+    url = new URL(text);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    return null;
+  }
+  return url.toString().replace(/\/+$/, '');
+}
+
+// Pairs the plugin with the online service by a short code instead of a pasted token
+// (SPEC §4.17): the service hands out a code, someone claims it for their boat, and the plugin,
+// polling meanwhile with a secret only it holds, collects its device token. `onPaired` is
+// given the service address and the token, to save them in the plugin configuration.
+function createCloudPairing({
+  db,
+  userAgent,
+  onPaired,
+  log,
+  fetch = globalThis.fetch,
+  clock = Date.now
+}) {
+  let state = { state: 'idle' };
+  // The current attempt's secret and address, never reported.
+  let attempt = null;
+  let timer = null;
+
+  async function call(url, path, body) {
+    const response = await fetch(`${url}/v1${path}`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'user-agent': userAgent,
+        'x-chiplog-version': userAgent.split('/')[1] ?? ''
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
+    const data = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      throw new PairingError(data.message ?? `The service answered ${response.status}`, {
+        status: response.status,
+        code: data.error ?? null
+      });
+    }
+    return data;
+  }
+
+  function schedule(current, delayMs) {
+    clearTimeout(timer);
+    timer = setTimeout(() => poll(current), delayMs);
+  }
+
+  async function poll(current) {
+    if (attempt !== current) {
+      return;
+    }
+    let result;
+    try {
+      result = await call(current.url, `/pairings/${current.pairingId}/poll`, {
+        pollSecret: current.pollSecret
+      });
+    } catch (error) {
+      if (attempt !== current) {
+        return;
+      }
+      if (error.status === 410 || Date.parse(state.expiresAt) <= clock()) {
+        attempt = null;
+        state = { state: 'expired', at: new Date(clock()).toISOString() };
+      } else if (!(error instanceof PairingError)) {
+        // Out of reach for a moment: the code is still good.
+        schedule(current, RETRY_MS);
+      } else {
+        attempt = null;
+        state = { state: 'failed', error: { message: error.message, code: error.code } };
+      }
+      return;
+    }
+    if (attempt !== current) {
+      return;
+    }
+    if (result.status !== 'paired') {
+      schedule(current, current.pollIntervalMs);
+      return;
+    }
+    attempt = null;
+    try {
+      await onPaired({ url: current.url, token: result.token });
+    } catch (error) {
+      log('error', `Online backup paired, but its settings could not be saved: ${error.message}`);
+      state = { state: 'failed', error: { message: error.message, code: 'save_failed' } };
+      return;
+    }
+    state = {
+      state: 'paired',
+      vesselName: result.vesselName,
+      at: new Date(clock()).toISOString()
+    };
+    log('info', `Online backup paired with ${result.vesselName || 'a vessel'} at ${current.url}`);
+  }
+
+  return {
+    // Asks the service for a code and starts waiting for it to be claimed. A pairing already
+    // under way is dropped: its code was not used.
+    async start(text) {
+      const url = serviceUrl(text);
+      if (!url) {
+        throw new PairingError('The service address must be an http or https URL', {
+          code: 'invalid_url'
+        });
+      }
+      this.cancel();
+      const pairing = await call(url, '/pairings', { logbookId: getLogbookId(db) });
+      const current = {
+        url,
+        pairingId: pairing.pairingId,
+        pollSecret: pairing.pollSecret,
+        pollIntervalMs: Math.max(1, pairing.pollIntervalSeconds) * 1000
+      };
+      attempt = current;
+      state = {
+        state: 'waiting',
+        url,
+        code: pairing.code,
+        claimUrl: pairing.claimUrl ?? null,
+        // The same address as a QR code, for a phone to open: the plugin's page is often on
+        // the chart table, the account on the phone in someone's hand.
+        claimQr: pairing.claimUrl ? qrCode(pairing.claimUrl) : null,
+        expiresAt: pairing.expiresAt
+      };
+      schedule(current, current.pollIntervalMs);
+      return this.status();
+    },
+
+    cancel() {
+      clearTimeout(timer);
+      attempt = null;
+      if (state.state === 'waiting') {
+        state = { state: 'idle' };
+      }
+    },
+
+    status() {
+      return { ...state };
+    },
+
+    stop() {
+      clearTimeout(timer);
+      attempt = null;
+    }
+  };
+}
+
+module.exports = { createCloudPairing, PairingError };