signalk-webhook-bridge 2.0.0

package/plugin/index.js

@@ -0,0 +1,481 @@
+/**
+ * plugin/index.js
+ *
+ * Signal K Webhook Bridge.
+ *
+ * Captures configured Signal K values at a selected interval,
+ * stores every snapshot in a persistent SQLite FIFO queue,
+ * and delivers queued entries to the configured webhook in order.
+ * Adds output-unit labels, retries backlog on startup and after each capture,
+ * and exposes path metadata and a configuration schema for the admin interface.
+ */
+
+const { getAvailablePaths } = require("./paths");
+const { convertValue, getOutputUnitLabel } = require("./units");
+const { sendWebhook } = require("./webhook");
+const storage = require("./storage");
+
+module.exports = function (app) {
+	const plugin = {};
+
+	plugin.id = "signalk-webhook-bridge";
+
+	plugin.name = "Webhook Bridge";
+
+	plugin.description =
+		"Send selected Signal K data paths to an external webhook, with configurable paths, units and offline storage.";
+
+	let captureTimer = null;
+	let currentSettings = null;
+	let deliveryRunning = false;
+	let stopped = false;
+
+	let lastCapture = null;
+	let lastDelivery = null;
+	let lastError = null;
+	let deliveryState = "idle";
+
+	/**
+	 * Read configured vessel values, unwrap Signal K value records and convert units.
+	 * Field names prefer fieldName, then the schema name, then the original path.
+	 */
+	function buildSnapshot(settings) {
+		const payload = {};
+		const units = {};
+
+		const configuredPaths =
+			Array.isArray(settings.paths) ? settings.paths : [];
+
+		configuredPaths.forEach((configuredPath) => {
+			if (!configuredPath || !configuredPath.path) {
+				return;
+			}
+
+			const entry = app.getSelfPath(configuredPath.path);
+
+			const value =
+				(
+					entry &&
+					typeof entry === "object" &&
+					Object.prototype.hasOwnProperty.call(entry, "value")
+				) ?
+					entry.value
+				:	entry;
+
+			const fieldName =
+				configuredPath.fieldName ||
+				configuredPath.name ||
+				configuredPath.path;
+
+			const outputUnits = configuredPath.units || "native";
+
+			payload[fieldName] = convertValue(value, outputUnits);
+
+			/*
+			 * Report the actual unit sent to the receiving endpoint.
+			 *
+			 * If "native" is selected, use the Signal K metadata unit.
+			 * Otherwise use the configured converted unit.
+			 */
+			const metadata = app.getMetadata(
+				`vessels.self.${configuredPath.path}`,
+			);
+
+			units[fieldName] = getOutputUnitLabel(outputUnits, metadata?.units);
+		});
+
+		payload.units = units;
+
+		return payload;
+	}
+
+	/**
+	 * Add a new snapshot to persistent storage.
+	 *
+	 * Data is always written to the queue BEFORE any delivery attempt.
+	 */
+	function captureSnapshot() {
+		if (!currentSettings) {
+			return;
+		}
+
+		try {
+			const payload = buildSnapshot(currentSettings);
+
+			const queued = storage.enqueue(payload);
+
+			lastCapture = queued.createdAt;
+			deliveryState = "queued";
+
+			app.debug(
+				`Queued webhook snapshot ${queued.id} at ${queued.createdAt}`,
+			);
+
+			/*
+			 * Try delivery immediately after capturing.
+			 * If a delivery worker is already active, it continues draining the same queue.
+			 */
+			processQueue();
+		} catch (error) {
+			lastError = error.message;
+			deliveryState = "error";
+
+			app.error(`Unable to capture webhook snapshot: ${error.message}`);
+		}
+	}
+
+	/**
+	 * Deliver queued entries in strict FIFO order.
+	 *
+	 * Only one delivery worker may operate at a time.
+	 *
+	 * A queued entry is removed only after the webhook confirms
+	 * successful delivery.
+	 *
+	 * On failure the entry remains at the front of the queue and
+	 * processing stops until another delivery attempt is triggered.
+	 */
+	async function processQueue() {
+		if (deliveryRunning || stopped || !currentSettings) {
+			return;
+		}
+
+		if (!currentSettings.webhookUrl) {
+			return;
+		}
+
+		deliveryRunning = true;
+		deliveryState = "delivering";
+
+		try {
+			while (!stopped) {
+				const queuedItem = storage.peekOldest();
+
+				if (!queuedItem) {
+					break;
+				}
+
+				/*
+				 * Preserve the original capture time when old entries are
+				 * eventually delivered after an offline period.
+				 */
+				const outgoingPayload = {
+					timestamp: queuedItem.createdAt,
+					...queuedItem.payload,
+				};
+
+				try {
+					await sendWebhook({
+						url: currentSettings.webhookUrl,
+						authKey: currentSettings.authKey,
+						payload: outgoingPayload,
+						app,
+					});
+
+					storage.remove(queuedItem.id);
+
+					lastDelivery = new Date().toISOString();
+					lastError = null;
+
+					app.debug(
+						`Delivered queued webhook entry ${queuedItem.id}`,
+					);
+				} catch (error) {
+					/*
+					 * Leave the oldest entry untouched.
+					 *
+					 * This preserves FIFO order and prevents newer entries
+					 * overtaking an entry that has not been delivered.
+					 */
+
+					lastError = error.message;
+					deliveryState = "waiting";
+
+					app.debug(
+						`Webhook delivery unavailable. Queue retained: ${error.message}`,
+					);
+
+					break;
+				}
+			}
+		} catch (error) {
+			app.error(`Error while processing webhook queue: ${error.message}`);
+		} finally {
+			deliveryRunning = false;
+
+			if (!stopped && deliveryState !== "waiting") {
+				try {
+					deliveryState =
+						storage.count() > 0 ? "queued" : "connected";
+				} catch (error) {
+					deliveryState = "error";
+					lastError = error.message;
+				}
+			}
+
+			
+			// Complete deferred cleanup after any in-flight request has settled.
+			if (stopped) {
+				storage.close();
+			}
+		}
+	}
+
+	// Open storage, attempt backlog delivery and schedule the first capture after one interval.
+	plugin.start = function (settings) {
+		app.debug("Starting Signal K Webhook Bridge");
+
+		currentSettings = settings || {};
+		stopped = false;
+
+		try {
+			storage.openQueue(app);
+
+			const queuedEntries = storage.count();
+
+			app.debug(
+				`Webhook queue contains ${queuedEntries} entr${
+					queuedEntries === 1 ? "y" : "ies"
+				}`,
+			);
+		} catch (error) {
+			app.error(`Unable to open webhook queue: ${error.message}`);
+
+			return;
+		}
+
+		/*
+		 * sendFreq is configured in minutes.
+		 */
+		const sendFreq = Number(currentSettings.sendFreq) || 10;
+		const intervalMilliseconds = sendFreq * 60 * 1000;
+
+		app.debug(
+			`Webhook capture interval set to ${sendFreq} minute${
+				sendFreq === 1 ? "" : "s"
+			}`,
+		);
+
+		/*
+		 * Immediately attempt to clear any backlog left from a previous
+		 * offline period or server restart.
+		 *
+		 * We do NOT capture a new snapshot immediately. New snapshots
+		 * follow the configured interval.
+		 */
+		processQueue();
+
+		captureTimer = setInterval(captureSnapshot, intervalMilliseconds);
+	};
+
+	// Stop future captures; an in-flight delivery finishes before its worker closes storage.
+	plugin.stop = function () {
+		app.debug("Stopping Signal K Webhook Bridge");
+
+		stopped = true;
+
+		if (captureTimer) {
+			clearInterval(captureTimer);
+			captureTimer = null;
+		}
+
+		currentSettings = null;
+
+		/*
+		 * processQueue may still be awaiting an HTTP request when stop()
+		 * is called. We therefore avoid closing SQLite underneath an
+		 * active delivery operation.
+		 */
+		if (!deliveryRunning) {
+			storage.close();
+		}
+	};
+
+	/**
+	 * Return currently available Signal K paths and schema metadata
+	 * for the custom configuration panel.
+	 */
+	plugin.registerWithRouter = function (router) {
+		router.get("/paths", (req, res) => {
+			try {
+				const availablePaths = getAvailablePaths(app);
+
+				const paths = availablePaths.map((path) => {
+					const metadata = app.getMetadata(`vessels.self.${path}`);
+
+					return {
+						path,
+						units: metadata?.units || null,
+						displayName: metadata?.displayName || null,
+						description: metadata?.description || null,
+						displayUnits: metadata?.displayUnits || null,
+					};
+				});
+
+				res.status(200).json({
+					paths,
+				});
+			} catch (error) {
+				app.error(
+					`Unable to retrieve available Signal K paths: ${error.message}`,
+				);
+
+				res.status(500).json({
+					error: "Unable to retrieve available Signal K paths",
+				});
+			}
+		});
+		router.get("/status", (req, res) => {
+			try {
+				const queueCount = storage.count();
+
+				res.status(200).json({
+					queueCount,
+					deliveryState,
+					lastCapture,
+					lastDelivery,
+					lastError,
+				});
+			} catch (error) {
+				app.error(
+					`Unable to retrieve webhook status: ${error.message}`,
+				);
+
+				res.status(500).json({
+					error: "Unable to retrieve webhook status",
+				});
+			}
+		});
+
+		router.post("/retry", async (req, res) => {
+			try {
+				await processQueue();
+
+				res.status(200).json({
+					success: true,
+					queueCount: storage.count(),
+					deliveryState,
+					lastCapture,
+					lastDelivery,
+					lastError,
+				});
+			} catch (error) {
+				app.error(`Unable to retry webhook delivery: ${error.message}`);
+
+				res.status(500).json({
+					success: false,
+					error: "Unable to retry webhook delivery",
+				});
+			}
+		});
+	};
+
+	/**
+	 * Describe webhook settings and path mappings for the schema-based configuration form.
+	 * Path choices are discovered when requested; the custom panel filters units by metadata.
+	 */
+	plugin.schema = function () {
+		const availablePaths = getAvailablePaths(app);
+
+		app.debug(`Found ${availablePaths.length} available Signal K paths`);
+
+		return {
+			type: "object",
+
+			required: ["sendFreq", "webhookUrl"],
+
+			properties: {
+				webhookUrl: {
+					type: "string",
+					title: "Webhook URL",
+					description:
+						"The destination URL that data will be sent to.",
+					default: "",
+				},
+
+				authKey: {
+					type: "string",
+					title: "Authentication Key",
+					description:
+						"Optional authentication key to include with webhook requests.",
+					default: "",
+				},
+
+				sendFreq: {
+					type: "number",
+					title: "Send Interval",
+					description:
+						"How often data should be captured and sent, in minutes.",
+					default: 10,
+					minimum: 1,
+				},
+
+				paths: {
+					type: "array",
+					title: "Signal K Data Paths",
+					description:
+						"Add the Signal K values you want to include in each webhook request.",
+
+					items: {
+						type: "object",
+						required: ["path"],
+
+						properties: {
+							path: {
+								type: "string",
+								title: "Signal K Path",
+								description:
+									"Select one of the Signal K paths currently available on this vessel.",
+								enum: availablePaths,
+							},
+
+							name: {
+								type: "string",
+								title: "Webhook Field Name",
+								description:
+									"Optional shorter name for this value in the outgoing JSON.",
+								default: "",
+							},
+
+							units: {
+								type: "string",
+								title: "Output Units",
+								default: "native",
+
+								enum: [
+									"native",
+									"knots",
+									"kmh",
+									"mph",
+									"metres",
+									"feet",
+									"degrees",
+									"celsius",
+									"fahrenheit",
+									"hpa",
+									"mbar",
+								],
+
+								enumNames: [
+									"Native Signal K units",
+									"Knots",
+									"km/h",
+									"mph",
+									"Metres",
+									"Feet",
+									"Degrees",
+									"Celsius",
+									"Fahrenheit",
+									"hPa",
+									"mbar",
+								],
+							},
+						},
+					},
+				},
+			},
+		};
+	};
+
+	return plugin;
+};

