signalk-webhook-bridge 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to Webhook Bridge will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project uses [Semantic Versioning](https://semver.org/).
 
+## [2.0.1] - 2026-09-13
+
+### Changed
+
+- Webhook captures are now aligned to the server clock rather than being timed from when the plugin starts.
+- A 60-minute interval now captures on the hour.
+- A 30-minute interval captures at `:00` and `:30`.
+- A 15-minute interval captures at `:00`, `:15`, `:30` and `:45`.
+- The next capture time is recalculated after every snapshot to avoid gradual timer drift.
+- Updated configuration help text to explain clock-aligned scheduling.
+
+### Added
+
+- Automated tests for clock-aligned capture scheduling, including hourly, half-hourly, quarter-hourly, five-minute and day-boundary behaviour.
+
 ## [2.0.0] - 2026-09-13
 
 ### Added

package/README.md

@@ -6,6 +6,8 @@ Choose the Signal K data paths you want to send, assign simple field names, sele
 
 If the webhook is unavailable, data is stored locally in a persistent queue and automatically delivered in order when the connection returns.
 
+Captures are aligned to the Signal K server's local clock. For example, a 60-minute interval captures on the hour, while a 15-minute interval captures at :00, :15, :30 and :45.
+
 ## Features
 
 - Send selected Signal K data to any HTTP webhook

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "signalk-webhook-bridge",
-	"version": "2.0.0",
+	"version": "2.0.1",
 	"description": "Send selected Signal K data paths to an external webhook with unit conversion, persistent queueing and automatic retry.",
 	"main": "plugin/index.js",
 	"scripts": {
@@ -60,4 +60,4 @@
 		"webpack": "^5.110.3",
 		"webpack-cli": "^7.2.3"
 	}
-}
+}

package/plugin/index.js

@@ -3,7 +3,7 @@
  *
  * Signal K Webhook Bridge.
  *
- * Captures configured Signal K values at a selected interval,
+ * Captures configured Signal K values at clock-aligned intervals,
  * 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,
@@ -13,6 +13,7 @@
 const { getAvailablePaths } = require("./paths");
 const { convertValue, getOutputUnitLabel } = require("./units");
 const { sendWebhook } = require("./webhook");
+const { getNextAlignedCaptureTime } = require("./schedule");
 const storage = require("./storage");
 
 module.exports = function (app) {
@@ -124,6 +125,36 @@ module.exports = function (app) {
 		}
 	}
 
+	/**
+	 * Schedule one capture at the next clock boundary.
+	 *
+	 * A new timeout is calculated after every capture rather than using
+	 * setInterval(), preventing gradual timing drift.
+	 */
+	function scheduleNextCapture() {
+		if (stopped || !currentSettings) {
+			return;
+		}
+
+		const intervalMinutes = Number(currentSettings.sendFreq) || 10;
+
+		const nextCapture = getNextAlignedCaptureTime(intervalMinutes);
+
+		const delay = Math.max(0, nextCapture.getTime() - Date.now());
+
+		app.debug(
+			`Next webhook capture scheduled for ${nextCapture.toISOString()}`,
+		);
+
+		captureTimer = setTimeout(() => {
+			captureTimer = null;
+
+			captureSnapshot();
+
+			scheduleNextCapture();
+		}, delay);
+	}
+
 	/**
 	 * Deliver queued entries in strict FIFO order.
 	 *
@@ -187,7 +218,6 @@ module.exports = function (app) {
 					 * This preserves FIFO order and prevents newer entries
 					 * overtaking an entry that has not been delivered.
 					 */
-
 					lastError = error.message;
 					deliveryState = "waiting";
 
@@ -213,17 +243,22 @@ module.exports = function (app) {
 				}
 			}
 
-			
-			// Complete deferred cleanup after any in-flight request has settled.
+			/*
+			 * 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.
+	/**
+	 * Open storage, attempt backlog delivery and schedule the first
+	 * clock-aligned capture.
+	 */
 	plugin.start = function (settings) {
-		app.debug("Starting Signal K Webhook Bridge");
+		app.debug("Starting Webhook Bridge");
 
 		currentSettings = settings || {};
 		stopped = false;
@@ -248,34 +283,36 @@ module.exports = function (app) {
 		 * 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"
-			}`,
+			}, aligned to the clock`,
 		);
 
 		/*
 		 * 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.
+		 * We do NOT capture a new snapshot immediately. The first new
+		 * snapshot is taken at the next clock-aligned boundary.
 		 */
 		processQueue();
 
-		captureTimer = setInterval(captureSnapshot, intervalMilliseconds);
+		scheduleNextCapture();
 	};
 
-	// Stop future captures; an in-flight delivery finishes before its worker closes storage.
+	/**
+	 * Stop future captures; an in-flight delivery finishes before its
+	 * worker closes storage.
+	 */
 	plugin.stop = function () {
-		app.debug("Stopping Signal K Webhook Bridge");
+		app.debug("Stopping Webhook Bridge");
 
 		stopped = true;
 
 		if (captureTimer) {
-			clearInterval(captureTimer);
+			clearTimeout(captureTimer);
 			captureTimer = null;
 		}
 
@@ -325,6 +362,7 @@ module.exports = function (app) {
 				});
 			}
 		});
+
 		router.get("/status", (req, res) => {
 			try {
 				const queueCount = storage.count();
@@ -371,8 +409,11 @@ module.exports = function (app) {
 	};
 
 	/**
-	 * 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.
+	 * 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);
@@ -405,7 +446,7 @@ module.exports = function (app) {
 					type: "number",
 					title: "Send Interval",
 					description:
-						"How often data should be captured and sent, in minutes.",
+						"Capture interval in minutes, aligned to the server clock. For example, 60 sends on the hour and 15 sends at :00, :15, :30 and :45.",
 					default: 10,
 					minimum: 1,
 				},

package/plugin/schedule.js

@@ -0,0 +1,21 @@
+function getNextAlignedCaptureTime(intervalMinutes, now = new Date()) {
+	const interval = Number(intervalMinutes);
+
+	if (!Number.isFinite(interval) || interval <= 0) {
+		throw new Error("Capture interval must be greater than zero");
+	}
+
+	const startOfDay = new Date(now);
+	startOfDay.setHours(0, 0, 0, 0);
+
+	const intervalMs = interval * 60 * 1000;
+	const elapsedToday = now.getTime() - startOfDay.getTime();
+
+	const nextElapsed = Math.floor(elapsedToday / intervalMs + 1) * intervalMs;
+
+	return new Date(startOfDay.getTime() + nextElapsed);
+}
+
+module.exports = {
+	getNextAlignedCaptureTime,
+};