signalk-chiplog 1.0.0

package/lib/usb-scheduler.js

@@ -0,0 +1,131 @@
+const { writeUsbExport } = require('./export');
+
+// SPEC §4.5: the abandon-ship copy is kept current without anyone thinking of
+// it — every few minutes, and as soon as a passage ends.
+const USB_EXPORT_DEFAULTS = { usbExportIntervalMinutes: 15, usbExportOnArrival: true };
+
+const CHECK_INTERVAL_MS = 30 * 1000;
+// Leaves the drive time to be mounted after the host boots.
+const FIRST_EXPORT_DELAY_MS = 60 * 1000;
+
+const iso = (ms) => new Date(ms).toISOString();
+
+function createUsbExportScheduler({
+  db,
+  settings,
+  clock = Date.now,
+  write = writeUsbExport,
+  log = () => {}
+}) {
+  const intervalMs = settings.usbExportIntervalMinutes * 60 * 1000;
+  let nextDueAt = intervalMs > 0 ? clock() + FIRST_EXPORT_DELAY_MS : null;
+  let lastActiveEntryId;
+  let current = null;
+  let queued = null;
+  let stopped = false;
+  let lastSuccess = null;
+  let lastError = null;
+
+  async function perform(reason) {
+    const startedAt = clock();
+    try {
+      const result = await write(db, settings.usbExportPath, iso(startedAt));
+      if (lastError) {
+        log('info', `USB copy written again (${reason})`);
+      }
+      lastSuccess = {
+        at: iso(clock()),
+        reason,
+        entries: result.entries,
+        written: result.written,
+        unchanged: result.unchanged,
+        removed: result.removed.length
+      };
+      lastError = null;
+      return result;
+    } catch (err) {
+      if (stopped) {
+        throw err;
+      }
+      // A missing drive is reported once, not every quarter of an hour.
+      if (!lastError || lastError.message !== err.message) {
+        log('error', `USB copy failed (${reason}): ${err.message}`);
+      }
+      lastError = { at: iso(clock()), reason, code: err.code ?? null, message: err.message };
+      throw err;
+    }
+  }
+
+  // One write at a time: a request while one runs is served by a single write
+  // after it, which then includes whatever changed meanwhile.
+  function run(reason) {
+    if (!settings.usbExportPath) {
+      return Promise.resolve(null);
+    }
+    if (!current) {
+      current = perform(reason).finally(() => {
+        current = null;
+      });
+      return current;
+    }
+    queued ??= current
+      .catch(() => {})
+      .then(() => {
+        queued = null;
+        return run(reason);
+      });
+    return queued;
+  }
+
+  const background = (reason) => run(reason).catch(() => {});
+
+  return {
+    run,
+
+    // Called every few seconds.
+    tick() {
+      if (stopped || nextDueAt === null || !settings.usbExportPath) {
+        return;
+      }
+      const now = clock();
+      if (now >= nextDueAt) {
+        nextDueAt = now + intervalMs;
+        background('scheduled');
+      }
+    },
+
+    // Called with each detection outcome: the open passage going away, or
+    // giving way to another, is an arrival.
+    afterDetection({ activeEntryId }) {
+      const previous = lastActiveEntryId;
+      lastActiveEntryId = activeEntryId;
+      if (
+        !stopped &&
+        settings.usbExportOnArrival &&
+        previous !== undefined &&
+        previous !== null &&
+        previous !== activeEntryId
+      ) {
+        background('arrival');
+      }
+    },
+
+    status() {
+      return {
+        configured: Boolean(settings.usbExportPath),
+        intervalMinutes: settings.usbExportIntervalMinutes,
+        onArrival: settings.usbExportOnArrival,
+        running: current !== null,
+        nextAt: settings.usbExportPath && nextDueAt !== null ? iso(nextDueAt) : null,
+        lastSuccess,
+        lastError
+      };
+    },
+
+    stop() {
+      stopped = true;
+    }
+  };
+}
+
+module.exports = { createUsbExportScheduler, USB_EXPORT_DEFAULTS, CHECK_INTERVAL_MS };

package/lib/validation.js

