Merge origin/main into the renderer-contract branch: the procedural fleet models drawn through the renderer's model sets

Aircraft, military, local ADS-B, vessel, transit and rail models come from
the fleet model set, loaded up front and drawn life size through the draw
port's models sets; no layer touches the viewer or Cesium outside
src/render/cesium/. The models capability gains glTF bytes (gltf), a
per-axis stretch (axisScale), a colour for tinted parts (maskColor) and a
cut below the origin (clip: 'belowOrigin'), with conformance checks.

Main's rail layer and Data Library are ported to the ports; the CCTV
footprint probe keeps the globe-terrain clamp through the query port.
This commit is contained in:
Sameh Khamis committed 2026-11-13 14:14:42 -08:00
commit e3865f462f
533 files changed
+55738 -2518

No files matched your search

-51
View File
@@ -467,54 +467,3 @@ export const CLASS_SCALE_2D = {
bizjet: 0.72,
uav: 0.75,
};
/** 3D model scale multipliers — clamped [0.75, 1.45] while every class shares
* the single airplane.glb (a jet mesh at C172 scale reads wrong). Widen when
* real per-class models land in CLASS_MODEL_URL. */
export const CLASS_SCALE_3D = {
light: 0.75,
glider: 0.75,
turboprop: 0.85,
airliner: 1.0,
widebody: 1.3,
quadjet: 1.45,
helicopter: 0.8,
fastjet: 0.8,
bizjet: 0.8,
uav: 0.8,
};
/** Per-class glTF — all the shared airplane today; drop real assets in here.
* NOTE for future models: each asset may need its own heading offset (the
* shared GLB uses MODEL_HEADING_OFFSET_DEG = 180 in both layers). */
export const CLASS_MODEL_URL = {
light: '/models/airplane.glb',
glider: '/models/airplane.glb',
turboprop: '/models/airplane.glb',
airliner: '/models/airplane.glb',
widebody: '/models/airplane.glb',
quadjet: '/models/airplane.glb',
helicopter: '/models/airplane.glb',
fastjet: '/models/airplane.glb',
bizjet: '/models/airplane.glb',
uav: '/models/airplane.glb',
};
/** Real per-class GLBs (2026-08-15 Hangar fleet, owner picks; CC-BY 4.0 —
* provenance in public/models/README.md). Every asset is vertex-baked to the
* airplane.glb convention: Y-up, X = length, Z = span, nose −X (so the layers'
* MODEL_HEADING_OFFSET_DEG = 180 applies unchanged), origin at bbox centre,
* REAL-WORLD METERS (render at scale 1 — no MODEL_SCALE, no CLASS_SCALE_3D).
* bellyM = origin→lowest-vertex distance (grounded-model lift, replaces the
* airplane.glb MODEL_BELLY_OFFSET_NATIVE formula); radiusM = bounding-sphere
* radius in meters (pixel-size math). Values measured from the shipped GLBs —
* pinned by modelScale.test.mjs. Classes NOT listed (airliner, quadjet,
* glider, fastjet) still render the shared airplane.glb via CLASS_MODEL_URL. */
export const CLASS_MODEL_REAL = {
helicopter: { url: '/models/bell206.glb', bellyM: 1.66, radiusM: 8.24 },
light: { url: '/models/c172.glb', bellyM: 1.36, radiusM: 7.0 },
bizjet: { url: '/models/citation2.glb', bellyM: 2.86, radiusM: 11.24 },
uav: { url: '/models/mq9.glb', bellyM: 2.02, radiusM: 12.0 },
widebody: { url: '/models/b789.glb', bellyM: 7.81, radiusM: 44.08 },
turboprop: { url: '/models/atr72.glb', bellyM: 3.81, radiusM: 19.49 },
};
+2 -13
View File
@@ -1,7 +1,7 @@
// src/data/aircraftClass.test.mjs
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { classifyAircraft, CLASS_SCALE_2D, CLASS_SCALE_3D, CLASS_MODEL_URL, CLASS_MODEL_REAL } from './aircraftClass.js';
import { classifyAircraft, CLASS_SCALE_2D } from './aircraftClass.js';
test('type-code classification (military layer path)', () => {
assert.equal(classifyAircraft({ typeCode: 'F16' }), 'fastjet');
@@ -48,19 +48,8 @@ test('typeCode outranks category; unknown → airliner', () => {
assert.equal(classifyAircraft({ typeCode: null, category: 0 }), 'airliner');
});
test('scale/url tables cover every class', () => {
test('the icon scale table covers every class', () => {
for (const kind of ['light','glider','turboprop','airliner','widebody','quadjet','helicopter','fastjet','bizjet','uav']) {
assert.ok(Number.isFinite(CLASS_SCALE_2D[kind]), kind);
assert.ok(CLASS_SCALE_3D[kind] >= 0.75 && CLASS_SCALE_3D[kind] <= 1.45, kind);
assert.ok(typeof CLASS_MODEL_URL[kind] === 'string', kind);
}
});
test('CLASS_MODEL_REAL entries carry the fields the layers consume', () => {
for (const [kind, spec] of Object.entries(CLASS_MODEL_REAL)) {
assert.ok(spec.url.startsWith('/models/') && spec.url.endsWith('.glb'), kind);
assert.ok(spec.radiusM > 0 && spec.bellyM > 0, kind);
// every real-model class must also exist in the classifier tables
assert.ok(Number.isFinite(CLASS_SCALE_2D[kind]), kind);
}
});
+2 -2
View File
@@ -160,8 +160,8 @@ const BODIES = {
L -3,31 L -8,34 L -8,30 L -6,16
L -27,26 L -27,20 L -5,-8
C -4.6,-16 -4,-24 -3.5,-30 Z" fill="white" ${STROKE}/>`,
// 2026-08-15 Hangar additions: two NEW classes shipped with the real-model
// fleet (CLASS_MODEL_REAL). Same contract as the set above: 96×96 nose-up,
// 2026-08-15 additions: two NEW classes (bizjet, uav). Same contract as
// the set above: 96×96 nose-up,
// white fill, hairline stroke, tint-safe.
// Business jet — slender fuselage, modest swept wing, aft engines, T-tail.
bizjet: `
+51 -51
View File
@@ -11,6 +11,7 @@ import {
showModel,
} from './modelRecord.js';
import { modelDrawnScale } from './modelVisualAnchor.js';
import { fleetModelSet } from './fleetModels.js';
import { findCamera, findDraw, rendererOf } from '../render/rendererOf.js';
import { fromDegrees, toLonLatH } from '../geo/ellipsoid.js';
import {
@@ -24,12 +25,6 @@ import {
/** A white tint: what an IR-boosted model draws with. */
const WHITE = Object.freeze([1, 1, 1, 1]);
/** Id of the hidden item that keeps the tracked asset loaded. */
const PRELOAD_ID = '~preload';
/** Where the preload item waits, unshown. */
const NOWHERE = Object.freeze({ x: 0, y: 0, z: 0 });
/** How long (ms) a fleet model whose load failed (`loadFailed`) waits
* before it is removed and added again, which loads it again. */
const FLEET_MODEL_RETRY_MS = 5000;
@@ -85,8 +80,12 @@ function inView(pose, point) {
* @param {object} options.policy The layer's model budgets, radii, pixel
* bounds, heading offset, fleet tick interval and tracked-model load
* budget.
* @param {(klass: string) => object} options.modelSpec The class's GLB, scale,
* geometry and tint blend; `headingOffsetDeg` overrides the policy's.
* @param {(meta: object|undefined) => object} options.modelSpec The fleet
* model an aircraft draws with, from its record (its type and emitter
* category): the model's url, scale, geometry, tint blend and spec `key`;
* `headingOffsetDeg` overrides the policy's. A spec without a `url` (the
* fleet set not loaded yet) keeps the aircraft an icon. A spec naming a
* `model` of the fleet set is drawn from the set's bytes (`gltf`).
* @param {(icao24: string) => object} options.modelColor Model tint
* (`{red, green, blue, alpha}`), including the tracked contact's.
* @param {(icao24: string) => void} [options.onModelEligible] Runs when a
@@ -141,22 +140,25 @@ export function createAircraftModels({
};
}
/** The model heading offset a class's GLB needs. */
const _headingOffsetDeg = (klass) =>
_modelSpec(klass).headingOffsetDeg ?? policy.MODEL_HEADING_OFFSET_DEG;
/** A contact's record (its type and emitter category pick its model). */
const _metaOf = (icao24) => state.records.data.get(icao24);
/** A course (degrees) as the class's model heading (radians). */
const _modelHeading = (course, klass) =>
((course || 0) + _headingOffsetDeg(klass)) * RADIANS_PER_DEGREE;
/** The model heading offset an aircraft's model needs. */
const _headingOffsetDeg = (meta) =>
_modelSpec(meta).headingOffsetDeg ?? policy.MODEL_HEADING_OFFSET_DEG;
/** A course (degrees) as the aircraft's model heading (radians). */
const _modelHeading = (course, meta) =>
((course || 0) + _headingOffsetDeg(meta)) * RADIANS_PER_DEGREE;
/**
* Make this lifetime's model sets on the viewer's draw port (none on a
* renderer that draws no models: the layer stays icons). `draw` stands in
* for the viewer's (tests).
* @param {object} viewer
* @param {{preloadUrl?: string, draw?: object}} [options]
* @param {{draw?: object}} [options]
*/
function _createModelSets(viewer, { preloadUrl, draw } = {}) {
function _createModelSets(viewer, { draw } = {}) {
_disposeModelSets();
const port = draw ?? findDraw(viewer);
if (typeof port?.models !== 'function') return;
@@ -195,20 +197,6 @@ export function createAircraftModels({
}),
];
state._modelSets = { fleet, tracked, offs };
// A hidden item keeps the tracked asset loaded, so the tracked model
// draws as soon as it is wanted.
if (preloadUrl)
tracked.upsert([
{
id: PRELOAD_ID,
pos: NOWHERE,
url: preloadUrl,
orientation: { heading: 0, pitch: 0, roll: 0 },
environmentMap: AIRCRAFT_ENVIRONMENT_MAP_OPTIONS.enabled,
show: false,
pickable: false,
},
]);
}
/** Let this lifetime's model sets go. */
@@ -328,7 +316,7 @@ export function createAircraftModels({
if (h == null) return null;
const at = toLonLatH(pos);
if (!at) return null;
return fromDegrees(at.lon, at.lat, h + _modelSpec(meta.klass).bellyM);
return fromDegrees(at.lon, at.lat, h + _modelSpec(meta).bellyM);
}
/** How a contact's model draws now: the IR boost's flat white, or its tint. */
@@ -359,6 +347,8 @@ export function createAircraftModels({
id,
pos: { x: record.position.x, y: record.position.y, z: record.position.z },
url: record.url,
// Built from the bytes loaded up front: never fetched mid-session.
...(record.gltf ? { gltf: record.gltf } : {}),
orientation: { heading: record.heading, pitch: 0, roll: 0 },
scale: record.scale,
minPixelSize: record.minPixelSize,
@@ -422,8 +412,8 @@ export function createAircraftModels({
icons.setShown(icao24, true);
return false;
}
const klass = state.records.data.get(icao24)?.klass;
const spec = _modelSpec(klass);
const meta = _metaOf(icao24);
const spec = _modelSpec(meta);
const set = state._modelSets?.fleet ?? null;
_retryFailedFleetModel(set, icao24, record);
const displayPos = _modelDisplayPosition(icao24, pos);
@@ -435,7 +425,7 @@ export function createAircraftModels({
}
// Placed BEFORE the readiness test on purpose: a model can turn ready
// between ticks, and its first drawn frame must be at this placement.
placeModel(record, displayPos, _modelHeading(course, klass));
placeModel(record, displayPos, _modelHeading(course, meta));
if (!record.ready) {
showModel(record, false); // not loaded yet → keep the 2D icon, no half-model flash
_send(set, icao24, record, spec, out);
@@ -532,23 +522,27 @@ export function createAircraftModels({
return { pose: _pose(), ..._viewport() };
}
/** Spec identity for an admitted model: URL and scale together (same-URL classes
* differ by scale — airliner vs quadjet both ship airplane.glb). */
/** Spec identity for an admitted model: the model and its scale together
* (one model draws several types, each at its own length). */
const _specKeyFor = (klass) => {
const spec = _modelSpec(klass);
return `${spec.url}@${spec.scale}`;
const _specKeyFor = (meta) => {
const spec = _modelSpec(meta);
return spec.key ?? `${spec.url}@${spec.scale}`;
};
/** Class-change model sync (enrichment AND poll-path klass updates): when the
* aircraft's model no longer matches its class's spec, drop it so the
/** A spec's bytes in the fleet model set loaded up front, if any. */
const _gltfOf = (spec) =>
spec.model ? (fleetModelSet()?.bytes?.get(spec.model) ?? null) : null;
/** Type-change model sync (enrichment AND poll-path type/category updates): when the
* aircraft's model no longer matches its type's spec, drop it so the
* eligibility pass admits the right asset at the right scale. Gap-proof: the
* fleet icon is re-shown with the release, so the contact never goes
* invisible for the tick gap. The tracked standalone model gets the same
* rule (its billboard entity is always the fallback visual). */
function _syncModelToClass(icao24) {
const key = _specKeyFor(state.records.data.get(icao24)?.klass);
const key = _specKeyFor(_metaOf(icao24));
const current = state._models.get(icao24);
if (current && current.specKey !== key) _releaseModel(icao24);
if (
@@ -580,15 +574,18 @@ export function createAircraftModels({
if (!state._modelSets) return;
if (state._models.size >= _modelCap()) return;
if (!_modelRegimeActive() || !state.records.data.has(icao24)) return;
const klass = state.records.data.get(icao24)?.klass;
const spec = _modelSpec(klass);
const meta = _metaOf(icao24);
const spec = _modelSpec(meta);
// Until the fleet model set has loaded the aircraft stays an icon.
if (!spec.url) return;
const record = createModelRecord({
specKey: _specKeyFor(klass), // class-change sync compares against this
specKey: _specKeyFor(meta), // type-change sync compares against this
bellyM: spec.bellyM,
scale: spec.scale,
minPixelSize: policy.MODEL_MIN_PX,
});
record.url = resolveAsset(spec.url);
record.gltf = _gltfOf(spec);
record.tint = state._irBoost ? WHITE : rgba(_modelColor(icao24));
// Admitted, not yet the visual: the handoff places and shows it, and the
// set loads it from its first write.
@@ -672,7 +669,7 @@ export function createAircraftModels({
state._modelSets?.tracked,
record.id,
record,
_modelSpec(state.records.data.get(record.id)?.klass),
_modelSpec(_metaOf(record.id)),
);
}
@@ -705,20 +702,23 @@ export function createAircraftModels({
return;
}
const icao24 = state._trackedIcao;
const klass = state.records.data.get(icao24)?.klass;
const spec = _modelSpec(klass);
const meta = _metaOf(icao24);
const spec = _modelSpec(meta);
if (state._trackedModel && state._trackedModel.id !== icao24)
_releaseTrackedModel();
if (!state._trackedModel) {
if (!_trackedModelLoadAllowed()) return; // the icon carries it
// Until the fleet model set has loaded the icon carries it.
if (!spec.url) return;
const record = createModelRecord({
specKey: _specKeyFor(klass), // class-change sync compares against this
specKey: _specKeyFor(meta), // type-change sync compares against this
bellyM: spec.bellyM,
scale: spec.scale,
minPixelSize: policy.TRACKED_MODEL_MIN_PX,
});
record.id = icao24;
record.url = resolveAsset(spec.url);
record.gltf = _gltfOf(spec);
state._trackedModel = record;
}
const record = state._trackedModel;
@@ -741,7 +741,7 @@ export function createAircraftModels({
placeModel(
record,
displayPos,
_modelHeading(parts.motion._trackedDisplayCourse(), klass),
_modelHeading(parts.motion._trackedDisplayCourse(), meta),
);
if (record.ready) {
const pose = _pose();
@@ -906,7 +906,7 @@ export function createAircraftModels({
state._modelSets?.fleet,
icao24,
hidden,
_modelSpec(state.records.data.get(icao24)?.klass),
_modelSpec(_metaOf(icao24)),
items,
);
}
+4 -4
View File
@@ -26,11 +26,11 @@ test('the shared option turns the dynamic environment map off', () => {
for (const { name, source } of SOURCES) {
test(`${name}: every drawn aircraft model skips the dynamic environment map`, () => {
// Its models are draw-port items; every item it builds (fleet, tracked
// and the tracked preload) carries the shared option.
// Its models are draw-port items; every item it builds (fleet and
// tracked) carries the shared option.
assert.doesNotMatch(source, /fromGltfAsync|loadModel\(/);
const items = [...source.matchAll(/\burl: (?:record\.url|preloadUrl),/g)];
assert.ok(items.length >= 2, `expected model items in ${name}`);
const items = [...source.matchAll(/\burl: record\.url,/g)];
assert.ok(items.length >= 1, `expected model items in ${name}`);
const flags = [
...source.matchAll(/\benvironmentMap:\s*AIRCRAFT_ENVIRONMENT_MAP_OPTIONS\.enabled\b/g),
];
+58
View File
@@ -258,3 +258,61 @@ test('partial static data keeps newer live metadata ahead of the old static cach
assert.equal(rowFor(mmsi).type, '80');
assert.equal(rowFor(mmsi).destination, 'HAMBURG');
});
// A static report's dimensions are the antenna's distances to bow (A), stern
// (B), port (C) and starboard (D): length A+B, beam C+D. Zero is AIS's "not
// available", so a vessel reporting none has no size, not a size of zero.
test('a static report gives a vessel its hull length and beam', () => {
ingestAisStreamEnvelope(positionReport('636019825', { Sog: 14 }));
ingestAisStreamEnvelope({
MessageType: 'ShipStaticData',
Message: {
ShipStaticData: {
UserID: 636019825,
Name: 'EVER GIVEN',
Type: 70,
Dimension: { A: 330, B: 70, C: 30, D: 29 },
},
},
MetaData: { MMSI: '636019825' },
});
const row = rowFor('636019825');
assert.equal(row.length, 400);
assert.equal(row.beam, 59);
ingestAisStreamEnvelope(positionReport('636019826', { Sog: 3 }));
ingestAisStreamEnvelope({
MessageType: 'ShipStaticData',
Message: {
ShipStaticData: {
UserID: 636019826,
Type: 52,
Dimension: { A: 0, B: 0, C: 0, D: 0 },
},
},
MetaData: { MMSI: '636019826' },
});
assert.equal(rowFor('636019826').length, null);
assert.equal(rowFor('636019826').beam, null);
});
test('a Class B report carries its dimensions in part B', () => {
ingestAisStreamEnvelope(positionReport('244000777', { Sog: 6 }));
ingestAisStreamEnvelope({
MessageType: 'StaticDataReport',
Message: {
StaticDataReport: {
UserID: 244000777,
ReportB: {
Valid: true,
ShipType: 37,
Dimension: { A: 8, B: 4, C: 2, D: 2 },
},
},
},
MetaData: { MMSI: '244000777' },
});
const row = rowFor('244000777');
assert.equal(row.length, 12);
assert.equal(row.beam, 4);
});
+1
View File
@@ -29,6 +29,7 @@ export const writeCalibrationStoreV2 = layer.writeCalibrationStoreV2;
export const deriveCalBadge = layer.deriveCalBadge;
export const computeFrustumGeometry = layer.computeFrustumGeometry;
export const activationProbeClampRange = layer.activationProbeClampRange;
export const flatGroundAxisDistance = layer.flatGroundAxisDistance;
export const frameSignatureFromPixels = layer.frameSignatureFromPixels;
export const _createCctvProjectionPlaneForTest =
layer._createCctvProjectionPlaneForTest;
+12
View File
@@ -41,6 +41,7 @@ import cctvLayer, {
_pushAmbientCardEntriesForTest,
_setCctvOverlayHostForTest,
activationProbeClampRange,
flatGroundAxisDistance,
bindCctvWorldClickGesture,
clearProbeClampOnDeactivation,
computeFrustumGeometry,
@@ -660,6 +661,17 @@ test('activation obstruction clamp uses the field-derived 12 m floor', () => {
assert.equal(activationProbeClampRange(210, 250), null);
});
test('on a globe map the axis ends on flat ground at the mount ground', () => {
// A 24 m mount pitched 30° down meets the ground 48 m along its axis.
assert.ok(Math.abs(flatGroundAxisDistance(24, -30) - 48) < 1e-9);
// The default 700 m range then clamps just short of that, not 700 m out.
const clamp = activationProbeClampRange(700, flatGroundAxisDistance(24, -30));
assert.ok(Math.abs(clamp - 44) < 1e-9);
assert.equal(flatGroundAxisDistance(24, 0), null);
assert.equal(flatGroundAxisDistance(24, 10), null);
assert.equal(flatGroundAxisDistance(0, -30), null);
});
test('deactivation clears the probe clamp and restores nominal frustum geometry', () => {
const record = {
camera: { ...UNCLAMPED_CAMERA },
+1 -1
View File
@@ -41,7 +41,7 @@ for (const layer of LAYERS) {
assert.ok(calls.length >= 1, 'the draw port creates models');
for (const [index, call] of calls.entries()) {
assert.match(call[1], /\basynchronous:\s*false\b/,
`Model.fromGltfAsync call ${index + 1} must keep bounded GLB readiness independent of tile jobs`);
`_createModel call ${index + 1} must keep bounded GLB readiness independent of tile jobs`);
}
});
+25
View File
@@ -146,6 +146,13 @@ export const DATA_CREDITS = [
'<a href="https://www.planespotters.net" target="_blank" rel="noopener">Planespotters.net</a> ' +
'· each photo is © its photographer, credited beside it',
},
{
key: 'openvesselphotos',
html:
'Vessel photos: ' +
'<a href="https://openvesselphotos.org" target="_blank" rel="noopener">Open Vessel Photos</a> ' +
"· each photo keeps its author's open licence, credited beside it",
},
{
key: 'aisstream',
html:
@@ -508,6 +515,10 @@ export const DATA_CREDITS = [
key: 'gtfs-rt',
html: 'Transit vehicles: operator GTFS-Realtime feeds (each operator is credited below when its vehicles are shown)',
},
{
key: 'rail-gtfs-rt',
html: 'Trains: operator realtime feeds (each operator is credited below when its trains are shown)',
},
{
key: 'radio-browser',
html:
@@ -764,6 +775,20 @@ export function transitFeedCredit(feed, snapshot = null) {
};
}
/**
* Per-feed rail credit, registered the first time that feed's trains render
* (see `src/data/railFeeds.js` for the licence of each).
* @param {{ id: string, attribution: string, license: string, licenseUrl: string }} feed
* @returns {{ key: string, html: string }}
*/
export function railFeedCredit(feed) {
const transit = transitFeedCredit(feed);
return {
key: `rail-${feed.id}`,
html: transit.html.replace(/^Transit \(/, 'Trains ('),
};
}
/** Registered when the Bhote Koshi event reconstruction activates. */
export const BHOTE_KOSHI_CREDIT = {
key: 'bhote-koshi-2026',
+16
View File
@@ -52,6 +52,13 @@ test('Planespotters is credited with a plain followable link', () => {
assert.doesNotMatch(credit.html, /nofollow/);
});
test('Open Vessel Photos is credited with a plain followable link', () => {
const credit = DATA_CREDITS.find((entry) => entry.key === 'openvesselphotos');
assert.ok(credit, 'the selected vessel photos come from Open Vessel Photos');
assert.match(credit.html, /href="https:\/\/openvesselphotos\.org"/);
assert.doesNotMatch(credit.html, /nofollow/);
});
test('the UCS Satellite Database is acknowledged with its version and webpage', () => {
// UCS database manual, section 3: references name the version (the Excel
// file's name) and link www.ucsusa.org/satellite_database.
@@ -347,3 +354,12 @@ test('Warsaw and Poznań credits carry the data date their licences ask for', ()
assert.equal(mbta.key, 'transit-mbta');
assert.doesNotMatch(mbta.html, /data of/);
});
test('the always-on rail credit names live feeds only, never timetables', () => {
// Every train shown is where its operator reported it; none is placed
// from a timetable.
const rail = DATA_CREDITS.find((entry) => entry.key === 'rail-gtfs-rt');
assert.ok(rail);
assert.match(rail.html, /realtime feeds/);
assert.doesNotMatch(rail.html, /timetable|placed from/i);
});
+400
View File
@@ -0,0 +1,400 @@
import { selectModelEligible } from './modelEligibility.js';
import { AIRCRAFT_ENVIRONMENT_MAP_OPTIONS } from './aircraftModelLighting.js';
import { fleetModelSet } from './fleetModels.js';
import { findCamera, findDraw } from '../render/rendererOf.js';
import { fromDegrees, toLonLatH } from '../geo/ellipsoid.js';
import { horizonFrom } from '../geo/horizon.js';
import {
distanceSquared,
dot,
RADIANS_PER_DEGREE,
sub,
} from '../geo/vector.js';
/**
* Models of the procedural fleet set (`fleetModels.js`) drawn through the
* renderer's draw port, and the icon-to-model handoff the Vessels, Transit
* and Rail layers share.
*/
/** Every fleet GLB is nose -X: opposite the draw contract's heading 0. */
export const FLEET_HEADING_OFFSET_DEG = 180;
/** How long (ms) a model whose load failed waits before it loads again. */
const RETRY_MS = 5000;
/** A white tint: what a model under the NVG/FLIR styles draws with. */
const WHITE = Object.freeze([1, 1, 1, 1]);
/**
* A colour as the draw contract takes it: a CSS string or `[r, g, b, a]`
* as given, `{red, green, blue, alpha}` as an array; null for none.
*/
export function fleetColor(color) {
if (color === undefined || color === null) return null;
if (typeof color === 'string' || Array.isArray(color)) return color;
if (typeof color.red === 'number')
return [color.red, color.green, color.blue, color.alpha ?? 1];
return null;
}
/**
* The per-axis stretch a fleet spec draws with on top of its length scale,
* along the model's glTF axes (`x` its length, `y` its height, `z` its
* beam), or undefined when it keeps its proportions.
* @param {object} spec `fleetModelSpec`.
* @returns {[number, number, number]|undefined}
*/
export function fleetAxisScale(spec) {
const [length, beam, height] = spec?.scaleXYZ ?? [];
if (!(length > 0) || (beam === length && height === length)) return;
return [1, height / length, beam / length];
}
/**
* Whether `point` is inside the eye's view cone (`pose`), a metre's slack.
* @param {object} pose The camera port's pose.
* @param {{x:number,y:number,z:number}} point
* @returns {boolean}
*/
function inView(pose, point) {
const v = sub(point, pose.position);
const depth = dot(v, pose.direction);
if (depth < -1) return false;
const tanY = Math.tan(pose.fovy / 2);
const tanX = tanY * pose.aspectRatio;
return (
Math.abs(dot(v, pose.right)) <= Math.max(0, depth) * tanX + 1 &&
Math.abs(dot(v, pose.up)) <= Math.max(0, depth) * tanY + 1
);
}
let instances = 0;
/**
* 3D models for one layer's vehicles under the DISPLAY rail's 3D toggle (the
* Flights layer's `models3d`/`models3dMode`), on the same rules the aircraft
* layers follow: models only below the camera altitude ceiling, for the
* nearest `cap` vehicles in the add/keep band, on-screen first. A vehicle's
* icon stays the visual until its model is loaded and placed; the layer reads
* `modelOwnsVisual` back from each item and hides that icon.
*
* The models are one `models` set of the viewer's draw port, built from the
* fleet set's bytes loaded up front (`gltf`), so none is fetched
* mid-session. Without a draw port that draws models the layer stays icons.
*
* Each frame the layer passes its vehicles as items:
* `{position, headingDeg, spec, tint, pickId, show, groundLiftM}`,
* `position` the ECEF point the model's origin stands on (the waterline,
* the road or rail top; the spec's `elevationM` is added here),
* `groundLiftM` any lift the layer's icon carries above that point (taken
* off again), `tint` the route colour a tinted model paints where its
* `_TINT` attribute marks it (a CSS colour or `[r, g, b, a]`, or null),
* `pickId` what a pick on the model hands back (the item's `meta`), `show`
* false to keep it hidden.
*
* Under the luminance-mapped NVG/FLIR styles (`irBoost`) models draw unlit
* flat white, as aircraft models do. With `waterline`, each model is clipped
* at its origin's horizontal plane and only the part above it is drawn: a
* ship's hull below the waterline would otherwise show through a plain
* globe, which models are not depth-tested against.
* @param {object} options
* @param {object} options.viewer The scene host.
* @param {() => object|null} [options.display] `{models3d, models3dMode,
* irBoost}`.
* @param {object} options.policy `{altitudeCeilingM, minimumPixelSize,
* cap, capAll, addM, addAllM, keepM, keepAllM, intervalMs}`.
* @param {(url: string) => string} [options.resolveAsset]
* @param {boolean} [options.waterline] Clip each model at its waterline.
* @param {object} [options.draw] Stands in for the viewer's draw port (tests).
* @returns {object}
*/
export function createFleetModelLayer({
viewer,
display = () => null,
policy,
waterline = false,
resolveAsset = (url) => url,
draw,
}) {
const port = draw ?? findDraw(viewer);
const set =
typeof port?.models === 'function'
? port.models({ id: `fleet-models:${++instances}` })
: null;
/** @type {Map<string, object>} id -> admitted model */
const models = new Map();
let destroyed = false;
let lastEligibilityAt = -Infinity;
let eligible = new Set();
let settling = 0;
const offs = set
? [
set.on('ready', (id) => {
const record = models.get(id);
if (!record) return;
record.ready = true;
record.failedAt = 0;
}),
set.on('loadFailed', (id) => {
const record = models.get(id);
if (record) record.failedAt = Date.now();
}),
]
: [];
function release(id) {
if (!models.delete(id)) return;
set?.remove([id]);
}
function releaseAll() {
if (models.size) set?.clear();
models.clear();
}
function preferences() {
return display?.() || null;
}
function pose() {
try {
return findCamera(viewer)?.pose() ?? null;
} catch {
return null;
}
}
function regime(prefs, eye = pose()) {
if (!set || !prefs?.models3d || !fleetModelSet()) return false;
const height = eye?.height ?? Infinity;
return height < policy.altitudeCeilingM;
}
function admit(id, item, cap) {
const fleet = fleetModelSet();
const gltf = fleet?.bytes?.get(item.spec.model);
// A model whose GLB did not load draws nothing: the icon stays.
if (!gltf) return;
const current = models.get(id);
if (current && current.specKey === item.spec.key) return;
if (current) release(id);
if (models.size >= cap) return;
models.set(id, {
specKey: item.spec.key,
url: resolveAsset(item.spec.url),
gltf,
ready: false,
failedAt: 0,
sent: null,
});
}
function refreshEligibility(items, prefs, eye) {
const all = prefs.models3dMode === 'all';
const cap = all ? policy.capAll : policy.cap;
const addM = all ? policy.addAllM : policy.addM;
const keepM = all ? policy.keepAllM : policy.keepM;
const candidates = [];
for (const [id, item] of items) {
if (!item.position || item.show === false || !item.spec?.url) continue;
const distanceSq = distanceSquared(eye.position, item.position);
if (distanceSq > keepM * keepM) continue;
candidates.push([id, distanceSq, inView(eye, item.position)]);
}
candidates.sort((a, b) => a[1] - b[1]);
eligible = selectModelEligible(candidates, {
cap,
addDistSq: addM * addM,
isModeled: (id) => models.has(id),
});
for (const id of [...models.keys()]) if (!eligible.has(id)) release(id);
for (const id of eligible) admit(id, items.get(id), cap);
}
/** Where the model's origin stands: the item's point raised by the spec's elevation. */
function placement(item) {
const lift = (item.spec.elevationM || 0) - (item.groundLiftM || 0);
if (!lift) return item.position;
const at = toLonLatH(item.position);
if (!at) return item.position;
return fromDegrees(at.lon, at.lat, at.height + lift);
}
/** The draw item for an admitted model, as the set draws it. */
function itemOf(id, record, item, show, boost) {
const at = placement(item);
const mask = item.spec.tinted && !boost ? fleetColor(item.tint) : null;
return {
id,
pos: { x: at.x, y: at.y, z: at.z },
url: record.url,
gltf: record.gltf,
orientation: {
heading:
((item.headingDeg || 0) + FLEET_HEADING_OFFSET_DEG) *
RADIANS_PER_DEGREE,
pitch: 0,
roll: 0,
},
scale: item.spec.scale,
...(fleetAxisScale(item.spec)
? { axisScale: fleetAxisScale(item.spec) }
: {}),
minPixelSize: policy.minimumPixelSize,
environmentMap: AIRCRAFT_ENVIRONMENT_MAP_OPTIONS.enabled,
...(boost
? {
shading: 'unlit',
tint: WHITE,
colorBlend: { mode: 'mix', amount: 1 },
}
: { shading: 'pbr' }),
...(mask ? { maskColor: mask } : {}),
...(waterline ? { clip: 'belowOrigin' } : {}),
meta: item.pickId ?? id,
show,
};
}
/** The item to write for a record, or null when nothing it draws changed. */
function changed(id, record, item, show, boost) {
const next = itemOf(id, record, item, show, boost);
const p = next.pos;
const mask = next.maskColor ? String(next.maskColor) : '';
const key = `${p.x},${p.y},${p.z}|${next.orientation.heading}|${item.spec.key}|${mask}|${boost}|${show}`;
if (key === record.sent && next.meta === record.meta) return null;
record.sent = key;
record.meta = next.meta;
return next;
}
return {
/** Ids whose model admission is current. */
get eligible() {
return eligible;
},
/**
* Per-frame pass: re-derive eligibility at the policy's cadence, then
* place every admitted model and hand each item's visual to its model
* only once the model is ready and placed (`item.modelOwnsVisual`).
* @param {Map<string, object>} items
* @param {number} nowMs
* @returns {boolean} Whether any model is drawn.
*/
frame(items, nowMs) {
if (destroyed) return false;
const prefs = preferences();
const eye = pose();
if (!eye || !regime(prefs, eye)) {
settling = 0;
if (models.size) releaseAll();
eligible = new Set();
for (const item of items.values()) item.modelOwnsVisual = false;
return false;
}
const boost = prefs.irBoost === true;
if (nowMs - lastEligibilityAt >= policy.intervalMs) {
lastEligibilityAt = nowMs;
refreshEligibility(items, prefs, eye);
}
for (const item of items.values()) item.modelOwnsVisual = false;
const horizon = horizonFrom(eye.position);
const writes = [];
let drawn = false;
settling = 0;
for (const [id, record] of models) {
const item = items.get(id);
if (!item) {
release(id);
continue;
}
if (item.spec?.key !== record.specKey) {
// A new type or size: the next eligibility pass admits it.
lastEligibilityAt = -Infinity;
release(id);
continue;
}
if (record.failedAt && Date.now() - record.failedAt >= RETRY_MS) {
// Removed and added again, the set loads it again.
record.failedAt = 0;
record.sent = null;
record.ready = false;
set.remove([id]);
}
const visible =
!!item.position &&
item.show !== false &&
horizon.isPointVisible(item.position);
if (!visible) {
if (record.sent !== null) {
const write = changed(id, record, item, false, boost);
if (write) writes.push(write);
}
continue;
}
// Placed before the readiness test: its first drawn frame is here.
const show = record.ready;
const write = changed(id, record, item, show, boost);
if (write) writes.push(write);
if (!show) {
if (!record.failedAt) settling += 1;
continue;
}
item.modelOwnsVisual = true;
drawn = true;
}
if (writes.length) set.upsert(writes);
return drawn;
},
/**
* Models loading or not yet ready after the last frame: the layer keeps
* frames coming while any are, so each one takes over as soon as it can.
*/
get settling() {
return settling;
},
/**
* Whether models are drawn now: 3D on, the set loaded and the camera
* below the altitude ceiling. A layer skips building items while not.
* @returns {boolean}
*/
active() {
return !destroyed && regime(preferences());
},
/** The record of the model drawing `id`, if one is admitted. */
modelFor(id) {
return models.get(id) || null;
},
/** Show or hide every model (the layer's own visibility). */
setVisible(show) {
if (set) set.show = show;
},
/** Drop every model (3D off, layer disabled). */
clear: releaseAll,
/** Number of admitted models (tests and diagnostics). */
get size() {
return models.size;
},
/** The draw set's id, for picks and height queries to name it. */
get setId() {
return set?.id ?? null;
},
destroy() {
if (destroyed) return;
destroyed = true;
releaseAll();
for (const off of offs) off();
set?.dispose();
},
};
}
+434
View File
@@ -0,0 +1,434 @@
// The icon-to-model handoff the Vessels, Transit and Rail layers share
// (fleetModelInstances.js): models only under the DISPLAY 3D toggle and the
// altitude ceiling, at most `cap` of the nearest, each vehicle's icon the
// visual until its model is loaded, ready and placed, drawn through the
// renderer's model sets from the bytes loaded up front, and a tinted model
// painted with its route colour.
import test from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
import {
createFleetModelLayer,
fleetAxisScale,
fleetColor,
FLEET_HEADING_OFFSET_DEG,
} from './fleetModelInstances.js';
import {
loadFleetModelSet,
transitModelSpec,
vesselModelSpec,
} from './fleetModels.js';
import { fetchPublicFile } from '../testSupport/fleetGlb.mjs';
import { bindFakeDraw } from '../testSupport/fakeDrawPort.mjs';
import { eastNorthUp } from '../geo/frames.js';
import { fromDegrees, toLonLatH } from '../geo/ellipsoid.js';
import { add, distance, scale } from '../geo/vector.js';
const realInfo = console.info;
console.info = () => {};
const set = await loadFleetModelSet({ fetchImpl: fetchPublicFile });
console.info = realInfo;
const POLICY = Object.freeze({
altitudeCeilingM: 800_000,
minimumPixelSize: 16,
cap: 2,
capAll: 4,
addM: 5_000,
addAllM: 20_000,
keepM: 6_000,
keepAllM: 24_000,
intervalMs: 80,
});
const CENTRE = fromDegrees(-122.4, 37.8, 0);
/** A scene host with a fake draw port and a camera `height` m above CENTRE, looking down. */
function fakeViewer(height = 1_000) {
const viewer = {};
const position = fromDegrees(-122.4, 37.8, height);
const enu = eastNorthUp(position);
const { draw } = bindFakeDraw(viewer, {
camera: {
pose: () => ({
lon: -122.4,
lat: 37.8,
height,
position,
direction: scale(enu.z, -1),
up: enu.y,
right: enu.x,
fovy: Math.PI / 3,
aspectRatio: 1.5,
}),
},
});
return { viewer, draw };
}
/** A vehicle `metres` east of the camera's foot. */
function itemAt(metres, spec, extra = {}) {
const position = add(CENTRE, scale(eastNorthUp(CENTRE).x, metres));
return { position, headingDeg: 90, spec, tint: null, pickId: null, ...extra };
}
/** The layer's model set in the fake draw port. */
const modelSet = (draw) => draw.find('fleet-models:');
test('models are drawn from the up-front set, never fetched by URL', () => {
const { viewer, draw } = fakeViewer();
const layer = createFleetModelLayer({
viewer,
display: () => ({ models3d: true }),
policy: POLICY,
resolveAsset: (url) => `/base${url}`,
});
const spec = vesselModelSpec(set, { type: '70', length: 200, beam: 32 });
layer.frame(new Map([['s', itemAt(10, spec, { pickId: 's' })]]), 0);
const item = modelSet(draw).items.get('s');
assert.ok(item.gltf instanceof Uint8Array, 'the loaded GLB bytes');
assert.equal(item.gltf, set.bytes.get(spec.model));
assert.equal(item.url, `/base${spec.url}`, 'the url names it');
assert.equal(item.environmentMap, false);
layer.destroy();
});
test('the icon stays the visual until the model is ready; only the nearest are drawn', () => {
const { viewer, draw } = fakeViewer();
const display = { models3d: true, models3dMode: 'proximity' };
const layer = createFleetModelLayer({
viewer,
display: () => display,
policy: POLICY,
});
const spec = transitModelSpec(set, { mode: 'tram' });
const items = new Map([
['near', itemAt(100, spec, { pickId: 'near' })],
['mid', itemAt(1_000, spec, { pickId: 'mid' })],
['far', itemAt(4_000, spec, { pickId: 'far' })],
]);
layer.frame(items, 0);
const models = modelSet(draw);
assert.equal(models.items.size, POLICY.cap, 'the cap holds');
assert.deepEqual(
[...models.items.keys()].sort(),
['mid', 'near'],
'the nearest are modelled',
);
const near = models.items.get('near');
assert.equal(near.scale, spec.scale, 'drawn life size');
assert.equal(near.minPixelSize, POLICY.minimumPixelSize);
assert.equal(near.meta, 'near', 'picked as its vehicle');
assert.equal(near.show, false, 'hidden until ready');
layer.frame(items, 100);
for (const item of items.values())
assert.equal(item.modelOwnsVisual, false, 'not ready: the icon draws');
assert.ok(
layer.settling > 0,
'the layer asks for frames while models settle',
);
draw.ready(models.spec.id, 'near');
draw.ready(models.spec.id, 'mid');
layer.frame(items, 200);
assert.equal(items.get('near').modelOwnsVisual, true);
assert.equal(items.get('mid').modelOwnsVisual, true);
assert.equal(items.get('far').modelOwnsVisual, false);
assert.equal(layer.settling, 0);
assert.equal(models.items.get('near').show, true);
// A placed model stands on its item's point, nose along its heading.
const placed = models.items.get('near');
assert.ok(distance(placed.pos, items.get('near').position) < 1e-6);
assert.ok(
Math.abs(
placed.orientation.heading -
((90 + FLEET_HEADING_OFFSET_DEG) * Math.PI) / 180,
) < 1e-12,
);
// 3D off: every model goes and every icon comes back.
display.models3d = false;
layer.frame(items, 300);
assert.equal(layer.size, 0);
assert.equal(models.items.size, 0, 'released from the set');
for (const item of items.values()) assert.equal(item.modelOwnsVisual, false);
layer.destroy();
assert.equal(models.disposed, true);
});
test('models stay off above the altitude ceiling', () => {
const { viewer, draw } = fakeViewer(POLICY.altitudeCeilingM + 1);
const layer = createFleetModelLayer({
viewer,
display: () => ({ models3d: true }),
policy: POLICY,
});
assert.equal(layer.active(), false);
layer.frame(new Map([['a', itemAt(0, transitModelSpec(set, {}))]]), 0);
assert.equal(modelSet(draw).items.size, 0);
layer.destroy();
});
test('a tinted model is painted with its route colour; an untinted one is not', () => {
const { viewer, draw } = fakeViewer();
const layer = createFleetModelLayer({
viewer,
display: () => ({ models3d: true }),
policy: POLICY,
});
const tram = transitModelSpec(set, { mode: 'tram' });
const ship = vesselModelSpec(set, { type: '70', length: 180 });
assert.equal(tram.tinted, true);
assert.equal(ship.tinted, false);
const items = new Map([
['tram', itemAt(10, tram, { pickId: 'tram', tint: '#ff0000' })],
['ship', itemAt(20, ship, { pickId: 'ship', tint: '#ff0000' })],
]);
layer.frame(items, 0);
const models = modelSet(draw);
assert.equal(models.items.get('tram').maskColor, '#ff0000');
assert.equal(models.items.get('ship').maskColor, undefined);
// A new route colour is written in place.
items.get('tram').tint = [0, 0, 1, 1];
layer.frame(items, 10);
assert.deepEqual(models.items.get('tram').maskColor, [0, 0, 1, 1]);
assert.deepEqual(fleetColor({ red: 1, green: 0, blue: 0 }), [1, 0, 0, 1]);
layer.destroy();
});
test('an elevated vehicle is raised by its type elevation', () => {
const { viewer, draw } = fakeViewer();
const layer = createFleetModelLayer({
viewer,
display: () => ({ models3d: true }),
policy: POLICY,
});
const monorail = transitModelSpec(set, { mode: 'monorail' });
assert.equal(monorail.elevationM, set.types.transit.elevation.monorail);
const item = itemAt(10, monorail, { pickId: 'm' });
layer.frame(new Map([['m', item]]), 0);
const placed = modelSet(draw).items.get('m');
const lifted = toLonLatH(placed.pos).height;
const ground = toLonLatH(item.position).height;
assert.ok(Math.abs(lifted - ground - monorail.elevationM) < 1e-3);
layer.destroy();
});
test('a vessel stretched to its reported beam keeps its length scale on the model', () => {
const spec = vesselModelSpec(set, { type: '70', length: 200, beam: 60 });
assert.ok(spec.scaleXYZ[1] > spec.scaleXYZ[0], 'a wide hull for its length');
// Along the model's glTF axes: x its length, y its height, z its beam.
const [x, y, z] = fleetAxisScale(spec);
assert.equal(x, 1);
assert.ok(Math.abs(y - spec.scaleXYZ[2] / spec.scaleXYZ[0]) < 1e-12);
assert.ok(Math.abs(z - spec.scaleXYZ[1] / spec.scaleXYZ[0]) < 1e-12);
assert.equal(
fleetAxisScale(transitModelSpec(set, { mode: 'tram' })),
undefined,
'a model at its own proportions is not stretched',
);
assert.equal(FLEET_HEADING_OFFSET_DEG, 180, 'fleet models are built nose -X');
const { viewer, draw } = fakeViewer();
const layer = createFleetModelLayer({
viewer,
display: () => ({ models3d: true }),
policy: POLICY,
});
layer.frame(new Map([['s', itemAt(10, spec, { pickId: 's' })]]), 0);
const item = modelSet(draw).items.get('s');
assert.equal(item.scale, spec.scale, 'its length scale');
assert.deepEqual(item.axisScale, [x, y, z], 'stretched to its beam');
layer.destroy();
});
test('Vessels, Transit and Rail draw fleet models under the shared 3D toggle', () => {
for (const file of [
'src/layers/vessels/rendering.js',
'src/layers/transit/rendering.js',
'src/layers/rail/rendering.js',
]) {
const source = fs.readFileSync(
new URL(`../../${file}`, import.meta.url),
'utf8',
);
assert.match(
source,
/createFleetModelLayer\(/,
`${file}: draws fleet models`,
);
assert.match(
source,
/loadFleetModelSet\(/,
`${file}: loads the set up front`,
);
assert.match(
source,
/modelOwnsVisual/,
`${file}: hands its icon to the model`,
);
}
for (const file of [
'src/app/layers/aisLiveVessels.js',
'src/app/layers/transit.js',
'src/app/layers/rail.js',
]) {
const source = fs.readFileSync(
new URL(`../../${file}`, import.meta.url),
'utf8',
);
assert.match(
source,
/fleet: fleetModelServices\(/,
`${file}: given the fleet service`,
);
}
const catalog = fs.readFileSync(
new URL('../app/constructCatalog.js', import.meta.url),
'utf8',
);
assert.equal(
catalog.match(/displayParams: \(\) => flights\.getParams\(\)/g)?.length,
4,
'Local ADS-B, Vessels, Transit and Rail follow the Flights 3D toggle',
);
});
/** A layer whose models are all ready as soon as they are written. */
function readyLayer({ display, waterline = false } = {}) {
const { viewer, draw } = fakeViewer();
const layer = createFleetModelLayer({
viewer,
display: () => display,
policy: POLICY,
waterline,
});
const frame = (items, nowMs) => {
layer.frame(items, nowMs);
const models = modelSet(draw);
for (const id of models.items.keys()) draw.ready(models.spec.id, id);
layer.frame(items, nowMs + 1);
return models;
};
return { layer, draw, frame };
}
test('a model stands on the floor its icon is lifted above', () => {
const { layer, frame } = readyLayer({ display: { models3d: true } });
const tram = transitModelSpec(set, { mode: 'tram' });
const item = itemAt(10, tram, { pickId: 't', groundLiftM: 1.5 });
const models = frame(new Map([['t', item]]), 0);
const drop =
toLonLatH(item.position).height -
toLonLatH(models.items.get('t').pos).height;
assert.ok(Math.abs(drop - 1.5) < 1e-3, `dropped ${drop} m`);
layer.destroy();
});
test('under NVG/FLIR models draw unlit white, and lit again on exit, without loading again', () => {
const display = { models3d: true, irBoost: false };
const { layer, frame } = readyLayer({ display });
const tram = transitModelSpec(set, { mode: 'tram' });
const items = new Map([
['t', itemAt(10, tram, { pickId: 't', tint: '#ff0000' })],
]);
let models = frame(items, 0);
let item = models.items.get('t');
assert.equal(item.shading, 'pbr');
assert.equal(item.maskColor, '#ff0000');
display.irBoost = true;
layer.frame(items, 100);
item = models.items.get('t');
assert.equal(item.shading, 'unlit');
assert.deepEqual(item.tint, [1, 1, 1, 1]);
assert.deepEqual(item.colorBlend, { mode: 'mix', amount: 1 });
assert.equal(item.maskColor, undefined, 'no route colour under NVG/FLIR');
assert.equal(item.show, true, 'still the visual: restyled in place');
display.irBoost = false;
layer.frame(items, 200);
item = models.items.get('t');
assert.equal(item.shading, 'pbr');
assert.equal(item.maskColor, '#ff0000');
layer.destroy();
});
test('a waterline layer clips each model at its origin, keeping the part above', () => {
const { layer, frame } = readyLayer({
display: { models3d: true },
waterline: true,
});
const ship = vesselModelSpec(set, { type: '70', length: 200, beam: 32 });
const models = frame(new Map([['s', itemAt(10, ship, { pickId: 's' })]]), 0);
assert.equal(models.items.get('s').clip, 'belowOrigin');
layer.destroy();
const plain = readyLayer({ display: { models3d: true } });
const others = plain.frame(
new Map([['t', itemAt(10, transitModelSpec(set, { mode: 'tram' }))]]),
0,
);
assert.equal(others.items.get('t').clip, undefined, 'others unclipped');
plain.layer.destroy();
});
test('a failed model loads again after a while; the icon stays meanwhile', () => {
const { viewer, draw } = fakeViewer();
const layer = createFleetModelLayer({
viewer,
display: () => ({ models3d: true }),
policy: POLICY,
});
const tram = transitModelSpec(set, { mode: 'tram' });
const items = new Map([['t', itemAt(10, tram, { pickId: 't' })]]);
layer.frame(items, 0);
const models = modelSet(draw);
draw.loadFailed(models.spec.id, 't');
layer.frame(items, 100);
assert.equal(items.get('t').modelOwnsVisual, false);
assert.equal(layer.settling, 0, 'a failed model is not waited on');
layer.destroy();
});
test('without a draw port that draws models, vehicles stay icons', () => {
const viewer = {};
const layer = createFleetModelLayer({
viewer,
display: () => ({ models3d: true }),
policy: POLICY,
draw: { models: undefined },
});
const items = new Map([
['t', itemAt(10, transitModelSpec(set, { mode: 'tram' }))],
]);
assert.equal(layer.active(), false);
assert.equal(layer.frame(items, 0), false);
assert.equal(items.get('t').modelOwnsVisual, false);
layer.destroy();
});
test('a vehicle drawn as its model keeps its card and its detection entry', () => {
const read = (file) =>
fs.readFileSync(new URL(`../../${file}`, import.meta.url), 'utf8');
assert.match(
read('src/layers/transit/selection.js'),
/marker\?\.show !== false \|\| entry\.modelOwnsVisual === true/,
);
assert.match(
read('src/layers/rail/selection.js'),
/entry\.marker\?\.show !== false \|\| entry\.modelOwnsVisual === true/,
);
assert.match(
read('src/layers/transit/queries.js'),
/marker\.show === false && entry\.modelOwnsVisual !== true/,
);
assert.match(
read('src/layers/vessels/queries.js'),
/if \(!visual\.visible\) continue;/,
);
assert.match(
read('src/layers/transit/rendering.js'),
/entry\.mode === 'unknown'/,
'a vehicle of unknown mode keeps its icon',
);
});
+481
View File
@@ -0,0 +1,481 @@
/**
* @module fleetModels
* @description The project's procedural fleet models (`public/models/fleet/`):
* which model draws an aircraft, a vessel or a transit or rail vehicle, and at
* what size, from the set's `catalog.json` (each model's file, bounds,
* length, beam, clearance and icon class) and `types.json` (which model
* draws which type, and the fallbacks).
*
* Every model is metres, glTF Y-up, nose toward local -X, origin at the body
* centre (an aircraft's fuselage axis, a vessel's waterline, a road or rail
* vehicle's road or rail top), and is drawn life size: a type's published
* length over the model's built length is its scale.
*
* The resolvers are plain functions over the parsed JSON; `loadFleetModelSet`
* fetches the JSON and every GLB once, up front, so no model is fetched
* mid-session.
*/
import { classifyAircraft } from './aircraftClass.js';
import { FLEET_TRAIL_ANCHORS } from './fleetTrailAnchors.js';
/** Where the model set is served, relative to the application base. */
export const FLEET_MODEL_BASE = '/models/fleet/';
/**
* Longest and widest hulls afloat, metres (Seawise Giant 458 m; the TI
* tankers 68 m abeam). AIS gives the bow and stern from the antenna in 9 bits
* and each side in 6, their largest values (511, 63) meaning "that or more"
* or a set never configured: a 30 m tug reported 511 m long would be drawn 17
* times its size.
*/
const MAX_HULL_LENGTH_M = 460;
const MAX_HULL_BEAM_M = 75;
/** The model a known aircraft class draws when its type has no entry. */
const CLASS_MODELS = Object.freeze({
light: 'c172',
glider: 'glider',
turboprop: 'at72',
widebody: 'b789',
quadjet: 'b744',
helicopter: 'generic_heli',
fastjet: 't38',
bizjet: 'c56x',
uav: 'mq9',
});
/** OpenSky's integer aircraft category (state vector index 17) → ADS-B emitter category. */
const OPENSKY_EMITTER_CATEGORY = Object.freeze({
2: 'A1',
3: 'A2',
4: 'A3',
5: 'A4',
6: 'A5',
7: 'A6',
8: 'A7',
9: 'B1',
10: 'B2',
11: 'B3',
12: 'B4',
14: 'B6',
15: 'B7',
16: 'C1',
17: 'C2',
18: 'C3',
19: 'C4',
20: 'C5',
});
/** A text vessel type (as some AIS sources name it) → a representative AIS ship-type code. */
const TEXT_SHIP_TYPES = [
[/tanker|lng|lpg|gas carrier/i, 80],
[/cargo|container|bulk|carrier|freighter|ro-?ro/i, 70],
[/passenger|ferry|cruise/i, 60],
[/high.?speed/i, 40],
[/fishing|trawler/i, 30],
[/tug|towing/i, 52],
[/pilot/i, 50],
[/search|rescue|\bsar\b/i, 51],
[/dredg/i, 33],
[/military|naval|navy/i, 35],
[/law|police|patrol|coast ?guard/i, 55],
[/sail/i, 36],
[/pleasure|yacht/i, 37],
];
/**
* The model for an aircraft of ICAO type `type` (A320, B738, R44) and ADS-B
* emitter category `category`: the type's, else the category's, else
* `default_aircraft`.
* @param {object} types Parsed `types.json`.
* @param {string} [type]
* @param {string} [category]
* @returns {{model: string, length: number|null}}
*/
export function resolveAircraft(types, type, category) {
const t = type?.trim().toUpperCase();
const [model, length] =
(t && (types.aircraft[t] ?? types.helicopters[t])) ||
(category && types.categories[category]) ||
types.default_aircraft;
return { model, length };
}
/**
* A reported length as one a hull can have, else undefined (drawn as built).
* @param {number} [length]
* @returns {number|undefined}
*/
export function hullLength(length) {
return length !== undefined &&
length !== null &&
length > 0 &&
length <= MAX_HULL_LENGTH_M
? length
: undefined;
}
/**
* A reported beam as one a hull can have, else undefined.
* @param {number} [beam]
* @returns {number|undefined}
*/
export function hullBeam(beam) {
return beam !== undefined &&
beam !== null &&
beam > 0 &&
beam <= MAX_HULL_BEAM_M
? beam
: undefined;
}
/**
* The model for a vessel of AIS ship type `shipType` and the reported length
* and beam (metres) and name: the first rule that matches in the first type
* range that has one, else `default_vessel`. Drawn at the reported length;
* when it is unknown (most live feeds send none), chosen and drawn at the
* range's `typical_len`, else as built.
* @param {object} types Parsed `types.json`.
* @param {number} [shipType]
* @param {number} [length]
* @param {number} [beam]
* @param {string} [name]
* @returns {{model: string, length: number|null}}
*/
export function resolveVessel(types, shipType, length, beam, name) {
const L = hullLength(length) ?? 0;
const B = hullBeam(beam) ?? 0;
if (shipType !== undefined && shipType !== null) {
for (const group of types.vessels) {
if (!(shipType >= group.types[0] && shipType <= group.types[1])) continue;
const len = L > 0 ? L : (group.typical_len ?? 0);
const drawn = len > 0 ? len : null;
for (const rule of group.rules) {
if (rule.min_len && len < rule.min_len) continue;
if (rule.max_len && len > rule.max_len) continue;
if (rule.name_re && !new RegExp(rule.name_re).test(name ?? ''))
continue;
if (rule.max_bl && !(B > 0 && L > 0 && B / L <= rule.max_bl)) continue;
return { model: rule.model, length: drawn };
}
}
}
return { model: types.default_vessel, length: L > 0 ? L : null };
}
/**
* The model for a public transport vehicle: a rail category and mode
* (`transit`/`local`/`regional`/`national`/`international` × `rail`/`metro`/
* `tram`), else a GTFS `route_type` (basic 0-12 or extended 100-1507), else a
* mode name (`bus`, `tram`, `subway`, `rail`, `ferry`, `light_rail`, …),
* else `transit.default`. Each comes with the length to draw it at.
* @param {object} types Parsed `types.json`.
* @param {{railCategory?: string, railMode?: string, routeType?: number|string,
* mode?: string}} vehicle
* @returns {{model: string, length: number|null}}
*/
export function resolveTransit(
types,
{ railCategory, railMode, routeType, mode } = {},
) {
const transit = types.transit;
const rail = railCategory ? transit.rail[railCategory] : null;
const routeKey =
routeType === undefined || routeType === null || routeType === ''
? null
: String(Number(routeType));
const [model, length] =
(rail && (rail[railMode || 'rail'] ?? rail.rail)) ||
(routeKey && transit.route_types[routeKey]) ||
(mode && transit.modes[mode]) ||
transit.default;
return { model, length };
}
/**
* An AIS ship type as its numeric code: a code as given ("70"), or the code
* of the family a text type names ("Cargo" → 70); undefined when it names
* none.
* @param {string|number|null|undefined} type
* @returns {number|undefined}
*/
export function aisShipTypeCode(type) {
const text = String(type ?? '').trim();
if (!text) return undefined;
if (/^\d+$/.test(text)) {
const code = Number(text);
return code > 0 && code < 100 ? code : undefined;
}
for (const [pattern, code] of TEXT_SHIP_TYPES)
if (pattern.test(text)) return code;
return undefined;
}
/**
* An aircraft category as an ADS-B emitter category: an emitter string as
* given ("A3"), or OpenSky's integer category mapped to one.
* @param {string|number|null|undefined} category
* @returns {string|undefined}
*/
export function emitterCategory(category) {
if (typeof category === 'number')
return OPENSKY_EMITTER_CATEGORY[category] || undefined;
const text = String(category ?? '')
.trim()
.toUpperCase();
if (/^\d+$/.test(text)) return OPENSKY_EMITTER_CATEGORY[Number(text)];
return /^[A-D][0-7]$/.test(text) ? text : undefined;
}
/**
* The scale of model `model` drawn `length` metres long, along the model's
* length, beam and height. A vessel's reported beam stretches it sideways;
* its height follows the mean of the two.
* @param {object} model Catalog entry.
* @param {number|null} length
* @param {number} [beam] A vessel's reported beam.
* @returns {[number, number, number]}
*/
export function placeScale(model, length, beam) {
if (length === null || length === undefined || !(model.length > 0))
return [1, 1, 1];
const sx = length / model.length;
const b = hullBeam(beam);
const sy = b !== undefined && model.beam > 0 ? b / model.beam : sx;
return [sx, sy, (sx + sy) / 2];
}
/** Half the diagonal of a model's bounds: the radius Cesium bounds it by. */
function boundingRadius(model) {
const [x0, y0, z0] = model.min;
const [x1, y1, z1] = model.max;
return Math.hypot(x1 - x0, y1 - y0, z1 - z0) / 2;
}
/**
* The drawing of model `name` at `length` metres: what the layers place.
*
* `scale` is the uniform scale (along the model's length) a Cesium Model
* takes; `scaleXYZ` the model's length, beam and height scales, for a vessel
* stretched to its reported beam. `clearanceM` is how far the model reaches
* below its origin at that scale (wheels below an aircraft's axis, a keel
* below the waterline): a grounded aircraft stands its origin that far up.
* `elevationM` lifts a vehicle off the route it follows (a monorail, a
* gondola). `tinted` models carry the `_TINT` vertex attribute marking where
* a route colour applies. `nativeRadiusM` (unscaled), `visualCenterNative`
* and `trailAnchorNative` (raw glTF axes, unscaled) serve the aircraft
* layers' pixel-size, bracket and trail geometry.
* @param {{catalog: object, types: object}} set
* @param {string} name Catalog model name.
* @param {number|null} length Metres along the body; null draws it as built.
* @param {{beam?: number}} [options]
* @returns {object}
*/
export function fleetModelSpec(set, name, length, { beam } = {}) {
const model = set.catalog[name];
// Ground vehicles, balloons and obstacles are built at the size their type
// names (a tower's 60 m is its height, not a length to scale to).
const drawnLength = model.category === 'other' ? null : length;
const scaleXYZ = placeScale(model, drawnLength, beam);
const elevationM = set.types.transit?.elevation?.[name] || 0;
return Object.freeze({
model: name,
url: FLEET_MODEL_BASE + model.file,
category: model.category,
icon: model.icon,
length: model.length * scaleXYZ[0],
scale: scaleXYZ[0],
scaleXYZ: Object.freeze(scaleXYZ),
clearanceM: model.clearance * scaleXYZ[2],
elevationM,
tinted: model.category === 'transit',
nativeRadiusM: boundingRadius(model),
visualCenterNative: CENTRED,
trailAnchorNative: FLEET_TRAIL_ANCHORS[name] || CENTRED,
key: `${name}@${scaleXYZ.map((s) => s.toFixed(4)).join('x')}`,
});
}
const CENTRED = Object.freeze([0, 0, 0]);
/** `resolved` drawn from `set`, its model replaced by `fallback` when the catalog lacks it. */
function specOf(set, resolved, fallback, options) {
const known = set.catalog[resolved.model] ? resolved : fallback(resolved);
return fleetModelSpec(set, known.model, known.length, options);
}
/**
* The model an aircraft is drawn with. The type's entry first; then, for a
* type the map lacks, the model of its class (a fast jet, a helicopter, a
* glider) when the type names one; then the emitter category's; then
* `default_aircraft`.
* @param {{catalog: object, types: object}} set
* @param {{typeCode?: string|null, type?: string|null,
* category?: string|number|null}} aircraft
* @returns {object} {@link fleetModelSpec}
*/
export function aircraftModelSpec(set, { typeCode, type, category } = {}) {
const { types, catalog } = set;
const code = String(typeCode ?? type ?? '')
.trim()
.toUpperCase();
const emitter = emitterCategory(category);
let resolved = resolveAircraft(types, code, emitter);
const typed = code && (types.aircraft[code] || types.helicopters[code]);
if (!typed && code) {
const model = CLASS_MODELS[classifyAircraft({ typeCode: code })];
if (model && catalog[model])
resolved = { model, length: catalog[model].length };
}
return specOf(set, resolved, () => ({
model: types.default_aircraft[0],
length: types.default_aircraft[1],
}));
}
/**
* The model a vessel is drawn with, from its AIS ship type (a code or a text
* family), reported length and beam (metres) and name.
* @param {{catalog: object, types: object}} set
* @param {{type?: string|number|null, length?: number|null,
* beam?: number|null, name?: string|null}} vessel
* @returns {object} {@link fleetModelSpec}
*/
export function vesselModelSpec(set, { type, length, beam, name } = {}) {
// A beam counts only beside a reported length: a vessel drawn at its type's
// typical length keeps the model's proportions.
const reported = hullLength(length ?? undefined);
const hullWidth = reported === undefined ? undefined : (beam ?? undefined);
const resolved = resolveVessel(
set.types,
aisShipTypeCode(type),
reported,
hullWidth,
name ?? undefined,
);
return specOf(
set,
resolved,
(r) => ({ model: set.types.default_vessel, length: r.length }),
{ beam: hullWidth },
);
}
/**
* The model a transit or rail vehicle is drawn with ({@link resolveTransit}).
* @param {{catalog: object, types: object}} set
* @param {object} vehicle
* @returns {object} {@link fleetModelSpec}
*/
export function transitModelSpec(set, vehicle) {
return specOf(set, resolveTransit(set.types, vehicle), () => ({
model: set.types.transit.default[0],
length: set.types.transit.default[1],
}));
}
/**
* Every model the type map names, defaults and fallbacks included.
* @param {object} types Parsed `types.json`.
* @returns {Set<string>}
*/
export function namedFleetModels(types) {
const pairs = (map) => Object.values(map).map(([model]) => model);
const transit = types.transit;
return new Set([
...pairs(types.aircraft),
...pairs(types.helicopters),
...pairs(types.categories),
...types.vessels.flatMap((group) => group.rules.map((rule) => rule.model)),
types.default_aircraft[0],
types.default_vessel,
...pairs(transit.modes),
...pairs(transit.route_types),
...Object.values(transit.rail).flatMap(pairs),
transit.default[0],
...Object.keys(transit.elevation),
...Object.values(CLASS_MODELS),
]);
}
let loading = null;
let loaded = null;
/**
* The model set once {@link loadFleetModelSet} has loaded it, else null.
* @returns {object|null}
*/
export function fleetModelSet() {
return loaded;
}
/**
* Fetch the model set once for every layer: `catalog.json`, `types.json` and
* every GLB the catalog names, all up front, so no model is fetched while a
* session runs. Resolves to `{catalog, types, bytes, loadMs, totalBytes}`,
* `bytes` holding each model's GLB by name; a GLB that fails to load is left
* out (that model then draws nothing and its entities stay icons).
* @param {{resolveAsset?: (url: string) => string,
* fetchImpl?: typeof fetch, now?: () => number}} [options]
* @returns {Promise<object>}
*/
export function loadFleetModelSet({
resolveAsset = (url) => url,
fetchImpl = globalThis.fetch,
now = () => globalThis.performance?.now?.() ?? Date.now(),
} = {}) {
if (loading) return loading;
const started = now();
const json = async (name) => {
const response = await fetchImpl(resolveAsset(FLEET_MODEL_BASE + name));
if (!response.ok) throw new Error(`${name}: HTTP ${response.status}`);
return response.json();
};
loading = (async () => {
const [catalog, types] = await Promise.all([
json('catalog.json'),
json('types.json'),
]);
const bytes = new Map();
let totalBytes = 0;
await Promise.all(
Object.entries(catalog).map(async ([name, model]) => {
try {
const response = await fetchImpl(
resolveAsset(FLEET_MODEL_BASE + model.file),
);
if (!response.ok) return;
const glb = new Uint8Array(await response.arrayBuffer());
bytes.set(name, glb);
totalBytes += glb.byteLength;
} catch {
/* that model draws nothing; its entities stay icons */
}
}),
);
loaded = Object.freeze({
catalog,
types,
bytes,
loadMs: now() - started,
totalBytes,
});
console.info(
`[Fleet] ${bytes.size}/${Object.keys(catalog).length} models ` +
`(${(totalBytes / 1048576).toFixed(2)} MB) loaded in ${Math.round(loaded.loadMs)} ms`,
);
return loaded;
})();
// A failed catalog load may be retried by the next layer that starts.
loading.catch(() => {
loading = null;
});
return loading;
}
/** Forget the loaded set (tests). */
export function resetFleetModelSet() {
loading = null;
loaded = null;
}
+457
View File
@@ -0,0 +1,457 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import {
FLEET_MODEL_BASE,
aircraftModelSpec,
aisShipTypeCode,
emitterCategory,
fleetModelSet,
fleetModelSpec,
hullBeam,
hullLength,
loadFleetModelSet,
namedFleetModels,
placeScale,
resetFleetModelSet,
resolveAircraft,
resolveTransit,
resolveVessel,
transitModelSpec,
vesselModelSpec,
} from './fleetModels.js';
import { FLEET_TRAIL_ANCHORS } from './fleetTrailAnchors.js';
import {
centrelineSegments,
distanceToSurface,
fleetMesh,
measuredTrailAnchor,
readGlb,
vertexBounds,
} from '../testSupport/fleetGlb.mjs';
const ROOT = path.resolve(
path.dirname(fileURLToPath(import.meta.url)),
'../..',
);
const DIR = path.join(ROOT, 'public', 'models', 'fleet');
const json = (name) =>
JSON.parse(fs.readFileSync(path.join(DIR, name), 'utf8'));
const catalog = json('catalog.json');
const types = json('types.json');
const set = { catalog, types };
// A slice of the set's types.json and catalog.json, as the resolver's own
// reference tests use, so these read independently of later model changes.
const sliceTypes = {
aircraft: {
A320: ['a320', 37.57],
A21N: ['a320', 44.51],
A319: ['a320', 33.84],
B38M: ['b738', 39.52],
},
helicopters: { EC35: ['ec35', 10.2] },
categories: { A1: ['c172', 8.3] },
vessels: [
{
types: [70, 79],
typical_len: 300,
rules: [
{ min_len: 70, max_len: 140, max_bl: 0.12, model: 'inland_cargo' },
{
name_re: '\\b(LEADER|HIGHWAY|ACE|GLOVIS|HOEGH|SPIRIT OF)\\b',
min_len: 150,
model: 'car_carrier',
},
{ min_len: 250, model: 'container_ship' },
{ model: 'general_cargo' },
],
},
{ types: [31, 32], rules: [{ model: 'tug' }] },
{ types: [52, 52], rules: [{ model: 'tug' }] },
{ types: [0, 99], rules: [{ model: 'generic_vessel' }] },
],
default_aircraft: ['generic_plane', 36],
default_vessel: 'generic_vessel',
};
const model = (category, file, length, beam, clearance) => ({
category,
file,
min: [0, 0, 0],
max: [0, 0, 0],
length,
beam,
clearance,
tris: 1,
icon: 'jet',
});
const sliceCatalog = {
a320: model('aircraft', 'aircraft/a320.glb', 37.57, 35.6, 3.063),
container_ship: model('ships', 'ships/container_ship.glb', 309.9, 48, 13.9),
};
test('aircraft resolve by type, then emitter category, then the generic plane', () => {
assert.deepEqual(resolveAircraft(sliceTypes, 'A320'), {
model: 'a320',
length: 37.57,
});
assert.deepEqual(resolveAircraft(sliceTypes, ' b38m '), {
model: 'b738',
length: 39.52,
});
assert.equal(resolveAircraft(sliceTypes, 'EC35').model, 'ec35');
assert.deepEqual(resolveAircraft(sliceTypes, 'ZZZZ', 'A1'), {
model: 'c172',
length: 8.3,
});
assert.deepEqual(resolveAircraft(sliceTypes, undefined, 'Q9'), {
model: 'generic_plane',
length: 36,
});
});
test('vessels: the first matching rule of the first type range with one, else the generic vessel', () => {
assert.equal(resolveVessel(sliceTypes, 70, 366, 51).model, 'container_ship');
assert.equal(
resolveVessel(sliceTypes, 71, 199, 32, 'GLOVIS SPIRIT').model,
'car_carrier',
);
assert.equal(resolveVessel(sliceTypes, 79, 110, 11.4).model, 'inland_cargo');
assert.equal(resolveVessel(sliceTypes, 70, 90, 15).model, 'general_cargo');
assert.deepEqual(resolveVessel(sliceTypes, 52, 30, 10), {
model: 'tug',
length: 30,
});
assert.deepEqual(resolveVessel(sliceTypes, undefined, 50), {
model: 'generic_vessel',
length: 50,
});
assert.deepEqual(resolveVessel(sliceTypes, 0), {
model: 'generic_vessel',
length: null,
});
});
test("vessels of unknown length are chosen and drawn at their range's typical length", () => {
assert.deepEqual(resolveVessel(sliceTypes, 70), {
model: 'container_ship',
length: 300,
});
assert.deepEqual(resolveVessel(sliceTypes, 70, 511, 126), {
model: 'container_ship',
length: 300,
});
assert.deepEqual(resolveVessel(sliceTypes, 70, 90, 15), {
model: 'general_cargo',
length: 90,
});
assert.deepEqual(resolveVessel(sliceTypes, 31), {
model: 'tug',
length: null,
});
// Every passenger, cargo and tanker range of the set has one.
for (const code of [60, 70, 80]) {
assert.ok(resolveVessel(types, code).length > 100, String(code));
}
});
test("vessels: AIS's out-of-range sizes (511 m long, 126 m abeam) are unknown, drawn as built", () => {
assert.deepEqual(resolveVessel(sliceTypes, 52, 511), {
model: 'tug',
length: null,
});
assert.equal(hullLength(511), undefined);
assert.equal(hullLength(0), undefined);
assert.equal(hullBeam(126), undefined);
assert.equal(hullBeam(32), 32);
const ship = sliceCatalog.container_ship;
assert.deepEqual(placeScale(ship, ship.length, 126), [1, 1, 1]);
});
test('scale: aircraft by the type length, vessels by length and beam', () => {
const a320 = sliceCatalog.a320;
const [sx, sy, sz] = placeScale(a320, 44.51);
assert.ok(Math.abs(sx - 44.51 / 37.57) < 1e-12);
assert.equal(sy, sx);
assert.equal(sz, sx);
const ship = sliceCatalog.container_ship;
assert.deepEqual(placeScale(ship, ship.length / 2, 24), [0.5, 0.5, 0.5]);
assert.deepEqual(placeScale(ship, null), [1, 1, 1]);
});
test('every model the type map names is in the catalog, and its file is a GLB on disk', () => {
for (const name of namedFleetModels(types))
assert.ok(
catalog[name],
`${name}: named by types.json but not in the catalog`,
);
assert.equal(catalog.generic_plane?.category, 'aircraft');
assert.equal(catalog.generic_vessel?.category, 'ships');
assert.equal(catalog.city_bus?.category, 'transit');
for (const [name, metres] of Object.entries(types.transit.elevation)) {
assert.ok(catalog[name], name);
assert.ok(metres > 0, name);
}
let total = 0;
for (const [name, entry] of Object.entries(catalog)) {
const file = path.join(DIR, entry.file);
assert.ok(fs.existsSync(file), `${name}: ${entry.file} is missing`);
const bytes = fs.readFileSync(file);
assert.equal(bytes.subarray(0, 4).toString('latin1'), 'glTF', name);
assert.ok(entry.length > 0, name);
assert.ok(entry.tris <= 50_000, name);
total += bytes.length;
}
// The set ships with the repository and loads up front: keep it small.
assert.ok(total < 3 * 1024 * 1024, `fleet GLBs total ${total} bytes`);
});
test('transit bodies mark the share of the route colour they take; other models mark none', () => {
for (const [name, entry] of Object.entries(catalog)) {
const { json: gltf } = readGlb(path.join(DIR, entry.file));
for (const mesh of gltf.meshes)
for (const primitive of mesh.primitives)
assert.equal(
'_TINT' in primitive.attributes,
entry.category === 'transit',
name,
);
assert.equal(
fleetModelSpec(set, name, null).tinted,
entry.category === 'transit',
);
}
});
test('aircraft specs: by type, then class for an unlisted type, then emitter category', () => {
assert.equal(aircraftModelSpec(set, { typeCode: 'A320' }).model, 'a320');
assert.equal(aircraftModelSpec(set, { type: 'b744' }).model, 'b744');
// An unlisted fast jet is still a fast jet, not the generic airliner.
assert.equal(
aircraftModelSpec(set, { typeCode: 'FA18', category: 'A3' }).model,
't38',
);
assert.equal(aircraftModelSpec(set, { typeCode: 'MQ9' }).model, 'mq9');
assert.equal(
aircraftModelSpec(set, { typeCode: 'PUMA' }).model,
'generic_heli',
);
// An unlisted type of no special class falls to its category.
assert.equal(
aircraftModelSpec(set, { typeCode: 'ZZZZ', category: 'A5' }).model,
'b77w',
);
// OpenSky's integer category: 8 is rotorcraft (A7), 2 light (A1).
assert.equal(emitterCategory(8), 'A7');
assert.equal(emitterCategory('a3'), 'A3');
assert.equal(emitterCategory(1), undefined);
assert.equal(aircraftModelSpec(set, { category: 8 }).model, 'generic_heli');
assert.equal(aircraftModelSpec(set, { category: 2 }).model, 'c172');
assert.equal(aircraftModelSpec(set, {}).model, types.default_aircraft[0]);
});
test('aircraft specs are life size, standing on their scaled clearance', () => {
const spec = aircraftModelSpec(set, { typeCode: 'A21N' });
const [, length] = types.aircraft.A21N;
assert.equal(spec.model, types.aircraft.A21N[0]);
assert.ok(Math.abs(spec.length - length) < 1e-9);
assert.ok(Math.abs(spec.scale - length / catalog[spec.model].length) < 1e-12);
assert.ok(
Math.abs(spec.clearanceM - catalog[spec.model].clearance * spec.scale) <
1e-12,
);
assert.equal(spec.url, `${FLEET_MODEL_BASE}${catalog[spec.model].file}`);
assert.equal(spec.tinted, false);
assert.equal(spec.elevationM, 0);
assert.ok(
spec.nativeRadiusM * spec.scale > 25 &&
spec.nativeRadiusM * spec.scale < 60,
);
assert.deepEqual(spec.trailAnchorNative, FLEET_TRAIL_ANCHORS[spec.model]);
// A grounded service vehicle and an obstacle are drawn as built: the
// tower's 60 m is its height, not a length to stretch it to.
const tower = aircraftModelSpec(set, { category: 'C3' });
assert.equal(tower.model, 'tower');
assert.equal(tower.scale, 1);
assert.equal(aircraftModelSpec(set, { category: 'C1' }).scale, 1);
});
test('vessel specs read AIS codes and text families, stretched to the reported beam', () => {
assert.equal(aisShipTypeCode('70'), 70);
assert.equal(aisShipTypeCode(' Cargo '), 70);
assert.equal(aisShipTypeCode('Tanker'), 80);
assert.equal(aisShipTypeCode('Tug'), 52);
assert.equal(aisShipTypeCode('0'), undefined);
assert.equal(aisShipTypeCode(''), undefined);
const box = vesselModelSpec(set, { type: '71', length: 366, beam: 51 });
assert.equal(box.model, 'container_ship');
assert.ok(Math.abs(box.length - 366) < 1e-9);
const [sx, sy, sz] = box.scaleXYZ;
assert.ok(Math.abs(sy - 51 / catalog.container_ship.beam) < 1e-12);
assert.ok(Math.abs(sz - (sx + sy) / 2) < 1e-12);
// A beam with no reported length: the type's typical length, in the model's
// own proportions, not a typical-length hull squeezed to that beam.
const unsized = vesselModelSpec(set, { type: '70', length: 0, beam: 14 });
assert.equal(unsized.model, 'container_ship');
const [ux, uy, uz] = unsized.scaleXYZ;
assert.ok(Math.abs(uy - ux) < 1e-12 && Math.abs(uz - ux) < 1e-12);
assert.equal(vesselModelSpec(set, { type: 'Tug', length: 30 }).model, 'tug');
assert.equal(vesselModelSpec(set, { type: '36' }).model, 'sailboat');
// No type, no size: the generic vessel as built.
const unknown = vesselModelSpec(set, {});
assert.equal(unknown.model, types.default_vessel);
assert.equal(unknown.scale, 1);
});
test('transit specs: rail category and mode, then route type, then mode, then the default', () => {
assert.deepEqual(resolveTransit(types, { railCategory: 'national' }), {
model: 'intercity',
length: types.transit.rail.national.rail[1],
});
assert.equal(
resolveTransit(types, { railCategory: 'transit', railMode: 'metro' }).model,
'metro',
);
assert.equal(
resolveTransit(types, { railCategory: 'regional', railMode: 'tram' }).model,
'light_rail',
);
assert.equal(resolveTransit(types, { routeType: 3 }).model, 'city_bus');
assert.equal(resolveTransit(types, { routeType: '0' }).model, 'tram');
assert.equal(resolveTransit(types, { routeType: 109 }).model, 'commuter_emu');
assert.equal(resolveTransit(types, { mode: 'subway' }).model, 'metro');
assert.equal(resolveTransit(types, { mode: 'ferry' }).model, 'fast_ferry');
assert.equal(
resolveTransit(types, { mode: 'unknown' }).model,
types.transit.default[0],
);
const tram = transitModelSpec(set, { mode: 'tram' });
assert.equal(tram.tinted, true);
assert.equal(tram.clearanceM, 0);
assert.ok(Math.abs(tram.length - types.transit.modes.tram[1]) < 1e-9);
assert.equal(
transitModelSpec(set, { routeType: 12 }).elevationM,
types.transit.elevation.monorail,
);
assert.equal(
transitModelSpec(set, { mode: 'gondola' }).elevationM,
types.transit.elevation.gondola,
);
assert.equal(transitModelSpec(set, { mode: 'ferry' }).tinted, false);
});
test('a model missing from the catalog falls back to the default of its kind', () => {
const thin = {
catalog: { ...catalog },
types: {
...types,
aircraft: { ...types.aircraft, XXXX: ['no_such_model', 20] },
},
};
assert.equal(
aircraftModelSpec(thin, { typeCode: 'XXXX' }).model,
types.default_aircraft[0],
);
});
const ANCHORED = Object.entries(catalog).filter(([, entry]) =>
['aircraft', 'helicopters', 'other'].includes(entry.category),
);
test('every aircraft-layer model has a trail anchor on its real aft-belly hull', async () => {
assert.deepEqual(
new Set(Object.keys(FLEET_TRAIL_ANCHORS)),
new Set(ANCHORED.map(([name]) => name)),
're-run scripts/measure-fleet-trail-anchors.mjs',
);
for (const [name, entry] of ANCHORED) {
const mesh = await fleetMesh(path.join(DIR, entry.file));
const { min, max } = vertexBounds(mesh.verts);
const anchor = FLEET_TRAIL_ANCHORS[name];
// On the hull, not in the air beside it.
const offHull = distanceToSurface(anchor, mesh.verts, mesh.tris);
assert.ok(
offHull <= 1e-3,
`${name}: trail anchor is ${offHull.toFixed(4)} m off the hull`,
);
// Aft of the middle, so the head segment does not run into the body.
assert.ok(
anchor[0] > (min[0] + max[0]) / 2,
`${name}: trail anchor is not aft`,
);
// Nothing of the centreline hangs lower at or behind its station.
const lowest = centrelineSegments(mesh.verts, mesh.tris)
.flat()
.filter((p) => p[0] >= anchor[0] - 1e-3)
.reduce((low, p) => Math.min(low, p[1]), Infinity);
assert.ok(
anchor[1] <= lowest + 1e-3,
`${name}: trail anchor is above the hull aft of it`,
);
assert.equal(anchor[2], 0, `${name}: trail anchor is off the centreline`);
// And it is the construction, re-derived.
const measured = measuredTrailAnchor(mesh);
for (const axis of [0, 1])
assert.ok(
Math.abs(anchor[axis] - measured[axis]) <= 1e-3,
`${name} axis ${axis}: table ${anchor[axis]} vs measured ${measured[axis].toFixed(4)}`,
);
}
});
test('catalog bounds match the GLBs they describe', async () => {
for (const [name, entry] of Object.entries(catalog)) {
const { min, max } = vertexBounds(
(await fleetMesh(path.join(DIR, entry.file))).verts,
);
// The catalog is Z up (glTF Y), glTF Z across.
const tolerance = 0.01 * Math.max(1, entry.length);
assert.ok(Math.abs(min[0] - entry.min[0]) <= tolerance, `${name} min x`);
assert.ok(Math.abs(max[0] - entry.max[0]) <= tolerance, `${name} max x`);
assert.ok(Math.abs(min[1] - entry.min[2]) <= tolerance, `${name} min up`);
assert.ok(
Math.abs(-min[1] - entry.clearance) <= tolerance,
`${name} clearance`,
);
assert.ok(
Math.abs(max[2] - min[2] - (entry.max[1] - entry.min[1])) <= tolerance,
`${name} beam`,
);
}
});
test('the model set loads once, every GLB up front, shared by every layer', async () => {
resetFleetModelSet();
const requested = [];
const fetchImpl = async (url) => {
requested.push(url);
const file = path.join(ROOT, 'public', url.replace(/^\/app/, ''));
if (!fs.existsSync(file)) return { ok: false, status: 404 };
const bytes = fs.readFileSync(file);
return {
ok: true,
json: async () => JSON.parse(bytes.toString('utf8')),
arrayBuffer: async () =>
bytes.buffer.slice(
bytes.byteOffset,
bytes.byteOffset + bytes.byteLength,
),
};
};
const resolveAsset = (url) => `/app${url}`;
const [first, second] = await Promise.all([
loadFleetModelSet({ resolveAsset, fetchImpl }),
loadFleetModelSet({ resolveAsset, fetchImpl }),
]);
assert.equal(first, second);
assert.equal(fleetModelSet(), first);
assert.equal(first.bytes.size, Object.keys(catalog).length);
assert.equal(requested.length, Object.keys(catalog).length + 2);
assert.ok(requested.every((url) => url.startsWith('/app/models/fleet/')));
assert.ok(first.totalBytes > 0 && Number.isFinite(first.loadMs));
await loadFleetModelSet({ resolveAsset, fetchImpl });
assert.equal(requested.length, Object.keys(catalog).length + 2);
resetFleetModelSet();
});
+66
View File
@@ -0,0 +1,66 @@
/**
* Aft-belly trail attachment points of the fleet models the aircraft layers
* draw, in raw glTF axes (X along the body, nose toward -X; Y up), metres
* before scale, node transforms applied. Each is the point of the model's
* centreline profile (its z = 0 slice) nearest its aft-belly bounding-box
* corner: on the hull, aft, and on the centreline (see modelVisualAnchor.js).
*
* Written by scripts/measure-fleet-trail-anchors.mjs; re-measured against the
* GLBs by fleetModels.test.mjs.
*/
export const FLEET_TRAIL_ANCHORS = Object.freeze({
a139: Object.freeze([6.8847, 0.2766, 0]),
a320: Object.freeze([17.2078, 0.7416, 0]),
a333: Object.freeze([29.7276, 1.1084, 0]),
a343: Object.freeze([30.0371, 1.2335, 0]),
a359: Object.freeze([31.0731, 1.1573, 0]),
a388: Object.freeze([34.3139, 1.9279, 0]),
as50: Object.freeze([5.2278, -0.0999, 0]),
at72: Object.freeze([12.8258, 0.6792, 0]),
b06: Object.freeze([4.62, -0.3002, 0]),
b407: Object.freeze([5.1264, -0.2797, 0]),
b738: Object.freeze([18.3819, 0.8391, 0]),
b744: Object.freeze([33.6232, 1.5411, 0]),
b763: Object.freeze([25.5464, 0.9889, 0]),
b77w: Object.freeze([34.4639, 1.2084, 0]),
b789: Object.freeze([29.0604, 1.0649, 0]),
balloon: Object.freeze([3.8215, -0.0009, 0]),
bcs3: Object.freeze([17.8658, 0.713, 0]),
be20: Object.freeze([6.6699, 0.5505, 0]),
blimp: Object.freeze([32.2493, -7.1382, 0]),
c17: Object.freeze([26.5207, 2.332, 0]),
c172: Object.freeze([4.0507, 0.4481, 0]),
c30j: Object.freeze([13.568, 0.9917, 0]),
c56x: Object.freeze([7.4627, 0.4526, 0]),
car: Object.freeze([2.3, 0.418, 0]),
cl35: Object.freeze([10.4607, 0.8247, 0]),
crj9: Object.freeze([17.8413, 0.8624, 0]),
dh8d: Object.freeze([15.7902, 0.7501, 0]),
e175: Object.freeze([14.697, 0.6077, 0]),
e55p: Object.freeze([7.6566, 0.503, 0]),
ec35: Object.freeze([5.1003, 0.1471, 0]),
ec45: Object.freeze([5.8004, 0.555, 0]),
fire_truck: Object.freeze([5.5, 0.6051, 0]),
generic_heli: Object.freeze([5.4997, 0.1604, 0]),
generic_plane: Object.freeze([16.5228, 0.712, 0]),
glf4: Object.freeze([13.4603, 0.8243, 0]),
glider: Object.freeze([3.3997, 0.1283, 0]),
h47: Object.freeze([7.7303, 0.0035, 0]),
h60: Object.freeze([7.6295, 0.1365, 0]),
h64: Object.freeze([6.9228, -0.5553, 0]),
k35r: Object.freeze([28.0221, -2.4508, 0]),
md11: Object.freeze([30.8002, 1.2291, 0]),
mq9: Object.freeze([5.8498, -0.062, 0]),
p28a: Object.freeze([3.3695, 0.3959, 0]),
pc12: Object.freeze([6.6416, 0.5288, 0]),
pushback: Object.freeze([3, 0.2499, 0]),
r44: Object.freeze([4.4219, -0.3001, 0]),
s76: Object.freeze([6.6001, 0.1915, 0]),
sr22: Object.freeze([3.6762, 0.2376, 0]),
t38: Object.freeze([7.0246, -0.3791, 0]),
tex2: Object.freeze([4.7383, 0.2302, 0]),
tower: Object.freeze([1.2952, -0.0007, 0]),
ultralight: Object.freeze([3.2271, 0.3259, 0]),
v22: Object.freeze([7.9868, 0.2956, 0]),
van: Object.freeze([2.75, 0.418, 0]),
});
+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 };
}
+193
View File
@@ -0,0 +1,193 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
IRISH_RAIL_MAX_TEXT_CHARS,
IRISH_RAIL_MAX_TRAINS,
IrishRailFormatError,
decodeIrishRailTrains,
decodeXmlText,
parseIrishRailTrainsXml,
parsePublicMessage,
} from './irishRail.js';
/** One `<objTrainPositions>` element, written by hand for these tests. */
function train({
status = 'R',
lat = '53.3531',
lon = '-6.24591',
code = 'A118',
date = '06 Nov 2026',
message = 'A118\\n14:50 - Dublin Connolly to Belfast (3 mins late)\\nDeparted Dundalk next stop Newry',
direction = 'Northbound',
} = {}) {
return ` <objTrainPositions>
<TrainStatus>${status}</TrainStatus>
<TrainLatitude>${lat}</TrainLatitude>
<TrainLongitude>${lon}</TrainLongitude>
<TrainCode>${code}</TrainCode>
<TrainDate>${date}</TrainDate>
<PublicMessage>${message}</PublicMessage>
<Direction>${direction}</Direction>
</objTrainPositions>`;
}
function document(...trains) {
return `<?xml version="1.0" encoding="utf-8"?>
<ArrayOfObjTrainPositions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.irishrail.ie/realtime/">
${trains.join('\n')}
</ArrayOfObjTrainPositions>`;
}
const FETCHED_S = 1_794_000_000;
test('a running-trains document becomes GTFS-shaped train records', () => {
const { vehicles, entityCount, truncated } = decodeIrishRailTrains(
document(
train(),
train({
code: 'E244',
status: 'N',
message: 'E244\\nHowth to Bray\\nExpected Departure 16:35',
direction: 'Southbound',
}),
train({
code: 'D825',
message:
'D825\\n16:40 - Dun Laoghaire to Dundalk (0 mins late)\\nArrived Dun Laoghaire next stop Blackrock',
}),
),
FETCHED_S,
);
assert.equal(entityCount, 3);
assert.equal(truncated, false);
assert.equal(vehicles.length, 3);
const [enterprise, dart, commuter] = vehicles;
assert.deepEqual(enterprise, {
id: 'A118',
lat: 53.3531,
lon: -6.24591,
bearing: null,
speedMps: null,
timestamp: FETCHED_S,
timestampSource: 'fetch',
routeId: 'Dublin Connolly - Belfast',
tripId: 'A118',
directionId: null,
label: 'A118 Dublin Connolly to Belfast',
stopId: null,
status: 'IN_TRANSIT_TO',
occupancy: null,
delaySec: 180,
});
// The message's stops and the row's direction decide the status only.
for (const field of ['serviceState', 'lastStop', 'nextStop', 'direction'])
assert.equal(field in dart, false, field);
assert.equal(dart.status, 'STOPPED_AT');
assert.equal(dart.routeId, 'Howth - Bray');
assert.equal(dart.delaySec, null);
assert.equal(commuter.status, 'STOPPED_AT');
assert.equal(commuter.delaySec, 0);
});
test('terminated, unplaced, malformed and repeated trains are dropped', () => {
const { vehicles, entityCount } = decodeIrishRailTrains(
document(
train({
code: 'A311',
status: 'T',
message:
'A311\\n15:05 - Tralee to Mallow(-2 mins late)\\nTERMINATED Mallow at 16:34',
}),
train({ code: 'A1', lat: '0', lon: '0' }),
train({ code: 'A2', lat: 'north', lon: '-6.2' }),
train({ code: 'A3', status: 'X' }),
train({ code: 'bad code!' }),
train({ code: 'A4' }),
train({ code: 'A4', lat: '53.0' }),
),
FETCHED_S,
);
assert.equal(entityCount, 7);
assert.deepEqual(
vehicles.map((vehicle) => [vehicle.id, vehicle.lat]),
[['A4', 53.3531]],
);
});
test('public messages: the three line shapes, with and without spacing', () => {
assert.deepEqual(
parsePublicMessage(
'A311\\n15:05 - Tralee to Mallow(-2 mins late)\\nTERMINATED Mallow at 16:34',
),
{
origin: 'Tralee',
destination: 'Mallow',
scheduledDeparture: '15:05',
delaySec: -120,
event: 'terminated',
lastStop: 'Mallow',
nextStop: null,
},
);
const real = parsePublicMessage(
'D319\n16:27 - Docklands to M3 Parkway (1 mins late)\nArrived Pelletstown next stop Ashtown',
);
assert.equal(real.destination, 'M3 Parkway');
assert.equal(real.event, 'arrived');
assert.equal(real.nextStop, 'Ashtown');
assert.equal(parsePublicMessage('').origin, null);
assert.equal(parsePublicMessage(null).event, null);
assert.equal(parsePublicMessage('X1\\nno route here\\n?').origin, null);
});
test('entities are decoded and DTDs refused', () => {
assert.equal(
decodeXmlText('Tom &amp; Jerry &lt;&gt; &quot;&apos; &#65;&#x42; &bogus;'),
'Tom & Jerry <> "\' AB &bogus;',
);
assert.equal(decodeXmlText('&#0; &#x110000;'), '&#0; &#x110000;');
const { rows } = parseIrishRailTrainsXml(
document(train({ direction: 'To Dun Laoghaire &amp; Bray' })),
);
assert.equal(rows[0].Direction, 'To Dun Laoghaire & Bray');
assert.throws(
() =>
parseIrishRailTrainsXml(
`<!DOCTYPE x [<!ENTITY a "aaaa">]>${document(train())}`,
),
IrishRailFormatError,
);
assert.throws(
() => parseIrishRailTrainsXml('<html>error</html>'),
IrishRailFormatError,
);
assert.throws(() => parseIrishRailTrainsXml(42), IrishRailFormatError);
});
test('sizes are capped: document, train count and field length', () => {
assert.throws(
() =>
parseIrishRailTrainsXml(
document(train()) + ' '.repeat(IRISH_RAIL_MAX_TEXT_CHARS),
),
/characters/,
);
const many = Array.from({ length: IRISH_RAIL_MAX_TRAINS + 3 }, (_, i) =>
train({ code: `E${i}` }),
);
const capped = parseIrishRailTrainsXml(document(...many));
assert.equal(capped.rows.length, IRISH_RAIL_MAX_TRAINS);
assert.equal(capped.truncated, true);
const { rows } = parseIrishRailTrainsXml(
document(train({ message: 'm'.repeat(600) }), '<objTrainPositions>'),
);
assert.equal(rows.length, 1, 'an unclosed element is not a train');
assert.equal(rows[0].PublicMessage, null, 'an over-long field is refused');
const empty = parseIrishRailTrainsXml(
document(
'<objTrainPositions><TrainCode>E1</TrainCode><Direction /></objTrainPositions>',
),
);
assert.equal(empty.rows[0].Direction, '');
assert.equal(empty.rows[0].TrainStatus, null);
});
+13
View File
@@ -313,6 +313,13 @@ const OPTION_GROUPS = Object.freeze({
high: 'h',
}),
]),
rail: Object.freeze([
booleanOption('transit', 't', true),
booleanOption('local', 'l', true),
booleanOption('regional', 'r', true),
booleanOption('national', 'n', true),
booleanOption('international', 'i', true),
]),
'wildlife-sightings': Object.freeze([
booleanOption('confirmed', 'c', false),
enumOption(
@@ -700,6 +707,12 @@ export const LAYER_STATE_REGISTRY = Object.freeze([
disposition: 'enabled+options',
optionOwner: 'radio',
}),
Object.freeze({
id: 'rail',
token: '02',
disposition: 'enabled+options',
optionOwner: 'rail',
}),
Object.freeze({
id: 'recent-imagery',
token: '1',
+7 -5
View File
@@ -203,8 +203,8 @@ function encode(state) {
test('production registry is exact, canonical, and rejects incomplete contracts', async () => {
assert.equal(validateLayerStateRegistry(), true);
assert.equal(REGISTERED_LAYER_IDS.length, 38);
assert.equal(new Set(REGISTERED_LAYER_IDS).size, 38);
assert.equal(REGISTERED_LAYER_IDS.length, 39);
assert.equal(new Set(REGISTERED_LAYER_IDS).size, 39);
assert.ok(REGISTERED_LAYER_IDS.includes('transit'));
assert.deepEqual(REGISTERED_LAYER_IDS, [...REGISTERED_LAYER_IDS].sort());
assert.deepEqual(LEGACY_LAYER_STATE_TOKENS, {
@@ -243,12 +243,14 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
for (const [id, token] of Object.entries(LEGACY_LAYER_STATE_TOKENS)) {
assert.equal(LAYER_STATE_TOKEN_RESERVATIONS[id], token);
}
// News holds 00 and Shipwrecks 01, the first pairs: the next token is 02.
assert.equal(nextLayerStateToken(), '02');
// The allocation rules below read the ledger before either took a pair.
// News holds 00, Shipwrecks 01 and Rail 02, the first pairs: the next token
// is 03.
assert.equal(nextLayerStateToken(), '03');
// The allocation rules below read the ledger before any of them took a pair.
const beforeNews = { ...LAYER_STATE_TOKEN_RESERVATIONS };
delete beforeNews.news;
delete beforeNews.shipwrecks;
delete beforeNews.rail;
assert.equal(nextLayerStateToken(beforeNews), '00');
assert.equal(
nextLayerStateToken({
+19 -11
View File
@@ -97,10 +97,11 @@ function withPublishedBase(
}
}
// The ledger before Wildlife Sightings took the last digit and News and
// Shipwrecks the first pairs, for the allocation rules written against it.
// The ledger before Wildlife Sightings took the last digit and News,
// Shipwrecks and Rail the first pairs, for the allocation rules written
// against it.
const beforeLastDigitRows = reservationRows.filter(
([id]) => !['wildlife-sightings', 'news', 'shipwrecks'].includes(id),
([id]) => !['wildlife-sightings', 'news', 'shipwrecks', 'rail'].includes(id),
);
function writeCodecFixture(cwd, rows, entries) {
@@ -112,6 +113,7 @@ function writeCodecFixture(cwd, rows, entries) {
readFileSync(new URL(`./${name}`, import.meta.url)),
);
let source = readFileSync(CODEC_SOURCE_PATH, 'utf8');
// Layers published after the fixture's ledger are not in its registry.
if (!rows.some(([id]) => id === 'wildlife-sightings'))
source = source.replace(
/ Object\.freeze\(\{\s*id: 'wildlife-sightings',[\s\S]*?\}\),\n/,
@@ -127,6 +129,11 @@ function writeCodecFixture(cwd, rows, entries) {
/ Object\.freeze\(\{\s*id: 'shipwrecks',[\s\S]*?\}\),\n/,
'',
);
if (!rows.some(([id]) => id === 'rail'))
source = source.replace(
/ Object\.freeze\(\{\s*id: 'rail',[\s\S]*?\}\),\n/,
'',
);
const registryEnd = ']);\n\nexport const REGISTERED_LAYER_IDS';
assert.equal(source.split(registryEnd).length, 2);
const additions = entries
@@ -150,7 +157,7 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
{ ...parseLayerStateTokenReservations(reservationRows) },
{ ...LAYER_STATE_TOKEN_RESERVATIONS },
);
assert.equal(Object.keys(LAYER_STATE_TOKEN_RESERVATIONS).length, 38);
assert.equal(Object.keys(LAYER_STATE_TOKEN_RESERVATIONS).length, 39);
assert.deepEqual(
{ ...LAYER_STATE_TOKEN_RESERVATIONS },
{
@@ -165,6 +172,7 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
'wildlife-sightings': '9',
news: '00',
shipwrecks: '01',
rail: '02',
},
);
assert.throws(
@@ -190,9 +198,9 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
/Duplicate layer-state token reservation/,
);
assert.equal(
parseLayerStateTokenReservations([...reservationRows, ['future', '02']])
parseLayerStateTokenReservations([...reservationRows, ['future', '03']])
.future,
'02',
'03',
);
assert.throws(
() =>
@@ -423,19 +431,19 @@ test('an isolated valid two-character fixture round-trips an l field beyond the
test('checker reads a complete future base ledger and rejects retired-token reuse', () => {
withPublishedBase(
{
rows: [...reservationRows, ['retired-layer', '02']],
rows: [...reservationRows, ['retired-layer', '03']],
source:
'export const LAYER_STATE_TOKEN_RESERVATIONS = Object.freeze({ ["retired-layer"]: "02" });\n',
'export const LAYER_STATE_TOKEN_RESERVATIONS = Object.freeze({ ["retired-layer"]: "03" });\n',
},
(cwd) => {
const published = readPublishedLayerStateReservations('HEAD', cwd);
assert.equal(Object.keys(published).length, 39);
assert.equal(published['retired-layer'], '02');
assert.equal(Object.keys(published).length, 40);
assert.equal(published['retired-layer'], '03');
assert.throws(
() =>
validateLayerStateAllocations(published, {
...LAYER_STATE_TOKEN_RESERVATIONS,
newcomer: '02',
newcomer: '03',
}),
/changed or removed/,
);
@@ -20,6 +20,7 @@
["military-installations", "i"],
["news", "00"],
["radio", "r"],
["rail", "02"],
["recent-imagery", "1"],
["rocket-launches", "x"],
["s2-ghostmaps", "5"],
+22
View File
@@ -0,0 +1,22 @@
/**
* The Data Library's layer namespace, owned by the layer lifecycle: the
* manager accepts a late registration only under `lib-<entry id>`, and the
* library names its layers with the same rule.
*/
/** A library entry id: lowercase, digits and hyphens, 3–48 characters. */
export const LIBRARY_ID_PATTERN = /^[a-z0-9][a-z0-9-]{2,47}$/;
export const LIBRARY_LAYER_PREFIX = 'lib-';
/** The manager id a library entry's layer registers under. */
export function libraryLayerId(entryId) {
return `${LIBRARY_LAYER_PREFIX}${entryId}`;
}
/** The entry id behind a library layer id, or null. */
export function libraryEntryIdOf(layerId) {
if (typeof layerId !== 'string' || !layerId.startsWith(LIBRARY_LAYER_PREFIX))
return null;
const id = layerId.slice(LIBRARY_LAYER_PREFIX.length);
return LIBRARY_ID_PATTERN.test(id) ? id : null;
}
+54
View File
@@ -0,0 +1,54 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { LayerLifecycle } from './lifecycle.js';
const layer = (id) => ({
id,
name: id,
icon: '',
source: 'test',
async init() {},
async enable() {},
async update() {},
async disable() {},
async destroy() {},
getStats: () => ({ count: 0, lastUpdate: null }),
});
test('library layers register only after sealing and only in the lib- namespace', async () => {
const manager = new LayerLifecycle({});
const activity = [];
manager.subscribeActivity((change) => activity.push(change.type));
manager.register(layer('earthquakes'));
assert.throws(
() => manager.registerLibraryLayer(layer('lib-night-lights')),
/after the catalog is sealed/,
);
manager.finalizeRegistrations([
{ id: 'earthquakes', disposition: 'enabled-only' },
]);
assert.throws(
() => manager.registerLibraryLayer(layer('radio')),
/lib- namespace/,
);
assert.throws(() => manager.register(layer('lib-x-y-z')), /finalized/);
manager.registerLibraryLayer(layer('lib-night-lights'));
assert.equal(manager.isLibraryLayer('lib-night-lights'), true);
assert.equal(manager.isLibraryLayer('earthquakes'), false);
const rows = manager.getAll();
assert.equal(
rows.find(({ id }) => id === 'earthquakes').libraryEntryId,
null,
);
assert.equal(
rows.find(({ id }) => id === 'lib-night-lights').libraryEntryId,
'night-lights',
);
assert.equal(await manager.unregisterLibraryLayer('earthquakes'), false);
assert.equal(manager.layers.has('earthquakes'), true);
await manager.setEnabled('lib-night-lights', true, { origin: 'user' });
assert.equal(await manager.unregisterLibraryLayer('lib-night-lights'), true);
assert.equal(manager.layers.has('lib-night-lights'), false);
assert.equal(manager.isLibraryLayer('lib-night-lights'), false);
assert.equal(activity.filter((type) => type === 'registrations').length, 2);
});
+42
View File
@@ -1,4 +1,5 @@
import { cancelCameraArrival } from './cameraArrival.js';
import { libraryEntryIdOf } from './libraryLayerIds.js';
function cloneLayerParams(value) {
if (Array.isArray(value)) return value.map(cloneLayerParams);
@@ -97,6 +98,7 @@ export class LayerLifecycle {
this._registrationDispositions = null;
this._allowQaRegistration = allowQaRegistration === true;
this._qaLayerIds = new Set();
this._libraryLayerIds = new Set();
}
register(layerModule) {
@@ -125,6 +127,41 @@ export class LayerLifecycle {
return destroyed;
}
/**
* Register a Data Library layer after the catalog is sealed. Only ids in
* the library namespace (`lib-<entry id>`) are accepted, so this seam can
* never stand in for a core layer, and library layers never join the core
* share-token registry: their selection travels in `lib=` instead.
* @param {object} layerModule
* @returns {string} The registered id.
*/
registerLibraryLayer(layerModule) {
if (!this._registrationsFinalized)
throw new Error('Library layers register after the catalog is sealed');
if (!libraryEntryIdOf(layerModule?.id))
throw new Error('Library layer ids must use the lib- namespace');
this._registerLayer(layerModule);
this._libraryLayerIds.add(layerModule.id);
this._publishActivity({ type: 'registrations', layerId: layerModule.id });
return layerModule.id;
}
/** Destroy a layer registered through `registerLibraryLayer`. */
async unregisterLibraryLayer(layerId) {
if (!this._libraryLayerIds.has(layerId)) return false;
const destroyed = await this.destroyLayer(layerId);
if (destroyed) {
this._libraryLayerIds.delete(layerId);
this._publishActivity({ type: 'registrations', layerId });
}
return destroyed;
}
/** Whether a registered layer came from the Data Library. */
isLibraryLayer(layerId) {
return this._libraryLayerIds.has(layerId);
}
_registerLayer(layerModule) {
if (!layerModule || typeof layerModule.id !== 'string' || !layerModule.id) {
throw new Error('Data layer must provide a stable id');
@@ -2231,6 +2268,7 @@ export class LayerLifecycle {
}
this.layers.delete(layerId);
this._qaLayerIds.delete(layerId);
this._libraryLayerIds.delete(layerId);
return true;
}
@@ -2274,6 +2312,10 @@ export class LayerLifecycle {
// showInTogglePanel). The layer reports stats.keyRequired while that
// key is absent; the panel builds the guidance text from the pair.
requiresKeyId: entry.module.requiresKeyId || null,
// Data Library entry id; the panel groups these under Library.
libraryEntryId: this._libraryLayerIds.has(id)
? libraryEntryIdOf(id)
: null,
enabled: entry.enabled,
lifecycleState: entry.lifecycleState,
lifecycleUncertain: entry.lifecycleUncertain,
+223 -45
View File
@@ -103,6 +103,13 @@ export function localInfrastructureOverlayCopy(properties, layerId) {
if (river && river.toLocaleLowerCase() !== title.toLocaleLowerCase()) {
details.push(clampCardLine(river));
}
} else if (Array.isArray(props.__gevDetails)) {
// Data Library features carry their card lines from the manifest
// (src/library/formats.js presentLibraryProperties).
for (const line of props.__gevDetails.slice(0, 2)) {
const clean = cleanLabel(line);
if (clean) details.push(clampCardLine(clean));
}
}
return { title, details };
@@ -508,8 +515,13 @@ function wideFov(pose) {
* port: polygons and lines on the ground, and on each polygon or point a
* 3D stem with a dot on its tip, sized to the camera and lifted onto the
* sampled surface. Clicking any of it selects the feature and flies there.
* @param {object} options Dataset URL, identity, appearance and optional adapters.
* @param {object} options Dataset URL (or a `loadFeatures({signal})` loader
* resolving to GeoJSON features), identity, appearance (an optional
* `featureColor(properties)` returns a CSS colour per feature) and optional
* adapters.
* @param {object} services Caller-owned operations; see docs/INFRASTRUCTURE-LAYERS.md.
* An optional `getSelectedEntityContext()` lets `replaceFeatures` keep the
* selection on a feature the new set still has.
* @returns {object} A fresh layer implementing init/enable/disable/update/destroy/getStats/getAnalystRecords.
* One live instance per layer id is allowed in a given viewer/context/overlay host.
* Destroy the previous instance before replacing it. Importing creates no layers.
@@ -526,6 +538,8 @@ export function createLocalGeoJsonLayer(
labels = true,
labelMax = DEFAULT_LABEL_MAX,
labelGridPx = DEFAULT_LABEL_GRID_PX,
loadFeatures = null,
featureColor = null,
inputFor = defaultInputFor,
projectToWindow = (viewer, position) =>
findQuery(viewer)?.project(position) ?? null,
@@ -536,12 +550,17 @@ export function createLocalGeoJsonLayer(
selectEntityContext,
clearSelectedEntityContextForLayer,
removeEntityContextsForLayer,
getSelectedEntityContext = null,
governorRequestRender,
showOsmCredit,
hideOsmCredit,
},
) {
const setPrefix = `${id}:${++layerInstances}`;
/** Builds made so far: each draws under set ids of its own. */
let builds = 0;
/** Bumped by each `replaceFeatures`, so only the latest one swaps in. */
let replacements = 0;
/** The pins its points stand on, one image per distinct marker. */
const pinMaker = createGeojsonPins();
/** What this layer draws while built: its sets and parts, or null. */
@@ -652,6 +671,12 @@ export function createLocalGeoJsonLayer(
host: overlayHost,
});
/** Register the context of each record a build made. */
function registerContexts(records) {
for (const record of records)
registerEntityContext(record.carrier, record.context);
}
/** Let go of every set a build made. */
function disposeSets(sets) {
for (const set of Object.values(sets)) {
@@ -708,24 +733,38 @@ export function createLocalGeoJsonLayer(
* Build the sets for the parsed features: a fill for each polygon, a
* draped line for each line, a pin for each point, and a stem and its dot
* for each polygon and point. Hidden until the enable finishes, as the
* loader's data source was.
* loader's data source was. Each record's context is made here and
* registered by the caller once the build has succeeded.
*/
function buildDrawn(viewer, features) {
const draw = drawOf(viewer);
const rgba = cssColor(color) ?? [1, 1, 1, 1];
const fillColor = [rgba[0], rgba[1], rgba[2], FILL_ALPHA];
// An optional per-feature colour (Data Library colorBy): its CSS value
// and RGBA, one per distinct value.
const colors = new Map();
const colorOf = (properties) => {
const css =
(typeof featureColor === 'function' && featureColor(properties)) ||
color;
if (css === color) return { css, rgba };
if (!colors.has(css)) colors.set(css, { css, rgba: cssColor(css) });
const found = colors.get(css);
return found.rgba ? found : { css: color, rgba };
};
const parts = localGeojsonParts(features);
const sets = {};
const built = { sets, parts: new Map(), records: [], count: parts.length };
const prefix = `${setPrefix}:${++builds}`;
try {
sets.fills = draw.shapes({ id: `${setPrefix}:fills`, show: false });
sets.fills = draw.shapes({ id: `${prefix}:fills`, show: false });
// Raised polygons apart: a ground fill showing or hiding changes in
// place only in a set of ground fills.
sets.raised = draw.shapes({ id: `${setPrefix}:raised`, show: false });
sets.lines = draw.lines({ id: `${setPrefix}:lines`, show: false });
sets.pins = draw.icons({ id: `${setPrefix}:pins`, show: false });
sets.stems = draw.lines({ id: `${setPrefix}:stems`, show: false });
sets.dots = draw.points({ id: `${setPrefix}:dots`, show: false });
sets.raised = draw.shapes({ id: `${prefix}:raised`, show: false });
sets.lines = draw.lines({ id: `${prefix}:lines`, show: false });
sets.pins = draw.icons({ id: `${prefix}:pins`, show: false });
sets.stems = draw.lines({ id: `${prefix}:stems`, show: false });
sets.dots = draw.points({ id: `${prefix}:dots`, show: false });
const fills = [];
const lines = [];
@@ -757,6 +796,7 @@ export function createLocalGeoJsonLayer(
continue;
}
const own = colorOf(properties);
let lon;
let lat;
if (part.kind === 'polygon') {
@@ -774,7 +814,11 @@ export function createLocalGeoJsonLayer(
}))
: rhumbPositions(ring),
);
part.fill = fillOf(style, fillColor);
// A feature colour of its own fills it, over its simplestyle fill.
part.fill =
own.rgba === rgba
? fillOf(style, fillColor)
: withAlpha(own.rgba, FILL_ALPHA);
// The stem stands on the centre of the outer ring's bounding
// sphere, carried to the surface.
const center = toLonLatH(
@@ -791,7 +835,7 @@ export function createLocalGeoJsonLayer(
lat = part.coordinates[1];
part.pinClamped = part.coordinates.length <= 2;
part.pinPos = { lon, lat };
const marker = markerOf(style, rgba);
const marker = markerOf(style, own.rgba);
part.pin = pinMaker.pin({
...marker,
symbol: style?.['marker-symbol'],
@@ -818,6 +862,7 @@ export function createLocalGeoJsonLayer(
lastGroundSampleMs: 0,
priority,
properties,
rgba: own.rgba,
visible: true,
entry: labels
? createLocalInfrastructureOverlayEntry({
@@ -826,9 +871,22 @@ export function createLocalGeoJsonLayer(
position: tip,
properties,
priority,
accent: color,
accent: own.css,
})
: null,
context: {
id: `${id}:${recordId}`,
layerId: id,
layerName: name,
source,
label: featureLabelFromProperties(properties, id),
properties,
latitude: Number(lat.toFixed(6)),
longitude: Number(lon.toFixed(6)),
// The surface base voice targeting projects. Ground sampling
// re-grounds it in place, so this stays current.
targetPosition: base,
},
};
carrier.record = record;
// A context record is active while its feature shows.
@@ -836,34 +894,20 @@ export function createLocalGeoJsonLayer(
get: () => record.visible,
enumerable: true,
});
registerEntityContext(carrier, {
id: `${id}:${recordId}`,
layerId: id,
layerName: name,
source,
label: featureLabelFromProperties(properties, id),
properties,
latitude: Number(lat.toFixed(6)),
longitude: Number(lon.toFixed(6)),
// The surface base voice targeting projects. Ground sampling
// re-grounds it in place, so this stays current.
targetPosition: base,
});
built.records.push(record);
if (part.kind === 'polygon') fills.push(fillItem(record, rgba));
if (part.kind === 'polygon') fills.push(fillItem(record));
else pins.push(pinItem(record));
}
sets.fills.set(fills.filter((item) => item.height === 'clampGround'));
sets.raised.set(fills.filter((item) => item.height !== 'clampGround'));
sets.lines.set(lines);
sets.pins.set(pins);
sets.stems.set(built.records.map((record) => stemItem(record, rgba)));
sets.dots.set(built.records.map((record) => dotItem(record, rgba)));
sets.stems.set(built.records.map(stemItem));
sets.dots.set(built.records.map(dotItem));
} catch (error) {
disposeSets(sets);
throw error;
}
built.rgba = rgba;
return built;
}
@@ -875,18 +919,14 @@ export function createLocalGeoJsonLayer(
function writeChanges(drawn, moved, shown) {
if (!moved.size && !shown.size) return;
const stems = new Set([...moved, ...shown]);
drawn.sets.stems.upsert(
[...stems].map((record) => stemItem(record, drawn.rgba)),
);
drawn.sets.dots.upsert(
[...stems].map((record) => dotItem(record, drawn.rgba)),
);
drawn.sets.stems.upsert([...stems].map(stemItem));
drawn.sets.dots.upsert([...stems].map(dotItem));
const fills = [];
const pins = [];
for (const record of stems) {
const { kind, pinClamped } = record.part;
if (!shown.has(record) && (kind !== 'point' || pinClamped)) continue;
if (kind === 'polygon') fills.push(fillItem(record, drawn.rgba));
if (kind === 'polygon') fills.push(fillItem(record));
else pins.push(pinItem(record));
}
const ground = fills.filter((item) => item.height === 'clampGround');
@@ -1091,7 +1131,17 @@ export function createLocalGeoJsonLayer(
_error = null;
try {
let features = _cachedFeatures;
if (!features) {
if (!features && loadFeatures) {
// A caller-owned loader (the Data Library) fetches and bounds
// its own live dataset; this layer only draws it.
features = await loadFeatures({
signal: _loadController.signal,
});
if (_destroyed) return;
if (!Array.isArray(features))
throw new Error('dataset unavailable');
_cachedFeatures = features;
} else if (!features) {
const response = await fetch(url, {
signal: _loadController.signal,
});
@@ -1113,6 +1163,12 @@ export function createLocalGeoJsonLayer(
});
if (_destroyed) return;
const built = buildDrawn(viewer, features);
try {
registerContexts(built.records);
} catch (error) {
disposeSets(built.sets);
throw error;
}
_count = built.count;
_stemRecords = built.records;
_stemGeometryDirty = true;
@@ -1392,6 +1448,124 @@ export function createLocalGeoJsonLayer(
disable: disableLayer,
/**
* Forget the parsed features so the next enable() loads them again: a
* caller-owned live loader (the Data Library) uses it once its data is
* older than the source allows.
*/
dropCachedFeatures: () => {
_cachedFeatures = null;
},
/**
* Draw a new feature set in place of the current one while the layer is
* on (a live loader's refresh). The current features stay drawn until
* the new ones are built; a selected feature stays selected when the new
* set still has it (same id, or same place and label); a failed rebuild
* keeps the current features and rejects. Off, the set is only kept for
* the next enable().
* @param {object} viewer
* @param {object[]} features GeoJSON features.
*/
replaceFeatures: async (viewer, features) => {
if (_destroyed) return;
const previousFeatures = _cachedFeatures;
_cachedFeatures = features;
if (!_enabled || !_drawn || _loadPromise) return;
const token = ++replacements;
const outgoing = _drawn;
// Still the replacement to make: on, not rebuilt or replaced meanwhile.
const current = () =>
!_destroyed &&
_enabled &&
_drawn === outgoing &&
token === replacements;
const selected = getSelectedEntityContext?.();
const selectedHere = selected?.layerId === id ? selected : null;
let built;
try {
// The loader drew its pins' symbols before it finished loading.
await pinMaker.load(markerSymbols(features));
if (!current()) return;
built = buildDrawn(viewer, features);
registerContexts(built.records);
} catch (error) {
// `buildDrawn` let go of its own sets on a throw; a build whose
// contexts failed goes here, and the current records keep theirs.
if (built) {
disposeSets(built.sets);
try {
registerContexts(outgoing.records);
} catch {
/* the store is gone with them */
}
}
if (!current()) return;
if (_cachedFeatures === features) _cachedFeatures = previousFeatures;
throw new Error(localDatasetError(error));
}
// A record the new set still has keeps the height sampled under it.
const previous = new Map(
outgoing.records.map((record) => [record.id, record]),
);
for (const record of built.records) {
const old = previous.get(record.id);
if (
!old?.groundSampled ||
old.lon !== record.lon ||
old.lat !== record.lat
)
continue;
record.groundSampled = true;
setLocalGroundHeight(record, old.groundHeight);
}
// The selected feature in the new set: by its own id (a feature
// without one has an id by position, which names another feature
// once the set changes), else by place and label.
const match = selectedHere
? (built.records.find(
(record) =>
given(record.part.feature.id) &&
record.context.id === selectedHere.id,
) ??
built.records.find(
(record) =>
Math.abs(record.lon - selectedHere.longitude) < 1e-6 &&
Math.abs(record.lat - selectedHere.latitude) < 1e-6 &&
record.context.label === selectedHere.label,
))
: null;
// A follow of an old part ends with it, as a removed entity's did.
stopFollow(viewer);
_drawn = built;
_stemRecords = built.records;
_count = built.count;
_lastUpdate = Date.now();
_error = null;
// A fresh walk for the new records: LOD, stems and labels.
_stemGeometryDirty = true;
_lastVisibilityUpdate = Number.NEGATIVE_INFINITY;
_activeLodIds = new Set();
_lodGraceState = new Map();
_lastLodBudgetLimit = 0;
_lodComputed = false;
_lastLodProbeMs = Number.NEGATIVE_INFINITY;
_groundRetryArms = 0;
// The new set's contexts took the old ids: a selection it does not
// have must not land on whatever now holds its id.
if (match) selectEntityContext(match.carrier);
else if (selectedHere)
clearSelectedEntityContextForLayer(id, { evicted: true });
// Records the new set no longer has go with the old sets.
removeEntityContextsForLayer(id, {
retainIds: new Set(built.records.map((record) => record.context.id)),
});
for (const set of Object.values(built.sets)) set.show = true;
disposeSets(outgoing.sets);
findFrame(viewer)?.requestRender('local-geojson');
},
destroy: (viewer) => {
if (_destroyed) return;
_destroyed = true;
@@ -1417,10 +1591,10 @@ export function createLocalGeoJsonLayer(
/**
* A polygon's fill, showing as its record does: on the ground, or with
* per-position heights and outlined in the layer colour (`outline`), as
* the loader outlined every polygon.
* per-position heights and outlined in the feature's colour, as the loader
* outlined every polygon.
*/
const fillItem = (record, outline) =>
const fillItem = (record) =>
record.part.raised
? {
id: record.id,
@@ -1430,7 +1604,7 @@ const fillItem = (record, outline) =>
perPositionHeight: true,
},
fill: record.part.fill,
outline,
outline: record.rgba,
// The loader's outline was an outline geometry, whose width the
// default renderer clamps to what WebGL draws: 1 px on most
// browsers, whatever `stroke-width` says.
@@ -1463,13 +1637,13 @@ const pinItem = (record) => ({
show: record.visible,
});
/** A record's stem, from its base to its tip. */
const stemItem = (record, color) => ({
/** A record's stem, from its base to its tip, in the feature's colour. */
const stemItem = (record) => ({
id: record.id,
positions: [copy(record.base), copy(record.tip)],
widthPx: STEM_WIDTH_PX,
mode: '3d',
style: { kind: 'solid', color },
style: { kind: 'solid', color: record.rgba },
meta: record.carrier,
show: record.visible,
});
@@ -1478,11 +1652,11 @@ const stemItem = (record, color) => ({
* The dot on a record's tip, never depth-tested against the photoreal
* mesh: the walk's horizon test hides it behind the globe.
*/
const dotItem = (record, color) => ({
const dotItem = (record) => ({
id: record.id,
pos: copy(record.tip),
pixelSize: 10,
color,
color: record.rgba,
outlineColor: BLACK,
outlineWidth: 2,
disableDepthTest: Number.POSITIVE_INFINITY,
@@ -1695,6 +1869,10 @@ function labelPriorityFromProperties(props, layerId) {
if (props.output || tags['plant:output:electricity']) score += 120;
if (layerId === 'local-dams') score += 80;
if (layerId === 'local-datacenters') score += 60;
// Data Library features carry their manifest importance (0–600), below the
// named/unnamed gap so a rank never promotes an unnamed feature.
if (Number.isFinite(props.__gevRank))
score += Math.max(0, Math.min(600, props.__gevRank));
return score;
}
+3 -2
View File
@@ -3,9 +3,10 @@
Offline polygons with no network dependency. The voice-annotation resolver
(`src/data/naturalEarthRegions.js`) reads the named regions, so "outline the
Alps" resolves to the real range geometry; area annotations read the
countries, states and provinces (`src/data/adminBoundaries.js`); and the News
countries, states and provinces (`src/data/adminBoundaries.js`); the News
layer reads the countries and the disputed areas
(`server/providers/news/areas.js`).
(`server/providers/news/areas.js`); and Data Library imagery draws its
coverage outlines from the countries (`src/library/outlines.js`).
| File | Source dataset | Features |
|------|----------------|----------|
File diff suppressed because it is too large. Load diff
+11 -89
View File
@@ -1,73 +1,16 @@
/**
* Model-space visual centres measured from the shipped GLBs' scene-space AABBs.
* Model-space anchors on the aircraft layers' fleet models: where brackets
* and readouts sit (a model's visual centre) and where a tracked trail
* attaches (its aft-belly point, measured per model in fleetTrailAnchors.js
* and handed to the layers with each model's spec by fleetModels.js).
*
* Unlike the trail anchors below, these are stored in the placed model's
* own frame (the glTF axes already turned, see `gltfToPlacedAxes`), so the
* layer's ENU placement applies to them directly. Values remain in native model units; callers supply the scale
* the model is drawn at (`modelDrawnScale`), which the placement does not
* carry and which the pixel floor may raise above `scale`.
* Values are native model units in raw glTF axes; the trail anchors are
* turned into the placed model's frame here (`gltfToPlacedAxes`), so the
* layer's ENU placement applies to them. A fleet model's visual centre is its
* origin. Callers supply the scale the model is drawn at (`modelDrawnScale`),
* which the placement does not carry and which the pixel floor may raise
* above `scale`.
*/
const CENTERED_MODEL = Object.freeze([0, 0, 0]);
export const MODEL_VISUAL_CENTER_NATIVE = Object.freeze({
'/models/airplane.glb': CENTERED_MODEL,
'/models/jet.glb': CENTERED_MODEL,
});
/**
* Aft-belly trail attachment points, measured on each approved model's actual
* MESH SURFACE. Every bundled asset is baked to one convention (see
* aircraftClass.js): origin at the bbox centre, X = length with the NOSE at
* local −X, glTF Y = up (the placed frame's Z here).
*
* Each value is the point of the hull's CENTRELINE PROFILE (the y = 0 slice of
* the mesh) closest to that model's aft-belly AABB corner. Three things follow
* from that construction, and each is asserted rather than described in
* modelScale.test.mjs:
*
* ON THE HULL. This is the correction that matters. The previous round put
* the anchor ON the AABB corner itself, reasoning that an anchor aft of
* every vertex makes non-intersection geometric. It does — but an AABB
* corner is EMPTY SPACE, and on these airframes it is a long way from
* any of them: 4.80 m out for airplane.glb and 6.14 m for jet.glb in
* native units, which at the 450 m framing is a visible gap between the
* aircraft and the end of its own trail. The trail must terminate on the
* aeroplane, so the anchor is a surface point.
*
* AFT. The head segment is drawn from a point behind the aircraft to this
* anchor, so an anchor near the middle makes the segment enter at the
* tail and stop mid-fuselage — a line drawn through the airframe. These
* sit at 83–96 % of each model's aft extreme, on the aft-most hull the
* centreline has.
*
* BELOW. Nothing of the aircraft is lower than the anchor at or behind its
* own station, so the trail leaves from underneath the way a wake does
* rather than out of the roof. On most assets that is a frank belly
* point; on jet.glb the aft centreline profile has swept up into the
* tail cone by then, so the anchor sits just above the model's vertical
* centre (+0.13 native on a 5.63 m half-height) at the exhaust — which
* is where a fast jet's wake leaves it anyway.
*
* Y stays on the centreline — the profile is sliced at y = 0 rather than taking
* the nearest surface point in the round — so the attachment cannot drift
* screen-left or screen-right as the aircraft turns. (The unconstrained nearest
* point would put jet.glb's anchor 1.29 m off-axis.) Values are native model
* units; callers scale them by the model's drawn scale (`modelDrawnScale`).
*
* Locked against the shipped GLBs by modelScale.test.mjs, which re-reads the
* POSITION buffers and re-derives every property above — re-measure, never
* re-guess, when an asset changes.
*/
export const MODEL_TRAIL_ANCHOR_NATIVE = Object.freeze({
'/models/airplane.glb': Object.freeze([24.0879, -2.2163, 0]),
'/models/jet.glb': Object.freeze([18.9103, 0.1266, 0]),
'/models/bell206.glb': Object.freeze([5.2077, -0.0005, 0]),
'/models/c172.glb': Object.freeze([3.6816, -0.2425, 0]),
'/models/citation2.glb': Object.freeze([6.8804, -0.6136, 0]),
'/models/mq9.glb': Object.freeze([5.1951, -1.1516, 0]),
'/models/b789.glb': Object.freeze([30.1007, -3.4814, 0]),
'/models/atr72.glb': Object.freeze([12.9785, -1.2935, 0]),
});
/**
* How a model's raw glTF axes land in its placed frame, as the renderer
@@ -183,27 +126,6 @@ export function modelDrawnScale({
return capped(drawn);
}
/**
* Return the model-local visual centre for an approved bundled GLB.
* Assets absent from the table were audited as origin-centred.
* @param {string} url Bundled model URL.
* @returns {readonly number[]} Placed-frame `[x, y, z]` native-unit offset.
*/
export function visualCenterForModel(url) {
return MODEL_VISUAL_CENTER_NATIVE[url] || CENTERED_MODEL;
}
/**
* Return the model-local aft-belly attachment point for a tracked trail.
* Unknown future assets safely fall back to their visual centre until their
* geometry is measured and added to the table.
* @param {string} url Bundled model URL.
* @returns {readonly number[]} Placed-frame `[x, y, z]` native-unit offset.
*/
export function trailAnchorForModel(url) {
return MODEL_TRAIL_ANCHOR_NATIVE[url] || visualCenterForModel(url);
}
/**
* Where a trail head segment should START being drawn: the whole segment, a
* shortened piece of it, or nothing at all.
@@ -220,7 +142,7 @@ export function trailAnchorForModel(url) {
* mistake matters:
*
* - Testing segment LENGTH against the radius hid real trail. With
* `airplane.glb`'s 34.41 m radius and 24.09 m tail anchor, a prior fix 58 m
* an airliner model's 34.41 m radius and 24.09 m tail anchor, a prior fix 58 m
* aft gives a 33.98 m segment — under the radius, so suppressed — even
* though ~23.6 m of it is in open air behind the aircraft. It also made the
* whole segment pop in at once on crossing ~58.4 m.
+135
View File
@@ -0,0 +1,135 @@
/**
* @module openVesselPhoto
* @description Reads an Open Vessel Photos answer into the one photo every
* surface shows. Open Vessel Photos (https://openvesselphotos.org) serves a
* free, keyless JSON and image API by MMSI. Every photo keeps the open licence
* its author chose (CC BY, CC BY-SA, CC0 or public domain), so it is shown
* with its credit and licence and links back to the vessel's page. A photo
* whose image is not on Open Vessel Photos' own host, or whose answer names
* no licence, is "no photo": nothing arbitrary is ever shown or linked.
*
* Accepts the upstream answer (`GET https://openvesselphotos.org/v1/mmsi/{mmsi}`,
* `{mmsi, photos: [...]}`) and an already-read photo
* (`{found, src, width, height, photographer, licence, link}`).
* Pure: no fetch, no DOM.
*/
/** The only host a photo may come from or link to. */
const HOST = 'openvesselphotos.org';
/** The API's per-vessel answer. */
const API = `https://${HOST}/v1/mmsi/`;
/** The image width asked for: sharp in the panel on a 2× screen, ~60 KB. */
const IMAGE_SIZE = '800';
const NO_PHOTO = Object.freeze({ found: false });
/** A vessel's MMSI: nine digits. */
export const MMSI = /^\d{9}$/;
/** The API answer for one MMSI. */
export function openVesselPhotosUrl(mmsi) {
return API + mmsi;
}
/** The vessel's page on Open Vessel Photos. */
function vesselPage(mmsi) {
return `https://${HOST}/vessels/mmsi/${mmsi}`;
}
/** The parsed `https:` URL on the Open Vessel Photos host, or null. */
function ownUrl(value) {
if (typeof value !== 'string' || !value) return null;
let url;
try {
url = new URL(value);
} catch {
return null;
}
return url.protocol === 'https:' &&
!url.username &&
!url.password &&
!url.port &&
url.hostname === HOST
? url
: null;
}
function dimension(value) {
const number = Number(value);
return value != null && Number.isFinite(number) && number > 0
? Math.round(number)
: null;
}
function text(value) {
return typeof value === 'string' ? value.trim() : '';
}
/** One upstream photo of the vessel `mmsi`, checked. */
function checkedUpstream(photo, mmsi) {
if (!photo || typeof photo !== 'object') return null;
const image = ownUrl(photo.urls?.mmsi);
const licence = text(photo.licenceName) || text(photo.licence);
if (!image || !licence) return null;
image.search = '';
image.hash = '';
image.searchParams.set('size', IMAGE_SIZE);
// The answer gives the full image's size; the 800 px one keeps its shape.
const width = dimension(photo.width);
const height = dimension(photo.height);
const scale =
width && width > Number(IMAGE_SIZE) ? Number(IMAGE_SIZE) / width : 1;
return {
found: true,
src: image.href,
width: width ? Math.round(width * scale) : null,
height: height ? Math.round(height * scale) : null,
photographer: text(photo.credit),
licence,
link: vesselPage(mmsi),
};
}
/** An already-read photo, checked again. */
function checkedRead(photo) {
const image = ownUrl(photo.src);
const page = ownUrl(photo.link);
const licence = text(photo.licence);
if (!image || !page || !licence) return null;
return {
found: true,
src: image.href,
width: dimension(photo.width),
height: dimension(photo.height),
photographer: text(photo.photographer),
licence,
link: page.href,
};
}
/**
* Read an Open Vessel Photos answer into the first photo that passes the
* checks.
* @param {*} payload Upstream answer or already-read photo.
* @param {?string} [requestedMmsi] The MMSI asked for; an upstream answer
* naming another is no photo.
* @returns {{found: true, src: string, width: ?number, height: ?number,
* photographer: string, licence: string, link: string} | {found: false}}
*/
export function parseOpenVesselPhoto(payload, requestedMmsi = null) {
if (!payload || typeof payload !== 'object') return NO_PHOTO;
if (Array.isArray(payload.photos)) {
const mmsi = String(payload.mmsi ?? '');
if (!MMSI.test(mmsi)) return NO_PHOTO;
// An answer about another vessel is no photo of this one.
if (requestedMmsi != null && mmsi !== String(requestedMmsi))
return NO_PHOTO;
for (const photo of payload.photos) {
const checked = checkedUpstream(photo, mmsi);
if (checked) return checked;
}
return NO_PHOTO;
}
if (payload.found !== true) return NO_PHOTO;
return checkedRead(payload) || NO_PHOTO;
}
+120
View File
@@ -0,0 +1,120 @@
// src/data/openVesselPhoto.test.mjs — an Open Vessel Photos answer is read
// into one credited, licensed photo, and nothing outside Open Vessel Photos'
// own host is ever shown or linked.
import test from 'node:test';
import assert from 'node:assert/strict';
import {
openVesselPhotosUrl,
parseOpenVesselPhoto,
} from './openVesselPhoto.js';
const UPSTREAM = Object.freeze({
mmsi: '366999709',
name: '01 USCGC Sockeye WPB87337',
photos: [
{
n: 1,
urls: {
cfr: null,
mmsi: 'https://openvesselphotos.org/v1/mmsi/366999709/photos/1.jpg',
},
credit: 'Gordon Leggett',
licence: 'CC-BY-4.0',
licenceName: 'CC BY 4.0',
width: 1600,
height: 1200,
},
],
});
const PHOTO = Object.freeze({
found: true,
src: 'https://openvesselphotos.org/v1/mmsi/366999709/photos/1.jpg?size=800',
width: 800,
height: 600,
photographer: 'Gordon Leggett',
licence: 'CC BY 4.0',
link: 'https://openvesselphotos.org/vessels/mmsi/366999709',
});
const withPhoto = (overrides) => ({
...UPSTREAM,
photos: [{ ...UPSTREAM.photos[0], ...overrides }],
});
test('the upstream answer maps to the 800 px image, its credit, licence and page', () => {
assert.deepEqual(parseOpenVesselPhoto(UPSTREAM), PHOTO);
assert.equal(
openVesselPhotosUrl('366999709'),
'https://openvesselphotos.org/v1/mmsi/366999709',
);
});
test('an image narrower than 800 px keeps its own size', () => {
const photo = parseOpenVesselPhoto(withPhoto({ width: 640, height: 480 }));
assert.equal(photo.width, 640);
assert.equal(photo.height, 480);
});
test('an already-read photo passes through its checks again', () => {
assert.deepEqual(parseOpenVesselPhoto(PHOTO), PHOTO);
assert.deepEqual(parseOpenVesselPhoto({ ...PHOTO, licence: '' }), {
found: false,
});
});
test('a photo off the Open Vessel Photos host, or without a licence, is no photo', () => {
for (const overrides of [
{ urls: { mmsi: 'https://example.com/1.jpg' } },
{
urls: {
mmsi: 'http://openvesselphotos.org/v1/mmsi/366999709/photos/1.jpg',
},
},
{ urls: { mmsi: 'https://openvesselphotos.org.evil.com/1.jpg' } },
{ urls: { mmsi: 'https://[email protected]/1.jpg' } },
{ licence: '', licenceName: '' },
])
assert.deepEqual(parseOpenVesselPhoto(withPhoto(overrides)), {
found: false,
});
assert.deepEqual(
parseOpenVesselPhoto({ ...PHOTO, link: 'https://example.com/' }),
{ found: false },
);
});
test('a vessel without photos, or an answer with a bad MMSI, is no photo', () => {
assert.deepEqual(parseOpenVesselPhoto({ ...UPSTREAM, photos: [] }), {
found: false,
});
assert.deepEqual(parseOpenVesselPhoto({ ...UPSTREAM, mmsi: '12/../x' }), {
found: false,
});
assert.deepEqual(parseOpenVesselPhoto(null), { found: false });
});
test('the next photo stands in when the first fails its checks', () => {
const second = {
...UPSTREAM.photos[0],
n: 2,
urls: {
mmsi: 'https://openvesselphotos.org/v1/mmsi/366999709/photos/2.jpg',
},
};
const photo = parseOpenVesselPhoto({
...UPSTREAM,
photos: [{ ...UPSTREAM.photos[0], licenceName: '', licence: '' }, second],
});
assert.equal(
photo.src,
'https://openvesselphotos.org/v1/mmsi/366999709/photos/2.jpg?size=800',
);
});
test('an answer about another vessel than the one asked for is no photo', () => {
assert.deepEqual(parseOpenVesselPhoto(UPSTREAM, '366999709'), PHOTO);
assert.deepEqual(parseOpenVesselPhoto(UPSTREAM, '227000101'), {
found: false,
});
});
File diff suppressed because it is too large. Load diff
+491
View File
@@ -0,0 +1,491 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
RAIL_CATEGORIES,
RAIL_ENABLED_FEEDS,
RAIL_FEED_ID_PATTERN,
RAIL_FEED_REGISTRY,
RAIL_MODES,
RAIL_POSITION_SOURCES,
classifyTrain,
getRailFeed,
getRegisteredRailFeed,
isRailFeedPollable,
publicRailCatalog,
railEnabledFeeds,
railFeedPositions,
railFeedsInRange,
} from './railFeeds.js';
const isHttps = (url) => new URL(url).protocol === 'https:';
test('every registered feed is complete, https and uniquely named', () => {
const ids = new Set();
for (const feed of RAIL_FEED_REGISTRY) {
assert.match(feed.id, RAIL_FEED_ID_PATTERN, feed.id);
assert.ok(!ids.has(feed.id), `duplicate id ${feed.id}`);
ids.add(feed.id);
const positions = railFeedPositions(feed);
assert.ok(RAIL_POSITION_SOURCES.includes(positions), feed.id);
assert.ok(isHttps(feed.url), feed.id);
for (const url of [feed.tripUpdatesUrl, feed.staticGtfsUrl])
if (url !== undefined) assert.ok(isHttps(url), `${feed.id} ${url}`);
assert.ok(
['gtfs-rt', 'irish-rail-xml', 'siri-vm'].includes(feed.format),
feed.id,
);
if (feed.format === 'irish-rail-xml')
assert.equal(positions, 'event', `${feed.id} positions are events`);
for (const key of ['name', 'operator', 'region', 'license', 'attribution'])
assert.ok(feed[key], `${feed.id} has ${key}`);
assert.ok(URL.canParse(feed.licenseUrl), `${feed.id} licence url`);
assert.equal(typeof feed.defaultEnabled, 'boolean', feed.id);
assert.equal(typeof feed.terms?.quote, 'string', feed.id);
assert.equal(typeof feed.classify, 'function', feed.id);
assert.ok(
Number.isFinite(feed.center.lat) && Number.isFinite(feed.center.lon),
);
assert.ok(feed.loadRadiusKm > 0 && feed.loadRadiusKm <= 1000, feed.id);
for (const ms of [feed.pollIntervalMs, feed.tripUpdatesIntervalMs])
if (ms !== undefined) assert.ok(ms >= 5_000 && ms <= 300_000, feed.id);
}
});
// The fields the registry documents (railFeeds.js, RAIL_FEED_REGISTRY):
// an entry carries nothing else, so no feed asks for a key, a sign-in or a
// timetable to place its trains.
const REGISTRY_FIELDS = new Set([
'id',
'name',
'operator',
'region',
'center',
'loadRadiusKm',
'format',
'url',
'positions',
'headers',
'headerClock',
'speedUnit',
'pollIntervalMs',
'tripUpdatesUrl',
'tripUpdatesIntervalMs',
'maxBodyBytes',
'limits',
'routesFrom',
'positionsByTrainNumber',
'staticGtfsUrl',
'staticGtfsEntry',
'staticHeaders',
'staticRouteTypes',
'staticTripEnds',
'staticSimplifyM',
'staticRouteRename',
'staticTripRename',
'license',
'licenseUrl',
'attribution',
'defaultEnabled',
'terms',
'classify',
]);
test('every feed reports live positions: GPS or signalling events', () => {
for (const feed of RAIL_FEED_REGISTRY) {
assert.notEqual(feed.positions, 'schedule', feed.id);
assert.ok(
['gps', 'event'].includes(railFeedPositions(feed)),
`${feed.id} positions`,
);
assert.equal(typeof feed.url, 'string', `${feed.id} has a live feed`);
}
for (const entry of publicRailCatalog())
assert.ok(['gps', 'event'].includes(entry.positions), entry.id);
});
/** Query parameter names that carry a key, a token or a signature. */
const ACCESS_PARAM =
/^(api[-_]?key|appid|app[-_]?key|key|token|access[-_]?token|auth|sig|signature|subscription[-_]?key)$/i;
/** `name=value` of each access parameter in a URL (values decoded). */
function accessParams(url) {
if (!url) return [];
return [...new URL(url).searchParams]
.filter(([name]) => ACCESS_PARAM.test(name))
.map(([name, value]) => `${name}=${value}`);
}
// The only access parameter allowed, a fixed public value the publisher
// prints in the published link for everyone, the same for every user and not
// a credential of the deployer's: Bordeaux Métropole's TBM `apiKey` (on the
// dataset page).
const PUBLISHED_ACCESS_VALUES = new Set([
'tbm-bordeaux apiKey=opendata-bordeaux-metropole-flux-gtfs-rt',
]);
test('an access parameter in a feed URL is found, whatever its spelling', () => {
for (const url of [
'https://x.test/a?apiKey=1',
'https://x.test/a?api_key=1',
'https://x.test/a?APIKEY=1',
'https://x.test/a?f=pb&key=1',
'https://x.test/a?token=1',
'https://x.test/a?access_token=1',
'https://x.test/a?sr=b&sig=abc%3D',
'https://x.test/a?signature=1',
'https://x.test/a?subscription-key=1',
])
assert.equal(accessParams(url).length, 1, url);
assert.deepEqual(accessParams('https://x.test/a?format=pb&route=key'), []);
assert.deepEqual(accessParams(null), []);
// Each published value is still in use, so the allow-list cannot go stale.
const used = new Set();
for (const feed of RAIL_FEED_REGISTRY)
for (const url of [feed.url, feed.tripUpdatesUrl, feed.staticGtfsUrl])
for (const param of accessParams(url)) used.add(`${feed.id} ${param}`);
assert.deepEqual([...used].sort(), [...PUBLISHED_ACCESS_VALUES].sort());
});
test('every feed is on, credited with its licence and terms, and fetched as published', () => {
const ids = new Set();
for (const feed of RAIL_FEED_REGISTRY) {
assert.ok(!ids.has(feed.id), `duplicate id ${feed.id}`);
ids.add(feed.id);
assert.equal(feed.defaultEnabled, true, `${feed.id} is on`);
for (const field of Object.keys(feed))
assert.ok(REGISTRY_FIELDS.has(field), `${feed.id}: ${field}`);
assert.ok(typeof feed.license === 'string' && feed.license, feed.id);
assert.ok(isHttps(feed.licenseUrl), `${feed.id} licence url`);
assert.ok(
typeof feed.attribution === 'string' && feed.attribution,
feed.id,
);
assert.equal(typeof feed.terms?.quote, 'string', `${feed.id} terms`);
assert.ok(feed.terms.quote || feed.terms.note, `${feed.id} terms basis`);
// No URL carries an access parameter, but for the fixed public values
// their publishers print for everyone (PUBLISHED_ACCESS_VALUES).
for (const url of [feed.url, feed.tripUpdatesUrl, feed.staticGtfsUrl])
for (const param of accessParams(url))
assert.ok(
PUBLISHED_ACCESS_VALUES.has(`${feed.id} ${param}`),
`${feed.id} ${url}`,
);
}
assert.equal(ids.size, RAIL_FEED_REGISTRY.length);
assert.deepEqual(
RAIL_ENABLED_FEEDS.map((feed) => feed.id),
RAIL_FEED_REGISTRY.map((feed) => feed.id),
);
});
test('a feed is switched on only when its terms were read and quoted', () => {
for (const feed of RAIL_ENABLED_FEEDS) {
assert.ok(
feed.terms.quote || feed.terms.note,
`${feed.id} is enabled without a recorded basis`,
);
}
// Tri-Rail states no licence; it is used without one by project owner
// decision, and the terms say so.
const triRail = getRailFeed('tri-rail');
assert.ok(triRail, 'tri-rail is pollable');
assert.ok(
triRail.terms.note.startsWith(
'Used without a published licence (project owner decision, 2026-11-10)',
),
);
assert.match(triRail.license, /^No licence stated/);
});
test('only enabled, well-formed ids resolve to a pollable feed', () => {
assert.equal(getRailFeed('mta-metro-north')?.id, 'mta-metro-north');
for (const id of ['', 'Nope', '../x', 'a', null, 42, 'unknown-feed'])
assert.equal(getRailFeed(id), null, String(id));
const mbta = getRegisteredRailFeed('mbta-rail');
assert.equal(isRailFeedPollable(mbta), true);
assert.equal(isRailFeedPollable({ ...mbta, defaultEnabled: false }), false);
assert.deepEqual(
railEnabledFeeds().map((entry) => entry.id),
RAIL_ENABLED_FEEDS.map((entry) => entry.id),
);
});
test('classifiers keep trains and drop buses in mixed feeds', () => {
const kind = (id, route) => classifyTrain(getRegisteredRailFeed(id), route);
assert.deepEqual(kind('mbta-rail', 'CR-Worcester'), {
category: 'local',
mode: 'rail',
});
assert.equal(kind('mbta-rail', 'Red').mode, 'metro');
assert.equal(kind('mbta-rail', 'Green-E').mode, 'tram');
assert.equal(kind('mbta-rail', 'Mattapan').category, 'transit');
assert.equal(kind('mbta-rail', '1'), null);
assert.equal(kind('mbta-rail', 'Boat-F1'), null);
assert.equal(kind('mbta-rail', 'Shuttle-Generic'), null);
assert.equal(kind('mbta-rail', null), null);
assert.equal(kind('rtd-denver-rail', 'A').category, 'local');
assert.equal(kind('rtd-denver-rail', '113G').category, 'local');
assert.equal(kind('rtd-denver-rail', '117N').category, 'local');
assert.equal(kind('rtd-denver-rail', '101E').category, 'transit');
assert.equal(kind('rtd-denver-rail', '107R').category, 'transit');
assert.equal(kind('rtd-denver-rail', '15'), null);
assert.equal(kind('rtd-denver-rail', '15L'), null);
assert.equal(kind('capmetro-rail', '550').category, 'local');
assert.equal(kind('capmetro-rail', '801'), null);
// Northstar's old route id is a bus now and must not come back as a train.
assert.equal(kind('metrotransit-rail', '888'), null);
assert.equal(kind('metrotransit-rail', '902').mode, 'tram');
assert.equal(kind('septa-trolley', 'M1').mode, 'metro');
assert.equal(kind('septa-trolley', '17'), null);
assert.equal(kind('translink-seq-rail', 'BRCA-5').category, 'local');
assert.equal(kind('translink-seq-rail', '61-3'), null);
assert.equal(kind('adelaide-metro', 'SEAFRD').category, 'local');
assert.equal(kind('adelaide-metro', 'GLNELG').mode, 'tram');
assert.equal(kind('adelaide-metro', 'J1A'), null);
assert.equal(kind('mta-metro-north', null).category, 'local');
});
test('Irish Rail: DART and Commuter local, InterCity by province, Enterprise international', () => {
const kind = (code, route) =>
classifyTrain(getRegisteredRailFeed('irish-rail'), route, {
tripId: code,
})?.category ?? null;
assert.equal(kind('E244', 'Howth - Bray'), 'local');
assert.equal(kind('D822', 'Grand Canal Dock - Drogheda'), 'local');
assert.equal(kind('P571', 'Midleton - Cork'), 'local');
assert.equal(kind('A216', 'Dublin Heuston - Cork'), 'national');
assert.equal(kind('A720', 'Dublin Heuston - Galway'), 'national');
assert.equal(kind('B701', 'Galway - Dublin Heuston'), 'national');
assert.equal(kind('A308', 'Mallow - Tralee'), 'regional', 'both Munster');
assert.equal(kind('A606', 'Dublin Connolly - Rosslare Europort'), 'regional');
assert.equal(kind('A118', 'Dublin Connolly - Belfast'), 'international');
assert.equal(kind('A131', 'Belfast - Dublin Connolly'), 'international');
assert.equal(kind('A999', 'Nowhere - Elsewhere'), 'national');
assert.equal(kind('A999', null), 'national');
assert.equal(kind('not a code', 'Howth - Bray'), null);
assert.equal(kind(null, 'Howth - Bray'), null);
});
test('a classifier answer outside the known lists is treated as not a train', () => {
const feed = (answer) => ({ classify: () => answer });
assert.equal(
classifyTrain(feed({ category: 'express', mode: 'rail' })),
null,
);
assert.equal(classifyTrain(feed({ category: 'local', mode: 'bus' })), null);
assert.equal(classifyTrain(feed(null)), null);
assert.equal(classifyTrain({}), null);
assert.equal(classifyTrain(null), null);
for (const feed of RAIL_FEED_REGISTRY) {
for (const route of [
'CR-Lowell',
'A',
'550',
'901',
'T1',
'BRCA-5',
'GAW',
null,
]) {
const kind = feed.classify(route);
if (!kind) continue;
assert.ok(RAIL_CATEGORIES.includes(kind.category), `${feed.id} ${route}`);
assert.ok(RAIL_MODES.includes(kind.mode), `${feed.id} ${route}`);
}
}
});
test('coverage selection returns enabled feeds near the point, nearest first', () => {
const nyc = railFeedsInRange(40.75, -73.99).map((feed) => feed.id);
assert.ok(nyc.includes('mta-metro-north') && nyc.includes('mta-lirr'));
assert.deepEqual(railFeedsInRange(0, -150), []);
assert.deepEqual(railFeedsInRange(Number.NaN, 0), []);
const brisbane = railFeedsInRange(-27.47, 153.02);
assert.equal(brisbane[0].id, 'translink-seq-rail');
// The browser passes the server's catalog, which lists a feed that reads
// its routes from a schedule pack only once that pack is built.
const madrid = (built) =>
railFeedsInRange(
40.42,
-3.7,
0,
publicRailCatalog({ schedulePackBuilt: () => built }),
).map((feed) => feed.id);
assert.ok(
!madrid(false).includes('renfe-larga-distancia'),
'no pack: not offered',
);
assert.ok(madrid(false).includes('renfe-cercanias'), 'needs no pack');
assert.ok(madrid(true).includes('renfe-larga-distancia'));
assert.deepEqual(railFeedsInRange(-27.47, 153.02, 0, null), []);
assert.deepEqual(railFeedsInRange(-27.47, 153.02, 0, [{ id: 'x' }]), []);
});
test('the public catalog exposes coverage and credit but never upstream URLs', () => {
const catalog = publicRailCatalog();
assert.equal(catalog.length, RAIL_ENABLED_FEEDS.length);
for (const entry of catalog) {
assert.equal(entry.url, undefined);
assert.equal(entry.tripUpdatesUrl, undefined);
assert.equal(entry.headers, undefined);
assert.equal(entry.classify, undefined);
assert.ok(entry.attribution && entry.licenseUrl);
assert.ok(RAIL_POSITION_SOURCES.includes(entry.positions));
assert.equal(typeof entry.tripUpdates, 'boolean');
}
const byId = new Map(catalog.map((entry) => [entry.id, entry]));
assert.equal(byId.get('irish-rail').positions, 'event');
assert.equal(byId.get('irish-rail').tripUpdates, false);
assert.equal(byId.get('mbta-rail').positions, 'gps');
assert.equal(byId.get('mbta-rail').tripUpdates, true);
// No upstream URL reaches the browser, by any field but the licence link
// (an access point's page can be both the licence and the download).
const text = JSON.stringify(
catalog.map((entry) => ({ ...entry, licenseUrl: null })),
);
for (const feed of RAIL_FEED_REGISTRY)
for (const url of [feed.url, feed.tripUpdatesUrl, feed.staticGtfsUrl])
if (url) assert.ok(!text.includes(url), `${feed.id} ${url}`);
});
test('Finland: commuter local, H/HDM regional, long distance national, Haaparanta international', () => {
const kind = (route) =>
classifyTrain(getRegisteredRailFeed('fintraffic-vr'), route)?.category ??
null;
assert.equal(kind('EPO_HKI_E_HL_10'), 'local');
assert.equal(kind('SK_ÄHT_480_HDM_10'), 'regional');
assert.equal(kind('TPE_PRI_1_H_10'), 'regional');
for (const route of [
'HKI_ROI_23_IC_10',
'HKI_OL_45_S_10',
'HKI_KOK_101_P_10',
'HKI_KLI_265_PYO_10',
])
assert.equal(kind(route), 'national', route);
assert.equal(kind('OL_HPA_407_IC_10'), 'international');
assert.equal(kind('HPA_OL_408_IC_10'), 'international');
for (const route of ['HKI_TKU_1_T_10', 'IC 23', null])
assert.equal(kind(route), null, String(route));
});
test('Renfe: products and the autonomous-community rule', () => {
const feed = getRegisteredRailFeed('renfe-larga-distancia');
const kind = (route) => classifyTrain(feed, route)?.category ?? null;
for (const product of ['AVE', 'AVLO', 'ALVIA', 'EUROMED', 'Intercity'])
for (const scope of ['S', 'X'])
assert.equal(kind(`${product}~${scope}~1`), 'national', product);
for (const product of ['MD', 'REGIONAL', 'REG.EXP.', 'PROXIMDAD', 'AVANT']) {
assert.equal(kind(`${product}~S~1`), 'regional', product);
assert.equal(kind(`${product}~X~1`), 'national', product);
}
assert.equal(kind('AVE INT~X~1'), 'international');
assert.equal(kind('TRENCELTA~X~1'), 'international');
assert.equal(kind('MD~B~1'), 'international', 'an end abroad');
assert.equal(kind('BUS~S~1'), null);
assert.equal(kind('1700037606GL023'), null, 'an unscoped operator id');
assert.equal(kind(null), null);
// The rename the path build applies to routes.txt rows.
const places = {
17000: { lat: 40.47, lon: -3.68 },
37606: { lat: 38.89, lon: -6.98 },
18000: { lat: 40.41, lon: -3.7 },
87089: { lat: 43.3, lon: 5.38 },
};
const helpers = {
stop: (id) => places[id] ?? null,
stateAt: (lat) =>
lat > 43
? { country: 'FR', state: 'FR-13' }
: lat < 39.5
? { country: 'ES', state: 'ES-EX' }
: { country: 'ES', state: 'ES-MD' },
};
const rename = (id, product) =>
feed.staticRouteRename(
{ route_id: id, route_short_name: product },
helpers,
);
assert.equal(rename('1700037606GL023', 'MD'), 'MD~X~1700037606GL023');
assert.equal(
rename('1700018000GL001', 'REGIONAL'),
'REGIONAL~S~1700018000GL001',
);
assert.equal(rename('1700087089AV016', 'AVE'), 'AVE~B~1700087089AV016');
assert.equal(
rename('1700099999GL001', 'MD'),
'MD~X~1700099999GL001',
'unplaced',
);
assert.equal(rename('short', 'MD'), null);
assert.equal(
classifyTrain(getRegisteredRailFeed('renfe-cercanias'), null)?.category,
'local',
);
});
test('Norway: by line and county, replacement buses dropped, Flåmsbana a tourist line', () => {
const kind = (id, route, tripId = 'VYG:ServiceJourney:536_906310-R') =>
classifyTrain(getRegisteredRailFeed(id), route, { tripId });
assert.equal(kind('entur-vy', 'VYG:Line:F4')?.category, 'national');
assert.equal(kind('entur-vy', 'VYG:Line:RE11')?.category, 'national');
assert.equal(kind('entur-vy', 'VYG:Line:L1')?.category, 'local');
assert.equal(kind('entur-vy', 'VYG:Line:RE20')?.category, 'international');
assert.equal(kind('entur-vy', 'VYG:Line:F1')?.category, 'international');
assert.equal(kind('entur-vy', 'VYG:Line:R55')?.category, 'regional');
const flam = kind('entur-vy', 'VYG:Line:R45');
assert.equal(flam.category, 'regional');
assert.equal(flam.tourist, true);
assert.equal(kind('entur-go-ahead', 'GOA:Line:50')?.category, 'national');
assert.equal(kind('entur-go-ahead', 'GOA:Line:59')?.category, 'local');
assert.equal(kind('entur-flytoget', 'FLT:Line:FLY1')?.category, 'local');
assert.equal(kind('entur-sj-nord', 'SJN:Line:21')?.category, 'national');
assert.equal(kind('entur-sj-nord', 'SJN:Line:72')?.category, 'international');
assert.equal(kind('entur-sj-nord', 'SJN:Line:26')?.category, 'regional');
assert.equal(
kind('entur-vy', 'VYG:Line:RE11', 'VYG:ServiceJourney:BUS-836_761763-R'),
null,
'a replacement bus on a train line',
);
assert.equal(kind('entur-vy', 'VYG:Line:X99'), null);
assert.match(getRegisteredRailFeed('entur-sj-nord').terms.note, /missing/);
// Its positions come from SIRI VM, the timetable still gives its stops.
assert.equal(
railFeedPositions(getRegisteredRailFeed('entur-sj-nord')),
'gps',
);
assert.equal(getRegisteredRailFeed('entur-sj-nord').format, 'siri-vm');
});
test('feeds that read routes from their schedule pack can build one', () => {
for (const feed of RAIL_FEED_REGISTRY.filter((entry) => entry.routesFrom)) {
assert.equal(feed.routesFrom, 'schedule', feed.id);
assert.ok(isHttps(feed.staticGtfsUrl), feed.id);
}
for (const feed of RAIL_FEED_REGISTRY.filter((entry) => entry.headerClock))
assert.equal(feed.headerClock, 'untrusted', feed.id);
// Identify-yourself headers never carry a person.
for (const feed of RAIL_FEED_REGISTRY)
for (const value of Object.values({
...(feed.headers || {}),
...(feed.staticHeaders || {}),
}))
assert.ok(!/@/.test(value), feed.id);
});
test('a feed Transit also reads declares the same speed unit', async () => {
const { TRANSIT_FEED_REGISTRY } = await import('./transitFeeds.js');
const transitByUrl = new Map(
TRANSIT_FEED_REGISTRY.map((feed) => [feed.url, feed]),
);
let shared = 0;
for (const feed of RAIL_FEED_REGISTRY) {
const transit = transitByUrl.get(feed.url);
if (!transit) continue;
shared += 1;
assert.equal(feed.speedUnit, transit.speedUnit, feed.id);
}
assert.ok(shared > 0);
assert.equal(getRegisteredRailFeed('tam-montpellier').speedUnit, 'km/h');
});
+63
View File
@@ -0,0 +1,63 @@
// Asian feeds: Japan's live tram feeds (Manyōsen and Toyama), registered,
// switched on with their licence basis recorded, and sorted into
// categories.
import test from 'node:test';
import assert from 'node:assert/strict';
import {
RAIL_ENABLED_FEEDS,
classifyTrain,
getRailFeed,
getRegisteredRailFeed,
railFeedPositions,
railFeedsInRange,
} from './railFeeds.js';
const LIVE = ['jp-manyosen', 'jp-toyama-tram'];
const feed = (id) => getRegisteredRailFeed(id);
const kind = (id, routeId) => classifyTrain(feed(id), routeId);
const TRAM = { category: 'transit', mode: 'tram' };
test('the Japanese feeds are on, with their licence basis recorded', () => {
for (const id of LIVE) {
assert.ok(getRailFeed(id), `${id} is pollable`);
assert.ok(RAIL_ENABLED_FEEDS.includes(feed(id)), id);
assert.ok(feed(id).license, id);
assert.match(feed(id).licenseUrl, /^https:\/\//, id);
assert.ok(feed(id).attribution, id);
assert.ok(feed(id).terms.quote, `${id} quotes its terms`);
assert.match(feed(id).terms.note, /read 2026-11-10/, id);
assert.doesNotMatch(feed(id).terms.note, /@/, id);
assert.equal(railFeedPositions(feed(id)), 'gps', id);
assert.match(feed(id).url, /^https:\/\/gtfs-rt-files\.buscatch\.jp\//);
}
assert.equal(
feed('jp-toyama-tram').staticGtfsUrl,
undefined,
'its static GTFS codes the tram as buses',
);
});
test('Japan: the Manyōsen and Toyama trams are transit', () => {
assert.deepEqual(kind('jp-manyosen', '1'), TRAM);
assert.deepEqual(
kind('jp-toyama-tram', '富山港線(南富山)(3004-1)'),
TRAM,
'a route id seen live',
);
});
test('each Japanese tram feed is polled around its own city only', () => {
const near = (lat, lon) => railFeedsInRange(lat, lon).map((f) => f.id);
// Takaoka for the Manyōsen, Toyama station for the city tram.
assert.ok(near(36.75, 137.02).includes('jp-manyosen'));
assert.ok(near(36.7, 137.21).includes('jp-toyama-tram'));
// Tokyo and Nagoya are hundreds of kilometres off.
for (const [lat, lon] of [
[35.68, 139.77],
[35.17, 136.88],
])
for (const id of LIVE) assert.ok(!near(lat, lon).includes(id), id);
for (const id of LIVE) assert.ok(feed(id).loadRadiusKm <= 25, id);
});
+97
View File
@@ -0,0 +1,97 @@
// The rail counts the documents state, against the registry: how many feeds
// there are, how many publish GPS or station reports, how many work out of
// the box, register trip updates or have a static GTFS, and one
// DATA_SOURCES.md row per feed, none for a feed the registry does not hold.
import test from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import {
RAIL_ENABLED_FEEDS,
RAIL_FEED_REGISTRY,
railFeedNeedsSchedulePack,
railFeedPositions,
} from './railFeeds.js';
const read = (file) =>
readFileSync(new URL(`../../${file}`, import.meta.url), 'utf8');
const counts = {
registry: RAIL_FEED_REGISTRY.length,
gps: RAIL_FEED_REGISTRY.filter((feed) => railFeedPositions(feed) === 'gps')
.length,
stationReports: RAIL_FEED_REGISTRY.filter(
(feed) => railFeedPositions(feed) === 'event',
).length,
outOfTheBox: RAIL_ENABLED_FEEDS.filter(
(feed) => !railFeedNeedsSchedulePack(feed),
).length,
tripUpdates: RAIL_FEED_REGISTRY.filter(
(feed) => typeof feed.tripUpdatesUrl === 'string',
).length,
staticGtfs: RAIL_FEED_REGISTRY.filter(
(feed) => typeof feed.staticGtfsUrl === 'string',
).length,
};
test('the registry holds the feeds the documents count', () => {
assert.deepEqual(counts, {
registry: 30,
gps: 29,
stationReports: 1,
outOfTheBox: 28,
tripUpdates: 22,
staticGtfs: 29,
});
assert.equal(RAIL_ENABLED_FEEDS.length, counts.registry, 'all switched on');
assert.deepEqual(
RAIL_FEED_REGISTRY.filter(
(feed) => railFeedPositions(feed) === 'event',
).map((feed) => feed.id),
['irish-rail'],
'the station reports are Irish Rail’s',
);
});
test('DATA_SOURCES.md states the rail counts and has one row per feed', () => {
const sources = read('DATA_SOURCES.md');
const { registry, gps, outOfTheBox, tripUpdates, staticGtfs } = counts;
for (const phrase of [
`The registry lists ${registry} feeds, all switched on`,
`${gps} feeds publish live GPS positions (SJ Nord's through SIRI VM), and Irish Rail reports the station or timing point a train last passed`,
`${tripUpdates} feeds register trip updates`,
`${outOfTheBox} feeds work out of the box`,
`(${staticGtfs} of the ${registry} have one)`,
])
assert.ok(sources.includes(phrase), phrase);
const rows = sources
.split('\n')
.filter((line) => /^\| \*\*.+\| Rail layer trains, /.test(line));
assert.equal(rows.length, registry, 'one row per feed');
for (const feed of RAIL_FEED_REGISTRY)
assert.ok(
rows.some((row) => row.includes(`| Rail layer trains, ${feed.region}:`)),
`${feed.id} has a row`,
);
});
test('CURRENT-STATE.md states the rail counts', () => {
const state = read('docs/CURRENT-STATE.md');
const { registry, gps, outOfTheBox, tripUpdates, staticGtfs } = counts;
for (const phrase of [
`(${registry} keyless feeds, all on, ${outOfTheBox} out of the box;`,
`The registry lists ${registry} feeds, all`,
`a host that has built nothing shows ${outOfTheBox} feeds`,
`By position source, ${gps} feeds publish live GPS.`,
'Irish Rail publishes the\nstation or timing point the signalling last reported.',
`${tripUpdates} feeds register trip updates;`,
`that has a static GTFS (${staticGtfs} of the ${registry})`,
])
assert.ok(state.includes(phrase), phrase);
});
test('README.md states the rail counts', () => {
const readme = read('README.md');
const { registry, gps, outOfTheBox } = counts;
const phrase = `from ${registry} keyless operator feeds: live GPS positions from ${gps} of them and Irish Rail’s station reports, ${outOfTheBox} live out of the box`;
assert.ok(readme.includes(phrase), phrase);
});
+86
View File
@@ -0,0 +1,86 @@
// France (2026-11-10): the Bordeaux and Montpellier tram networks, from
// transport.data.gouv.fr. Registered, switched on with the dataset's licence
// field quoted, polled for live positions, and sorted into categories; no
// registry URL is on a download path its host's robots.txt disallows.
import test from 'node:test';
import assert from 'node:assert/strict';
import {
RAIL_FEED_REGISTRY,
classifyTrain,
getRailFeed,
getRegisteredRailFeed,
railFeedHasTripUpdates,
railFeedPositions,
} from './railFeeds.js';
const kind = (id, routeId) => {
const train = classifyTrain(getRegisteredRailFeed(id), routeId);
return train ? `${train.category}/${train.mode}` : null;
};
const FR_FEEDS = ['tbm-bordeaux', 'tam-montpellier'];
// ------------------------------------------------------------ registry
test('the French feeds are on and quote the dataset licence field', () => {
for (const id of FR_FEEDS) {
const feed = getRegisteredRailFeed(id);
assert.ok(feed, `${id} is registered`);
assert.ok(getRailFeed(id), `${id} is pollable`);
assert.equal(feed.defaultEnabled, true, id);
assert.match(feed.staticGtfsUrl, /^https:\/\//, id);
assert.ok(['lov2', 'odc-odbl', 'fr-lo'].includes(feed.terms.quote), id);
assert.match(feed.terms.note, /transport\.data\.gouv\.fr dataset "/, id);
assert.match(feed.terms.note, /2026-11-10/, id);
}
});
test('the ODbL dataset carries the share-alike note and the access point conditions', () => {
const feed = getRegisteredRailFeed('tam-montpellier');
assert.equal(feed.license, 'ODbL 1.0');
assert.match(feed.terms.note, /share-alike/);
assert.match(feed.terms.note, /dans le format d'origine/);
assert.equal(
getRegisteredRailFeed('tbm-bordeaux').license,
'Licence Ouverte / Open Licence 1.0',
);
});
test('positions: Bordeaux and Montpellier trams are GPS, with trip updates', () => {
for (const id of FR_FEEDS) {
assert.equal(railFeedPositions(getRegisteredRailFeed(id)), 'gps', id);
assert.ok(railFeedHasTripUpdates(getRegisteredRailFeed(id)), id);
}
});
// ------------------------------------------------------------ categories
test('tram lines are transit; buses are dropped', () => {
const cases = [
['tbm-bordeaux', '164', 'transit/tram'],
['tbm-bordeaux', '901', null],
['tam-montpellier', '5', 'transit/tram'],
['tam-montpellier', 'A', null],
];
for (const [id, route, expected] of cases)
assert.equal(kind(id, route), expected, `${id} ${route}`);
});
// ------------------------------------------------------------ download
// Hosts whose robots.txt disallows the download paths French publishers use.
const DISALLOWED = [
/^https:\/\/eu\.ftp\.opendatasoft\.com\//,
/^https:\/\/thello\.axelor\.com\//,
/^https:\/\/static\.data\.gouv\.fr\/resources\//,
/^https:\/\/www\.data\.gouv\.fr\/(fr\/)?(api\/1\/)?datasets\/r\//,
/\/explore\/dataset\/.*\/download/,
];
test('no registry URL is on a download path its robots.txt disallows', () => {
for (const feed of RAIL_FEED_REGISTRY)
for (const url of [feed.url, feed.tripUpdatesUrl, feed.staticGtfsUrl])
if (url)
for (const pattern of DISALLOWED)
assert.ok(!pattern.test(url), `${feed.id} ${url}`);
});
+103
View File
@@ -0,0 +1,103 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
RAIL_ENABLED_FEEDS,
classifyTrain,
getRailFeed,
getRegisteredRailFeed,
} from './railFeeds.js';
import {
railAdmissionGlobalMax,
railNaturalRequestsPerMinute,
} from './railProxy.js';
/** One end of a run, as the path build's `readTripEnds` writes it. */
const at = (name, country, state) => ({ name, country, state });
const ends = (
from,
to,
countries = [...new Set([from.country, to.country])],
) => ({ from, to, countries });
/**
* The category a timetable trip gets: the feed's route rename (when it has
* one), its trip rename with the run's ends, then its classifier on the pack
* route id, as the build and the browser apply them.
*/
function tripKind(feedId, route, run = null, trip = { trip_id: 't1' }) {
const feed = getRegisteredRailFeed(feedId);
const base =
(typeof feed.staticRouteRename === 'function'
? feed.staticRouteRename(route, { stop: () => null, stateAt: () => null })
: null) ?? route.route_id;
const id =
typeof feed.staticTripRename === 'function'
? feed.staticTripRename(trip, base, { ends: run })
: base;
return classifyTrain(feed, id, { tripId: trip.trip_id });
}
const category = (...args) => tripKind(...args)?.category ?? null;
test('the national feeds are on and quote their terms', () => {
for (const id of ['ktmb', 'entur-sj-nord']) {
assert.ok(getRailFeed(id), `${id} is pollable`);
assert.ok(getRegisteredRailFeed(id).terms.quote, `${id} quotes its terms`);
}
});
test('the admission cap grows with the KTMB and SJ Nord feeds', () => {
const before = RAIL_ENABLED_FEEDS.filter(
(feed) => !['ktmb', 'entur-sj-nord'].includes(feed.id),
);
assert.ok(
railNaturalRequestsPerMinute() > railNaturalRequestsPerMinute(before),
);
assert.ok(railAdmissionGlobalMax() >= railAdmissionGlobalMax(before));
});
test('KTMB: Komuter local, Shuttle Tebrau international, ETS and Intercity by state', () => {
const route = (id) => ({ route_id: id, route_type: '2' });
const kl = at('KL SENTRAL', 'MY', 'MY-14');
const jb = at('JB SENTRAL', 'MY', 'MY-01');
const tumpat = at('TUMPAT', 'MY', 'MY-03');
const guaMusang = at('GUA MUSANG', 'MY', 'MY-03');
// The simplified polygons put Padang Besar station in Thailand.
const padangBesar = at('PADANG BESAR', 'TH', 'TH-90');
const butterworth = at('BUTTERWORTH', 'MY', 'MY-07');
assert.equal(category('ktmb', route('KA15_KD19'), ends(kl, kl)), 'local');
assert.equal(category('ktmb', route('KC05_KB18')), 'local');
assert.equal(
category('ktmb', route('100_47300'), ends(butterworth, padangBesar)),
'local',
'Komuter Utara',
);
assert.equal(category('ktmb', { route_id: 'SS', route_type: '0' }), 'local');
assert.equal(category('ktmb', route('ST')), 'international');
assert.equal(category('ktmb', route('ETS'), ends(kl, jb)), 'national');
assert.equal(
category('ktmb', route('ETS'), ends(kl, padangBesar)),
'national',
'Padang Besar is in Perlis',
);
assert.equal(
category('ktmb', route('ETS'), ends(kl, at('HAT YAI', 'TH', 'TH-90'))),
'international',
);
assert.equal(
category(
'ktmb',
route('ERT'),
ends(at('MERAPOH', 'MY', 'MY-06'), at('WOODLANDS CIQ', 'SG', 'SG-03')),
),
'international',
);
assert.equal(
category('ktmb', route('SH'), ends(tumpat, guaMusang)),
'regional',
);
assert.equal(category('ktmb', route('SH')), 'national', 'ends unknown');
assert.equal(category('ktmb', route('BUS1'), ends(kl, jb)), null);
// The realtime vehicles carry no route: it comes from the schedule pack.
assert.equal(getRegisteredRailFeed('ktmb').routesFrom, 'schedule');
assert.equal(getRegisteredRailFeed('ktmb').pollIntervalMs, 30_000);
});
+46
View File
@@ -0,0 +1,46 @@
// Tri-Rail, South Florida's commuter line: switched on with its basis,
// polled for live positions, and sorted into categories by route or by
// train number.
import test from 'node:test';
import assert from 'node:assert/strict';
import {
RAIL_ENABLED_FEEDS,
classifyTrain,
getRailFeed,
getRegisteredRailFeed,
railFeedHasTripUpdates,
railFeedPositions,
} from './railFeeds.js';
const feed = (id) => getRegisteredRailFeed(id);
const kind = (id, routeId, context) =>
classifyTrain(feed(id), routeId, context);
test('Tri-Rail is on, with its basis', () => {
const tri = feed('tri-rail');
assert.ok(getRailFeed('tri-rail'), 'pollable');
assert.ok(RAIL_ENABLED_FEEDS.includes(tri));
assert.ok(tri.terms.quote, 'quotes its terms');
assert.ok(tri.terms.note, 'explains its basis');
// Used by project owner decision, which it says, naming no person.
assert.match(tri.terms.note, /\(project owner decision, 2026-11-10\)/);
assert.doesNotMatch(tri.terms.note, /@/);
});
test('Tri-Rail: live positions with trip updates, trains by route or train number', () => {
const tri = feed('tri-rail');
assert.equal(railFeedPositions(tri), 'gps');
assert.ok(railFeedHasTripUpdates(tri));
assert.equal(tri.staticGtfsUrl, 'https://gtfs.tri-rail.com/gtfs.zip');
const local = { category: 'local', mode: 'rail' };
// Pack routes: Mainline and Downtown Miami Link.
assert.deepEqual(kind('tri-rail', '1'), local);
assert.deepEqual(kind('tri-rail', '2'), local);
// The airport shuttle bus, should a route id ever reach the classifier.
assert.equal(kind('tri-rail', '4'), null);
// Realtime vehicles carry no route, only the train number.
assert.deepEqual(kind('tri-rail', null, { tripId: 'P617' }), local);
assert.deepEqual(kind('tri-rail', '', { tripId: 'P601X' }), local);
assert.equal(kind('tri-rail', null, { tripId: 'FLA Loop_T01' }), null);
assert.equal(kind('tri-rail', null, {}), null);
});
+62
View File
@@ -0,0 +1,62 @@
// A United States feed whose publisher states no terms (Charlotte LYNX):
// switched on with the reason recorded, and sorted into categories.
import test from 'node:test';
import assert from 'node:assert/strict';
import {
RAIL_ENABLED_FEEDS,
classifyTrain,
getRailFeed,
getRegisteredRailFeed,
railFeedHasTripUpdates,
railFeedPositions,
} from './railFeeds.js';
import { keepsRouteType } from '../../scripts/build-rail-paths.mjs';
// The feeds that publish no terms, used without a published licence by project
// owner decision of 2026-11-10.
const ON = ['charlotte-lynx'];
const BASIS =
'Publishes no terms; used without a published licence (project owner decision, 2026-11-10).';
const TRAM = { category: 'transit', mode: 'tram' };
const feed = (id) => getRegisteredRailFeed(id);
const kind = (id, routeId, context) =>
classifyTrain(feed(id), routeId, context);
test('the no-terms feed is on and says why', () => {
for (const id of ON) {
const entry = feed(id);
assert.ok(getRailFeed(id), `${id} is pollable`);
assert.ok(RAIL_ENABLED_FEEDS.includes(entry), id);
assert.equal(entry.license, 'No licence published', id);
assert.ok(entry.terms.note.startsWith(BASIS), id);
// Nothing personal in the recorded basis.
assert.doesNotMatch(entry.terms.note, /@/, id);
}
});
test('Charlotte LYNX: live light rail and streetcar with trip updates, buses dropped', () => {
const lynx = feed('charlotte-lynx');
assert.equal(railFeedPositions(lynx), 'gps');
assert.ok(railFeedHasTripUpdates(lynx));
assert.match(
lynx.staticGtfsUrl,
/^https:\/\/gtfsrealtime\.ridetransit\.org\//,
);
// Routes seen live on 2026-11-10: 501 Blue Line, 510 Gold Line, buses.
assert.deepEqual(kind('charlotte-lynx', '501'), TRAM);
assert.deepEqual(kind('charlotte-lynx', '510'), TRAM);
for (const bus of ['9', '22', '5', null])
assert.equal(kind('charlotte-lynx', bus), null, String(bus));
});
test('a listed staticRouteTypes is the whole list, so trains coded as buses build', () => {
assert.equal(keepsRouteType({}, '3'), false, 'a bus by default');
assert.equal(keepsRouteType({}, ' 2 '), true);
assert.equal(keepsRouteType({ staticRouteTypes: [3] }, '3'), true);
assert.equal(keepsRouteType({ staticRouteTypes: [3] }, '2'), false);
assert.equal(keepsRouteType({ staticRouteTypes: [0, 2] }, '0'), true);
assert.equal(keepsRouteType({ staticRouteTypes: [0, 2] }, '1'), false);
assert.equal(keepsRouteType({ staticRouteTypes: [3] }, ''), false);
});
+57
View File
@@ -0,0 +1,57 @@
// United States streetcar feeds (Seattle, Cincinnati): switched on with
// their basis, polled for live positions, and sorted into categories with
// the buses dropped.
import test from 'node:test';
import assert from 'node:assert/strict';
import {
RAIL_ENABLED_FEEDS,
classifyTrain,
getRailFeed,
getRegisteredRailFeed,
railFeedHasTripUpdates,
railFeedPositions,
} from './railFeeds.js';
// Licensed and switched on.
const ON = ['seattle-streetcar', 'cincinnati-connector'];
const TRAM = { category: 'transit', mode: 'tram' };
const feed = (id) => getRegisteredRailFeed(id);
const kind = (id, routeId, context) =>
classifyTrain(feed(id), routeId, context);
test('the US streetcar feeds: licensed feeds on, each with its basis', () => {
for (const id of ON) {
assert.ok(getRailFeed(id), `${id} is pollable`);
assert.ok(RAIL_ENABLED_FEEDS.includes(feed(id)), id);
assert.ok(feed(id).terms.note, `${id} explains its basis`);
assert.ok(feed(id).staticGtfsUrl, `${id} has a timetable`);
assert.ok(feed(id).terms.quote, `${id} quotes its terms`);
// Nothing personal in the recorded basis.
assert.doesNotMatch(feed(id).terms.note, /@/, id);
}
});
test('the US streetcar feeds poll positions and trip updates', () => {
for (const id of ON) {
assert.equal(railFeedPositions(feed(id)), 'gps', id);
assert.ok(railFeedHasTripUpdates(feed(id)), id);
}
});
test('Seattle Streetcar: the two City of Seattle routes of the King County feed', () => {
assert.deepEqual(kind('seattle-streetcar', '100340'), TRAM);
assert.deepEqual(kind('seattle-streetcar', '102638'), TRAM);
assert.equal(kind('seattle-streetcar', '100001'), null, 'a Metro bus');
assert.equal(kind('seattle-streetcar', null), null);
assert.equal(
feed('seattle-streetcar').attribution,
'Transit scheduling, geographic, and real-time data provided by permission of King County',
);
});
test('Cincinnati Connector: the streetcar route, buses dropped', () => {
assert.deepEqual(kind('cincinnati-connector', '100'), TRAM);
assert.equal(kind('cincinnati-connector', '78'), null);
});
+134
View File
@@ -0,0 +1,134 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
classifyTrain,
getRailFeed,
getRegisteredRailFeed,
publicRailCatalog,
railFeedHasTripUpdates,
railFeedPositions,
} from './railFeeds.js';
import {
buildRailSnapshot,
railMaxBodyBytes,
railUpstreamHeaders,
} from './railProxy.js';
const irish = getRegisteredRailFeed('irish-rail');
test('Irish Rail keeps its XML positions and gains a timetable', () => {
assert.equal(irish.format, 'irish-rail-xml');
assert.equal(irish.positions, 'event');
assert.ok(getRailFeed('irish-rail'));
assert.match(irish.staticGtfsUrl, /\/transitData\/Data\/GTFS_Realtime\.zip$/);
assert.deepEqual(irish.staticRouteTypes, [2]);
assert.equal(irish.positionsByTrainNumber, true);
assert.equal(irish.routesFrom, 'schedule');
// The XML's own headers and cap.
assert.match(railUpstreamHeaders(irish).Accept, /xml/);
assert.equal(railMaxBodyBytes(irish), 1024 * 1024);
// The positions publish no licence; the NTA timetable is CC BY 4.0.
assert.equal(
irish.license,
'No licence published (positions); CC BY 4.0 (NTA timetable)',
);
assert.equal(
irish.attribution,
'Iarnród Éireann / Irish Rail; timetable: National Transport Authority, provided as is',
);
});
test('Irish Rail is placed by its XML events and serves no trip updates', () => {
assert.equal(railFeedPositions(irish), 'event');
assert.equal(irish.tripUpdatesUrl, undefined);
assert.equal(railFeedHasTripUpdates(irish), false);
// Listed without a timetable pack: the XML's train codes classify alone.
const entry = publicRailCatalog({ schedulePackBuilt: () => false }).find(
(feed) => feed.id === 'irish-rail',
);
assert.equal(entry.positions, 'event');
assert.equal(entry.tripUpdates, false);
});
test('Irish Rail pack routes: the code letter and the provinces of the ends', () => {
const rename = (code, from, to, countries = ['IE']) =>
irish.staticTripRename({ trip_short_name: code }, 'R-1', {
ends: {
from: { name: from, country: countries[0] },
to: { name: to, country: countries.at(-1) },
countries,
},
});
assert.equal(
rename('A100', 'Dublin Connolly', 'Belfast', ['IE', 'GB']),
'A~B~R-1',
);
assert.equal(rename('A203', 'Cork (Kent)', 'Dublin Heuston'), 'A~X~R-1');
assert.equal(rename('A301', 'Mallow', 'Tralee (Casement)'), 'A~S~R-1');
assert.equal(rename('P501', 'Mallow', 'Cobh'), 'P~S~R-1');
assert.equal(rename('E206', 'Bray (Daly)', 'Howth'), 'E~X~R-1');
assert.equal(rename('195.MF-BH.93-GRN-y11', 'a', 'b'), null, 'no train code');
const kind = (route) => classifyTrain(irish, route, { tripId: '6024_1' });
assert.equal(
kind('A~B~DUB-BFT-O').category,
'international',
'the Enterprise',
);
assert.equal(kind('A~X~DUB-CORK-O').category, 'national');
assert.equal(kind('A~S~DUB-TRALEE-O').category, 'regional');
assert.equal(kind('E~X~BRAY-HOWTH-I').category, 'local', 'DART');
assert.equal(kind('P~S~MAL-COBH-O').category, 'local', 'commuter');
assert.equal(kind('D~S~MAL-COBH-O').category, 'local');
// The XML's own records still classify by their code and ends.
assert.equal(
classifyTrain(irish, 'Dublin Connolly - Belfast', { tripId: 'A100' })
.category,
'international',
);
assert.equal(
classifyTrain(irish, 'Bray - Howth', { tripId: 'E206' }).category,
'local',
);
});
test('an Irish Rail train code takes the timetable run it is on now', () => {
const xml = `<?xml version="1.0" encoding="utf-8"?>
<ArrayOfObjTrainPositions xmlns="http://api.irishrail.ie/realtime/">
<objTrainPositions>
<TrainStatus>R</TrainStatus><TrainLatitude>53.1442</TrainLatitude>
<TrainLongitude>-6.06085</TrainLongitude><TrainCode>A610</TrainCode>
<TrainDate>09 Nov 2026</TrainDate>
<PublicMessage>A610\\n18:37 - Dublin Connolly to Rosslare Europort (3 mins late)\\nDeparted Greystones next stop Kilcoole</PublicMessage>
<Direction>Southbound</Direction>
</objTrainPositions>
<objTrainPositions>
<TrainStatus>R</TrainStatus><TrainLatitude>53.35</TrainLatitude>
<TrainLongitude>-6.25</TrainLongitude><TrainCode>E999</TrainCode>
<TrainDate>09 Nov 2026</TrainDate>
<PublicMessage>E999\\n19:00 - Bray to Howth (0 mins late)\\nDeparted Connolly next stop Clontarf Road</PublicMessage>
<Direction>Northbound</Direction>
</objTrainPositions>
</ArrayOfObjTrainPositions>`;
const pack = { '6024_8435': 'A~X~DUB-EUROPORT-I' };
const snapshot = buildRailSnapshot(
irish,
new TextEncoder().encode(xml),
1_794_251_747_000,
{
routeFor: (tripId) => pack[tripId] ?? null,
tripFor: (code) => (code === 'A610' ? '6024_8435' : null),
},
);
const byCode = Object.fromEntries(
snapshot.trains.map((train) => [train.trainNumber ?? train.tripId, train]),
);
assert.equal(byCode.A610.tripId, '6024_8435');
assert.equal(byCode.A610.routeId, 'A~X~DUB-EUROPORT-I');
assert.equal(byCode.A610.category, 'national');
assert.equal(byCode.A610.positionSource, 'event');
assert.equal(byCode.A610.id, 'A610', 'the vehicle keeps its code');
// Not in the timetable: its own code and ends, as before.
assert.equal(byCode.E999.tripId, 'E999');
assert.equal(byCode.E999.trainNumber, undefined);
assert.equal(byCode.E999.category, 'local');
});
File diff suppressed because it is too large. Load diff
+297
View File
@@ -0,0 +1,297 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { mkdtemp, rm, writeFile } from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import { crc32 } from 'node:zlib';
import { PbfWriter } from 'pbf';
import {
NO_TRAIN_POSITION_BOX,
NO_TRAIN_POSITION_COUNTRIES,
isNoTrainPositionPoint,
isNoTrainPositionStop,
stopIdCountry,
} from './railNoPositions.js';
import { buildRailSnapshot } from './railProxy.js';
import { createRunIndex } from './railScheduleIndex.js';
import {
buildPack,
buildSchedule,
openZip,
} from '../../scripts/build-rail-paths.mjs';
const KYIV = [50.45, 30.52];
const LVIV = [49.84, 24.03];
const SIMFEROPOL = [44.95, 34.1];
const AMSTERDAM = [52.37, 4.9];
const PRZEMYSL = [49.78, 22.77];
const CHISINAU = [47.0, 28.86];
/** A fake feed: every vehicle and route is a train, so only the rule drops. */
function fakeFeed(extra = {}) {
return Object.freeze({
id: 'test-no-positions',
name: 'Test',
format: 'gtfs-rt',
classify: () => ({ category: 'international', mode: 'rail' }),
...extra,
});
}
test('the area is Ukraine, Crimea included, behind a cheap box', () => {
assert.deepEqual(NO_TRAIN_POSITION_COUNTRIES, ['UA']);
for (const [lat, lon] of [KYIV, LVIV, SIMFEROPOL, [48.0, 37.8]])
assert.equal(isNoTrainPositionPoint(lat, lon), true, `${lat},${lon}`);
for (const [lat, lon] of [AMSTERDAM, PRZEMYSL, CHISINAU, [53.9, 27.56]])
assert.equal(isNoTrainPositionPoint(lat, lon), false, `${lat},${lon}`);
// Outside the box nothing more is computed.
assert.ok(NO_TRAIN_POSITION_BOX.west > 22 && NO_TRAIN_POSITION_BOX.east < 41);
for (const bad of [NaN, null, undefined])
assert.equal(isNoTrainPositionPoint(bad, 30), false);
});
test('stations on the border fall on their own side (OpenStreetMap positions)', () => {
// Outside Ukraine, within 1 km of the border: on the Tisa (Bocicoi), by
// the Polish crossing (Medyka) and on the Slovak line (Čierna nad Tisou).
for (const [name, lat, lon] of [
['Bocicoi', 47.95743, 24.02333],
['Valea Vișeului', 47.91463, 24.15557],
['Sighetu Marmației', 47.9358, 23.88536],
['Medyka', 49.80248, 22.93929],
['Čierna nad Tisou št. hr.', 48.43209, 22.13597],
['Záhony', 48.4017, 22.18376],
])
assert.equal(isNoTrainPositionPoint(lat, lon), false, name);
// Inside Ukraine, as close to the border.
for (const [name, lat, lon] of [
['Uhniv', 50.37859, 23.73241],
['Korchiv', 50.39422, 23.83512],
['Teresva', 47.99573, 23.70047],
['Solotvyno-Likarnia', 47.96591, 23.86276],
])
assert.equal(isNoTrainPositionPoint(lat, lon), true, name);
});
test('a stop is left out when its id names Ukraine or its position is inside', () => {
assert.equal(stopIdCountry('ua:22005:1:1'), 'UA');
assert.equal(stopIdCountry('Pua:22005'), 'UA');
assert.equal(stopIdCountry('de:09162:6'), 'DE');
assert.equal(stopIdCountry('8000105'), null);
// A Ukrainian stop the outline would put in Hungary (Chop, on the border).
assert.equal(
isNoTrainPositionStop({ id: 'ua:22005:1:1', lat: 48.43, lon: 22.1 }),
true,
);
// A stop whose id names Poland, at a position the outline puts in
// Ukraine (Shehyni, across the border from Medyka): its id does not keep
// it.
assert.equal(
isNoTrainPositionStop({ id: 'pl:1:1', lat: 49.7949, lon: 22.9768 }),
true,
);
// Border stations on their own side stay, by id or by position alone.
for (const [id, lat, lon] of [
['pl:1:2', 49.80248, 22.93929], // Medyka
['hu:1:1', 48.4017, 22.18376], // Záhony
['sk:1:1', 48.43209, 22.13597], // Čierna nad Tisou
['ro:1:1', 47.95743, 24.02333], // Bocicoi
['5001', 49.80248, 22.93929],
])
assert.equal(isNoTrainPositionStop({ id, lat, lon }), false, id);
assert.equal(
isNoTrainPositionStop({ id: '9001', lat: LVIV[0], lon: LVIV[1] }),
true,
);
assert.equal(isNoTrainPositionStop(null), false);
});
/** A minimal stored (uncompressed) zip. */
function makeZip(files) {
const locals = [];
const centrals = [];
let offset = 0;
for (const [name, text] of Object.entries(files)) {
const data = Buffer.from(text, 'utf8');
const nameBytes = Buffer.from(name, 'utf8');
const local = Buffer.alloc(30);
local.writeUInt32LE(0x04034b50, 0);
local.writeUInt16LE(20, 4);
local.writeUInt32LE(crc32(data), 14);
local.writeUInt32LE(data.length, 18);
local.writeUInt32LE(data.length, 22);
local.writeUInt16LE(nameBytes.length, 26);
const central = Buffer.alloc(46);
central.writeUInt32LE(0x02014b50, 0);
central.writeUInt16LE(20, 4);
central.writeUInt16LE(20, 6);
central.writeUInt32LE(crc32(data), 16);
central.writeUInt32LE(data.length, 20);
central.writeUInt32LE(data.length, 24);
central.writeUInt16LE(nameBytes.length, 28);
central.writeUInt32LE(offset, 42);
locals.push(local, nameBytes, data);
centrals.push(central, nameBytes);
offset += local.length + nameBytes.length + data.length;
}
const cd = Buffer.concat(centrals);
const end = Buffer.alloc(22);
end.writeUInt32LE(0x06054b50, 0);
end.writeUInt16LE(locals.length / 3, 8);
end.writeUInt16LE(locals.length / 3, 10);
end.writeUInt32LE(cd.length, 12);
end.writeUInt32LE(offset, 16);
return Buffer.concat([...locals, cd, end]);
}
/**
* Wien–Budapest, Budapest–Chop (a `ua:` stop the outline would miss),
* Budapest–Lviv (an id without a country, inside the outline) and
* Sighet–Bocicoi (a Romanian halt on the border river, which a coarser
* outline would place in Ukraine).
*/
const GTFS = {
'agency.txt':
'agency_id,agency_name,agency_url,agency_timezone\n1,Test,https://example.invalid,Europe/Vienna\n',
'routes.txt': 'route_id,route_short_name,route_type\nR,EC,2\n',
'trips.txt': [
'route_id,service_id,trip_id,trip_short_name',
'R,daily,vienna-budapest,EC 1',
'R,daily,budapest-chop,EC 2',
'R,daily,budapest-lviv,EC 3',
'R,daily,sighet-bocicoi,R 4',
].join('\n'),
'stops.txt': [
'stop_id,stop_name,stop_lat,stop_lon',
'at:49:1,Wien Hauptbahnhof,48.185,16.376',
'hu:55:1,Budapest-Keleti,47.500,19.083',
'ua:22005:1:1,Chop,48.43,22.1',
'9001,Lviv,49.84,24.03',
'43820,Sighetu Marmaţiei,47.9358,23.88536',
'43753,Bocicoi Hm.,47.95743,24.02333',
].join('\n'),
'stop_times.txt': [
'trip_id,arrival_time,departure_time,stop_id,stop_sequence',
'vienna-budapest,08:00:00,08:00:00,at:49:1,1',
'vienna-budapest,10:40:00,10:40:00,hu:55:1,2',
'budapest-chop,11:00:00,11:00:00,hu:55:1,1',
'budapest-chop,16:00:00,16:00:00,ua:22005:1:1,2',
'budapest-lviv,12:00:00,12:00:00,hu:55:1,1',
'budapest-lviv,20:00:00,20:00:00,9001,2',
'sighet-bocicoi,09:00:00,09:00:00,43820,1',
'sighet-bocicoi,09:20:00,09:20:00,43753,2',
].join('\n'),
'calendar.txt': [
'service_id,monday,tuesday,wednesday,thursday,friday,saturday,sunday,start_date,end_date',
'daily,1,1,1,1,1,1,1,20260101,20271231',
].join('\n'),
};
async function buildFake(t) {
const dir = await mkdtemp(path.join(os.tmpdir(), 'gev-rail-no-pos-test-'));
t.after(() => rm(dir, { recursive: true, force: true }));
const file = path.join(dir, 'feed.zip');
await writeFile(file, makeZip(GTFS));
const zip = await openZip(file);
t.after(() => zip.handle.close());
const feed = fakeFeed();
const { pack } = await buildPack(feed, zip, { url: 'x' });
return buildSchedule(feed, zip, { url: 'x' }, pack, {
from: '2026-11-09',
days: 2,
});
}
test('the build leaves out every timetable trip that stops in Ukraine', async (t) => {
const { schedule, stats } = await buildFake(t);
assert.deepEqual(Object.keys(schedule.trips).sort(), [
'sighet-bocicoi',
'vienna-budapest',
]);
assert.equal(stats.tripsNoPositions, 2);
assert.deepEqual(schedule.stops.map((stop) => stop.name).sort(), [
'Bocicoi Hm.',
'Budapest-Keleti',
'Sighetu Marmaţiei',
'Wien Hauptbahnhof',
]);
});
test('a kept stop records no country', async (t) => {
const { schedule } = await buildFake(t);
for (const stop of schedule.stops) {
assert.equal(Object.hasOwn(stop, 'cc'), false, stop.name);
assert.equal(Object.hasOwn(stop, 'country'), false, stop.name);
}
});
test('a left-out trip has no runs for a reported train to take', async (t) => {
const { schedule } = await buildFake(t);
const runs = createRunIndex(schedule);
for (const tripId of ['budapest-chop', 'budapest-lviv'])
assert.deepEqual(runs.runsOf(tripId), [], tripId);
assert.ok(runs.runsOf('vienna-budapest').length > 0);
});
/** A GTFS-RT VehiclePositions message with one vehicle per position. */
function encodeVehicles(positions) {
const writer = new PbfWriter();
const header = new PbfWriter();
header.writeStringField(1, '2.0');
header.writeVarintField(3, 1_794_000_000);
writer.writeBytesField(1, header.finish());
positions.forEach(([lat, lon], i) => {
const entity = new PbfWriter();
entity.writeStringField(1, `v${i}`);
const vehicle = new PbfWriter();
const trip = new PbfWriter();
trip.writeStringField(1, `trip-${i}`);
trip.writeStringField(5, 'R');
vehicle.writeBytesField(1, trip.finish());
const position = new PbfWriter();
position.writeFloatField(1, lat);
position.writeFloatField(2, lon);
vehicle.writeBytesField(2, position.finish());
vehicle.writeVarintField(5, 1_793_999_990);
entity.writeBytesField(4, vehicle.finish());
writer.writeBytesField(2, entity.finish());
});
return writer.finish();
}
test('a live GPS position in Ukraine is dropped and counted, never sent', () => {
const snapshot = buildRailSnapshot(
fakeFeed({ url: 'https://example.invalid/vp' }),
encodeVehicles([AMSTERDAM, KYIV, SIMFEROPOL, PRZEMYSL]),
1_794_000_000_000,
);
assert.equal(snapshot.count, 2);
assert.equal(snapshot.dropped, 2);
for (const train of snapshot.trains)
assert.equal(isNoTrainPositionPoint(train.lat, train.lon), false);
});
test('an adapter position (Irish Rail XML) in Ukraine is dropped too', () => {
const position = (code, [lat, lon]) => `
<objTrainPositions>
<TrainStatus>R</TrainStatus>
<TrainLatitude>${lat}</TrainLatitude>
<TrainLongitude>${lon}</TrainLongitude>
<TrainCode>${code}</TrainCode>
<TrainDate>06 Nov 2026</TrainDate>
<PublicMessage>${code}</PublicMessage>
<Direction>Northbound</Direction>
</objTrainPositions>`;
const body = `<?xml version="1.0" encoding="utf-8"?>
<ArrayOfObjTrainPositions xmlns="http://api.irishrail.ie/realtime/">${position('A101', AMSTERDAM)}${position('A102', LVIV)}
</ArrayOfObjTrainPositions>`;
const snapshot = buildRailSnapshot(
fakeFeed({ format: 'irish-rail-xml', url: 'https://example.invalid/xml' }),
new TextEncoder().encode(body),
1_794_000_000_000,
);
assert.deepEqual(
snapshot.trains.map((train) => train.id),
['A101'],
);
assert.equal(snapshot.dropped, 1);
});
+288
View File
@@ -0,0 +1,288 @@
/**
* @module railPaths
* @description Track geometry for the Rail layer: a railway line as an indexed
* polyline measured by arc length, with projection of a position onto it and
* the point at a given arc length.
*
* Paths come from per-feed path packs (scripts/build-rail-paths.mjs), served by
* `/api/rail/paths/<feedId>`. A pack holds each unique shape as a flat
* `[lat, lon, lat, lon, ...]` array with its cumulative distances in metres.
*
* Distances are measured in one local equirectangular frame per path, centred
* on the path's middle latitude. Over the extent of a commuter network (a few
* hundred kilometres) the east-west scale error stays within a few per cent,
* which moves a projection by metres, well under what a marker shows.
*
* Pure: no Cesium, no DOM, no Node built-ins.
*/
/** Metres per degree of latitude (and of longitude at the equator). */
const M_PER_DEG = 111_320;
/** Segments per bounding box in the whole-path search index. */
const CHUNK = 32;
/** Longitude difference wrapped into (-180, 180]. */
function wrapLon(delta) {
return ((((delta + 180) % 360) + 360) % 360) - 180;
}
/**
* Build an indexed path from a flat lat/lon array.
* @param {ArrayLike<number>} coords `[lat, lon, lat, lon, ...]`, at least two points.
* @param {ArrayLike<number>} [dist] Cumulative metres per point. When absent,
* wrong-sized or decreasing, the distances are measured in the local frame.
* @returns {object|null} The path, or null when the input is not a polyline.
*/
export function createRailPath(coords, dist = null) {
const n = Math.floor((coords?.length ?? 0) / 2);
if (n < 2) return null;
const lat = new Float64Array(n);
const lon = new Float64Array(n);
let minLat = Infinity;
let maxLat = -Infinity;
for (let i = 0; i < n; i++) {
const a = Number(coords[2 * i]);
const o = Number(coords[2 * i + 1]);
if (!Number.isFinite(a) || !Number.isFinite(o) || Math.abs(a) > 90)
return null;
lat[i] = a;
lon[i] = o;
if (a < minLat) minLat = a;
if (a > maxLat) maxLat = a;
}
const lat0 = (minLat + maxLat) / 2;
const lon0 = lon[0];
const kx = M_PER_DEG * Math.cos((lat0 * Math.PI) / 180);
const ky = M_PER_DEG;
const x = new Float64Array(n);
const y = new Float64Array(n);
for (let i = 0; i < n; i++) {
x[i] = wrapLon(lon[i] - lon0) * kx;
y[i] = (lat[i] - lat0) * ky;
}
const s = new Float64Array(n);
let given = dist?.length === n && Number(dist[0]) >= 0;
for (let i = 0; given && i < n; i++) {
const d = Number(dist[i]);
if (!Number.isFinite(d) || (i > 0 && d < s[i - 1])) given = false;
else s[i] = d;
}
if (!given) {
s[0] = 0;
for (let i = 1; i < n; i++)
s[i] = s[i - 1] + Math.hypot(x[i] - x[i - 1], y[i] - y[i - 1]);
}
const chunks = Math.ceil((n - 1) / CHUNK);
const box = new Float64Array(chunks * 4);
for (let c = 0; c < chunks; c++) {
let x0 = Infinity;
let x1 = -Infinity;
let y0 = Infinity;
let y1 = -Infinity;
const end = Math.min(n - 1, (c + 1) * CHUNK);
for (let i = c * CHUNK; i <= end; i++) {
if (x[i] < x0) x0 = x[i];
if (x[i] > x1) x1 = x[i];
if (y[i] < y0) y0 = y[i];
if (y[i] > y1) y1 = y[i];
}
box[4 * c] = x0;
box[4 * c + 1] = x1;
box[4 * c + 2] = y0;
box[4 * c + 3] = y1;
}
return Object.freeze({
n,
lat,
lon,
x,
y,
s,
box,
lat0,
lon0,
kx,
ky,
length: s[n - 1],
});
}
/** Index of the segment [i, i+1] whose arc range holds `s`, clamped. */
function segmentAt(path, s) {
const arc = path.s;
let lo = 0;
let hi = path.n - 2;
if (!(s > arc[0])) return 0;
if (s >= arc[hi + 1]) return hi;
while (lo < hi) {
const mid = (lo + hi + 1) >> 1;
if (arc[mid] <= s) lo = mid;
else hi = mid - 1;
}
return lo;
}
/**
* Squared distance from (px, py) to segment i, writing the parameter to `hit`.
* @returns {number}
*/
function segmentDistance2(path, i, px, py, hit) {
const { x, y } = path;
const dx = x[i + 1] - x[i];
const dy = y[i + 1] - y[i];
const len2 = dx * dx + dy * dy;
let t = len2 > 0 ? ((px - x[i]) * dx + (py - y[i]) * dy) / len2 : 0;
if (t < 0) t = 0;
else if (t > 1) t = 1;
const ex = x[i] + dx * t - px;
const ey = y[i] + dy * t - py;
hit.t = t;
return ex * ex + ey * ey;
}
/**
* Project a position onto a path.
*
* With a hint, only the segments whose arc range overlaps
* `[hintS - windowM, hintS + windowM]` are searched: a train known to be near
* arc `hintS` cannot jump to the far side of a loop or to a parallel branch
* that the same shape passes later. Without one, the whole path is searched.
*
* @param {object} path From createRailPath.
* @param {number} lat
* @param {number} lon
* @param {number} [hintS] Expected arc length (m).
* @param {number} [windowM] Half-width of the search window around the hint (m).
* @param {{s?: number, offsetM?: number, index?: number}} [out]
* @returns {{s: number, offsetM: number, index: number}|null}
*/
export function projectOnPath(path, lat, lon, hintS, windowM, out = {}) {
if (!path || !Number.isFinite(lat) || !Number.isFinite(lon)) return null;
const px = wrapLon(lon - path.lon0) * path.kx;
const py = (lat - path.lat0) * path.ky;
const hit = { t: 0 };
let best = Infinity;
let bestIndex = -1;
let bestT = 0;
if (Number.isFinite(hintS) && Number.isFinite(windowM) && windowM >= 0) {
const first = segmentAt(path, hintS - windowM);
const last = segmentAt(path, hintS + windowM);
for (let i = first; i <= last; i++) {
const d2 = segmentDistance2(path, i, px, py, hit);
if (d2 < best) {
best = d2;
bestIndex = i;
bestT = hit.t;
}
}
} else {
const { box } = path;
const chunks = box.length / 4;
for (let c = 0; c < chunks; c++) {
const ox = Math.max(box[4 * c] - px, 0, px - box[4 * c + 1]);
const oy = Math.max(box[4 * c + 2] - py, 0, py - box[4 * c + 3]);
if (ox * ox + oy * oy >= best) continue;
const end = Math.min(path.n - 2, (c + 1) * CHUNK - 1);
for (let i = c * CHUNK; i <= end; i++) {
const d2 = segmentDistance2(path, i, px, py, hit);
if (d2 < best) {
best = d2;
bestIndex = i;
bestT = hit.t;
}
}
}
}
if (bestIndex < 0) return null;
const s = path.s;
out.s = s[bestIndex] + (s[bestIndex + 1] - s[bestIndex]) * bestT;
out.offsetM = Math.sqrt(best);
out.index = bestIndex;
return out;
}
/**
* The position and direction of travel at an arc length, clamped to the path.
* @param {object} path From createRailPath.
* @param {number} s Arc length (m).
* @param {{lat?: number, lon?: number, bearingDeg?: number}} [out]
* @returns {{lat: number, lon: number, bearingDeg: number}|null}
*/
export function pointAtS(path, s, out = {}) {
if (!path || !Number.isFinite(s)) return null;
const clamped = Math.max(0, Math.min(path.length, s));
let i = segmentAt(path, clamped);
// A zero-length segment has no direction; borrow its neighbour's.
while (i < path.n - 2 && path.s[i + 1] === path.s[i]) i++;
const span = path.s[i + 1] - path.s[i];
const t =
span > 0 ? Math.max(0, Math.min(1, (clamped - path.s[i]) / span)) : 0;
out.lat = path.lat[i] + (path.lat[i + 1] - path.lat[i]) * t;
let lon = path.lon[i] + wrapLon(path.lon[i + 1] - path.lon[i]) * t;
if (lon > 180) lon -= 360;
else if (lon < -180) lon += 360;
out.lon = lon;
const dx = path.x[i + 1] - path.x[i];
const dy = path.y[i + 1] - path.y[i];
out.bearingDeg =
dx === 0 && dy === 0
? NaN
: ((Math.atan2(dx, dy) * 180) / Math.PI + 360) % 360;
return out;
}
/** Path-pack format this module reads. */
export const RAIL_PATH_PACK_VERSION = 1;
/**
* Wrap a decoded path pack for lookups. Shapes are indexed lazily, the first
* time a train asks for one.
* @param {object} raw The JSON body of `/api/rail/paths/<feedId>`.
* @returns {{feedId: string, shapeCount: number,
* pathAt: (index: number) => object|null,
* shapeForTrip: (tripId: string) => number|null,
* shapesForRoute: (routeId: string) => number[]}}
*/
export function createRailPathPack(raw) {
if (
!raw ||
raw.version !== RAIL_PATH_PACK_VERSION ||
typeof raw.feedId !== 'string' ||
!Array.isArray(raw.shapes) ||
!Array.isArray(raw.dist) ||
raw.dist.length !== raw.shapes.length
)
throw new TypeError('Malformed rail path pack');
const shapes = raw.shapes;
const dist = raw.dist;
const trips = raw.trips && typeof raw.trips === 'object' ? raw.trips : {};
const routes = raw.routes && typeof raw.routes === 'object' ? raw.routes : {};
const built = new Map();
const validIndex = (value) =>
Number.isInteger(value) && value >= 0 && value < shapes.length
? value
: null;
return Object.freeze({
feedId: raw.feedId,
/** When the pack was built (ISO), matched by a schedule's pathsBuiltAt. */
builtAt: typeof raw.builtAt === 'string' ? raw.builtAt : null,
shapeCount: shapes.length,
pathAt(index) {
if (validIndex(index) === null) return null;
if (!built.has(index))
built.set(index, createRailPath(shapes[index], dist[index]));
return built.get(index);
},
shapeForTrip(tripId) {
const id = String(tripId ?? '');
return id && Object.hasOwn(trips, id) ? validIndex(trips[id]) : null;
},
shapesForRoute(routeId) {
const id = String(routeId ?? '');
const list = id && Object.hasOwn(routes, id) ? routes[id] : null;
return Array.isArray(list)
? list.filter((value) => validIndex(value) !== null)
: [];
},
});
}
+163
View File
@@ -0,0 +1,163 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
RAIL_PATH_PACK_VERSION,
createRailPath,
createRailPathPack,
pointAtS,
projectOnPath,
} from './railPaths.js';
const M_PER_DEG = 111_320;
/** An L: 1 km east along the equator, then 1 km north. */
function lPath() {
const dLon = 1000 / M_PER_DEG;
return createRailPath([0, 0, 0, dLon, dLon, dLon]);
}
/**
* A hairpin: 2 km east along lat 0, a 100 m step north, then 2 km back west.
* The two legs are parallel and 100 m apart, like the two sides of a loop.
*/
function hairpin() {
const d = 1 / M_PER_DEG;
return createRailPath([0, 0, 0, 2000 * d, 100 * d, 2000 * d, 100 * d, 0]);
}
test('a path measures its arc length in metres', () => {
const path = lPath();
assert.equal(path.n, 3);
assert.ok(Math.abs(path.length - 2000) < 0.5, String(path.length));
assert.equal(createRailPath([0, 0]), null, 'one point is not a path');
assert.equal(createRailPath([0, 0, Number.NaN, 1]), null);
assert.equal(createRailPath(null), null);
});
test('given distances are used, and bad ones are measured instead', () => {
const coords = [0, 0, 0, 0.01, 0, 0.02];
assert.deepEqual([...createRailPath(coords, [0, 5, 10]).s], [0, 5, 10]);
const measured = createRailPath(coords, [0, 10, 5]);
assert.ok(Math.abs(measured.s[2] - 2 * 0.01 * M_PER_DEG) < 0.5);
const wrongSize = createRailPath(coords, [0, 1]);
assert.ok(wrongSize.s[1] > 1000);
});
test('projection finds the arc and the offset from the line', () => {
const path = lPath();
const d = 1 / M_PER_DEG;
const hit = projectOnPath(path, 20 * d, 500 * d);
assert.ok(Math.abs(hit.s - 500) < 0.5, String(hit.s));
assert.ok(Math.abs(hit.offsetM - 20) < 0.5, String(hit.offsetM));
assert.equal(hit.index, 0);
const second = projectOnPath(path, 300 * d, 1030 * d);
assert.ok(Math.abs(second.s - 1300) < 0.5, String(second.s));
assert.ok(Math.abs(second.offsetM - 30) < 0.5);
assert.equal(second.index, 1);
const beyond = projectOnPath(path, 2000 * d, 1000 * d);
assert.ok(Math.abs(beyond.s - 2000) < 0.5, 'clamped to the end');
assert.ok(Math.abs(beyond.offsetM - 1000) < 1);
assert.equal(projectOnPath(path, Number.NaN, 0), null);
assert.equal(projectOnPath(null, 0, 0), null);
});
test('a hint keeps the projection on its own side of a loop', () => {
const path = hairpin();
const d = 1 / M_PER_DEG;
// 45 m north of the outbound leg, 55 m south of the return leg: the
// whole-path answer is the outbound leg...
const point = [45 * d, 1000 * d];
const free = projectOnPath(path, ...point);
assert.ok(Math.abs(free.s - 1000) < 1, String(free.s));
// ...but a train known to be on the return leg stays on it.
const hinted = projectOnPath(path, ...point, 3100, 500);
assert.ok(Math.abs(hinted.s - 3100) < 1, String(hinted.s));
assert.ok(Math.abs(hinted.offsetM - 55) < 0.5);
});
test('the whole-path search agrees with a brute-force scan on a long path', () => {
const coords = [];
for (let i = 0; i < 500; i++)
coords.push(40 + Math.sin(i / 20) * 0.01, -74 + i * 0.001);
const path = createRailPath(coords);
for (const [lat, lon] of [
[40.004, -73.9],
[40.02, -73.75],
[39.99, -73.6],
]) {
const fast = projectOnPath(path, lat, lon);
let best = Infinity;
for (let i = 0; i < path.n - 1; i++) {
const hit = projectOnPath(
path,
lat,
lon,
(path.s[i] + path.s[i + 1]) / 2,
0,
);
best = Math.min(best, hit.offsetM);
}
assert.ok(
Math.abs(fast.offsetM - best) < 1e-6,
`${fast.offsetM} vs ${best}`,
);
}
});
test('the point at an arc length carries the direction of travel', () => {
const path = lPath();
const d = 1 / M_PER_DEG;
const east = pointAtS(path, 250);
assert.ok(Math.abs(east.lon - 250 * d) < 1e-9);
assert.equal(east.lat, 0);
assert.ok(Math.abs(east.bearingDeg - 90) < 1e-6, String(east.bearingDeg));
const north = pointAtS(path, 1500);
assert.ok(Math.abs(north.lat - 500 * d) < 1e-6);
assert.ok(
Math.abs(north.bearingDeg - 0) < 1e-6 ||
Math.abs(north.bearingDeg - 360) < 1e-6,
);
const out = {};
assert.equal(pointAtS(path, -50, out), out, 'writes into the caller scratch');
assert.equal(out.lat, 0);
assert.equal(out.lon, 0);
assert.ok(Math.abs(pointAtS(path, 9e9).lat - 1000 * d) < 1e-9);
assert.equal(pointAtS(path, Number.NaN), null);
});
test('a pack resolves trips and routes to shapes and builds paths lazily', () => {
const raw = {
version: RAIL_PATH_PACK_VERSION,
feedId: 'grt-ion',
shapes: [
[43.4, -80.5, 43.41, -80.5],
[43.4, -80.5, 43.4, -80.49],
],
dist: [
[0, 1113.2],
[0, 808.9],
],
trips: { t1: 0, t2: 1, bad: 7 },
routes: { 301: [0, 1, 9] },
};
const pack = createRailPathPack(raw);
assert.equal(pack.feedId, 'grt-ion');
assert.equal(pack.shapeCount, 2);
assert.equal(pack.shapeForTrip('t1'), 0);
assert.equal(pack.shapeForTrip('bad'), null, 'out-of-range index');
assert.equal(pack.shapeForTrip('constructor'), null, 'no prototype keys');
assert.equal(pack.shapeForTrip(''), null);
assert.deepEqual(pack.shapesForRoute('301'), [0, 1]);
assert.deepEqual(pack.shapesForRoute('302'), []);
const path = pack.pathAt(1);
assert.equal(path.length, 808.9);
assert.equal(pack.pathAt(1), path, 'built once');
assert.equal(pack.pathAt(5), null);
for (const broken of [
null,
{ ...raw, version: 2 },
{ ...raw, feedId: 3 },
{ ...raw, dist: [] },
])
assert.throws(() => createRailPathPack(broken), TypeError);
});
+518
View File
@@ -0,0 +1,518 @@
/**
* @module railProxy
* @description Pure server-side mechanics for the `/api/rail` proxy.
*
* The upstream mechanics are the Transit proxy's (src/data/transitProxy.js):
* the same decoder, timestamp repair, redirect rule, conditional headers, cache
* windows and backoff ladder. What differs is which feeds are reachable and
* what leaves the server: only vehicles a feed's classifier recognises as
* trains, each tagged with its category, mode and position source. On top of
* that come the Irish Rail XML and SIRI-VM adapters and trip updates. Every
* train is placed where its operator reports it. Every feed is open: no
* request carries a credential.
*/
import {
TRANSIT_ADMISSION_MAX_GLOBAL,
TRANSIT_PROXY_MAX_BODY_BYTES,
TRANSIT_PROXY_STALE_MAX_MS,
TRANSIT_PROXY_TTL_MS,
TransitFeedShapeError,
buildTransitSnapshot,
} from './transitProxy.js';
import { GTFS_INCREMENTALITY_FULL_DATASET } from './gtfsRealtime.js';
import {
RAIL_FEED_REGISTRY,
classifyTrain,
getRailFeed,
railFeedHasTripUpdates,
railFeedPositions,
} from './railFeeds.js';
import { decodeIrishRailTrains } from './irishRail.js';
import { decodeSiriVehicleMonitoring } from './railSiriVm.js';
import { decodeTripUpdates } from './railTripUpdates.js';
import { isNoTrainPositionPoint } from './railNoPositions.js';
/**
* Text formats with their own adapter, by registry `format`. Each turns the
* document and the fetch time (epoch s) into `{entityCount, truncated,
* vehicles, feedTimestamp?}`.
*/
const TEXT_ADAPTERS = Object.freeze({
'irish-rail-xml': decodeIrishRailTrains,
'siri-vm': decodeSiriVehicleMonitoring,
});
export {
TRANSIT_ADMISSION_MAX_PER_FEED as RAIL_ADMISSION_MAX_PER_FEED,
TRANSIT_ADMISSION_WINDOW_MS as RAIL_ADMISSION_WINDOW_MS,
TRANSIT_PROXY_TIMEOUT_MS as RAIL_PROXY_TIMEOUT_MS,
TransitFeedShapeError as RailFeedShapeError,
isAcceptableTransitUpstreamUrl as isAcceptableRailUpstreamUrl,
nextTransitBackoffMs as nextRailBackoffMs,
} from './transitProxy.js';
/**
* Largest path or schedule pack the proxy serves or reads (bytes). The
* biggest national packs built so far were 14 to 16 MB; anything far beyond
* that is a build fault, not a pack to ship. A pack over the cap is refused
* with its own answer, not taken for a missing one.
*/
export const RAIL_PATH_PACK_MAX_BYTES = 24 * 1024 * 1024;
/**
* Default freshness window for trip updates. Predictions move more slowly
* than positions, and several operators refresh them every 30 to 60 s.
*/
export const RAIL_TRIP_UPDATES_TTL_MS = 30_000;
/** Shortest window a registry entry may ask for. */
export const RAIL_MIN_TTL_MS = 5_000;
/** Trips one `/updates` answer carries, after the rail filter. */
export const RAIL_UPDATES_MAX_TRIPS = 3_000;
/** Stop updates one `/updates` answer carries, across all its trips. */
export const RAIL_UPDATES_MAX_STOPS = 40_000;
/**
* Freshness window for one route of a feed: its own interval when the
* registry sets one (never below RAIL_MIN_TTL_MS), else the default.
* @param {object} feed
* @param {'trains'|'updates'} route
* @returns {number} ms
*/
export function railFeedTtlMs(feed, route = 'trains') {
const own =
route === 'updates' ? feed?.tripUpdatesIntervalMs : feed?.pollIntervalMs;
if (Number.isFinite(own) && own > 0) return Math.max(RAIL_MIN_TTL_MS, own);
return route === 'updates' ? RAIL_TRIP_UPDATES_TTL_MS : TRANSIT_PROXY_TTL_MS;
}
/**
* Largest byte cap a feed may set for itself (`maxBodyBytes`): nothing
* larger is read into memory.
*/
export const RAIL_PROXY_MAX_BODY_CEILING_BYTES = 64 * 1024 * 1024;
/**
* Upstream byte cap for a feed: its own cap when it sets one (never above
* RAIL_PROXY_MAX_BODY_CEILING_BYTES), else the Transit proxy's 8 MiB.
* @param {object} feed
* @returns {number}
*/
export function railMaxBodyBytes(feed) {
const own = feed?.maxBodyBytes;
return Number.isFinite(own) && own > 0
? Math.min(own, RAIL_PROXY_MAX_BODY_CEILING_BYTES)
: TRANSIT_PROXY_MAX_BODY_BYTES;
}
/**
* Classify a cache entry against a freshness window: the Transit policy with
* a per-feed TTL. The serve-stale window is the same ten minutes.
* @param {{at: number}|null|undefined} entry
* @param {number} now
* @param {number} [ttlMs]
* @returns {'none'|'fresh'|'stale'|'expired'}
*/
export function railCacheStateFor(entry, now, ttlMs = TRANSIT_PROXY_TTL_MS) {
if (!entry || !Number.isFinite(entry.at)) return 'none';
const age = now - entry.at;
if (age < ttlMs) return 'fresh';
if (age < Math.max(TRANSIT_PROXY_STALE_MAX_MS, ttlMs)) return 'stale';
return 'expired';
}
/**
* Resolve `/trains/<feedId>`, `/paths/<feedId>`, `/schedule/<feedId>` or
* `/updates/<feedId>` (the path after the `/api/rail` mount) to a pollable
* feed. Anything else (another route, an unknown or disabled id, an
* `/updates` request for a feed with no trip updates, path tricks) resolves
* to null and the caller 404s.
* @param {string} url Request URL relative to the mount point.
* @returns {{ route: 'feeds' } |
* { route: 'trains'|'paths'|'schedule'|'updates', feed: object } | null}
*/
export function resolveRailRoute(url) {
const pathname = String(url || '').split('?')[0];
if (pathname === '/feeds' || pathname === '/feeds/')
return { route: 'feeds' };
const match = /^\/(trains|paths|schedule|updates)\/([^/]+)\/?$/.exec(
pathname,
);
if (!match) return null;
let id;
try {
id = decodeURIComponent(match[2]);
} catch {
return null;
}
const feed = getRailFeed(id);
if (!feed) return null;
if (match[1] === 'updates' && !railFeedHasTripUpdates(feed)) return null;
return { route: match[1], feed };
}
/**
* Classify decoded vehicles and keep only trains. A position where no train
* is placed (src/data/railNoPositions.js: Ukraine) is dropped first, so it
* is only counted and never leaves the server.
*/
function keepTrains(feed, vehicles, routeFor = null) {
const positionSource = railFeedPositions(feed) === 'event' ? 'event' : 'gps';
const trains = [];
for (const vehicle of vehicles) {
if (isNoTrainPositionPoint(vehicle.lat, vehicle.lon)) continue;
const routeId = resolvedRouteId(feed, vehicle, routeFor);
const kind = classifyTrain(feed, routeId, { tripId: vehicle.tripId });
if (!kind) continue;
trains.push({
...vehicle,
routeId,
category: kind.category,
mode: kind.mode,
...(kind.tourist ? { tourist: true } : {}),
positionSource,
});
}
return trains;
}
/**
* The route a record is classified by. A feed with `routesFrom: 'schedule'`
* publishes trips whose route is missing or not the one its classifier reads;
* `routeFor(tripId)` answers from the feed's schedule pack, whose route ids
* the build wrote to carry the product. A trip the pack does not know keeps
* what the feed said, which its classifier then drops.
*/
function resolvedRouteId(feed, record, routeFor) {
if (feed?.routesFrom !== 'schedule' || typeof routeFor !== 'function')
return record.routeId;
return (record.tripId && routeFor(record.tripId)) || record.routeId;
}
/**
* For a feed whose positions name each train by its number
* (`positionsByTrainNumber`, Irish Rail's train codes), the record takes
* the schedule pack's trip that number is running now (`tripFor`, given the
* number and the record, whose stated delay moves its timetable), so the
* train is drawn on its line and its card lists its stops; the number stays
* as `trainNumber`. A number the timetable does not place keeps its own id.
*/
function byTrainNumber(feed, vehicles, tripFor) {
if (feed?.positionsByTrainNumber !== true || typeof tripFor !== 'function')
return vehicles;
return vehicles.map((vehicle) => {
const tripId = vehicle.tripId ? tripFor(vehicle.tripId, vehicle) : null;
return tripId
? { ...vehicle, tripId, trainNumber: vehicle.tripId }
: vehicle;
});
}
/**
* For a feed whose header clock cannot be trusted (`headerClock:
* 'untrusted'`, Renfe: local time written as UTC), a time the Transit
* ladder took from the header is replaced by the fetch time and labelled so.
*/
function distrustHeaderClock(feed, vehicles, now) {
if (feed?.headerClock !== 'untrusted') return vehicles;
const fetchedS = Math.floor(now / 1000);
return vehicles.map((vehicle) =>
vehicle.timestampSource === 'header'
? { ...vehicle, timestamp: fetchedS, timestampSource: 'fetch' }
: vehicle,
);
}
/**
* An upstream answer that is no document of the feed's: a failed fetch, not
* a reason to distrust the last good snapshot, which the service keeps
* serving while it is young enough (`code: 'UPSTREAM_UNREADABLE'`, a 502).
* @param {string} detail
* @returns {Error & {code: string}}
*/
function unreadableUpstream(detail) {
const failure = new Error(`upstream document unreadable: ${detail}`);
failure.code = 'UPSTREAM_UNREADABLE';
return failure;
}
/**
* Run a GTFS-RT decode and refuse what is not a FeedMessage: bytes protobuf
* cannot read (an HTML or JSON error page served as 200), and a message
* without a FeedHeader or its gtfs_realtime_version, which every
* FeedMessage carries. An empty body (a 200 or 204 with nothing in it)
* decodes to exactly that, and would otherwise read as a full snapshot with
* no trains. A DIFFERENTIAL feed's refusal passes through as it is.
* @template {{version: string|null}} T
* @param {() => T} decode
* @returns {T}
*/
function decodeGtfsRealtime(decode) {
let decoded;
try {
decoded = decode();
} catch (error) {
if (error instanceof TransitFeedShapeError) throw error;
throw unreadableUpstream(error?.message || String(error));
}
if (decoded?.version === null || decoded?.version === undefined)
throw unreadableUpstream('no FeedHeader with a gtfs_realtime_version');
return decoded;
}
/**
* Decode upstream bytes into the JSON snapshot the Rail layer consumes.
*
* For GTFS-RT feeds, decoding, the refusal of DIFFERENTIAL feeds and the
* report-time ladder are the Transit proxy's; a body that is no FeedMessage
* (no header, no version, not protobuf) is refused as unreadable
* (decodeGtfsRealtime). Irish Rail's XML and SIRI-VM go through their
* adapters. The classifier then runs on every vehicle: a vehicle it does
* not recognise (a bus in a mixed feed, a shuttle, an out-of-service vehicle
* with no route in a mixed feed) is dropped and only counted, so the browser
* receives trains and nothing else. Every train carries `positionSource`:
* `gps` for GTFS-RT positions, `event` for signalling events.
*
* @param {object} feed Rail registry entry.
* @param {Uint8Array|ArrayBuffer} bytes Raw upstream body.
* @param {number} [now=Date.now()] Fetch time (ms epoch).
* @param {{routeFor?: Function|null, tripFor?: Function|null}} [lookups]
* `routeFor` resolves a trip's route from the schedule pack, and
* `tripFor(number, record)` a train number's running trip
* (`positionsByTrainNumber`).
* @returns {{ feedId: string, name: string, fetchedAt: number, feedTimestamp: number|null,
* version: string|null, entityCount: number, truncated: boolean, count: number,
* dropped: number, positions: string, trains: object[] }}
*/
export function buildRailSnapshot(
feed,
bytes,
now = Date.now(),
{ routeFor = null, tripFor = null } = {},
) {
const adapter = Object.hasOwn(TEXT_ADAPTERS, feed?.format)
? TEXT_ADAPTERS[feed.format]
: null;
if (adapter) {
const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
const text = new TextDecoder('utf-8').decode(view);
let decoded;
try {
decoded = adapter(text, Math.floor(now / 1000));
} catch (error) {
// An unreadable document (an error page served as 200, a truncated
// body) is a failed fetch, not a reason to distrust the last good one.
throw unreadableUpstream(error?.message || String(error));
}
const trains = keepTrains(
feed,
byTrainNumber(feed, decoded.vehicles, tripFor),
routeFor,
);
return {
feedId: feed.id,
name: feed.name,
fetchedAt: now,
feedTimestamp: Number.isFinite(decoded.feedTimestamp)
? decoded.feedTimestamp
: null,
version: null,
entityCount: decoded.entityCount,
truncated: decoded.truncated,
count: trains.length,
dropped: decoded.vehicles.length - trains.length,
positions: railFeedPositions(feed),
trains,
};
}
const decoded = decodeGtfsRealtime(() =>
buildTransitSnapshot(feed, bytes, now),
);
const trains = keepTrains(
feed,
distrustHeaderClock(feed, decoded.vehicles, now),
routeFor,
);
return {
feedId: decoded.feedId,
name: decoded.name,
fetchedAt: decoded.fetchedAt,
feedTimestamp:
feed.headerClock === 'untrusted' ? null : decoded.feedTimestamp,
version: decoded.version,
entityCount: decoded.entityCount,
truncated: decoded.truncated,
count: trains.length,
dropped: decoded.vehicles.length - trains.length,
positions: railFeedPositions(feed),
trains,
};
}
/**
* Decode a TripUpdates feed into the `/api/rail/updates/<feedId>` body: one
* record per rail trip, filtered with the same classifier as the positions
* (a feed's buses never leave the server), capped in trips and stops.
*
* A DIFFERENTIAL feed is refused, for the same reason positions are: an
* unmentioned trip would read as one with no prediction. A body that is no
* FeedMessage is refused as unreadable (decodeGtfsRealtime).
*
* @param {object} feed Rail registry entry.
* @param {Uint8Array|ArrayBuffer} bytes Raw GTFS-RT FeedMessage.
* @param {number} [now=Date.now()] Fetch time (ms epoch).
* @param {{routeFor?: ((tripId: string) => string|null)|null}} [lookups]
* `routeFor` is the schedule pack's trip-to-route lookup, for a feed
* whose trips do not carry the route its classifier reads (`routesFrom:
* 'schedule'`).
* @returns {{ feedId: string, name: string, fetchedAt: number,
* feedTimestamp: number|null, entityCount: number, truncated: boolean,
* count: number, dropped: number, trips: object[] }}
*/
export function buildRailTripUpdatesSnapshot(
feed,
bytes,
now = Date.now(),
{ routeFor = null } = {},
) {
const decoded = decodeGtfsRealtime(() => decodeTripUpdates(bytes));
if (decoded.incrementality !== GTFS_INCREMENTALITY_FULL_DATASET) {
throw new TransitFeedShapeError(
`feed is differential (incrementality ${decoded.incrementality})`,
'differential',
);
}
const trips = [];
let truncated = decoded.truncated;
let stops = 0;
let rail = 0;
for (const trip of decoded.trips) {
const routeId = resolvedRouteId(feed, trip, routeFor);
const kind = classifyTrain(feed, routeId, { tripId: trip.tripId });
if (!kind) continue;
rail += 1;
if (
trips.length >= RAIL_UPDATES_MAX_TRIPS ||
stops + trip.stops.length > RAIL_UPDATES_MAX_STOPS
) {
truncated = true;
continue;
}
stops += trip.stops.length;
trips.push({
...trip,
routeId,
category: kind.category,
mode: kind.mode,
...(kind.tourist ? { tourist: true } : {}),
});
}
return {
feedId: feed.id,
name: feed.name,
fetchedAt: now,
feedTimestamp: decoded.timestamp,
entityCount: decoded.entityCount,
truncated,
count: trips.length,
dropped: decoded.trips.length - rail,
trips,
};
}
/**
* Upstream request headers. Same obligations as Transit's (conditional
* validators, gzip, a User-Agent that says who is asking, any identify-yourself
* header the registry names), with this proxy's own name in the User-Agent.
* A feed's own `headers` (an Accept for an XML feed) come last.
* @param {object} feed Registry entry.
* @param {{etag?: string|null, lastModified?: string|null}} [validators]
* @returns {Record<string, string>}
*/
export function railUpstreamHeaders(feed, validators = null) {
return {
'User-Agent':
'gods-eye-view-rail-proxy/1.0 (+https://github.com/bilawalsidhu/gods-eye-view)',
Accept: 'application/x-protobuf, application/octet-stream;q=0.9, */*;q=0.1',
'Accept-Encoding': 'gzip',
...(validators?.etag ? { 'If-None-Match': validators.etag } : {}),
...(validators?.lastModified
? { 'If-Modified-Since': validators.lastModified }
: {}),
...(feed?.headers || {}),
};
}
/**
* Upstream requests one minute may need when every feed in the registry is
* polled at once: one per freshness window for each feed's positions and
* trip updates.
* @param {ReadonlyArray<object>} [feeds]
* @returns {number}
*/
export function railNaturalRequestsPerMinute(feeds = RAIL_FEED_REGISTRY) {
let total = 0;
for (const feed of feeds) {
if (feed?.defaultEnabled !== true) continue;
if (feed.url) total += Math.ceil(60_000 / railFeedTtlMs(feed, 'trains'));
if (railFeedHasTripUpdates(feed))
total += Math.ceil(60_000 / railFeedTtlMs(feed, 'updates'));
}
return total;
}
/**
* The process-wide admission cap (requests per admission window, all
* operators): the natural load of every enabled feed, half again on top for
* retries on the backoff ladder, never below the Transit proxy's own cap
* (TRANSIT_ADMISSION_MAX_GLOBAL, 40). It is a backstop against a bug or a
* runaway client, not the protection an operator relies on: that is each
* feed's freshness window and the per-feed admission count. Transit's fixed
* cap alone sat below the natural load once the registry passed about ten
* feeds polled every 15 s, so a viewer of several regions got 503s from a
* healthy proxy.
* @param {ReadonlyArray<object>} [feeds]
* @returns {number}
*/
export function railAdmissionGlobalMax(feeds = RAIL_FEED_REGISTRY) {
return Math.max(
TRANSIT_ADMISSION_MAX_GLOBAL,
Math.ceil(railNaturalRequestsPerMinute(feeds) * 1.5),
);
}
/**
* Response headers for a snapshot. `X-GEV-Cache` mirrors the other proxies
* (HIT / MISS / INFLIGHT / STALE-ERROR); `X-Rail-Contact` is when the operator
* last ANSWERED, which a revalidated (304) feed advances without changing the
* body's own fetch time. `max-age` is what is left of the feed's own
* freshness window once the snapshot is `ageMs` old, so a HIT near the end
* of the window is not kept a whole window more downstream.
* @param {'HIT'|'MISS'|'INFLIGHT'|'STALE-ERROR'} cacheState
* @param {string} [upstreamHost]
* @param {number|null} [contactedAt]
* @param {number} [ttlMs]
* @param {number} [ageMs] How old the snapshot is (ms); 0 for a fresh one.
* @returns {Record<string, string>}
*/
export function railResponseHeaders(
cacheState,
upstreamHost = '',
contactedAt = null,
ttlMs = TRANSIT_PROXY_TTL_MS,
ageMs = 0,
) {
const age = Number.isFinite(ageMs) && ageMs > 0 ? ageMs : 0;
return {
'Content-Type': 'application/json; charset=utf-8',
'Cache-Control':
cacheState === 'STALE-ERROR'
? 'no-store'
: `public, max-age=${Math.max(0, Math.ceil((ttlMs - age) / 1000))}`,
'X-GEV-Cache': cacheState,
...(upstreamHost ? { 'X-Rail-Upstream': upstreamHost } : {}),
...(Number.isFinite(contactedAt)
? { 'X-Rail-Contact': String(Math.floor(contactedAt)) }
: {}),
};
}
+586
View File
@@ -0,0 +1,586 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { PbfWriter } from 'pbf';
import {
RAIL_UPDATES_MAX_TRIPS,
RailFeedShapeError,
buildRailSnapshot,
buildRailTripUpdatesSnapshot,
railAdmissionGlobalMax,
railNaturalRequestsPerMinute,
railCacheStateFor,
railFeedTtlMs,
railMaxBodyBytes,
railResponseHeaders,
railUpstreamHeaders,
resolveRailRoute,
} from './railProxy.js';
import {
RAIL_FEED_REGISTRY,
getRailFeed,
getRegisteredRailFeed,
railFeedPositions,
} from './railFeeds.js';
/** A minimal TripUpdates FeedMessage: `[tripId, routeId, delay]` rows. */
function encodeTripUpdates(rows, { incrementality = null } = {}) {
const writer = new PbfWriter();
const header = new PbfWriter();
header.writeStringField(1, '2.0');
if (incrementality !== null) header.writeVarintField(2, incrementality);
header.writeVarintField(3, 1_794_000_000);
writer.writeBytesField(1, header.finish());
for (const [tripId, routeId, delay, stopCount = 1] of rows) {
const entity = new PbfWriter();
entity.writeStringField(1, tripId);
const update = new PbfWriter();
const trip = new PbfWriter();
trip.writeStringField(1, tripId);
if (routeId) trip.writeStringField(5, routeId);
update.writeBytesField(1, trip.finish());
for (let i = 0; i < stopCount; i += 1) {
const stop = new PbfWriter();
stop.writeVarintField(1, i + 1);
const arrival = new PbfWriter();
arrival.writeVarintField(1, delay);
stop.writeBytesField(2, arrival.finish());
stop.writeStringField(4, `s${i}`);
update.writeBytesField(2, stop.finish());
}
entity.writeBytesField(3, update.finish());
writer.writeBytesField(2, entity.finish());
}
return writer.finish();
}
const IRISH_XML = `<?xml version="1.0" encoding="utf-8"?>
<ArrayOfObjTrainPositions xmlns="http://api.irishrail.ie/realtime/">
<objTrainPositions>
<TrainStatus>R</TrainStatus>
<TrainLatitude>54.0</TrainLatitude>
<TrainLongitude>-6.4</TrainLongitude>
<TrainCode>A118</TrainCode>
<TrainDate>06 Nov 2026</TrainDate>
<PublicMessage>A118\\n14:50 - Dublin Connolly to Belfast (0 mins late)\\nDeparted Dundalk next stop Newry</PublicMessage>
<Direction>Northbound</Direction>
</objTrainPositions>
<objTrainPositions>
<TrainStatus>R</TrainStatus>
<TrainLatitude>53.29</TrainLatitude>
<TrainLongitude>-6.13</TrainLongitude>
<TrainCode>E931</TrainCode>
<TrainDate>06 Nov 2026</TrainDate>
<PublicMessage>E931\\n15:03 - Greystones to Howth (16 mins late)\\nDeparted Sutton next stop Howth</PublicMessage>
<Direction>Northbound</Direction>
</objTrainPositions>
</ArrayOfObjTrainPositions>`;
/** A minimal FeedMessage whose vehicles carry a trip route id. */
function encodeFeed({ incrementality = null, entities = [] }) {
const writer = new PbfWriter();
const header = new PbfWriter();
header.writeStringField(1, '2.0');
if (incrementality !== null) header.writeVarintField(2, incrementality);
header.writeVarintField(3, 1_700_000_000);
writer.writeBytesField(1, header.finish());
for (const entity of entities) {
const feedEntity = new PbfWriter();
feedEntity.writeStringField(1, entity.id);
const vehicle = new PbfWriter();
if (entity.route) {
const trip = new PbfWriter();
trip.writeStringField(1, `trip-${entity.id}`);
trip.writeStringField(5, entity.route);
vehicle.writeBytesField(1, trip.finish());
}
const position = new PbfWriter();
position.writeFloatField(1, entity.lat ?? 42.35);
position.writeFloatField(2, entity.lon ?? -71.06);
vehicle.writeBytesField(2, position.finish());
vehicle.writeVarintField(5, 1_699_999_990);
const descriptor = new PbfWriter();
descriptor.writeStringField(1, entity.id);
// A vendor extension (field 1999), as Adelaide Metro sends: it must be
// skipped, not fail the snapshot.
const extension = new PbfWriter();
extension.writeVarintField(1, 1);
descriptor.writeBytesField(1999, extension.finish());
vehicle.writeBytesField(8, descriptor.finish());
feedEntity.writeBytesField(4, vehicle.finish());
writer.writeBytesField(2, feedEntity.finish());
}
return writer.finish();
}
test('route resolution admits only the catalog and enabled rail feeds', () => {
assert.deepEqual(resolveRailRoute('/feeds'), { route: 'feeds' });
assert.deepEqual(resolveRailRoute('/feeds/?x=1'), { route: 'feeds' });
assert.equal(resolveRailRoute('/trains/mbta-rail')?.feed?.id, 'mbta-rail');
assert.equal(resolveRailRoute('/trains/mbta-rail/')?.feed?.id, 'mbta-rail');
assert.equal(resolveRailRoute('/trains/vre'), null, 'not registered');
assert.equal(
resolveRailRoute('/trains/mbta'),
null,
'a transit id is not a rail id',
);
assert.equal(resolveRailRoute('/vehicles/mbta-rail'), null);
assert.equal(resolveRailRoute('/trains/mbta-rail/extra'), null);
assert.equal(resolveRailRoute('/trains/..%2F..%2Fetc'), null);
assert.equal(resolveRailRoute('/trains/%E0%A4%A'), null);
assert.equal(resolveRailRoute(''), null);
assert.equal(resolveRailRoute(undefined), null);
});
test('path packs resolve for enabled rail feeds only', () => {
const route = resolveRailRoute('/paths/mta-lirr');
assert.equal(route?.route, 'paths');
assert.equal(route?.feed?.id, 'mta-lirr');
assert.equal(resolveRailRoute('/paths/mta-lirr/?v=1')?.route, 'paths');
assert.equal(resolveRailRoute('/trains/mta-lirr')?.route, 'trains');
assert.equal(resolveRailRoute('/paths/vre'), null, 'not registered');
assert.equal(resolveRailRoute('/paths/unknown'), null);
assert.equal(resolveRailRoute('/paths/'), null);
assert.equal(resolveRailRoute('/paths/mta-lirr/extra'), null);
assert.equal(resolveRailRoute('/paths/..%2F..%2Fetc%2Fpasswd'), null);
assert.equal(resolveRailRoute('/paths/mta-lirr.json'), null);
assert.equal(resolveRailRoute('/paths/%E0%A4%A'), null);
});
test('snapshots keep classified trains only and count what was dropped', () => {
const feed = getRailFeed('mbta-rail');
const snapshot = buildRailSnapshot(
feed,
encodeFeed({
entities: [
{ id: 'cr1', route: 'CR-Lowell' },
{ id: 'red1', route: 'Red' },
{ id: 'grn1', route: 'Green-D' },
{ id: 'bus1', route: '39' },
{ id: 'none' },
],
}),
1_700_000_000_000,
);
assert.equal(snapshot.feedId, 'mbta-rail');
assert.equal(snapshot.entityCount, 5);
assert.equal(snapshot.count, 3);
assert.equal(snapshot.dropped, 2);
assert.deepEqual(
snapshot.trains.map(({ id, category, mode }) => [id, category, mode]),
[
['cr1', 'local', 'rail'],
['red1', 'transit', 'metro'],
['grn1', 'transit', 'tram'],
],
);
assert.equal(snapshot.trains[0].timestampSource, 'vehicle');
assert.equal(snapshot.vehicles, undefined, 'buses never leave the server');
});
test('a rail-only feed keeps vehicles that carry no route', () => {
const snapshot = buildRailSnapshot(
getRailFeed('mta-metro-north'),
encodeFeed({ entities: [{ id: 'mnr1' }] }),
);
assert.equal(snapshot.count, 1);
assert.equal(snapshot.trains[0].category, 'local');
});
test('a differential feed is refused, as in the Transit proxy', () => {
assert.throws(
() =>
buildRailSnapshot(
getRailFeed('mbta-rail'),
encodeFeed({ incrementality: 1, entities: [] }),
),
RailFeedShapeError,
);
});
test('a body that is no FeedMessage is unreadable, not an empty snapshot', () => {
const feed = getRailFeed('mbta-rail');
const headerless = new PbfWriter();
const entity = new PbfWriter();
entity.writeStringField(1, 'x');
headerless.writeBytesField(2, entity.finish());
const versionless = new PbfWriter();
const header = new PbfWriter();
header.writeVarintField(3, 1_700_000_000);
versionless.writeBytesField(1, header.finish());
for (const [label, bytes] of [
['empty', new Uint8Array(0)],
['no header', headerless.finish()],
['no version', versionless.finish()],
['html', new TextEncoder().encode('<!DOCTYPE html><html></html>')],
['json', new TextEncoder().encode('{"error":"quota"}')],
]) {
for (const build of [buildRailSnapshot, buildRailTripUpdatesSnapshot])
assert.throws(
() => build(feed, bytes, 1_700_000_000_000),
(error) =>
error.code === 'UPSTREAM_UNREADABLE' &&
!(error instanceof RailFeedShapeError),
`${build.name}: ${label}`,
);
}
// A FeedMessage with its header and nothing else is a real empty feed.
const quiet = encodeFeed({ entities: [] });
assert.equal(buildRailSnapshot(feed, quiet).count, 0);
assert.equal(buildRailTripUpdatesSnapshot(feed, quiet).count, 0);
});
test('upstream headers identify the rail proxy and let a feed override Accept', () => {
const plain = railUpstreamHeaders(getRailFeed('mbta-rail'), {
etag: '"abc"',
lastModified: 'Thu, 01 Jan 2026 00:00:00 GMT',
});
assert.match(plain['User-Agent'], /gods-eye-view-rail-proxy/);
assert.equal(plain['If-None-Match'], '"abc"');
assert.equal(plain['If-Modified-Since'], 'Thu, 01 Jan 2026 00:00:00 GMT');
const adelaide = railUpstreamHeaders(getRegisteredRailFeed('adelaide-metro'));
assert.equal(adelaide.Accept, 'application/x-google-protobuf');
assert.equal(
railUpstreamHeaders(getRailFeed('irish-rail')).Accept,
'text/xml, application/xml;q=0.9',
);
});
test('response headers report cache state and operator contact', () => {
const fresh = railResponseHeaders('MISS', 'cdn.mbta.com', 1_700_000_000_123);
assert.equal(fresh['X-GEV-Cache'], 'MISS');
assert.equal(fresh['X-Rail-Upstream'], 'cdn.mbta.com');
assert.equal(fresh['X-Rail-Contact'], '1700000000123');
assert.match(fresh['Cache-Control'], /max-age=15/);
assert.equal(railResponseHeaders('STALE-ERROR')['Cache-Control'], 'no-store');
assert.equal(railResponseHeaders('HIT')['X-Rail-Contact'], undefined);
});
test('GTFS trains say their positions are GPS', () => {
const snapshot = buildRailSnapshot(
getRailFeed('mbta-rail'),
encodeFeed({ entities: [{ id: 'cr1', route: 'CR-Lowell' }] }),
);
assert.equal(snapshot.positions, 'gps');
assert.equal(snapshot.trains[0].positionSource, 'gps');
});
test('Irish Rail XML becomes classified, event-positioned trains', () => {
const now = 1_794_000_000_000;
const snapshot = buildRailSnapshot(
getRailFeed('irish-rail'),
new TextEncoder().encode(IRISH_XML),
now,
);
assert.equal(snapshot.feedId, 'irish-rail');
assert.equal(snapshot.positions, 'event');
assert.equal(snapshot.entityCount, 2);
assert.equal(snapshot.count, 2);
assert.equal(snapshot.feedTimestamp, null);
const byId = new Map(snapshot.trains.map((t) => [t.id, t]));
assert.equal(byId.get('A118').category, 'international');
assert.equal(byId.get('A118').positionSource, 'event');
assert.equal(byId.get('A118').timestampSource, 'fetch');
assert.equal(byId.get('A118').timestamp, now / 1000);
assert.equal(byId.get('E931').category, 'local');
assert.equal(byId.get('E931').delaySec, 960);
assert.throws(
() =>
buildRailSnapshot(
getRailFeed('irish-rail'),
new TextEncoder().encode('<html>Service Unavailable</html>'),
),
(error) =>
error.code === 'UPSTREAM_UNREADABLE' &&
!(error instanceof RailFeedShapeError),
);
});
test('no enabled feed is placed from its timetable', () => {
// Every train is where its operator reports it: no feed answers `/trains`
// with a timetable-only list.
for (const feed of RAIL_FEED_REGISTRY.filter((f) => f.defaultEnabled))
assert.ok(
['gps', 'event'].includes(railFeedPositions(feed)) &&
typeof feed.url === 'string',
feed.id,
);
});
test('trip updates keep rail trips only, with category, and refuse differential feeds', () => {
const feed = getRailFeed('mbta-rail');
const snapshot = buildRailTripUpdatesSnapshot(
feed,
encodeTripUpdates([
['cr', 'CR-Worcester', 120],
['red', 'Red', -30],
['bus', '39', 60],
['none', null, 0],
]),
5_000,
);
assert.equal(snapshot.feedId, 'mbta-rail');
assert.equal(snapshot.fetchedAt, 5_000);
assert.equal(snapshot.feedTimestamp, 1_794_000_000);
assert.equal(snapshot.count, 2);
assert.equal(snapshot.dropped, 2);
assert.deepEqual(
snapshot.trips.map((t) => [t.tripId, t.routeId, t.delaySec, t.category]),
[
['cr', 'CR-Worcester', 120, 'local'],
['red', 'Red', -30, 'transit'],
],
);
assert.deepEqual(snapshot.trips[0].stops[0], {
stopId: 's0',
stopSequence: 1,
arrival: { time: null, delay: 120 },
departure: null,
});
assert.throws(
() =>
buildRailTripUpdatesSnapshot(
feed,
encodeTripUpdates([], { incrementality: 1 }),
),
RailFeedShapeError,
);
});
test('a train named by its number takes its run, never a timetable position', () => {
const now = 1_794_000_000_000;
const bytes = new TextEncoder().encode(IRISH_XML);
const plain = buildRailSnapshot(getRailFeed('irish-rail'), bytes, now);
const named = buildRailSnapshot(getRailFeed('irish-rail'), bytes, now, {
tripFor: (code) => (code === 'A118' ? 'pack-trip' : null),
routeFor: (tripId) =>
tripId === 'pack-trip' ? 'A~X~DUB-EUROPORT-I' : null,
});
const at = (snapshot) =>
Object.fromEntries(
snapshot.trains.map((t) => [t.id, [t.lat, t.lon, t.positionSource]]),
);
assert.deepEqual(at(named), at(plain), 'positions as reported');
const train = named.trains.find((t) => t.id === 'A118');
assert.equal(train.tripId, 'pack-trip');
assert.equal(train.trainNumber, 'A118');
});
test('trip updates are kept by their own route', () => {
const feed = getRailFeed('mbta-rail');
const snapshot = buildRailTripUpdatesSnapshot(
feed,
encodeTripUpdates([
['cr', 'CR-Worcester', 120],
['bus', '39', 60],
]),
5_000,
{ routeFor: () => null },
);
assert.deepEqual(
snapshot.trips.map((t) => [t.tripId, t.routeId]),
[['cr', 'CR-Worcester']],
);
assert.equal(snapshot.dropped, 1);
});
test('trip update answers are capped in trips', () => {
const rows = Array.from({ length: RAIL_UPDATES_MAX_TRIPS + 2 }, (_, i) => [
`t${i}`,
'CR-Lowell',
0,
]);
const snapshot = buildRailTripUpdatesSnapshot(
getRailFeed('mbta-rail'),
encodeTripUpdates(rows),
);
assert.equal(snapshot.count, RAIL_UPDATES_MAX_TRIPS);
assert.equal(snapshot.truncated, true);
assert.equal(snapshot.dropped, 0, 'capped trips are rail, not dropped');
});
test('/updates resolves only for feeds that publish trip updates', () => {
assert.equal(resolveRailRoute('/updates/mbta-rail')?.route, 'updates');
assert.equal(resolveRailRoute('/updates/marc')?.feed?.id, 'marc');
assert.equal(resolveRailRoute('/updates/irish-rail'), null, 'no updates');
assert.equal(resolveRailRoute('/updates/capmetro-rail'), null);
assert.equal(resolveRailRoute('/updates/vre'), null, 'not registered');
assert.equal(resolveRailRoute('/updates/mbta-rail/x'), null);
});
test('feed windows: own interval when set, a floor, and per-route defaults', () => {
assert.equal(railFeedTtlMs(getRailFeed('mbta-rail')), 15_000);
assert.equal(railFeedTtlMs(getRailFeed('mbta-rail'), 'updates'), 30_000);
assert.equal(railFeedTtlMs(getRailFeed('irish-rail')), 30_000);
assert.equal(railFeedTtlMs(getRailFeed('adelaide-metro'), 'updates'), 60_000);
assert.equal(railFeedTtlMs({ pollIntervalMs: 10 }), 5_000);
assert.equal(railMaxBodyBytes(getRailFeed('irish-rail')), 1024 * 1024);
assert.equal(railMaxBodyBytes(getRailFeed('mbta-rail')), 8 * 1024 * 1024);
assert.equal(railCacheStateFor(null, 0), 'none');
assert.equal(railCacheStateFor({ at: 0 }, 29_000, 30_000), 'fresh');
assert.equal(railCacheStateFor({ at: 0 }, 31_000, 30_000), 'stale');
assert.equal(railCacheStateFor({ at: 0 }, 11 * 60_000, 30_000), 'expired');
});
test('response headers follow the feed window', () => {
assert.match(
railResponseHeaders('MISS', 'h', null, 60_000)['Cache-Control'],
/max-age=60/,
);
// An older snapshot is kept downstream only for the rest of its window.
const maxAge = (ageMs) =>
railResponseHeaders('HIT', 'h', null, 60_000, ageMs)['Cache-Control'];
assert.equal(maxAge(45_000), 'public, max-age=15');
assert.equal(maxAge(59_200), 'public, max-age=1');
assert.equal(maxAge(60_000), 'public, max-age=0');
assert.equal(maxAge(-5), 'public, max-age=60', 'a clock step is no age');
});
test('/schedule resolves for every pollable feed', () => {
assert.equal(resolveRailRoute('/schedule/ktmb')?.route, 'schedule');
assert.equal(
resolveRailRoute('/schedule/irish-rail')?.feed?.id,
'irish-rail',
);
assert.equal(resolveRailRoute('/schedule/mbta-rail')?.route, 'schedule');
assert.equal(resolveRailRoute('/schedule/vre'), null, 'not registered');
assert.equal(resolveRailRoute('/schedule/ktmb/x'), null);
assert.equal(resolveRailRoute('/schedule/..%2Fktmb'), null);
});
test('the global admission cap scales with the registry', () => {
const natural = railNaturalRequestsPerMinute();
const cap = railAdmissionGlobalMax();
assert.ok(natural > 40, 'the registry outgrew the old fixed cap');
assert.ok(
cap >= natural * 1.5,
'room for retries on top of the natural load',
);
assert.equal(railAdmissionGlobalMax([]), 40, 'never below the Transit floor');
const one = [{ defaultEnabled: true, url: 'https://x.test/vp' }];
assert.equal(railNaturalRequestsPerMinute(one), 4, 'one feed at 15 s');
const updatesOnly = [
{ defaultEnabled: true, tripUpdatesUrl: 'https://x.test/tu' },
];
assert.equal(railNaturalRequestsPerMinute(updatesOnly), 2, 'no positions');
assert.equal(
railNaturalRequestsPerMinute([{ ...one[0], defaultEnabled: false }]),
0,
);
});
/** Vehicles with a trip id and no route or time, as Renfe sends them. */
function encodeRenfeLike(headerTime, trips) {
const writer = new PbfWriter();
const header = new PbfWriter();
header.writeStringField(1, '2.0');
header.writeVarintField(3, headerTime);
writer.writeBytesField(1, header.finish());
for (const [id, tripId, route] of trips) {
const entity = new PbfWriter();
entity.writeStringField(1, id);
const vehicle = new PbfWriter();
const trip = new PbfWriter();
trip.writeStringField(1, tripId);
if (route) trip.writeStringField(5, route);
vehicle.writeBytesField(1, trip.finish());
const position = new PbfWriter();
position.writeFloatField(1, 40.4);
position.writeFloatField(2, -3.7);
vehicle.writeBytesField(2, position.finish());
const descriptor = new PbfWriter();
descriptor.writeStringField(1, id);
vehicle.writeBytesField(8, descriptor.finish());
entity.writeBytesField(4, vehicle.finish());
writer.writeBytesField(2, entity.finish());
}
return writer.finish();
}
test('a feed with an untrusted header clock stamps its trains with the fetch time', () => {
const now = 1_794_000_000_000;
// Renfe writes local time as UTC: the header reads an hour behind.
const bytes = encodeRenfeLike(now / 1000 - 3600, [
['04192', '0419212026-11-06'],
]);
const routes = new Map([['0419212026-11-06', 'ALVIA~X~1700037606GL023']]);
const snapshot = buildRailSnapshot(
getRailFeed('renfe-larga-distancia'),
bytes,
now,
{
routeFor: (tripId) => routes.get(tripId) ?? null,
},
);
assert.equal(snapshot.count, 1);
const [train] = snapshot.trains;
assert.equal(train.timestampSource, 'fetch');
assert.equal(train.timestamp, now / 1000, 'not the header time');
assert.equal(
snapshot.feedTimestamp,
null,
'the header clock is not reported',
);
assert.equal(
train.routeId,
'ALVIA~X~1700037606GL023',
'from the schedule pack',
);
assert.equal(train.category, 'national');
// A trusted feed keeps the header ladder.
const trusted = buildRailSnapshot(
getRailFeed('mta-metro-north'),
encodeRenfeLike(now / 1000 - 5, [['mnr1', 't1']]),
now,
);
assert.equal(trusted.trains[0].timestampSource, 'header');
});
test('a trip the schedule pack does not know is dropped, not guessed', () => {
const snapshot = buildRailSnapshot(
getRailFeed('renfe-larga-distancia'),
encodeRenfeLike(1_794_000_000, [
['a', 'known'],
['b', 'unknown'],
]),
1_794_000_000_000,
{ routeFor: (tripId) => (tripId === 'known' ? 'MD~S~1' : null) },
);
assert.deepEqual(
snapshot.trains.map((t) => [t.id, t.category]),
[['a', 'regional']],
);
assert.equal(snapshot.dropped, 1);
// Without a lookup nothing in this feed can be classified.
const blind = buildRailSnapshot(
getRailFeed('renfe-larga-distancia'),
encodeRenfeLike(1_794_000_000, [['a', 'known']]),
);
assert.equal(blind.count, 0);
});
test('trip updates take their route from the schedule pack too, and carry the tourist flag', () => {
const snapshot = buildRailTripUpdatesSnapshot(
getRailFeed('renfe-larga-distancia'),
encodeTripUpdates([
['0419212026-11-06', null, 60],
['999', null, 0],
]),
5_000,
{
routeFor: (tripId) =>
tripId === '0419212026-11-06' ? 'ALVIA~X~1700037606GL023' : null,
},
);
assert.deepEqual(
snapshot.trips.map((t) => [t.tripId, t.routeId, t.category]),
[['0419212026-11-06', 'ALVIA~X~1700037606GL023', 'national']],
);
assert.equal(snapshot.dropped, 1, 'the trip the pack does not know');
const flam = buildRailSnapshot(
getRailFeed('entur-vy'),
encodeFeed({ entities: [{ id: 'flam', route: 'VYG:Line:R45' }] }),
);
assert.equal(flam.trains[0].tourist, true);
assert.equal(flam.trains[0].category, 'regional');
});
+741
View File
@@ -0,0 +1,741 @@
import {
dayNumberOf,
formatClock,
isTimeZone,
parseServiceDate,
serviceDayOriginMs,
} from './railTimeZones.js';
/**
* @module railSchedule
* @description Timetable tier of the Rail layer: which trains run now
* according to the operator's static GTFS, where along their line the
* timetable puts them (only to match a live train to its run, never drawn),
* and the stop list a train card shows.
*
* Schedule packs come from scripts/build-rail-paths.mjs (`<feedId>.schedule.json`).
* Service calendars are resolved to concrete dates at build time, so this
* module never evaluates a calendar. Stop times are seconds after the service
* day's GTFS origin (noon minus 12 h, agency time zone) and may exceed 24 h.
*
* Realtime delays follow GTFS-RT TripUpdate semantics:
*
* delays = { [tripId]: { delaySec?, startDate?, relationship?, stops?: [{
* stopId? | stopSequence?, relationship?,
* arrival?: { time?, delay? }, departure?: { time?, delay? } }] } }
*
* (the trip records of src/data/railTripUpdates.js, keyed by trip id). A
* trip `relationship` of 'CANCELED' or 'DELETED' drops the run from
* activeTrips; a stop `relationship` of 'SKIPPED' (or `skipped: true`) is
* passed without a stop, and one of 'NO_DATA' has no prediction: that stop
* and the stops after it keep their timetable times until the next update.
*
* `time` is POSIX seconds (milliseconds are accepted too), `delay` seconds.
* A stop update's delay carries on to later stops until the next update;
* stops before the first update use the trip's `delaySec` (else the
* timetable). `startDate` ('YYYYMMDD' or 'YYYY-MM-DD') pins the entry to one
* run of a trip that runs on several days.
*
* Clock strings are 24-hour 'HH:MM' in each STATION's own time zone.
*
* Pure: no Cesium, no DOM, no I/O.
*/
/** Schedule-pack format this module reads. */
export const RAIL_SCHEDULE_PACK_VERSION = 1;
/** Earliest a delayed or early train is looked for around its timetable (ms). */
const EARLY_SLACK_MS = 60 * 60_000;
const LATE_SLACK_MS = 12 * 60 * 60_000;
const MINUS = '−';
/** TripUpdate relationships under which a scheduled run does not run. */
const CANCELED = new Set(['CANCELED', 'DELETED']);
/**
* A relative time chip as the Launches layer writes its countdown: `T−4`
* for an event four minutes ahead, `T+3` for one three minutes past. Minutes
* round up toward the event (Math.ceil, as the Launches countdown rounds its
* seconds), so `T−1` shows until the moment itself and `T+0` for the first
* minute after. An hour or more reads `T−1:05`.
* @param {number} deltaMs Event time minus now.
* @returns {string}
*/
export function formatRelative(deltaMs) {
if (!Number.isFinite(deltaMs)) return '';
const minutes = Math.ceil(deltaMs / 60_000);
const sign = deltaMs > 0 ? MINUS : '+';
const total = Math.abs(minutes);
const text =
total >= 60
? `${Math.floor(total / 60)}:${String(total % 60).padStart(2, '0')}`
: String(total);
return `T${sign}${text}`;
}
const isIndex = (value, length) =>
Number.isInteger(value) && value >= 0 && value < length;
/** Largest delay a live report may state, either way (s): a day. */
const LIVE_DELAY_MAX_S = 86_400;
/**
* The delay a live train's own report states (`delaySec`: Irish Rail's
* public message, SIRI VM's `Delay`), for a feed that publishes no trip
* updates; null when it states none, or more than a day either way (a unit
* error, not a late train).
* @param {{delaySec?: unknown}|null|undefined} record
* @returns {number|null} Seconds, positive when late.
*/
export function liveDelaySec(record) {
const value = record?.delaySec;
return typeof value === 'number' &&
Number.isFinite(value) &&
Math.abs(value) <= LIVE_DELAY_MAX_S
? value
: null;
}
/**
* Validate and index a decoded schedule pack.
* @param {object} raw The JSON body of `<feedId>.schedule.json`.
* @returns {object} A schedule for the functions below.
*/
export function createSchedule(raw) {
if (
!raw ||
raw.version !== RAIL_SCHEDULE_PACK_VERSION ||
typeof raw.feedId !== 'string' ||
!Array.isArray(raw.stops) ||
!Array.isArray(raw.patterns) ||
!Array.isArray(raw.profiles) ||
!raw.trips ||
typeof raw.trips !== 'object' ||
!raw.services ||
typeof raw.services !== 'object'
)
throw new TypeError('Malformed rail schedule pack');
const timezone = isTimeZone(raw.timezone) ? raw.timezone : 'UTC';
const stops = raw.stops.map((stop, index) => ({
index,
id: String(stop?.id ?? ''),
name: String(stop?.name ?? ''),
lat: Number(stop?.lat),
lon: Number(stop?.lon),
parent: isIndex(stop?.parent, raw.stops.length) ? stop.parent : null,
platform: stop?.platform ? String(stop.platform) : null,
ownZone: isTimeZone(stop?.tz) ? stop.tz : null,
}));
for (const stop of stops) {
const parent = stop.parent === null ? null : stops[stop.parent];
stop.timezone = stop.ownZone ?? parent?.ownZone ?? timezone;
delete stop.ownZone;
Object.freeze(stop);
}
const stopIndexById = new Map(stops.map((stop) => [stop.id, stop.index]));
const patterns = raw.patterns.map((pattern, index) => {
const list = Array.isArray(pattern?.stops) ? pattern.stops : [];
const n = list.length;
if (n < 2 || !list.every((value) => isIndex(value, stops.length)))
throw new TypeError(`Malformed rail schedule pattern ${index}`);
const dist =
Array.isArray(pattern.dist) && pattern.dist.length === n
? pattern.dist.map(Number)
: new Array(n).fill(0);
const seq =
Array.isArray(pattern.seq) && pattern.seq.length === n
? pattern.seq.map(Number)
: list.map((_, k) => k + 1);
return Object.freeze({
index,
shape: Number.isInteger(pattern.shape) ? pattern.shape : null,
stops: Object.freeze(list.slice()),
seq: Object.freeze(seq),
dist: Object.freeze(dist),
pass: Object.freeze(
Array.isArray(pattern.pass) && pattern.pass.length === n
? pattern.pass.map((value) => value === 1)
: new Array(n).fill(false),
),
});
});
const origins = new Map();
const originOf = (date) => {
let origin = origins.get(date);
if (origin === undefined) {
origin = serviceDayOriginMs(date, timezone);
origins.set(date, origin);
}
return origin;
};
const trips = new Map();
const instances = [];
let maxDurationMs = 0;
for (const [tripId, value] of Object.entries(raw.trips)) {
const pattern = patterns[value?.pattern];
const profile = raw.profiles[value?.profile];
if (!pattern || !Array.isArray(profile)) continue;
if (profile.length !== pattern.stops.length * 2) continue;
const startSec = Number(value.startSec);
if (!Number.isFinite(startSec)) continue;
const trip = Object.freeze({
id: tripId,
pattern,
offsets: profile,
startSec,
routeId: value.route == null ? null : String(value.route),
service: String(value.service ?? ''),
headsign: value.headsign ? String(value.headsign) : null,
name: value.name ? String(value.name) : null,
direction: Number.isInteger(value.direction) ? value.direction : null,
});
trips.set(tripId, trip);
const dates = raw.services[trip.service];
if (!Array.isArray(dates)) continue;
const durationMs = profile[profile.length - 1] * 1000;
if (durationMs > maxDurationMs) maxDurationMs = durationMs;
for (const date of dates) {
if (!parseServiceDate(date)) continue;
const startMs = originOf(date) + startSec * 1000;
if (Number.isFinite(startMs))
instances.push({
trip,
serviceDate: date,
startMs,
endMs: startMs + durationMs,
});
}
}
instances.sort((a, b) => a.startMs - b.startMs);
const runsByTrip = new Map();
for (const instance of instances) {
let list = runsByTrip.get(instance.trip.id);
if (!list) runsByTrip.set(instance.trip.id, (list = []));
list.push(instance);
}
return Object.freeze({
feedId: raw.feedId,
/**
* The `builtAt` of the path pack this timetable's shape indices point
* into (written by the same build), or null in packs that predate it.
*/
pathsBuiltAt:
typeof raw.pathsBuiltAt === 'string' ? raw.pathsBuiltAt : null,
timezone,
window: raw.window ?? null,
routes: raw.routes && typeof raw.routes === 'object' ? raw.routes : {},
stops: Object.freeze(stops),
patterns: Object.freeze(patterns),
trips,
stopIndexById,
instances: Object.freeze(instances),
runsByTrip,
instanceStarts: Float64Array.from(
instances,
(instance) => instance.startMs,
),
maxDurationMs,
});
}
/**
* When the last run a decoded schedule pack holds arrives (epoch ms): past
* it the pack's window has ended, and it names no train that can still be
* running. Each trip counts on the latest date of its service. Read from the
* raw pack, without indexing it (the server checks a pack it reads only for
* its routes). Null when the pack names no window (`window.to`), so its end
* is not known; -Infinity when it holds no run.
* @param {object} raw The JSON body of `<feedId>.schedule.json`.
* @returns {number|null}
*/
export function schedulePackEndMs(raw) {
if (!parseServiceDate(raw?.window?.to)) return null;
const trips = raw?.trips && typeof raw.trips === 'object' ? raw.trips : {};
const services =
raw?.services && typeof raw.services === 'object' ? raw.services : {};
const profiles = Array.isArray(raw?.profiles) ? raw.profiles : [];
const zone = isTimeZone(raw?.timezone) ? raw.timezone : 'UTC';
/** Service id → the origin of its latest date (-Infinity: no date). */
const lastOrigin = new Map();
const latestOrigin = (service) => {
let origin = lastOrigin.get(service);
if (origin !== undefined) return origin;
const dates = Object.hasOwn(services, service) ? services[service] : null;
let latest = -Infinity;
let latestDate = null;
for (const date of Array.isArray(dates) ? dates : []) {
const day = dayNumberOf(date);
if (day > latest) {
latest = day;
latestDate = date;
}
}
origin = latestDate === null ? NaN : serviceDayOriginMs(latestDate, zone);
if (!Number.isFinite(origin)) origin = -Infinity;
lastOrigin.set(service, origin);
return origin;
};
let end = -Infinity;
for (const trip of Object.values(trips)) {
const profile = profiles[trip?.profile];
const startSec = Number(trip?.startSec);
if (!Array.isArray(profile) || !Number.isFinite(startSec)) continue;
const origin = latestOrigin(String(trip.service ?? ''));
if (origin === -Infinity) continue;
const durationSec = Number(profile[profile.length - 1]) || 0;
end = Math.max(end, origin + (startSec + durationSec) * 1000);
}
return end;
}
/** First index whose start is greater than `ms`. */
function upperBound(starts, ms) {
let lo = 0;
let hi = starts.length;
while (lo < hi) {
const mid = (lo + hi) >> 1;
if (starts[mid] <= ms) lo = mid + 1;
else hi = mid;
}
return lo;
}
/** The public view of one run of a trip. */
function runOf(instance) {
const { trip } = instance;
return {
tripId: trip.id,
serviceDate: instance.serviceDate,
routeId: trip.routeId,
headsign: trip.headsign,
name: trip.name,
direction: trip.direction,
pattern: trip.pattern.index,
shape: trip.pattern.shape,
scheduledStartMs: instance.startMs,
scheduledEndMs: instance.endMs,
};
}
/** The delay entry for a run, honouring a `startDate` pin. */
function delayFor(delays, run) {
const entry =
delays && Object.hasOwn(delays, run.tripId) ? delays[run.tripId] : null;
if (!entry || typeof entry !== 'object') return null;
if (entry.startDate != null) {
const pinned = parseServiceDate(entry.startDate);
const own = parseServiceDate(run.serviceDate);
if (
!pinned ||
!own ||
pinned.year !== own.year ||
pinned.month !== own.month ||
pinned.day !== own.day
)
return null;
}
return entry;
}
const toMs = (time) => {
const value = Number(time);
if (!Number.isFinite(value) || value <= 0) return NaN;
return value > 1e11 ? value : value * 1000;
};
/** The pattern index each stop update applies to, in order. */
function matchUpdates(schedule, pattern, updates) {
const byIndex = new Map();
let from = 0;
for (const update of updates) {
if (!update || typeof update !== 'object') continue;
let found = -1;
for (let pass = 0; pass < 2 && found < 0; pass++) {
const start = pass === 0 ? from : 0;
for (let k = start; k < pattern.stops.length; k++) {
if (stopMatches(schedule, pattern, k, update)) {
found = k;
break;
}
}
}
if (found < 0) continue;
byIndex.set(found, update);
from = found + 1;
}
return byIndex;
}
function stopMatches(schedule, pattern, k, update) {
if (update.stopSequence != null && update.stopSequence !== '')
return Number(update.stopSequence) === pattern.seq[k];
if (update.stopId == null) return false;
const id = String(update.stopId);
const stop = schedule.stops[pattern.stops[k]];
if (stop.id === id) return true;
if (stop.parent !== null && schedule.stops[stop.parent].id === id)
return true;
const other = schedule.stopIndexById.get(id);
if (other === undefined) return false;
const otherParent = schedule.stops[other].parent;
return otherParent !== null && otherParent === (stop.parent ?? stop.index);
}
/** Whether a stop update carries this StopTimeUpdate relationship. */
function stopRelationshipIs(update, relationship) {
return (
update.relationship === relationship ||
update.scheduleRelationship === relationship
);
}
/**
* Scheduled and expected times of every stop of a run.
* @returns {{schedArr: number[], schedDep: number[], arr: number[],
* dep: number[], skipped: boolean[], hasRealtime: boolean}}
*/
function runTimes(schedule, instance, delays) {
const { trip } = instance;
const n = trip.pattern.stops.length;
const schedArr = new Array(n);
const schedDep = new Array(n);
for (let k = 0; k < n; k++) {
schedArr[k] = instance.startMs + trip.offsets[2 * k] * 1000;
schedDep[k] = instance.startMs + trip.offsets[2 * k + 1] * 1000;
}
const arr = schedArr.slice();
const dep = schedDep.slice();
const skipped = new Array(n).fill(false);
const entry = delayFor(delays, {
tripId: trip.id,
serviceDate: instance.serviceDate,
});
if (!entry)
return { schedArr, schedDep, arr, dep, skipped, hasRealtime: false };
const updates = matchUpdates(
schedule,
trip.pattern,
Array.isArray(entry.stops) ? entry.stops : [],
);
let carried = Number.isFinite(Number(entry.delaySec))
? Number(entry.delaySec)
: 0;
for (let k = 0; k < n; k++) {
const update = updates.get(k);
let arrDelay = carried;
let depDelay = carried;
if (update && stopRelationshipIs(update, 'NO_DATA')) {
// No prediction (GTFS-RT NO_DATA): the delay carried so far no longer
// holds, here or at the stops after it.
carried = 0;
arrDelay = 0;
depDelay = 0;
} else if (update) {
if (update.skipped === true || stopRelationshipIs(update, 'SKIPPED'))
skipped[k] = true;
const a = update.arrival ?? null;
const d = update.departure ?? null;
const aTime = toMs(a?.time);
const dTime = toMs(d?.time);
const aDelay = Number(a?.delay);
const dDelay = Number(d?.delay);
let arrivalGiven = true;
if (Number.isFinite(aTime)) arrDelay = (aTime - schedArr[k]) / 1000;
else if (a && a.delay != null && Number.isFinite(aDelay))
arrDelay = aDelay;
else arrivalGiven = false;
if (Number.isFinite(dTime)) depDelay = (dTime - schedDep[k]) / 1000;
else if (d && d.delay != null && Number.isFinite(dDelay))
depDelay = dDelay;
else if (arrivalGiven) depDelay = arrDelay;
else depDelay = carried;
if (!arrivalGiven && (Number.isFinite(dTime) || (d && d.delay != null)))
arrDelay = Math.min(carried, depDelay);
carried = depDelay;
}
arr[k] = schedArr[k] + arrDelay * 1000;
dep[k] = schedDep[k] + depDelay * 1000;
}
// Predictions are not always consistent; time never runs backwards.
for (let k = 0; k < n; k++) {
if (k > 0 && arr[k] < dep[k - 1]) arr[k] = dep[k - 1];
if (dep[k] < arr[k]) dep[k] = arr[k];
}
return { schedArr, schedDep, arr, dep, skipped, hasRealtime: true };
}
/** The instance of `trip` (a run object or a trip id) meant at `nowMs`. */
function resolveInstance(schedule, trip, nowMs, delays) {
const pinned = trip && typeof trip === 'object';
const runs = schedule.runsByTrip.get(
String((pinned ? trip.tripId : trip) ?? ''),
);
if (!runs) return null;
if (pinned && trip.serviceDate != null) {
const match = runs.find(
(instance) => instance.serviceDate === trip.serviceDate,
);
if (match) return match;
}
let best = null;
let bestScore = Infinity;
for (const instance of runs) {
const times = runTimes(schedule, instance, delays);
const start = times.dep[0];
const end = times.arr[times.arr.length - 1];
// Running now wins; else the nearest run, upcoming before past.
const score =
nowMs >= start && nowMs <= end
? -1
: nowMs < start
? start - nowMs
: (nowMs - end) * 2;
if (score < bestScore) {
bestScore = score;
best = instance;
}
}
return best;
}
/**
* Trains the timetable has running at `nowMs`: from the departure at the
* first stop to the arrival at the last, shifted by realtime delays.
* @param {object} schedule From createSchedule.
* @param {number} nowMs
* @param {{delays?: object, beforeMs?: number, afterMs?: number}} [options]
* `beforeMs` / `afterMs` widen the window (a train waiting at its origin,
* one just arrived).
* @returns {object[]} Runs: {tripId, serviceDate, routeId, headsign, name,
* direction, pattern, shape, scheduledStartMs, scheduledEndMs,
* expectedStartMs, expectedEndMs}.
*/
export function activeTrips(
schedule,
nowMs,
{ delays = null, beforeMs = 0, afterMs = 0 } = {},
) {
if (!schedule || !Number.isFinite(nowMs)) return [];
const lead = Math.max(0, beforeMs);
const tail = Math.max(0, afterMs);
const last = upperBound(
schedule.instanceStarts,
nowMs + lead + EARLY_SLACK_MS,
);
const floor = nowMs - tail - LATE_SLACK_MS - schedule.maxDurationMs;
const out = [];
for (let i = last - 1; i >= 0; i--) {
const instance = schedule.instances[i];
if (instance.startMs < floor) break;
const run = runOf(instance);
let start = instance.startMs + instance.trip.offsets[1] * 1000;
let end = instance.endMs;
const entry = delayFor(delays, run);
if (entry && CANCELED.has(entry.relationship)) continue;
if (entry) {
const times = runTimes(schedule, instance, delays);
start = times.dep[0];
end = times.arr[times.arr.length - 1];
} else if (instance.endMs < nowMs - tail) continue;
if (nowMs < start - lead || nowMs > end + tail) continue;
run.expectedStartMs = start;
run.expectedEndMs = end;
out.push(run);
}
return out.reverse();
}
/**
* Where the timetable puts a train at `nowMs`, along its pattern's shape.
* Between two stops the arc runs linearly in time from the departure to the
* next arrival; during a dwell it holds at the stop. Before the first
* departure it waits at the origin, after the last arrival at the terminus.
*
* @param {object} schedule From createSchedule.
* @param {object|string} trip A run from activeTrips, or a trip id.
* @param {number} nowMs
* @param {object} [delays]
* @returns {{tripId: string, serviceDate: string, shape: number|null,
* s: number, prevStop: number, nextStop: number,
* prevStopId: string|null, nextStopId: string|null, dwell: boolean,
* state: 'before'|'running'|'arrived', fraction: number, delaySec: number,
* lat?: number, lon?: number}|null} Stop fields are pattern indices (-1 for
* none). `lat`/`lon` interpolate between the stops and are set only when
* the pattern has no shape.
*/
export function scheduledPosition(schedule, trip, nowMs, delays = null) {
if (!schedule || !Number.isFinite(nowMs)) return null;
const instance = resolveInstance(schedule, trip, nowMs, delays);
if (!instance) return null;
const { pattern } = instance.trip;
const times = runTimes(schedule, instance, delays);
// Skipped stops are passed without a stop: their times do not pace the run.
const nodes = [];
for (let k = 0; k < pattern.stops.length; k++)
if (!times.skipped[k]) nodes.push(k);
if (nodes.length < 2)
nodes.splice(0, nodes.length, 0, pattern.stops.length - 1);
const result = {
tripId: instance.trip.id,
serviceDate: instance.serviceDate,
shape: pattern.shape,
s: 0,
prevStop: -1,
nextStop: -1,
prevStopId: null,
nextStopId: null,
dwell: false,
state: 'running',
fraction: 0,
delaySec: 0,
};
const first = nodes[0];
const lastNode = nodes[nodes.length - 1];
let at = -1;
let from = -1;
let to = -1;
if (nowMs < times.dep[first]) {
result.state = 'before';
at = first;
result.prevStop = -1;
result.nextStop = first;
} else if (nowMs >= times.arr[lastNode]) {
result.state = 'arrived';
at = lastNode;
result.prevStop = lastNode;
result.nextStop = -1;
} else {
for (let j = 0; j < nodes.length; j++) {
const k = nodes[j];
if (nowMs >= times.arr[k] && nowMs < times.dep[k]) {
at = k;
result.prevStop = k;
result.nextStop = j + 1 < nodes.length ? nodes[j + 1] : -1;
break;
}
if (
j + 1 < nodes.length &&
nowMs >= times.dep[k] &&
nowMs < times.arr[nodes[j + 1]]
) {
from = k;
to = nodes[j + 1];
break;
}
}
}
if (at >= 0) {
result.dwell = true;
result.s = pattern.dist[at];
result.fraction = 0;
result.delaySec = Math.round(
(result.state === 'arrived'
? times.arr[at] - times.schedArr[at]
: times.dep[at] - times.schedDep[at]) / 1000,
);
} else {
const span = times.arr[to] - times.dep[from];
const fraction =
span > 0 ? Math.min(1, Math.max(0, (nowMs - times.dep[from]) / span)) : 1;
result.prevStop = from;
result.nextStop = to;
result.fraction = fraction;
result.s =
pattern.dist[from] + (pattern.dist[to] - pattern.dist[from]) * fraction;
result.delaySec = Math.round((times.arr[to] - times.schedArr[to]) / 1000);
}
if (result.prevStop >= 0)
result.prevStopId = schedule.stops[pattern.stops[result.prevStop]].id;
if (result.nextStop >= 0)
result.nextStopId = schedule.stops[pattern.stops[result.nextStop]].id;
if (pattern.shape === null) {
const a =
schedule.stops[
pattern.stops[result.prevStop >= 0 ? result.prevStop : result.nextStop]
];
const b = result.dwell ? a : schedule.stops[pattern.stops[result.nextStop]];
result.lat = a.lat + (b.lat - a.lat) * result.fraction;
result.lon = a.lon + (b.lon - a.lon) * result.fraction;
}
return result;
}
/**
* A run's stop list for a train card.
*
* `state` is 'passed' once the train has left (or, at the terminus, reached)
* the stop, 'next' for the first stop not yet passed (with `atStop` while the
* train dwells there) and 'upcoming' after it. `relative` is the chip from
* formatRelative: for a passed stop the departure (terminus: arrival), for
* the stop the train stands at its departure, else the arrival.
*
* @param {object} schedule
* @param {object|string} trip A run from activeTrips, or a trip id.
* @param {number} nowMs
* @param {object} [delays]
* @returns {object[]} Per stop: {index, stopId, name, platform, parentId,
* parentName, lat, lon, timezone, scheduledArrivalMs,
* scheduledDepartureMs, expectedArrivalMs, expectedDepartureMs,
* arrivalDelaySec, departureDelaySec, scheduledArrival,
* scheduledDeparture, expectedArrival, expectedDeparture (local 'HH:MM'),
* passThrough, skipped, realtime, state, atStop, relative, relativeMs}.
*/
export function tripStops(schedule, trip, nowMs, delays = null) {
if (!schedule || !Number.isFinite(nowMs)) return [];
const instance = resolveInstance(schedule, trip, nowMs, delays);
if (!instance) return [];
const { pattern } = instance.trip;
const times = runTimes(schedule, instance, delays);
const n = pattern.stops.length;
const out = [];
let nextFound = false;
for (let k = 0; k < n; k++) {
const stop = schedule.stops[pattern.stops[k]];
const parent = stop.parent === null ? null : schedule.stops[stop.parent];
const zone = stop.timezone;
const terminus = k === n - 1;
const leftAt = terminus ? times.arr[k] : times.dep[k];
let state;
let atStop = false;
if (nowMs >= leftAt) state = 'passed';
else if (!nextFound) {
state = 'next';
nextFound = true;
atStop = nowMs >= times.arr[k] && !times.skipped[k];
} else state = 'upcoming';
const eventMs =
state === 'passed'
? leftAt
: atStop || k === 0
? times.dep[k]
: times.arr[k];
out.push({
index: k,
stopId: stop.id,
name: stop.name || parent?.name || stop.id,
platform: stop.platform,
parentId: parent?.id ?? null,
parentName: parent?.name ?? null,
lat: stop.lat,
lon: stop.lon,
timezone: zone,
scheduledArrivalMs: times.schedArr[k],
scheduledDepartureMs: times.schedDep[k],
expectedArrivalMs: times.arr[k],
expectedDepartureMs: times.dep[k],
arrivalDelaySec: Math.round((times.arr[k] - times.schedArr[k]) / 1000),
departureDelaySec: Math.round((times.dep[k] - times.schedDep[k]) / 1000),
scheduledArrival: formatClock(times.schedArr[k], zone),
scheduledDeparture: formatClock(times.schedDep[k], zone),
expectedArrival: formatClock(times.arr[k], zone),
expectedDeparture: formatClock(times.dep[k], zone),
passThrough: pattern.pass[k],
skipped: times.skipped[k],
realtime: times.hasRealtime,
state,
atStop,
relativeMs: eventMs - nowMs,
relative: formatRelative(eventMs - nowMs),
});
}
return out;
}
+444
View File
@@ -0,0 +1,444 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
activeTrips,
createSchedule,
formatRelative,
liveDelaySec,
schedulePackEndMs,
scheduledPosition,
tripStops,
} from './railSchedule.js';
import {
formatClock,
localDate,
serviceDayOriginMs,
zonedTimeToEpochMs,
} from './railTimeZones.js';
const MIN = 60_000;
const H = 3_600_000;
/**
* Four stops on one shape, New York time except the last (Chicago). Run
* times: A 0, B arrive +5 min / leave +6 min, C +15 min, D +25 min.
*/
function pack(overrides = {}) {
return {
version: 1,
feedId: 'test-feed',
timezone: 'America/New_York',
window: { from: '2026-10-31', to: '2026-11-03' },
routes: { R: { type: 2, short: 'R' } },
stops: [
{ id: 'A', name: 'Alpha', lat: 40, lon: -74 },
{
id: 'B1',
name: 'Track 1',
lat: 40,
lon: -73.99,
parent: 4,
platform: '1',
},
{ id: 'C', name: 'Charlie', lat: 40, lon: -73.97 },
{ id: 'D', name: 'Delta', lat: 40, lon: -73.94, tz: 'America/Chicago' },
{ id: 'B', name: 'Bravo', lat: 40, lon: -73.99 },
],
patterns: [
{
shape: 0,
stops: [0, 1, 2, 3],
seq: [1, 2, 3, 4],
dist: [0, 1000, 3000, 6000],
},
{ shape: null, stops: [0, 2], seq: [1, 2], dist: [0, 2500] },
],
profiles: [
[0, 0, 300, 360, 900, 900, 1500, 1500],
[0, 0, 600, 600],
],
services: {
SAT: ['2026-10-31'],
SUN: ['2026-11-01'],
DAILY: ['2026-10-31', '2026-11-01', '2026-11-02'],
},
trips: {
morning: {
pattern: 0,
profile: 0,
startSec: 8 * 3600,
route: 'R',
service: 'SUN',
headsign: 'Delta',
name: '101',
direction: 0,
},
late: {
pattern: 0,
profile: 0,
startSec: 25 * 3600,
route: 'R',
service: 'SAT',
name: '199',
},
fallback: {
pattern: 0,
profile: 0,
startSec: 1.5 * 3600,
route: 'R',
service: 'SUN',
},
shuttle: {
pattern: 1,
profile: 1,
startSec: 12 * 3600,
route: 'R',
service: 'DAILY',
},
},
...overrides,
};
}
const at = (iso) => Date.parse(iso);
/** 08:00 EST on 2026-11-01, the morning trip's departure. */
const MORNING = at('2026-11-01T13:00:00Z');
test('relative chips read T−n ahead and T+n past, rounded like the Launches countdown', () => {
assert.equal(formatRelative(4 * MIN), 'T−4');
assert.equal(formatRelative(3.5 * MIN), 'T−4');
assert.equal(formatRelative(30_000), 'T−1');
assert.equal(formatRelative(0), 'T+0');
assert.equal(formatRelative(-30_000), 'T+0');
assert.equal(formatRelative(-3 * MIN), 'T+3');
assert.equal(formatRelative(-3.5 * MIN), 'T+3');
assert.equal(formatRelative(65 * MIN), 'T−1:05');
assert.equal(formatRelative(-125 * MIN), 'T+2:05');
assert.equal(formatRelative(NaN), '');
});
test('service days count from noon minus 12 h, across both DST changes', () => {
// Ordinary day: local midnight.
assert.equal(
serviceDayOriginMs('2026-10-31', 'America/New_York'),
at('2026-10-31T04:00:00Z'),
);
// Fall back: 01:00 EDT, so 08:00:00 is 08:00 EST.
const fall = serviceDayOriginMs('20261101', 'America/New_York');
assert.equal(fall, at('2026-11-01T05:00:00Z'));
assert.equal(formatClock(fall + 8 * H, 'America/New_York'), '08:00');
// Spring forward: 23:00 EST the evening before, so 06:00:00 is 06:00 EDT.
const spring = serviceDayOriginMs('2026-03-08', 'America/New_York');
assert.equal(spring, at('2026-03-08T04:00:00Z'));
assert.equal(formatClock(spring + 6 * H, 'America/New_York'), '06:00');
assert.ok(Number.isNaN(serviceDayOriginMs('2026-02-30', 'UTC')));
});
test('wall times resolve to instants: overlaps take the earlier, gaps move on', () => {
assert.equal(
zonedTimeToEpochMs('America/New_York', 2026, 11, 1, 1, 30),
at('2026-11-01T05:30:00Z'),
);
assert.equal(
zonedTimeToEpochMs('America/New_York', 2026, 3, 8, 2, 30),
at('2026-03-08T07:30:00Z'),
);
assert.equal(
zonedTimeToEpochMs('Europe/London', 2026, 7, 1, 12),
at('2026-07-01T11:00:00Z'),
);
assert.equal(
localDate(at('2026-11-01T03:59:00Z'), 'America/New_York'),
'2026-10-31',
);
assert.equal(formatClock(at('2026-11-01T23:59:00Z'), 'Asia/Tokyo'), '08:59');
});
test('a malformed pack is refused', () => {
assert.throws(() => createSchedule(null), TypeError);
assert.throws(() => createSchedule({ ...pack(), version: 2 }), TypeError);
assert.throws(
() => createSchedule(pack({ patterns: [{ shape: 0, stops: [0, 99] }] })),
TypeError,
);
});
test('active trips come from service dates in the agency zone', () => {
const schedule = createSchedule(pack());
const ids = (now) =>
activeTrips(schedule, now).map((run) => `${run.tripId}@${run.serviceDate}`);
assert.deepEqual(ids(MORNING + 10 * MIN), ['morning@2026-11-01']);
assert.deepEqual(ids(MORNING - MIN), []);
assert.deepEqual(ids(MORNING + 26 * MIN), []);
// Saturday's 25:00:00 trip runs at 01:00 EDT on Sunday, the first 01:00.
assert.deepEqual(ids(at('2026-11-01T05:10:00Z')), ['late@2026-10-31']);
// Sunday's 01:30:00 trip runs at 01:30 EST, the second 01:30.
assert.deepEqual(ids(at('2026-11-01T06:40:00Z')), ['fallback@2026-11-01']);
// A daily trip appears once per run; widening the window catches a train
// waiting at its origin.
assert.deepEqual(ids(at('2026-11-02T17:05:00Z')), ['shuttle@2026-11-02']);
assert.deepEqual(
activeTrips(schedule, MORNING - 2 * MIN, { beforeMs: 5 * MIN }).map(
(run) => run.tripId,
),
['morning'],
);
const [run] = activeTrips(schedule, MORNING + MIN);
assert.equal(run.name, '101');
assert.equal(run.headsign, 'Delta');
assert.equal(run.shape, 0);
assert.equal(run.scheduledStartMs, MORNING);
assert.equal(run.scheduledEndMs, MORNING + 25 * MIN);
});
test('the timetable position runs linearly between stops and holds through a dwell', () => {
const schedule = createSchedule(pack());
const [run] = activeTrips(schedule, MORNING + MIN);
const moving = scheduledPosition(schedule, run, MORNING + 150_000);
assert.equal(moving.state, 'running');
assert.equal(moving.dwell, false);
assert.equal(moving.s, 500);
assert.equal(moving.prevStop, 0);
assert.equal(moving.nextStop, 1);
assert.equal(moving.nextStopId, 'B1');
assert.equal(
moving.lat,
undefined,
'a shaped pattern leaves lat/lon to the path',
);
const dwell = scheduledPosition(schedule, run, MORNING + 330_000);
assert.equal(dwell.dwell, true);
assert.equal(dwell.s, 1000);
assert.equal(dwell.prevStop, 1);
assert.equal(dwell.nextStop, 2);
const leg = scheduledPosition(schedule, 'morning', MORNING + 630_000);
assert.equal(leg.s, 2000, 'halfway from B (leaves +6) to C (arrives +15)');
const before = scheduledPosition(schedule, run, MORNING - MIN);
assert.equal(before.state, 'before');
assert.equal(before.s, 0);
assert.equal(before.nextStop, 0);
const after = scheduledPosition(schedule, run, MORNING + 30 * MIN);
assert.equal(after.state, 'arrived');
assert.equal(after.s, 6000);
assert.equal(after.nextStop, -1);
});
test('a pattern without a shape interpolates between its stops', () => {
const schedule = createSchedule(pack());
const noon = at('2026-11-01T17:00:00Z');
const position = scheduledPosition(
schedule,
{ tripId: 'shuttle', serviceDate: '2026-11-01' },
noon + 5 * MIN,
);
assert.equal(position.shape, null);
assert.equal(position.s, 1250);
assert.ok(Math.abs(position.lon - -73.985) < 1e-9);
assert.equal(position.lat, 40);
});
test('the stop list shows station-local 24 h clocks, states and chips', () => {
const schedule = createSchedule(pack());
const stops = tripStops(schedule, 'morning', MORNING + 320_000);
assert.deepEqual(
stops.map((stop) => [stop.stopId, stop.state, stop.atStop, stop.relative]),
[
['A', 'passed', false, 'T+5'],
['B1', 'next', true, 'T−1'],
['C', 'upcoming', false, 'T−10'],
['D', 'upcoming', false, 'T−20'],
],
);
assert.equal(stops[0].scheduledDeparture, '08:00');
assert.equal(stops[1].scheduledArrival, '08:05');
assert.equal(stops[1].scheduledDeparture, '08:06');
assert.equal(stops[1].name, 'Track 1');
assert.equal(stops[1].parentName, 'Bravo');
assert.equal(stops[1].platform, '1');
assert.equal(stops[1].timezone, 'America/New_York');
// Delta keeps Chicago time: 08:25 Eastern is 07:25 Central.
assert.equal(stops[3].timezone, 'America/Chicago');
assert.equal(stops[3].scheduledArrival, '07:25');
assert.equal(stops[3].scheduledArrivalMs, MORNING + 25 * MIN);
assert.equal(stops[3].realtime, false);
});
test('times past 24:00:00 land on the next calendar day', () => {
const schedule = createSchedule(pack());
const stops = tripStops(schedule, 'late', at('2026-11-01T05:00:00Z'));
assert.equal(stops[0].scheduledDepartureMs, at('2026-11-01T05:00:00Z'));
assert.equal(stops[0].scheduledDeparture, '01:00');
assert.equal(stops[1].scheduledArrival, '01:05');
// The fall-back trip at 01:30:00 runs an hour of real time later.
const fallback = tripStops(schedule, 'fallback', at('2026-11-01T06:30:00Z'));
assert.equal(fallback[0].scheduledDepartureMs, at('2026-11-01T06:30:00Z'));
assert.equal(fallback[0].scheduledDeparture, '01:30');
});
test('a stop delay carries on to later stops until the next update', () => {
const schedule = createSchedule(pack());
const delays = {
morning: {
stops: [
{ stopId: 'B1', arrival: { delay: 120 } },
{ stopSequence: 4, arrival: { time: (MORNING + 26 * MIN) / 1000 } },
],
},
};
const stops = tripStops(schedule, 'morning', MORNING, delays);
assert.deepEqual(
stops.map((stop) => [stop.arrivalDelaySec, stop.departureDelaySec]),
[
[0, 0],
[120, 120],
[120, 120],
[60, 60],
],
);
assert.equal(stops[1].expectedArrival, '08:07');
assert.equal(stops[1].scheduledArrival, '08:05');
assert.equal(stops[1].realtime, true);
// Between A (left on time) and B (arrives +7) the run is slower.
const position = scheduledPosition(
schedule,
'morning',
MORNING + 210_000,
delays,
);
assert.equal(position.s, 500);
assert.equal(position.delaySec, 120);
// A late train is still active after its timetable ends.
const late = { morning: { delaySec: 600 } };
assert.deepEqual(
activeTrips(schedule, MORNING + 30 * MIN).map((run) => run.tripId),
[],
);
const [run] = activeTrips(schedule, MORNING + 30 * MIN, { delays: late });
assert.equal(run.tripId, 'morning');
assert.equal(run.expectedEndMs, MORNING + 35 * MIN);
});
test('a delay pinned to a start date leaves other runs alone; parent ids match platforms', () => {
const schedule = createSchedule(pack());
const pinned = { morning: { startDate: '20261031', delaySec: 300 } };
assert.equal(
tripStops(schedule, 'morning', MORNING, pinned)[2].arrivalDelaySec,
0,
);
const own = {
morning: {
startDate: '2026-11-01',
stops: [{ stopId: 'B', departure: { delay: 60 } }],
},
};
const stops = tripStops(schedule, 'morning', MORNING, own);
assert.equal(stops[1].departureDelaySec, 60);
assert.equal(stops[2].arrivalDelaySec, 60);
});
test('a skipped stop is passed without a dwell', () => {
const schedule = createSchedule(pack());
// The record shape src/data/railTripUpdates.js serves.
const delays = {
morning: {
tripId: 'morning',
startDate: '20261101',
delaySec: null,
stops: [
{
stopId: null,
stopSequence: 2,
arrival: null,
departure: null,
relationship: 'SKIPPED',
},
],
},
};
const position = scheduledPosition(
schedule,
'morning',
MORNING + 450_000,
delays,
);
assert.equal(position.dwell, false);
assert.equal(position.prevStop, 0);
assert.equal(position.nextStop, 2);
assert.equal(position.s, 1500, 'halfway from A (+0) to C (+15)');
assert.equal(
tripStops(schedule, 'morning', MORNING, delays)[1].skipped,
true,
);
});
test('a canceled run leaves the active list', () => {
const schedule = createSchedule(pack());
const now = MORNING + 10 * MIN;
const canceled = { morning: { relationship: 'CANCELED' } };
assert.equal(activeTrips(schedule, now).length, 1);
assert.equal(activeTrips(schedule, now, { delays: canceled }).length, 0);
});
test('NO_DATA at a stop ends the delay carried to it: the timetable applies again', () => {
const schedule = createSchedule(pack());
const delays = {
morning: {
delaySec: 300,
stops: [
{ stopId: 'B1', arrival: { delay: 240 } },
{ stopId: 'C', relationship: 'NO_DATA' },
],
},
};
const stops = tripStops(schedule, 'morning', MORNING, delays);
assert.deepEqual(
stops.map((stop) => [stop.arrivalDelaySec, stop.departureDelaySec]),
[
[300, 300],
[240, 240],
// No prediction from C on: its time and D's are the timetable's.
[0, 0],
[0, 0],
],
);
assert.equal(stops[2].expectedArrival, stops[2].scheduledArrival);
// A later update after NO_DATA counts again.
const later = {
morning: {
stops: [
{ stopId: 'B1', arrival: { delay: 240 } },
{ stopId: 'C', scheduleRelationship: 'NO_DATA' },
{ stopSequence: 4, arrival: { delay: 60 } },
],
},
};
assert.deepEqual(
tripStops(schedule, 'morning', MORNING, later).map(
(stop) => stop.arrivalDelaySec,
),
[0, 240, 0, 60],
);
});
test('a pack ends when the last run it holds arrives', () => {
// The latest run: the shuttle on its last date, 2 November, at noon New
// York time for 10 minutes (31 October's 25:00 train arrives earlier).
const end = schedulePackEndMs(pack());
assert.equal(
end,
serviceDayOriginMs('2026-11-02', 'America/New_York') + 12 * H + 10 * MIN,
);
// Without a window the end is not known; with no run there is none.
assert.equal(schedulePackEndMs(pack({ window: undefined })), null);
assert.equal(schedulePackEndMs(pack({ trips: {} })), -Infinity);
assert.equal(schedulePackEndMs(null), null);
});
test('a live report states its own delay; a day or more either way is no delay', () => {
assert.equal(liveDelaySec({ delaySec: 540 }), 540);
assert.equal(liveDelaySec({ delaySec: -120 }), -120);
assert.equal(liveDelaySec({ delaySec: 0 }), 0);
for (const value of [null, undefined, '540', NaN, Infinity, 86_401, -86_401])
assert.equal(liveDelaySec({ delaySec: value }), null, String(value));
assert.equal(liveDelaySec(null), null);
});
+124
View File
@@ -0,0 +1,124 @@
/**
* @module railScheduleIndex
* @description Server-side lookup over a schedule pack (the
* `<feedId>.schedule.json` scripts/build-rail-paths.mjs writes) for a
* realtime source that names a train by its number (Irish Rail's train
* codes): `createRunIndex`, the dated runs of a pack's trips, so a reported
* train takes the trip it is on (its line and stops). The train's position
* is never taken from the timetable.
*
* Pure: no I/O. Times are epoch milliseconds; a run starts at the service
* day's GTFS origin (noon minus 12 h in the pack's time zone) plus the
* trip's start, and lasts its profile's last offset, as
* src/data/railSchedule.js reads them.
*/
import { serviceDayOriginMs } from './railTimeZones.js';
function packTrips(raw) {
return raw?.trips && typeof raw.trips === 'object' ? raw.trips : {};
}
function packServices(raw) {
return raw?.services && typeof raw.services === 'object' ? raw.services : {};
}
function serviceDates(services, service) {
const dates = services[service];
return Array.isArray(dates) ? dates : [];
}
/**
* The dated runs of a pack's trips. Built lazily per trip, so a source that
* looks up a few hundred train numbers never expands the whole pack. It
* keeps the parts of the pack it reads (trips, profiles, services), not the
* pack itself.
* @param {object} raw Decoded schedule pack.
* @returns {{runsOf: (tripId: string) => Array<{tripId: string, date: string,
* startMs: number, endMs: number}>,
* tripsNamed: (name: string) => string[],
* activeTrip: (name: string, nowMs: number,
* options?: {slackMs?: number, delayMs?: number}) =>
* ({tripId: string, date: string, startMs: number, endMs: number}|null)}}
*/
export function createRunIndex(raw) {
const trips = packTrips(raw);
const services = packServices(raw);
const zone = typeof raw?.timezone === 'string' ? raw.timezone : 'UTC';
const profiles = Array.isArray(raw?.profiles) ? raw.profiles : [];
const origins = new Map();
const originOf = (date) => {
let origin = origins.get(date);
if (origin === undefined) {
origin = serviceDayOriginMs(date, zone);
origins.set(date, origin);
}
return origin;
};
let names = null;
const runs = new Map();
function runsOf(tripId) {
let list = runs.get(tripId);
if (list) return list;
list = [];
const trip = Object.hasOwn(trips, tripId) ? trips[tripId] : null;
const profile = trip ? profiles[trip.profile] : null;
if (trip && Array.isArray(profile) && Number.isFinite(trip.startSec)) {
const durationMs = (Number(profile[profile.length - 1]) || 0) * 1000;
for (const date of serviceDates(services, trip.service)) {
const origin = originOf(date);
if (!Number.isFinite(origin)) continue;
const startMs = origin + trip.startSec * 1000;
list.push({ tripId, date, startMs, endMs: startMs + durationMs });
}
}
runs.set(tripId, list);
return list;
}
return {
runsOf,
tripsNamed(name) {
if (!names) {
names = new Map();
for (const [tripId, trip] of Object.entries(trips)) {
if (typeof trip?.name !== 'string' || !trip.name) continue;
const list = names.get(trip.name);
if (list) list.push(tripId);
else names.set(trip.name, [tripId]);
}
}
return names.get(String(name ?? '')) ?? [];
},
/**
* The run of a train number that is under way at `nowMs` (or within
* `slackMs` of its start or end); the one whose span is nearest when
* several qualify, null when none or when two tie. A train running
* `delayMs` late (negative: early) is where its timetable was that long
* ago, so its runs are compared at `nowMs - delayMs`.
*/
activeTrip(name, nowMs, { slackMs = 10 * 60_000, delayMs = 0 } = {}) {
const at = nowMs - (Number.isFinite(delayMs) ? delayMs : 0);
let best = null;
let bestScore = Infinity;
let tie = false;
for (const tripId of this.tripsNamed(name)) {
for (const run of runsOf(tripId)) {
if (at < run.startMs - slackMs || at > run.endMs + slackMs) continue;
const score =
at < run.startMs
? run.startMs - at
: at > run.endMs
? at - run.endMs
: 0;
if (score < bestScore) {
best = run;
bestScore = score;
tie = false;
} else if (score === bestScore && best && run.tripId !== best.tripId)
tie = true;
}
}
return tie ? null : best;
},
};
}
+188
View File
@@ -0,0 +1,188 @@
/**
* @module railSiriVm
* @description Adapter for SIRI Vehicle Monitoring (SIRI Lite `vm`, as
* Entur publishes it at `api.entur.io/realtime/v1/rest/vm`), turning each
* `<VehicleActivity>` into the train records the GTFS-RT path produces.
*
* Only the handful of elements a position needs are read (RecordedAtTime,
* ValidUntilTime, LineRef, VehicleMode, VehicleLocation, Bearing, Delay,
* VehicleJourneyRef, VehicleRef), with a small scanner instead of an XML
* library: no DTDs, no entity definitions, attributes ignored, an optional
* namespace prefix on any element. A document that declares a DTD or
* entities is refused, and every size is capped (whole text, activity count,
* field length).
*
* The positions are the operator's own GPS reports, each with the time it
* was recorded, so records carry `timestampSource: 'vehicle'`. An activity
* whose `ValidUntilTime` has passed is dropped, as is one whose
* `VehicleMode` says it is not a train (Entur lists replacement buses under
* the train lines).
*
* Pure: no Node built-ins, safe for node:test and any server runtime.
*/
import { isPlausibleVehiclePosition } from './gtfsRealtime.js';
import { decodeXmlText } from './irishRail.js';
/** Longest document read (characters). SJ Nord's is about 7 KB. */
export const SIRI_VM_MAX_TEXT_CHARS = 2 * 1024 * 1024;
/** Most activities read from one document. */
export const SIRI_VM_MAX_ACTIVITIES = 5000;
/** Longest accepted field (characters). */
export const SIRI_VM_MAX_FIELD_CHARS = 256;
/** Error for a document this adapter will not read. */
export class SiriVmFormatError extends Error {
constructor(message) {
super(message);
this.name = 'SiriVmFormatError';
}
}
/** `<Name>` or `<prefix:Name>` (no attributes kept), up to its close. */
function readField(block, name) {
const match = new RegExp(
`<(?:[A-Za-z_][\\w.-]*:)?${name}(?:\\s[^>]*)?>([^<]*)</(?:[A-Za-z_][\\w.-]*:)?${name}>`,
).exec(block);
if (!match || match[1].length > SIRI_VM_MAX_FIELD_CHARS * 6) return null;
const value = decodeXmlText(match[1]).trim();
return value.length <= SIRI_VM_MAX_FIELD_CHARS ? value : null;
}
/**
* Seconds in an ISO 8601 duration as SIRI writes a delay (`PT0S`,
* `PT2M30S`, `-PT45S`, `P1DT1H`), or null.
* @param {string|null} text
* @returns {number|null}
*/
export function parseIsoDurationSec(text) {
const match =
/^(-)?P(?:(\d+(?:\.\d+)?)D)?(?:T(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?)?$/.exec(
String(text ?? '').trim(),
);
if (!match || !(match[2] || match[3] || match[4] || match[5])) return null;
const [, sign, d = 0, h = 0, m = 0, s = 0] = match;
const total =
Number(d) * 86_400 + Number(h) * 3600 + Number(m) * 60 + Number(s);
return Math.round(sign ? -total : total);
}
/** Epoch seconds of an ISO date-time with its offset, or null. */
function epochSeconds(text) {
const ms = Date.parse(String(text ?? ''));
return Number.isFinite(ms) ? Math.floor(ms / 1000) : null;
}
/**
* Split a SIRI VM document into raw activity rows.
* @param {string} text
* @returns {{rows: Array<Record<string, string|null>>, truncated: boolean,
* responseTimestamp: string|null}}
*/
export function parseSiriVmXml(text) {
if (typeof text !== 'string') throw new SiriVmFormatError('not text');
if (text.length > SIRI_VM_MAX_TEXT_CHARS)
throw new SiriVmFormatError(`document is ${text.length} characters`);
if (/<!DOCTYPE|<!ENTITY/i.test(text))
throw new SiriVmFormatError('document declares a DTD');
if (!/<(?:[A-Za-z_][\w.-]*:)?VehicleMonitoringDelivery[\s>]/.test(text))
throw new SiriVmFormatError('not a vehicle monitoring document');
const open = /<(?:[A-Za-z_][\w.-]*:)?VehicleActivity(?:\s[^>]*)?>/g;
const close = /<\/(?:[A-Za-z_][\w.-]*:)?VehicleActivity>/g;
const rows = [];
let truncated = false;
let found;
while ((found = open.exec(text))) {
close.lastIndex = open.lastIndex;
const end = close.exec(text);
if (!end) break;
if (rows.length >= SIRI_VM_MAX_ACTIVITIES) {
truncated = true;
break;
}
const block = text.slice(open.lastIndex, end.index);
rows.push({
recordedAt: readField(block, 'RecordedAtTime'),
validUntil: readField(block, 'ValidUntilTime'),
lineRef: readField(block, 'LineRef'),
mode: readField(block, 'VehicleMode'),
latitude: readField(block, 'Latitude'),
longitude: readField(block, 'Longitude'),
bearing: readField(block, 'Bearing'),
delay: readField(block, 'Delay'),
journeyRef:
readField(block, 'VehicleJourneyRef') ??
readField(block, 'DatedVehicleJourneyRef'),
vehicleRef: readField(block, 'VehicleRef'),
lineName: readField(block, 'PublishedLineName'),
});
open.lastIndex = end.index + end[0].length;
}
const head = text.slice(0, 4096);
return {
rows,
truncated,
responseTimestamp: readField(head, 'ResponseTimestamp'),
};
}
/**
* Turn a SIRI VM document into unclassified train records in the shape the
* GTFS-RT path produces (src/data/gtfsRealtime.js), plus `delaySec`.
*
* `routeId` is the `LineRef` (Entur: the same `<codespace>:Line:<n>` ids as
* the static GTFS), `tripId` the `VehicleJourneyRef` (Entur: a
* `DatedServiceJourney`, not the GTFS trip id; the timetable matches the
* train to a run by line and position instead). One record per vehicle:
* a vehicle listed twice keeps its latest report.
*
* @param {string} text The XML document.
* @param {number} fetchedAtS Fetch time (epoch seconds), used when an
* activity carries no RecordedAtTime and to drop expired activities.
* @returns {{entityCount: number, truncated: boolean,
* feedTimestamp: number|null, vehicles: object[]}}
*/
export function decodeSiriVehicleMonitoring(text, fetchedAtS) {
const { rows, truncated, responseTimestamp } = parseSiriVmXml(text);
const byId = new Map();
for (const row of rows) {
if (row.mode && !/^rail$/i.test(row.mode)) continue;
const lat = Number.parseFloat(row.latitude ?? '');
const lon = Number.parseFloat(row.longitude ?? '');
if (!isPlausibleVehiclePosition(lat, lon)) continue;
const validUntil = epochSeconds(row.validUntil);
if (validUntil !== null && validUntil < fetchedAtS) continue;
const id = row.vehicleRef || row.journeyRef;
if (!id || !/^[\w:.-]{1,128}$/.test(id)) continue;
const recorded = epochSeconds(row.recordedAt);
const bearing = Number.parseFloat(row.bearing ?? '');
const record = {
id,
lat: Number(lat.toFixed(6)),
lon: Number(lon.toFixed(6)),
bearing:
Number.isFinite(bearing) && bearing >= 0 && bearing <= 360
? bearing
: null,
speedMps: null,
timestamp: recorded ?? fetchedAtS,
timestampSource: recorded === null ? 'fetch' : 'vehicle',
routeId: row.lineRef || null,
tripId: row.journeyRef || null,
directionId: null,
label: row.lineName || null,
stopId: null,
status: null,
occupancy: null,
delaySec: parseIsoDurationSec(row.delay),
};
const known = byId.get(id);
if (!known || record.timestamp >= known.timestamp) byId.set(id, record);
}
return {
entityCount: rows.length,
truncated,
feedTimestamp: epochSeconds(responseTimestamp),
vehicles: [...byId.values()],
};
}
+182
View File
@@ -0,0 +1,182 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
SIRI_VM_MAX_ACTIVITIES,
SiriVmFormatError,
decodeSiriVehicleMonitoring,
parseIsoDurationSec,
parseSiriVmXml,
} from './railSiriVm.js';
import { buildRailSnapshot } from './railProxy.js';
import { getRegisteredRailFeed } from './railFeeds.js';
const NOW_S = Date.parse('2026-11-09T16:27:00Z') / 1000;
/** One `<VehicleActivity>`, shaped like Entur's SIRI Lite answer. */
function activity({
recorded = '2026-11-09T17:26:17+01:00',
validUntil = '2026-11-09T17:29:17+01:00',
line = 'SJN:Line:25',
lat = '63.42107333333333',
lon = '10.377486666666666',
delay = 'PT0S',
journey = 'SJN:DatedServiceJourney:2388_ROS-HMR_26-11-09',
vehicle = '957605930081',
extra = '',
} = {}) {
return `<VehicleActivity><RecordedAtTime>${recorded}</RecordedAtTime><ValidUntilTime>${validUntil}</ValidUntilTime><MonitoredVehicleJourney><LineRef>${line}</LineRef><DataSource>SJN</DataSource>${extra}<VehicleLocation><Longitude>${lon}</Longitude><Latitude>${lat}</Latitude></VehicleLocation><Delay>${delay}</Delay><VehicleJourneyRef>${journey}</VehicleJourneyRef><VehicleRef>${vehicle}</VehicleRef></MonitoredVehicleJourney></VehicleActivity>`;
}
function document(...activities) {
return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Siri xmlns="http://www.siri.org.uk/siri" version="2.0"><ServiceDelivery><ResponseTimestamp>2026-11-09T17:26:46.11584667+01:00</ResponseTimestamp><ProducerRef>ENT</ProducerRef><VehicleMonitoringDelivery version="2.0"><ResponseTimestamp>2026-11-09T17:26:46.115848853+01:00</ResponseTimestamp>${activities.join('')}</VehicleMonitoringDelivery></ServiceDelivery></Siri>`;
}
test('SIRI delays are ISO 8601 durations', () => {
assert.equal(parseIsoDurationSec('PT0S'), 0);
assert.equal(parseIsoDurationSec('PT2M30S'), 150);
assert.equal(parseIsoDurationSec('-PT45S'), -45);
assert.equal(parseIsoDurationSec('PT1H'), 3600);
assert.equal(parseIsoDurationSec('P1DT1M'), 86_460);
assert.equal(parseIsoDurationSec('PT1.6S'), 2);
assert.equal(parseIsoDurationSec('P'), null);
assert.equal(parseIsoDurationSec('soon'), null);
assert.equal(parseIsoDurationSec(null), null);
});
test('a vehicle activity becomes a train record with its own report time', () => {
const decoded = decodeSiriVehicleMonitoring(
document(activity({ delay: 'PT3M' })),
NOW_S,
);
assert.equal(decoded.entityCount, 1);
assert.equal(decoded.truncated, false);
assert.equal(
decoded.feedTimestamp,
Math.floor(Date.parse('2026-11-09T16:26:46.115Z') / 1000),
);
assert.deepEqual(decoded.vehicles, [
{
id: '957605930081',
lat: 63.421073,
lon: 10.377487,
bearing: null,
speedMps: null,
timestamp: Date.parse('2026-11-09T16:26:17Z') / 1000,
timestampSource: 'vehicle',
routeId: 'SJN:Line:25',
tripId: 'SJN:DatedServiceJourney:2388_ROS-HMR_26-11-09',
directionId: null,
label: null,
stopId: null,
status: null,
occupancy: null,
delaySec: 180,
},
]);
});
test('buses, expired reports, bad positions and duplicates are dropped', () => {
const decoded = decodeSiriVehicleMonitoring(
document(
activity({ vehicle: 'bus', extra: '<VehicleMode>bus</VehicleMode>' }),
activity({ vehicle: 'rail', extra: '<VehicleMode>rail</VehicleMode>' }),
activity({ vehicle: 'old', validUntil: '2026-11-09T17:20:00+01:00' }),
activity({ vehicle: 'nowhere', lat: '0', lon: '0' }),
activity({ vehicle: 'twice', recorded: '2026-11-09T17:25:00+01:00' }),
activity({ vehicle: 'twice', recorded: '2026-11-09T17:26:00+01:00' }),
activity({ vehicle: 'bad id!' }),
),
NOW_S,
);
assert.equal(decoded.entityCount, 7);
assert.deepEqual(
decoded.vehicles.map((v) => v.id),
['rail', 'twice'],
);
assert.equal(
decoded.vehicles[1].timestamp,
Date.parse('2026-11-09T16:26:00Z') / 1000,
'the later of two reports',
);
});
test('a report without a time takes the fetch time, labelled so', () => {
const xml = document(activity()).replace(
/<RecordedAtTime>[^<]*<\/RecordedAtTime>/,
'',
);
const [train] = decodeSiriVehicleMonitoring(xml, NOW_S).vehicles;
assert.equal(train.timestamp, NOW_S);
assert.equal(train.timestampSource, 'fetch');
});
test('namespace prefixes, bearings and published line names are read', () => {
const xml = document(
activity({ extra: '<Bearing>91.5</Bearing>' }).replace(
/<(\/?)(VehicleActivity|LineRef|Latitude|Longitude)>/g,
'<$1siri:$2>',
),
).replace(
'<VehicleJourneyRef>',
'<PublishedLineName>F6</PublishedLineName><VehicleJourneyRef>',
);
const [train] = decodeSiriVehicleMonitoring(xml, NOW_S).vehicles;
assert.equal(train.routeId, 'SJN:Line:25');
assert.equal(train.bearing, 91.5);
assert.equal(train.label, 'F6');
});
test('documents that are not vehicle monitoring, or declare a DTD, are refused', () => {
assert.throws(() => parseSiriVmXml(42), SiriVmFormatError);
assert.throws(
() => parseSiriVmXml('<html><body>Bad gateway</body></html>'),
SiriVmFormatError,
);
assert.throws(
() =>
parseSiriVmXml(`<!DOCTYPE x [<!ENTITY a "b">]>${document(activity())}`),
SiriVmFormatError,
);
assert.equal(parseSiriVmXml(document()).rows.length, 0);
});
test('the activity count is capped', () => {
const many = Array.from(
{ length: SIRI_VM_MAX_ACTIVITIES + 2 },
(_, i) =>
`<VehicleActivity><VehicleRef>v${i}</VehicleRef></VehicleActivity>`,
);
const parsed = parseSiriVmXml(document(...many));
assert.equal(parsed.rows.length, SIRI_VM_MAX_ACTIVITIES);
assert.equal(parsed.truncated, true);
});
test('the rail proxy reads SJ Nord from SIRI VM and classifies its lines', () => {
const feed = getRegisteredRailFeed('entur-sj-nord');
assert.equal(feed.format, 'siri-vm');
const bytes = new TextEncoder().encode(
document(
activity({ vehicle: 'a', line: 'SJN:Line:25' }),
activity({ vehicle: 'b', line: 'SJN:Line:26' }),
activity({ vehicle: 'c', line: 'SJN:Line:72' }),
activity({ vehicle: 'd', line: 'SJN:Line:999' }),
),
);
const snapshot = buildRailSnapshot(feed, bytes, NOW_S * 1000);
assert.equal(snapshot.positions, 'gps');
assert.equal(snapshot.entityCount, 4);
assert.equal(snapshot.dropped, 1, 'an unknown line');
assert.deepEqual(
snapshot.trains.map((t) => [t.id, t.category, t.positionSource]),
[
['a', 'national', 'gps'],
['b', 'regional', 'gps'],
['c', 'international', 'gps'],
],
);
assert.ok(Number.isFinite(snapshot.feedTimestamp));
assert.throws(
() => buildRailSnapshot(feed, new TextEncoder().encode('<html/>'), 0),
(error) => error.code === 'UPSTREAM_UNREADABLE',
);
});
+174
View File
@@ -0,0 +1,174 @@
/**
* @module railTimeZones
* @description Wall-clock arithmetic in IANA time zones for rail timetables,
* built on Intl.DateTimeFormat only.
*
* GTFS measures stop times from "noon minus 12 hours" of the service day in
* the agency's time zone: midnight on ordinary days, and the hour that keeps
* every timetable time unambiguous on the two days a year the clocks change.
* `serviceDayOriginMs` returns that instant; a stop time of `sec` seconds is
* `origin + sec * 1000`, which also covers times past 24:00:00.
*
* Pure: no Cesium, no DOM, no Node built-ins.
*/
const DAY_MS = 86_400_000;
const formatters = new Map();
const clocks = new Map();
/** Whether `zone` is an IANA zone this runtime knows. */
export function isTimeZone(zone) {
if (typeof zone !== 'string' || !zone) return false;
try {
partsFormatter(zone);
return true;
} catch {
return false;
}
}
function partsFormatter(zone) {
let formatter = formatters.get(zone);
if (!formatter) {
formatter = new Intl.DateTimeFormat('en-US', {
timeZone: zone,
hourCycle: 'h23',
year: 'numeric',
month: '2-digit',
day: '2-digit',
hour: '2-digit',
minute: '2-digit',
second: '2-digit',
});
formatters.set(zone, formatter);
}
return formatter;
}
/**
* The wall-clock fields of an instant in a zone.
* @param {number} epochMs
* @param {string} zone
* @returns {{year: number, month: number, day: number, hour: number,
* minute: number, second: number}}
*/
export function zonedParts(epochMs, zone) {
const out = {};
for (const part of partsFormatter(zone).formatToParts(epochMs))
if (part.type !== 'literal') out[part.type] = Number(part.value);
return {
year: out.year,
month: out.month,
day: out.day,
hour: out.hour % 24,
minute: out.minute,
second: out.second,
};
}
/** UTC offset of a zone at an instant, in ms (east positive). */
export function zoneOffsetMs(epochMs, zone) {
const p = zonedParts(epochMs, zone);
const wall = Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second);
return wall - Math.floor(epochMs / 1000) * 1000;
}
/**
* The instant a wall-clock time occurs in a zone. In a gap (spring forward)
* the result is shifted forward by the gap; in an overlap (fall back) the
* earlier instant is returned.
*/
export function zonedTimeToEpochMs(
zone,
year,
month,
day,
hour = 0,
minute = 0,
second = 0,
) {
const wall = Date.UTC(year, month - 1, day, hour, minute, second);
const first = zoneOffsetMs(wall, zone);
let guess = wall - first;
const offset2 = zoneOffsetMs(guess, zone);
if (offset2 !== first) {
const alternative = wall - offset2;
// Prefer the candidate whose wall time round-trips; else the earlier.
if (zoneOffsetMs(alternative, zone) === offset2)
guess = Math.min(guess, alternative);
}
return guess;
}
/** Parse 'YYYY-MM-DD' or 'YYYYMMDD' into numbers, or null. */
export function parseServiceDate(text) {
const match = /^(\d{4})-?(\d{2})-?(\d{2})$/.exec(String(text ?? '').trim());
if (!match) return null;
const year = Number(match[1]);
const month = Number(match[2]);
const day = Number(match[3]);
const check = new Date(Date.UTC(year, month - 1, day));
if (check.getUTCMonth() !== month - 1 || check.getUTCDate() !== day)
return null;
return { year, month, day };
}
/** 'YYYY-MM-DD' of a UTC-day number (days since 1970-01-01). */
export function dateFromDayNumber(dayNumber) {
return new Date(dayNumber * DAY_MS).toISOString().slice(0, 10);
}
/** UTC-day number of a service date, or NaN. */
export function dayNumberOf(text) {
const date = parseServiceDate(text);
return date ? Date.UTC(date.year, date.month - 1, date.day) / DAY_MS : NaN;
}
/** The local calendar date ('YYYY-MM-DD') of an instant in a zone. */
export function localDate(epochMs, zone) {
const p = zonedParts(epochMs, zone);
return `${p.year}-${String(p.month).padStart(2, '0')}-${String(p.day).padStart(2, '0')}`;
}
/**
* The instant GTFS times of a service date count from: noon minus 12 hours,
* local to `zone`.
* @param {string} date 'YYYY-MM-DD' or 'YYYYMMDD'.
* @param {string} zone IANA zone.
* @returns {number} Epoch ms, or NaN for a malformed date.
*/
export function serviceDayOriginMs(date, zone) {
const parsed = parseServiceDate(date);
if (!parsed) return NaN;
return (
zonedTimeToEpochMs(zone, parsed.year, parsed.month, parsed.day, 12) -
12 * 3_600_000
);
}
/**
* A 24-hour 'HH:MM' clock string of an instant in a zone.
* @param {number} epochMs
* @param {string} zone
* @returns {string}
*/
export function formatClock(epochMs, zone) {
if (!Number.isFinite(epochMs)) return '';
let formatter = clocks.get(zone);
if (!formatter) {
formatter = new Intl.DateTimeFormat('en-GB', {
timeZone: zone,
hourCycle: 'h23',
hour: '2-digit',
minute: '2-digit',
});
clocks.set(zone, formatter);
}
let hour = '';
let minute = '';
for (const part of formatter.formatToParts(epochMs)) {
if (part.type === 'hour') hour = part.value;
else if (part.type === 'minute') minute = part.value;
}
return `${hour.padStart(2, '0')}:${minute.padStart(2, '0')}`;
}
+278
View File
@@ -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,
};
}
+262
View File
@@ -0,0 +1,262 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { PbfWriter } from 'pbf';
import { GTFS_MAX_ENTITIES } from './gtfsRealtime.js';
import {
RAIL_TRIP_UPDATE_MAX_STOPS,
RAIL_TRIP_UPDATE_MAX_TRIPS,
decodeTripUpdates,
normalizeTripUpdateEntity,
} from './railTripUpdates.js';
const NOW_S = 1_794_000_000;
function event(writer, tag, { delay, time } = {}) {
const message = new PbfWriter();
if (delay !== undefined) message.writeVarintField(1, delay);
if (time !== undefined) message.writeVarintField(2, time);
writer.writeBytesField(tag, message.finish());
}
/**
* A FeedMessage with trip updates. Each trip:
* `{id, tripId, routeId, startDate, delay, relationship, vehicleId, stops}`,
* each stop `{stopId, sequence, arrival, departure, relationship}`.
*/
function encodeTripUpdates({ incrementality = null, trips = [], extra = [] }) {
const writer = new PbfWriter();
const header = new PbfWriter();
header.writeStringField(1, '2.0');
if (incrementality !== null) header.writeVarintField(2, incrementality);
header.writeVarintField(3, NOW_S);
writer.writeBytesField(1, header.finish());
for (const trip of trips) {
const entity = new PbfWriter();
entity.writeStringField(1, trip.id ?? trip.tripId ?? 'e');
if (trip.deleted) entity.writeBooleanField(2, true);
const update = new PbfWriter();
const descriptor = new PbfWriter();
if (trip.tripId) descriptor.writeStringField(1, trip.tripId);
if (trip.startDate) descriptor.writeStringField(3, trip.startDate);
if (trip.relationship !== undefined)
descriptor.writeVarintField(4, trip.relationship);
if (trip.routeId) descriptor.writeStringField(5, trip.routeId);
update.writeBytesField(1, descriptor.finish());
for (const stop of trip.stops || []) {
const stu = new PbfWriter();
if (stop.sequence !== undefined) stu.writeVarintField(1, stop.sequence);
if (stop.arrival) event(stu, 2, stop.arrival);
if (stop.departure) event(stu, 3, stop.departure);
if (stop.stopId) stu.writeStringField(4, stop.stopId);
if (stop.relationship !== undefined)
stu.writeVarintField(5, stop.relationship);
update.writeBytesField(2, stu.finish());
}
if (trip.vehicleId) {
const vehicle = new PbfWriter();
vehicle.writeStringField(1, trip.vehicleId);
update.writeBytesField(3, vehicle.finish());
}
update.writeVarintField(4, NOW_S - 5);
if (trip.delay !== undefined) update.writeVarintField(5, trip.delay);
entity.writeBytesField(3, update.finish());
writer.writeBytesField(2, entity.finish());
}
for (const bytes of extra) writer.writeBytesField(2, bytes);
return writer.finish();
}
/** An entity that carries only a vehicle position (a combined feed). */
function vehicleOnlyEntity() {
const entity = new PbfWriter();
entity.writeStringField(1, 'veh');
const vehicle = new PbfWriter();
const position = new PbfWriter();
position.writeFloatField(1, 40.7);
position.writeFloatField(2, -73.9);
vehicle.writeBytesField(2, position.finish());
entity.writeBytesField(4, vehicle.finish());
return entity.finish();
}
test('trip updates decode with stop times, signed delays and the header', () => {
const decoded = decodeTripUpdates(
encodeTripUpdates({
trips: [
{
tripId: 'GO202_26_1959',
routeId: '4',
startDate: '20261106',
vehicleId: '7171',
stops: [
{ stopId: '179', sequence: 1, relationship: 2 },
{
stopId: '33',
sequence: 2,
arrival: { time: NOW_S + 60, delay: 58 },
departure: { time: NOW_S + 90, delay: -45 },
},
],
},
],
extra: [vehicleOnlyEntity()],
}),
);
assert.equal(decoded.version, '2.0');
assert.equal(decoded.timestamp, NOW_S);
assert.equal(decoded.incrementality, 0);
assert.equal(decoded.entityCount, 2, 'the vehicle entity is counted');
assert.equal(decoded.trips.length, 1, 'but is not a trip');
const [trip] = decoded.trips;
assert.equal(trip.tripId, 'GO202_26_1959');
assert.equal(trip.routeId, '4');
assert.equal(trip.startDate, '20261106');
assert.equal(trip.vehicleId, '7171');
assert.equal(trip.relationship, 'SCHEDULED');
assert.equal(trip.delaySec, 58, 'first stated stop delay');
assert.deepEqual(trip.stops, [
{
stopId: '179',
stopSequence: 1,
arrival: null,
departure: null,
relationship: 'NO_DATA',
},
{
stopId: '33',
stopSequence: 2,
arrival: { time: NOW_S + 60, delay: 58 },
departure: { time: NOW_S + 90, delay: -45 },
},
]);
});
test('a trip-level delay wins; a times-only feed reports no delay, not zero', () => {
const decoded = decodeTripUpdates(
encodeTripUpdates({
trips: [
{
tripId: 'a',
routeId: 'CR-Lowell',
delay: -120,
stops: [{ stopId: 's', arrival: { delay: 30 } }],
},
{
tripId: 'b',
routeId: 'CR-Lowell',
stops: [{ stopId: 's', arrival: { time: NOW_S + 300 } }],
},
{ tripId: 'c', routeId: 'CR-Lowell', relationship: 3 },
],
}),
);
const byId = new Map(decoded.trips.map((trip) => [trip.tripId, trip]));
assert.equal(byId.get('a').delaySec, -120);
assert.equal(byId.get('b').delaySec, null);
assert.deepEqual(byId.get('b').stops[0].arrival, {
time: NOW_S + 300,
delay: null,
});
assert.equal(byId.get('c').relationship, 'CANCELED');
assert.deepEqual(byId.get('c').stops, []);
});
test('implausible values are dropped instead of carried', () => {
const decoded = decodeTripUpdates(
encodeTripUpdates({
trips: [
{
tripId: 'x',
routeId: 'r',
delay: 999_999,
stops: [
{ stopId: 'a', arrival: { time: 12, delay: 10 } },
{ stopId: 'b', arrival: { time: 9_999_999_999 } },
{ sequence: 4 },
{},
],
},
],
}),
);
const [trip] = decoded.trips;
assert.equal(trip.delaySec, 10, 'a delay of eleven days is not a delay');
assert.deepEqual(trip.stops[0].arrival, { time: null, delay: 10 });
assert.equal(trip.stops[1].arrival, null, 'a time past 2100 is no time');
assert.equal(
trip.stops.length,
3,
'a stop with no id or sequence is dropped',
);
});
test('stops past the per-trip cap are left unread and the trip says so', () => {
const stops = Array.from(
{ length: RAIL_TRIP_UPDATE_MAX_STOPS + 5 },
(_, i) => ({ stopId: `s${i}`, sequence: i, arrival: { delay: 0 } }),
);
const [trip] = decodeTripUpdates(
encodeTripUpdates({ trips: [{ tripId: 'long', routeId: 'r', stops }] }),
).trips;
assert.equal(trip.stops.length, RAIL_TRIP_UPDATE_MAX_STOPS);
assert.equal(trip.stopsTruncated, true);
});
test('over-long strings drop the record, deleted and empty entities are skipped', () => {
const long = 'x'.repeat(300);
const decoded = decodeTripUpdates(
encodeTripUpdates({
trips: [
{ tripId: long, routeId: 'r' },
{ tripId: 'gone', routeId: 'r', deleted: true },
{ id: 'empty' },
{
tripId: 'ok',
routeId: 'r',
stops: [{ stopId: long, sequence: 1 }, { stopId: 'fine' }],
},
],
}),
);
assert.deepEqual(
decoded.trips.map((trip) => trip.tripId),
['ok'],
);
assert.deepEqual(
decoded.trips[0].stops.map((stop) => stop.stopId),
['fine'],
);
assert.equal(normalizeTripUpdateEntity(null), null);
assert.equal(normalizeTripUpdateEntity({ id: 'v' }), null);
});
test('every trip is decoded, up to the shared entity cap, whatever the caller asks', () => {
// The decoder takes no per-caller filter (`keep`) or entity cap
// (`maxEntities`): options like these change nothing.
const trips = Array.from({ length: GTFS_MAX_ENTITIES + 1 }, (_, i) => ({
tripId: `t${i}`,
}));
const decoded = decodeTripUpdates(encodeTripUpdates({ trips }), {
keep: () => false,
maxEntities: GTFS_MAX_ENTITIES * 2,
});
assert.equal(decoded.entityCount, GTFS_MAX_ENTITIES);
assert.equal(decoded.truncated, true);
assert.equal(
decoded.trips.length,
Math.min(GTFS_MAX_ENTITIES, RAIL_TRIP_UPDATE_MAX_TRIPS),
);
assert.equal(decoded.skipped, undefined);
assert.equal(decoded.feedVersion, undefined);
});
test('incrementality is reported so the proxy can refuse differential feeds', () => {
assert.equal(
decodeTripUpdates(encodeTripUpdates({ incrementality: 1 })).incrementality,
1,
);
const empty = decodeTripUpdates(new Uint8Array(0));
assert.equal(empty.incrementality, 0);
assert.equal(empty.timestamp, null);
assert.deepEqual(empty.trips, []);
});
+1
View File
@@ -7,6 +7,7 @@ export const SPRITE_LAYER_ORDER = Object.freeze([
'bikeshare',
'transit',
'transit-motion',
'rail',
'directions',
'ais',
'military',
+16 -4
View File
@@ -55,6 +55,17 @@ import { clearTr3bRegistry, setTr3b } from './tr3bRegistry.js';
import { reportMeshFloorCell, _clearMeshFloorCellsForTest } from './groundFloor.js';
import { bindFakeCesiumCamera } from '../testSupport/fakeCameraPort.mjs';
import { fakeDrawPort } from '../testSupport/fakeDrawPort.mjs';
import { loadFleetModelSet } from './fleetModels.js';
import { aircraftLayerModelSpec } from '../layers/flights/modelSpec.js';
import { fetchPublicFile } from '../testSupport/fleetGlb.mjs';
// The layers draw only once the fleet model set has loaded; load it from disk.
const _silentInfo = console.info;
console.info = () => {};
await loadFleetModelSet({ fetchImpl: fetchPublicFile });
console.info = _silentInfo;
const FLIGHTS_META = Object.freeze({ typeCode: 'A320', klass: 'airliner' });
const MILITARY_META = Object.freeze({ typeCode: 'F16', klass: 'fastjet' });
// Sample altitudes are expressed RELATIVE to the band rather than as absolute
// offsets. The thresholds have already been retuned once (1_000_000 → 150_000
@@ -245,7 +256,8 @@ const LAYERS = [
trackedModel: flightsTrackedModel,
modelSetIds: flightsModelSetIds,
trackedBillboardColor: flightsTrackedBillboardColor,
bellyM: 6.719,
/** How far a grounded A320 stands its origin above the ground (scaled wheel clearance). */
bellyM: aircraftLayerModelSpec(FLIGHTS_META).bellyM,
seed({ viewer, tracked = true, icao24 = ICAO, onGround = false, models = [] }) {
const billboard = contactBillboard();
_setTrackedFlightRefreshStateForTest({
@@ -257,7 +269,7 @@ const LAYERS = [
tracked,
models,
draw: viewer.draw,
meta: { callsign: 'TEST123 ', altitude: 10_668, klass: 'airliner', onGround },
meta: { callsign: 'TEST123 ', altitude: 10_668, ...FLIGHTS_META, onGround },
});
return iconView(icao24, flightsIcon, flightsSetIcon);
},
@@ -272,7 +284,7 @@ const LAYERS = [
trackedModel: militaryTrackedModel,
modelSetIds: militaryModelSetIds,
trackedBillboardColor: militaryTrackedBillboardColor,
bellyM: 5.631 * 0.8,
bellyM: aircraftLayerModelSpec(MILITARY_META).bellyM,
seed({ viewer, tracked = true, icao24 = ICAO, onGround = false, models = [] }) {
const billboard = contactBillboard();
_setTrackedMilitaryRefreshStateForTest({
@@ -284,7 +296,7 @@ const LAYERS = [
tracked,
models,
draw: viewer.draw,
meta: { callsign: 'TEST123 ', altitudeFt: 35_000, klass: 'fastjet', onGround },
meta: { callsign: 'TEST123 ', altitudeFt: 35_000, ...MILITARY_META, onGround },
});
return iconView(icao24, militaryIcon, militarySetIcon);
},