diff --git a/.github/workflows/data-refresh.yml b/.github/workflows/data-refresh.yml index fa24a64..bf90aa5 100644 --- a/.github/workflows/data-refresh.yml +++ b/.github/workflows/data-refresh.yml @@ -49,9 +49,11 @@ jobs: key: gaia-dr3-${{ hashFiles('tools/etl/sources/gaia.ts') }} # Every other source is fetched live on this fresh runner. A failed fetch fails the run by - # design — no refresh is better than a partial one. That includes Gaia on a cold cache: - # the ETL skips it when unreachable, and the merge gate in build.ts then refuses a - # catalogue it contributed nothing to. + # design — no refresh is better than a partial one. That includes Gaia on a cold cache, by + # two different paths: its Hipparcos cross-match is required, so an unreachable archive + # fails the run from fetchStars itself, while its main query is skipped when unreachable and + # the merge gate in build.ts then refuses a catalogue it contributed nothing to. An archive + # that answers short rather than not at all is caught in fetchGaiaStars. - name: Rebuild the datasets run: npm run etl diff --git a/tools/etl/build.ts b/tools/etl/build.ts index b213455..5ca1709 100644 --- a/tools/etl/build.ts +++ b/tools/etl/build.ts @@ -66,8 +66,18 @@ function validateStars(stars: StarRecord[]): void { * The other failure leaves no close pair at all, because proper motion had already carried the * two entries tens of arcseconds apart — the 2026-08-24 refresh, where HYG sat at epoch 2000.0 * and Gaia at J2016.0. What it does leave is HYG rows that found no counterpart: 36 056 of them - * against the 10 876 Gaia genuinely lacks (bright stars it saturates on, red dwarfs past its - * magnitude cut). + * against the 10 886 today, and no counterpart was possible for most of those. Two thirds of them, + * 6 835, are the stars Gaia measures but the main query never downloads, because Gaia's parallax + * puts them past `ETL_GAIA_DISTANCE_PC` while Hipparcos put them inside `ETL_STAR_DISTANCE_PC`; + * they are every star in the published catalogue beyond 250 pc. The rest are what Gaia genuinely + * lacks: bright stars it saturates on, red dwarfs past its magnitude cut. So the headroom left to + * the ceiling tracks the gap between those two cutoffs as much as Gaia's completeness. + * + * This bounds a merge that went wrong, and — loosely — a Gaia download that came back short: a + * truncated answer leaves the HYG rows whose counterpart it dropped without one, so survivors go + * *up*, not down. Measured against the published catalogue: 10 886 today, 11 004 at nine tenths of + * the rows, 12 711 at half, 16 258 at a third. So this ceiling only catches a truncation past about + * two thirds, and `fetchGaiaStars` catches the shallower ones with its own row floor. */ const MAX_UNMERGED_TWINS = 100; const MAX_HYG_SURVIVORS = 15_000; diff --git a/tools/etl/fetchStars.ts b/tools/etl/fetchStars.ts index 1f2eb66..0225fba 100644 --- a/tools/etl/fetchStars.ts +++ b/tools/etl/fetchStars.ts @@ -3,7 +3,7 @@ import { writeFileSync } from 'node:fs'; import { mergeStarCatalogues, placementDistancePc } from '../../src/app/shared/astro/star-merge'; import { encodeStarCatalog } from '../../src/app/shared/models/star-catalog'; import { StarRecord, SUN_STAR_ID } from '../../src/app/shared/models/star.model'; -import { fetchGaiaDistancesByHip } from './sources/gaia'; +import { fetchGaiaDistancesByHip, GaiaAnswerError } from './sources/gaia'; import { positionalSources } from './sources/registry'; import { PARALLAX_PRECISION_MAS } from './sources/star-sources'; import { parseCsvObjects, parseOptionalNumber } from './lib/csv'; @@ -142,7 +142,9 @@ export async function fetchStars(): Promise { * * A source that cannot be reached is reported and skipped here rather than thrown, so a run still * gets as far as validation and says what it has. Whether that may be published is decided - * there: `validateMerge` in build.ts refuses a catalogue Gaia contributed nothing to. + * there: `validateMerge` in build.ts refuses a catalogue Gaia contributed nothing to. A source + * that answered with something unusable ({@link GaiaAnswerError}) is a different matter, and stops + * the run where it happened rather than being reported later as an outage. */ async function mergeWithOtherSources(hygStars: StarRecord[]): Promise { const others = positionalSources().filter((source) => source.id !== 'hyg'); @@ -160,6 +162,11 @@ async function mergeWithOtherSources(hygStars: StarRecord[]): Promise { for (let attempt = 0; ; attempt++) { - const response = await fetch(url).catch((error: unknown) => (error instanceof Error ? error : new Error(String(error)))); + let response = await fetch(url).catch((error: unknown) => (error instanceof Error ? error : new Error(String(error)))); if (!(response instanceof Error) && response.ok) { - return response.text(); + // Read inside the loop, because the body is where these downloads fail: the Gaia CSV is + // 57 MB, and a connection reset part-way through rejects here, long after the 200. + const body = await response.text().catch((error: unknown) => (error instanceof Error ? error : new Error(String(error)))); + if (typeof body === 'string') { + return body; + } + response = body; } const reason = response instanceof Error ? response.message : `${response.status} ${response.statusText}`; // A 4xx is the request's own fault, and waiting will not change the answer. diff --git a/tools/etl/sources/gaia.ts b/tools/etl/sources/gaia.ts index c70d6a6..bdd6626 100644 --- a/tools/etl/sources/gaia.ts +++ b/tools/etl/sources/gaia.ts @@ -38,9 +38,12 @@ const CATALOGUE_EPOCH = 2000.0; * past anything this map draws, so the limit here is a payload decision: the catalogue is baked * into a static asset that a browser downloads before the first frame. */ -const DISTANCE_CUTOFF_PC = Number(process.env['ETL_GAIA_DISTANCE_PC'] ?? 250); -const MAGNITUDE_LIMIT = Number(process.env['ETL_GAIA_MAGNITUDE_LIMIT'] ?? 12); -const ROW_LIMIT = Number(process.env['ETL_GAIA_ROW_LIMIT'] ?? 500000); +const DEFAULT_DISTANCE_CUTOFF_PC = 250; +const DEFAULT_MAGNITUDE_LIMIT = 12; +const DEFAULT_ROW_LIMIT = 500_000; +const DISTANCE_CUTOFF_PC = Number(process.env['ETL_GAIA_DISTANCE_PC'] ?? DEFAULT_DISTANCE_CUTOFF_PC); +const MAGNITUDE_LIMIT = Number(process.env['ETL_GAIA_MAGNITUDE_LIMIT'] ?? DEFAULT_MAGNITUDE_LIMIT); +const ROW_LIMIT = Number(process.env['ETL_GAIA_ROW_LIMIT'] ?? DEFAULT_ROW_LIMIT); /** * Relative parallax error above which a star is dropped: a parallax measured to worse than 20% @@ -67,6 +70,35 @@ function buildQuery(): string { ].join(' '); } +/** + * How many rows the query above holds when nothing is overridden: 412 765, and DR3 is a finished + * data release, so that number only moves when the query does. It lives here, under the query, so + * that an edit to any of its filters is made with the count it invalidates in view. + * + * Checked because a short answer looks exactly like a complete one. The TAP service truncates on + * its own timeout and still serves a well-formed CSV with a 200, and the rows are ordered by + * magnitude, so what comes back is the bright half — the half HYG overlaps. The merge gate in + * `build.ts` would then see Gaia stars present and a survivor count barely moved, and pass a + * catalogue missing two hundred thousand stars, which the weekly job would publish and the runner + * would cache for the weeks after it. Same failure, and same guard, as + * {@link MIN_USABLE_HIP_DISTANCES} below. + * + * Only checked when nothing is overridden: the environment overrides exist to fetch a smaller + * slice on purpose. + */ +const DEFAULT_QUERY_ROWS = 412_765; +const MIN_ROW_SHARE = 0.95; + +/** + * An answer the archive gave that cannot be worked with, as against an archive that gave none. + * + * `fetchStars` skips a source it cannot reach and leaves the merge gate to judge the result. That + * is right for an outage and wrong for a truncated CSV, which would be skipped, cached, and land + * as "the archive was unreachable" long after the assets had been overwritten — so these throws + * are marked, and rethrown there. + */ +export class GaiaAnswerError extends Error {} + /** * Gaia publishes no spectral classifications, but `bp_rp` is a colour index on the same footing * as HYG's `ci` — so the app's existing colour and spectral-class handling works unchanged, and @@ -90,8 +122,22 @@ export async function fetchGaiaStars(): Promise { // Keyed by the whole request, so a response cached for other columns, another order, or // another endpoint can never be mistaken for this one — the cache records only that some // response arrived, not what it answered. - const csv = await fetchTextCached(url, `gaia-dr3-${createHash('sha1').update(url).digest('hex').slice(0, 8)}.csv`); + const cacheKey = `gaia-dr3-${createHash('sha1').update(url).digest('hex').slice(0, 8)}.csv`; + const csv = await fetchTextCached(url, cacheKey); const rows = parseCsvObjects(csv); + const jobsQuery = DISTANCE_CUTOFF_PC === DEFAULT_DISTANCE_CUTOFF_PC && MAGNITUDE_LIMIT === DEFAULT_MAGNITUDE_LIMIT && ROW_LIMIT === DEFAULT_ROW_LIMIT; + if (jobsQuery && rows.length < DEFAULT_QUERY_ROWS * MIN_ROW_SHARE) { + throw new GaiaAnswerError( + `Gaia returned ${rows.length} rows, not the ~${DEFAULT_QUERY_ROWS} this query holds — the answer was cut short, it was an error page ` + + `served with a 200, or the query was edited without updating DEFAULT_QUERY_ROWS; delete tools/etl/.cache/${cacheKey} once the archive answers properly` + ); + } + // Not gated on `jobsQuery` like the floor above it: the only ways to reach this cap are the + // overrides that *widen* the query, and they are exactly when it is worth saying. What it must + // not fire on is a deliberately smaller slice, where filling the limit is the whole point. + if (ROW_LIMIT >= DEFAULT_ROW_LIMIT && rows.length >= ROW_LIMIT) { + throw new GaiaAnswerError(`Gaia returned the query's own ${ROW_LIMIT}-row limit, so it is the limit deciding what the map holds; raise ETL_GAIA_ROW_LIMIT.`); + } const stars: StarRecord[] = []; rows.forEach((row, index) => {