mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 16:22:20 +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,278 @@
|
||||
/**
|
||||
* @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,
|
||||
};
|
||||
}
|
||||
Reference in new issue
Block a user