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:
Denis Groshev committed 2026-11-11 16:06:22 +01:00
1 parent 14db73f201
commit 830c080803
114 files changed
+26639 -26

No files matched your search

+257
View File
@@ -0,0 +1,257 @@
/**
* @module irishRail
* @description Adapter for the Irish Rail realtime API's running-trains list
* (`getCurrentTrainsXML`), turning it into the train records the GTFS-RT path
* produces.
*
* The document is a flat list of `<objTrainPositions>` elements, each with
* seven text children (TrainStatus, TrainLatitude, TrainLongitude, TrainCode,
* TrainDate, PublicMessage, Direction). That schema is all this reads, so it
* is read with a small scanner instead of an XML library: no DTDs, no entity
* definitions, no attributes, no nesting beyond those two levels. A document
* that declares a DTD or entities is refused, and every size is capped (whole
* text, train count, field length).
*
* Positions are NOT GPS: the operator places each train at the station or
* timing point its signalling system last reported. The record says so with
* `positionSource: 'event'` (added by the rail proxy). The feed carries no
* time for that report, so a record's time is the fetch time, labelled
* `timestampSource: 'fetch'`, which the layer ages conservatively.
*
* Pure: no Node built-ins, safe for node:test and any server runtime.
*/
import { isPlausibleVehiclePosition } from './gtfsRealtime.js';
/** Longest document read (characters). A full day's list is about 35 KB. */
export const IRISH_RAIL_MAX_TEXT_CHARS = 1024 * 1024;
/** Most trains read from one document; about 80 run at once. */
export const IRISH_RAIL_MAX_TRAINS = 2000;
/** Longest accepted field (characters); the public message is the longest. */
export const IRISH_RAIL_MAX_FIELD_CHARS = 512;
const FIELDS = Object.freeze([
'TrainStatus',
'TrainLatitude',
'TrainLongitude',
'TrainCode',
'TrainDate',
'PublicMessage',
'Direction',
]);
/** Error for a document this adapter will not read. */
export class IrishRailFormatError extends Error {
constructor(message) {
super(message);
this.name = 'IrishRailFormatError';
}
}
const NAMED_ENTITIES = Object.freeze({
amp: '&',
lt: '<',
gt: '>',
quot: '"',
apos: "'",
});
/**
* Decode the five predefined XML entities and numeric character references.
* An unknown entity is left as written (no DTD can define one here).
* @param {string} text
* @returns {string}
*/
export function decodeXmlText(text) {
return String(text).replace(
/&(#x[0-9a-fA-F]{1,6}|#[0-9]{1,7}|[a-zA-Z]{2,4});/g,
(whole, body) => {
if (body[0] === '#') {
const code =
body[1] === 'x' || body[1] === 'X'
? Number.parseInt(body.slice(2), 16)
: Number.parseInt(body.slice(1), 10);
return Number.isInteger(code) && code > 0 && code <= 0x10ffff
? String.fromCodePoint(code)
: whole;
}
return Object.hasOwn(NAMED_ENTITIES, body) ? NAMED_ENTITIES[body] : whole;
},
);
}
/**
* The text of `<name>...</name>` inside one train element, `''` for an empty
* or self-closing element, null when absent or over the field cap.
*/
function readField(block, name) {
const open = `<${name}>`;
const start = block.indexOf(open);
if (start < 0) {
return block.includes(`<${name}/>`) || block.includes(`<${name} />`)
? ''
: null;
}
const from = start + open.length;
const end = block.indexOf(`</${name}>`, from);
if (end < 0 || end - from > IRISH_RAIL_MAX_FIELD_CHARS * 6) return null;
const value = decodeXmlText(block.slice(from, end)).trim();
return value.length <= IRISH_RAIL_MAX_FIELD_CHARS ? value : null;
}
/**
* Split the running-trains document into raw train rows.
* @param {string} text
* @returns {{rows: Array<Record<string, string|null>>, truncated: boolean}}
*/
export function parseIrishRailTrainsXml(text) {
if (typeof text !== 'string') throw new IrishRailFormatError('not text');
if (text.length > IRISH_RAIL_MAX_TEXT_CHARS)
throw new IrishRailFormatError(`document is ${text.length} characters`);
if (/<!DOCTYPE|<!ENTITY/i.test(text))
throw new IrishRailFormatError('document declares a DTD');
if (!text.includes('<ArrayOfObjTrainPositions'))
throw new IrishRailFormatError('not a running-trains document');
const rows = [];
let truncated = false;
const OPEN = '<objTrainPositions>';
const CLOSE = '</objTrainPositions>';
let at = text.indexOf(OPEN);
while (at >= 0) {
const end = text.indexOf(CLOSE, at + OPEN.length);
if (end < 0) break;
if (rows.length >= IRISH_RAIL_MAX_TRAINS) {
truncated = true;
break;
}
const block = text.slice(at + OPEN.length, end);
const row = {};
for (const name of FIELDS) row[name] = readField(block, name);
rows.push(row);
at = text.indexOf(OPEN, end + CLOSE.length);
}
return { rows, truncated };
}
/**
* Read the three lines of a public message. The operator separates lines
* with a literal backslash-n; a real newline is accepted too.
*
* A118\n14:50 - Dublin Connolly to Belfast (0 mins late)\nDeparted Dundalk next stop Newry
* E244\nHowth to Bray\nExpected Departure 16:35
* A311\n15:05 - Tralee to Mallow(-2 mins late)\nTERMINATED Mallow at 16:34
*
* @param {string|null} message
* @returns {{origin: string|null, destination: string|null,
* scheduledDeparture: string|null, delaySec: number|null,
* event: 'departed'|'arrived'|'expected'|'terminated'|null,
* lastStop: string|null, nextStop: string|null}}
*/
export function parsePublicMessage(message) {
const result = {
origin: null,
destination: null,
scheduledDeparture: null,
delaySec: null,
event: null,
lastStop: null,
nextStop: null,
};
const lines = String(message ?? '')
.split(/\\n|\r?\n/)
.map((line) => line.trim())
.filter(Boolean);
const route =
/^(?:(\d{1,2}:\d{2})\s*-\s*)?(.+?)\s+to\s+(.+?)(?:\s*\((-?\d{1,4})\s*mins?\s+late\))?$/i.exec(
lines[1] || '',
);
if (route) {
result.scheduledDeparture = route[1] || null;
result.origin = route[2].trim();
result.destination = route[3].trim();
if (route[4] !== undefined) result.delaySec = Number(route[4]) * 60;
}
const event = lines[2] || '';
let match;
if (
(match = /^(Departed|Arrived)\s+(.+?)\s+next stop\s+(.+)$/i.exec(event))
) {
result.event =
match[1].toLowerCase() === 'departed' ? 'departed' : 'arrived';
result.lastStop = match[2].trim();
result.nextStop = match[3].trim();
} else if (/^Expected Departure\b/i.test(event)) {
result.event = 'expected';
} else if (
(match = /^TERMINATED\s+(.+?)\s+at\s+\d{1,2}:\d{2}/i.exec(event))
) {
result.event = 'terminated';
result.lastStop = match[1].trim();
}
return result;
}
/**
* Turn the running-trains document into unclassified train records in the
* shape the GTFS-RT path produces (src/data/gtfsRealtime.js), plus the
* delay the public message states (`delaySec`). The message's last and next
* stop and the row's direction only decide `status`; nothing reads them
* further, so they do not leave the server.
*
* Status `T` (terminated) trains are dropped: they are out of service, parked
* at the end of their run. Status `N` trains are due to start within ten
* minutes and stand at their origin (`STOPPED_AT`). A running train is
* `STOPPED_AT` after "Arrived" and `IN_TRANSIT_TO` its next stop after
* "Departed".
*
* @param {string} text The XML document.
* @param {number} fetchedAtS Fetch time (epoch seconds), the only time the
* feed lets a record carry.
* @returns {{entityCount: number, truncated: boolean, vehicles: object[]}}
*/
export function decodeIrishRailTrains(text, fetchedAtS) {
const { rows, truncated } = parseIrishRailTrainsXml(text);
const seen = new Set();
const vehicles = [];
for (const row of rows) {
const code = row.TrainCode;
if (!code || !/^[A-Z0-9]{1,8}$/.test(code) || seen.has(code)) continue;
const status = row.TrainStatus;
if (status !== 'R' && status !== 'N') continue;
const lat = Number.parseFloat(row.TrainLatitude ?? '');
const lon = Number.parseFloat(row.TrainLongitude ?? '');
if (!isPlausibleVehiclePosition(lat, lon)) continue;
seen.add(code);
const message = parsePublicMessage(row.PublicMessage);
const routeId =
message.origin && message.destination
? `${message.origin} - ${message.destination}`
: null;
vehicles.push({
id: code,
lat: Number(lat.toFixed(6)),
lon: Number(lon.toFixed(6)),
bearing: null,
speedMps: null,
timestamp: fetchedAtS,
timestampSource: 'fetch',
routeId,
tripId: code,
directionId: null,
label: routeId
? `${code} ${message.origin} to ${message.destination}`
: code,
stopId: null,
status:
// i18n-ignore: GTFS-Realtime status codes, not UI text
status === 'N' || message.event === 'arrived'
? 'STOPPED_AT'
: message.event === 'departed'
? 'IN_TRANSIT_TO'
: null,
occupancy: null,
delaySec: message.delaySec,
});
}
return { entityCount: rows.length, truncated, vehicles };
}