Files
gods-eye-view/src/maps/controller.test.mjs
T
Sameh Khamis a8a9cc73a4 Map stacks off the Cesium allow-list: providers move into the Cesium adapter
The map stacks' imagery, terrain and Google 3D factories move into the
Cesium adapter (src/render/cesium/mapImagery.js, mapTerrain.js,
google3d.js); the ./maps/imagery, ./maps/terrain and ./maps/3d exports
point there. The catalog names its ion stacks by asset number, and the
map source controller and default sources are Cesium-free: they
build providers and switch imagery layers, terrain, tilesets and the
globe's visibility through a map engine (src/maps/engine.js) that the
Cesium adapter provides as it loads (mapEngine.js), through the
application's renderer or the ./render/cesium/unbound export. The
controller and createDefaultMapSources also take it as an `engine`
option.

src/maps/catalog.js, controller.js, imagery.js, terrain.js and google3d.js
leave the allow-list.
2026-11-09 12:11:42 -08:00

1395 lines
46 KiB
JavaScript

import test from 'node:test';
import assert from 'node:assert/strict';
import { MapSourceController } from './controller.js';
// The controller switches stacks through the Cesium map engine.
import '../render/cesium/mapEngine.js';
import { createDefaultMapSources } from './defaultSources.js';
import { bindRenderer } from '../render/rendererOf.js';
function event() {
const listeners = new Set();
return {
addEventListener(fn) {
listeners.add(fn);
return () => listeners.delete(fn);
},
raise(value = {}) {
for (const fn of [...listeners]) fn(value);
},
get size() {
return listeners.size;
},
};
}
function fixture(registry, options = {}) {
const imagery = [],
credits = new Set(),
primitives = [],
removed = [],
changes = [];
const viewer = {
scene: {
globe: { show: true },
requestRender() {},
primitives: {
add(value) {
primitives.push(value);
},
remove(value) {
primitives.splice(primitives.indexOf(value), 1);
value.destroy?.();
},
},
},
imageryLayers: {
add(value) {
imagery.push(value);
},
remove(value, destroy) {
imagery.splice(imagery.indexOf(value), 1);
removed.push({ value, destroy });
},
},
};
bindRenderer(viewer, {
credits: {
addStatic(credit) {
credits.add(credit);
return () => credits.delete(credit);
},
},
});
const controller = new MapSourceController(viewer, {
registry,
createImageryLayer: (provider) => ({ provider }),
onChange: (state) => changes.push(state),
...options,
});
return { viewer, controller, imagery, credits, primitives, removed, changes };
}
const settle = async () => {
for (let i = 0; i < 20; i++) await Promise.resolve();
};
const descriptor = (id) => ({ id, label: id, kind: 'imagery' });
function publicFixture(options) {
const tileset = { show: true };
const registry = createDefaultMapSources({ googleTileset: tileset });
const providers = new Map();
for (const source of registry.sources) {
if (!source.imagery) continue;
const provider = { id: source.descriptor.id, errorEvent: event() };
providers.set(source.descriptor.id, provider);
source.imagery = async () => provider;
source.terrain = {
id: 'keyless',
create: async () => ({ provider: { id: 'terrain' } }),
};
}
return { ...fixture(registry, options), registry, providers, tileset };
}
test('an additional imagery source needs no controller branch and owns its cached resources', async () => {
let reads = 0,
destroys = 0,
terrainReads = 0;
const provider = {
destroy() {
destroys++;
},
};
const terrain = {
id: 'custom-floor',
create: async () => {
terrainReads++;
return { provider: { id: 'terrain' } };
},
};
const registry = {
defaultId: 'custom',
sources: [
{
descriptor: descriptor('custom'),
imagery: async () => {
reads++;
return provider;
},
terrain,
},
],
};
const env = fixture(registry);
await env.controller.setStack('custom');
await env.controller.setStack('custom');
assert.equal(env.controller.getActiveId(), 'custom');
assert.equal(env.viewer.terrainProvider.id, 'terrain');
assert.equal(reads, 1);
assert.equal(terrainReads, 1);
assert.equal(env.imagery.length, 1);
assert.equal(
env.removed.length,
0,
'same provider keeps its loaded imagery layer',
);
env.controller.destroy();
env.controller.destroy();
await settle();
assert.equal(env.imagery.length, 0);
assert.equal(env.removed[0].destroy, true);
assert.equal(destroys, 1);
});
test('repeated Esri shot handoffs retain imagery and keep tile fallback live', async () => {
const env = publicFixture();
await env.controller.setStack('esri-imagery');
const layer = env.imagery[0];
const generation = env.controller.getSwitchGeneration();
const errors = env.providers.get('esri-imagery').errorEvent;
for (let i = 0; i < 3; i++) await env.controller.setStack('esri-imagery');
assert.equal(env.imagery[0], layer);
assert.equal(env.removed.length, 0);
assert.equal(errors.size, 1);
assert.equal(env.controller.getSwitchGeneration(), generation + 3);
errors.raise();
errors.raise();
await settle();
assert.equal(env.controller.getActiveId(), 'osm');
assert.equal(env.removed.length, 1);
assert.equal(errors.size, 0);
env.controller.destroy();
});
test('returning to the live provider supersedes a pending switch without rebuilding imagery', async () => {
const env = publicFixture();
await env.controller.setStack('esri-imagery');
const layer = env.imagery[0];
let resolve;
env.registry.sources.find(
(source) => source.descriptor.id === 'osm',
).imagery = () =>
new Promise((done) => {
resolve = done;
});
const pending = env.controller.setStack('osm');
await settle();
await env.controller.setStack('esri-imagery');
resolve(env.providers.get('osm'));
await pending;
assert.equal(env.controller.getActiveId(), 'esri-imagery');
assert.equal(env.imagery[0], layer);
assert.equal(env.removed.length, 0);
await env.controller.setStack('photoreal');
assert.equal(env.imagery.length, 0);
assert.equal(env.tileset.show, true);
await env.controller.setStack('esri-imagery');
assert.notEqual(env.imagery[0], layer, 'a removed layer must be recreated');
assert.equal(env.viewer.scene.globe.show, true);
assert.equal(env.tileset.show, false);
env.controller.destroy();
});
test('a destroyed controller aborts creation and disposes a late provider without touching the scene', async () => {
let resolve,
signal,
destroyed = 0;
const env = fixture({
defaultId: 'slow',
sources: [
{
descriptor: descriptor('slow'),
imagery: (request) => {
signal = request.signal;
return new Promise((done) => {
resolve = done;
});
},
},
],
});
const loading = env.controller.setStack('slow');
await settle();
env.controller.destroy();
assert.equal(signal.aborted, true);
resolve({
destroy() {
destroyed++;
},
});
await loading;
await settle();
assert.equal(destroyed, 1);
assert.equal(env.imagery.length, 0);
assert.deepEqual(
env.changes.map((state) => state.status),
['switching'],
);
});
test('slow terrain cannot overwrite a newer source and a 3D view never starts unused terrain', async () => {
const env = publicFixture();
let resolve,
reads = 0;
const osm = env.registry.sources.find(
(source) => source.descriptor.id === 'osm',
);
osm.terrain = {
id: 'slow-floor',
create: () => {
reads++;
return new Promise((done) => {
resolve = done;
});
},
};
await env.controller.setStack('photoreal');
assert.equal(reads, 0);
const loading = env.controller.setStack('osm');
await settle();
await env.controller.setStack('photoreal');
resolve({ provider: { id: 'late-terrain' } });
await loading;
assert.equal(env.viewer.terrainProvider, undefined);
assert.equal(env.viewer.scene.globe.show, false);
assert.equal(env.tileset.show, true);
assert.equal(env.controller.getActiveId(), 'photoreal');
env.controller.destroy();
});
test('Esri construction fallback reports and attributes the source actually rendered', async () => {
const env = publicFixture();
env.registry.sources.find(
(source) => source.descriptor.id === 'esri-imagery',
).imagery = async () => {
throw new Error('unreachable');
};
await env.controller.setStack('esri-imagery');
assert.equal(env.controller.getActiveId(), 'osm');
assert.equal(
env.controller.getState().lastError,
'Esri Satellite is unavailable; using OSM',
);
assert.equal(env.imagery[0].provider, env.providers.get('osm'));
assert.equal(env.credits.size, 0);
env.controller.destroy();
});
test('one Esri tile failure stays put, two fall back, and stale errors cannot replace a selection', async () => {
const env = publicFixture();
await env.controller.setStack('esri-imagery');
assert.deepEqual(
[...env.credits],
[{ text: 'Powered by Esri', href: 'https://www.esri.com', inline: true }],
);
const errorEvent = env.providers.get('esri-imagery').errorEvent;
errorEvent.raise();
await settle();
assert.equal(env.controller.getActiveId(), 'esri-imagery');
errorEvent.raise();
await settle();
assert.equal(env.controller.getActiveId(), 'osm');
assert.equal(env.credits.size, 0);
assert.equal(
env.controller.getState().lastError,
'Esri Satellite tile requests failed; using OSM',
);
assert.equal(errorEvent.size, 0);
await env.controller.setStack('photoreal');
errorEvent.raise({ timesRetried: 9 });
await settle();
assert.equal(env.controller.getActiveId(), 'photoreal');
env.controller.destroy();
});
test('tooltips and rejected selection share the registry reason, including retired map IDs', async () => {
const errors = [],
env = publicFixture();
env.controller._onError = (message) => errors.push(message);
const reason = env.controller
.getStacks()
.find((stack) => stack.id === 'bing-aerial').unavailableReason;
await env.controller.setStack('bing-aerial');
assert.deepEqual(errors, [reason]);
assert.match(reason, /CESIUM_ION_TOKEN/);
await env.controller.setStack('bing-road');
assert.equal(env.controller.getActiveId(), 'photoreal');
env.controller.destroy();
});
test('a factory-owned 3D tileset is released after late completion and supplied tilesets stay caller-owned', async () => {
let resolve,
destroyed = 0;
const supplied = {
show: true,
destroy() {
assert.fail('caller-owned tileset');
},
};
const env = fixture({
defaultId: 'three',
sources: [
{
descriptor: { id: 'three' },
createTileset: () =>
new Promise((done) => {
resolve = done;
}),
},
{ descriptor: { id: 'supplied' }, tileset: supplied },
],
});
const loading = env.controller.setStack('three');
await settle();
env.controller.destroy();
resolve({
destroy() {
destroyed++;
},
});
await loading;
assert.equal(destroyed, 1);
assert.equal(env.primitives.length, 0);
});
test('invalid source graphs fail before constructing or caching a provider', () => {
const a = { descriptor: descriptor('a'), constructionFallback: { id: 'b' } };
const b = { descriptor: descriptor('b'), constructionFallback: { id: 'a' } };
assert.throws(() => fixture({ sources: [a, b] }), /fallback cycle/);
assert.throws(() => fixture({ sources: [a, a] }), /unique/);
assert.throws(() => fixture({ sources: [a] }), /Unknown map fallback/);
});
for (const reactivate of [false, true]) {
test(`a superseded 3D load stays outside the scene and is released (reactivate: ${reactivate})`, async () => {
let resolve,
destroyed = 0,
reads = 0;
const tileset = {
show: true,
isDestroyed: () => destroyed > 0,
destroy() {
destroyed++;
},
};
const supplied = { show: true };
const env = fixture({
defaultId: 'slow',
sources: [
{
descriptor: { id: 'slow' },
createTileset: () => {
reads++;
return new Promise((done) => {
resolve = done;
});
},
},
{ descriptor: { id: 'supplied' }, tileset: supplied },
],
});
const loading = env.controller.setStack('slow');
await settle();
await env.controller.setStack('supplied');
resolve(tileset);
await loading;
assert.equal(env.primitives.length, 0);
assert.equal(supplied.show, true);
assert.equal(env.controller.getActiveId(), 'supplied');
if (reactivate) {
await env.controller.setStack('slow');
await env.controller.setStack('slow');
assert.deepEqual(env.primitives, [tileset]);
assert.equal(reads, 1);
assert.equal(tileset.show, true);
assert.equal(supplied.show, false);
}
env.controller.destroy();
await settle();
assert.equal(env.primitives.length, 0);
assert.equal(destroyed, 1);
});
}
test('a failed recovery reports its error and leaves switching settled', async () => {
const errors = [];
const env = fixture(
{
defaultId: 'first',
recoveryId: 'recovery',
sources: [
{
descriptor: descriptor('first'),
imagery: async () => {
throw new Error('first offline');
},
},
{
descriptor: descriptor('recovery'),
imagery: async () => {
throw new Error('recovery offline');
},
},
],
},
{ onError: (message) => errors.push(message) },
);
const result = await env.controller.setStack('first');
assert.equal(result.status, 'ready');
assert.equal(result.lastError, 'recovery offline');
assert.deepEqual(errors, ['first offline', 'recovery offline']);
assert.equal(env.changes.at(-1).status, 'error');
assert.equal(env.imagery.length, 0);
env.controller.destroy();
});
test('imagery host tileset follows supplied, owned and globe map sources', async () => {
const supplied = { show: true };
const owned = { show: false };
const registry = {
defaultId: 'supplied',
sources: [
{ descriptor: descriptor('supplied'), tileset: supplied },
{ descriptor: descriptor('owned'), createTileset: async () => owned },
{ descriptor: descriptor('globe'), imagery: async () => ({}) },
],
};
const { controller } = fixture(registry);
assert.equal(controller.getImageryHostTileset(), supplied);
await controller.setStack('owned');
assert.equal(controller.getImageryHostTileset(), owned);
assert.equal(controller.getDrapeSurface(), 'tileset');
await controller.setStack('globe');
assert.equal(controller.getImageryHostTileset(), null);
assert.equal(controller.getDrapeSurface(), 'globe');
await controller.setStack('supplied');
assert.equal(controller.getImageryHostTileset(), supplied);
assert.equal(controller.getDrapeSurface(), 'tileset');
supplied.show = false;
assert.equal(controller.getDrapeSurface(), 'none');
controller.destroy();
assert.equal(controller.getImageryHostTileset(), null);
assert.equal(controller.getDrapeSurface(), null);
});
function leaseFixture() {
const env = publicFixture();
const switches = [];
const setStack = env.controller.setStack.bind(env.controller);
env.controller.setStack = (id, options) => {
switches.push(id);
return setStack(id, options);
};
return { ...env, switches };
}
test('an imagery comparison lease rejects a second owner synchronously until released', async () => {
const env = leaseFixture();
const lease = env.controller.acquireImageryComparison({
owner: 'nepal',
switchPolicy: 'preserve',
});
assert.throws(
() => env.controller.acquireImageryComparison({ owner: 'recent' }),
/held by nepal/,
);
assert.deepEqual(await lease.ready, {
status: 'ready',
activeId: 'photoreal',
});
await lease.release();
const next = env.controller.acquireImageryComparison({ owner: 'recent' });
assert.deepEqual(await next.ready, {
status: 'ready',
activeId: 'photoreal',
});
await next.release();
assert.deepEqual(env.switches, []);
env.controller.destroy();
});
test("the 'esri' policy switches from any other stack and release restores it", async () => {
for (const initial of ['photoreal', 'osm']) {
const env = leaseFixture();
if (initial !== env.controller.getActiveId())
await env.controller.setStack(initial);
env.switches.length = 0;
const lease = env.controller.acquireImageryComparison({
owner: 'nepal',
switchPolicy: 'esri',
});
assert.deepEqual(await lease.ready, {
status: 'ready',
activeId: 'esri-imagery',
});
assert.equal(env.controller.getActiveId(), 'esri-imagery');
await lease.release();
assert.equal(env.controller.getActiveId(), initial);
assert.deepEqual(env.switches, ['esri-imagery', initial]);
env.controller.destroy();
}
});
test("the 'esri-if-photoreal' policy leaves any 2D basemap alone", async () => {
const photoreal = leaseFixture();
const fromPhotoreal = photoreal.controller.acquireImageryComparison({
owner: 'recent',
switchPolicy: 'esri-if-photoreal',
});
assert.equal((await fromPhotoreal.ready).activeId, 'esri-imagery');
await fromPhotoreal.release();
assert.deepEqual(photoreal.switches, ['esri-imagery', 'photoreal']);
photoreal.controller.destroy();
const osm = leaseFixture();
await osm.controller.setStack('osm');
osm.switches.length = 0;
const fromOsm = osm.controller.acquireImageryComparison({
owner: 'recent',
switchPolicy: 'esri-if-photoreal',
});
assert.deepEqual(await fromOsm.ready, { status: 'ready', activeId: 'osm' });
await fromOsm.release();
assert.equal(osm.controller.getActiveId(), 'osm');
assert.deepEqual(osm.switches, []);
osm.controller.destroy();
});
test("the 'preserve' policy never switches, whatever is active", async () => {
for (const initial of ['photoreal', 'esri-imagery', 'osm']) {
const env = leaseFixture();
if (initial !== env.controller.getActiveId())
await env.controller.setStack(initial);
env.switches.length = 0;
const lease = env.controller.acquireImageryComparison({
owner: 'nepal',
});
assert.deepEqual(await lease.ready, { status: 'ready', activeId: initial });
await lease.release();
assert.equal(env.controller.getActiveId(), initial);
assert.deepEqual(env.switches, []);
env.controller.destroy();
}
});
test('release keeps an operator choice made while the comparison was open', async () => {
const env = leaseFixture();
const lease = env.controller.acquireImageryComparison({
owner: 'nepal',
switchPolicy: 'esri',
});
await lease.ready;
await env.controller.setStack('osm');
await lease.release();
assert.equal(env.controller.getActiveId(), 'osm');
assert.deepEqual(env.switches, ['esri-imagery', 'osm']);
env.controller.destroy();
});
test('release keeps a fallback that replaced the comparison stack', async () => {
const env = leaseFixture();
const lease = env.controller.acquireImageryComparison({
owner: 'nepal',
switchPolicy: 'esri',
});
await lease.ready;
const errors = env.providers.get('esri-imagery').errorEvent;
errors.raise();
errors.raise();
await settle();
assert.equal(env.controller.getActiveId(), 'osm');
await lease.release();
assert.equal(env.controller.getActiveId(), 'osm');
assert.deepEqual(env.switches, ['esri-imagery', 'osm']);
env.controller.destroy();
});
test('release during acquisition lets no late activation survive', async () => {
const env = leaseFixture();
let resolve;
env.registry.sources.find(
(source) => source.descriptor.id === 'esri-imagery',
).imagery = () =>
new Promise((done) => {
resolve = done;
});
const lease = env.controller.acquireImageryComparison({
owner: 'nepal',
switchPolicy: 'esri',
});
await settle();
const releasing = lease.release();
resolve(env.providers.get('esri-imagery'));
assert.deepEqual(await lease.ready, {
status: 'superseded',
activeId: 'photoreal',
});
await releasing;
await settle();
assert.equal(env.controller.getActiveId(), 'photoreal');
assert.equal(env.viewer.scene.globe.show, false);
assert.equal(env.imagery.length, 0);
assert.equal(env.tileset.show, true);
assert.deepEqual(env.switches, ['esri-imagery', 'photoreal']);
env.controller.destroy();
});
test('release is idempotent and frees the lease for the next owner', async () => {
const env = leaseFixture();
const lease = env.controller.acquireImageryComparison({
owner: 'nepal',
switchPolicy: 'esri',
});
await lease.ready;
const first = lease.release();
assert.equal(lease.release(), first);
await first;
await lease.release();
assert.deepEqual(env.switches, ['esri-imagery', 'photoreal']);
const next = env.controller.acquireImageryComparison({
owner: 'recent',
switchPolicy: 'esri',
});
assert.equal((await next.ready).status, 'ready');
await next.release();
assert.deepEqual(env.switches, [
'esri-imagery',
'photoreal',
'esri-imagery',
'photoreal',
]);
env.controller.destroy();
});
test('an unavailable comparison stack reports failure and release leaves the map alone', async () => {
const env = leaseFixture();
const errors = [];
env.controller._onError = (message) => errors.push(message);
const esri = env.controller._sources.get('esri-imagery');
esri.available = false;
esri.unavailableReason = 'Esri offline';
const lease = env.controller.acquireImageryComparison({
owner: 'nepal',
switchPolicy: 'esri',
});
assert.deepEqual(await lease.ready, {
status: 'failed',
activeId: 'photoreal',
});
await lease.release();
assert.deepEqual(env.switches, ['esri-imagery']);
assert.deepEqual(errors, ['Esri offline']);
assert.equal(env.controller.getActiveId(), 'photoreal');
env.controller.destroy();
});
test('a lease stays owned until its restoration settles, so a rival cannot read the comparison stack as its own', async () => {
const env = leaseFixture();
const lease = env.controller.acquireImageryComparison({
owner: 'recent',
switchPolicy: 'esri-if-photoreal',
});
assert.equal((await lease.ready).activeId, 'esri-imagery');
// Hold the restore switch open: the map is still on Esri while it runs.
const setStack = env.controller.setStack;
let finishRestore;
env.controller.setStack = (id, options) =>
new Promise((resolve) => {
finishRestore = () => resolve(setStack(id, options));
});
const releasing = lease.release();
assert.equal(typeof finishRestore, 'function', 'the restore was issued');
assert.throws(
() =>
env.controller.acquireImageryComparison({
owner: 'nepal',
switchPolicy: 'esri',
}),
/held by recent/,
'the pending restoration still owns the lease',
);
finishRestore();
await releasing;
assert.equal(env.controller.getActiveId(), 'photoreal');
env.controller.setStack = setStack;
const next = env.controller.acquireImageryComparison({
owner: 'nepal',
switchPolicy: 'esri',
});
assert.deepEqual(await next.ready, {
status: 'ready',
activeId: 'esri-imagery',
});
await next.release();
assert.equal(env.controller.getActiveId(), 'photoreal');
assert.deepEqual(env.switches, [
'esri-imagery',
'photoreal',
'esri-imagery',
'photoreal',
]);
env.controller.destroy();
});
test('subscribe hears every settled activation — silent switches, fallbacks and recoveries — until unsubscribed or destroyed', async () => {
const env = publicFixture();
const heard = [];
const off = env.controller.subscribe((state) =>
heard.push([state.activeId, state.status]),
);
assert.equal(typeof off, 'function');
assert.equal(typeof env.controller.subscribe(null), 'function');
await env.controller.setStack('esri-imagery');
assert.deepEqual(heard, [['esri-imagery', 'ready']]);
// A silent switch mutes onChange but not the subscription.
const changesBefore = env.changes.length;
await env.controller.setStack('photoreal', { silent: true });
assert.equal(env.changes.length, changesBefore, 'onChange stays silent');
assert.deepEqual(heard.at(-1), ['photoreal', 'ready']);
// A subscriber that throws does not stop the others.
const noisy = env.controller.subscribe(() => {
throw new Error('listener failed');
});
const warn = console.warn;
const warnings = [];
console.warn = (...args) => warnings.push(args);
try {
await env.controller.setStack('esri-imagery');
} finally {
console.warn = warn;
}
assert.equal(warnings.length, 1);
assert.deepEqual(heard.at(-1), ['esri-imagery', 'ready']);
noisy();
off();
await env.controller.setStack('photoreal');
assert.equal(heard.length, 3, 'unsubscribed listeners hear nothing');
env.controller.destroy();
// A failed activation that recovers still settles once, on the recovery.
const recovering = fixture(
{
defaultId: 'first',
recoveryId: 'recovery',
sources: [
{
descriptor: descriptor('first'),
imagery: async () => {
throw new Error('first offline');
},
},
{ descriptor: descriptor('recovery'), imagery: async () => ({}) },
],
},
{ onError: () => {} },
);
const recovered = [];
recovering.controller.subscribe((state) => recovered.push(state.activeId));
await recovering.controller.setStack('first');
assert.deepEqual(recovered, ['recovery']);
recovering.controller.destroy();
await recovering.controller.setStack('first');
assert.deepEqual(recovered, ['recovery'], 'a destroyed controller is mute');
});
test('each switch generation reports its origin: an outside setStack is manual, a fallback or recovery automatic', async () => {
const env = publicFixture();
const heard = [];
env.controller.subscribe((state) =>
heard.push([state.activeId, state.switchOrigin]),
);
await env.controller.setStack('esri-imagery');
assert.equal(env.controller.getSwitchOrigin(), 'manual');
const generation = env.controller.getSwitchGeneration();
// Two tile failures: the controller falls back to OSM on its own.
const errors = env.providers.get('esri-imagery').errorEvent;
errors.raise();
errors.raise();
await settle();
assert.equal(env.controller.getActiveId(), 'osm');
assert.equal(env.controller.getSwitchGeneration(), generation + 1);
assert.equal(env.controller.getSwitchOrigin(), 'automatic');
assert.equal(env.controller.getState().switchOrigin, 'automatic');
// A silent switch from outside is still the caller's choice.
await env.controller.setStack('photoreal', { silent: true });
assert.equal(env.controller.getSwitchOrigin(), 'manual');
assert.deepEqual(heard, [
['esri-imagery', 'manual'],
['osm', 'automatic'],
['photoreal', 'manual'],
]);
env.controller.destroy();
// A failed activation that recovers settles as automatic.
const recovering = fixture(
{
defaultId: 'first',
recoveryId: 'recovery',
sources: [
{
descriptor: descriptor('first'),
imagery: async () => {
throw new Error('first offline');
},
},
{ descriptor: descriptor('recovery'), imagery: async () => ({}) },
],
},
{ onError: () => {} },
);
const recovered = [];
recovering.controller.subscribe((state) =>
recovered.push([state.activeId, state.switchOrigin]),
);
await recovering.controller.setStack('first');
assert.equal(recovering.controller.getActiveId(), 'recovery');
assert.equal(recovering.controller.getSwitchOrigin(), 'automatic');
await recovering.controller.setStack('recovery');
assert.equal(recovering.controller.getSwitchOrigin(), 'manual');
assert.deepEqual(recovered, [
['recovery', 'automatic'],
['recovery', 'manual'],
]);
recovering.controller.destroy();
});
function failingEsri(env) {
const esri = { failing: true, attempts: 0, next: null };
env.registry.sources.find(
(source) => source.descriptor.id === 'esri-imagery',
).imagery = async () => {
esri.attempts++;
if (esri.next) await esri.next;
if (esri.failing) throw new Error('Esri unreachable');
return env.providers.get('esri-imagery');
};
return esri;
}
const deferred = () => {
let resolve;
const promise = new Promise((done) => (resolve = done));
return { promise, resolve };
};
test('a failed Esri construction shows OSM at once, backs off while retries fail, and recovers in place', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] });
const env = publicFixture();
const esri = failingEsri(env);
await env.controller.setStack('esri-imagery');
assert.equal(env.controller.getActiveId(), 'osm');
const osmLayer = env.imagery.at(-1);
t.mock.timers.tick(30_000);
await settle();
assert.equal(esri.attempts, 2, 'one background retry');
assert.equal(env.imagery.at(-1), osmLayer, 'a failed retry keeps the layer');
await env.controller.setStack('osm');
await env.controller.setStack('esri-imagery');
assert.equal(esri.attempts, 2, 'a reselection does not retry at once');
t.mock.timers.tick(30_000);
await settle();
assert.equal(esri.attempts, 2, 'the second retry waits twice as long');
t.mock.timers.tick(30_000);
await settle();
assert.equal(esri.attempts, 3);
esri.failing = false;
t.mock.timers.tick(120_000);
await settle();
assert.equal(esri.attempts, 4);
assert.equal(env.controller.getActiveId(), 'esri-imagery');
assert.equal(env.controller.getSwitchOrigin(), 'automatic');
assert.equal(env.controller.getState().lastError, null);
assert.equal(env.imagery.at(-1).provider, env.providers.get('esri-imagery'));
t.mock.timers.tick(600_000);
await settle();
assert.equal(esri.attempts, 4, 'the real provider ends the retries');
env.controller.destroy();
});
test('retries of a fallback that keeps failing back off to a 10 minute cap', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] });
const env = publicFixture();
const esri = failingEsri(env);
await env.controller.setStack('esri-imagery');
for (const delay of [30, 60, 120, 240, 480, 600, 600]) {
t.mock.timers.tick(delay * 1000);
await settle();
}
assert.equal(esri.attempts, 8);
env.controller.destroy();
});
test('Esri is retried only while its fallback is shown', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] });
const env = publicFixture();
const esri = failingEsri(env);
await env.controller.setStack('esri-imagery');
await env.controller.setStack('osm');
t.mock.timers.tick(30_000);
await settle();
assert.equal(esri.attempts, 1, 'no retry while OSM was chosen');
await env.controller.setStack('esri-imagery');
assert.equal(esri.attempts, 1, 'the cached fallback shows at once');
assert.equal(env.controller.getActiveId(), 'osm');
esri.failing = false;
t.mock.timers.tick(30_000);
await settle();
assert.equal(esri.attempts, 2);
assert.equal(env.controller.getActiveId(), 'esri-imagery');
env.controller.destroy();
});
test('an Esri recovery that lands mid-switch applies once the switch settles', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] });
const env = publicFixture();
const esri = failingEsri(env);
await env.controller.setStack('esri-imagery');
const retry = deferred();
esri.next = retry.promise;
esri.failing = false;
t.mock.timers.tick(30_000);
await settle();
// The fallback activates OSM's terrain; make that switch slow.
const slow = deferred();
env.registry.sources.find(
(source) => source.descriptor.id === 'osm',
).terrain = { id: 'slow', create: () => slow.promise };
const switching = env.controller.setStack('esri-imagery');
retry.resolve();
await settle();
assert.equal(env.controller.getActiveId(), 'osm', 'the switch is still open');
slow.resolve({ provider: { id: 'slow' } });
await switching;
await settle();
assert.equal(env.controller.getActiveId(), 'esri-imagery');
assert.equal(env.imagery.at(-1).provider, env.providers.get('esri-imagery'));
env.controller.destroy();
});
function terrainFixture(t, create) {
t.mock.timers.enable({ apis: ['setTimeout'] });
let renders = 0;
const env = publicFixture({ requestRender: () => renders++ });
const installed = [];
Object.defineProperty(env.viewer, 'terrainProvider', {
get: () => installed.at(-1),
set: (provider) => installed.push(provider),
});
const terrain = { id: 'keyless', calls: 0 };
terrain.create = () => create(++terrain.calls);
for (const source of env.registry.sources)
if (source.imagery) source.terrain = terrain;
return { env, installed, terrain, renders: () => renders };
}
const flatTerrain = (n) => ({ provider: { id: `flat-${n}` }, fallback: true });
test('flat fallback terrain stays installed while retries run, and real terrain replaces it live', async (t) => {
const real = { id: 'real' };
let working = false;
const { env, installed, terrain, renders } = terrainFixture(t, async (n) =>
working ? { provider: real } : flatTerrain(n),
);
await env.controller.setStack('esri-imagery');
const [flat] = installed;
t.mock.timers.tick(30_000);
await settle();
assert.equal(terrain.calls, 2, 'one background retry');
await env.controller.setStack('osm');
assert.deepEqual(installed, [flat], 'failed retries and switches keep it');
working = true;
const before = renders();
t.mock.timers.tick(60_000);
await settle();
assert.equal(terrain.calls, 3);
assert.deepEqual(installed, [flat, real]);
assert.equal(renders(), before + 1, 'the live swap requests a render');
t.mock.timers.tick(600_000);
await settle();
assert.equal(terrain.calls, 3, 'the real terrain ends the retries');
env.controller.destroy();
});
test('terrain is not retried or installed while a 3D tileset hides the globe', async (t) => {
const real = { id: 'real' };
let working = false;
const { env, installed, terrain } = terrainFixture(t, async (n) =>
working ? { provider: real } : flatTerrain(n),
);
await env.controller.setStack('esri-imagery');
await env.controller.setStack('photoreal');
t.mock.timers.tick(30_000);
await settle();
assert.equal(terrain.calls, 1, 'no retry behind a hidden globe');
await env.controller.setStack('esri-imagery');
const hidden = deferred();
terrain.create = async () => {
terrain.calls++;
await hidden.promise;
return { provider: real };
};
t.mock.timers.tick(30_000);
await settle();
assert.equal(terrain.calls, 2, 'the globe activation re-arms the retry');
await env.controller.setStack('photoreal');
hidden.resolve();
await settle();
assert.equal(installed.length, 1, 'nothing is installed behind a tileset');
await env.controller.setStack('osm');
assert.equal(installed.at(-1), real, 'the next globe activation installs it');
assert.equal(terrain.calls, 2);
env.controller.destroy();
});
test('a switch that read the flat fallback installs the terrain a retry just cached', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] });
// Sweep the microtask distance between the retry landing and the switch.
for (let hops = 0; hops < 12; hops++) {
const real = { id: 'real' },
gate = deferred();
const keyless = {
id: 'keyless',
create: async () => {
if (!keyless.retried) return flatTerrain(1);
await gate.promise;
return { provider: real };
},
};
const other = { id: 'other', create: async () => ({ provider: {} }) };
const source = (id, terrain) => ({
descriptor: descriptor(id),
imagery: async () => ({ id }),
terrain,
});
const env = fixture({
defaultId: 'a',
sources: [source('a', keyless), source('c', other)],
});
const installed = [];
Object.defineProperty(env.viewer, 'terrainProvider', {
get: () => installed.at(-1),
set: (provider) => installed.push(provider),
});
await env.controller.setStack('a');
keyless.retried = true;
t.mock.timers.tick(30_000);
await settle();
await env.controller.setStack('c');
gate.resolve();
for (let i = 0; i < hops; i++) await null;
await env.controller.setStack('a');
await settle();
assert.equal(installed.at(-1), real, `hops ${hops}`);
env.controller.destroy();
}
});
test('destroy cancels a pending retry and releases one in flight', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] });
const env = publicFixture();
const esri = failingEsri(env);
await env.controller.setStack('esri-imagery');
env.controller.destroy();
t.mock.timers.tick(30_000);
await settle();
assert.equal(esri.attempts, 1, 'a pending retry is cancelled');
const late = publicFixture();
const lateEsri = failingEsri(late);
await late.controller.setStack('esri-imagery');
const retry = deferred();
lateEsri.next = retry.promise;
lateEsri.failing = false;
let destroyed = 0;
late.providers.get('esri-imagery').destroy = () => destroyed++;
t.mock.timers.tick(30_000);
await settle();
late.controller.destroy();
retry.resolve();
await settle();
assert.equal(destroyed, 1, 'a late provider is released');
assert.equal(late.imagery.length, 0);
t.mock.timers.tick(600_000);
await settle();
assert.equal(lateEsri.attempts, 2);
});
test('retries stay single-flight when an activation re-shows the fallback mid-retry', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] });
const env = publicFixture();
const created = [],
pending = [];
let attempts = 0;
env.registry.sources.find(
(source) => source.descriptor.id === 'esri-imagery',
).imagery = async () => {
if (++attempts === 1) throw new Error('Esri unreachable');
const gate = deferred();
pending.push(gate);
await gate.promise;
const provider = { id: `esri-${attempts}`, errorEvent: event() };
provider.destroy = () => (provider.destroyed = true);
created.push(provider);
return provider;
};
await env.controller.setStack('esri-imagery');
t.mock.timers.tick(30_000);
await settle();
assert.equal(attempts, 2, 'retry #1 is in flight');
await env.controller.setStack('osm');
await env.controller.setStack('esri-imagery');
assert.equal(env.controller.getActiveId(), 'osm', 'the fallback is shown');
t.mock.timers.tick(30_000);
await settle();
assert.equal(attempts, 2, 'no second retry while one is in flight');
for (const gate of pending.reverse()) {
gate.resolve();
await settle();
}
const shown = env.imagery.at(-1).provider;
assert.equal(env.controller.getActiveId(), 'esri-imagery');
await env.controller.setStack('osm');
await env.controller.setStack('esri-imagery');
assert.equal(env.imagery.at(-1).provider, shown, 'the cached one is shown');
env.controller.destroy();
await settle();
assert.ok(created.length > 0);
for (const provider of created)
assert.equal(provider.destroyed, true, `${provider.id} is disposed`);
});
test('a stalled terrain retry does not hold back recovered imagery', async (t) => {
const stalled = deferred();
const { env, terrain } = terrainFixture(t, async (n) => {
if (n > 1) await stalled.promise;
return flatTerrain(n);
});
const esri = failingEsri(env);
await env.controller.setStack('esri-imagery');
assert.equal(env.controller.getActiveId(), 'osm');
esri.failing = false;
t.mock.timers.tick(30_000);
await settle();
assert.equal(terrain.calls, 2, 'the terrain retry is in flight');
assert.equal(env.controller.getActiveId(), 'esri-imagery');
assert.equal(env.imagery.at(-1).provider, env.providers.get('esri-imagery'));
stalled.resolve();
await settle();
env.controller.destroy();
});
test('a stalled imagery retry does not hold back recovered terrain', async (t) => {
const real = { id: 'real' };
const { env, installed } = terrainFixture(t, async (n) =>
n > 1 ? { provider: real } : flatTerrain(n),
);
const esri = failingEsri(env);
await env.controller.setStack('esri-imagery');
const stalled = deferred();
esri.next = stalled.promise;
t.mock.timers.tick(30_000);
await settle();
assert.equal(esri.attempts, 2, 'the imagery retry is in flight');
assert.equal(installed.at(-1), real, 'real terrain is installed');
stalled.resolve();
await settle();
env.controller.destroy();
});
test('a retry attempt that never settles is abandoned at its deadline and released if it lands late', async (t) => {
const hung = deferred();
const late = { id: 'late', destroy: () => (late.destroyed = true) };
const { env, installed, terrain } = terrainFixture(t, async (n) => {
if (n === 2) await hung.promise;
return n === 2 ? { provider: late } : flatTerrain(n);
});
const esri = failingEsri(env);
await env.controller.setStack('esri-imagery');
t.mock.timers.tick(30_000);
await settle();
assert.equal(esri.attempts, 2, 'imagery failed');
assert.equal(terrain.calls, 2, 'terrain hangs');
t.mock.timers.tick(60_000); // The hung attempt's deadline.
await settle();
t.mock.timers.tick(60_000); // The doubled backoff.
await settle();
assert.equal(esri.attempts, 3, 'imagery is retried again');
assert.equal(terrain.calls, 3, 'terrain is retried again');
hung.resolve();
await settle();
assert.equal(late.destroyed, true, 'the late provider is released');
assert.ok(!installed.includes(late), 'and never installed');
env.controller.destroy();
});
test('a failed retry after a mid-retry re-show re-arms once, after the doubled delay', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] });
const env = publicFixture();
const esri = failingEsri(env);
await env.controller.setStack('esri-imagery');
const gate = deferred();
esri.next = gate.promise;
t.mock.timers.tick(30_000);
await settle();
await env.controller.setStack('osm');
await env.controller.setStack('esri-imagery');
gate.resolve();
await settle();
assert.equal(esri.attempts, 2);
t.mock.timers.tick(59_999);
await settle();
assert.equal(esri.attempts, 2, 'not before the doubled delay');
t.mock.timers.tick(1);
await settle();
assert.equal(esri.attempts, 3, 'one retry after it');
t.mock.timers.tick(119_999);
await settle();
assert.equal(esri.attempts, 3, 'no second timer was armed');
env.controller.destroy();
});
test('destroy releases recovered imagery and terrain that lands afterwards', async (t) => {
const stalled = deferred();
const real = { id: 'real', destroy: () => (real.destroyed = true) };
const { env, installed } = terrainFixture(t, async (n) => {
if (n === 1) return flatTerrain(n);
await stalled.promise;
return { provider: real };
});
const esri = failingEsri(env);
const imagery = env.providers.get('esri-imagery');
imagery.destroy = () => (imagery.destroyed = true);
await env.controller.setStack('esri-imagery');
esri.failing = false;
t.mock.timers.tick(30_000);
await settle();
assert.equal(env.imagery.at(-1).provider, imagery, 'imagery has landed');
env.controller.destroy();
stalled.resolve();
await settle();
assert.equal(imagery.destroyed, true);
assert.equal(real.destroyed, true);
assert.ok(!installed.includes(real));
});
function liveTimers(t) {
const live = new Set();
const { setTimeout: set, clearTimeout: clear } = globalThis;
globalThis.setTimeout = (fn, ms, ...args) => {
const id = set(
(...values) => {
live.delete(id);
fn(...values);
},
ms,
...args,
);
live.add(id);
return id;
};
globalThis.clearTimeout = (id) => {
live.delete(id);
clear(id);
};
t.after(() =>
Object.assign(globalThis, { setTimeout: set, clearTimeout: clear }),
);
return live;
}
test('destroy during a hung retry attempt clears its deadline at once', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] });
const live = liveTimers(t);
const env = publicFixture();
const esri = failingEsri(env);
await env.controller.setStack('esri-imagery');
esri.next = new Promise(() => {});
t.mock.timers.tick(30_000);
await settle();
assert.equal(esri.attempts, 2, 'the attempt hangs');
assert.equal(live.size, 1, 'only its deadline is armed');
env.controller.destroy();
assert.equal(live.size, 0, 'destroy clears the deadline');
assert.equal(env.controller._retrying, false);
await settle();
assert.equal(live.size, 0, 'and nothing re-arms');
});
function destroyableFlat(n) {
const provider = { id: `flat-${n}` };
provider.destroy = () => (provider.destroyed = true);
return { provider, fallback: true };
}
test('terrain recovered on screen releases the fallback it replaced', async (t) => {
const real = { id: 'real' };
let flat;
const { env, installed } = terrainFixture(t, async (n) =>
n === 1 ? (flat = destroyableFlat(n)) : { provider: real },
);
await env.controller.setStack('esri-imagery');
t.mock.timers.tick(30_000);
await settle();
assert.equal(installed.at(-1), real);
assert.equal(flat.provider.destroyed, true);
env.controller.destroy();
});
test('terrain recovered behind a tileset releases the fallback once a globe replaces it', async (t) => {
const real = { id: 'real' };
const gate = deferred();
let flat;
const { env, installed } = terrainFixture(t, async (n) => {
if (n === 1) return (flat = destroyableFlat(n));
await gate.promise;
return { provider: real };
});
await env.controller.setStack('esri-imagery');
t.mock.timers.tick(30_000);
await settle();
await env.controller.setStack('photoreal');
gate.resolve();
await settle();
assert.equal(installed.at(-1), flat.provider);
assert.ok(!flat.provider.destroyed, 'still installed behind the tileset');
await env.controller.setStack('osm');
assert.equal(installed.at(-1), real);
assert.equal(flat.provider.destroyed, true);
env.controller.destroy();
});
test('a hung imagery attempt that lands after its deadline is released, never cached or shown', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] });
const env = publicFixture();
const hung = deferred();
const late = { id: 'late', errorEvent: event() };
const good = { id: 'good', errorEvent: event() };
for (const provider of [late, good])
provider.destroy = () => (provider.destroyed = true);
let attempts = 0;
env.registry.sources.find(
(source) => source.descriptor.id === 'esri-imagery',
).imagery = async () => {
if (++attempts === 1) throw new Error('Esri unreachable');
if (attempts === 2) {
await hung.promise;
return late;
}
return good;
};
await env.controller.setStack('esri-imagery');
t.mock.timers.tick(30_000);
await settle();
t.mock.timers.tick(60_000); // The deadline.
await settle();
hung.resolve();
await settle();
assert.equal(late.destroyed, true, 'the late provider is released');
assert.equal(env.controller.getActiveId(), 'osm', 'and not shown');
t.mock.timers.tick(60_000);
await settle();
assert.equal(attempts, 3);
assert.equal(env.imagery.at(-1).provider, good, 'the next retry installs');
await env.controller.setStack('osm');
await env.controller.setStack('esri-imagery');
assert.equal(env.imagery.at(-1).provider, good, 'only its own is cached');
env.controller.destroy();
await settle();
assert.equal(good.destroyed, true);
});