Files
gods-eye-view/src/sources/live/standalone.js
T
Sameh Khamis 60644c5f5d feat: name live feed routes and sources for what they serve
The flight, military and vessel feeds were named after the providers the
bundled server uses (/api/opensky, /api/adsblol/mil, /api/ais-live and
their track routes; createOpenSkySource, createAdsbLolSource,
createAisStreamSource). Any server should be able to answer a feed from
its own provider, so the feeds are now:

  /api/flights   /api/flights/track?icao24=
  /api/military  /api/military/track?hex=
  /api/vessels   /api/vessels/track?mmsi=

with createFlightSource, createMilitarySource and createVesselSource. The
old routes are removed. Each server names its provider in X-Feed-Source
(the bundled server sends OpenSky Network, adsb.lol and AISStream, so its
attribution is unchanged) and the military feed's cache state and age in
X-Feed-Cache and X-Feed-Age-Ms. Sources report the provider the server
names and fall back to the feed's name.
2026-10-03 23:10:32 -07:00

242 lines
7.7 KiB
JavaScript

import {
epoch,
finite,
httpError,
LiveSourceError,
readResponse,
} from './contract.js';
import {
normalizeAircraftTrack,
openSkySnapshot,
readsbSnapshot,
readsbIdentities,
} from './aircraft.js';
import { normalizeVesselTrack, vesselSnapshot } from './vessels.js';
const defaultFetch = (...args) => globalThis.fetch(...args);
const header = (response, name) => response.headers?.get?.(name);
function openSkyError(response) {
const error = httpError(response, 'Flights');
const mode = String(
header(response, 'x-opensky-auth-mode-used') ||
header(response, 'x-opensky-auth') ||
'',
).toLowerCase();
const reason = String(
header(response, 'x-opensky-auth-reason') || '',
).toLowerCase();
if (response.status === 429 && (!mode || mode === 'anon'))
error.message = 'OpenSky rate limited (anonymous)';
if (response.status === 401 || response.status === 403) {
const reasons = {
oauth_invalid_or_missing: 'OpenSky OAuth client missing/invalid',
oauth_invalid_credentials: 'OpenSky OAuth rejected credentials',
basic_invalid_credentials: 'OpenSky username/password rejected',
missing_basic_creds: 'OpenSky auth missing',
missing_oauth_and_basic_creds: 'OpenSky auth missing',
auth_required: 'OpenSky auth required',
forced_anonymous: 'OpenSky auth required',
};
error.message =
reasons[reason] ||
(/^(oauth_|basic_)/.test(reason)
? 'OpenSky auth invalid'
: mode === 'anon'
? 'OpenSky auth required'
: 'OpenSky auth failed');
}
return error;
}
/**
* The provider a feed response names in `X-Feed-Source`, so a server that
* answers a feed route from another provider is reported as that provider.
*/
function feedSource(response, fallback) {
const named = header(response, 'x-feed-source');
return typeof named === 'string' && named.trim()
? named.trim().slice(0, 80)
: fallback;
}
/** The flights feed (/api/flights); no request starts during construction. */
export function createFlightSource({
fetchImpl = defaultFetch,
now = () => Date.now(),
} = {}) {
return {
label: 'Flights',
async getSnapshot(query = {}, { signal } = {}) {
const params = new URLSearchParams();
if (Number.isFinite(query.latitude) && Number.isFinite(query.longitude)) {
params.set('lat', query.latitude.toFixed(4));
params.set('lon', query.longitude.toFixed(4));
}
const { response, payload } = await readResponse(
fetchImpl,
`/api/flights${params.size ? '?' + params : ''}`,
{ signal },
'Flights',
);
if (!response.ok) throw openSkyError(response);
return {
...openSkySnapshot(payload, {
// A fallback provider names itself in X-Flight-Source.
source:
header(response, 'x-flight-source') ||
feedSource(response, 'Flights'),
coverage:
header(response, 'x-flight-coverage') ||
'worldwide upstream snapshot',
now: now(),
}),
status: response.status,
};
},
async getTrack(reference, { signal } = {}) {
const { response, payload } = await readResponse(
fetchImpl,
'/api/flights/track?icao24=' + encodeURIComponent(reference),
{ signal },
'Flights',
);
if (!response.ok) throw httpError(response, 'Flights');
return {
records: normalizeAircraftTrack(payload?.path),
complete: false,
};
},
async getEnrichment(query, { signal } = {}) {
if (!['type', 'route'].includes(query.kind))
throw new LiveSourceError('unsupported', 'Enrichment unavailable');
const { response, payload } = await readResponse(
fetchImpl,
`/api/adsbdb/${query.kind}/${encodeURIComponent(query.id)}`,
{ signal },
'adsbdb',
);
if (!response.ok) throw httpError(response, 'adsbdb');
return payload;
},
};
}
export function createMilitarySource({
fetchImpl = defaultFetch,
now = () => Date.now(),
} = {}) {
return {
label: 'Military aircraft',
async getIdentities(_query = {}, { signal } = {}) {
const { response, payload } = await readResponse(
fetchImpl,
'/api/military',
{ signal },
'Military aircraft',
);
if (!response.ok) throw httpError(response, 'Military aircraft');
return readsbIdentities(payload);
},
async getSnapshot(_query = {}, { signal } = {}) {
const { response, payload } = await readResponse(
fetchImpl,
'/api/military',
{ signal },
'Military aircraft',
);
if (!response.ok) throw httpError(response, 'Military aircraft');
const age = finite(header(response, 'x-feed-age-ms'));
return {
...readsbSnapshot(payload, {
source: feedSource(response, 'Military aircraft'),
observedAtMs: now() - (age != null && age > 0 ? age : 0),
now: now(),
stale: header(response, 'x-feed-cache') === 'STALE',
}),
status: response.status,
};
},
async getTrack(reference, { signal } = {}) {
const { response, payload } = await readResponse(
fetchImpl,
'/api/military/track?hex=' + encodeURIComponent(reference),
{ signal },
'Military aircraft',
);
if (!response.ok) throw httpError(response, 'Military aircraft');
const baseTimeMs = epoch(payload?.timestamp, 1000);
return {
records:
baseTimeMs == null
? []
: normalizeAircraftTrack(payload?.trace, {
baseTimeMs,
readsb: true,
}),
complete: false,
};
},
};
}
export function createVesselSource({
fetchImpl = defaultFetch,
apiUrl = '/api/vessels',
origin = () => globalThis.location?.origin || 'http://localhost',
} = {}) {
return {
label: 'Vessels',
async getSnapshot({ maxRows = 12000, area } = {}, { signal } = {}) {
const url = new URL(apiUrl, origin());
url.searchParams.set('maxRows', String(maxRows));
// An area asks for the vessels around a point; servers that hold every
// vessel may ignore it, since callers still keep only what they need.
if (
Number.isFinite(area?.lat) &&
Number.isFinite(area?.lon) &&
Number.isFinite(area?.radiusKm)
) {
url.searchParams.set('lat', area.lat.toFixed(5));
url.searchParams.set('lon', area.lon.toFixed(5));
url.searchParams.set('radius_km', area.radiusKm.toFixed(1));
}
const { response, payload } = await readResponse(
fetchImpl,
url.toString(),
{ signal, cache: 'no-store' },
'Vessels',
);
if (!response.ok) {
const error = httpError(response, 'Vessels');
const reasons = {
'missing-key': 'AISSTREAM_API_KEY not set',
'auth-failed': 'API key rejected — check AISSTREAM_API_KEY',
unsupported: 'live feed unsupported',
error: 'feed down',
closed: 'feed disconnected',
};
error.message = reasons[payload?.status] || error.message;
throw error;
}
return {
...vesselSnapshot(payload, { source: feedSource(response, 'Vessels') }),
status: response.status,
};
},
async getTrack(reference, { signal } = {}) {
const { response, payload } = await readResponse(
fetchImpl,
'/api/vessels/track?mmsi=' + encodeURIComponent(reference),
{ signal },
'Vessels',
);
if (!response.ok) throw httpError(response, 'Vessels');
return {
records: normalizeVesselTrack(payload?.samples),
complete: false,
};
},
};
}