package/plugin/paths.js

@@ -0,0 +1,38 @@
+/**
+ * plugin/paths.js
+ *
+ * Discovers available Signal K stream paths for the API and configuration schema.
+ * Checks the server response, removes exact duplicates, trims and sorts path names.
+ */
+
+// Share path discovery between the HTTP endpoint and configuration schema.
+function getAvailablePaths(app) {
+	// A server without this API can still render configuration with an empty list.
+	if (
+		!app.streambundle ||
+		typeof app.streambundle.getAvailablePaths !== "function"
+	) {
+		app.debug("streambundle.getAvailablePaths() is not available");
+		return [];
+	}
+
+	const paths = app.streambundle.getAvailablePaths();
+
+	// Guard the array operations below against an unexpected server response.
+	if (!Array.isArray(paths)) {
+		app.debug("getAvailablePaths() did not return an array");
+		return [];
+	}
+
+	// Remove exact duplicates, keep non-empty strings, trim and sort for display.
+	// Deduplication happens before trimming, so whitespace variants can remain.
+	return [...new Set(paths)]
+		.filter((path) => typeof path === "string")
+		.map((path) => path.trim())
+		.filter((path) => path.length > 0)
+		.sort();
+}
+
+module.exports = {
+	getAvailablePaths,
+};

