mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
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.
203 lines
7.1 KiB
JavaScript
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,
|
|
};
|
|
}
|