kahu-signalk 0.0.6 → 0.0.8

package/README.md

@@ -185,8 +185,31 @@ wanting to build a more elaborate server-side setup.
 ## Runtime Requirements
 
 - **Signal K Server:** v2.22.1+ (latest stable)
-- **Node.js:** 20.x or later (required by Signal K server v2.22+)
-- **Dependencies:** avro-js, promise-socket, sqlite/sqlite3, uuid
+- **Node.js:** **22.5.0+** (built-in `node:sqlite`; no native `sqlite3` bindings).
+- **Dependencies:** avro-js, promise-socket, uuid
+
+---
+
+## Node.js version (enforced)
+
+This plugin uses **Node’s built-in SQLite** (`node:sqlite`, `DatabaseSync`) — **not** the `sqlite3` npm package. That avoids native addon / binding failures entirely.
+
+| Requirement | Detail |
+|---------------|--------|
+| **Node.js** | **22.5.0 or later** (same major line Signal K recommends) |
+| **Install check** | `npm install` runs a **preinstall** script; it **exits with an error** on older Node so you get a clear message instead of a runtime crash. |
+
+If you see *“kahu-signalk requires Node.js 22.5.0 or later”*, switch the Node version used to run Signal K (e.g. [nvm](https://github.com/nvm-sh/nvm) or [Signal K’s Node guide](https://github.com/SignalK/signalk-server/wiki/Installing-and-Updating-Node.js)), then install the plugin again.
+
+You may see an **ExperimentalWarning** about SQLite from Node; that is expected until the API is stabilized.
+
+### Command typo
+
+Use `--config-dir` (with an **n**), not `--confic-dir`:
+```bash
+npm start -- --config-dir /home/bs01743/Projects/KAHU/signalk-server/signalk-server/config
+```
+The `--` is needed so npm passes `--config-dir` to the start script.
 
 ---
 

package/data/protocol/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 KAHU Earth AS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/data/protocol/README.md

@@ -0,0 +1,13 @@
+# KAHU Radar Hub protocol
+*A radar crowdsourcing protocol*
+
+Contribute AIS and ARPA targets from your vessel to crowdsourcing for marine safety!
+
+This is the ptotocol specification used by our plugins and clients as well as server code (e.g. [radarhub-opencpn](https://github.com/KAHU-radar/radarhub-opencpn) and [radarhub-signalk](https://github.com/KAHU-radar/radarhub-signalk)) that lets you upload AIS and radar ARPA targets (or any NMEA) to an internet server.
+The communication protocol is based on [Apache Avro](https://avro.apache.org/) and batches track points so that the overhead for each point above timestamp and lat/lon is low, meaning it is designed to be as bandwidth conservative as possible.
+
+Note: This protocol does **not** use the Avro RPC mechanism, as it is not well supported in all languages, and adds extra requirements such as adding run-length framing to each message. Instead, it relies on a simple union of message types.
+
+## Database schema
+
+The protocol includes a client side database schema used to cache tracks in an sqlite3 database. It is provided as a series of migration SQL files, to be applied in alphabetical order.

package/data/protocol/migrations/0001-create-targets.sql

@@ -0,0 +1,24 @@
+create table if not exists target (
+    target_id integer primary key autoincrement,
+    uuid varchar(36) unique
+);
+
+create table if not exists target_position (
+    id integer primary key autoincrement,
+    timestamp datetime default current_timestamp,
+    target_id integer references target(id),
+    target_distance float,
+    target_bearing float,
+    target_bearing_unit text,
+    target_speed float,
+    target_course float,
+    target_course_unit text,
+    target_distance_unit text,
+    target_name text,
+    target_status text,
+    latitude float,
+    longitude float,
+    target_latitude float,
+    target_longitude float,
+    sent integer default false
+);

package/data/protocol/migrations/0002-target-indices.sql

@@ -0,0 +1,3 @@
+CREATE INDEX idx_sent ON target_position(sent);
+CREATE INDEX idx_target_id ON target_position(target_id);
+CREATE INDEX idx_sent_target_id_timestamp ON target_position(sent, target_id, timestamp);

package/data/protocol/proto_avro.json

@@ -0,0 +1,71 @@
+{"name": "kahu.Proto", "type": "record",
+ "fields": [
+   {"name": "Message", "type": [
+     {"name": "kahu.Call", "type": "record",
+      "fields": [
+        {"name": "Call", "type": {
+          "name": "kahu.CallMessage", "type": "record",
+          "fields": [
+            {"name": "id", "type": "int"},
+            {"name": "Call", "type": [
+              {"name": "kahu.LoginMessage", "type": "record",
+               "fields": [{"name": "Login", "type": {
+                 "name": "kahu.Login", "type": "record",
+                 "fields": [
+                   {"name": "apikey", "type": "string"}
+                 ]
+               }}]},
+              {"name": "kahu.SubmitMessage", "type": "record",
+               "fields": [{"name": "Submit", "type": {
+                 "name": "kahu.Submit", "type": "record",
+                 "fields": [
+                   {"name": "uuid", "type": ["null", "string"], "logicalType": "uuid"},
+                   {"name": "route", "type": {
+                     "type": "array", "items": {
+                       "name": "kahu.LineString",
+                       "type": "record",
+                       "fields": [
+                         {"name": "lat", "type": "float"},
+                         {"name": "lon", "type": "float"},
+                         {"name": "timestamp", "type": "float"}
+                       ]
+                     }}},
+                   {"name": "nmea", "type": ["null", "string"]},
+                   {"name": "start", "type": "long", "logicalType": "timestamp-millis"}
+                 ]
+               }}]}
+            ]}
+          ]}}
+      ]},
+     {"name": "kahu.Response", "type": "record",
+      "fields": [
+        {"name": "Response", "type": {
+          "name": "kahu.ResponseMessage", "type": "record",
+          "fields": [
+            {"name": "id", "type": "int"},
+            {"name": "Response", "type": [
+              {"name": "kahu.ErrorResponseMessage", "type": "record",
+               "fields": [{"name": "Error", "type": {
+                 "name": "kahu.ErrorResponse", "type": "record",
+                 "fields": [
+                   {"name": "exception", "type": "string"}
+                 ]
+               }}]},
+              {"name": "kahu.LoginResponseMessage", "type": "record",
+               "fields": [{"name": "Login", "type": {
+                 "name": "kahu.LoginResponse", "type": "record",
+                 "fields": []
+               }}]},
+              {"name": "kahu.SubmitResponseMessage", "type": "record",
+               "fields": [{"name": "Submit", "type": {
+                 "name": "kahu.SubmitResponse", "type": "record",
+                 "fields": [
+                   {"name": "uuid", "type": ["null", "string"], "logicalType": "uuid"}
+                 ]
+               }}]}
+            ]}
+          ]}}
+      ]}
+   ]}
+ ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kahu-signalk",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Contribute AIS and ARPA targets from your vessel to crowdsourcing for marine safety!",
   "keywords": [
     "signalk-node-server-plugin",
@@ -15,9 +15,10 @@
   },
   "main": "plugin/index.js",
   "engines": {
-    "node": ">=20"
+    "node": ">=22.5.0"
   },
   "scripts": {
+    "preinstall": "node scripts/check-node-version.js",
     "test": "echo \"Error: no test specified passing build\" && exit 0"
   },
   "author": "Kahu <info@kahu.earth>",
@@ -29,8 +30,6 @@
   "dependencies": {
     "avro-js": "^1.12.0",
     "promise-socket": "^8.0.0",
-    "sqlite": "^5.1.1",
-    "sqlite3": "^6.0.1",
     "uuid": "^8.1.0"
   }
 }

package/plugin/routecache.js

@@ -1,8 +1,23 @@
-const sqlite3 = require('sqlite3').verbose();
-const sqlite = require('sqlite');
 const fs = require('fs').promises;
 const path = require('path');
 
+let DatabaseSync;
+try {
+  ({ DatabaseSync } = require('node:sqlite'));
+} catch (e) {
+  DatabaseSync = null;
+}
+
+function requireNodeSqlite() {
+  if (!DatabaseSync) {
+    throw new Error(
+      'kahu-signalk requires Node.js 22.5+ (built-in node:sqlite). ' +
+      'Install Node 22 LTS as recommended for Signal K: ' +
+      'https://github.com/SignalK/signalk-server/wiki/Installing-and-Updating-Node.js'
+    );
+  }
+}
+
 class Routecache {
   constructor(migrations_dir, db_name) {
     this.db = null;
@@ -11,8 +26,25 @@ class Routecache {
     console.log("Routecache created for " + db_name + " with migrations " + migrations_dir);
   }
 
+  _sanitizeParam(v) {
+    return v === undefined ? null : v;
+  }
+
+  _all(sql, params = []) {
+    const stmt = this.db.prepare(sql);
+    const safe = params.map(this._sanitizeParam);
+    return safe.length ? stmt.all(...safe) : stmt.all();
+  }
+
+  _run(sql, params = []) {
+    const stmt = this.db.prepare(sql);
+    const safe = params.map(this._sanitizeParam);
+    return safe.length ? stmt.run(...safe) : stmt.run();
+  }
+
   async init() {
     try {
+      requireNodeSqlite();
       await this.openDB();
       await this.createEmpty();
       await this.migrate();
@@ -30,33 +62,30 @@ class Routecache {
     }
   }
 
-  async doesTableExist(tableName) {
-    const query = await this.db.all(
-      "SELECT count(*) as count FROM sqlite_master WHERE type='table' AND name=?",
-      [tableName]);
-    return query[0].count > 0;
+  doesTableExist(tableName) {
+    const row = this.db
+      .prepare("SELECT count(*) as count FROM sqlite_master WHERE type='table' AND name=?")
+      .get(tableName);
+    return Number(row.count) > 0;
   }
 
   async destroy() {
-    if (this.db != null) await this.db.close();
+    if (this.db != null) this.db.close();
     this.db = null;
   }
 
   async openDB() {
-    this.db = await sqlite.open({
-      filename: this.db_name,
-      driver: sqlite3.Database
-    });
+    this.db = new DatabaseSync(this.db_name);
   }
 
   async closeDB() {
-    if (this.db != null) await this.db.close();
+    if (this.db != null) this.db.close();
     this.db = null;
   }
 
   async createEmpty() {
     if (await this.doesTableExist("migrations")) return;
-    const res = await this.db.run(`
+    this.db.exec(`
         CREATE TABLE IF NOT EXISTS migrations (
             id integer,
             name text,
@@ -66,58 +95,51 @@ class Routecache {
   }
 
   async migrate() {
-    const rows = await this.db.all(
-      "SELECT max(id) as maxid FROM migrations");
+    const rows = this._all("SELECT max(id) as maxid FROM migrations");
     const maxId = rows[0].maxid;
+    const baseline = maxId == null ? 0 : Number(maxId);
 
     try {
       const files = (
-        await fs.readdir(
-          this.migrations_dir, { withFileTypes: true }
-        )
-      ).filter(
-        (file) => file.isFile()
-      ).map(
-        (file) => file.name);
+        await fs.readdir(this.migrations_dir, { withFileTypes: true })
+      )
+        .filter((file) => file.isFile())
+        .map((file) => file.name);
       files.sort();
-      
+
       for (const filename of files) {
         const migrationId = parseInt(filename, 10);
-        if (migrationId > maxId) {
-          const migrationPath = path.join(this.migrations_dir, filename);
-          await this.runMigration(migrationId, migrationPath);
-        }
+        if (!Number.isFinite(migrationId) || migrationId <= baseline) continue;
+        const migrationPath = path.join(this.migrations_dir, filename);
+        await this.runMigration(migrationId, migrationPath);
       }
     } catch (error) {
-        throw new Error(`Unable to process migrations directory: ${error.message}`);
+      throw new Error(`Unable to process migrations directory: ${error.message}`);
     }
   }
 
   async runMigration(i, name) {
     console.error("Running migration ", i, ": ", name);
 
-    const sql = await fs.readFile(name, 'utf8');    
-    await this.db.exec(sql);
-    await this.db.run(
-      "insert into migrations (id, name) values (?, ?)",
-      [i, name]);
+    const sql = await fs.readFile(name, 'utf8');
+    this.db.exec(sql);
+    this._run("insert into migrations (id, name) values (?, ?)", [i, name]);
   }
 
-  async insert({...props}) {
-    const target_count = await this.db.all(`
-      select count(*) as count from target where uuid = ?;
-    `, [props.target_id]);
-    if (target_count[0].count == 0) {
-      await this.db.run(`
-        insert into target (uuid) values (?);
-      `, [props.target_id]);
+  async insert({ ...props }) {
+    const target_count = this._all(
+      `select count(*) as count from target where uuid = ?;`,
+      [props.target_id]
+    );
+    if (Number(target_count[0].count) === 0) {
+      this._run(`insert into target (uuid) values (?);`, [props.target_id]);
     }
-    const target = await this.db.all(`
-      select target_id from target where uuid = ?;
-    `, [props.target_id]);
-    
-    await this.db.run(`
-      insert into target_position (
+    const target = this._all(`select target_id from target where uuid = ?;`, [
+      props.target_id,
+    ]);
+
+    this._run(
+      `insert into target_position (
         target_id,
         target_distance,
         target_bearing,
@@ -135,32 +157,35 @@ class Routecache {
       ) values (
         ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
    `,
-      [target[0].target_id,
-       props.position?.relative?.distance,
-       props.position?.relative?.bearing,
-       props.position?.relative?.bearing_unit,
-       props.speedOverGround,
-       props.courseOverGroundTrue,
-       'T', // target_course_unit
-       props.position?.relative?.distance_unit,
-       props.name,
-       'T', //props.target_status,
-       props.position?.relative?.position?.latitude,
-       props.position?.relative?.position?.longitude,
-       props.position?.latitude,
-       props.position?.longitude]);
+      [
+        target[0].target_id,
+        props.position?.relative?.distance,
+        props.position?.relative?.bearing,
+        props.position?.relative?.bearing_unit,
+        props.speedOverGround,
+        props.courseOverGroundTrue,
+        'T',
+        props.position?.relative?.distance_unit,
+        props.name,
+        'T',
+        props.position?.relative?.position?.latitude,
+        props.position?.relative?.position?.longitude,
+        props.position?.latitude,
+        props.position?.longitude,
+      ]
+    );
   }
 
   async connectionStats() {
-    const query1 = await this.db.all(`
+    const query1 = this._all(`
       select
         count(*) as unsent_datapoints
       from
         target_position
-      where       
+      where
         not sent;
       `);
-    const query2 = await this.db.all(`
+    const query2 = this._all(`
       select
         count(*) as unsent_tracks
       from
@@ -172,12 +197,14 @@ class Routecache {
            not sent
         )
     `);
-    return {unsent_datapoints: query1[0].unsent_datapoints,
-            unsent_tracks: query2[0].unsent_tracks};
+    return {
+      unsent_datapoints: Number(query1[0].unsent_datapoints),
+      unsent_tracks: Number(query2[0].unsent_tracks),
+    };
   }
-  
+
   async retrieve() {
-    const query = await this.db.all(`
+    const query = this._all(`
       select
         target.uuid,
         target_position.timestamp,
@@ -201,9 +228,9 @@ class Routecache {
                 target_id
               from
                 target_position
-              group by 
+              group by
                 target_id
-              having 
+              having
                 count(*) > 1
             )
           order by
@@ -218,19 +245,17 @@ class Routecache {
     if (!query.length) return null;
 
     const res = {
-      uuid: {"string": query[0].uuid},
+      uuid: { string: query[0].uuid },
       route: [],
       nmea: null,
-      start: query[0].timestamp_epoch};
-
-    let isfirst = true;
-    let start;
+      start: Number(query[0].timestamp_epoch),
+    };
 
     for (const row of query) {
       res.route.push({
         lat: row.target_latitude,
         lon: row.target_longitude,
-        timestamp: row.timestamp_epoch - res.start
+        timestamp: Number(row.timestamp_epoch) - res.start,
       });
     }
 
@@ -238,28 +263,32 @@ class Routecache {
   }
 
   async markAsSent(route_message) {
-    const end = route_message.route[route_message.route.length - 1].timestamp + route_message.start;
+    const end =
+      route_message.route[route_message.route.length - 1].timestamp +
+      route_message.start;
 
     const uuid = route_message.uuid.string;
-    
-    const query = await this.db.run(`
-      update
+
+    const result = this._run(
+      `update
         target_position
       set
         sent = 1
       where
         target_id = (select target_id from target where uuid = ?)
-        and timestamp <= datetime(? / 1000, 'unixepoch');
-    `, [uuid, end]);
-    
+        and timestamp <= datetime(? / 1000, 'unixepoch');`,
+      [uuid, end]
+    );
+
     console.error(
-      "Updated "
-        + query.changes
-        + " rows for "
-        + uuid
-        + " @ "
-        + end
-        + ".");
+      'Updated ' +
+        result.changes +
+        ' rows for ' +
+        uuid +
+        ' @ ' +
+        end +
+        '.'
+    );
   }
 }
 

package/scripts/check-node-version.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * kahu-signalk uses Node's built-in node:sqlite (no native sqlite3 bindings).
+ * Requires Node 22.5+ where DatabaseSync is available.
+ */
+const [major, minor] = process.versions.node.split('.').map(Number);
+const ok = major > 22 || (major === 22 && minor >= 5);
+if (!ok) {
+  console.error(
+    '\nkahu-signalk requires Node.js 22.5.0 or later.\n' +
+      'This plugin uses the built-in SQLite module (node:sqlite) so it does not depend on native sqlite3 binaries.\n' +
+      'Signal K recommends Node 22: https://github.com/SignalK/signalk-server/wiki/Installing-and-Updating-Node.js\n' +
+      `Current Node version: ${process.version}\n`
+  );
+  process.exit(1);
+}