mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 16:22:20 +00:00
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.
279 lines
9.7 KiB
JavaScript
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,
|
|
};
|
|
}
|