package/plugin/storage.js

@@ -0,0 +1,145 @@
+/**
+ * plugin/storage.js
+ *
+ * Persists pending webhook payloads in a SQLite queue in the plugin data directory.
+ * Provides operations to enqueue, inspect the oldest entry, remove entries and count
+ * pending records. The caller handles delivery and removes entries after success.
+ * Stores JSON and enqueue timestamps in webhook-queue.sqlite, ordered by record ID.
+ * Uses Node's built-in SQLite API with a shared synchronous database connection.
+ */
+
+const path = require("path");
+const fs = require("fs");
+const { DatabaseSync } = require("node:sqlite");
+
+// Reuse one connection until close() releases it.
+let db = null;
+
+// Open the persistent queue, creating its directory and table on first use.
+function openQueue(app) {
+	if (db) {
+		return db;
+	}
+
+	const dataDir = app.getDataDirPath();
+
+	if (!fs.existsSync(dataDir)) {
+		fs.mkdirSync(dataDir, { recursive: true });
+	}
+
+	const dbPath = path.join(dataDir, "webhook-queue.sqlite");
+
+	db = new DatabaseSync(dbPath);
+
+	// Enable write-ahead logging and full synchronisation for durable queue writes.
+	db.exec(`
+    PRAGMA journal_mode = WAL;
+    PRAGMA synchronous = FULL;
+
+    CREATE TABLE IF NOT EXISTS queue (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      created_at TEXT NOT NULL,
+      payload TEXT NOT NULL
+    );
+  `);
+
+	app.debug(`Webhook queue opened at ${dbPath}`);
+
+	return db;
+}
+
+// Fail explicitly if a queue operation is attempted before opening the database.
+function ensureOpen() {
+	if (!db) {
+		throw new Error("Webhook queue has not been opened");
+	}
+}
+
+// Store a JSON payload with its enqueue time and return the new record's identity.
+function enqueue(payload) {
+	ensureOpen();
+
+	const statement = db.prepare(`
+    INSERT INTO queue (created_at, payload)
+    VALUES (?, ?)
+  `);
+
+	const createdAt = new Date().toISOString();
+	const payloadJson = JSON.stringify(payload);
+
+	const result = statement.run(createdAt, payloadJson);
+
+	return {
+		id: Number(result.lastInsertRowid),
+		createdAt,
+	};
+}
+
+// Read the earliest inserted entry without deleting it; return null for an empty queue.
+function peekOldest() {
+	ensureOpen();
+
+	const statement = db.prepare(`
+    SELECT id, created_at, payload
+    FROM queue
+    ORDER BY id ASC
+    LIMIT 1
+  `);
+
+	const row = statement.get();
+
+	if (!row) {
+		return null;
+	}
+
+	return {
+		id: Number(row.id),
+		createdAt: row.created_at,
+		payload: JSON.parse(row.payload),
+	};
+}
+
+// Delete a specific entry, normally after the caller confirms successful delivery.
+function remove(id) {
+	ensureOpen();
+
+	const statement = db.prepare(`
+    DELETE FROM queue
+    WHERE id = ?
+  `);
+
+	statement.run(id);
+}
+
+// Return the number of entries still waiting in the queue.
+function count() {
+	ensureOpen();
+
+	const statement = db.prepare(`
+    SELECT COUNT(*) AS total
+    FROM queue
+  `);
+
+	const row = statement.get();
+
+	return Number(row.total);
+}
+
+// Release the database connection; repeated calls are safe and the queue can reopen.
+function close() {
+	if (!db) {
+		return;
+	}
+
+	db.close();
+	db = null;
+}
+
+module.exports = {
+	openQueue,
+	enqueue,
+	peekOldest,
+	remove,
+	count,
+	close,
+};