Files
gods-eye-view/src/sources/live/vessels.js
T
Sameh Khamis cbbf55cacd feat(vessels): key vessels by their source's stable id, and share a selected vessel
AIS Vessels are keyed by the id their live source gives, with the MMSI as an
attribute: an MMSI can be shared, spoofed or reused, so two vessels with one
MMSI are now two vessels. Looking a vessel up or selecting it by MMSI still
finds it.

A share link made while a vessel is selected opens that vessel. A UUID vessel
id travels as 16 bytes in a new thing field (13). A shared thing that is not
reporting now says so in a sentence per kind, with its id (ICAO, NORAD, MMSI
or vessel UUID) on a second line.
2026-11-10 18:12:53 -08:00

134 lines
4.4 KiB
JavaScript

import { coordinates, epoch, finite, LiveSourceError } from './contract.js';
/** An MMSI is up to ten digits (AIS carries it in 30 bits); anything else a
* row names it is not one. */
const MMSI_PATTERN = /^\d{1,10}$/;
/** The row's MMSI when it carries one that looks like an MMSI, else ''. */
function vesselMmsi(row) {
const text = String(row?.mmsi ?? '').trim();
return MMSI_PATTERN.test(text) ? text : '';
}
/** A row's stable id when its source names none: its MMSI or identifier. */
function defaultVesselId(row) {
return String(row?.mmsi || row?.input_identifier || '');
}
/**
* AIS positions are sea-surface observations; heading and course are distinct.
* `id` is the vessel's key; an MMSI is not one (vessels share numbers and a
* number can move to another hull), so `mmsi` is an attribute, '' when the
* row has none. A row with no id of its own is keyed by its MMSI.
*/
export function normalizeVesselObservation(row, reference = null, id = null) {
const key = String(id ?? defaultVesselId(row)).trim();
const latitude = finite(row?.lat),
longitude = finite(row?.lon);
if (!key || !coordinates(latitude, longitude)) return null;
const mmsi = vesselMmsi(row);
const speedKts = finite(row.speed);
return {
id: key,
mmsi,
reference: reference ?? key,
latitude,
longitude,
// A source's own id is not a name: a vessel with none is unnamed.
name: String(row.name || row.input_name || mmsi || defaultVesselId(row)),
imo: String(row.imo || ''),
type: String(row.type_specific || row.type || ''),
destination: String(row.destination || ''),
speedMps: speedKts == null ? null : speedKts * 0.514444,
courseDeg: finite(row.course),
headingDeg: finite(row.heading),
observedAtMs:
epoch(row.last_position_epoch, 1000) ??
epoch(Date.parse(row.last_position_UTC)),
altitudeDatum: 'sea-surface',
};
}
/**
* A vessel snapshot from a `{ rows }` payload. `idFor(row)` gives a row's
* stable id (its MMSI or identifier by default); rows are deduped by that id,
* so two vessels sharing an MMSI stay two vessels. A source whose rows carry
* an id of their own passes it, such as `idFor: (row) => row.uuid || row.mmsi`.
* `referenceFor(row)` gives the reference its track is asked for by; the id
* by default.
*/
export function vesselSnapshot(
payload,
{
source = 'AISStream',
coverage = 'received AIS positions',
idFor = defaultVesselId,
referenceFor = null,
} = {},
) {
if (!Array.isArray(payload?.rows))
throw new LiveSourceError('malformed', 'Malformed vessel response');
const rows = payload.rows;
const records = [],
ids = new Set();
for (const row of rows) {
const record = normalizeVesselObservation(
row,
null,
row && typeof row === 'object' ? idFor(row) : null,
);
// A row's track is asked for by its id unless the source says otherwise.
if (record && referenceFor) record.reference = referenceFor(row);
if (record && !ids.has(record.id)) {
records.push(record);
ids.add(record.id);
}
}
const observedAtMs =
epoch(payload?.newestPositionAt) ??
epoch(Date.parse(payload?.newestPositionAt)) ??
records.reduce(
(newest, row) => Math.max(newest || 0, row.observedAtMs || 0) || null,
null,
);
return {
records,
source,
coverage,
complete: records.length === rows.length && !payload?.refreshing,
rejectedCount: rows.length - records.length,
observedAtMs,
freshness: payload?.refreshing
? 'stale'
: observedAtMs == null
? 'unknown'
: 'current',
stale: Boolean(payload?.refreshing),
// Connection state is distinct from receipt of a usable position.
transportStatus:
typeof payload?.status === 'string' ? payload.status : null,
lastMessageAt: payload?.lastMessageAt ?? null,
nextAttemptAt: finite(payload?.nextAttemptAt),
silentForMs: finite(payload?.silentForMs),
reconnectAttempt: finite(payload?.reconnectAttempt),
rawRowCount: rows.length,
};
}
export function normalizeVesselTrack(samples) {
if (!Array.isArray(samples)) return [];
return samples.flatMap((sample) => {
const latitude = finite(sample?.lat),
longitude = finite(sample?.lon);
if (!coordinates(latitude, longitude)) return [];
return [
{
latitude,
longitude,
observedAtMs: epoch(sample?.t, 1000),
altitudeDatum: 'sea-surface',
},
];
});
}