Files
gods-eye-view/src/layers/wildlifeSightings/acquisition.test.mjs
T
German Khokhlov 69fa1bf222 i18n: follow-up to the review of the plural and context fixes
- The street-level plan step names its place the way show_street_level
  reads its arguments: a pointed or numbered thing has no place yet, and
  "this spot" needs both coordinates.
- The view-centre error message is removed: the Street Level layer always
  gives its own translated text for an empty search, so it never showed.
  "the view centre" is one exported constant for both voice modules.
- The orbital site status uses the word of the FOCUS card in es, fr, it,
  pt and he, and the Wildlife chip agrees with "avistamientos" and
  "avvistamenti".
- CURRENTLY OVER is the noun for an overflight in de, uk, it and pt,
  shorter than before, so the place name keeps its room on a phone.
- The glossaries record the new terms; I18N.md words two rules more
  exactly.
2026-11-16 12:46:22 +04:00

1196 lines
40 KiB
JavaScript

import assert from 'node:assert/strict';
import test from 'node:test';
import { getLocale, setLocale } from '../../i18n/index.js';
import { translateFeedError } from '../../ui/statusText.js';
import { createControls } from './controls.js';
import { createLifecycle } from './lifecycle.js';
import { createWildlifeSightingsSource } from './source.js';
import { wildlifeGridCellId } from './gridViewport.js';
import { LayerLifecycle } from '../../data/lifecycle.js';
import { layerFeedState } from '../../data/feedState.js';
const NOW = Date.UTC(2026, 10, 4, 18);
const rectangle = { south: 10, west: 10, north: 12, east: 12 };
const noop = () => {};
function harness(source = { getSnapshot: async () => [] }) {
let time = NOW;
let bounds = rectangle;
let timerId = 0;
let notifications = 0;
let managerRequests = 0;
const timers = new Map();
const cameraListeners = new Set();
const document = { hidden: false };
const state = {
viewer: {
camera: {
moveEnd: {
addEventListener(fn) {
cameraListeners.add(fn);
return () => cameraListeners.delete(fn);
},
},
positionCartographic: { height: 30_000 },
computeViewRectangle: () =>
bounds &&
Object.fromEntries(
Object.entries(bounds).map(([key, value]) => [
key,
(value * Math.PI) / 180,
]),
),
},
},
enabled: true,
destroyed: false,
points: {},
rows: new Map(),
renderedRows: [],
rowById: new Map(),
selectedId: null,
selectedRow: null,
confirmed: false,
taxa: 'all',
drawnParams: null,
pendingParams: null,
failedParams: null,
lastUpdate: null,
retryAt: 0,
failures: 0,
controlsListener: () => notifications++,
};
const services = {
source,
now: () => time,
eventTarget: { document },
setTimer(fn, delay) {
const id = ++timerId;
timers.set(id, { fn, delay, due: time + delay });
return id;
},
clearTimer: (id) => timers.delete(id),
};
const parts = {
rendering: {
rebuild() {
state.renderedRows = [...state.rows.values()];
state.rowById = new Map(state.rows);
state.sightingCount = state.gridAvailable
? state.gridTotal
: state.renderedRows.length;
return true;
},
cull: noop,
clear: noop,
destroy: noop,
requestRender: noop,
},
photos: { clear: noop, destroy: noop },
selection: {
sourceIds: [],
install: noop,
refreshAmbient: noop,
publishSelected: noop,
notify: noop,
destroy: noop,
refreshContexts: noop,
syncCredits: noop,
remove: noop,
clear() {
state.selectedId = null;
state.selectedRow = null;
},
},
};
const owner = { state, services, parts };
parts.controls = createControls(owner);
parts.lifecycle = createLifecycle(owner);
const layer = {
...parts.controls.methods,
...parts.lifecycle.methods,
};
layer.attachDataManager({
refreshLayer(_id, options) {
managerRequests++;
return layer.update(undefined, options);
},
});
return {
state,
layer,
parts,
timers,
document,
chip: (id = 'taxa-all') =>
layer.getRowControls().chips.find((chip) => chip.id === id),
bounds: (value) => {
bounds = value;
},
notifications: () => notifications,
managerRequests: () => managerRequests,
moveEnd: () => {
for (const listener of cameraListeners) listener();
},
async advance(ms) {
time += ms;
for (const [id, timer] of [...timers]) {
if (timer.due <= time) {
timers.delete(id);
timer.fn();
}
}
// Timer callbacks intentionally detach manager work. Flush the promise
// chain to observe its result without wall-clock time or network access.
await new Promise((resolve) => setImmediate(resolve));
},
};
}
test('retrying a failed chip during cooldown schedules its deadline through the manager', async () => {
let attempts = 0;
const h = harness({
getSnapshot: async () => {
if (++attempts === 1)
throw Object.assign(new Error('iNaturalist rate limited'), {
status: 429,
});
return [];
},
});
await h.layer.update();
assert.equal(h.chip().state, 'error');
assert.equal(h.layer.getStats().retryInSec, 30);
h.layer.setParams(h.chip().params);
assert.equal(h.chip().state, 'loading');
assert.equal(h.timers.size, 1, 'retry retains one scheduled acquisition');
assert.equal([...h.timers.values()][0].delay, 30_000);
await h.advance(29_999);
assert.equal(attempts, 1);
await h.advance(1);
assert.equal(attempts, 2);
assert.equal(h.managerRequests(), 1);
assert.equal(h.chip().state, 'active');
assert.equal(h.chip().busy, false);
assert.equal(h.timers.size, 0);
assert.equal(h.layer.getStats().retryInSec, undefined);
});
test('parameter chips stop being pending when acquisition has no usable viewport or is disabled', async () => {
for (const scenario of ['no viewport', 'disabled']) {
const h = harness();
if (scenario === 'no viewport') h.bounds(null);
else h.layer.disable();
h.layer.setParams({ taxa: 'Aves' });
assert.equal(h.chip('taxa-birds').busy, false, scenario);
assert.equal(h.chip('taxa-birds').disabled, false, scenario);
assert.equal(h.timers.size, 0, scenario);
assert.ok(h.notifications() > 0, scenario);
}
const h = harness();
h.layer.setParams({ taxa: 'Aves' });
assert.equal(h.chip('taxa-birds').busy, true);
h.layer.disable();
assert.equal(h.chip('taxa-birds').busy, false);
assert.equal(h.timers.size, 0);
});
test('an unusable viewport at a local height never invents zoom-in guidance', async () => {
const h = harness({
getSnapshot: () =>
assert.fail('oversized snapped boxes must not be fetched'),
});
h.bounds({ south: 10.2, west: 0, north: 50.1, east: 1 });
assert.equal(await h.layer.update(), true);
assert.equal(h.layer.getStats().status, undefined);
assert.equal(h.state.query, null);
assert.equal(h.timers.size, 0);
});
test('deferred acquisition clears pending chips if its view disappears, the page hides or the manager declines', async () => {
for (const scenario of ['no viewport', 'hidden', 'manager declined']) {
const h = harness({
getSnapshot: () => assert.fail('acquisition must not proceed'),
});
h.layer.setParams({ taxa: 'Aves' });
assert.equal(h.chip('taxa-birds').busy, true);
if (scenario === 'no viewport') h.bounds(null);
if (scenario === 'hidden') h.document.hidden = true;
if (scenario === 'manager declined')
h.layer.attachDataManager({ refreshLayer: async () => false });
await h.advance(600);
assert.equal(h.chip('taxa-birds').busy, false, scenario);
assert.equal(h.chip('taxa-birds').disabled, false, scenario);
assert.equal(h.timers.size, 0, scenario);
}
});
test('a filter deferred by an unavailable viewport becomes pending when acquisition can resume', async () => {
let resolve;
let ready = true;
const h = harness({
getSnapshot: () =>
ready
? Promise.resolve([])
: new Promise((done) => {
resolve = done;
}),
});
await h.layer.update();
h.bounds(null);
h.layer.setParams({ taxa: 'Aves' });
assert.equal(h.chip('taxa-birds').busy, false);
assert.equal(h.chip().active, true, 'the last accepted filter stays active');
ready = false;
await h.advance(500);
h.bounds(rectangle);
const update = h.layer.update();
assert.equal(h.chip('taxa-birds').busy, true);
assert.equal(h.chip('taxa-birds').active, false);
resolve([]);
await update;
assert.equal(h.chip('taxa-birds').active, true);
assert.equal(h.chip('taxa-birds').busy, false);
});
test('long Retry-After and daily-budget deadlines survive source errors and control manager retries', async () => {
const nextMidnight = Date.UTC(2026, 10, 5);
for (const [retryAfter, expectedSeconds] of [
['3600', 3600],
[new Date(nextMidnight).toUTCString(), 21_600],
]) {
let requests = 0;
const source = createWildlifeSightingsSource({
now: () => NOW,
fetchImpl: async (url) => {
if (url.startsWith('/api/inaturalist/grid?'))
return Response.json({ cells: [], totalResults: 0, fetchedAt: NOW });
requests++;
return requests === 1
? new Response('', {
status: 429,
headers: {
'Retry-After': retryAfter,
'X-Upstream-Status': '429',
},
})
: Response.json({ rows: [], totalResults: 0 });
},
});
const h = harness(source);
await h.layer.update();
assert.equal(h.layer.getStats().retryInSec, expectedSeconds);
h.layer.setParams(h.chip().params);
assert.equal([...h.timers.values()][0]?.delay, expectedSeconds * 1000);
await h.advance(expectedSeconds * 1000 - 1);
assert.equal(
requests,
1,
'neither debounce nor the normal poll shortens the deadline',
);
await h.layer.update();
assert.equal(requests, 1, 'manager polling also observes the cooldown');
await h.advance(1);
assert.equal(requests, 2);
assert.equal(h.managerRequests(), 1);
assert.equal(h.chip().state, 'active');
}
});
test('failed-chip titles translate feed error patterns in German', () => {
const locale = getLocale();
try {
setLocale('de');
const h = harness();
h.state.failedParams = { confirmed: false, taxa: 'all', keys: ['taxa'] };
for (const error of [
'iNaturalist rate limited',
'Malformed iNaturalist response',
]) {
h.state.error = error;
const translated = translateFeedError(error);
assert.notEqual(translated, error);
assert.ok(h.chip().title.includes(translated), h.chip().title);
assert.equal(h.chip().title.includes(error), false);
}
} finally {
setLocale(locale);
}
});
const sighting = {
stableId: 'inat:101',
origin: 'inaturalist',
lat: 11,
lon: 11,
observedAt: NOW - 3_600_000,
iconic: 'Mammalia',
commonName: 'Synthetic whale',
};
test('SF WHALES failure keeps chosen error chip, drawn rows and manager DEGRADED with retry at 250 km', async () => {
const drawn = { ...sighting, lat: 37.7, lon: -122.5 };
let fail = false;
let gridRequests = 0;
const h = harness({
getSnapshotDetail: async () => {
if (fail)
throw Object.assign(new Error('iNaturalist HTTP 502'), {
status: 502,
retryAfterSec: 45,
});
return { rows: [drawn], totalResults: 1, fetchedAt: NOW };
},
getGridSnapshot: async () => {
gridRequests++;
return { cells: [], totalResults: 12, fetchedAt: NOW };
},
});
h.bounds({ south: 37.2, west: -123, north: 38.2, east: -122 });
h.state.viewer.camera.positionCartographic.height = 250_000;
const manager = new LayerLifecycle(h.state.viewer);
manager.register({ ...h.layer, init: () => true, updateInterval: 0 });
h.layer.attachDataManager(manager);
try {
assert.equal(await manager.setEnabled(h.layer.id, true), true);
const previousUpdate = h.layer.getStats().lastUpdate;
const previousRows = h.state.renderedRows;
fail = true;
h.layer.setParams({ taxa: 'whales' });
await h.advance(2500);
const chip = h.chip('taxa-whales');
assert.deepEqual(h.layer.getParams(), { confirmed: false, taxa: 'whales' });
assert.equal(chip.active, true);
assert.equal(chip.state, 'error');
assert.equal(chip.disabled, false);
assert.match(chip.title, /iNaturalist HTTP 502.*click to retry/);
assert.equal(h.chip('taxa-all').active, false);
assert.equal(h.state.renderedRows, previousRows);
assert.deepEqual([...h.state.rows.values()], [drawn]);
assert.equal(h.layer.getStats().lastUpdate, previousUpdate);
const stats = manager.getAll()[0].stats;
assert.equal(stats.error, 'iNaturalist HTTP 502');
assert.equal(stats.managerRefreshError, 'iNaturalist HTTP 502');
assert.equal(stats.retryInSec, 45);
assert.equal(layerFeedState(stats), 'degraded');
assert.equal(stats.status, undefined);
assert.equal(stats.statusMessage, undefined);
assert.equal(
gridRequests,
2,
'a successful grid cannot mask failed observations',
);
// A later unavailable rectangle must not replace the deck error with a
// fabricated camera-height instruction or reset the chosen filter.
h.bounds(null);
await h.layer.update();
assert.equal(h.chip('taxa-whales').active, true);
assert.equal(h.chip('taxa-whales').state, 'error');
assert.equal(layerFeedState(h.layer.getStats()), 'degraded');
assert.equal(h.layer.getStats().status, undefined);
} finally {
await manager.destroyLayer(h.layer.id);
}
});
test('ordinary WHALES refresh failure keeps the same active chip and last good rows', async () => {
let fail = false;
const h = harness({
getSnapshot: async () => {
if (fail) throw new Error('iNaturalist HTTP 503');
return [sighting];
},
});
h.layer.setParams({ taxa: 'whales' });
await h.layer.update();
const rows = h.state.renderedRows;
const update = h.state.lastUpdate;
fail = true;
await h.advance(3000);
await h.layer.update();
assert.equal(h.chip('taxa-whales').active, true);
assert.equal(h.chip('taxa-whales').state, 'error');
assert.equal(h.state.renderedRows, rows);
assert.equal(h.state.lastUpdate, update);
assert.equal(layerFeedState(h.layer.getStats()), 'degraded');
assert.equal(h.layer.getStats().retryInSec, 30);
h.layer.setParams(h.chip('taxa-whales').params);
assert.equal(h.chip('taxa-whales').state, 'loading');
assert.equal([...h.timers.values()][0].delay, 30_000);
});
test('grid acquisition runs in close views and its failure keeps cells while accepting observations', async () => {
let fail = false;
let observationRequests = 0;
let gridRequests = 0;
const cells = [{ id: 'synthetic-grid-cell', lat: 11, lon: 11, cellCount: 9 }];
const h = harness({
getSnapshotDetail: async () => ({
rows: [{ ...sighting, stableId: `inat:${++observationRequests}` }],
totalResults: 1,
fetchedAt: NOW,
}),
getGridSnapshot: async () => {
gridRequests++;
if (fail)
throw Object.assign(new Error('iNaturalist HTTP 502'), {
status: 502,
retryAfterSec: 60,
});
return { cells, totalResults: 9, fetchedAt: NOW };
},
});
h.bounds({ south: 10.5, west: 10.5, north: 11.5, east: 11.5 });
await h.layer.update();
assert.equal(gridRequests, 1);
assert.equal(h.layer.getStats().countLabel, '9 sightings in view');
fail = true;
await h.advance(3000);
assert.equal(await h.layer.update(), true);
assert.equal(observationRequests, 2);
assert.equal(gridRequests, 2);
assert.equal(h.state.gridCells, cells);
assert.equal(h.state.gridAvailable, true);
assert.deepEqual([...h.state.rows.keys()], ['inat:2']);
assert.equal(h.layer.getStats().countLabel, '9 sightings in view');
assert.equal(layerFeedState(h.layer.getStats()), 'degraded');
assert.equal(h.layer.getStats().retryInSec, 60);
});
test('a new sample preserves rows behind incumbent ambient cards until eligibility or parameters change', async () => {
const oldCard = { ...sighting, photo: { square: 'synthetic-open-photo' } };
let rows = [oldCard];
const h = harness({ getSnapshot: async () => rows });
let retained = [oldCard];
h.parts.selection.retainedAmbientRows = () => retained;
await h.layer.update();
rows = [{ ...sighting, stableId: 'inat:202' }];
await h.advance(3000);
await h.layer.update();
assert.equal(h.state.rows.get(oldCard.stableId), oldCard);
assert.equal(h.state.rowById.get(oldCard.stableId), oldCard);
retained = [];
await h.advance(3000);
await h.layer.update();
assert.equal(h.state.rows.has(oldCard.stableId), false);
assert.equal(h.state.selectedId, null);
retained = [oldCard];
h.layer.setParams({ taxa: 'whales' });
await h.advance(3000);
await h.layer.update();
assert.equal(h.state.rows.has(oldCard.stableId), false);
});
test('a selected observation survives omitted samples, zoom, changed filters and the observation window', async () => {
let rows = [sighting];
const h = harness({ getSnapshot: async () => rows });
await h.layer.update();
h.state.selectedId = sighting.stableId;
h.state.selectedRow = sighting;
rows = [{ ...sighting, stableId: 'inat:202' }];
await h.layer.update();
assert.equal(h.state.rows.get(sighting.stableId), sighting);
assert.equal(h.state.selectedId, sighting.stableId);
h.state.viewer.camera.positionCartographic.height = 3_500_000;
h.bounds({ south: 40, west: 40, north: 42, east: 42 });
await h.layer.update();
assert.equal(h.state.query.scope, 'global');
assert.equal(h.state.rowById.get(sighting.stableId), sighting);
h.layer.setParams({ taxa: 'Aves', confirmed: true });
await h.advance(49 * 3_600_000);
await h.layer.update();
assert.equal(h.state.rows.get(sighting.stableId), sighting);
assert.equal(h.state.selectedRow, sighting);
assert.equal(h.state.selectedId, sighting.stableId);
const refreshed = { ...sighting, commonName: 'Updated synthetic whale' };
rows = [refreshed];
await h.layer.update();
assert.equal(h.state.selectedRow, refreshed);
h.parts.selection.clear();
rows = [];
await h.layer.update();
assert.equal(h.state.rows.has(sighting.stableId), false);
assert.equal(h.state.selectedRow, null);
});
test('the bounded observation LRU evicts other rows before a pinned sighting', async () => {
let rows = [sighting];
const h = harness({ getSnapshot: async () => rows });
await h.layer.update();
h.state.selectedId = sighting.stableId;
h.state.selectedRow = sighting;
rows = Array.from({ length: 2100 }, (_, index) => ({
...sighting,
stableId: `inat:${index + 1000}`,
}));
await h.layer.update();
assert.equal(h.state.rows.size, 2000);
assert.equal(h.state.rows.get(sighting.stableId), sighting);
assert.equal(h.state.selectedId, sighting.stableId);
});
test('retention never revives an incumbent card after the observation window expires', async () => {
const expired = { ...sighting, observedAt: NOW - 49 * 3_600_000 };
const h = harness({ getSnapshot: async () => [] });
h.parts.selection.retainedAmbientRows = () => [expired];
await h.layer.update();
await h.advance(3000);
await h.layer.update();
assert.equal(h.state.rows.has(expired.stableId), false);
});
test('all heights and the sampled fallback use the same sightings-in-view count label', () => {
const h = harness();
h.state.renderedRows = [sighting];
assert.equal(h.layer.getStats().countLabel, '1 sighting in view');
h.state.sightingCount = 2000;
assert.equal(h.layer.getStats().count, 2000);
assert.equal(
h.layer.getStats().countLabel,
'2,000 sightings in view',
'sample totals survive reduction of many sightings into one screen bucket',
);
h.state.gridAvailable = true;
h.state.gridTotal = 1000;
h.state.sightingCount = 870;
for (const height of [30_000, 1_500_000]) {
h.state.viewer.camera.positionCartographic.height = height;
assert.equal(h.layer.getStats().count, 870);
assert.equal(h.layer.getStats().countLabel, '870 sightings in view');
}
});
test('the sightings count takes the plural form of its number', (t) => {
t.after(() => setLocale('en'));
const h = harness();
const label = (count) => {
h.state.sightingCount = count;
return h.layer.getStats().countLabel;
};
setLocale('ru');
assert.equal(label(1), '1 наблюдение в кадре');
assert.equal(label(3), '3 наблюдения в кадре');
assert.equal(label(5), '5 наблюдений в кадре');
setLocale('de');
assert.equal(label(1), '1 Beobachtung im Bild');
assert.equal(label(2000), '2.000 Beobachtungen im Bild');
});
test('the CONFIRMED chip names the sightings, apart from a confirmed launch landing', (t) => {
t.after(() => setLocale('en'));
const h = harness();
assert.equal(h.chip('quality-confirmed').label, 'CONFIRMED');
setLocale('sv');
assert.equal(h.chip('quality-confirmed').label, 'BEKRÄFTADE');
setLocale('es');
assert.equal(h.chip('quality-confirmed').label, 'CONFIRMADOS');
});
test('a stale fallback with a failed-refresh deadline remains DEGRADED, retryable and dated to the cached data', async () => {
const h = harness({
getSnapshotDetail: async () => ({
rows: [sighting],
totalResults: 1,
stale: true,
retryAfterSec: 90,
fetchedAt: NOW - 300_000,
}),
});
h.layer.setParams({ taxa: 'whales' });
await h.layer.update();
assert.equal(h.state.lastUpdate, NOW - 300_000);
assert.equal(h.layer.getStats().retryInSec, 90);
assert.equal(
h.layer.getStats().error,
'Wildlife sightings source unavailable',
);
assert.equal(layerFeedState(h.layer.getStats()), 'degraded');
assert.equal(h.chip('taxa-whales').active, true);
assert.equal(h.chip('taxa-whales').state, 'error');
assert.match(h.chip('taxa-whales').title, /click to retry/);
});
test('first enable settles one camera burst before dispatch and does not restart its first fetch set', async () => {
let observations = 0;
let tiles = 0;
let requestSignal;
const h = harness({
getSnapshotDetail: async ({ signal }) => {
observations++;
requestSignal = signal;
return { rows: [sighting], totalResults: 1, fetchedAt: NOW };
},
getGridSnapshot: async () => {
tiles++;
return { cells: [], totalResults: 0, fetchedAt: NOW };
},
});
h.state.enabled = false;
h.layer.enable();
const pending = h.layer.update();
assert.equal(observations, 0);
await h.advance(100);
h.moveEnd();
assert.equal(h.timers.size, 1);
await h.advance(299);
assert.equal(observations, 0);
await h.advance(1);
await pending;
assert.equal(observations, 1);
assert.equal(tiles, 1);
assert.equal(h.state.renderedRows[0].stableId, sighting.stableId);
h.moveEnd();
await h.advance(600);
assert.equal(observations, 1);
assert.equal(tiles, 1);
assert.equal(requestSignal.aborted, false);
assert.equal(h.timers.size, 0);
});
test('observations and each tile publish progressively without waiting for remaining tiles', async () => {
let emit;
let complete;
let tileOptions;
const h = harness({
getSnapshotDetail: async () => ({
rows: [sighting],
totalResults: 1,
fetchedAt: NOW,
}),
getGridSnapshot: (options) => {
tileOptions = options;
emit = options.onTile;
return new Promise((resolve) => {
complete = resolve;
});
},
});
assert.equal(
await h.layer.update(),
true,
'the manager receives observations without waiting for tiles',
);
assert.equal(h.state.renderedRows.length, 1);
assert.equal(h.state.gridAvailable, false);
const first = { id: 'grid:first', lat: 11, lon: 11, cellCount: 4 };
emit(
{ cells: [first], totalResults: 4, fetchedAt: NOW },
{ tile: tileOptions.tiles[0] },
);
assert.deepEqual(h.state.gridCells, [first]);
const second = { id: 'grid:second', lat: 11.5, lon: 11.5, cellCount: 3 };
complete({ cells: [first, second], totalResults: 7, fetchedAt: NOW });
await new Promise((resolve) => setImmediate(resolve));
assert.deepEqual(h.state.gridCells, [first, second]);
assert.equal(h.state.loading, false);
});
test('Europe density tiles publish before a slow observation page and survive its failure', async () => {
let rejectObservation;
let completeGrid;
let tileOptions;
const h = harness({
getSnapshotDetail: () =>
new Promise((_resolve, reject) => {
rejectObservation = reject;
}),
getGridSnapshot: (options) => {
tileOptions = options;
return new Promise((resolve) => {
completeGrid = resolve;
});
},
});
h.bounds({ south: 44, west: -8, north: 55, east: 24 });
h.state.viewer.scene = { canvas: { clientWidth: 1280, clientHeight: 800 } };
h.state.viewer.camera.positionCartographic.height = 1_500_000;
const updating = h.layer.update();
assert.equal(tileOptions.tiles.length, 3);
const first = { id: 'grid:first', lat: 48, lon: 8, cellCount: 4 };
tileOptions.onTile(
{ cells: [first], totalResults: 4, fetchedAt: NOW },
{ tile: tileOptions.tiles[0] },
);
assert.deepEqual(h.state.gridCells, [first]);
assert.equal(h.state.gridAvailable, true);
assert.equal(h.layer.getStats().count, 4);
assert.equal(h.state.rows.size, 0);
assert.equal(h.state.drawnParams, null);
await h.advance(20_000);
assert.deepEqual(
h.state.gridCells,
[first],
'a stalled observation request does not withhold accepted density',
);
rejectObservation(new Error('iNaturalist HTTP 503'));
assert.equal(await updating, true);
assert.equal(tileOptions.signal.aborted, false);
assert.equal(h.state.error, 'iNaturalist HTTP 503');
const second = { id: 'grid:second', lat: 49, lon: 10, cellCount: 7 };
tileOptions.onTile(
{ cells: [second], totalResults: 7, fetchedAt: NOW },
{ tile: tileOptions.tiles[1] },
);
assert.deepEqual(h.state.gridCells, [first, second]);
completeGrid({ cells: [first, second], totalResults: 11, fetchedAt: NOW });
await new Promise((resolve) => setImmediate(resolve));
assert.equal(h.state.loading, false);
assert.equal(h.state.error, 'iNaturalist HTTP 503');
assert.equal(layerFeedState(h.layer.getStats()), 'degraded');
});
test('a completed density response needs no per-tile callback or observation page to publish', async () => {
let completeObservations;
const cells = [{ id: 'grid:first', lat: 11, lon: 11, cellCount: 2 }];
const h = harness({
getSnapshotDetail: () =>
new Promise((resolve) => {
completeObservations = resolve;
}),
getGridSnapshot: async () => ({ cells, totalResults: 2, fetchedAt: NOW }),
});
const updating = h.layer.update();
await new Promise((resolve) => setImmediate(resolve));
assert.equal(h.state.gridCells, cells);
completeObservations({ rows: [sighting], totalResults: 1, fetchedAt: NOW });
await updating;
assert.equal(h.state.rows.get(sighting.stableId), sighting);
assert.equal(h.state.gridCells, cells);
});
test('density arriving first cannot replace a previous filter transaction before observations validate', async () => {
let rejectObservations;
let first = true;
const oldCells = [{ id: 'grid:old', lat: 11, lon: 11, cellCount: 2 }];
const h = harness({
getSnapshotDetail: () =>
first
? Promise.resolve({ rows: [sighting], totalResults: 1, fetchedAt: NOW })
: new Promise((_resolve, reject) => {
rejectObservations = reject;
}),
getGridSnapshot: async () => ({
cells: first
? oldCells
: [{ id: 'grid:new', lat: 11, lon: 11, cellCount: 6 }],
totalResults: first ? 2 : 6,
fetchedAt: NOW,
}),
});
await h.layer.update();
first = false;
h.layer.setParams({ taxa: 'Aves' });
const updating = h.layer.update();
await new Promise((resolve) => setImmediate(resolve));
assert.equal(h.state.gridCells, oldCells);
rejectObservations(new Error('iNaturalist HTTP 503'));
await updating;
assert.equal(h.state.gridCells, oldCells);
assert.equal(h.state.rows.get(sighting.stableId), sighting);
assert.equal(h.chip('taxa-birds').state, 'error');
});
test('an empty tile retires its old zoom cells while uncovered density survives a failed sibling', async () => {
let first = true;
let oldZoom;
let oldCells;
let tileOptions;
let rejectObservations;
let completeGrid;
const h = harness({
getSnapshotDetail: () =>
first
? Promise.resolve({ rows: [], totalResults: 0, fetchedAt: NOW })
: new Promise((_resolve, reject) => {
rejectObservations = reject;
}),
getGridSnapshot: (options) => {
if (first) {
oldZoom = options.tiles[0].z;
oldCells = [-4, 4].map((lon) => ({
id: wildlifeGridCellId(48, lon, oldZoom),
lat: 48,
lon,
cellCount: 2,
}));
return Promise.resolve({
cells: oldCells,
totalResults: 4,
fetchedAt: NOW,
});
}
tileOptions = options;
return new Promise((resolve) => {
completeGrid = resolve;
});
},
});
h.bounds({ south: 44, west: -8, north: 55, east: 24 });
h.state.viewer.scene = { canvas: { clientWidth: 160, clientHeight: 100 } };
h.state.viewer.camera.positionCartographic.height = 1_500_000;
await h.layer.update();
first = false;
h.state.viewer.scene.canvas.clientWidth = 1280;
h.state.viewer.scene.canvas.clientHeight = 800;
const updating = h.layer.update();
const zoom = tileOptions.tiles[0].z;
assert.ok(zoom > oldZoom);
const emptyTile = tileOptions.tiles.find((tile) =>
wildlifeGridCellId(48, -4, zoom).startsWith(
`grid:${tile.z}/${tile.x}/${tile.y}:`,
),
);
assert.ok(emptyTile);
tileOptions.onTile(
{ cells: [], totalResults: 0, fetchedAt: NOW },
{ tile: emptyTile },
);
assert.deepEqual(h.state.gridCells, [oldCells[1]]);
rejectObservations(new Error('iNaturalist HTTP 503'));
await updating;
completeGrid({
cells: [],
totalResults: 0,
fetchedAt: NOW,
error: new Error('iNaturalist HTTP 502'),
});
await new Promise((resolve) => setImmediate(resolve));
assert.deepEqual(h.state.gridCells, [oldCells[1]]);
assert.equal(h.state.gridTotal, 2);
});
test('only 429 and 5xx failures create cooldown; client, network and schema errors can retry on the next view', async () => {
for (const error of [
Object.assign(new Error('iNaturalist HTTP 400'), {
status: 400,
upstreamStatus: 0,
retryAfterSec: 30,
}),
new TypeError('Failed to fetch'),
new Error('Malformed iNaturalist response'),
]) {
let calls = 0;
const h = harness({
getSnapshot: async () => {
if (++calls === 1) throw error;
return [sighting];
},
});
await h.layer.update();
assert.equal(h.state.retryAt, 0, error.message);
assert.equal(h.layer.getStats().retryInSec, undefined);
assert.doesNotMatch(h.state.error, /rate limited/i);
await h.layer.update();
assert.equal(calls, 2);
assert.equal(h.state.renderedRows.length, 1);
}
const h = harness({
getSnapshot: async () => {
throw Object.assign(new Error('iNaturalist rate limited'), {
status: 429,
upstreamStatus: 429,
retryAfterSec: 2,
});
},
});
await h.layer.update();
assert.equal(
h.layer.getStats().retryInSec,
2,
'actual Retry-After is honored without imposing a 30s local floor',
);
// The proxy's daily-budget 503 has no upstream status. Its HTTP status and
// Retry-After still govern the next request.
const budget = harness({
getSnapshot: async () => {
throw Object.assign(new Error('iNaturalist HTTP 503'), {
status: 503,
upstreamStatus: 0,
retryAfterSec: 3600,
});
},
});
await budget.layer.update();
assert.equal(budget.layer.getStats().retryInSec, 3600);
});
test('stale cached tiles with local pacing metadata keep their display and do not enter cooldown', async () => {
const h = harness({
getSnapshotDetail: async () => ({
rows: [sighting],
totalResults: 1,
fetchedAt: NOW,
stale: true,
retryAfterSec: 30,
upstreamStatus: 0,
}),
});
await h.layer.update();
assert.equal(h.state.renderedRows.length, 1);
assert.equal(h.state.stale, true);
assert.equal(h.state.error, null);
assert.equal(h.state.retryAt, 0);
});
test('an explicit upstream Retry-After zero retries immediately while a missing header keeps the default backoff', async () => {
for (const status of [429, 503]) {
for (const explicitZero of [true, false]) {
let attempts = 0;
const source = createWildlifeSightingsSource({
now: () => NOW,
fetchImpl: async (url) => {
if (url.startsWith('/api/inaturalist/grid?'))
return Response.json({
cells: [],
totalResults: 0,
fetchedAt: NOW,
});
if (++attempts > 1)
return Response.json({ rows: [], totalResults: 0, fetchedAt: NOW });
return new Response('', {
status,
headers: {
'X-Upstream-Status': String(status),
...(explicitZero ? { 'Retry-After': '0' } : {}),
},
});
},
});
const h = harness(source);
await h.layer.update();
if (explicitZero) {
assert.equal(
h.state.retryAt,
NOW,
`${status}: zero remains an immediate deadline`,
);
assert.equal(h.layer.getStats().retryInSec, undefined);
await h.layer.update();
assert.equal(attempts, 2);
assert.equal(h.state.error, null);
} else {
assert.equal(
h.state.retryAt,
NOW + 30_000,
`${status}: no header uses the default backoff`,
);
assert.equal(h.layer.getStats().retryInSec, 30);
await h.layer.update();
assert.equal(attempts, 1);
}
}
}
});
const salishSea = { south: 47.5, west: -122.5, north: 47.7, east: -122.2 };
const inatRow = {
stableId: 'inat:301',
origin: 'inaturalist',
lat: 47.6,
lon: -122.3,
observedAt: NOW - 3_600_000,
iconic: 'Mammalia',
};
const acartiaRow = {
stableId: 'acartia:301',
origin: 'acartia',
lat: 47.6,
lon: -122.35,
observedAt: NOW - 3_600_000,
cetacean: true,
quality: 'research',
provider: { name: 'Provider', entity: null },
};
const emptyGrid = () =>
Response.json({ cells: [], totalResults: 0, fetchedAt: NOW });
const unavailable = (headers = {}) =>
new Response('', {
status: 503,
headers: { 'Retry-After': '120', ...headers },
});
// Each case runs the real source and lifecycle. A healthy source draws its
// rows while the failed source's Retry-After holds the next acquisition.
for (const [name, respond] of [
[
'Acartia alone returns 503',
(url) =>
url.startsWith('/api/acartia')
? unavailable()
: url.startsWith('/api/inaturalist/grid?')
? emptyGrid()
: Response.json({
rows: [inatRow],
totalResults: 1,
fetchedAt: NOW,
}),
],
[
'iNaturalist returns 503 without X-Upstream-Status',
(url) =>
url.startsWith('/api/acartia')
? Response.json({ rows: [acartiaRow], fetchedAt: NOW })
: url.startsWith('/api/inaturalist/grid?')
? emptyGrid()
: unavailable(),
],
[
'iNaturalist returns 503 while every grid tile fails its schema',
(url) =>
url.startsWith('/api/acartia')
? Response.json({ rows: [acartiaRow], fetchedAt: NOW })
: url.startsWith('/api/inaturalist/grid?')
? Response.json({ cells: 'malformed' })
: unavailable({ 'X-Upstream-Status': '503' }),
],
]) {
test(`a partial failure keeps its Retry-After: ${name}`, async () => {
let healthy = false;
let requests = 0;
const source = createWildlifeSightingsSource({
now: () => NOW,
fetchImpl: async (url) => {
if (!url.startsWith('/api/inaturalist/grid?')) requests++;
if (healthy)
return url.startsWith('/api/acartia')
? Response.json({ rows: [acartiaRow], fetchedAt: NOW })
: url.startsWith('/api/inaturalist/grid?')
? emptyGrid()
: Response.json({
rows: [inatRow],
totalResults: 1,
fetchedAt: NOW,
});
return respond(url);
},
});
const h = harness(source);
h.bounds(salishSea);
h.state.enabled = false;
h.layer.enable();
const first = h.layer.update();
await h.advance(300);
await first;
await new Promise((resolve) => setImmediate(resolve));
assert.equal(h.state.renderedRows.length, 1, 'the healthy source draws');
assert.ok(h.state.error, 'the failed source is reported');
// The source clock stays at NOW; the layer settled 300 ms of camera time.
assert.equal(h.state.retryAt, NOW + 300 + 120_000);
assert.equal(h.layer.getStats().retryInSec, 120);
const attempted = requests;
h.bounds({ ...salishSea, north: 47.8 });
h.moveEnd();
assert.equal([...h.timers.values()][0]?.delay, 120_000);
await h.advance(119_999);
await h.layer.update();
assert.equal(
requests,
attempted,
'neither a camera move nor manager polling skips the cooldown',
);
healthy = true;
await h.advance(1);
await new Promise((resolve) => setImmediate(resolve));
assert.ok(requests > attempted, 'acquisition resumes at the deadline');
assert.equal(h.state.error, null);
assert.equal(h.state.retryAt, 0, 'a fully successful refresh clears it');
assert.equal(h.layer.getStats().retryInSec, undefined);
assert.equal(h.state.renderedRows.length, 2);
});
}
// Every failed request keeps its own timing. The layer waits for the longest
// effective delay: 4xx other than 429 never waits, 429/5xx wait for their
// Retry-After or the default backoff. The shown error explains that wait.
async function settleThroughSource(fetchImpl, bounds = salishSea) {
const h = harness(
createWildlifeSightingsSource({ now: () => NOW, fetchImpl }),
);
h.bounds(bounds);
h.state.enabled = false;
h.layer.enable();
const first = h.layer.update();
await h.advance(300);
await first;
await new Promise((resolve) => setImmediate(resolve));
await new Promise((resolve) => setImmediate(resolve));
return h;
}
const tileX = (url) =>
Number(new URL(url, 'https://example.test').searchParams.get('x'));
const observations = () =>
Response.json({ rows: [inatRow], totalResults: 1, fetchedAt: NOW });
test('an antimeridian box 400 never hides the other box 503 Retry-After', async () => {
for (const westFails of [true, false]) {
const h = await settleThroughSource(
async (url) => {
if (url.startsWith('/api/inaturalist/grid?')) return emptyGrid();
const west =
Number(
new URL(url, 'https://example.test').searchParams.get('west'),
) > 0;
return west === westFails
? new Response('', { status: 400 })
: unavailable();
},
{ south: 10, west: 179, north: 12, east: -179 },
);
assert.equal(h.state.error, 'iNaturalist HTTP 503');
assert.equal(h.state.retryAt, NOW + 300 + 120_000);
assert.equal(h.layer.getStats().retryInSec, 120);
}
});
test('a grid tile 400 with Retry-After beside successful tiles creates no cooldown', async () => {
let tiles = new Set();
const h = await settleThroughSource(async (url) => {
if (!url.startsWith('/api/inaturalist/grid?')) return observations();
tiles.add(tileX(url));
return tileX(url) === Math.min(...tiles) && tiles.size === 1
? new Response('', { status: 400, headers: { 'Retry-After': '120' } })
: emptyGrid();
});
assert.ok(tiles.size > 1, 'the view spans several grid tiles');
assert.equal(h.state.error, 'iNaturalist HTTP 400');
assert.equal(h.state.retryAt, 0);
assert.equal(h.layer.getStats().retryInSec, undefined);
});
test('a short grid Retry-After never undercuts a sibling 5xx default backoff', async () => {
let failed = 0;
const h = await settleThroughSource(async (url) => {
if (!url.startsWith('/api/inaturalist/grid?')) return observations();
failed++;
if (failed === 1)
return new Response('', { status: 503, headers: { 'Retry-After': '2' } });
if (failed === 2) return new Response('', { status: 502 });
return emptyGrid();
});
assert.ok(failed >= 2);
assert.equal(h.state.error, 'iNaturalist HTTP 502');
assert.equal(h.state.retryAt, NOW + 300 + 30_000);
assert.equal(h.layer.getStats().retryInSec, 30);
});
test('an enormous Retry-After is capped at one day and a non-finite one uses the default backoff', async () => {
for (const [header, delay] of [
['1' + '0'.repeat(306), 86_400_000],
['1' + '0'.repeat(400), 30_000],
]) {
const h = await settleThroughSource(async (url) =>
url.startsWith('/api/inaturalist/grid?')
? emptyGrid()
: url.startsWith('/api/acartia')
? Response.json({ rows: [], fetchedAt: NOW })
: new Response('', {
status: 503,
headers: { 'Retry-After': header },
}),
);
assert.equal(h.state.error, 'iNaturalist HTTP 503');
assert.ok(Number.isFinite(h.state.retryAt));
assert.equal(h.state.retryAt, NOW + 300 + delay, header.length);
}
});