@signalk/tracks-plugin 3.0.1 → 3.0.3

package/docs/history-and-storage.md

@@ -12,15 +12,68 @@ Neither is simply better than the other, which is why both are used.
 | Size                         | small                              | far larger, which is why retention exists        |
 
 The plugin writes its positions to a SQLite file in its data directory, so they
-survive a restart. How long they are kept depends on two settings: the own
-vessel's track is kept indefinitely by default, and another vessel is dropped
-30 days after its last fix.
+survive a restart. A power cut can still lose the most recent ones, because
+they are not forced onto the storage one at a time (on an SD card each such
+write can take seconds), but it cannot damage the file. How long they are kept
+depends on two settings: the own vessel's track is kept indefinitely by
+default, and another vessel is dropped 30 days after its last fix.
 
 So the provider is the finer record of the recent past, and the plugin's store
 is what remains of everything older. The interval and the retention are both
 settings on the plugin's configuration page, which is where their current
 defaults are shown.
 
+## Storage responsiveness and shutdown
+
+SQLite runs in a dedicated worker, including opening the database, queries,
+pruning and WAL checkpointing. A slow storage operation therefore does not block
+the Signal K server's event loop. This does not make slow storage faster: a track
+query can still wait behind earlier writes, while unrelated server requests can
+continue. Large query results still arrive via structured cloning, and their
+materialization and HTTP serialization take main-thread time, so the worker
+does not remove every source of server latency.
+
+Positions retain their arrival timestamp (or the supplied observation timestamp)
+and coordinates are copied when accepted. Operations are ordered, with one batch
+in flight; the entire adjacent waiting mutation run commits in one transaction,
+bounded by the same queue byte/item limits. Positions
+inside a context's resolution window are discarded before cloning/admission;
+the worker also retains the store's throttle as a consistency guard. There is no
+extra batching delay or change to the configured recording resolution, spatial
+filters or schema. SQLite uses WAL with `synchronous=NORMAL`, so a commit does
+not sync; the only syncs are the checkpoints, which run in the worker too.
+Persisted vessel names are cached from
+worker-acknowledged writes; the live data model still takes precedence.
+
+Pending operations are bounded to 10,000 items / 8 MiB of serialized arguments,
+including the batch in flight. If recording exceeds either limit, a plugin error
+pauses further recording while accepted work drains. Recording automatically
+resumes once both item and byte usage reach at most half capacity. The plugin
+logs the gap's start time and dropped operation count (operations include names
+and maintenance, not just positions). Dropped samples are not replayed.
+
+A failed write transaction stops subsequent writes until a plugin restart;
+uncertain writes are never retried. A successful rollback leaves the database
+open, so History and v1 queries can still read committed tracks, including when
+storage is full. Startup, worker exit or an uncertain rollback fail the whole
+store. These errors remain visible instead of being replaced by healthy status.
+
+Stopping unsubscribes input immediately, then returns a Promise that resolves
+only after accepted work drains, SQLite closes and the worker exits. Plugin
+lifecycle callers must await `stop()` before restarting or removing its data
+directory. `start()` returns the initialization Promise; track requests submitted
+during initialization wait behind it. This drain covers callers that actually
+invoke and await `stop()`, such as a settings change or disabling the plugin.
+The current server shutdown path does not guarantee that: a server restart can
+lose accepted queued samples even on an otherwise orderly process shutdown.
+Do not assume the plugin's async stop promise is awaited by the server.
+
+Accepted but uncommitted data is still in RAM. Abrupt power loss or forced process
+termination can lose pending samples; worker isolation does not promise zero data
+loss. Committed records are not synced one by one either, so a power cut can
+also lose the most recent of them, though never damage the file. Rollback of plugin code
+must never replace the database with an older copy over newly recorded tracks.
+
 ## What you get with no history provider
 
 Everything comes from the plugin's own store, at whatever interval it is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalk/tracks-plugin",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "description": "Plugin to keep track of tracks of vessels",
   "type": "module",
   "exports": {