Files
gods-eye-view/src/sources/live/contract.js
T
Sameh Khamis 2b5fb51684 Contacts move back as smoothly as they move on
A snapshot timeline may declare spanMs: each record of a snapshot at a
time then carries its own fixes from spanMs before the time to spanMs
after it. Flights, military flights and vessels following the clock are
placed on those fixes, so a seek or a move back within the fixes loaded
is no jump: nothing is cleared and play does not wait. The step there is
asked for once and stands in for every contact; those it has keep their
place. Fixes are merged across snapshots at least 20 s apart, at most
240 a contact, and a contact is not drawn more than a minute before its
first fix.
2026-11-15 09:27:31 -08:00

203 lines
7.1 KiB
JavaScript

/**
* Browser live-source contract. Coordinates are WGS84 degrees; lengths and
* velocities are metres and metres/second; times are Unix milliseconds.
* Barometric altitude and ellipsoid altitude are separate, nullable observations.
* A missing timestamp is unknown, never the time the response was received.
*
* Sources expose getSnapshot(query, { signal }) and optionally
* getTrack(reference, { signal }). References are opaque to consumers.
* Snapshots describe coverage and completeness independently of freshness.
* Records contain observation data only, with no scene objects or transport data.
* Every record has a stable `id` (a non-empty string) that keys it across
* snapshots. A vessel record's `id` is whatever its source gives, such as a
* provider id; its `mmsi` is an optional attribute ('' or absent when
* unknown), never its key, since vessels can share an MMSI. A source that
* only has MMSIs uses the MMSI as the id. A vessel record's `virtual` is true
* for a virtual aid to navigation, a mark broadcast where nothing physical
* stands (AIS message 21's virtual flag), else false; any source may set it.
*
* A source may also declare a timeline (see readSnapshotTimeline): it can
* answer a snapshot at a given time, so the layer follows the world clock.
* The query then carries `atMs` (absent while the clock is live, so a live
* request is unchanged), and the snapshot is the world as it stood at that
* time: `observedAtMs` <= `atMs`, no record observed later than `atMs`,
* freshness and staleness judged against `atMs`, and `atMs` echoed back. A
* vessel snapshot at a time reports `transportStatus: 'live'`. getTrack then
* receives `{ signal, atMs }` and returns only points at or before `atMs`.
*
* A timeline that declares `spanMs` lets each record of a snapshot at a time
* carry `fixes`: `{atMs, lat, lon, altitudeM?}` in time order, its own track
* from `spanMs` before the time to `spanMs` after it (see
* src/time/timelineFixes.js). The layer places the contact on them at any
* time they span, earlier ones too, so the clock can move within them,
* forwards or back, without a new snapshot.
*/
// Messages are English data (AI tools read them too); the Layers panel shows
// them translated by their shape (translateFeedError in src/ui/statusText.js),
// so a new or reworded message is changed there as well.
export class LiveSourceError extends Error {
constructor(
code,
message,
{ status = null, retryAfterMs = 20000, source = null } = {},
) {
super(message);
this.name = 'LiveSourceError';
this.code = code;
this.status = status;
this.retryAfterMs = retryAfterMs;
this.source = source;
}
}
export function finite(value) {
if (value == null || value === '' || typeof value === 'boolean') return null;
const number = Number(value);
return Number.isFinite(number) ? number : null;
}
export function epoch(value, scale = 1) {
const number = finite(value);
const milliseconds = number == null ? null : number * scale;
return milliseconds != null &&
milliseconds > 0 &&
milliseconds <= 8640000000000000
? milliseconds
: null;
}
export function cleanText(value) {
return typeof value === 'string' ? value.trim() : '';
}
export function coordinates(latitude, longitude) {
return (
Number.isFinite(latitude) &&
Math.abs(latitude) <= 90 &&
Number.isFinite(longitude) &&
Math.abs(longitude) <= 180
);
}
/**
* Admit a snapshot atomically; an all-invalid nonempty feed is unavailable.
* `unpositionedId(row)` names a rejected row that is a valid contact without
* a position: it is returned in `retainIds` and does not make the snapshot
* incomplete.
*/
export function admitRecords(rows, normalize, label, unpositionedId) {
if (!Array.isArray(rows))
throw new LiveSourceError('malformed', `Malformed ${label} response`);
const records = [];
const ids = new Set();
const retainIds = new Set();
let unpositioned = 0;
for (const row of rows) {
const record = normalize(row);
if (record && !ids.has(record.id)) {
records.push(record);
ids.add(record.id);
} else if (!record) {
const id = unpositionedId?.(row);
if (id) {
retainIds.add(id);
unpositioned += 1;
}
}
}
if (rows.length && !records.length) {
throw new LiveSourceError('malformed', `Malformed ${label} aircraft rows`);
}
return {
records,
retainIds,
complete: records.length + unpositioned === rows.length,
rejectedCount: rows.length - records.length,
};
}
/** Cancellation is checked after body parsing even when a transport ignores it. */
export async function readResponse(
fetchImpl,
url,
{ signal, ...init } = {},
source = 'Live source',
) {
signal?.throwIfAborted();
let response;
try {
response = await fetchImpl(url, { ...init, signal });
signal?.throwIfAborted();
} catch (error) {
signal?.throwIfAborted();
if (error?.name === 'AbortError') throw error;
throw new LiveSourceError('unavailable', `${source} network error`, {
source,
});
}
let payload = null;
try {
payload = await response.json();
} catch {
/* classified below */
}
signal?.throwIfAborted();
return { response, payload };
}
export function httpError(response, source) {
const status = response.status;
const code =
status === 429
? 'limited'
: status === 401 || status === 403
? 'denied'
: 'unavailable';
return new LiveSourceError(
code,
status === 429 ? `${source} rate limited` : `${source} HTTP ${status}`,
{
status,
source,
retryAfterMs: code === 'limited' || code === 'denied' ? 45000 : 20000,
},
);
}
/**
* The timeline a source declares, or null when it has none or it is
* malformed: `{ coverage(), stepMs, subscribe? }`. `coverage()` returns the
* span `{start, end}` (epoch ms) the source can answer a snapshot for, or
* null while it does not know yet; `stepMs` is the spacing of its snapshots;
* the optional `subscribe(listener)` tells of a change in coverage, or of a
* better answer for a time already answered (a paused layer then loads the
* time shown again), and returns the unsubscribe. The optional `spanMs` is
* how far either side of its time a snapshot's records carry their `fixes`
* (0 when they carry none).
* @param {object|null|undefined} source
* @returns {{coverage: () => ({start: number, end: number}|null),
* stepMs: number, spanMs: number,
* subscribe: ((listener: () => void) => () => void)|null}|null}
*/
export function readSnapshotTimeline(source) {
const timeline = source?.timeline;
if (!timeline || typeof timeline !== 'object') return null;
if (typeof timeline.coverage !== 'function') return null;
const stepMs = timeline.stepMs;
if (!Number.isFinite(stepMs) || stepMs <= 0) return null;
if (timeline.subscribe != null && typeof timeline.subscribe !== 'function')
return null;
const spanMs =
Number.isFinite(timeline.spanMs) && timeline.spanMs > 0
? timeline.spanMs
: 0;
return {
coverage: () => timeline.coverage(),
stepMs,
spanMs,
subscribe: timeline.subscribe
? (listener) => timeline.subscribe(listener)
: null,
};
}