mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-11-21 19:40:34 +00:00
feat(flight-live): follow booked flights live from keyless ADS-B feeds
A new flight-live domain polls the open feeds adsb.lol and adsb.fi (no key, no cost; adsb.fi only on self-hosted installs, its terms are non-commercial) for every booked flight leg in its watch window, derives phase, take-off, landing, delay and an arrival estimate, and pushes changes as flight:live. GET /api/trips/:tripId/flights/live, the MCP tool get_trip_flight_status, notifications for take-off, landing and delays, and the admin switch flight_live_enabled (FLIGHT_LIVE_ENABLED wins) come with it.
This commit is contained in:
@@ -111,6 +111,12 @@ export function deriveSession(raw: RawEnv) {
|
||||
};
|
||||
}
|
||||
|
||||
/** A boolean variable as the stored settings spell it, or undefined when unset or not a boolean. */
|
||||
function flagText(raw: string | undefined): 'true' | 'false' | undefined {
|
||||
const value = parseBool(raw);
|
||||
return value === undefined ? undefined : value ? 'true' : 'false';
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether this instance is centrally administered: somebody other than its
|
||||
* admin user owns the configuration, the credentials and the upgrade schedule.
|
||||
@@ -312,6 +318,12 @@ export function deriveIntegrations(raw: RawEnv) {
|
||||
* request whose prompt plus cap overruns its context (#2677).
|
||||
*/
|
||||
llmMaxOutputTokens: positiveIntOr(raw.LLM_MAX_OUTPUT_TOKENS, 0) || undefined,
|
||||
/**
|
||||
* The operator's word on live flight status, as the admin setting spells it
|
||||
* ('true'/'false'), or undefined when unset or not a boolean: then the admin
|
||||
* switch (`flight_live_enabled`) decides.
|
||||
*/
|
||||
flightLiveEnabled: flagText(raw.FLIGHT_LIVE_ENABLED),
|
||||
// TRANSIT_API_URL, KITINERARY_EXTRACTOR_PATH and PATH are boot-stable and
|
||||
// read only by Nest providers, so the transitConfig and kitineraryConfig
|
||||
// tokens own them (boot-derive.ts).
|
||||
|
||||
@@ -185,6 +185,7 @@ export const envSchema = z.object({
|
||||
GOOGLE_LIST_DATA_BASE: url,
|
||||
TREK_PLACES_URL: url,
|
||||
TREK_PLACES_ENABLED: boolStr,
|
||||
FLIGHT_LIVE_ENABLED: boolStr,
|
||||
TREK_PLACES_CONTRIBUTE: oneOf(['off', 'admin']),
|
||||
TREK_SERVICES: oneOf(['auto', 'off']),
|
||||
TREK_SERVICES_KEY: optionalWith(isServiceKeyShape, 'must be a TREK services key (tk1.<kid>.<payload>.<signature>)'),
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
import { EntityRepositoryType, type Opt, PrimaryKeyProp, defineEntity, p } from '@mikro-orm/core';
|
||||
import { FlightLiveStatesRepository } from '../repositories/FlightLiveStates.repository';
|
||||
import { DbTimestampType } from '../types';
|
||||
|
||||
export class FlightLiveStates {
|
||||
[EntityRepositoryType]?: FlightLiveStatesRepository;
|
||||
[PrimaryKeyProp]?: ['callsign', 'service_date', 'origin', 'destination'];
|
||||
callsign!: string;
|
||||
service_date!: string;
|
||||
origin!: string;
|
||||
destination!: string;
|
||||
phase: string & Opt = 'scheduled';
|
||||
departed_at?: string | null;
|
||||
landed_at?: string | null;
|
||||
lat?: number | null;
|
||||
lng?: number | null;
|
||||
altitude_ft?: number | null;
|
||||
ground_speed_kt?: number | null;
|
||||
track_deg?: number | null;
|
||||
vertical_rate_fpm?: number | null;
|
||||
on_ground?: number | null;
|
||||
registration?: string | null;
|
||||
aircraft_type?: string | null;
|
||||
source?: string | null;
|
||||
first_seen_at?: string | null;
|
||||
last_seen_at?: string | null;
|
||||
fetched_at?: string | null;
|
||||
next_poll_at?: string | null;
|
||||
fail_count: number & Opt = 0;
|
||||
departed_notified: number & Opt = 0;
|
||||
landed_notified: number & Opt = 0;
|
||||
delay_notified: number & Opt = 0;
|
||||
}
|
||||
|
||||
export const FlightLiveStatesSchema = defineEntity({
|
||||
class: FlightLiveStates,
|
||||
repository: () => FlightLiveStatesRepository,
|
||||
properties: {
|
||||
callsign: p.text().primary(),
|
||||
service_date: p.text().primary(),
|
||||
origin: p.text().primary(),
|
||||
destination: p.text().primary(),
|
||||
phase: p.text().default('scheduled'),
|
||||
departed_at: p.type(DbTimestampType).nullable(),
|
||||
landed_at: p.type(DbTimestampType).nullable(),
|
||||
lat: p.double().nullable(),
|
||||
lng: p.double().nullable(),
|
||||
altitude_ft: p.double().nullable(),
|
||||
ground_speed_kt: p.double().nullable(),
|
||||
track_deg: p.double().nullable(),
|
||||
vertical_rate_fpm: p.double().nullable(),
|
||||
on_ground: p.integer().nullable(),
|
||||
registration: p.text().nullable(),
|
||||
aircraft_type: p.text().nullable(),
|
||||
source: p.text().nullable(),
|
||||
first_seen_at: p.type(DbTimestampType).nullable(),
|
||||
last_seen_at: p.type(DbTimestampType).nullable(),
|
||||
fetched_at: p.type(DbTimestampType).nullable(),
|
||||
next_poll_at: p.type(DbTimestampType).nullable(),
|
||||
fail_count: p.integer().default(0),
|
||||
departed_notified: p.integer().default(0),
|
||||
landed_notified: p.integer().default(0),
|
||||
delay_notified: p.integer().default(0),
|
||||
},
|
||||
});
|
||||
@@ -40,6 +40,7 @@ import { DocumentProvidersSchema } from './DocumentProviders.entity';
|
||||
import { DocumentSyncItemsSchema } from './DocumentSyncItems.entity';
|
||||
import { FerrataTilesSchema } from './FerrataTiles.entity';
|
||||
import { FileLinksSchema } from './FileLinks.entity';
|
||||
import { FlightLiveStatesSchema } from './FlightLiveStates.entity';
|
||||
import { GoogleApiUsageSchema } from './GoogleApiUsage.entity';
|
||||
import { GooglePlacePhotoMetaSchema } from './GooglePlacePhotoMeta.entity';
|
||||
import { HiddenCountriesSchema } from './HiddenCountries.entity';
|
||||
@@ -209,6 +210,7 @@ export const ALL_ENTITIES: readonly EntitySchema[] = [
|
||||
DocumentSyncItemsSchema,
|
||||
FerrataTilesSchema,
|
||||
FileLinksSchema,
|
||||
FlightLiveStatesSchema,
|
||||
GoogleApiUsageSchema,
|
||||
GooglePlacePhotoMetaSchema,
|
||||
HiddenCountriesSchema,
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
// Generated by scripts/generate-db-types.ts from the migrated schema. Do not edit by hand:
|
||||
// change the migration, then run `npm run gen:db-types`.
|
||||
import type { InsertOptional } from './columns';
|
||||
|
||||
export interface FlightLiveStatesTable {
|
||||
callsign: string;
|
||||
service_date: string;
|
||||
origin: string;
|
||||
destination: string;
|
||||
phase: InsertOptional<string>;
|
||||
departed_at: InsertOptional<string | null>;
|
||||
landed_at: InsertOptional<string | null>;
|
||||
lat: InsertOptional<number | null>;
|
||||
lng: InsertOptional<number | null>;
|
||||
altitude_ft: InsertOptional<number | null>;
|
||||
ground_speed_kt: InsertOptional<number | null>;
|
||||
track_deg: InsertOptional<number | null>;
|
||||
vertical_rate_fpm: InsertOptional<number | null>;
|
||||
on_ground: InsertOptional<number | null>;
|
||||
registration: InsertOptional<string | null>;
|
||||
aircraft_type: InsertOptional<string | null>;
|
||||
source: InsertOptional<string | null>;
|
||||
first_seen_at: InsertOptional<string | null>;
|
||||
last_seen_at: InsertOptional<string | null>;
|
||||
fetched_at: InsertOptional<string | null>;
|
||||
next_poll_at: InsertOptional<string | null>;
|
||||
fail_count: InsertOptional<number>;
|
||||
departed_notified: InsertOptional<number>;
|
||||
landed_notified: InsertOptional<number>;
|
||||
delay_notified: InsertOptional<number>;
|
||||
}
|
||||
@@ -43,6 +43,7 @@ import type { DocumentProvidersTable } from './DocumentProviders.table';
|
||||
import type { DocumentSyncItemsTable } from './DocumentSyncItems.table';
|
||||
import type { FerrataTilesTable } from './FerrataTiles.table';
|
||||
import type { FileLinksTable } from './FileLinks.table';
|
||||
import type { FlightLiveStatesTable } from './FlightLiveStates.table';
|
||||
import type { GoogleApiUsageTable } from './GoogleApiUsage.table';
|
||||
import type { GooglePlacePhotoMetaTable } from './GooglePlacePhotoMeta.table';
|
||||
import type { HiddenCountriesTable } from './HiddenCountries.table';
|
||||
@@ -218,6 +219,7 @@ export interface DB {
|
||||
document_sync_items: DocumentSyncItemsTable;
|
||||
ferrata_tiles: FerrataTilesTable;
|
||||
file_links: FileLinksTable;
|
||||
flight_live_states: FlightLiveStatesTable;
|
||||
google_api_usage: GoogleApiUsageTable;
|
||||
google_place_photo_meta: GooglePlacePhotoMetaTable;
|
||||
hidden_countries: HiddenCountriesTable;
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
import { Migration } from '@mikro-orm/migrations';
|
||||
|
||||
/**
|
||||
* Live flight status: what the open ADS-B feeds last said about one flight on
|
||||
* one day, keyed by the callsign it transmits, its local departure date and
|
||||
* its two airports. A through flight keeps one flight number over two sectors
|
||||
* (FRA to BOM to SIN as LH 754 on one day), and each sector has a state of its own.
|
||||
* One row serves every trip that booked the same flight, so the feeds are asked
|
||||
* once per flight, not once per traveller. Next to the derived state sit the
|
||||
* poll's bookkeeping (when to ask next, how often it failed) and whether each
|
||||
* notification already went out, so a departure is announced once.
|
||||
*
|
||||
* No foreign key: the row describes a flight in the air, not a booking, and is
|
||||
* found again from the bookings by its key.
|
||||
*/
|
||||
export class Migration20200101046400_a_booked_flight_shows_where_it_is extends Migration {
|
||||
override name = 'Migration20200101046400_a_booked_flight_shows_where_it_is';
|
||||
|
||||
override up(): void {
|
||||
this.addSql(`
|
||||
CREATE TABLE IF NOT EXISTS flight_live_states (
|
||||
callsign TEXT NOT NULL,
|
||||
service_date TEXT NOT NULL,
|
||||
origin TEXT NOT NULL,
|
||||
destination TEXT NOT NULL,
|
||||
phase TEXT NOT NULL DEFAULT 'scheduled',
|
||||
departed_at DATETIME,
|
||||
landed_at DATETIME,
|
||||
lat REAL,
|
||||
lng REAL,
|
||||
altitude_ft REAL,
|
||||
ground_speed_kt REAL,
|
||||
track_deg REAL,
|
||||
vertical_rate_fpm REAL,
|
||||
on_ground INTEGER,
|
||||
registration TEXT,
|
||||
aircraft_type TEXT,
|
||||
source TEXT,
|
||||
first_seen_at DATETIME,
|
||||
last_seen_at DATETIME,
|
||||
fetched_at DATETIME,
|
||||
next_poll_at DATETIME,
|
||||
fail_count INTEGER NOT NULL DEFAULT 0,
|
||||
departed_notified INTEGER NOT NULL DEFAULT 0,
|
||||
landed_notified INTEGER NOT NULL DEFAULT 0,
|
||||
delay_notified INTEGER NOT NULL DEFAULT 0,
|
||||
PRIMARY KEY (callsign, service_date, origin, destination)
|
||||
)
|
||||
`);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,210 @@
|
||||
import type { FlightLiveStates } from '../entities/FlightLiveStates.entity';
|
||||
import type { DB } from '../kysely/db';
|
||||
import type { DbTimestamp } from '../types';
|
||||
import { TrekRepository } from './_shared/trek-repository';
|
||||
|
||||
/** A flight booking as the live flight status reads it; the metadata is the stored text. */
|
||||
export interface FlightBookingDbRow {
|
||||
id: number;
|
||||
trip_id: number;
|
||||
trip_title: string;
|
||||
metadata: string | null;
|
||||
day_id: number | null;
|
||||
end_day_id: number | null;
|
||||
reservation_time: string | null;
|
||||
reservation_end_time: string | null;
|
||||
}
|
||||
|
||||
interface FlightEndpointDbRow {
|
||||
reservation_id: number;
|
||||
role: string;
|
||||
sequence: number;
|
||||
name: string;
|
||||
code: string | null;
|
||||
lat: number;
|
||||
lng: number;
|
||||
timezone: string | null;
|
||||
local_date: string | null;
|
||||
local_time: string | null;
|
||||
}
|
||||
|
||||
/**
|
||||
* One flight state, every column; timestamps in the canonical UTC text. `T`
|
||||
* is `string` for a row read back and `DbTimestamp` for one being written.
|
||||
*/
|
||||
interface FlightLiveStateFields<T extends string> {
|
||||
callsign: string;
|
||||
service_date: string;
|
||||
origin: string;
|
||||
destination: string;
|
||||
phase: string;
|
||||
departed_at: T | null;
|
||||
landed_at: T | null;
|
||||
lat: number | null;
|
||||
lng: number | null;
|
||||
altitude_ft: number | null;
|
||||
ground_speed_kt: number | null;
|
||||
track_deg: number | null;
|
||||
vertical_rate_fpm: number | null;
|
||||
on_ground: number | null;
|
||||
registration: string | null;
|
||||
aircraft_type: string | null;
|
||||
source: string | null;
|
||||
first_seen_at: T | null;
|
||||
last_seen_at: T | null;
|
||||
fetched_at: T | null;
|
||||
next_poll_at: T | null;
|
||||
fail_count: number;
|
||||
departed_notified: number;
|
||||
landed_notified: number;
|
||||
delay_notified: number;
|
||||
}
|
||||
|
||||
export type FlightLiveStateRow = FlightLiveStateFields<string>;
|
||||
export type FlightLiveStateWrite = FlightLiveStateFields<DbTimestamp>;
|
||||
|
||||
const BOOKING_COLUMNS = [
|
||||
'reservations.id',
|
||||
'reservations.trip_id',
|
||||
'reservations.metadata',
|
||||
'reservations.day_id',
|
||||
'reservations.end_day_id',
|
||||
'reservations.reservation_time',
|
||||
'reservations.reservation_end_time',
|
||||
] as const;
|
||||
|
||||
const ENDPOINT_COLUMNS = [
|
||||
'reservation_id',
|
||||
'role',
|
||||
'sequence',
|
||||
'name',
|
||||
'code',
|
||||
'lat',
|
||||
'lng',
|
||||
'timezone',
|
||||
'local_date',
|
||||
'local_time',
|
||||
] as const;
|
||||
|
||||
/**
|
||||
* `flight_live_states`: what the open ADS-B feeds last said about a flight on
|
||||
* a day, one row per (callsign, service date, origin, destination) whichever
|
||||
* trips booked it.
|
||||
*
|
||||
* The flight bookings, their endpoints, the days they name and their
|
||||
* travellers are read here too, through Kysely: the live status only reads
|
||||
* them, and the reservations domain has no read of flights across all trips.
|
||||
*/
|
||||
export class FlightLiveStatesRepository extends TrekRepository<FlightLiveStates> {
|
||||
/** The flight bookings of one trip. */
|
||||
async listFlightBookingsForTrip(trip_id: number): Promise<FlightBookingDbRow[]> {
|
||||
return await this.kysely<Pick<DB, 'reservations' | 'trips'>>()
|
||||
.selectFrom('reservations')
|
||||
.innerJoin('trips', 'trips.id', 'reservations.trip_id')
|
||||
.select([...BOOKING_COLUMNS, 'trips.title as trip_title'])
|
||||
.where('reservations.trip_id', '=', trip_id)
|
||||
.where('reservations.type', '=', 'flight')
|
||||
.orderBy('reservations.id')
|
||||
.execute();
|
||||
}
|
||||
|
||||
/**
|
||||
* The flight bookings of every trip that is not archived and whose dates
|
||||
* (where it has any) reach into `from_date`..`to_date`: the candidates for a
|
||||
* poll. Which leg is really in its window the caller works out from the
|
||||
* schedule.
|
||||
*/
|
||||
async listFlightBookingsBetween(from_date: string, to_date: string): Promise<FlightBookingDbRow[]> {
|
||||
return await this.kysely<Pick<DB, 'reservations' | 'trips'>>()
|
||||
.selectFrom('reservations')
|
||||
.innerJoin('trips', 'trips.id', 'reservations.trip_id')
|
||||
.select([...BOOKING_COLUMNS, 'trips.title as trip_title'])
|
||||
.where('reservations.type', '=', 'flight')
|
||||
.where((eb) => eb.or([eb('trips.is_archived', 'is', null), eb('trips.is_archived', '=', 0)]))
|
||||
.where((eb) => eb.or([eb('trips.end_date', 'is', null), eb('trips.end_date', '>=', from_date)]))
|
||||
.where((eb) => eb.or([eb('trips.start_date', 'is', null), eb('trips.start_date', '<=', to_date)]))
|
||||
.orderBy('reservations.id')
|
||||
.execute();
|
||||
}
|
||||
|
||||
/** The endpoints of the given bookings, in their order. */
|
||||
async listEndpoints(reservation_ids: readonly number[]): Promise<FlightEndpointDbRow[]> {
|
||||
if (reservation_ids.length === 0) return [];
|
||||
return await this.kysely<Pick<DB, 'reservation_endpoints'>>()
|
||||
.selectFrom('reservation_endpoints')
|
||||
.select([...ENDPOINT_COLUMNS])
|
||||
.where('reservation_id', 'in', [...reservation_ids])
|
||||
.orderBy('reservation_id')
|
||||
.orderBy('sequence')
|
||||
.execute();
|
||||
}
|
||||
|
||||
/** The date of each given trip day that has one. */
|
||||
async listDayDates(day_ids: readonly number[]): Promise<Array<{ id: number; date: string }>> {
|
||||
if (day_ids.length === 0) return [];
|
||||
const rows = await this.kysely<Pick<DB, 'days'>>()
|
||||
.selectFrom('days')
|
||||
.select(['id', 'date'])
|
||||
.where('id', 'in', [...day_ids])
|
||||
.execute();
|
||||
return rows.flatMap((row) => (row.date ? [{ id: row.id, date: row.date }] : []));
|
||||
}
|
||||
|
||||
/**
|
||||
* The users put on a booking as its travellers who still belong to its trip:
|
||||
* the owner or a member. Someone removed from the trip stays on the
|
||||
* traveller list until it is edited, and must hear nothing more of it.
|
||||
*/
|
||||
async listTravelerIds(reservation_id: number): Promise<number[]> {
|
||||
const rows = await this.kysely<Pick<DB, 'reservation_travelers' | 'reservations' | 'trips' | 'trip_members'>>()
|
||||
.selectFrom('reservation_travelers as rt')
|
||||
.innerJoin('reservations as r', 'r.id', 'rt.reservation_id')
|
||||
.innerJoin('trips as t', 't.id', 'r.trip_id')
|
||||
.select('rt.user_id')
|
||||
.where('rt.reservation_id', '=', reservation_id)
|
||||
.where((eb) =>
|
||||
eb.or([
|
||||
eb('t.user_id', '=', eb.ref('rt.user_id')),
|
||||
eb.exists(
|
||||
eb
|
||||
.selectFrom('trip_members as tm')
|
||||
.select('tm.id')
|
||||
.whereRef('tm.trip_id', '=', 'r.trip_id')
|
||||
.whereRef('tm.user_id', '=', 'rt.user_id'),
|
||||
),
|
||||
]),
|
||||
)
|
||||
.orderBy('rt.user_id')
|
||||
.execute();
|
||||
return rows.map((row) => row.user_id);
|
||||
}
|
||||
|
||||
/** Every stored state of the given callsigns, whatever their day. */
|
||||
async findForCallsigns(callsigns: readonly string[]): Promise<FlightLiveStateRow[]> {
|
||||
if (callsigns.length === 0) return [];
|
||||
return await this.kysely<Pick<DB, 'flight_live_states'>>()
|
||||
.selectFrom('flight_live_states')
|
||||
.selectAll()
|
||||
.where('callsign', 'in', [...callsigns])
|
||||
.execute();
|
||||
}
|
||||
|
||||
/** Writes a flight's whole state, replacing the one stored under its key. */
|
||||
async saveState(row: FlightLiveStateWrite): Promise<void> {
|
||||
const { callsign, service_date, origin, destination, ...changes } = row;
|
||||
await this.kysely<Pick<DB, 'flight_live_states'>>()
|
||||
.insertInto('flight_live_states')
|
||||
.values({ callsign, service_date, origin, destination, ...changes })
|
||||
.onConflict((oc) => oc.columns(['callsign', 'service_date', 'origin', 'destination']).doUpdateSet(changes))
|
||||
.execute();
|
||||
}
|
||||
|
||||
/** Drops the states of flights that departed before `service_date`; answers how many went. */
|
||||
async deleteBefore(service_date: string): Promise<number> {
|
||||
const result = await this.kysely<Pick<DB, 'flight_live_states'>>()
|
||||
.deleteFrom('flight_live_states')
|
||||
.where('service_date', '<', service_date)
|
||||
.executeTakeFirst();
|
||||
return Number(result.numDeletedRows);
|
||||
}
|
||||
}
|
||||
@@ -46,6 +46,7 @@ import { DocSyncModule } from './doc-sync/doc-sync.module';
|
||||
import { FeedsModule } from './feeds/feeds.module';
|
||||
import { FerratasModule } from './ferratas/ferratas.module';
|
||||
import { FilesModule } from './files/files.module';
|
||||
import { FlightLiveModule } from './flight-live/flight-live.module';
|
||||
import { GeoModule } from './geo/geo.module';
|
||||
import { GoogleQuotaModule } from './google-quota/google-quota.module';
|
||||
import { HealthModule } from './health/health.module';
|
||||
@@ -178,6 +179,7 @@ import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_PIPE } from '@nestjs/core';
|
||||
PhotosModule,
|
||||
MemoriesModule,
|
||||
AirtrailModule,
|
||||
FlightLiveModule,
|
||||
DawarichModule,
|
||||
JourneyModule,
|
||||
JourneyRecordingsModule,
|
||||
|
||||
@@ -44,7 +44,7 @@ import { EphemeralTokenService } from '../auth-core/ephemeral-token.service';
|
||||
// every consumer of this module — a nest→mcp→nest module cycle.
|
||||
import { revokeUserSessions } from '../../mcp/sessionManager';
|
||||
import { UserCleanupService } from './user-cleanup.service';
|
||||
import { splitManagedKeys } from '../common/managed';
|
||||
import { envLockedKeys, splitManagedKeys, withEnvLocks } from '../common/managed';
|
||||
import { emitUserDeleted } from '../../plugin-user-lifecycle';
|
||||
import { verifyJwtAndLoadUser } from '../auth-core/jwt-verify';
|
||||
import { User } from '../../types';
|
||||
@@ -711,7 +711,7 @@ export class AuthService {
|
||||
const value = await readAppSetting(this.appSettings, key);
|
||||
if (value !== null) result[key] = MASKED_ADMIN_SETTING_KEYS.has(key) ? '••••••••' : value;
|
||||
}
|
||||
return { data: result };
|
||||
return { data: withEnvLocks(result) };
|
||||
}
|
||||
|
||||
async updateAppSettings(
|
||||
@@ -754,7 +754,7 @@ export class AuthService {
|
||||
// the admin does own, so a managed install skips those names and keeps the
|
||||
// rest of the save working. Reported, never thrown: the settings tab sends
|
||||
// the whole form in one request.
|
||||
const { blocked } = splitManagedKeys(body as Record<string, unknown>, readEnv().managed.enabled);
|
||||
const blocked = [...splitManagedKeys(body, readEnv().managed.enabled).blocked, ...envLockedKeys(body)];
|
||||
|
||||
await this.uow.transactional(async () => { // the whole form lands, or none of it
|
||||
for (const key of ADMIN_FORM_SETTING_KEYS) {
|
||||
|
||||
@@ -93,6 +93,8 @@ export const APP_SETTINGS = {
|
||||
// 'auto' (what every install had before Amap existed), 'google', 'amap' or
|
||||
// 'openstreetmap'; the maps domain validates it (isPlacesProviderChoice).
|
||||
places_provider: { schema: text, default: 'auto', adminForm: true, publicConfig: true, managedLocked: true },
|
||||
// Live flight status from the keyless ADS-B feeds (flight-live). On by default; FLIGHT_LIVE_ENABLED wins over it.
|
||||
flight_live_enabled: { schema: flag, default: 'true', env: (e) => e.integrations.flightLiveEnabled, adminForm: true },
|
||||
|
||||
// Read by name elsewhere.
|
||||
oidc_issuer: { schema: text, default: null, env: (e) => e.oidc.issuer, publicConfig: true },
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
import { readEnv } from '../../app-config';
|
||||
import { RuntimeEnvService } from '../app-config/runtime-env.service';
|
||||
import { APP_SETTINGS, type AppSettingDef, type AppSettingKey } from './app-settings.registry';
|
||||
import { byCodeUnit } from './compare';
|
||||
import { SetMetadata } from '@nestjs/common';
|
||||
|
||||
@@ -144,6 +146,7 @@ export const MANAGED_CUSTOMER_KEYS = [
|
||||
'dark_mode',
|
||||
'default_currency',
|
||||
'distance_unit',
|
||||
'flight_live_enabled',
|
||||
'map_provider',
|
||||
'map_tile_url',
|
||||
'mapbox_3d_enabled',
|
||||
@@ -192,3 +195,37 @@ export function splitManagedKeys<T extends Record<string, unknown>>(
|
||||
}
|
||||
return { allowed, blocked: blocked.sort(byCodeUnit) };
|
||||
}
|
||||
|
||||
/**
|
||||
* Admin form switches an environment variable holds once it is set. The
|
||||
* variable wins over the stored value anyway (resolveAppSetting), so the form
|
||||
* shows the variable's value and a save leaves the stored one alone instead of
|
||||
* pretending to change what still applies. SMTP keeps its old behaviour.
|
||||
*/
|
||||
const ENV_LOCKED_ADMIN_KEYS: readonly AppSettingKey[] = ['flight_live_enabled'];
|
||||
|
||||
/** The value the environment pins a switch to, or null while it is unset. */
|
||||
function envValue(key: AppSettingKey): string | null {
|
||||
return (APP_SETTINGS[key] as AppSettingDef).env?.(readEnv()) || null;
|
||||
}
|
||||
|
||||
/** The env-held switches the write body sends, which the save skips and reports like the operator's keys. */
|
||||
export function envLockedKeys(body: Record<string, unknown>): string[] {
|
||||
return ENV_LOCKED_ADMIN_KEYS.filter((key) => body[key] !== undefined && envValue(key) !== null);
|
||||
}
|
||||
|
||||
/**
|
||||
* The admin form's values with every env-held switch set to the value that
|
||||
* applies, and `env_override_<key>` beside it so the form can show the switch
|
||||
* locked (the shape of `env_override_oidc_only` in the app config).
|
||||
*/
|
||||
export function withEnvLocks(values: Record<string, string>): Record<string, string> {
|
||||
const out = { ...values };
|
||||
for (const key of ENV_LOCKED_ADMIN_KEYS) {
|
||||
const value = envValue(key);
|
||||
if (value === null) continue;
|
||||
out[key] = value;
|
||||
out[`env_override_${key}`] = value;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
@@ -0,0 +1,328 @@
|
||||
import { FlightLiveStates } from '../../db/entities/FlightLiveStates.entity';
|
||||
import type {
|
||||
FlightLiveStatesRepository,
|
||||
FlightLiveStateWrite,
|
||||
} from '../../db/repositories/FlightLiveStates.repository';
|
||||
import { dbNow, type DbTimestamp } from '../../db/types';
|
||||
import { logDebug, logError } from '../audit/audit-log.logger';
|
||||
import { NotificationsService, type NotificationPayload } from '../notifications/notifications.service';
|
||||
import { RealtimeService } from '../realtime/realtime.service';
|
||||
import {
|
||||
advance,
|
||||
closeIfOver,
|
||||
departureDelay,
|
||||
emptyState,
|
||||
failed,
|
||||
inWatchWindow,
|
||||
nextPollAt,
|
||||
pickAircraft,
|
||||
toLiveLeg,
|
||||
watchWindow,
|
||||
type LiveState,
|
||||
} from './flight-live.derive';
|
||||
import { FlightLiveFeedService, type FeedLookup } from './flight-live.feeds';
|
||||
import { FlightLiveService, legKey, type TripLeg } from './flight-live.service';
|
||||
import { InjectRepository } from '@mikro-orm/nestjs';
|
||||
import { Injectable } from '@nestjs/common';
|
||||
|
||||
type NotifEventType = NotificationPayload['event'];
|
||||
|
||||
const DAY_MS = 24 * 60 * 60 * 1000;
|
||||
/** A delay worth telling the travellers about, in minutes. */
|
||||
const DELAY_NOTICE_MIN = 15;
|
||||
/** A client's refresh brings a flight forward only when it is due within this anyway. */
|
||||
const REFRESH_AHEAD_MS = 2 * 60 * 1000;
|
||||
/** At most this many feed requests in one tick (a minute); the hourly budget is the real limit. */
|
||||
const MAX_REQUESTS_PER_TICK = 20;
|
||||
/** States of flights that departed longer ago are dropped. */
|
||||
const KEEP_DAYS = 30;
|
||||
|
||||
interface PollResult {
|
||||
asked: number;
|
||||
changed: number;
|
||||
skipped: 'disabled' | 'running' | null;
|
||||
}
|
||||
|
||||
function ts(ms: number | null): DbTimestamp | null {
|
||||
return ms === null ? null : dbNow(new Date(ms));
|
||||
}
|
||||
|
||||
function toWrite(state: LiveState): FlightLiveStateWrite {
|
||||
const p = state.position;
|
||||
return {
|
||||
callsign: state.callsign,
|
||||
service_date: state.service_date,
|
||||
origin: state.origin,
|
||||
destination: state.destination,
|
||||
phase: state.phase,
|
||||
departed_at: ts(state.departed_at),
|
||||
landed_at: ts(state.landed_at),
|
||||
lat: p?.lat ?? null,
|
||||
lng: p?.lng ?? null,
|
||||
altitude_ft: p?.altitude_ft ?? null,
|
||||
ground_speed_kt: p?.ground_speed_kt ?? null,
|
||||
track_deg: p?.track_deg ?? null,
|
||||
vertical_rate_fpm: p?.vertical_rate_fpm ?? null,
|
||||
on_ground: p ? (p.on_ground ? 1 : 0) : null,
|
||||
registration: state.registration,
|
||||
aircraft_type: state.aircraft_type,
|
||||
source: state.source,
|
||||
first_seen_at: ts(state.first_seen_at),
|
||||
last_seen_at: ts(state.last_seen_at),
|
||||
fetched_at: ts(state.fetched_at),
|
||||
next_poll_at: ts(state.next_poll_at),
|
||||
fail_count: state.fail_count,
|
||||
departed_notified: state.departed_notified ? 1 : 0,
|
||||
landed_notified: state.landed_notified ? 1 : 0,
|
||||
delay_notified: state.delay_notified ? 1 : 0,
|
||||
};
|
||||
}
|
||||
|
||||
/** What a client sees of a state; a poll that changed none of it is not broadcast. */
|
||||
function visible(state: LiveState): string {
|
||||
return JSON.stringify([
|
||||
state.phase,
|
||||
state.departed_at,
|
||||
state.landed_at,
|
||||
state.position,
|
||||
state.registration,
|
||||
state.aircraft_type,
|
||||
state.last_seen_at,
|
||||
]);
|
||||
}
|
||||
|
||||
/** The local date `days` away from `now`'s UTC date. */
|
||||
function utcDate(now: number, days: number): string {
|
||||
return new Date(now + days * DAY_MS).toISOString().slice(0, 10);
|
||||
}
|
||||
|
||||
/**
|
||||
* The poll behind live flight status, one tick a minute (FlightLiveJob).
|
||||
*
|
||||
* It reads every flight leg in its watch window across all trips, asks the
|
||||
* feed once per flight (callsign and departure day) that is due by its
|
||||
* cadence or that a client asked to refresh, within the instance's budget,
|
||||
* stores what changed, sends it to every trip holding the flight and tells
|
||||
* the travellers when the flight departs, lands or runs late.
|
||||
*/
|
||||
@Injectable()
|
||||
export class FlightLivePollService {
|
||||
private running = false;
|
||||
private lastPurgeDay: string | null = null;
|
||||
/** Waits between two requests; a test hands in one that does not. */
|
||||
sleep: (ms: number) => Promise<void> = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
||||
|
||||
constructor(
|
||||
@InjectRepository(FlightLiveStates) private readonly states: FlightLiveStatesRepository,
|
||||
private readonly live: FlightLiveService,
|
||||
private readonly feeds: FlightLiveFeedService,
|
||||
private readonly notifications: NotificationsService,
|
||||
private readonly realtime: RealtimeService,
|
||||
) {}
|
||||
|
||||
/**
|
||||
* One tick. A second call while one runs returns at once.
|
||||
*
|
||||
* @txIndependent every flight's state is one write of its own, with network
|
||||
* I/O between them; a tick cut short keeps what it stored.
|
||||
*/
|
||||
async poll(clock: () => number = Date.now): Promise<PollResult> {
|
||||
if (this.running) return { asked: 0, changed: 0, skipped: 'running' };
|
||||
this.running = true;
|
||||
try {
|
||||
if (!(await this.live.isEnabled())) return { asked: 0, changed: 0, skipped: 'disabled' };
|
||||
await this.purge(clock());
|
||||
return await this.pollDue(clock);
|
||||
} finally {
|
||||
this.running = false;
|
||||
}
|
||||
}
|
||||
|
||||
private async purge(now: number): Promise<void> {
|
||||
const today = utcDate(now, 0);
|
||||
if (this.lastPurgeDay === today) return;
|
||||
this.lastPurgeDay = today;
|
||||
const dropped = await this.states.deleteBefore(utcDate(now, -KEEP_DAYS));
|
||||
if (dropped > 0) logDebug(`[flight-live] dropped ${dropped} old flight states`);
|
||||
}
|
||||
|
||||
/**
|
||||
* @txIndependent one write per flight, with a feed request and the notices
|
||||
* between them; a flight stored stays stored if a later one fails.
|
||||
*/
|
||||
private async pollDue(clock: () => number): Promise<PollResult> {
|
||||
const now = clock();
|
||||
const bookings = await this.states.listFlightBookingsBetween(utcDate(now, -2), utcDate(now, 2));
|
||||
const loaded = await this.live.loadLegs(bookings);
|
||||
const stored = await this.live.statesFor(loaded);
|
||||
await this.closeEnded(loaded, stored, now);
|
||||
const groups = new Map<string, TripLeg[]>();
|
||||
for (const leg of loaded.filter((l) => inWatchWindow(l, now))) {
|
||||
groups.set(legKey(leg), [...(groups.get(legKey(leg)) ?? []), leg]);
|
||||
}
|
||||
const requested = this.live.takeRefreshRequests(now);
|
||||
const due = [...groups.keys()]
|
||||
.map((key) => ({ key, state: stored.get(key) ?? null }))
|
||||
.filter(({ key, state }) => {
|
||||
if (state?.phase === 'landed') return false;
|
||||
if (!state || state.next_poll_at === null) return true;
|
||||
// A client's ask may bring a flight forward a little, never past its cadence or a back-off.
|
||||
const ahead = requested.has(key) ? REFRESH_AHEAD_MS : 0;
|
||||
return state.next_poll_at - ahead <= now;
|
||||
})
|
||||
.sort(
|
||||
(a, b) =>
|
||||
Number(requested.has(b.key)) - Number(requested.has(a.key)) ||
|
||||
(a.state?.next_poll_at ?? 0) - (b.state?.next_poll_at ?? 0),
|
||||
);
|
||||
|
||||
const queue = due.slice(0, MAX_REQUESTS_PER_TICK).map(({ key, state }) => ({ legs: groups.get(key) ?? [], state }));
|
||||
const result: PollResult = { asked: 0, changed: 0, skipped: null };
|
||||
await this.pollEach(queue, clock, result);
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Closes every flight whose window ended while it was still taxiing or in
|
||||
* the air: stored as unknown with no next poll, and sent to its trips.
|
||||
*
|
||||
* @txIndependent one write per closed flight; each stands on its own.
|
||||
*/
|
||||
private async closeEnded(legs: readonly TripLeg[], stored: Map<string, LiveState>, now: number): Promise<void> {
|
||||
const ended = new Map<string, TripLeg[]>();
|
||||
for (const leg of legs) {
|
||||
const span = watchWindow(leg);
|
||||
if (span !== null && now > span.end) ended.set(legKey(leg), [...(ended.get(legKey(leg)) ?? []), leg]);
|
||||
}
|
||||
await [...ended].reduce(async (previous, [key, flightLegs]) => {
|
||||
await previous;
|
||||
const state = stored.get(key);
|
||||
const route = flightLegs[0];
|
||||
if (!state || !route) return;
|
||||
const closed = closeIfOver(state, route, now);
|
||||
if (closed === state) return;
|
||||
stored.set(key, closed);
|
||||
await this.states.saveState(toWrite(closed));
|
||||
this.broadcast(flightLegs, closed, now);
|
||||
}, Promise.resolve());
|
||||
}
|
||||
|
||||
/**
|
||||
* Asks about the flights one after the other, waiting out the feed spacing
|
||||
* between them, until the queue or the budget runs out.
|
||||
*
|
||||
* @txIndependent one write per flight (pollDue).
|
||||
*/
|
||||
private async pollEach(
|
||||
queue: ReadonlyArray<{ legs: TripLeg[]; state: LiveState | null }>,
|
||||
clock: () => number,
|
||||
result: PollResult,
|
||||
): Promise<void> {
|
||||
const [head, ...rest] = queue;
|
||||
const route = head?.legs[0];
|
||||
if (!head || !route) return;
|
||||
const wait = this.feeds.waitMs(clock());
|
||||
if (wait > 0) await this.sleep(wait);
|
||||
if (!this.feeds.canAsk(clock())) return;
|
||||
const prev =
|
||||
head.state ?? emptyState(route.callsign, route.service_date, route.origin.code, route.destination.code);
|
||||
const answer = await this.feeds.lookup(route.callsign, clock);
|
||||
// Spelled out: without strictNullChecks `ok` alone does not narrow the union.
|
||||
if (!answer.ok && (answer as Extract<FeedLookup, { ok: false }>).reason === 'budget') return;
|
||||
result.asked++;
|
||||
const at = clock();
|
||||
let next = answer.ok ? advance(prev, pickAircraft(answer.aircraft, route), route, at, answer.source) : failed(prev);
|
||||
next = closeIfOver({ ...next, next_poll_at: nextPollAt(next, route, at) }, route, at);
|
||||
const notices = this.dueNotices(prev, next, head.legs, at);
|
||||
next = { ...next, ...notices.flags };
|
||||
await this.states.saveState(toWrite(next));
|
||||
if (visible(prev) !== visible(next)) {
|
||||
result.changed++;
|
||||
this.broadcast(head.legs, next, at);
|
||||
}
|
||||
await this.announce(notices.events, head.legs, next, at);
|
||||
await this.pollEach(rest, clock, result);
|
||||
}
|
||||
|
||||
/** The notices this poll owes the travellers, each at most once per flight, and the flags that record them. */
|
||||
private dueNotices(
|
||||
prev: LiveState,
|
||||
next: LiveState,
|
||||
legs: readonly TripLeg[],
|
||||
now: number,
|
||||
): { events: NotifEventType[]; flags: Pick<LiveState, 'departed_notified' | 'landed_notified' | 'delay_notified'> } {
|
||||
const events: NotifEventType[] = [];
|
||||
const flags = {
|
||||
departed_notified: prev.departed_notified,
|
||||
landed_notified: prev.landed_notified,
|
||||
delay_notified: prev.delay_notified,
|
||||
};
|
||||
const delays = legs.map((leg) => departureDelay(leg, next, now)).filter((d): d is number => d !== null);
|
||||
if (!flags.delay_notified && delays.some((d) => d >= DELAY_NOTICE_MIN)) {
|
||||
events.push('flight_delayed');
|
||||
flags.delay_notified = true;
|
||||
}
|
||||
if (!flags.departed_notified && next.phase === 'airborne') {
|
||||
events.push('flight_departed');
|
||||
flags.departed_notified = true;
|
||||
}
|
||||
if (!flags.landed_notified && next.phase === 'landed') {
|
||||
events.push('flight_landed');
|
||||
flags.landed_notified = true;
|
||||
// Seen only once it was down: departing now would be news from the past.
|
||||
flags.departed_notified = true;
|
||||
}
|
||||
return { events, flags };
|
||||
}
|
||||
|
||||
/** The changed flight to every trip holding one of its legs, as the client reads it. */
|
||||
private broadcast(legs: readonly TripLeg[], state: LiveState, now: number): void {
|
||||
const byTrip = new Map<number, TripLeg[]>();
|
||||
for (const leg of legs) byTrip.set(leg.trip_id, [...(byTrip.get(leg.trip_id) ?? []), leg]);
|
||||
for (const [tripId, tripLegs] of byTrip) {
|
||||
this.realtime.broadcast(tripId, 'flight:live', { flights: tripLegs.map((leg) => toLiveLeg(leg, state, now)) });
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Each notice to the travellers of each booking holding the flight, or to
|
||||
* the whole trip when nobody is put on the booking.
|
||||
*
|
||||
* @txStandalone a notice stands on its own; the state that records it is already stored.
|
||||
*/
|
||||
private async announce(
|
||||
events: readonly NotifEventType[],
|
||||
legs: readonly TripLeg[],
|
||||
state: LiveState,
|
||||
now: number,
|
||||
): Promise<void> {
|
||||
if (events.length === 0) return;
|
||||
// One leg after the other, as every other sender in the codebase does: a notice writes its rows.
|
||||
await legs.reduce(async (previous, leg) => {
|
||||
await previous;
|
||||
const params: Record<string, string> = {
|
||||
flight: leg.flight_number,
|
||||
from: leg.origin.code,
|
||||
to: leg.destination.code,
|
||||
trip: leg.trip_title,
|
||||
tripId: String(leg.trip_id),
|
||||
delay: String(Math.max(0, departureDelay(leg, state, now) ?? 0)),
|
||||
};
|
||||
try {
|
||||
const travelers = await this.states.listTravelerIds(leg.reservation_id);
|
||||
const targets: Array<{ scope: 'trip' | 'user'; targetId: number }> =
|
||||
travelers.length === 0
|
||||
? [{ scope: 'trip', targetId: leg.trip_id }]
|
||||
: travelers.map((userId) => ({ scope: 'user', targetId: userId }));
|
||||
const sends = events.flatMap((event) => targets.map((target) => ({ event, ...target })));
|
||||
await sends.reduce(async (sent, payload) => {
|
||||
await sent;
|
||||
await this.notifications.send({ ...payload, actorId: null, params });
|
||||
}, Promise.resolve());
|
||||
} catch (err) {
|
||||
const reason = err instanceof Error ? err.message : String(err);
|
||||
logError(`[flight-live] notice for ${leg.callsign}: ${reason}`);
|
||||
}
|
||||
}, Promise.resolve());
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,50 @@
|
||||
/**
|
||||
* How often this instance may ask the open ADS-B feeds: at most one request a
|
||||
* second and 200 an hour across every flight, whichever trip asked. The feeds
|
||||
* are run by volunteers on donated capacity; a planner instance has no reason
|
||||
* to come near what they allow. A 429 or a run of failures pauses a source for
|
||||
* a quarter of an hour.
|
||||
*
|
||||
* Process state on purpose: TREK runs as one process, and the job that spends
|
||||
* the budget holds a scheduler lease, so a second process does not tick at the
|
||||
* same time.
|
||||
*/
|
||||
export const BUDGET_PER_HOUR = 200;
|
||||
const MIN_SPACING_MS = 1000;
|
||||
const BACKOFF_MS = 15 * 60 * 1000;
|
||||
const HOUR_MS = 60 * 60 * 1000;
|
||||
|
||||
export class FeedBudget {
|
||||
private readonly sent: number[] = [];
|
||||
private readonly pausedUntil = new Map<string, number>();
|
||||
|
||||
/** Takes one request from the budget when there is one left now. */
|
||||
tryTake(now: number): boolean {
|
||||
while (this.sent.length > 0 && now - this.sent[0] >= HOUR_MS) this.sent.shift();
|
||||
const last = this.sent[this.sent.length - 1];
|
||||
if (last !== undefined && now - last < MIN_SPACING_MS) return false;
|
||||
if (this.sent.length >= BUDGET_PER_HOUR) return false;
|
||||
this.sent.push(now);
|
||||
return true;
|
||||
}
|
||||
|
||||
/** How long until the spacing lets the next request go, in ms; 0 when it may go now. */
|
||||
waitMs(now: number): number {
|
||||
const last = this.sent[this.sent.length - 1];
|
||||
return last === undefined ? 0 : Math.max(0, MIN_SPACING_MS - (now - last));
|
||||
}
|
||||
|
||||
/** Whether the hourly budget is used up. */
|
||||
exhausted(now: number): boolean {
|
||||
return this.sent.filter((at) => now - at < HOUR_MS).length >= BUDGET_PER_HOUR;
|
||||
}
|
||||
|
||||
pause(source: string, now: number): void {
|
||||
this.pausedUntil.set(source, now + BACKOFF_MS);
|
||||
}
|
||||
|
||||
isPaused(source: string, now: number): boolean {
|
||||
const until = this.pausedUntil.get(source);
|
||||
return until !== undefined && now < until;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,79 @@
|
||||
import { logWarn } from '../audit/audit-log.logger';
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
/**
|
||||
* From the flight number a traveller booked to the callsign the aircraft
|
||||
* transmits: "LH 716", "LH0716" and "lh716" all fly as DLH716.
|
||||
*
|
||||
* The IATA to ICAO table is server/assets/airlines-icao.json, built by
|
||||
* scripts/build-airlines.mjs from the VRS standing data (CC0); where IATA hands
|
||||
* one code to several airlines the one with the most recorded routes wins (the
|
||||
* script says why). Read once and kept, like the airports.
|
||||
*/
|
||||
|
||||
let table: ReadonlyMap<string, string> | null = null;
|
||||
|
||||
/** The IATA airline code to ICAO callsign prefix table, empty when the asset is missing. */
|
||||
export function airlineTable(): ReadonlyMap<string, string> {
|
||||
if (table) return table;
|
||||
const file = path.join(__dirname, '..', '..', '..', 'assets', 'airlines-icao.json');
|
||||
if (!fs.existsSync(file)) {
|
||||
logWarn('[flight-live] airlines-icao.json missing: run `node scripts/build-airlines.mjs`');
|
||||
table = new Map();
|
||||
return table;
|
||||
}
|
||||
const raw = JSON.parse(fs.readFileSync(file, 'utf8')) as Record<string, unknown>;
|
||||
table = new Map(Object.entries(raw).filter((entry): entry is [string, string] => typeof entry[1] === 'string'));
|
||||
return table;
|
||||
}
|
||||
|
||||
const ICAO_FORM = /^([A-Z]{3})(\d{1,4}[A-Z]?)$/;
|
||||
/** Two characters with at least one letter, then the number: LH716, U21234, 4U9520. */
|
||||
const IATA_FORM = /^([A-Z][A-Z0-9]|[0-9][A-Z])(\d{1,4}[A-Z]?)$/;
|
||||
const NUMBER_ONLY = /^(\d{1,4}[A-Z]?)$/;
|
||||
|
||||
/** "0716" -> "716", "0007A" -> "7A", "0" stays "0". */
|
||||
function trimNumber(number: string): string {
|
||||
return number.replace(/^0+(?=\d)/, '');
|
||||
}
|
||||
|
||||
/** The ICAO prefix an airline field names, when it is a code at all ("LH", "DLH"); a name is not looked up. */
|
||||
function prefixOfAirline(airline: string, airlines: ReadonlyMap<string, string>): string | null {
|
||||
const code = airline.trim().toUpperCase();
|
||||
if (/^[A-Z]{3}$/.test(code)) return code;
|
||||
if (/^(?:[A-Z][A-Z0-9]|[0-9][A-Z])$/.test(code)) return airlines.get(code) ?? null;
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* The ICAO callsign of a booked flight, or null when it cannot be told.
|
||||
*
|
||||
* A number already in ICAO form (three letters and digits) is taken as it is.
|
||||
* A number without an airline code borrows one from `airline` when that holds
|
||||
* a code. Spaces and dashes are dropped and leading zeros of the number go,
|
||||
* as the transponder sends them.
|
||||
*/
|
||||
export function toCallsign(
|
||||
flightNumber: string | null | undefined,
|
||||
airline?: string | null,
|
||||
airlines: ReadonlyMap<string, string> = airlineTable(),
|
||||
): string | null {
|
||||
if (typeof flightNumber !== 'string') return null;
|
||||
const compact = flightNumber.toUpperCase().replace(/[\s-]/g, '');
|
||||
if (!compact) return null;
|
||||
const icao = ICAO_FORM.exec(compact);
|
||||
if (icao) return icao[1] + trimNumber(icao[2]);
|
||||
const iata = IATA_FORM.exec(compact);
|
||||
if (iata) {
|
||||
const prefix = airlines.get(iata[1]);
|
||||
return prefix ? prefix + trimNumber(iata[2]) : null;
|
||||
}
|
||||
const bare = NUMBER_ONLY.exec(compact);
|
||||
if (bare && typeof airline === 'string') {
|
||||
const prefix = prefixOfAirline(airline, airlines);
|
||||
return prefix ? prefix + trimNumber(bare[1]) : null;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
@@ -0,0 +1,30 @@
|
||||
import type { TripAccess } from '../../db/repositories/Trips.repository';
|
||||
import { JwtAuthGuard } from '../auth-core/jwt-auth.guard';
|
||||
import { ResponseContract } from '../common/response-contract';
|
||||
import { TripAccessGuard } from '../permissions/trip-access.guard';
|
||||
import { Trip } from '../permissions/trip.decorator';
|
||||
import { FlightLiveService } from './flight-live.service';
|
||||
import { Controller, Get, UseGuards } from '@nestjs/common';
|
||||
import { tripFlightLiveResponseSchema, type TripFlightLiveResponse } from '@trek/shared';
|
||||
|
||||
/**
|
||||
* GET /api/trips/:tripId/flights/live: every flight leg of the trip with its
|
||||
* schedule in UTC and what the open ADS-B feeds last said about it.
|
||||
*
|
||||
* Trip-scoped like reading the bookings: TripAccessGuard answers 404 for a trip
|
||||
* the caller cannot reach, and reading needs no permission beyond access. The
|
||||
* read never asks a feed; an in-window leg whose answer is older than two
|
||||
* minutes is put up for the poll's next tick. With the admin switch off it
|
||||
* answers `{ enabled: false, attribution: null, flights: [] }`.
|
||||
*/
|
||||
@Controller('api/trips/:tripId/flights')
|
||||
@UseGuards(JwtAuthGuard, TripAccessGuard)
|
||||
export class FlightLiveController {
|
||||
constructor(private readonly live: FlightLiveService) {}
|
||||
|
||||
@Get('live')
|
||||
@ResponseContract(tripFlightLiveResponseSchema)
|
||||
async list(@Trip() trip: TripAccess): Promise<TripFlightLiveResponse> {
|
||||
return await this.live.tripFlights(trip.id);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,389 @@
|
||||
import { haversineKm } from '../common/geo';
|
||||
import type { ScheduledLeg } from './flight-live.schedule';
|
||||
import type { FlightLiveLeg, FlightLivePhase, FlightLivePosition, FlightLiveSource } from '@trek/shared';
|
||||
|
||||
/**
|
||||
* What the positions of an aircraft say about a booked flight, worked out
|
||||
* without the airline: the phase, wheels-up and touchdown, the delays and the
|
||||
* arrival estimate, and when to ask the feed again. Pure, every clock passed
|
||||
* in as epoch milliseconds.
|
||||
*/
|
||||
|
||||
const MIN = 60 * 1000;
|
||||
const HOUR = 60 * MIN;
|
||||
const KT_TO_KMH = 1.852;
|
||||
|
||||
/** The watch window around a leg: from three hours before departure to two after arrival. */
|
||||
const WATCH_BEFORE_MS = 3 * HOUR;
|
||||
const WATCH_AFTER_MS = 2 * HOUR;
|
||||
/** Without a scheduled arrival the window closes this long after departure. */
|
||||
const ASSUMED_FLIGHT_MS = 16 * HOUR;
|
||||
/** A callsign not heard this long after the scheduled departure is reported unknown. */
|
||||
const UNKNOWN_AFTER_MS = 2 * HOUR;
|
||||
/** An airborne aircraft not heard for longer is shown as stale. */
|
||||
const STALE_AFTER_MS = 10 * MIN;
|
||||
/** Approach, landing and taxi on top of the great-circle flight time. */
|
||||
const APPROACH_BUFFER_MS = 8 * MIN;
|
||||
|
||||
/** One aircraft as the feed reported it, already validated. */
|
||||
export interface FeedAircraft {
|
||||
hex: string;
|
||||
flight: string | null;
|
||||
registration: string | null;
|
||||
type: string | null;
|
||||
/** Feet; 'ground' when the transponder says it is on the ground. */
|
||||
alt_baro: number | 'ground' | null;
|
||||
alt_geom: number | null;
|
||||
gs: number | null;
|
||||
track: number | null;
|
||||
baro_rate: number | null;
|
||||
geom_rate: number | null;
|
||||
lat: number | null;
|
||||
lon: number | null;
|
||||
/** Seconds since the feed last heard the aircraft, and since its last position. */
|
||||
seen: number | null;
|
||||
seen_pos: number | null;
|
||||
}
|
||||
|
||||
/** The state of one flight (callsign, service date) between polls; times are epoch ms. */
|
||||
export interface LiveState {
|
||||
callsign: string;
|
||||
service_date: string;
|
||||
/** IATA codes of the sector: one flight number can fly two sectors on one day. */
|
||||
origin: string;
|
||||
destination: string;
|
||||
phase: FlightLivePhase;
|
||||
departed_at: number | null;
|
||||
landed_at: number | null;
|
||||
position: FlightLivePosition | null;
|
||||
registration: string | null;
|
||||
aircraft_type: string | null;
|
||||
source: FlightLiveSource | null;
|
||||
first_seen_at: number | null;
|
||||
last_seen_at: number | null;
|
||||
fetched_at: number | null;
|
||||
next_poll_at: number | null;
|
||||
fail_count: number;
|
||||
departed_notified: boolean;
|
||||
landed_notified: boolean;
|
||||
delay_notified: boolean;
|
||||
}
|
||||
|
||||
export function emptyState(callsign: string, service_date: string, origin: string, destination: string): LiveState {
|
||||
return {
|
||||
callsign,
|
||||
service_date,
|
||||
origin,
|
||||
destination,
|
||||
phase: 'scheduled',
|
||||
departed_at: null,
|
||||
landed_at: null,
|
||||
position: null,
|
||||
registration: null,
|
||||
aircraft_type: null,
|
||||
source: null,
|
||||
first_seen_at: null,
|
||||
last_seen_at: null,
|
||||
fetched_at: null,
|
||||
next_poll_at: null,
|
||||
fail_count: 0,
|
||||
departed_notified: false,
|
||||
landed_notified: false,
|
||||
delay_notified: false,
|
||||
};
|
||||
}
|
||||
|
||||
type Route = Pick<ScheduledLeg, 'origin' | 'destination' | 'scheduled_departure' | 'scheduled_arrival'>;
|
||||
type Schedule = Pick<Route, 'scheduled_departure' | 'scheduled_arrival'>;
|
||||
type WatchWindow = { start: number; end: number };
|
||||
|
||||
function kmTo(lat: number, lng: number, airport: { lat: number; lng: number }): number {
|
||||
return haversineKm(lat, lng, airport.lat, airport.lng);
|
||||
}
|
||||
|
||||
function finite(value: number | null | undefined): number | null {
|
||||
return typeof value === 'number' && Number.isFinite(value) ? value : null;
|
||||
}
|
||||
|
||||
/** The leg's watch window, or null without a scheduled departure. */
|
||||
export function watchWindow(leg: Schedule): WatchWindow | null {
|
||||
if (leg.scheduled_departure === null) return null;
|
||||
const arrival = leg.scheduled_arrival ?? leg.scheduled_departure + ASSUMED_FLIGHT_MS;
|
||||
return { start: leg.scheduled_departure - WATCH_BEFORE_MS, end: arrival + WATCH_AFTER_MS };
|
||||
}
|
||||
|
||||
export function inWatchWindow(leg: Schedule, now: number): boolean {
|
||||
const span = watchWindow(leg);
|
||||
return span !== null && now >= span.start && now <= span.end;
|
||||
}
|
||||
|
||||
/**
|
||||
* The aircraft that flies this leg among those the feed answered for the
|
||||
* callsign: the one with a position nearest the great circle between the two
|
||||
* airports (least detour over the direct distance). A callsign is reused by
|
||||
* the next leg of a rotation, so two can be in the air at once.
|
||||
*/
|
||||
export function pickAircraft(aircraft: readonly FeedAircraft[], route: Route): FeedAircraft | null {
|
||||
const total = kmTo(route.origin.lat, route.origin.lng, route.destination);
|
||||
let best: FeedAircraft | null = null;
|
||||
let bestScore = Number.POSITIVE_INFINITY;
|
||||
for (const ac of aircraft) {
|
||||
const lat = finite(ac.lat);
|
||||
const lng = finite(ac.lon);
|
||||
const score =
|
||||
lat === null || lng === null
|
||||
? Number.MAX_VALUE
|
||||
: kmTo(lat, lng, route.origin) + kmTo(lat, lng, route.destination) - total;
|
||||
if (best === null || score < bestScore) {
|
||||
best = ac;
|
||||
bestScore = score;
|
||||
}
|
||||
}
|
||||
return best;
|
||||
}
|
||||
|
||||
/** The aircraft's report as a position at its own time; null without coordinates. */
|
||||
export function observe(
|
||||
ac: FeedAircraft,
|
||||
now: number,
|
||||
): { position: FlightLivePosition; positionAt: number; heardAt: number } | null {
|
||||
const lat = finite(ac.lat);
|
||||
const lng = finite(ac.lon);
|
||||
if (lat === null || lng === null) return null;
|
||||
const onGround = ac.alt_baro === 'ground';
|
||||
const baro = typeof ac.alt_baro === 'number' ? finite(ac.alt_baro) : null;
|
||||
const altitude = onGround ? 0 : (baro ?? finite(ac.alt_geom));
|
||||
return {
|
||||
position: {
|
||||
lat,
|
||||
lng,
|
||||
altitude_ft: altitude,
|
||||
ground_speed_kt: finite(ac.gs),
|
||||
track_deg: finite(ac.track),
|
||||
vertical_rate_fpm: finite(ac.baro_rate) ?? finite(ac.geom_rate),
|
||||
on_ground: onGround,
|
||||
},
|
||||
positionAt: now - Math.max(0, finite(ac.seen_pos) ?? finite(ac.seen) ?? 0) * 1000,
|
||||
heardAt: now - Math.max(0, finite(ac.seen) ?? 0) * 1000,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* The next state of a flight after one answer from the feed. `aircraft` is the
|
||||
* picked one, or null when the feed knew nothing of the callsign.
|
||||
*
|
||||
* - On the ground within 30 km of the destination after having flown, or
|
||||
* after the scheduled departure: landed.
|
||||
* - On the ground at the origin: taxiing.
|
||||
* - In the air: airborne; wheels-up is the first airborne report while still
|
||||
* below 10,000 ft within 60 km of the origin, else it stays unknown.
|
||||
* - Lost below 5,000 ft within 40 km of the destination and not heard for ten
|
||||
* minutes: landed at its last report.
|
||||
* - Never heard two hours after the scheduled departure: unknown.
|
||||
*/
|
||||
export function advance(
|
||||
prev: LiveState,
|
||||
aircraft: FeedAircraft | null,
|
||||
route: Route,
|
||||
now: number,
|
||||
source: FlightLiveSource,
|
||||
): LiveState {
|
||||
const next: LiveState = { ...prev, fetched_at: now, source, fail_count: 0 };
|
||||
if (prev.phase === 'landed') return next;
|
||||
const seen = aircraft ? observe(aircraft, now) : null;
|
||||
|
||||
if (seen && aircraft) {
|
||||
const { position, positionAt, heardAt } = seen;
|
||||
const fromOrigin = kmTo(position.lat, position.lng, route.origin);
|
||||
const toDestination = kmTo(position.lat, position.lng, route.destination);
|
||||
const hasFlown = prev.phase === 'airborne' || prev.departed_at !== null;
|
||||
next.position = position;
|
||||
next.registration = aircraft.registration ?? prev.registration;
|
||||
next.aircraft_type = aircraft.type ?? prev.aircraft_type;
|
||||
next.first_seen_at = prev.first_seen_at ?? heardAt;
|
||||
next.last_seen_at = heardAt;
|
||||
if (position.on_ground) {
|
||||
// Down at the destination after the scheduled departure counts even unseen in the air (no coverage at
|
||||
// the origin); down anywhere else after flying is a diversion.
|
||||
const departureDue = route.scheduled_departure !== null && now >= route.scheduled_departure;
|
||||
const atDestination = toDestination <= 30 && (hasFlown || departureDue);
|
||||
if (atDestination || (hasFlown && fromOrigin > 30)) {
|
||||
next.phase = 'landed';
|
||||
next.landed_at = prev.landed_at ?? positionAt;
|
||||
} else {
|
||||
next.phase = 'taxiing';
|
||||
}
|
||||
} else {
|
||||
if (prev.phase !== 'airborne' && prev.departed_at === null) {
|
||||
const low = position.altitude_ft !== null && position.altitude_ft < 10000;
|
||||
next.departed_at = low && fromOrigin <= 60 ? positionAt : null;
|
||||
}
|
||||
next.phase = 'airborne';
|
||||
}
|
||||
return next;
|
||||
}
|
||||
|
||||
if (prev.phase === 'airborne' && prev.position && prev.last_seen_at !== null) {
|
||||
const { lat, lng, altitude_ft } = prev.position;
|
||||
const lostLow = altitude_ft !== null && altitude_ft < 5000 && kmTo(lat, lng, route.destination) <= 40;
|
||||
if (lostLow && now - prev.last_seen_at >= STALE_AFTER_MS) {
|
||||
next.phase = 'landed';
|
||||
next.landed_at = prev.last_seen_at;
|
||||
return next;
|
||||
}
|
||||
}
|
||||
if (
|
||||
prev.first_seen_at === null &&
|
||||
route.scheduled_departure !== null &&
|
||||
now >= route.scheduled_departure + UNKNOWN_AFTER_MS
|
||||
) {
|
||||
next.phase = 'unknown';
|
||||
}
|
||||
return next;
|
||||
}
|
||||
|
||||
/** Whether the leg's watch window is over. */
|
||||
function windowOver(leg: Schedule, now: number): boolean {
|
||||
const span = watchWindow(leg);
|
||||
return span !== null && now > span.end;
|
||||
}
|
||||
|
||||
/**
|
||||
* A flight still taxiing or in the air when its window closes went quiet
|
||||
* without a landing anyone saw (out of coverage, switched off): it is closed
|
||||
* as unknown, never left in the air, and asked about no more.
|
||||
*/
|
||||
export function closeIfOver(state: LiveState, route: Schedule, now: number): LiveState {
|
||||
if (!windowOver(route, now) || (state.phase !== 'airborne' && state.phase !== 'taxiing')) return state;
|
||||
return { ...state, phase: 'unknown', next_poll_at: null };
|
||||
}
|
||||
|
||||
/** A failed ask: the state stays, the failure is counted. */
|
||||
export function failed(prev: LiveState): LiveState {
|
||||
return { ...prev, fail_count: prev.fail_count + 1 };
|
||||
}
|
||||
|
||||
/**
|
||||
* When to ask the feed next about this flight, or null to stop: landed, or
|
||||
* past its window.
|
||||
*
|
||||
* - unknown: every 15 minutes until the window closes;
|
||||
* - airborne: every 3 minutes, every 6 when more than two hours of flying
|
||||
* from both airports at its ground speed;
|
||||
* - more than 40 minutes before departure: every 10 minutes;
|
||||
* - around departure until airborne: every 2 minutes;
|
||||
* - three failures in a row: 15 minutes.
|
||||
*/
|
||||
export function nextPollAt(state: LiveState, route: Route, now: number): number | null {
|
||||
if (state.phase === 'landed') return null;
|
||||
const span = watchWindow(route);
|
||||
if (!span || now > span.end) return null;
|
||||
if (state.fail_count >= 3 || state.phase === 'unknown') return now + 15 * MIN;
|
||||
if (state.phase === 'airborne') {
|
||||
const at = state.position;
|
||||
const gs = at?.ground_speed_kt ?? null;
|
||||
if (at && gs !== null && gs > 0) {
|
||||
const kmh = gs * KT_TO_KMH;
|
||||
const hoursFrom = (airport: { lat: number; lng: number }) => kmTo(at.lat, at.lng, airport) / kmh;
|
||||
if (hoursFrom(route.origin) > 2 && hoursFrom(route.destination) > 2) return now + 6 * MIN;
|
||||
}
|
||||
return now + 3 * MIN;
|
||||
}
|
||||
if (route.scheduled_departure !== null && now < route.scheduled_departure - 40 * MIN) {
|
||||
return Math.min(now + 10 * MIN, Math.max(now + 2 * MIN, route.scheduled_departure - 40 * MIN));
|
||||
}
|
||||
return now + 2 * MIN;
|
||||
}
|
||||
|
||||
function iso(ms: number | null): string | null {
|
||||
return ms === null ? null : new Date(ms).toISOString();
|
||||
}
|
||||
|
||||
function minutes(ms: number): number {
|
||||
return Math.round(ms / MIN);
|
||||
}
|
||||
|
||||
/**
|
||||
* The leg as the client reads it: the schedule, and what the stored state
|
||||
* says on top of it. Without a state the schedule alone answers: scheduled
|
||||
* (the client tells a past one from its times), unknown late in the window.
|
||||
* After the window nothing is in the air or taxiing any more: such a state
|
||||
* reads as unknown.
|
||||
*/
|
||||
export function toLiveLeg(leg: ScheduledLeg, state: LiveState | null, now: number): FlightLiveLeg {
|
||||
const total = kmTo(leg.origin.lat, leg.origin.lng, leg.destination);
|
||||
const span = watchWindow(leg);
|
||||
let phase: FlightLivePhase = state?.phase ?? 'scheduled';
|
||||
if (!state && leg.scheduled_departure !== null && span && now <= span.end) {
|
||||
if (now >= leg.scheduled_departure + UNKNOWN_AFTER_MS) phase = 'unknown';
|
||||
}
|
||||
if ((phase === 'airborne' || phase === 'taxiing') && windowOver(leg, now)) phase = 'unknown';
|
||||
|
||||
const position = state?.position ?? null;
|
||||
const remaining = position
|
||||
? kmTo(position.lat, position.lng, leg.destination)
|
||||
: phase === 'landed'
|
||||
? 0
|
||||
: phase === 'scheduled' || phase === 'taxiing'
|
||||
? total
|
||||
: null;
|
||||
const progress = remaining === null || total <= 0 ? null : Math.min(1, Math.max(0, 1 - remaining / total));
|
||||
|
||||
const gs = position?.ground_speed_kt ?? null;
|
||||
const estimate =
|
||||
phase === 'airborne' && position && remaining !== null && gs !== null && gs > 150
|
||||
? (state?.last_seen_at ?? now) + (remaining / (gs * KT_TO_KMH)) * HOUR + APPROACH_BUFFER_MS
|
||||
: null;
|
||||
const departedAt = state?.departed_at ?? null;
|
||||
const landedAt = state?.landed_at ?? null;
|
||||
const arrivalBasis = landedAt ?? estimate;
|
||||
const lastSeen = state?.last_seen_at ?? null;
|
||||
|
||||
return {
|
||||
reservation_id: leg.reservation_id,
|
||||
leg_index: leg.leg_index,
|
||||
callsign: leg.callsign,
|
||||
flight_number: leg.flight_number,
|
||||
service_date: leg.service_date,
|
||||
origin: leg.origin,
|
||||
destination: leg.destination,
|
||||
phase,
|
||||
scheduled_departure: iso(leg.scheduled_departure),
|
||||
scheduled_arrival: iso(leg.scheduled_arrival),
|
||||
departed_at: iso(departedAt),
|
||||
landed_at: iso(landedAt),
|
||||
estimated_arrival: iso(estimate === null ? null : Math.round(estimate)),
|
||||
departure_delay_min:
|
||||
departedAt !== null && leg.scheduled_departure !== null ? minutes(departedAt - leg.scheduled_departure) : null,
|
||||
arrival_delay_min:
|
||||
arrivalBasis !== null && leg.scheduled_arrival !== null ? minutes(arrivalBasis - leg.scheduled_arrival) : null,
|
||||
progress,
|
||||
distance_total_km: Math.round(total),
|
||||
distance_remaining_km: remaining === null ? null : Math.round(remaining),
|
||||
position,
|
||||
aircraft:
|
||||
state && (state.registration || state.aircraft_type)
|
||||
? { registration: state.registration, type: state.aircraft_type }
|
||||
: null,
|
||||
last_seen_at: iso(lastSeen),
|
||||
fetched_at: iso(state?.fetched_at ?? null),
|
||||
stale: phase === 'airborne' && lastSeen !== null && now - lastSeen > STALE_AFTER_MS,
|
||||
source: state?.source ?? null,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* How late the leg is running at departure, in minutes, when there is
|
||||
* evidence of it; else null. Wheels-up says it outright. An aircraft still
|
||||
* heard on the ground after the scheduled time is late by at least the time it
|
||||
* was last heard, but only while that report is recent: one gone quiet at the
|
||||
* gate says nothing about now.
|
||||
*/
|
||||
export function departureDelay(leg: ScheduledLeg, state: LiveState, now: number): number | null {
|
||||
const scheduled = leg.scheduled_departure;
|
||||
if (scheduled === null) return null;
|
||||
if (state.departed_at !== null) return minutes(state.departed_at - scheduled);
|
||||
const heard = state.last_seen_at;
|
||||
if (state.phase !== 'taxiing' || heard === null || heard <= scheduled) return null;
|
||||
return now - heard < STALE_AFTER_MS ? minutes(heard - scheduled) : null;
|
||||
}
|
||||
@@ -0,0 +1,186 @@
|
||||
import { readCappedJson } from '../../utils/cappedFetch';
|
||||
import { RuntimeEnvService } from '../app-config/runtime-env.service';
|
||||
import { logWarn } from '../audit/audit-log.logger';
|
||||
import { FeedBudget } from './flight-live.budget';
|
||||
import type { FeedAircraft } from './flight-live.derive';
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import type { FlightLiveSource } from '@trek/shared';
|
||||
|
||||
import { z } from 'zod';
|
||||
|
||||
/**
|
||||
* The two keyless ADS-B feeds TREK reads live flights from. adsb.lol first;
|
||||
* adsb.fi only when this is not a managed install, because adsb.fi's terms
|
||||
* rule out commercial use. Only the callsign goes out, never a user, a trip
|
||||
* or a route. Both answer the readsb "v2" shape.
|
||||
*/
|
||||
|
||||
const FEED_TIMEOUT_MS = 8000;
|
||||
/** A callsign's answer is one or two aircraft, a few hundred bytes each. */
|
||||
const MAX_FEED_BYTES = 256 * 1024;
|
||||
/** Failures in a row before a source is paused like a 429. */
|
||||
const FAILURES_BEFORE_PAUSE = 3;
|
||||
|
||||
export const FEED_ATTRIBUTION: Record<FlightLiveSource, string> = {
|
||||
'adsb.lol': 'Live positions: adsb.lol (ODbL)',
|
||||
'adsb.fi': 'Live positions: adsb.fi',
|
||||
};
|
||||
|
||||
const FEED_URL: Record<FlightLiveSource, (callsign: string) => string> = {
|
||||
'adsb.lol': (callsign) => `https://api.adsb.lol/v2/callsign/${callsign}`,
|
||||
'adsb.fi': (callsign) => `https://opendata.adsb.fi/api/v2/callsign/${callsign}`,
|
||||
};
|
||||
|
||||
const num = z.number().nullish();
|
||||
const str = z.string().nullish();
|
||||
|
||||
/** The fields of one aircraft TREK reads; everything else in the answer is dropped. */
|
||||
const aircraftSchema = z.object({
|
||||
hex: z.string(),
|
||||
flight: str,
|
||||
r: str,
|
||||
t: str,
|
||||
alt_baro: z.union([z.number(), z.literal('ground')]).nullish(),
|
||||
alt_geom: num,
|
||||
gs: num,
|
||||
track: num,
|
||||
baro_rate: num,
|
||||
geom_rate: num,
|
||||
lat: num,
|
||||
lon: num,
|
||||
seen: num,
|
||||
seen_pos: num,
|
||||
});
|
||||
|
||||
const feedAnswerSchema = z.object({
|
||||
ac: z.array(aircraftSchema).max(50).nullish(),
|
||||
now: z.number(),
|
||||
});
|
||||
|
||||
const CALLSIGN_RE = /^[A-Z0-9]{3,8}$/;
|
||||
|
||||
export type FeedLookup =
|
||||
| { ok: true; source: FlightLiveSource; now: number; aircraft: FeedAircraft[] }
|
||||
| { ok: false; reason: 'budget' | 'unavailable' };
|
||||
|
||||
type SourceAnswer =
|
||||
{ ok: true; now: number; aircraft: FeedAircraft[] } | { ok: false; status: number | null; reason: string };
|
||||
|
||||
function toAircraft(ac: z.infer<typeof aircraftSchema>): FeedAircraft {
|
||||
return {
|
||||
hex: ac.hex,
|
||||
flight: ac.flight?.trim() || null,
|
||||
registration: ac.r?.trim() || null,
|
||||
type: ac.t?.trim() || null,
|
||||
alt_baro: ac.alt_baro ?? null,
|
||||
alt_geom: ac.alt_geom ?? null,
|
||||
gs: ac.gs ?? null,
|
||||
track: ac.track ?? null,
|
||||
baro_rate: ac.baro_rate ?? null,
|
||||
geom_rate: ac.geom_rate ?? null,
|
||||
lat: ac.lat ?? null,
|
||||
lon: ac.lon ?? null,
|
||||
seen: ac.seen ?? null,
|
||||
seen_pos: ac.seen_pos ?? null,
|
||||
};
|
||||
}
|
||||
|
||||
@Injectable()
|
||||
export class FlightLiveFeedService {
|
||||
private readonly budget = new FeedBudget();
|
||||
private readonly failures = new Map<FlightLiveSource, number>();
|
||||
/** Waits out the spacing before a fallback request; a test hands in one that does not. */
|
||||
sleep: (ms: number) => Promise<void> = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
||||
|
||||
constructor(private readonly env: RuntimeEnvService) {}
|
||||
|
||||
/** The sources this install may ask, in order. */
|
||||
sources(): FlightLiveSource[] {
|
||||
return this.env.isManaged() ? ['adsb.lol'] : ['adsb.lol', 'adsb.fi'];
|
||||
}
|
||||
|
||||
/** The credit line of the first source this install asks. */
|
||||
attribution(): string {
|
||||
return FEED_ATTRIBUTION[this.sources()[0]];
|
||||
}
|
||||
|
||||
/** Whether one more request fits in the budget right now. */
|
||||
canAsk(now: number = Date.now()): boolean {
|
||||
return this.budget.waitMs(now) === 0 && !this.budget.exhausted(now);
|
||||
}
|
||||
|
||||
/** How long until the spacing lets the next request go. */
|
||||
waitMs(now: number = Date.now()): number {
|
||||
return this.budget.waitMs(now);
|
||||
}
|
||||
|
||||
/**
|
||||
* The aircraft flying under a callsign, from the first source that answers.
|
||||
* Each request spends the budget; a source that answered 429, or failed
|
||||
* three times in a row, is paused for a quarter of an hour.
|
||||
*/
|
||||
async lookup(callsign: string, now: () => number = Date.now): Promise<FeedLookup> {
|
||||
if (!CALLSIGN_RE.test(callsign)) return { ok: false, reason: 'unavailable' };
|
||||
return await this.lookupFrom(this.sources(), callsign, now, false);
|
||||
}
|
||||
|
||||
/** The first of the sources that answers, one after the other; `asked` says whether one was asked already. */
|
||||
private async lookupFrom(
|
||||
sources: readonly FlightLiveSource[],
|
||||
callsign: string,
|
||||
now: () => number,
|
||||
asked: boolean,
|
||||
): Promise<FeedLookup> {
|
||||
const [source, ...rest] = sources;
|
||||
if (source === undefined) return { ok: false, reason: asked ? 'unavailable' : 'budget' };
|
||||
if (this.budget.isPaused(source, now())) return await this.lookupFrom(rest, callsign, now, asked);
|
||||
const wait = this.budget.waitMs(now());
|
||||
if (wait > 0) await this.sleep(wait);
|
||||
if (!this.budget.tryTake(now())) return { ok: false, reason: asked ? 'unavailable' : 'budget' };
|
||||
const answer = await this.ask(source, callsign);
|
||||
if (answer.ok) {
|
||||
this.failures.set(source, 0);
|
||||
return { ok: true, source, now: answer.now, aircraft: answer.aircraft };
|
||||
}
|
||||
// Spelled out: the server builds without strictNullChecks, where `ok` alone does not narrow the union.
|
||||
const failure = answer as Extract<SourceAnswer, { ok: false }>;
|
||||
const count = (this.failures.get(source) ?? 0) + 1;
|
||||
this.failures.set(source, count);
|
||||
if (failure.status === 429 || count >= FAILURES_BEFORE_PAUSE) {
|
||||
this.budget.pause(source, now());
|
||||
this.failures.set(source, 0);
|
||||
}
|
||||
logWarn(`[flight-live] ${source} for ${callsign}: ${failure.reason}`);
|
||||
return await this.lookupFrom(rest, callsign, now, true);
|
||||
}
|
||||
|
||||
private async ask(source: FlightLiveSource, callsign: string): Promise<SourceAnswer> {
|
||||
let response: Response;
|
||||
try {
|
||||
response = await fetch(FEED_URL[source](encodeURIComponent(callsign)), {
|
||||
headers: { Accept: 'application/json' },
|
||||
signal: AbortSignal.timeout(FEED_TIMEOUT_MS),
|
||||
});
|
||||
} catch (err) {
|
||||
return { ok: false, status: null, reason: err instanceof Error ? err.message : String(err) };
|
||||
}
|
||||
if (!response.ok) {
|
||||
await response.body?.cancel().catch(() => undefined);
|
||||
return { ok: false, status: response.status, reason: `HTTP ${response.status}` };
|
||||
}
|
||||
let body: unknown;
|
||||
try {
|
||||
body = await readCappedJson<unknown>(response, MAX_FEED_BYTES);
|
||||
} catch (err) {
|
||||
return { ok: false, status: null, reason: err instanceof Error ? err.message : String(err) };
|
||||
}
|
||||
if (body === undefined) return { ok: false, status: null, reason: 'unreadable or oversized answer' };
|
||||
const parsed = feedAnswerSchema.safeParse(body);
|
||||
if (!parsed.success) return { ok: false, status: null, reason: 'unexpected answer shape' };
|
||||
const wanted = callsign.toUpperCase();
|
||||
const aircraft = (parsed.data.ac ?? [])
|
||||
.map(toAircraft)
|
||||
.filter((ac) => ac.flight === null || ac.flight.toUpperCase() === wanted);
|
||||
return { ok: true, now: parsed.data.now, aircraft };
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
import { logDebug, logError } from '../audit/audit-log.logger';
|
||||
import { CronRegistrarService } from '../scheduling/cron-registrar.service';
|
||||
import { FlightLivePollService } from './flight-live-poll.service';
|
||||
import { Injectable, type OnApplicationBootstrap } from '@nestjs/common';
|
||||
|
||||
/**
|
||||
* Every minute, the flights in their watch window asked of the ADS-B feeds
|
||||
* by their cadence (FlightLivePollService). The registrar runs the tick in a
|
||||
* request context under the job's lease and never starts it twice; the poll
|
||||
* keeps a guard of its own for a tick that outlasts its minute.
|
||||
*/
|
||||
@Injectable()
|
||||
export class FlightLiveJob implements OnApplicationBootstrap {
|
||||
constructor(
|
||||
private readonly registrar: CronRegistrarService,
|
||||
private readonly poll: FlightLivePollService,
|
||||
) {}
|
||||
|
||||
onApplicationBootstrap(): void {
|
||||
if (!this.registrar.isEnabled()) return;
|
||||
this.registrar.register('flight-live', '* * * * *', () => this.tick());
|
||||
}
|
||||
|
||||
/** @txIndependent each flight's state is a write of its own (FlightLivePollService.poll). */
|
||||
async tick(): Promise<void> {
|
||||
try {
|
||||
const result = await this.poll.poll();
|
||||
if (result.asked > 0) logDebug(`[flight-live] asked ${result.asked}, ${result.changed} changed`);
|
||||
} catch (err: unknown) {
|
||||
logError(`[flight-live] poll failed: ${err instanceof Error ? err.message : String(err)}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
import { noAccess } from '../../mcp/tools/_shared';
|
||||
import { McpController, ok, Tool, TOOL_ANNOTATIONS_READONLY, type McpContext } from '../../nest-mcp';
|
||||
import { TripAccessService } from '../trip-membership/trip-access.service';
|
||||
import { FlightLiveService } from './flight-live.service';
|
||||
import { idSchema, tripFlightLiveResponseSchema } from '@trek/shared';
|
||||
|
||||
/**
|
||||
* get_trip_flight_status, the twin of GET /api/trips/:tripId/flights/live:
|
||||
* the same service method behind the same check (the caller must see the
|
||||
* trip; reading the bookings needs nothing more). The answer is parsed
|
||||
* against the REST route's response contract, so both surfaces say the same.
|
||||
*/
|
||||
@McpController()
|
||||
export class FlightLiveMcp {
|
||||
constructor(
|
||||
private readonly live: FlightLiveService,
|
||||
private readonly access: TripAccessService,
|
||||
) {}
|
||||
|
||||
@Tool({
|
||||
name: 'get_trip_flight_status',
|
||||
description:
|
||||
"Get the live status of a trip's booked flights, one entry per flight leg with a known flight number and both airports: the schedule in UTC with each airport's time zone, the phase (scheduled, taxiing, airborne, landed, unknown), observed wheels-up and touchdown, an estimated arrival with the delays worked out from it, progress and distances along the great circle, the last position with altitude and speed, and the aircraft's registration and type. Positions come from free open ADS-B feeds, so gates, terminals and cancellations are not known, and every delay and arrival time is an estimate. `enabled` is false when the admin switched live flight status off; `attribution` is the credit line to show with the data.",
|
||||
inputSchema: { tripId: idSchema },
|
||||
annotations: TOOL_ANNOTATIONS_READONLY,
|
||||
access: { group: 'reservations', mode: 'read' },
|
||||
})
|
||||
async getTripFlightStatus({ tripId }: { tripId: number }, ctx: McpContext) {
|
||||
if (!(await this.access.findAccessible(tripId, ctx.userId))) return noAccess();
|
||||
return ok(tripFlightLiveResponseSchema.parse(await this.live.tripFlights(tripId)));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
import { FlightLiveStates } from '../../db/entities/FlightLiveStates.entity';
|
||||
import { AirportsModule } from '../airports/airports.module';
|
||||
import { AppConfigModule } from '../app-config/app-config.module';
|
||||
import { NotificationsModule } from '../notifications/notifications.module';
|
||||
import { PermissionsModule } from '../permissions/permissions.module';
|
||||
import { SchedulingModule } from '../scheduling/scheduling.module';
|
||||
import { SettingsModule } from '../settings/settings.module';
|
||||
import { TripMembershipModule } from '../trip-membership/trip-membership.module';
|
||||
import { FlightLivePollService } from './flight-live-poll.service';
|
||||
import { FlightLiveController } from './flight-live.controller';
|
||||
import { FlightLiveFeedService } from './flight-live.feeds';
|
||||
import { FlightLiveJob } from './flight-live.job';
|
||||
import { FlightLiveMcp } from './flight-live.mcp';
|
||||
import { FlightLiveService } from './flight-live.service';
|
||||
import { MikroOrmModule } from '@mikro-orm/nestjs';
|
||||
import { Module } from '@nestjs/common';
|
||||
|
||||
/**
|
||||
* Live flight status (flight-live): where a booked flight is, from the keyless
|
||||
* ADS-B feeds. The REST read and its MCP twin, the minute poll on the
|
||||
* scheduler, and the notices when a flight departs, lands or runs late.
|
||||
* Registered in AppModule.
|
||||
*/
|
||||
@Module({
|
||||
imports: [
|
||||
MikroOrmModule.forFeature([FlightLiveStates]),
|
||||
AppConfigModule,
|
||||
AirportsModule,
|
||||
NotificationsModule,
|
||||
PermissionsModule,
|
||||
SchedulingModule,
|
||||
SettingsModule,
|
||||
TripMembershipModule,
|
||||
],
|
||||
controllers: [FlightLiveController],
|
||||
providers: [FlightLiveService, FlightLivePollService, FlightLiveFeedService, FlightLiveJob, FlightLiveMcp],
|
||||
})
|
||||
export class FlightLiveModule {}
|
||||
@@ -0,0 +1,249 @@
|
||||
import { wallClockInstant } from '../common/timezoneService';
|
||||
import { toCallsign } from './flight-live.callsign';
|
||||
import type { FlightLiveAirport } from '@trek/shared';
|
||||
|
||||
/**
|
||||
* The legs of a booked flight with their schedule in UTC, out of what the
|
||||
* planner stores: the leg chain in `metadata.legs` (client/src/utils/flightLegs.ts
|
||||
* is the model, mirrored here rule for rule), the endpoints with their local
|
||||
* date, time and zone, and the trip days a leg names. Pure: the caller reads
|
||||
* the rows and hands in the airport lookup.
|
||||
*/
|
||||
|
||||
/** A flight booking as the repository reads it. */
|
||||
export interface FlightBookingRow {
|
||||
id: number;
|
||||
trip_id: number;
|
||||
metadata: Record<string, unknown>;
|
||||
day_id: number | null;
|
||||
end_day_id: number | null;
|
||||
/** Local "YYYY-MM-DDTHH:MM" of the first departure, when the form stored one. */
|
||||
reservation_time: string | null;
|
||||
reservation_end_time: string | null;
|
||||
}
|
||||
|
||||
export interface FlightEndpointRow {
|
||||
reservation_id: number;
|
||||
role: string;
|
||||
sequence: number;
|
||||
name: string;
|
||||
code: string | null;
|
||||
lat: number;
|
||||
lng: number;
|
||||
timezone: string | null;
|
||||
local_date: string | null;
|
||||
local_time: string | null;
|
||||
}
|
||||
|
||||
/** What the bundled airport dataset knows about a code. */
|
||||
export interface AirportFacts {
|
||||
name: string;
|
||||
city: string;
|
||||
lat: number;
|
||||
lng: number;
|
||||
tz: string;
|
||||
}
|
||||
|
||||
type AirportLookup = (iata: string) => AirportFacts | null;
|
||||
|
||||
/** One leg that can be tracked: a callsign, both airports and the local day it departs. */
|
||||
export interface ScheduledLeg {
|
||||
reservation_id: number;
|
||||
trip_id: number;
|
||||
leg_index: number;
|
||||
callsign: string;
|
||||
flight_number: string;
|
||||
service_date: string;
|
||||
origin: FlightLiveAirport;
|
||||
destination: FlightLiveAirport;
|
||||
/** Epoch ms, null when the booking holds no time for that end. */
|
||||
scheduled_departure: number | null;
|
||||
scheduled_arrival: number | null;
|
||||
}
|
||||
|
||||
interface RawLeg {
|
||||
from: string | null;
|
||||
to: string | null;
|
||||
airline: string | null;
|
||||
flight_number: string | null;
|
||||
dep_day_id: number | null;
|
||||
dep_time: string | null;
|
||||
arr_day_id: number | null;
|
||||
arr_time: string | null;
|
||||
}
|
||||
|
||||
const DAY_MS = 24 * 60 * 60 * 1000;
|
||||
|
||||
function str(value: unknown): string | null {
|
||||
return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
|
||||
}
|
||||
|
||||
function int(value: unknown): number | null {
|
||||
return typeof value === 'number' && Number.isInteger(value) ? value : null;
|
||||
}
|
||||
|
||||
/** "10:30", "10:30:00" -> "10:30"; anything else is no time. */
|
||||
function hhmm(value: string | null): string | null {
|
||||
return value && /^\d{2}:\d{2}/.test(value) ? value.slice(0, 5) : null;
|
||||
}
|
||||
|
||||
/** The date and the time of a stored "YYYY-MM-DDTHH:MM". */
|
||||
function splitLocal(iso: string | null): { date: string | null; time: string | null } {
|
||||
if (!iso) return { date: null, time: null };
|
||||
const [date, time] = iso.split('T');
|
||||
return { date: /^\d{4}-\d{2}-\d{2}$/.test(date ?? '') ? date : null, time: hhmm(time ?? null) };
|
||||
}
|
||||
|
||||
/** "Paris Charles de Gaulle (CDG)" -> "Paris Charles de Gaulle", as the client strips it. */
|
||||
function stripCode(name: string): string {
|
||||
const trimmed = name.trimEnd();
|
||||
return /\([A-Z]{3}\)$/.test(trimmed) ? trimmed.slice(0, -5).trimEnd() : name;
|
||||
}
|
||||
|
||||
function ordered(endpoints: readonly FlightEndpointRow[]): FlightEndpointRow[] {
|
||||
return endpoints.slice().sort((a, b) => a.sequence - b.sequence);
|
||||
}
|
||||
|
||||
/** The legs as the client's getFlightLegs reads them: `metadata.legs`, else one leg from the endpoints. */
|
||||
function rawLegs(row: FlightBookingRow, endpoints: readonly FlightEndpointRow[]): RawLeg[] {
|
||||
const meta = row.metadata;
|
||||
if (Array.isArray(meta.legs) && meta.legs.length > 0) {
|
||||
return meta.legs.map((value): RawLeg => {
|
||||
const leg = value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
|
||||
return {
|
||||
from: str(leg.from),
|
||||
to: str(leg.to),
|
||||
airline: str(leg.airline),
|
||||
flight_number: str(leg.flight_number),
|
||||
dep_day_id: int(leg.dep_day_id),
|
||||
dep_time: hhmm(str(leg.dep_time)),
|
||||
arr_day_id: int(leg.arr_day_id),
|
||||
arr_time: hhmm(str(leg.arr_time)),
|
||||
};
|
||||
});
|
||||
}
|
||||
const first = endpoints[0];
|
||||
const last = endpoints[endpoints.length - 1];
|
||||
const from = first?.code ?? str(meta.departure_airport);
|
||||
const to = last?.code ?? str(meta.arrival_airport);
|
||||
if (!from && !to) return [];
|
||||
return [
|
||||
{
|
||||
from,
|
||||
to,
|
||||
airline: str(meta.airline),
|
||||
flight_number: str(meta.flight_number),
|
||||
dep_day_id: row.day_id,
|
||||
dep_time: hhmm(first?.local_time ?? null),
|
||||
arr_day_id: row.end_day_id ?? row.day_id,
|
||||
arr_time: hhmm(last?.local_time ?? null),
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
/** An airport of the leg from its endpoint, else from the dataset; null when its place is unknown. */
|
||||
function airportOf(
|
||||
code: string | null,
|
||||
endpoint: FlightEndpointRow | undefined,
|
||||
lookup: AirportLookup,
|
||||
): FlightLiveAirport | null {
|
||||
const iata = code ? code.slice(0, 3).toUpperCase() : null;
|
||||
if (!iata || !/^[A-Z0-9]{3}$/.test(iata)) return null;
|
||||
const known = lookup(iata);
|
||||
const usable = endpoint && Number.isFinite(endpoint.lat) && Number.isFinite(endpoint.lng) ? endpoint : undefined;
|
||||
if (!usable && !known) return null;
|
||||
return {
|
||||
code: iata,
|
||||
name: usable ? stripCode(usable.name) : (known?.name ?? null),
|
||||
lat: usable ? usable.lat : (known as AirportFacts).lat,
|
||||
lng: usable ? usable.lng : (known as AirportFacts).lng,
|
||||
timezone: usable?.timezone ?? known?.tz ?? null,
|
||||
};
|
||||
}
|
||||
|
||||
/** The endpoint at the leg's end of the chain when it names that airport, else the first one that does. */
|
||||
function endpointFor(
|
||||
endpoints: readonly FlightEndpointRow[],
|
||||
index: number,
|
||||
code: string | null,
|
||||
): FlightEndpointRow | undefined {
|
||||
if (!code) return undefined;
|
||||
const iata = code.slice(0, 3).toUpperCase();
|
||||
const atIndex = endpoints[index];
|
||||
if (atIndex && atIndex.code?.toUpperCase() === iata) return atIndex;
|
||||
return endpoints.find((e) => e.code?.toUpperCase() === iata);
|
||||
}
|
||||
|
||||
/** The instant a local date and time read in a zone; null when any of the three is missing. */
|
||||
export function localToUtc(date: string | null, time: string | null, zone: string | null): number | null {
|
||||
if (!date || !time || !zone) return null;
|
||||
return wallClockInstant(date, time, zone);
|
||||
}
|
||||
|
||||
/**
|
||||
* Every leg of one flight booking that can be tracked: it has a flight number
|
||||
* that maps to a callsign, both airports are known and its departure day is
|
||||
* known. The schedule is null where the booking holds no time; an arrival
|
||||
* without its own date falls on the departure day, or the next one when that
|
||||
* would put it before the departure.
|
||||
*/
|
||||
export function legsOfBooking(
|
||||
row: FlightBookingRow,
|
||||
endpointRows: readonly FlightEndpointRow[],
|
||||
dayDates: ReadonlyMap<number, string>,
|
||||
lookup: AirportLookup,
|
||||
airlines?: ReadonlyMap<string, string>,
|
||||
): ScheduledLeg[] {
|
||||
const endpoints = ordered(endpointRows);
|
||||
const legs = rawLegs(row, endpoints);
|
||||
const firstEnd = endpoints[0];
|
||||
const lastEnd = endpoints[endpoints.length - 1];
|
||||
const start = splitLocal(row.reservation_time);
|
||||
const end = splitLocal(row.reservation_end_time);
|
||||
const single = !(Array.isArray(row.metadata.legs) && row.metadata.legs.length > 0);
|
||||
const out: ScheduledLeg[] = [];
|
||||
|
||||
legs.forEach((leg, index) => {
|
||||
const callsign = toCallsign(leg.flight_number, leg.airline, airlines);
|
||||
if (!callsign || !leg.flight_number) return;
|
||||
const fromEnd = endpointFor(endpoints, index, leg.from);
|
||||
const toEnd = endpointFor(endpoints, index + 1, leg.to);
|
||||
const origin = airportOf(leg.from, fromEnd, lookup);
|
||||
const destination = airportOf(leg.to, toEnd, lookup);
|
||||
if (!origin || !destination) return;
|
||||
|
||||
const isFirst = index === 0;
|
||||
const isLast = index === legs.length - 1;
|
||||
const depDayDate = leg.dep_day_id !== null ? (dayDates.get(leg.dep_day_id) ?? null) : null;
|
||||
const arrDayDate = leg.arr_day_id !== null ? (dayDates.get(leg.arr_day_id) ?? null) : null;
|
||||
const firstDate = isFirst ? (firstEnd?.local_date ?? start.date) : null;
|
||||
const lastDate = isLast ? (lastEnd?.local_date ?? end.date) : null;
|
||||
// A single leg's endpoints carry its own local dates; a chain's legs name their days.
|
||||
const depDate = (single && isFirst ? firstEnd?.local_date : null) ?? depDayDate ?? firstDate;
|
||||
const depTime = leg.dep_time ?? (isFirst ? start.time : null);
|
||||
if (!depDate) return;
|
||||
const arrDateGiven = (single && isLast ? lastEnd?.local_date : null) ?? arrDayDate ?? lastDate;
|
||||
const arrTime = leg.arr_time ?? (isLast ? end.time : null);
|
||||
|
||||
const departure = localToUtc(depDate, depTime, origin.timezone);
|
||||
let arrival = localToUtc(arrDateGiven ?? depDate, arrTime, destination.timezone);
|
||||
if (arrival !== null && departure !== null && arrival <= departure) {
|
||||
arrival = arrDateGiven ? null : arrival + DAY_MS;
|
||||
if (arrival !== null && arrival <= departure) arrival = null;
|
||||
}
|
||||
|
||||
out.push({
|
||||
reservation_id: row.id,
|
||||
trip_id: row.trip_id,
|
||||
leg_index: index,
|
||||
callsign,
|
||||
flight_number: leg.flight_number,
|
||||
service_date: depDate,
|
||||
origin,
|
||||
destination,
|
||||
scheduled_departure: departure,
|
||||
scheduled_arrival: arrival,
|
||||
});
|
||||
});
|
||||
return out;
|
||||
}
|
||||
@@ -0,0 +1,206 @@
|
||||
import { FlightLiveStates } from '../../db/entities/FlightLiveStates.entity';
|
||||
import { RESERVATION_METADATA } from '../../db/json-columns';
|
||||
import type {
|
||||
FlightBookingDbRow,
|
||||
FlightLiveStateRow,
|
||||
FlightLiveStatesRepository,
|
||||
} from '../../db/repositories/FlightLiveStates.repository';
|
||||
import { parseDbTimestamp } from '../../db/types';
|
||||
import { decodeJson } from '../../utils/json-column';
|
||||
import { AirportsService } from '../airports/airports.service';
|
||||
import { SettingsService } from '../settings/settings.service';
|
||||
import { emptyState, inWatchWindow, toLiveLeg, type LiveState } from './flight-live.derive';
|
||||
import { FEED_ATTRIBUTION, FlightLiveFeedService } from './flight-live.feeds';
|
||||
import { legsOfBooking, type FlightEndpointRow, type ScheduledLeg } from './flight-live.schedule';
|
||||
import { InjectRepository } from '@mikro-orm/nestjs';
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import {
|
||||
flightLivePhaseSchema,
|
||||
flightLiveSourceSchema,
|
||||
type FlightLiveLeg,
|
||||
type FlightLivePosition,
|
||||
type TripFlightLiveResponse,
|
||||
} from '@trek/shared';
|
||||
|
||||
/** A stored answer older than this is refreshed when a client asks for an in-window leg. */
|
||||
const REFRESH_AFTER_MS = 2 * 60 * 1000;
|
||||
/** A callsign is put up for a refresh at most once a minute, however many clients ask. */
|
||||
const REFRESH_SPACING_MS = 60 * 1000;
|
||||
|
||||
/** The key a flight state is stored under: one per callsign, local departure day and sector. */
|
||||
export function stateKey(callsign: string, serviceDate: string, origin: string, destination: string): string {
|
||||
return `${callsign}|${serviceDate}|${origin}|${destination}`;
|
||||
}
|
||||
|
||||
/** The key of the flight a leg flies. */
|
||||
export function legKey(leg: Pick<ScheduledLeg, 'callsign' | 'service_date' | 'origin' | 'destination'>): string {
|
||||
return stateKey(leg.callsign, leg.service_date, leg.origin.code, leg.destination.code);
|
||||
}
|
||||
|
||||
/** States the poll will not ask about soon: a client asking again must not get around that. */
|
||||
function backingOff(state: LiveState | null): boolean {
|
||||
return state !== null && (state.phase === 'unknown' || state.fail_count >= 3);
|
||||
}
|
||||
|
||||
function ms(ts: string | null): number | null {
|
||||
return parseDbTimestamp(ts)?.getTime() ?? null;
|
||||
}
|
||||
|
||||
/** A stored row as the derivation reads it; a value the column should not hold falls back. */
|
||||
export function rowToState(row: FlightLiveStateRow): LiveState {
|
||||
const phase = flightLivePhaseSchema.safeParse(row.phase);
|
||||
const source = flightLiveSourceSchema.safeParse(row.source);
|
||||
const position: FlightLivePosition | null =
|
||||
row.lat !== null && row.lng !== null
|
||||
? {
|
||||
lat: row.lat,
|
||||
lng: row.lng,
|
||||
altitude_ft: row.altitude_ft,
|
||||
ground_speed_kt: row.ground_speed_kt,
|
||||
track_deg: row.track_deg,
|
||||
vertical_rate_fpm: row.vertical_rate_fpm,
|
||||
on_ground: row.on_ground === 1,
|
||||
}
|
||||
: null;
|
||||
return {
|
||||
...emptyState(row.callsign, row.service_date, row.origin, row.destination),
|
||||
phase: phase.success ? phase.data : 'scheduled',
|
||||
departed_at: ms(row.departed_at),
|
||||
landed_at: ms(row.landed_at),
|
||||
position,
|
||||
registration: row.registration,
|
||||
aircraft_type: row.aircraft_type,
|
||||
source: source.success ? source.data : null,
|
||||
first_seen_at: ms(row.first_seen_at),
|
||||
last_seen_at: ms(row.last_seen_at),
|
||||
fetched_at: ms(row.fetched_at),
|
||||
next_poll_at: ms(row.next_poll_at),
|
||||
fail_count: row.fail_count,
|
||||
departed_notified: row.departed_notified === 1,
|
||||
landed_notified: row.landed_notified === 1,
|
||||
delay_notified: row.delay_notified === 1,
|
||||
};
|
||||
}
|
||||
|
||||
/** A flight leg with the trip it belongs to, for the poll's notices. */
|
||||
export interface TripLeg extends ScheduledLeg {
|
||||
trip_title: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Live flight status for the trips' flight bookings: the read the planner and
|
||||
* the MCP tool share, and the leg loading the poll job builds on.
|
||||
*
|
||||
* The positions come from the open ADS-B feeds (FlightLiveFeedService), asked
|
||||
* only by the poll job (FlightLivePollService) within a leg's watch window and
|
||||
* kept in `flight_live_states`; a client read never asks a feed itself. A read
|
||||
* that finds an in-window leg's answer older than two minutes puts the
|
||||
* callsign up for the job's next tick instead.
|
||||
*/
|
||||
@Injectable()
|
||||
export class FlightLiveService {
|
||||
/** When each flight was last put up for a refresh, for the once-a-minute throttle. */
|
||||
private readonly lastRequested = new Map<string, number>();
|
||||
/** The flights waiting for the poll's next tick. */
|
||||
private readonly pending = new Set<string>();
|
||||
|
||||
constructor(
|
||||
@InjectRepository(FlightLiveStates) private readonly states: FlightLiveStatesRepository,
|
||||
private readonly airports: AirportsService,
|
||||
private readonly settings: SettingsService,
|
||||
private readonly feeds: FlightLiveFeedService,
|
||||
) {}
|
||||
|
||||
/** The admin switch, `flight_live_enabled`, with FLIGHT_LIVE_ENABLED over it; anything but 'false' is on. */
|
||||
async isEnabled(): Promise<boolean> {
|
||||
return (await this.settings.getResolvedAppSetting('flight_live_enabled')) !== 'false';
|
||||
}
|
||||
|
||||
/**
|
||||
* Every flight leg of the trip that has a callsign and two known airports,
|
||||
* at any date, with its schedule and what the feeds last said about it.
|
||||
* The caller has checked that the user may see the trip.
|
||||
*/
|
||||
async tripFlights(tripId: number, now: number = Date.now()): Promise<TripFlightLiveResponse> {
|
||||
if (!(await this.isEnabled())) return { enabled: false, attribution: null, flights: [] };
|
||||
const legs = await this.loadLegs(await this.states.listFlightBookingsForTrip(tripId));
|
||||
const states = await this.statesFor(legs);
|
||||
const flights: FlightLiveLeg[] = legs.map((leg) => {
|
||||
const state = states.get(legKey(leg)) ?? null;
|
||||
if (inWatchWindow(leg, now) && state?.phase !== 'landed' && !backingOff(state)) {
|
||||
const fetched = state?.fetched_at ?? null;
|
||||
if (fetched === null || now - fetched > REFRESH_AFTER_MS) this.requestRefresh(legKey(leg), now);
|
||||
}
|
||||
return toLiveLeg(leg, state, now);
|
||||
});
|
||||
return { enabled: true, attribution: this.attributionFor(flights), flights };
|
||||
}
|
||||
|
||||
/** The credit line for what the answer shows: the sources its legs were read from, else the first source. */
|
||||
private attributionFor(flights: readonly FlightLiveLeg[]): string {
|
||||
const sources = [...new Set(flights.flatMap((f) => (f.source ? [f.source] : [])))].sort();
|
||||
if (sources.length === 0) return this.feeds.attribution();
|
||||
return sources.map((source) => FEED_ATTRIBUTION[source]).join('; ');
|
||||
}
|
||||
|
||||
/** Puts a flight (its {@link legKey}) up for the poll's next tick, at most once a minute. */
|
||||
requestRefresh(key: string, now: number): void {
|
||||
const last = this.lastRequested.get(key);
|
||||
if (last !== undefined && now - last < REFRESH_SPACING_MS) return;
|
||||
this.lastRequested.set(key, now);
|
||||
this.pending.add(key);
|
||||
}
|
||||
|
||||
/** The flights clients asked to refresh since the last call, handed over once. */
|
||||
takeRefreshRequests(now: number): Set<string> {
|
||||
const wanted = new Set(this.pending);
|
||||
this.pending.clear();
|
||||
for (const [key, at] of this.lastRequested) {
|
||||
if (now - at >= REFRESH_SPACING_MS) this.lastRequested.delete(key);
|
||||
}
|
||||
return wanted;
|
||||
}
|
||||
|
||||
/** The stored states of the legs' flights, by {@link stateKey}. */
|
||||
async statesFor(legs: readonly ScheduledLeg[]): Promise<Map<string, LiveState>> {
|
||||
const rows = await this.states.findForCallsigns([...new Set(legs.map((leg) => leg.callsign))]);
|
||||
const key = (row: FlightLiveStateRow) => stateKey(row.callsign, row.service_date, row.origin, row.destination);
|
||||
return new Map(rows.map((row) => [key(row), rowToState(row)]));
|
||||
}
|
||||
|
||||
/** The trackable legs of the bookings, each with its trip's title. */
|
||||
async loadLegs(bookings: readonly FlightBookingDbRow[]): Promise<TripLeg[]> {
|
||||
if (bookings.length === 0) return [];
|
||||
const endpoints = await this.states.listEndpoints(bookings.map((b) => b.id));
|
||||
const byBooking = new Map<number, FlightEndpointRow[]>();
|
||||
for (const endpoint of endpoints) {
|
||||
const list = byBooking.get(endpoint.reservation_id) ?? [];
|
||||
list.push(endpoint);
|
||||
byBooking.set(endpoint.reservation_id, list);
|
||||
}
|
||||
const decoded = bookings.map((row) => ({
|
||||
row,
|
||||
metadata: decodeJson(RESERVATION_METADATA, row.metadata, `reservation ${row.id}`),
|
||||
}));
|
||||
const dayIds = new Set<number>();
|
||||
for (const { row, metadata } of decoded) {
|
||||
if (row.day_id !== null) dayIds.add(row.day_id);
|
||||
if (row.end_day_id !== null) dayIds.add(row.end_day_id);
|
||||
const legs = Array.isArray(metadata.legs) ? (metadata.legs as unknown[]) : [];
|
||||
for (const leg of legs) {
|
||||
if (!leg || typeof leg !== 'object') continue;
|
||||
const { dep_day_id: dep, arr_day_id: arr } = leg as Record<string, unknown>;
|
||||
if (typeof dep === 'number') dayIds.add(dep);
|
||||
if (typeof arr === 'number') dayIds.add(arr);
|
||||
}
|
||||
}
|
||||
const dayDates = new Map((await this.states.listDayDates([...dayIds])).map((d) => [d.id, d.date]));
|
||||
const lookup = (code: string) => this.airports.findByIata(code);
|
||||
return decoded.flatMap(({ row, metadata }) =>
|
||||
legsOfBooking({ ...row, metadata }, byBooking.get(row.id) ?? [], dayDates, lookup).map((leg) => ({
|
||||
...leg,
|
||||
trip_title: row.trip_title,
|
||||
})),
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -30,6 +30,9 @@ export const INAPP_CHANNEL = 'inapp';
|
||||
export type NotifEventType =
|
||||
| 'trip_invite'
|
||||
| 'booking_change'
|
||||
| 'flight_departed'
|
||||
| 'flight_delayed'
|
||||
| 'flight_landed'
|
||||
| 'trip_reminder'
|
||||
| 'todo_due'
|
||||
| 'vacay_invite'
|
||||
@@ -49,6 +52,9 @@ export type NotifEventType =
|
||||
export const ALL_EVENT_TYPES: NotifEventType[] = [
|
||||
'trip_invite',
|
||||
'booking_change',
|
||||
'flight_departed',
|
||||
'flight_delayed',
|
||||
'flight_landed',
|
||||
'trip_reminder',
|
||||
'todo_due',
|
||||
'vacay_invite',
|
||||
|
||||
@@ -5,7 +5,7 @@ import { NotificationChannelPreferences } from '../../db/entities/NotificationCh
|
||||
import type { AppSettingsRepository } from '../../db/repositories/AppSettings.repository';
|
||||
import type { NotificationChannelPreferencesRepository } from '../../db/repositories/NotificationChannelPreferences.repository';
|
||||
import { AddonsService } from '../addons/addons.service';
|
||||
import { readAppSetting } from '../common/app-settings.registry';
|
||||
import { readAppSetting, resolveAppSetting } from '../common/app-settings.registry';
|
||||
import { UnitOfWork } from '../database/unit-of-work';
|
||||
import { listChannels } from './channel-registry';
|
||||
import { MailerService } from './mailer/mailer.service';
|
||||
@@ -131,6 +131,10 @@ export class NotificationPreferencesService {
|
||||
return photoProviders.includes('synologyphotos');
|
||||
case 'wanderer_source_hint':
|
||||
return this.addons.isWandererAvailable();
|
||||
case 'flight_departed':
|
||||
case 'flight_delayed':
|
||||
case 'flight_landed':
|
||||
return (await resolveAppSetting(this.appSettings, 'flight_live_enabled')) !== 'false';
|
||||
default:
|
||||
return true;
|
||||
}
|
||||
|
||||
@@ -173,6 +173,28 @@ const EVENT_NOTIFICATION_CONFIG: Record<string, EventNotifConfig> = {
|
||||
navigateTextKey: 'notif.action.view_trip',
|
||||
navigateTarget: (p) => (p.tripId ? `/trips/${p.tripId}` : null),
|
||||
},
|
||||
// Live flight status (flight-live): the poll saw the flight leave, land or run late.
|
||||
flight_departed: {
|
||||
inAppType: 'navigate',
|
||||
titleKey: 'notif.flight_departed.title',
|
||||
textKey: 'notif.flight_departed.text',
|
||||
navigateTextKey: 'notif.action.view_trip',
|
||||
navigateTarget: (p) => (p.tripId ? `/trips/${p.tripId}` : null),
|
||||
},
|
||||
flight_delayed: {
|
||||
inAppType: 'navigate',
|
||||
titleKey: 'notif.flight_delayed.title',
|
||||
textKey: 'notif.flight_delayed.text',
|
||||
navigateTextKey: 'notif.action.view_trip',
|
||||
navigateTarget: (p) => (p.tripId ? `/trips/${p.tripId}` : null),
|
||||
},
|
||||
flight_landed: {
|
||||
inAppType: 'navigate',
|
||||
titleKey: 'notif.flight_landed.title',
|
||||
textKey: 'notif.flight_landed.text',
|
||||
navigateTextKey: 'notif.action.view_trip',
|
||||
navigateTarget: (p) => (p.tripId ? `/trips/${p.tripId}` : null),
|
||||
},
|
||||
trip_reminder: {
|
||||
inAppType: 'navigate',
|
||||
titleKey: 'notif.trip_reminder.title',
|
||||
|
||||
@@ -23,6 +23,9 @@ export interface NtfyConfig {
|
||||
const NTFY_EVENT_META: Partial<Record<NotifEventType, { priority: 1 | 2 | 3 | 4 | 5; tags: string[] }>> = {
|
||||
trip_invite: { priority: 4, tags: ['loudspeaker'] },
|
||||
booking_change: { priority: 3, tags: ['calendar'] },
|
||||
flight_departed: { priority: 3, tags: ['airplane'] },
|
||||
flight_delayed: { priority: 4, tags: ['airplane', 'hourglass'] },
|
||||
flight_landed: { priority: 3, tags: ['airplane'] },
|
||||
trip_reminder: { priority: 4, tags: ['bell', 'alarm_clock'] },
|
||||
vacay_invite: { priority: 4, tags: ['palm_tree'] },
|
||||
todo_due: { priority: 4, tags: ['ballot_box_with_check'] },
|
||||
|
||||
@@ -3,7 +3,7 @@ import { AppSettings } from '../../db/entities/AppSettings.entity';
|
||||
import { Settings } from '../../db/entities/Settings.entity';
|
||||
import type { AppSettingsRepository } from '../../db/repositories/AppSettings.repository';
|
||||
import type { SettingsRepository } from '../../db/repositories/Settings.repository';
|
||||
import { readAppSetting, type AppSettingKey } from '../common/app-settings.registry';
|
||||
import { readAppSetting, resolveAppSetting, type AppSettingKey } from '../common/app-settings.registry';
|
||||
import { decrypt_api_key, maybe_encrypt_api_key } from '../common/crypto/apiKeyCrypto';
|
||||
import { UnitOfWork } from '../database/unit-of-work';
|
||||
import { TripMembershipService } from '../trip-membership/trip-membership.service';
|
||||
@@ -401,6 +401,11 @@ export class SettingsService {
|
||||
return await readAppSetting(this.appSettings, key);
|
||||
}
|
||||
|
||||
/** The environment value of a registered instance setting when one is set, else its stored text, else null. */
|
||||
async getResolvedAppSetting(key: AppSettingKey): Promise<string | null> {
|
||||
return await resolveAppSetting(this.appSettings, key);
|
||||
}
|
||||
|
||||
/** Writes a registered instance setting only while it has no row; the first of several processes keeps it. */
|
||||
async insertAppSettingIfAbsent(key: AppSettingKey, value: string): Promise<void> {
|
||||
await this.appSettings.insertIfAbsent(key, value);
|
||||
|
||||
Reference in New Issue
Block a user