Files
gods-eye-view/src/data/railTripUpdates.js
T
Denis Groshev 830c080803 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.
2026-11-11 16:06:22 +01:00

279 lines
9.7 KiB
JavaScript

/**
* @module railTripUpdates
* @description Minimal, bounded GTFS-Realtime decoder for TripUpdates feeds,
* for the Rail layer's live delays.
*
* Same approach as the VehiclePositions decoder (src/data/gtfsRealtime.js):
* `pbf` straight off the wire, field numbers as the contract, no generated
* code. Only what a delay readout needs is read; vehicle positions, alerts and
* every extension are skipped by pbf.
*
* Field numbers (gtfs-realtime.proto, v2.0):
* FeedEntity 3 trip_update
* TripUpdate 1 trip, 2 stop_time_update[], 3 vehicle, 4 timestamp,
* 5 delay
* StopTimeUpdate 1 stop_sequence, 2 arrival, 3 departure, 4 stop_id,
* 5 schedule_relationship
* StopTimeEvent 1 delay (int32), 2 time (int64), 3 uncertainty
* TripDescriptor 1 trip_id, 2 start_time, 3 start_date,
* 4 schedule_relationship, 5 route_id, 6 direction_id
*
* Decoding is bounded the way the vehicle decoder is: entities past the cap
* are left unread, stop updates past the per-trip cap are left unread, and an
* over-long string drops the record it belongs to instead of truncating it.
*
* Pure: safe to import from the browser layer, the Vite proxy, and node:test.
*/
import { PbfReader } from 'pbf';
import {
GTFS_INCREMENTALITY_FULL_DATASET,
GTFS_MAX_ENTITIES,
GTFS_MAX_STRING_CHARS,
} from './gtfsRealtime.js';
/** Stop updates kept per trip. The longest rail trips call at ~100 stops. */
export const RAIL_TRIP_UPDATE_MAX_STOPS = 200;
/** Trips kept per decode, before the rail filter. */
export const RAIL_TRIP_UPDATE_MAX_TRIPS = 20_000;
/**
* Plausible delay range (seconds). A day either way covers every honest
* report; a value outside it is a unit error, not a late train.
*/
export const RAIL_TRIP_UPDATE_MAX_DELAY_S = 86_400;
/** TripDescriptor.ScheduleRelationship enum → label. */
const TRIP_RELATIONSHIP = Object.freeze({
0: 'SCHEDULED',
1: 'ADDED',
2: 'UNSCHEDULED',
3: 'CANCELED',
5: 'REPLACEMENT',
6: 'DUPLICATED',
7: 'DELETED',
8: 'NEW',
});
/** StopTimeUpdate.ScheduleRelationship enum → label. */
const STOP_RELATIONSHIP = Object.freeze({
0: 'SCHEDULED',
1: 'SKIPPED',
2: 'NO_DATA',
3: 'UNSCHEDULED',
});
function readBoundedString(pbf, target) {
const value = pbf.readString();
if (value.length <= GTFS_MAX_STRING_CHARS) return value;
target.oversize = true;
return null;
}
function readFeedHeader(tag, header, pbf) {
if (tag === 1) header.version = readBoundedString(pbf, header);
else if (tag === 2) header.incrementality = pbf.readVarint();
else if (tag === 3) header.timestamp = pbf.readVarint();
}
function readTripDescriptor(tag, trip, pbf) {
if (tag === 1) trip.tripId = readBoundedString(pbf, trip);
else if (tag === 2) trip.startTime = readBoundedString(pbf, trip);
else if (tag === 3) trip.startDate = readBoundedString(pbf, trip);
else if (tag === 4) trip.scheduleRelationship = pbf.readVarint();
else if (tag === 5) trip.routeId = readBoundedString(pbf, trip);
else if (tag === 6) trip.directionId = pbf.readVarint();
}
function readVehicleDescriptor(tag, descriptor, pbf) {
if (tag === 1) descriptor.id = readBoundedString(pbf, descriptor);
else if (tag === 2) descriptor.label = readBoundedString(pbf, descriptor);
}
function readStopTimeEvent(tag, event, pbf) {
// int32 and int64 are plain (not zig-zag) varints: negatives arrive as
// ten-byte two's complement, which the signed read restores.
if (tag === 1) event.delay = pbf.readVarint(true);
else if (tag === 2) event.time = pbf.readVarint(true);
}
function readStopTimeUpdate(tag, update, pbf) {
if (tag === 1) update.stopSequence = pbf.readVarint();
else if (tag === 2) update.arrival = pbf.readMessage(readStopTimeEvent, {});
else if (tag === 3) update.departure = pbf.readMessage(readStopTimeEvent, {});
else if (tag === 4) update.stopId = readBoundedString(pbf, update);
else if (tag === 5) update.scheduleRelationship = pbf.readVarint();
}
function readTripUpdate(tag, tripUpdate, pbf) {
if (tag === 1) tripUpdate.trip = pbf.readMessage(readTripDescriptor, {});
else if (tag === 2) {
// Past the cap the stop is left unread; pbf skips it whole.
if (tripUpdate.stops.length >= RAIL_TRIP_UPDATE_MAX_STOPS) {
tripUpdate.stopsTruncated = true;
return;
}
tripUpdate.stops.push(pbf.readMessage(readStopTimeUpdate, {}));
} else if (tag === 3)
tripUpdate.vehicle = pbf.readMessage(readVehicleDescriptor, {});
else if (tag === 4) tripUpdate.timestamp = pbf.readVarint();
else if (tag === 5) tripUpdate.delay = pbf.readVarint(true);
}
function readFeedEntity(tag, entity, pbf) {
if (tag === 1) entity.id = readBoundedString(pbf, entity);
else if (tag === 2) entity.isDeleted = pbf.readBoolean();
else if (tag === 3)
entity.tripUpdate = pbf.readMessage(readTripUpdate, { stops: [] });
// 4 (vehicle) and 5 (alert) are skipped: a combined feed (the MTA's) costs
// one length varint per vehicle here.
}
function readFeedMessage(tag, message, pbf) {
if (tag === 1) message.header = pbf.readMessage(readFeedHeader, {});
else if (tag === 2) {
if (message.entityCount >= GTFS_MAX_ENTITIES) {
message.truncated = true;
return;
}
message.entityCount += 1;
const entity = pbf.readMessage(readFeedEntity, {});
if (!entity.tripUpdate) return;
if (message.tripUpdates.length >= RAIL_TRIP_UPDATE_MAX_TRIPS) {
message.truncated = true;
return;
}
message.tripUpdates.push(entity);
}
}
function nonEmptyString(value) {
const text = typeof value === 'string' ? value.trim() : '';
return text ? text : null;
}
function plausibleDelay(value) {
return Number.isInteger(value) &&
Math.abs(value) <= RAIL_TRIP_UPDATE_MAX_DELAY_S
? value
: null;
}
/** Epoch seconds between 2000 and 2100, else null. */
function plausibleTime(value) {
return Number.isInteger(value) && value > 946_684_800 && value < 4_102_444_800
? value
: null;
}
function normalizeEvent(event) {
if (!event) return null;
const time = plausibleTime(event.time);
const delay = plausibleDelay(event.delay);
if (time === null && delay === null) return null;
return { time, delay };
}
/**
* Flatten one decoded FeedEntity into the trip record `/api/rail/updates`
* serves, or null when it carries no usable trip.
*
* `delaySec` is the trip's own delay when the operator states one, else the
* delay at the first stop update that carries one (feeds list the stops still
* ahead, so that is the delay the train is running with now). Feeds that only
* publish predicted times (MBTA) have no delay to report: null, not zero.
* @param {object} entity Decoded FeedEntity.
* @returns {object|null}
*/
export function normalizeTripUpdateEntity(entity) {
if (!entity || entity.isDeleted === true) return null;
const update = entity.tripUpdate;
if (!update || entity.oversize || update.trip?.oversize) return null;
if (update.vehicle?.oversize) return null;
const tripId = nonEmptyString(update.trip?.tripId);
const routeId = nonEmptyString(update.trip?.routeId);
if (!tripId && !routeId) return null;
const stops = [];
for (const stop of update.stops) {
if (stop.oversize) continue;
const arrival = normalizeEvent(stop.arrival);
const departure = normalizeEvent(stop.departure);
const relationship = STOP_RELATIONSHIP[stop.scheduleRelationship] || null;
const stopId = nonEmptyString(stop.stopId);
const stopSequence = Number.isInteger(stop.stopSequence)
? stop.stopSequence
: null;
if (stopId === null && stopSequence === null) continue;
const record = { stopId, stopSequence, arrival, departure };
if (relationship && relationship !== 'SCHEDULED')
record.relationship = relationship;
stops.push(record);
}
let delaySec = plausibleDelay(update.delay);
if (delaySec === null) {
for (const stop of stops) {
const delay = stop.arrival?.delay ?? stop.departure?.delay ?? null;
if (delay !== null) {
delaySec = delay;
break;
}
}
}
const relationship =
TRIP_RELATIONSHIP[update.trip?.scheduleRelationship] || 'SCHEDULED';
const timestamp =
Number.isFinite(update.timestamp) && update.timestamp > 0
? update.timestamp
: null;
return {
tripId,
routeId,
startDate: nonEmptyString(update.trip?.startDate),
startTime: nonEmptyString(update.trip?.startTime),
directionId: Number.isInteger(update.trip?.directionId)
? update.trip.directionId
: null,
vehicleId: nonEmptyString(update.vehicle?.id),
relationship,
timestamp,
delaySec,
stopsTruncated: update.stopsTruncated === true,
stops,
};
}
/**
* Decode a TripUpdates FeedMessage, at most GTFS_MAX_ENTITIES entities.
* @param {Uint8Array|ArrayBuffer} bytes Protobuf wire bytes.
* @returns {{ version: string|null, timestamp: number|null,
* incrementality: number, entityCount: number, truncated: boolean,
* trips: object[] }}
*/
export function decodeTripUpdates(bytes) {
const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
const message = new PbfReader(view).readFields(readFeedMessage, {
header: {},
tripUpdates: [],
entityCount: 0,
truncated: false,
});
const trips = [];
for (const entity of message.tripUpdates) {
const trip = normalizeTripUpdateEntity(entity);
if (trip) trips.push(trip);
}
const header = message.header || {};
return {
version: header.oversize ? null : nonEmptyString(header.version),
timestamp:
Number.isFinite(header.timestamp) && header.timestamp > 0
? header.timestamp
: null,
incrementality: Number.isFinite(header.incrementality)
? header.incrementality
: GTFS_INCREMENTALITY_FULL_DATASET,
entityCount: message.entityCount,
truncated: message.truncated === true,
trips,
};
}