@@ -0,0 +1,105 @@
+const { badRequest } = require('./errors');
+
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 500;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function requireBody(body, allowedFields) {
+  if (!isPlainObject(body)) {
+    throw badRequest('Request body must be a JSON object');
+  }
+  const unknown = Object.keys(body).filter((field) => !allowedFields.includes(field));
+  if (unknown.length > 0) {
+    throw badRequest(`Unknown field(s): ${unknown.join(', ')}`);
+  }
+  return body;
+}
+
+function parseId(value, name = 'id') {
+  if (!/^[1-9]\d*$/.test(String(value))) {
+    throw badRequest(`${name} must be a positive integer`);
+  }
+  return Number(value);
+}
+
+function parseTimestamp(value, name) {
+  const date = typeof value === 'string' ? new Date(value) : null;
+  if (!date || Number.isNaN(date.getTime())) {
+    throw badRequest(`${name} must be an ISO 8601 timestamp`);
+  }
+  return date.toISOString();
+}
+
+function parseOptionalTimestamp(value, name) {
+  return value === undefined ? undefined : parseTimestamp(value, name);
+}
+
+function parseNonNegativeNumber(value, name) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+    throw badRequest(`${name} must be a non-negative number`);
+  }
+  return value;
+}
+
+function parsePosition(value, name) {
+  if (value === null) {
+    return null;
+  }
+  const valid =
+    isPlainObject(value) &&
+    typeof value.lat === 'number' &&
+    typeof value.lon === 'number' &&
+    value.lat >= -90 &&
+    value.lat <= 90 &&
+    value.lon >= -180 &&
+    value.lon <= 180;
+  if (!valid) {
+    throw badRequest(`${name} must be { lat, lon } in decimal degrees, or null`);
+  }
+  return { lat: value.lat, lon: value.lon };
+}
+
+function parseString(value, name, { maxLength = 1000, allowNull = false } = {}) {
+  if (value === null && allowNull) {
+    return null;
+  }
+  if (typeof value !== 'string' || value.trim() === '' || value.length > maxLength) {
+    throw badRequest(`${name} must be a non-empty string of at most ${maxLength} characters`);
+  }
+  return value.trim();
+}
+
+function parsePagination(query) {
+  const limit = query.limit === undefined ? DEFAULT_LIMIT : Number(query.limit);
+  const offset = query.offset === undefined ? 0 : Number(query.offset);
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+    throw badRequest(`limit must be an integer between 1 and ${MAX_LIMIT}`);
+  }
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw badRequest('offset must be a non-negative integer');
+  }
+  return { limit, offset };
+}
+
+function parseEnum(value, name, allowed) {
+  if (!allowed.includes(value)) {
+    throw badRequest(`${name} must be one of: ${allowed.join(', ')}`);
+  }
+  return value;
+}
+
+module.exports = {
+  isPlainObject,
+  requireBody,
+  parseId,
+  parseTimestamp,
+  parseOptionalTimestamp,
+  parseNonNegativeNumber,
+  parsePosition,
+  parseString,
+  parsePagination,
+  parseEnum
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "signalk-chiplog",
+  "version": "1.0.0",
+  "description": "Automated digital logbook plugin for Signal K, with keyboard/handwritten entry on tablet",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "lib/",
+    "public/",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "demo:seed": "node scripts/seed-demo.js",
+    "prepare": "husky && node scripts/vendor.js"
+  },
+  "keywords": [
+    "signalk-node-server-plugin",
+    "signalk-webapp",
+    "signalk-category-utility",
+    "signalk",
+    "logbook"
+  ],
+  "signalk": {
+    "displayName": "Chiplog",
+    "appIcon": "./icon.svg"
+  },
+  "author": "Cedric RICARD <ricard33@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ricard33/signalk-chiplog.git"
+  },
+  "homepage": "https://github.com/ricard33/signalk-chiplog#readme",
+  "bugs": {
+    "url": "https://github.com/ricard33/signalk-chiplog/issues"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "lint-staged": {
+    "*.{js,mjs}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,css,html}": [
+      "prettier --write"
+    ]
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.10.0",
+    "eslint-config-prettier": "^10.1.8",
+    "express": "^4.22.2",
+    "globals": "^17.12.0",
+    "htm": "^3.1.1",
+    "husky": "^9.1.7",
+    "leaflet": "^1.9.4",
+    "lint-staged": "^17.5.1",
+    "preact": "^10.29.8",
+    "prettier": "^3.9.6"
+  }
+}