Files
gods-eye-view/src/sources/vectorTiles.js
T
manjunath 2e82425d62 address review findings on voice outlines
- remove the unused Nominatim reserve(); spacing tests now measure the
  actual transport start across processes
- start each queued building's 2 s ground-sampling budget when it
  reaches the head of the queue, and request a frame on promotion
- accept Nominatim and grounds outlines that cross the antimeridian
- let an unnamed school, university, hospital, cemetery, stadium or zoo
  area answer a grounds ask whose head noun names that kind, using only
  the part that holds the point; compare grounds names symmetrically
- charge shared OpenFreeMap consumers their own slice and keep the
  charged budget at the previous 64 MiB
- share one place-name fold, point-in-polygon, line stitching and
  nextTask helper instead of duplicates
- exclude Who's On First sources licensed only as "CC BY (equivalent)"
  or "CC0 (equivalent)"; rebuild the pack from the pinned archives
- whole-word neighbourhood alias guard; correct the outline size-limit
  comment
- restore DATA_SOURCES.md table formatting, keeping only real edits
- test behaviour instead of private engine fields
2026-10-30 20:47:20 +05:30

636 lines
20 KiB
JavaScript

import { phaseTiming } from './phaseTiming.js';
import { tilesForBounds } from '../data/tomtomTiles.js';
import { readResponseBytesCapped, readResponseJsonCapped } from './httpBody.js';
// Marks text for i18n extraction; the UI translates these failures where it
// shows them (layer row, loading chip). Kept local because AI tool services
// import this module outside the browser.
const msg = (text) => text;
/** Validate a non-dateline geographic viewport before selecting a bounded grid. */
export function validTileBounds(box) {
return (
box &&
[box.south, box.west, box.north, box.east].every(Number.isFinite) &&
box.south >= -90 &&
box.north <= 90 &&
box.west >= -180 &&
box.east <= 180 &&
box.north > box.south &&
box.east > box.west
);
}
/**
* The origin a configured TileJSON is served from, or undefined when there is
* no absolute URL to read one off. Deriving `allowedOrigin` from it means
* repointing `tileJsonUrl` at a mirror cannot silently keep loading tiles from
* the old host: the origin check below then names the mismatch instead of
* passing it (#933).
*/
function tileJsonOrigin(tileJsonUrl) {
if (typeof tileJsonUrl !== 'string') return undefined;
try {
return new URL(tileJsonUrl).origin;
} catch {
return undefined;
}
}
const DECODER_IDS = new WeakMap();
let nextDecoderId = 1;
/** Give the page a turn; shared completion must not run every consumer's selection in one task. */
export const nextTask = () =>
globalThis.scheduler?.yield
? globalThis.scheduler.yield()
: new Promise((resolve) => setTimeout(resolve, 0));
function sharedDecoderKey(decode) {
let id = DECODER_IDS.get(decode);
if (!id) {
id = nextDecoderId++;
DECODER_IDS.set(decode, id);
}
return id;
}
/**
* Bounded decoded ownership shared by compatible vector-tile consumers.
* Entries are keyed by decoder identity, immutable tile template and XYZ;
* callers still keep their own consumer-shaped caches and request lifetimes.
*/
export function createSharedDecodedTileCache({
maxEntries = 192,
maxCacheBytes = 64 * 1024 * 1024,
} = {}) {
const cache = new Map();
const flights = new Map();
let cacheBytes = 0;
let generation = 0;
const release = (entry) => {
if (!entry || entry.released) return;
entry.released = true;
entry.value?.releaseSharedCacheEntry?.();
};
const remove = (key, expected = null) => {
const entry = cache.get(key);
if (!entry || (expected && entry !== expected)) return false;
cache.delete(key);
cacheBytes -= entry.size;
release(entry);
return true;
};
const evict = () => {
while (cache.size > maxEntries || cacheBytes > maxCacheBytes) {
remove(cache.keys().next().value);
}
};
const resize = (key, value, entry, size) => {
if (!Number.isFinite(size) || size < 0) return;
const previousSize = entry.size;
entry.size = size;
if (cache.get(key) !== entry || entry.value !== value) return;
cacheBytes += size - previousSize;
evict();
};
const store = (key, value, size) => {
const entry = { value, size, released: false };
if (!Number.isFinite(size) || size < 0 || size > maxCacheBytes)
return entry;
remove(key);
cache.set(key, entry);
cacheBytes += size;
try {
value?.bindSharedCacheEntry?.(
(nextSize) => resize(key, value, entry, nextSize),
size,
);
} catch (error) {
remove(key, entry);
throw error;
}
evict();
return entry;
};
const subscribe = (flight, signal, key) => {
signal?.throwIfAborted();
flight.users += 1;
return new Promise((resolve, reject) => {
const abort = () => reject(signal.reason);
signal?.addEventListener('abort', abort, { once: true });
flight.promise
.then(resolve, reject)
.finally(() => signal?.removeEventListener('abort', abort));
}).finally(() => {
flight.users -= 1;
if (!flight.users && flights.get(key) === flight) {
flights.delete(key);
flight.controller.abort();
}
});
};
return {
get(key) {
const hit = cache.get(key);
if (!hit) return null;
cache.delete(key);
cache.set(key, hit);
return hit;
},
set(key, value, size) {
return store(key, value, size);
},
load(key, signal, loader) {
const hit = this.get(key);
if (hit) return Promise.resolve(hit);
let flight = flights.get(key);
if (!flight) {
flight = {
controller: new AbortController(),
users: 0,
promise: null,
generation,
};
flights.set(key, flight);
flight.promise = Promise.resolve()
.then(() => loader(flight.controller.signal))
.then(({ value, size }) => {
flight.controller.signal.throwIfAborted();
if (flight.generation !== generation)
throw new DOMException('Shared tile cache cleared', 'AbortError');
return store(key, value, size);
})
.finally(() => {
if (flights.get(key) === flight) flights.delete(key);
});
}
return subscribe(flight, signal, key);
},
clear() {
generation += 1;
for (const flight of flights.values()) flight.controller.abort();
flights.clear();
for (const entry of cache.values()) release(entry);
cache.clear();
cacheBytes = 0;
},
stats: () => ({ entries: cache.size, bytes: cacheBytes }),
};
}
/** A decoded XYZ cache with bounded workers, reads, retained bytes and request lifetimes. */
export function createVectorTileSource({
tileJsonUrl,
template,
allowedOrigin = tileJsonOrigin(tileJsonUrl),
decode,
fetchImpl = (...args) => globalThis.fetch(...args),
maxTiles = 16,
concurrency = 4,
ttlMs = Infinity,
maxEntries = 64,
maxCacheBytes = 24 * 1024 * 1024,
maxResponseBytes = 4 * 1024 * 1024,
metadataCooldownMs = 5000,
now = Date.now,
sharedDecodedCache = null,
selectDecoded = (value) => value,
selectedSize = null,
}) {
const cache = new Map();
const active = new Set();
const flights = new Map();
let cacheBytes = 0;
let metadata = null;
let metadataError = null;
let metadataFlight = null;
let metadataRetryAt = 0;
let generation = 0;
let fetched = 0;
let activeWorkers = 0;
const waiters = [];
async function request(url, parentSignal, read, trackAsSource = true) {
const controller = new AbortController();
const abort = () => controller.abort(parentSignal?.reason);
parentSignal?.throwIfAborted();
parentSignal?.addEventListener('abort', abort, { once: true });
if (trackAsSource) active.add(controller);
const timer = setTimeout(
() =>
controller.abort(
new DOMException(
msg('Vector tile request timed out'),
'TimeoutError',
),
),
12_000,
);
let response;
try {
response = await fetchImpl(url, {
signal: controller.signal,
redirect: 'error',
});
if (!response.ok) {
const status = Number.isFinite(response.status)
? response.status
: null;
throw Object.assign(
new Error(
status === null
? msg('Vector tiles unavailable')
: // Shown through the 'Vector tiles unavailable (HTTP {status})' key.
`Vector tiles unavailable (HTTP ${status})`,
),
{ status },
);
}
const value = await read(response, controller.signal);
controller.signal.throwIfAborted();
return value;
} catch (error) {
// Retain request ownership until every failed read has been cancelled.
controller.abort(error);
await response?.body?.cancel().catch(() => {});
throw error;
} finally {
clearTimeout(timer);
parentSignal?.removeEventListener('abort', abort);
if (trackAsSource) active.delete(controller);
}
}
async function getMetadata(signal) {
signal?.throwIfAborted();
if (metadata) return metadata;
if (metadataError && (!metadataError.retryable || now() < metadataRetryAt))
throw metadataError;
metadataError = null;
if (!metadataFlight) {
const flight = {
controller: new AbortController(),
users: 0,
promise: null,
};
const metadataStart = performance.now();
metadataFlight = flight;
flight.promise = (
template
? Promise.resolve({ tiles: [template] })
: request(
tileJsonUrl,
flight.controller.signal,
(res, requestSignal) =>
readResponseJsonCapped(res, 256 * 1024, requestSignal),
)
)
.then((value) => {
flight.controller.signal.throwIfAborted();
const url = value?.tiles?.[0];
if (
typeof url !== 'string' ||
!['{z}', '{x}', '{y}'].every((token) => url.includes(token))
)
throw Object.assign(new Error('Invalid vector tile metadata'), {
retryable: false,
});
let parsed;
try {
parsed = new URL(
url.replace('{z}', '0').replace('{x}', '0').replace('{y}', '0'),
allowedOrigin,
);
} catch {
throw Object.assign(new Error('Invalid vector tile origin'), {
retryable: false,
});
}
if (
parsed.origin !== allowedOrigin ||
parsed.username ||
parsed.password
)
throw Object.assign(new Error('Invalid vector tile origin'), {
retryable: false,
});
if (!template)
phaseTiming('tilejson-fetch', metadataStart, {
source: allowedOrigin,
});
metadata = { ...value, template: url };
return metadata;
})
.catch((error) => {
if (flight.controller.signal.aborted || error.name === 'AbortError')
throw error;
metadataError = Object.assign(
new Error(msg('Vector tile metadata unavailable'), {
cause: error,
}),
{
status: error.status ?? null,
name: error.name === 'TimeoutError' ? 'TimeoutError' : 'Error',
retryable:
error.retryable !== false && !(error instanceof SyntaxError),
},
);
metadataRetryAt =
now() + Math.min(30_000, Math.max(0, metadataCooldownMs));
throw metadataError;
})
.finally(() => {
if (metadataFlight === flight) metadataFlight = null;
});
}
const flight = metadataFlight;
flight.users += 1;
return new Promise((resolve, reject) => {
const abort = () => reject(signal.reason);
signal?.addEventListener('abort', abort, { once: true });
const cleanup = () => signal?.removeEventListener('abort', abort);
flight.promise.then(
(value) => {
cleanup();
resolve(value);
},
(error) => {
cleanup();
reject(error);
},
);
}).finally(() => {
// Each caller owns its wait; only the last departing caller cancels shared metadata.
flight.users -= 1;
if (!flight.users && metadataFlight === flight) {
flight.controller.abort();
metadataFlight = null;
}
});
}
async function acquire(signal) {
signal?.throwIfAborted();
if (activeWorkers >= concurrency) {
await new Promise((resolve, reject) => {
const waiter = {
resolve: () => {
signal?.removeEventListener('abort', abort);
resolve();
},
};
const abort = () => {
const i = waiters.indexOf(waiter);
if (i >= 0) waiters.splice(i, 1);
reject(signal.reason);
};
signal?.addEventListener('abort', abort, { once: true });
waiters.push(waiter);
});
} else activeWorkers += 1;
}
function release() {
const waiter = waiters.shift();
if (waiter) waiter.resolve();
else activeWorkers -= 1;
}
function subscribe(flight, signal, key) {
signal?.throwIfAborted();
flight.users++;
return new Promise((resolve, reject) => {
const abort = () => reject(signal.reason);
signal?.addEventListener('abort', abort, { once: true });
flight.promise
.then(resolve, reject)
.finally(() => signal?.removeEventListener('abort', abort));
}).finally(() => {
if (--flight.users === 0 && flights.get(key) === flight) {
flights.delete(key);
flight.controller.abort();
}
});
}
async function getTile(tile, meta, signal, epoch) {
signal?.throwIfAborted();
if (epoch !== generation)
throw new DOMException('Source cleared', 'AbortError');
const key = `${meta.template}:${tile.z}/${tile.x}/${tile.y}`;
const sharedKey = `${sharedDecoderKey(decode)}:${key}`;
const hit = cache.get(key);
if (hit && now() - hit.at < ttlMs) {
cache.delete(key);
cache.set(key, hit);
return hit.value;
}
if (hit) {
cache.delete(key);
cacheBytes -= hit.size;
}
const loadDecoded = async (ownedSignal, sharedOwnership = false) => {
await acquire(ownedSignal);
try {
ownedSignal.throwIfAborted();
fetched++;
const url = meta.template
.replace('{z}', tile.z)
.replace('{x}', tile.x)
.replace('{y}', tile.y);
const fetchStart = performance.now();
const bytes = await request(
url,
ownedSignal,
async (res, requestSignal) => {
const bodyStart = performance.now();
const value = await readResponseBytesCapped(
res,
maxResponseBytes,
requestSignal,
);
phaseTiming('tile-body-read', bodyStart, {
source: allowedOrigin,
key,
bytes: value.byteLength,
});
return value;
},
!sharedOwnership,
);
phaseTiming('tile-fetch', fetchStart, {
source: allowedOrigin,
key,
bytes: bytes.byteLength,
});
const decodeStart = performance.now();
const decoded = decode(bytes, tile.z, tile.x, tile.y);
phaseTiming('decode', decodeStart, { source: allowedOrigin, key });
ownedSignal.throwIfAborted();
// Body-based decoded-storage estimate; projections may increase it.
return { value: decoded, size: bytes.byteLength * 4 };
} finally {
release();
}
};
let flight = flights.get(key);
if (!flight) {
flight = { controller: new AbortController(), users: 0 };
const ownedSignal = flight.controller.signal;
flights.set(key, flight);
flight.promise = (async () => {
const decodedEntry = sharedDecodedCache
? await sharedDecodedCache.load(
sharedKey,
ownedSignal,
(sharedSignal) => loadDecoded(sharedSignal, true),
)
: await loadDecoded(ownedSignal);
ownedSignal.throwIfAborted();
if (sharedDecodedCache) {
await nextTask();
ownedSignal.throwIfAborted();
if (epoch !== generation)
throw new DOMException('Source cleared', 'AbortError');
}
const selected = selectDecoded(decodedEntry.value, tile);
// Shared entries stay authoritative; consumers own their nested arrays.
const value = sharedDecodedCache ? structuredClone(selected) : selected;
// A consumer of a shared tile retains only its own slice; charge that,
// not the whole decoded tile, which the shared cache already counts.
let size = decodedEntry.size;
if (sharedDecodedCache && selectedSize) {
try {
size = selectedSize(value);
} catch {
size = decodedEntry.size;
}
}
if (epoch === generation && size <= maxCacheBytes) {
if (cache.has(key)) cacheBytes -= cache.get(key).size;
cache.delete(key);
cache.set(key, { at: now(), value, size });
cacheBytes += size;
while (cache.size > maxEntries || cacheBytes > maxCacheBytes) {
const oldest = cache.keys().next().value;
cacheBytes -= cache.get(oldest).size;
cache.delete(oldest);
}
}
return value;
})().finally(() => {
if (flights.get(key) === flight) flights.delete(key);
});
}
return subscribe(flight, signal, key);
}
return {
getMetadata,
async fetchBounds(
box,
{ zoom, signal, onTile, tiles: selectedTiles } = {},
) {
if (
!validTileBounds(box) ||
!Number.isInteger(zoom) ||
zoom < 0 ||
zoom > 14
)
throw new TypeError('Invalid tile viewport');
signal?.throwIfAborted();
const epoch = generation;
const metaStart = performance.now();
const meta = await getMetadata(signal);
phaseTiming('tilejson', metaStart, { source: allowedOrigin });
const candidates = selectedTiles
? selectedTiles.slice()
: tilesForBounds(box, zoom, { maxTiles: maxTiles + 1 });
if (
candidates.some(
(t) =>
t.z !== zoom ||
!Number.isInteger(t.x) ||
!Number.isInteger(t.y) ||
t.x < 0 ||
t.y < 0 ||
t.x >= 2 ** zoom ||
t.y >= 2 ** zoom,
)
)
throw new TypeError('Invalid tile selection');
const cx = candidates.reduce((n, t) => n + t.x, 0) / candidates.length;
const cy = candidates.reduce((n, t) => n + t.y, 0) / candidates.length;
if (!selectedTiles)
candidates.sort(
(a, b) =>
Math.hypot(a.x - cx, a.y - cy) - Math.hypot(b.x - cx, b.y - cy),
);
const limited = candidates.length > maxTiles;
// Refuse over-wide views instead of silently sampling a northwest strip.
if (limited)
throw Object.assign(
new Error(msg('Zoom in for vector tile coverage')),
{
retryable: false,
code: 'TILE_VIEW_TOO_WIDE',
},
);
let index = 0;
const results = new Array(candidates.length);
await Promise.all(
Array.from(
{ length: Math.min(concurrency, candidates.length) },
async () => {
while (index < candidates.length) {
const i = index++;
try {
results[i] = {
value: await getTile(candidates[i], meta, signal, epoch),
tile: candidates[i],
};
signal?.throwIfAborted();
onTile?.(results[i].value, candidates[i]);
} catch (error) {
results[i] = { error };
}
}
},
),
);
signal?.throwIfAborted();
if (epoch !== generation)
throw new DOMException('Source cleared', 'AbortError');
const good = results.filter((result) => !result.error);
if (!good.length && results.length) throw results[0].error;
return {
tiles: good.map((result) => result.value),
loadedTiles: good.map((result) => result.tile),
partial: good.length !== results.length,
limited,
};
},
getStats: () => ({
tilesFetched: fetched,
cacheEntries: cache.size,
cacheBytes,
}),
clear() {
generation += 1;
metadataFlight?.controller.abort();
metadataFlight = null;
metadata = null;
metadataError = null;
metadataRetryAt = 0;
for (const flight of flights.values()) flight.controller.abort();
flights.clear();
for (const controller of active) controller.abort();
cache.clear();
cacheBytes = 0;
},
};
}