Whitebox Plugin - Location

This is a plugin for whitebox that provides location utilities and extensions.

Installation

Simply install the plugin to whitebox:

poetry add whitebox-plugin-location

Observed location

The location.data store exposes lastObservedLocation, one usable socket observation seen by this page. It is page-lived, not persisted history or proof of current GPS freshness. Loading or clearing flight history neither seeds nor clears it. Consumers still apply their acquisition/status and playback rules; the map does not require this provider just to mount.

See state stores for access and offline preparation for shared setup.

Flight history hydration contract

History/latest HTTP rows and newly produced observation.location.update payloads carry the persisted sample's id as a decimal string, including above JavaScript's safe integer range. This is not the socket event's eid. Coordinates or timestamps are not identity: distinct samples at the same place/time must survive. Location timestamps use UTC ISO with six fractional digits; history orders by timestamp, then sample ID for exact ties. The handler stamps time before awaiting persistence, so commit order can differ from sample order: HTTP may include later B while earlier A is still uncommitted. Appending unmatched live points would put A after B.

fetchLocationDataForFlightSession(flightSession, mode = "flight") merges HTTP rows with arrivals during that request; HTTP wins duplicate string IDs. Live insertions and same-flight/same-mode pending refetches use the same reconciliation. Only pending arrivals inherit, not a previously settled snapshot. Another flight, another mode or clear() invalidates the pending record. Failing/non-array HTTP leaves visible arrivals intact. Ownership retires before publication, so synchronous subscribers can start newer work without old cleanup erasing it. Publication errors propagate rather than clearing history as an HTTP failure.

addPosition(point, owner) accepts an optional { sessionId, mode } owner (string session ID); the service supplies it and preserves sample metadata. An explicit owner mismatch cannot enter another history. Without an owner it appends to the current history, preserving the existing one-argument API. No active history owner also permits ordinary append. clear() clears history, not the last observation.

Legacy missing/invalid/numeric IDs remain separate occurrences; there is no old-event backfill or exactly-once promise. Legacy valid timestamps have native-Date millisecond ordering; unusable/out-of-four-digit-year times follow timed points in source order. Corrected timestamps retain microsecond ordering, but playback still uses its existing millisecond clock. The socket's coordinate-only throttle is unchanged and may suppress stationary samples. Reconciliation covers received observations, not every persisted row or proof of their selected-flight membership.

Additional Instructions

• Plugin Development Guide
• Plugin Testing Guide
• Contributing Guidelines