@aeroswarm/live-server 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,178 @@
-# Temporary Holding Version
+# @aeroswarm/live-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The live-picture runtime AeroSwarm's `client-service` uses, packaged so a backend can serve the
+**same live WebSocket** (`/ws/tracks/live`) without running AeroSwarm's services. `@aeroswarm/client`
+connects to it unchanged.
+
+| Piece | What it does |
+|---|---|
+| `createTrackState` | Current tracks: `active → stale → lost → removed`, de-dupe by Mode-S address, flight-plan attachment, filtered snapshots |
+| `createFlightPlanStore` | AFTN messages folded into flight plans; correlation to live tracks (Mode-S, then callsign; the leg in progress wins) |
+| `createMovementDetector` | Takeoff / landing detection from consecutive track samples |
+| `createLiveServer` | WebSocket handlers speaking the AeroSwarm envelope protocol |
+
+No I/O: no database, Kafka, Redis or auth. The host injects `authenticate` and persists from the
+events these classes emit. Depends only on `@aeroswarm/core` (bundled) and `zod`.
+
+## Wiring
+
+```ts
+import { createFlightPlanStore, createTrackState, createLiveServer, createMovementDetector } from "@aeroswarm/live-server";
+
+const plans = createFlightPlanStore();
+const state = createTrackState({ attachFlightPlan: plans.attach });
+plans.on("changed", (plan) => {
+  state.refreshFlightPlans((t) => plans.matches(plan, t)); // push the plan to tracks already on screen
+  persist(plan);                                           // host's job
+});
+state.startSweep();   // recomputes stale/lost every 5 s; required, or tracks never go lost
+plans.startSweep();
+
+const live = createLiveServer({
+  state,
+  authenticate: async (token) => (await verify(token)) ? { airportId: "WARR" } : null,
+});
+
+// feeds (see @aeroswarm/ingest)
+trackSource.start((ev) => { if (ev.kind === "track") state.ingest(ev.event as FusedTrackEvent); });
+aftnSource.start((ev)  => { if (ev.kind === "flightplan") plans.apply(ev.event); });
+
+// movements
+const movements = createMovementDetector();
+state.on("update", (t) => {
+  const m = movements.update({ trackId: t.trackId, icao24: t.icao24, callsign: t.callsign, airportId: t.airportId,
+    at: t.lastSeenAt, lat: t.lat!, lon: t.lon!, altitudeFt: t.altitudeFt, groundSpeedKt: t.groundSpeedKt });
+  if (m) saveMovement(m);
+});
+state.on("removed", ({ trackId }) => movements.forget(trackId));
+```
+
+### Bun
+
+```ts
+Bun.serve({
+  fetch(req, srv) {
+    const url = new URL(req.url);
+    if (url.pathname === "/ws/tracks/live")
+      return srv.upgrade(req, { data: { token: url.searchParams.get("token") } }) ? undefined : new Response("upgrade failed", { status: 400 });
+    // ...
+  },
+  websocket: {
+    open: (ws) => live.handlers.open(ws, { token: ws.data.token }),
+    message: (ws, raw) => live.handlers.message(ws, raw),
+    close: (ws) => live.handlers.close(ws),
+  },
+});
+```
+
+### `ws` library
+
+```ts
+wss.on("connection", (ws, req) => {
+  void live.handlers.open(ws, { token: new URL(req.url!, "http://x").searchParams.get("token") });
+  ws.on("message", (m) => live.handlers.message(ws, m.toString()));
+  ws.on("close", () => live.handlers.close(ws));
+});
+```
+
+## Several sensors, one aircraft (fusion)
+
+Radar, MLAT and ADS-B often see the same aircraft. Each feed makes its own
+track id, and `TrackState` replaces a track whenever another id arrives for the
+same `icao24`, so two feeds knock each other out on every update. Put the fuser
+between the feeds and `state.ingest`:
+
+```ts
+import { createTrackFuser } from "@aeroswarm/live-server";
+
+const fuser = createTrackFuser();            // or createTrackFuser({ spatial: true, ... })
+
+trackSource.start((ev) => {
+  if (ev.kind !== "track") return;
+  const fused = fuser.ingest(ev.event as FusedTrackEvent);   // null = nothing new to show
+  if (fused) { persist(fused); state.ingest(fused); }
+});
+state.on("removed", ({ trackId }) => fuser.forget(trackId));
+setInterval(() => fuser.sweep(), 30_000);    // forget sensors that went silent
+```
+
+What you get: one canonical `trackId` per aircraft, `sources` listing every
+contributing sensor (`lifecycle: "merged"`), and the position of the preferred
+sensor. A sensor that lets go of the track (`lifecycle: "dropped"`) does not
+remove the aircraft while another sensor still sees it. With one sensor the
+output is the same as without the fuser, with a stable track id.
+
+**Matching.** By Mode-S address (`icao24`). Targets without one (surface
+vehicles, SSR-only radar) get a synthetic id from sensor + track number
+(`r50-176-42`), which means nothing to another sensor; they are only joined when
+`spatial` is on, by distance and time. A candidate that is ambiguous (more than
+one), or that carries a different Mode-S address, is never merged.
+
+**Which sensor's position is shown.** The first match in the priority list for
+the current state, where "on the ground" means some fresh report says
+`onGround`. Entries are a protocol (`asterix-cat010`) or a feed's source id.
+The default prefers MLAT in both lists, then ADS-B, the system track and radar.
+A sensor silent for `maxSourceAgeMs` stops competing.
+
+| Option | Default | |
+|---|---|---|
+| `surfacePriority` | MLAT (CAT010/011/020), CAT021, CAT062, CAT048 | best first |
+| `airbornePriority` | MLAT (CAT020/010/011), CAT021, CAT062, CAT048 | best first |
+| `maxSourceAgeMs` | `5000` | silent sensor stops competing |
+| `forgetAfterMs` | `600000` | sensor forgotten after this long silent |
+| `spatial` | `false` | also match tracks that share no Mode-S address |
+| `matchRadiusM` | `150` | spatial matching: distance |
+| `matchMaxSkewMs` | `3000` | spatial matching: time difference |
+| `disagreeM` | `300` | sensors further apart are counted as disagreeing |
+| `now` | `Date.now` | clock, for tests |
+
+`fuser.stats()` returns `{ aircraft, merged, spatialMatches, ambiguous,
+disagreements }`. `confidence.sourceAgreement` on a merged track falls from 1 to
+0 as its sensors drift apart.
+
+Fusion applies to what the host feeds it: events that arrive some other way
+(HTTP, Kafka) are not fused unless the host passes them through `ingest` too.
+
+## Protocol
+
+JSON envelopes `{ type, seq, serverTime, payload }`, `seq` strictly increasing across the server.
+
+| Server sends | Payload |
+|---|---|
+| `snapshot` | `{ tracks: CurrentTrack[] }`, on `subscribe` and `update-filter` |
+| `track.updated` | `{ track }`, rate-limited per client per track (`maxUpdateHz`); status and flight-plan changes are never throttled |
+| `track.removed` | `{ trackId, reason }`, reason is `dropped`, `superseded`, `lost`, `evicted` (over `maxTracks`) or `filtered` (left the client's filter) |
+| `source.status` / `stream.degraded` | via `live.sourceStatus()` / `live.degraded()` |
+| `stream.heartbeat` | every `heartbeatMs` (default 15 s) and once on open |
+| `stream.error` | `{ code, message, recoverable: true }` for `BAD_JSON`, `BAD_SUBSCRIBE`, `BAD_FILTER` |
+
+Client sends `subscribe` (`bbox`, `airportId`, `minConfidence`, `maxTracks`, `maxUpdateHz`, …) and
+`update-filter`. Always JSON; `encoding: "msgpack"` is accepted but ignored.
+
+Close codes: `4001` no token, `4003` rejected by `authenticate`, `1001` server stopping.
+Messages that arrive before `authenticate` resolves are queued, not dropped.
+
+### Airport scoping
+
+`authenticate` returning `{ airportId }` pins the connection to that airport, whatever the client
+subscribes with (a sensor token). Return `{}` for a viewer token that may ask for any airport.
+
+## Status semantics
+
+`toCurrentTrack` computes `status` once. `TrackState.sweep()` recomputes it from `lastSeenAt` and
+emits only when it actually changes, so a quiet stretch does not spam clients. Defaults: stale after
+15 s, lost after 90 s, removed after 30 min (`staleAfterMs`, `lostAfterMs`, `removeAfterMs`).
+
+## Scaling
+
+State is in-process memory: run one instance, or put a shared fan-out in front.
+
+## Develop
+
+```
+pnpm --filter @aeroswarm/live-server test
+pnpm --filter @aeroswarm/live-server build
+```
+
+`test/client-integration.test.ts` runs the real `AeroWsClient` / `TrackCache` from
+`@aeroswarm/client` against a live server over a socket, including `reconnect()`.

package/dist/index.d.ts

@@ -0,0 +1,301 @@
+import { CurrentTrack, FusedTrackEvent, FlightPlan, FlightPlanEvent } from '@aeroswarm/core/types';
+import { FusedTrackEvent as FusedTrackEvent$1 } from '@aeroswarm/core';
+
+/** Minimal socket surface. Satisfied by Bun's `ServerWebSocket` and the `ws` library. */
+interface LiveSocket {
+    send(data: string): unknown;
+    close(code?: number, reason?: string): unknown;
+    /** Optional; used for backpressure when present. */
+    getBufferedAmount?(): number;
+}
+interface Logger {
+    info(obj: unknown, msg?: string): void;
+    warn(obj: unknown, msg?: string): void;
+    error(obj: unknown, msg?: string): void;
+}
+type Bbox = [number, number, number, number];
+interface TrackFilter {
+    airportId?: string;
+    bbox?: Bbox;
+    minConfidence?: number;
+    maxTracks?: number;
+}
+type RemoveReason = "dropped" | "superseded" | "lost" | "evicted" | "filtered";
+interface UpdateInfo {
+    /** Bypass per-client rate limiting (status change, flight-plan change). */
+    force: boolean;
+}
+type TrackListener = (track: CurrentTrack, info: UpdateInfo) => void;
+type RemovedListener = (ev: {
+    trackId: string;
+    reason: RemoveReason;
+}) => void;
+
+interface TrackStateOptions {
+    /** Default STALE_AFTER_MS (15 s). */
+    staleAfterMs?: number;
+    /** Default LOST_AFTER_MS (90 s). */
+    lostAfterMs?: number;
+    /** Tracks unseen this long are removed. 0 disables. Default 30 min. */
+    removeAfterMs?: number;
+    /** Drop tracks outside this box unless heading into it within the lookahead. */
+    interestBbox?: Bbox;
+    /** Minutes. Default 90. */
+    interestLookaheadMin?: number;
+    /** Clock, for tests. Default Date.now. */
+    now?: () => number;
+    /** Attach flight-plan data, e.g. `flightPlanStore.attach`. */
+    attachFlightPlan?: (track: CurrentTrack) => CurrentTrack;
+}
+/** Live picture of all tracks: lifecycle (active, stale, lost, removed),
+ *  de-duplication by Mode-S address, flight-plan attachment. No I/O. */
+declare class TrackState {
+    private readonly opts;
+    private readonly tracks;
+    private readonly byIcao24;
+    private readonly onUpdate;
+    private readonly onRemoved;
+    private readonly staleAfterMs;
+    private readonly lostAfterMs;
+    private readonly removeAfterMs;
+    private sweepTimer;
+    private readonly now;
+    constructor(opts?: TrackStateOptions);
+    private statusFor;
+    on(event: "update", fn: TrackListener): () => void;
+    on(event: "removed", fn: RemovedListener): () => void;
+    get size(): number;
+    get(trackId: string): CurrentTrack | undefined;
+    values(): IterableIterator<CurrentTrack>;
+    /** Apply one fused event. Returns the resulting track, or null when the event
+     *  removed a track or was ignored. */
+    ingest(fused: FusedTrackEvent): CurrentTrack | null;
+    /** Remove a track (no-op if unknown). */
+    drop(trackId: string, reason?: RemoveReason): void;
+    /** Recompute `status` from `lastSeenAt` and remove long-gone tracks.
+     *  Emits only on a real status change. Call every few seconds. */
+    sweep(now?: number): void;
+    /** Re-attach flight plans, emitting only for tracks whose plan data changed.
+     *  Call when a plan changes so clients see it before the next radar update. */
+    refreshFlightPlans(match?: (track: CurrentTrack) => boolean): void;
+    snapshot(filter?: TrackFilter): CurrentTrack[];
+    /** Run `sweep` on an interval. Idempotent. */
+    startSweep(intervalMs?: number): void;
+    stopSweep(): void;
+    private remove;
+    private emitUpdate;
+    private inInterestZone;
+}
+declare function createTrackState(opts?: TrackStateOptions): TrackState;
+
+interface FlightPlanStoreOptions {
+    /** Plans untouched this long are dropped from memory. Default 48 h. */
+    ttlMs?: number;
+}
+interface FlightPlanFilter {
+    airportId?: string;
+    status?: string;
+    callsign?: string;
+    limit?: number;
+}
+type Listener<T> = (value: T) => void;
+/** Flight plans folded from AFTN messages, indexed for correlation with live
+ *  tracks (Mode-S address first, then callsign). No I/O: the host persists via
+ *  the `changed` event and restores with `load`. */
+declare class FlightPlanStore {
+    private readonly plans;
+    private readonly byCallsign;
+    private readonly byIcao24;
+    private readonly onChanged;
+    private readonly onExpired;
+    private readonly ttlMs;
+    private sweepTimer;
+    constructor(opts?: FlightPlanStoreOptions);
+    /** `changed`: a plan was created or updated. `expired`: a plan id left memory. */
+    on(event: "changed", fn: Listener<FlightPlan>): () => void;
+    on(event: "expired", fn: Listener<string>): () => void;
+    get size(): number;
+    get(id: string): FlightPlan | undefined;
+    /** Fold one AFTN message into its flight. Returns the updated plan, or null if ignored. */
+    apply(ev: FlightPlanEvent): FlightPlan | null;
+    /** Restore plans (e.g. from a database after a restart). Does not emit `changed`. */
+    load(plans: FlightPlan[], now?: number): number;
+    /** Best plan for a live track. Every plan sharing the Mode-S address or
+     *  callsign is a candidate (an airframe flies several legs a day); the leg
+     *  in progress, or nearest in time, wins. Cancelled plans never match. */
+    find(track: Pick<CurrentTrack, "icao24" | "callsign">, now?: number): FlightPlan | undefined;
+    /** Track with its flight-plan summary attached; unchanged when none matches.
+     *  An arrow property so it can be passed unbound, e.g. `{ attachFlightPlan: store.attach }`. */
+    readonly attach: (track: CurrentTrack) => CurrentTrack;
+    /** True if `plan` could correlate with `track`. Pair with `TrackState.refreshFlightPlans`. */
+    matches(plan: FlightPlan, track: Pick<CurrentTrack, "icao24" | "callsign">): boolean;
+    list(filter?: FlightPlanFilter): FlightPlan[];
+    /** Drop plans past the TTL; returns their ids. */
+    sweep(now?: number): string[];
+    startSweep(intervalMs?: number): void;
+    stopSweep(): void;
+    private index;
+    private unindex;
+}
+declare function createFlightPlanStore(opts?: FlightPlanStoreOptions): FlightPlanStore;
+
+/**
+ * Takeoff / landing detection from consecutive track states.
+ *
+ * Pure, dependency-free state machine. One detector instance tracks many
+ * targets. Copied from process-service so backends running without
+ * AeroSwarm's services get identical detection.
+ *
+ * Heuristics (dual-threshold hysteresis so noisy altitude/on-ground
+ * flags don't double-count):
+ *   ground → airborne  at ≥ TAKEOFF_MIN_GS_KT and (onGround=false or
+ *                      alt > AIRBORNE_ALT_FT)          ⇒ takeoff
+ *   airborne → ground  at ≤ LANDING_MAX_GS_KT and (onGround=true or
+ *                      alt < GROUND_ALT_FT)            ⇒ landing
+ */
+type MovementType = "takeoff" | "landing";
+interface MovementEvent {
+    trackId: string;
+    icao24: string | null;
+    callsign: string | null;
+    airportId?: string;
+    type: MovementType;
+    /** Unix epoch ms of the transition */
+    at: number;
+    lat: number;
+    lon: number;
+}
+interface MovementSample {
+    trackId: string;
+    icao24?: string | null;
+    callsign?: string | null;
+    airportId?: string;
+    at: number;
+    lat: number;
+    lon: number;
+    altitudeFt?: number | null;
+    groundSpeedKt?: number | null;
+    onGround?: boolean;
+}
+declare class MovementDetector {
+    private phases;
+    /** Feed one track state; returns a movement event on a transition. */
+    update(s: MovementSample): MovementEvent | null;
+    /** Forget one track (call when its track is removed). */
+    forget(trackId: string): void;
+    /** Forget tracks not updated within maxAgeMs (call periodically). */
+    sweep(maxAgeMs: number, now?: number): void;
+    get trackedCount(): number;
+    private makeEvent;
+}
+declare function createMovementDetector(): MovementDetector;
+
+/**
+ * Several sensors (radar, MLAT, ...) often see the same aircraft. Each feed
+ * produces its own track id, so without this layer they replace one another
+ * on every update. The fuser keeps ONE canonical track per aircraft and picks
+ * which sensor's position to show.
+ *
+ *   feed events ──► fuser.ingest ──► one event per aircraft ──► storage, live picture
+ *
+ * Matching: by Mode-S address when both have one. Tracks without it (surface
+ * vehicles, SSR-only radar: ids like "r50-176-42") only match across sensors
+ * when `spatial` is on, by position and time.
+ */
+interface FusionOptions {
+    /** Preferred sources while the aircraft is on the ground, best first. Each entry is a protocol ("asterix-cat010") or a source id. */
+    surfacePriority: string[];
+    /** Same, for an aircraft in the air. */
+    airbornePriority: string[];
+    /** A sensor silent for longer than this stops competing for the position. */
+    maxSourceAgeMs: number;
+    /** A sensor's contribution is forgotten after this long without an update. */
+    forgetAfterMs: number;
+    /** Also match tracks that share no Mode-S address, by distance and time. */
+    spatial: boolean;
+    matchRadiusM: number;
+    matchMaxSkewMs: number;
+    /** Two sensors further apart than this are reported as disagreeing. */
+    disagreeM: number;
+    now?: () => number;
+}
+/** MLAT first (CAT010 surface, CAT020 wide-area), then ADS-B, the system track, radar. */
+declare const DEFAULT_SURFACE_PRIORITY: readonly string[];
+/** MLAT is preferred in the air too. Put "asterix-cat062"/"asterix-cat048" first to prefer radar. */
+declare const DEFAULT_AIRBORNE_PRIORITY: readonly string[];
+/** Every option, with the defaults a host gets when it passes none. */
+declare function defaultFusionOptions(): FusionOptions;
+interface FusionStats {
+    /** Canonical tracks held. */
+    aircraft: number;
+    /** Of those, how many are fed by more than one sensor right now. */
+    merged: number;
+    /** Tracks joined by position because they shared no id. */
+    spatialMatches: number;
+    /** New tracks with several possible partners, left unmerged. */
+    ambiguous: number;
+    /** Emitted updates where the sensors were further apart than `disagreeM`. */
+    disagreements: number;
+}
+interface TrackFuser {
+    /** The event to store and show, or null when it adds nothing new. */
+    ingest(event: FusedTrackEvent$1): FusedTrackEvent$1 | null;
+    /** Forget a canonical track, e.g. when the live picture removed it. */
+    forget(trackId: string): void;
+    /** Drop sensors that went silent and tracks with none left. */
+    sweep(): void;
+    stats(): FusionStats;
+}
+/** Ids the ingest package builds from sensor + track number when there is no Mode-S address. */
+declare const isSyntheticId: (icao24: string) => boolean;
+/**
+ * Options not given (or `undefined`) take their defaults, so a host passes only
+ * what it wants to change: `createTrackFuser({ spatial: true })`.
+ */
+declare function createTrackFuser(options?: Partial<FusionOptions>): TrackFuser;
+
+/** Result of `authenticate`. `airportId` pins the connection to that airport
+ *  (a sensor token); leave it undefined for viewer tokens that may request any. */
+interface LiveAuth {
+    airportId?: string;
+}
+interface LiveServerOptions {
+    state: TrackState;
+    /** Return null to reject. A missing token is rejected (4001) before this is called. */
+    authenticate: (token: string) => Promise<LiveAuth | null> | LiveAuth | null;
+    /** Per-client, per-track push rate when the client does not ask for one. Default 10. */
+    defaultUpdateHz?: number;
+    /** Default 15 000. */
+    heartbeatMs?: number;
+    /** Skip non-forced deltas for sockets buffering more than this. Default 1 MiB. */
+    maxBufferedBytes?: number;
+    logger?: Logger;
+}
+interface LiveOpenContext {
+    /** Value of the `token` query parameter, read by the host at upgrade time. */
+    token: string | null;
+}
+interface LiveServerStats {
+    clients: number;
+    subscribed: number;
+    messagesSent: number;
+    deltasSkipped: number;
+}
+type LiveMessage = string | ArrayBuffer | Uint8Array;
+interface LiveServer {
+    handlers: {
+        open(ws: LiveSocket, ctx: LiveOpenContext): Promise<void>;
+        message(ws: LiveSocket, raw: LiveMessage): void;
+        close(ws: LiveSocket): void;
+    };
+    /** Tell clients a data source changed health. */
+    sourceStatus(sourceId: string, status: "healthy" | "degraded" | "offline"): void;
+    /** Tell clients the stream is degraded (e.g. a feed went silent). */
+    degraded(reason: string, sourceId?: string): void;
+    stats(): LiveServerStats;
+    /** Stop timers and close every socket. */
+    stop(): void;
+}
+declare function createLiveServer(opts: LiveServerOptions): LiveServer;
+
+export { type Bbox, DEFAULT_AIRBORNE_PRIORITY, DEFAULT_SURFACE_PRIORITY, type FlightPlanFilter, FlightPlanStore, type FlightPlanStoreOptions, type FusionOptions, type FusionStats, type LiveAuth, type LiveMessage, type LiveOpenContext, type LiveServer, type LiveServerOptions, type LiveServerStats, type LiveSocket, type Logger, MovementDetector, type MovementEvent, type MovementSample, type MovementType, type RemoveReason, type RemovedListener, type TrackFilter, type TrackFuser, type TrackListener, TrackState, type TrackStateOptions, type UpdateInfo, createFlightPlanStore, createLiveServer, createMovementDetector, createTrackFuser, createTrackState, defaultFusionOptions, isSyntheticId };