Files
gods-eye-view/src/layers/streetLevel/providers/panoramax/source.js
T
German KhokhlovandClaude Opus 5.5 7fd1dd867f Merge origin/main: Panoramax, bikeshare Norway/Detroit, cloud filter strength, Overpass cache
Conflicts:
- KartaView viewer moved into the shared photoViewer.js on main; its
  labels now take the provider name ("{name} street-level photo") and
  are translated there.
- Weather: main's cloud filter strength slider, with its labels in t().
- Street Level caption: translated creator line plus main's licence.

Panoramax status and error texts are marked like KartaView's, and
"Panoramax answered HTTP {status}" gets a template in the panel and the
layer row. Catalogs: es/ru 2553 messages each, complete.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-16 00:06:45 +04:00

307 lines
11 KiB
JavaScript

import { createLimiter } from '../../limiter.js';
import { msg } from '../../../../i18n/index.js';
import {
API_CONCURRENCY,
API_TIMEOUT_MS,
BUSY_BACKOFF_BASE_SEC,
MAX_RESPONSE_BYTES,
NEAREST_BOX_LIMIT,
NEAREST_FOV_TOLERANCE_DEG,
NEAREST_LIMIT,
NEAREST_RADIUS_M,
PANORAMAX_API,
PICTURE_TILE_CONCURRENCY,
STREAM_IDLE_TIMEOUT_MS,
TILE_CONCURRENCY,
TILE_TIMEOUT_MS,
} from './policy.js';
/** Longest wait a Retry-After (or the backoff) asks for. */
const RETRY_AFTER_MAX_SEC = 300;
/** An HTTP or API failure; `retryAfterSec` is set while Panoramax is busy. */
export class PanoramaxSourceError extends Error {
constructor(message, { status = 0, retryAfterSec = null } = {}) {
super(message);
this.name = 'PanoramaxSourceError';
this.status = status;
this.retryAfterSec = retryAfterSec;
}
}
const NO_ANSWER = msg('Panoramax did not answer in time — try again');
const UNREACHABLE = msg(
'Panoramax could not be reached — check the connection',
);
/**
* Seconds from a Retry-After header (delay seconds or an HTTP date), or
* null. The meta-catalogue exposes no headers to the browser, so in the
* app this is usually null and the caller backs off on its own.
*/
export function retryAfterSeconds(response, now = Date.now()) {
const header = response.headers?.get?.('retry-after');
if (header == null || header === '') return null;
let value = Number(header);
if (!Number.isFinite(value)) {
const at = Date.parse(header);
if (!Number.isFinite(at)) return null;
value = Math.ceil((at - now) / 1000);
}
if (value < 0) return null;
// A maintenance page's hour must not freeze coverage for an hour.
return Math.min(RETRY_AFTER_MAX_SEC, Math.max(1, value));
}
/**
* The body as bytes, refusing more than MAX_RESPONSE_BYTES whatever the
* headers say. `onChunk` hears each piece arrive (the idle timeout).
*/
async function readBounded(response, onChunk = () => {}) {
const tooMuch = () =>
new PanoramaxSourceError(msg('Panoramax sent too much data'), {
status: response.status,
});
const length = Number(response.headers?.get?.('content-length'));
if (length > MAX_RESPONSE_BYTES) throw tooMuch();
const reader = response.body?.getReader?.();
if (!reader) {
const bytes = new Uint8Array(await response.arrayBuffer());
if (bytes.byteLength > MAX_RESPONSE_BYTES) throw tooMuch();
return bytes;
}
const chunks = [];
let total = 0;
for (;;) {
const { done, value } = await reader.read();
if (done) break;
onChunk();
total += value.byteLength;
if (total > MAX_RESPONSE_BYTES) {
reader.cancel().catch(() => {});
throw tooMuch();
}
chunks.push(value);
}
const body = new Uint8Array(total);
let offset = 0;
for (const chunk of chunks) {
body.set(chunk, offset);
offset += chunk.byteLength;
}
return body;
}
/**
* Every network path the Panoramax provider uses, browser-side and keyless:
* the meta-catalogue allows any origin. Vector tiles for coverage and
* cones, STAC search for single pictures and nearest ones.
* @param {{fetchImpl?: typeof fetch, api?: string}} [options]
*/
export function createPanoramaxSource({
fetchImpl = (...args) => globalThis.fetch(...args),
api = PANORAMAX_API,
} = {}) {
const root = api.replace(/\/+$/, '');
const apiLimiter = createLimiter(API_CONCURRENCY, { lifo: true });
const tileLimiter = createLimiter(TILE_CONCURRENCY);
// The cones' z15 tiles have their own connection: a selection never
// waits behind coverage tiles.
const pictureLimiter = createLimiter(PICTURE_TILE_CONCURRENCY, {
lifo: true,
});
/** Busy answers in a row with no readable Retry-After (the backoff grows). */
let busyStreak = 0;
/**
* GET: its headers within `timeoutMs`, then a body that may take as long
* as it keeps arriving (silent for STREAM_IDLE_TIMEOUT_MS is given up).
* The caller's abort wins over both.
*/
async function get(url, { signal, timeoutMs, empty = [] }) {
const controller = new AbortController();
const onAbort = () => controller.abort(signal.reason);
if (signal?.aborted) throw signal.reason;
signal?.addEventListener('abort', onAbort, { once: true });
const giveUp = () => controller.abort(new PanoramaxSourceError(NO_ANSWER));
let timer = setTimeout(giveUp, timeoutMs);
try {
const response = await fetchImpl(url, { signal: controller.signal });
if (empty.includes(response.status)) {
busyStreak = 0;
return null;
}
if (response.status === 429 || response.status === 503) {
const told = retryAfterSeconds(response);
// Not told how long: back off, longer each time (5, 10, 20… 300 s).
const wait =
told ??
Math.min(
RETRY_AFTER_MAX_SEC,
BUSY_BACKOFF_BASE_SEC * 2 ** Math.min(busyStreak, 8),
);
busyStreak++;
throw new PanoramaxSourceError(msg('Panoramax is busy'), {
status: response.status,
retryAfterSec: wait,
});
}
if (!response.ok)
throw new PanoramaxSourceError(
`Panoramax answered HTTP ${response.status}`,
{ status: response.status },
);
busyStreak = 0;
// The answer has begun: from here only silence is timed.
clearTimeout(timer);
timer = setTimeout(giveUp, STREAM_IDLE_TIMEOUT_MS);
return await readBounded(response, () => {
clearTimeout(timer);
timer = setTimeout(giveUp, STREAM_IDLE_TIMEOUT_MS);
});
} catch (error) {
if (signal?.aborted) throw signal.reason;
if (controller.signal.aborted) throw controller.signal.reason;
if (error instanceof PanoramaxSourceError) throw error;
// Offline, or a CORS or TLS failure: not a timeout, not worth a retry.
throw new PanoramaxSourceError(UNREACHABLE);
} finally {
clearTimeout(timer);
signal?.removeEventListener('abort', onAbort);
}
}
/**
* A STAC search, through the API gate (newest request first). One that
* timed out is asked once more: a search is quick once the connection
* is free.
*/
async function search(params, { signal } = {}) {
const url = `${root}/search?${new URLSearchParams(params)}`;
const once = () =>
apiLimiter.run(() => get(url, { signal, timeoutMs: API_TIMEOUT_MS }), {
signal,
});
let bytes;
try {
bytes = await once();
} catch (error) {
if (signal?.aborted || error?.message !== NO_ANSWER) throw error;
bytes = await once();
}
let payload;
try {
payload = JSON.parse(new TextDecoder().decode(bytes));
} catch {
throw new PanoramaxSourceError(
msg('Panoramax sent an unreadable answer'),
);
}
return Array.isArray(payload?.features) ? payload.features : [];
}
return {
api: root,
/** Raw vector-tile bytes; an empty array where there is no coverage. */
async getTile({ x, y, z }, { signal, lane = 'coverage' } = {}) {
const url = `${root}/map/${z}/${x}/${y}.mvt`;
const gate = lane === 'pictures' ? pictureLimiter : tileLimiter;
const bytes = await gate.run(
() =>
get(url, { signal, timeoutMs: TILE_TIMEOUT_MS, empty: [204, 404] }),
{ signal },
);
return bytes ?? new Uint8Array(0);
},
/** One picture (a STAC item) by id, or null. */
async getItem(id, { signal } = {}) {
const [item] = await search({ ids: String(id), limit: '1' }, { signal });
return item && String(item.id) === String(id) ? item : null;
},
/**
* Pictures within `radius` metres of a point, unranked: the caller ranks
* them by distance. Two searches side by side, since neither finds them
* all: `place_position` (nearest first) leaves out pictures looking
* away from the point, whatever the tolerance; a bounding box has them,
* roughly nearest first (not exactly: the caller ranks the union).
* `collections` keeps one sequence's, `pano` and `sinceMs` filter as
* the imagery filter does.
*/
async nearestItems(
{
lat,
lon,
radius = NEAREST_RADIUS_M,
limit = NEAREST_LIMIT,
collections = null,
pano = 'all',
sinceMs = null,
},
{ signal } = {},
) {
const metres = Math.min(1000, Math.max(1, Math.round(radius)));
const shared = {};
if (collections) shared.collections = String(collections);
if (pano === 'pano') shared.filter = 'field_of_view=360';
else if (pano === 'flat') shared.filter = 'field_of_view<360';
if (Number.isFinite(sinceMs) && sinceMs > 0)
shared.datetime = `${new Date(sinceMs).toISOString()}/..`;
const dLat = metres / 111_320;
const dLon =
metres / (111_320 * Math.max(0.01, Math.cos((lat * Math.PI) / 180)));
// Clamped to the map: the API finds nothing in a box past ±180°.
const box = [
Math.max(-180, lon - dLon),
Math.max(-90, lat - dLat),
Math.min(180, lon + dLon),
Math.min(90, lat + dLat),
].map((v) => v.toFixed(7));
// One search failing (busy, no answer) leaves the other's pictures;
// only both failing fails the lookup. The caller's abort stops both.
const both = new AbortController();
const onAbort = () => both.abort(signal.reason);
if (signal?.aborted) throw signal.reason;
signal?.addEventListener('abort', onAbort, { once: true });
const run = (params) =>
search(params, { signal: both.signal }).catch((error) => {
if (!both.signal.aborted && !signal?.aborted) failures.push(error);
throw error;
});
const failures = [];
let settled;
try {
settled = await Promise.allSettled([
run({
place_position: `${Number(lon).toFixed(7)},${Number(lat).toFixed(7)}`,
place_distance: `0-${metres}`,
place_fov_tolerance: String(NEAREST_FOV_TOLERANCE_DEG),
limit: String(Math.min(100, Math.max(1, limit))),
...shared,
}),
run({
bbox: box.join(','),
limit: String(NEAREST_BOX_LIMIT),
...shared,
}),
]);
} finally {
signal?.removeEventListener('abort', onAbort);
}
if (signal?.aborted) throw signal.reason;
const found = settled
.filter((result) => result.status === 'fulfilled')
.map((result) => result.value);
if (!found.length) throw failures[0] ?? settled[0].reason;
const byId = new Map();
for (const item of found.flat())
if (item?.id != null && !byId.has(String(item.id)))
byId.set(String(item.id), item);
return [...byId.values()];
},
};
}