Files
gods-eye-view/src/layers/rail/schedules.js
T
Sameh Khamis 283890cee0 fix(rail): trip-update delays are as old as the server's read
The browser stamped every trip-updates answer as just read. While an
operator's feed fails, the rail proxy replays its last good copy for up to
ten minutes, and a cached copy can be a TTL old, so those delays never
reached RAIL_UPDATES_MAX_AGE_MS and a selected train's card showed them as
current. Delays now take their age from the snapshot's fetchedAt (capped
at now), as positions do in ingestion.js, so they stop applying 75 s after
the server last read the operator.
2026-11-11 14:57:02 -08:00

527 lines
18 KiB
JavaScript

/**
* @module layers/rail/schedules
* @description The Rail layer's schedule tier: each feed's optional schedule
* pack (src/data/railSchedule.js) and live trip-update delays, read for the
* selected live train's stops, headsign and delays (the stops provider,
* `stopsFor`). It never places or moves a train: every train drawn is where
* its operator last reported it.
*
* A schedule pack is fetched the first time a train on that feed is
* selected, and kept until the feed has been out of use for a while
* (`forget`). Trip updates are polled every RAIL_UPDATES_POLL_MS while a
* train on the feed is selected. A feed that publishes none (Irish Rail, SJ
* Nord) may state each train's delay in its report (`delaySec`): that delay
* then moves the train's timetable, for its stops and for finding its run.
*
* No Cesium, no DOM. Network access goes through the injected source and
* timers through injected functions, so node:test drives it.
*/
import {
activeTrips,
createSchedule,
liveDelaySec,
scheduledPosition,
tripStops,
} from '../../data/railSchedule.js';
import { pointAtS } from '../../data/railPaths.js';
/** Trip updates are re-read this often while needed (ms). */
export const RAIL_UPDATES_POLL_MS = 30_000;
/** Delays older than this are not applied: a stopped poll must not lie (ms). */
export const RAIL_UPDATES_MAX_AGE_MS = 2 * RAIL_UPDATES_POLL_MS + 15_000;
/**
* A schedule pack that failed (other than a 404) is tried again after
* SCHEDULE_RETRY_FIRST_MS, then twice as long after each failure in a row,
* up to SCHEDULE_RETRY_MS (ms): one bad answer from the server does not
* leave a selected train without its stops for ten minutes.
*/
export const SCHEDULE_RETRY_FIRST_MS = 30_000;
export const SCHEDULE_RETRY_MS = 10 * 60_000;
/**
* A live train without a known trip id may be matched to a run from this
* long before its departure (waiting at the origin)...
*/
export const MATCH_BEFORE_MS = 5 * 60_000;
/** ...to this long after its arrival, at the terminus. */
export const MATCH_AFTER_MS = 2 * 60_000;
/** A live train without a known trip id matches a run this close (m). */
export const MATCH_NEAREST_MAX_M = 3_000;
/** How long a nearest-run match is kept before it is looked for again (ms). */
export const MATCH_KEEP_MS = 60_000;
/**
* How long a schedule pack waits after its nth failure in a row (ms).
* @param {number} failures 1 after the first.
* @returns {number}
*/
export function scheduleRetryDelayMs(failures) {
return Math.min(
SCHEDULE_RETRY_MS,
SCHEDULE_RETRY_FIRST_MS * 2 ** Math.max(0, failures - 1),
);
}
const M_PER_DEG = 111_320;
/** Ground distance in metres, equirectangular: fine at a few kilometres. */
function distanceM(lat1, lon1, lat2, lon2) {
const kx = M_PER_DEG * Math.cos((((lat1 + lat2) / 2) * Math.PI) / 180);
const dLon = ((((lon2 - lon1 + 180) % 360) + 360) % 360) - 180;
return Math.hypot(dLon * kx, (lat2 - lat1) * M_PER_DEG);
}
/**
* GTFS-RT trip records (the `/api/rail/updates` body) as the `delays` map
* railSchedule reads, keyed by trip id.
* @param {{trips?: object[]}|null} body
* @returns {Record<string, object>}
*/
export function delaysFromUpdates(body) {
const delays = {};
for (const trip of Array.isArray(body?.trips) ? body.trips : []) {
if (typeof trip?.tripId !== 'string' || !trip.tripId) continue;
delays[trip.tripId] = {
delaySec: Number.isFinite(trip.delaySec) ? trip.delaySec : null,
startDate: trip.startDate ?? null,
relationship: trip.relationship ?? null,
stops: Array.isArray(trip.stops) ? trip.stops : [],
};
}
return delays;
}
/**
* Whether a timetable's shape indices point into this path pack: the two
* come from one build. A path pack rebuilt on its own (or a schedule left
* from an older build) has other shapes at those indices, so its runs are
* compared between their stops instead of along some other line. Packs that
* predate the stamps are taken as a pair.
* @param {{pathsBuiltAt?: string|null}} schedule
* @param {{builtAt?: string|null}|null} pack
* @returns {boolean}
*/
export function pathsMatch(schedule, pack) {
if (!pack) return false;
if (!schedule?.pathsBuiltAt || !pack.builtAt) return true;
return schedule.pathsBuiltAt === pack.builtAt;
}
/**
* Where the timetable has one run now: on its shape when the path pack has
* it, else between its stops. Only compared with a live train's report, to
* find the run it is on (stopsFor); never drawn.
* @param {object} schedule From createSchedule.
* @param {object|string} run A run from activeTrips, or a trip id.
* @param {number} nowMs
* @param {object|null} delays
* @param {object|null} pack A path pack (createRailPathPack), when loaded.
* @returns {object|null} scheduledPosition's result plus `lat`, `lon`,
* `bearingDeg` (NaN when unknown) and `onShape`.
*/
export function scheduledRunPoint(schedule, run, nowMs, delays, pack) {
const position = scheduledPosition(schedule, run, nowMs, delays);
if (!position) return null;
const path =
position.shape !== null && pathsMatch(schedule, pack)
? pack.pathAt(position.shape)
: null;
const point = path ? pointAtS(path, position.s) : null;
if (point && Number.isFinite(point.lat) && Number.isFinite(point.lon))
return { ...position, ...point, onShape: true };
if (Number.isFinite(position.lat) && Number.isFinite(position.lon))
return { ...position, bearingDeg: NaN, onShape: false };
// A shaped pattern whose path pack is not here (yet): between the stops.
const trip = schedule.trips.get(position.tripId);
if (!trip) return null;
const stopAt = (k) => (k >= 0 ? schedule.stops[trip.pattern.stops[k]] : null);
const a = stopAt(
position.prevStop >= 0 ? position.prevStop : position.nextStop,
);
const b =
position.dwell || position.nextStop < 0 ? a : stopAt(position.nextStop);
if (!a || !b) return null;
const f = position.dwell ? 0 : position.fraction;
return {
...position,
lat: a.lat + (b.lat - a.lat) * f,
lon: a.lon + (b.lon - a.lon) * f,
bearingDeg: NaN,
onShape: false,
};
}
/**
* The schedule tier for one layer instance.
* @param {{source: object,
* hasTripUpdates: (feedId: string) => boolean,
* pathPackFor?: (feedId: string) => object|null,
* now?: () => number,
* setInterval?: Function, clearInterval?: Function,
* onChange?: (feedId: string) => void}} options
* @returns {object}
*/
export function createRailSchedules({
source,
hasTripUpdates,
pathPackFor = () => null,
now = () => Date.now(),
setInterval: startInterval = (fn, ms) => globalThis.setInterval(fn, ms),
clearInterval: stopInterval = (id) => globalThis.clearInterval(id),
onChange = () => {},
}) {
/**
* feedId → `{status: 'loading'|'ready'|'none', schedule, retryAt, promise,
* failures}`; `failures` counts failed loads in a row.
*/
const schedules = new Map();
/** feedId → `{delays, at, timer, reasons: Set, controller}`. */
const updates = new Map();
/** `${feedId}\n${trainId}` → `{tripKey, run, via, at}` for live trains. */
const matches = new Map();
let selectedFeed = null;
/**
* The feed's schedule, loading it on first ask.
* @param {string} feedId
* @returns {Promise<object|null>} The schedule, or null when it has none.
*/
function loadSchedule(feedId) {
const known = schedules.get(feedId);
if (known?.status === 'ready') return Promise.resolve(known.schedule);
if (known?.status === 'loading') return known.promise;
if (known?.status === 'none' && now() < known.retryAt)
return Promise.resolve(null);
if (typeof source?.requestSchedule !== 'function') {
schedules.set(feedId, {
status: 'none',
schedule: null,
retryAt: Infinity,
});
return Promise.resolve(null);
}
const slot = {
status: 'loading',
schedule: null,
retryAt: Infinity,
failures: known?.failures ?? 0,
};
slot.promise = (async () => {
try {
const response = await source.requestSchedule(feedId);
if (!response.ok) {
const error = new Error(`rail schedule HTTP ${response.status}`);
error.status = response.status;
throw error;
}
const raw = await response.json();
let schedule;
try {
schedule = createSchedule(raw);
if (schedule.feedId !== feedId)
throw new TypeError('rail schedule pack is for another feed');
} catch (error) {
error.permanent = true;
throw error;
}
slot.schedule = schedule;
slot.status = 'ready';
slot.failures = 0;
onChange(feedId);
return schedule;
} catch (error) {
slot.status = 'none';
slot.failures += 1;
// A 404 is "no timetable for this feed", not a fault to retry; a
// malformed pack will not mend itself before the next build either.
slot.retryAt =
error?.status === 404 || error?.permanent === true
? Infinity
: now() + scheduleRetryDelayMs(slot.failures);
if (error?.status !== 404)
console.warn(
`[Data:Rail] ${feedId} timetable unavailable:`,
error?.message || error,
);
return null;
} finally {
slot.promise = null;
}
})();
schedules.set(feedId, slot);
return slot.promise;
}
/** The feed's schedule if loaded; starts the load otherwise. */
function scheduleFor(feedId) {
const known = schedules.get(feedId);
if (known?.status === 'ready') return known.schedule;
void loadSchedule(feedId);
return null;
}
function updatesSlot(feedId) {
let slot = updates.get(feedId);
if (!slot) {
slot = {
delays: null,
at: -Infinity,
timer: null,
reasons: new Set(),
controller: null,
};
updates.set(feedId, slot);
}
return slot;
}
async function fetchUpdates(feedId) {
const slot = updatesSlot(feedId);
if (slot.controller || typeof source?.requestUpdates !== 'function') return;
const controller = new AbortController();
slot.controller = controller;
try {
const response = await source.requestUpdates(feedId, {
signal: controller.signal,
});
if (!response.ok) throw new Error(`rail updates HTTP ${response.status}`);
const body = await response.json();
if (slot.controller !== controller) return;
// Delays are as old as the server's read of the operator (`fetchedAt`),
// not this answer: a cached copy, or the last good one replayed while
// the operator fails, stops applying RAIL_UPDATES_MAX_AGE_MS after it,
// as positions do (ingestion.js applySnapshot).
const at = now();
slot.delays = delaysFromUpdates(body);
slot.at = Math.min(
Number.isFinite(body?.fetchedAt) ? body.fetchedAt : at,
at,
);
onChange(feedId);
} catch (error) {
if (error?.name !== 'AbortError')
console.warn(
`[Data:Rail] ${feedId} trip updates unavailable:`,
error?.message || error,
);
} finally {
if (slot.controller === controller) slot.controller = null;
}
}
/**
* Poll a feed's trip updates while `reason` needs them. Reasons are
* counted, so every reader shares one poll.
* @param {string} feedId
* @param {string} reason
*/
function watchUpdates(feedId, reason) {
if (!hasTripUpdates(feedId)) return;
const slot = updatesSlot(feedId);
slot.reasons.add(reason);
if (slot.timer !== null) return;
void fetchUpdates(feedId);
slot.timer = startInterval(
() => void fetchUpdates(feedId),
RAIL_UPDATES_POLL_MS,
);
}
function unwatchUpdates(feedId, reason) {
const slot = updates.get(feedId);
if (!slot) return;
slot.reasons.delete(reason);
if (slot.reasons.size || slot.timer === null) return;
stopInterval(slot.timer);
slot.timer = null;
slot.controller?.abort();
slot.controller = null;
}
/** Current delays for a feed, or null when none are fresh. */
function delaysFor(feedId) {
const slot = updates.get(feedId);
return slot?.delays && now() - slot.at <= RAIL_UPDATES_MAX_AGE_MS
? slot.delays
: null;
}
/**
* The run a live train is on. Its trip id when the timetable has it (live
* GTFS trip ids are normally the static ones); otherwise, as a fallback,
* the running run of its route nearest the train's report, kept for a
* minute so the stop list does not hop between neighbouring runs. A train
* its own report says is `liveDelayMs` late is compared with where the
* timetable had each run that long ago.
*/
function matchRun(schedule, train, nowMs, delays, liveDelayMs = 0) {
const tripId = train.tripId || null;
if (tripId && schedule.runsByTrip.has(tripId))
return { trip: tripId, via: 'trip' };
const record = train.record || {};
if (!Number.isFinite(record.lat) || !Number.isFinite(record.lon))
return null;
const key = `${train.feedId}\n${record.id ?? ''}`;
const tripKey = `${tripId ?? ''}\n${train.routeId ?? ''}`;
const kept = matches.get(key);
if (kept && kept.tripKey === tripKey && nowMs - kept.at < MATCH_KEEP_MS)
return kept.run ? { trip: kept.run, via: 'nearest' } : null;
const pack = pathPackFor(train.feedId);
// A uniform delay is a time shift: the run as timetabled that long ago.
const matchMs = nowMs - liveDelayMs;
let best = null;
let bestM = MATCH_NEAREST_MAX_M;
for (const run of activeTrips(schedule, matchMs, {
delays,
beforeMs: MATCH_BEFORE_MS,
afterMs: MATCH_AFTER_MS,
})) {
if (train.routeId && run.routeId !== train.routeId) continue;
const point = scheduledRunPoint(schedule, run, matchMs, delays, pack);
if (!point) continue;
const m = distanceM(record.lat, record.lon, point.lat, point.lon);
if (m < bestM) {
bestM = m;
best = run;
}
}
matches.set(key, { tripKey, run: best, at: nowMs });
return best ? { trip: best, via: 'nearest' } : null;
}
/**
* The stops provider (see createRailLayer): the selected train's stops and
* headsign, or null until the feed's timetable has loaded (or when it has
* none, or the train matches no run).
* @param {{feedId: string, tripId: string|null, routeId: string|null,
* record: object}} train
* @param {number} nowMs
* @returns {{stops: object[], headsign: string|null,
* match: 'trip'|'nearest'}|null}
*/
function stopsFor(train, nowMs) {
if (!train?.feedId) return null;
const schedule = scheduleFor(train.feedId);
if (!schedule) return null;
// A feed without trip updates: the delay the train's report states.
const liveDelay = hasTripUpdates(train.feedId)
? null
: liveDelaySec(train.record);
const updates = liveDelay === null ? delaysFor(train.feedId) : null;
const match = matchRun(
schedule,
train,
nowMs,
updates,
(liveDelay ?? 0) * 1000,
);
if (!match) return null;
const tripId =
typeof match.trip === 'string' ? match.trip : match.trip.tripId;
const delays =
liveDelay === null
? updates
: {
[tripId]: {
delaySec: liveDelay,
startDate:
typeof match.trip === 'string' ? null : match.trip.serviceDate,
},
};
const stops = tripStops(schedule, match.trip, nowMs, delays);
if (!stops.length) return null;
const trip = schedule.trips.get(tripId);
return {
stops,
headsign: trip?.headsign || null,
match: match.via,
};
}
/**
* A train was selected (or the selection cleared): poll its delays once
* its feed's timetable is loaded. Delays are shown only at the
* timetable's stops, so a feed without one is not polled.
*/
function onSelect(train) {
const feedId = train?.feedId || null;
if (feedId === selectedFeed) return;
if (selectedFeed) unwatchUpdates(selectedFeed, 'selection');
selectedFeed = feedId;
if (!feedId) return;
void loadSchedule(feedId).then((schedule) => {
if (schedule && selectedFeed === feedId)
watchUpdates(feedId, 'selection');
});
}
/** Stop every poll; loaded schedules stay for the next enable. */
function stop() {
onSelect(null);
for (const [feedId, slot] of updates)
for (const reason of [...slot.reasons]) unwatchUpdates(feedId, reason);
matches.clear();
}
/**
* Release what is held for a feed no longer in use: its parsed schedule,
* its last trip updates and its live-train matches. A load or a poll
* still under way is left to finish; the feed loads again when next used.
* @param {string} feedId
*/
function forget(feedId) {
if (schedules.get(feedId)?.status !== 'loading') schedules.delete(feedId);
const slot = updates.get(feedId);
if (slot && slot.reasons.size === 0 && slot.timer === null) {
slot.controller?.abort();
updates.delete(feedId);
}
const prefix = `${feedId}
`;
for (const key of [...matches.keys()])
if (key.startsWith(prefix)) matches.delete(key);
}
/** Counts for QA probes and tests. */
function stats() {
return {
schedules: Object.fromEntries(
[...schedules].map(([feedId, slot]) => [
feedId,
slot.status === 'ready'
? {
status: 'ready',
trips: slot.schedule.trips.size,
runs: slot.schedule.instances.length,
}
: { status: slot.status },
]),
),
updates: Object.fromEntries(
[...updates].map(([feedId, slot]) => [
feedId,
{
polling: slot.timer !== null,
reasons: [...slot.reasons],
trips: slot.delays ? Object.keys(slot.delays).length : 0,
ageMs: Number.isFinite(slot.at) ? now() - slot.at : null,
},
]),
),
};
}
return {
stopsFor,
onSelect,
loadSchedule,
scheduleFor,
watchUpdates,
unwatchUpdates,
delaysFor,
stop,
forget,
stats,
};
}