mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-19 01:32:19 +00:00
feat(rail): add a Rail layer with keyless live trains
Live trains from 30 keyless operator feeds: GPS positions from 29 and Irish Rail's station reports, shown as the operators publish them. 28 work out of the box; Renfe long and medium distance and KTMB appear once their pack is built, because their vehicles name no route. Packs are opt-in (scripts/build-rail-paths.mjs): the operator's own route lines, stop names, next stops and trip-update delays for live trains. Nothing downloads when the app starts, no train is placed from a timetable, and no request carries a deployer's key.
This commit is contained in:
1 parent
14db73f201
commit
830c080803
114 files changed
+26639
-26
No files matched your search
@@ -0,0 +1,518 @@
|
||||
/**
|
||||
* @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;
|
||||
slot.delays = delaysFromUpdates(body);
|
||||
slot.at = now();
|
||||
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,
|
||||
};
|
||||
}
|
||||
Reference in new issue
Block a user