Whitebox Plugin - Location¶
This is a plugin for whitebox that provides location utilities and extensions.
Installation¶
Simply install the plugin to whitebox:
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.