mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-21 02:32:18 +00:00
Panoramax, the open federated street-level commons, registers beside Mapillary, Google Street View and KartaView. Its meta-catalogue (api.panoramax.xyz) is keyless and CORS-open, so it runs in the browser: - coverage from its vector tiles: sequence lines at z11–14 below 30 km (longest first under the per-tile cap), and above that the grid layer's density cells as binned points, not counted as sequences; - a click on a line opens that sequence's picture nearest the click (STAC search, any direction), without moving the camera, then any sequence's if it has none within 50 m; the 360° and since filters go to the lines and to the API; - cones from the z15 tiles' pictures layer around the open picture (~110 bytes a picture, against ~7.5 kB for a STAC item), re-centred when a picture opens outside them; ‹ › follow the picture's prev/next links; - the caption names the author (not an account named by an email address) and the picture's licence (StreetPose `license`), and links to the picture in the Panoramax viewer; the globe credits Panoramax. KartaView's viewer becomes the shared photoViewer.js (flat <img>, 360° on panorama.js, ‹ ›, keyboard, pinch, context loss), driven by a per-provider PhotoSources table; the request limiter moves to limiter.js. Panoramax shows the 2,048 px SD derivative and fetches the HD original only when the viewer is wide enough, once, shrunk while it decodes (never above 8,192 px). Orange #ff6f00 (Panoramax's own), off by default, share option 0.m.0_0.r.panoramax-1. The MCP panel allows the meta-catalogue and the biggest instances. Tests: policy, decode, source, viewer, provider, and a Panoramax fixture in the hermetic browser gate. Co-Authored-By: Claude Opus 5.5 <[email protected]>
301 lines
10 KiB
JavaScript
301 lines
10 KiB
JavaScript
import {
|
|
IMAGE_PROBE_TIMEOUT_MS,
|
|
MAX_RESPONSE_BYTES,
|
|
KARTAVIEW_API_HOST,
|
|
NEAREST_LIMIT,
|
|
NEAREST_SEARCH_ZOOM,
|
|
PAGE_CONCURRENCY,
|
|
PAGE_TIMEOUT_MS,
|
|
PHOTO_API_CONCURRENCY,
|
|
PHOTO_API_RETRIES,
|
|
PHOTO_API_RETRY_BASE_MS,
|
|
PHOTO_API_RETRY_MAX_MS,
|
|
PHOTO_API_FIRST_TIMEOUT_MS,
|
|
PHOTO_API_TIMEOUT_MS,
|
|
TILE_CONCURRENCY,
|
|
TILE_TIMEOUT_MS,
|
|
} from './policy.js';
|
|
import { createLimiter } from '../../limiter.js';
|
|
|
|
export { createLimiter } from '../../limiter.js';
|
|
|
|
/** An HTTP or API failure; `retryAfterSec` is set while KartaView rate-limits. */
|
|
export class KartaViewSourceError extends Error {
|
|
constructor(message, { status = 0, retryAfterSec = null } = {}) {
|
|
super(message);
|
|
this.name = 'KartaViewSourceError';
|
|
this.status = status;
|
|
this.retryAfterSec = retryAfterSec;
|
|
}
|
|
}
|
|
|
|
const NO_ANSWER = 'KartaView did not answer in time — try again';
|
|
/** Statuses that mean a photo file is gone, not that storage hiccupped. */
|
|
const GONE_STATUSES = Object.freeze([403, 404, 409, 410]);
|
|
|
|
/** Resolves after `ms`, or rejects when `signal` aborts first. */
|
|
function wait(ms, signal) {
|
|
return new Promise((resolve, reject) => {
|
|
if (signal?.aborted) return reject(signal.reason);
|
|
const timer = setTimeout(done, ms);
|
|
const onAbort = () => {
|
|
clearTimeout(timer);
|
|
reject(signal.reason);
|
|
};
|
|
signal?.addEventListener('abort', onAbort, { once: true });
|
|
function done() {
|
|
signal?.removeEventListener('abort', onAbort);
|
|
resolve();
|
|
}
|
|
});
|
|
}
|
|
|
|
/** Seconds from a Retry-After header, or null. */
|
|
function retryAfterSeconds(response) {
|
|
const header = response.headers?.get?.('retry-after');
|
|
const value = header == null || header === '' ? NaN : Number(header);
|
|
return Number.isFinite(value) && value >= 0 ? value : null;
|
|
}
|
|
|
|
/**
|
|
* KartaView's public API, browser-side and keyless (it allows any origin).
|
|
* It speaks HTTP/1.1, so the browser opens six connections to it: tiles take
|
|
* at most three, photo lookups two and sequence pages one, so a lookup never
|
|
* waits behind slow tiles or pages. The photo API answers 429 to more than
|
|
* about three requests at once; a 429 (and a lookup that timed out) is
|
|
* retried.
|
|
* @param {{fetchImpl?: typeof fetch, apiHost?: string, retryBaseMs?: number}} [options]
|
|
*/
|
|
export function createKartaViewSource({
|
|
fetchImpl = (...args) => globalThis.fetch(...args),
|
|
apiHost = KARTAVIEW_API_HOST,
|
|
retryBaseMs = PHOTO_API_RETRY_BASE_MS,
|
|
} = {}) {
|
|
const limiter = createLimiter(PHOTO_API_CONCURRENCY);
|
|
const tileLimiter = createLimiter(TILE_CONCURRENCY);
|
|
const pageLimiter = createLimiter(PAGE_CONCURRENCY, { lifo: true });
|
|
|
|
/** GET JSON within `timeoutMs`; the caller's abort wins over the timeout. */
|
|
async function getJson(url, { signal, timeoutMs }) {
|
|
const controller = new AbortController();
|
|
const onAbort = () => controller.abort(signal.reason);
|
|
if (signal?.aborted) throw signal.reason;
|
|
signal?.addEventListener('abort', onAbort, { once: true });
|
|
const timer = setTimeout(
|
|
() => controller.abort(new KartaViewSourceError(NO_ANSWER)),
|
|
timeoutMs,
|
|
);
|
|
try {
|
|
const response = await fetchImpl(url, { signal: controller.signal });
|
|
if (response.status === 429)
|
|
throw new KartaViewSourceError('KartaView is rate-limiting requests', {
|
|
status: 429,
|
|
retryAfterSec: retryAfterSeconds(response) ?? 2,
|
|
});
|
|
if (!response.ok)
|
|
throw new KartaViewSourceError(
|
|
`KartaView answered HTTP ${response.status}`,
|
|
{ status: response.status },
|
|
);
|
|
const length = Number(response.headers?.get?.('content-length'));
|
|
const tooMuch = () =>
|
|
new KartaViewSourceError('KartaView sent too much data', {
|
|
status: response.status,
|
|
});
|
|
if (length > MAX_RESPONSE_BYTES) throw tooMuch();
|
|
// KartaView answers chunked, without a length: count while reading.
|
|
const reader = response.body?.getReader?.();
|
|
if (!reader) return await response.json();
|
|
const chunks = [];
|
|
let bytes = 0;
|
|
for (;;) {
|
|
const { done, value } = await reader.read();
|
|
if (done) break;
|
|
bytes += value.byteLength;
|
|
if (bytes > MAX_RESPONSE_BYTES) {
|
|
reader.cancel().catch(() => {});
|
|
throw tooMuch();
|
|
}
|
|
chunks.push(value);
|
|
}
|
|
const body = new Uint8Array(bytes);
|
|
let offset = 0;
|
|
for (const chunk of chunks) {
|
|
body.set(chunk, offset);
|
|
offset += chunk.byteLength;
|
|
}
|
|
return JSON.parse(new TextDecoder().decode(body));
|
|
} catch (error) {
|
|
if (signal?.aborted) throw signal.reason;
|
|
if (controller.signal.aborted) throw controller.signal.reason;
|
|
if (error instanceof KartaViewSourceError) throw error;
|
|
throw new KartaViewSourceError(NO_ANSWER);
|
|
} finally {
|
|
clearTimeout(timer);
|
|
signal?.removeEventListener('abort', onAbort);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* A photo-API call through `gate`, retrying 429s with backoff and, once, a
|
|
* call that timed out.
|
|
*/
|
|
async function photoApi(
|
|
path,
|
|
params,
|
|
{ signal } = {},
|
|
{
|
|
gate = limiter,
|
|
timeoutMs = PHOTO_API_TIMEOUT_MS,
|
|
firstTimeoutMs = PHOTO_API_FIRST_TIMEOUT_MS,
|
|
} = {},
|
|
) {
|
|
const query = params ? `?${new URLSearchParams(params)}` : '';
|
|
const url = `${apiHost}${path}${query}`;
|
|
let timeouts = 0;
|
|
for (let attempt = 0; ; attempt++) {
|
|
try {
|
|
const payload = await gate.run(
|
|
// A slow first answer is usually quick when asked again.
|
|
() =>
|
|
getJson(url, {
|
|
signal,
|
|
timeoutMs: timeouts === 0 ? firstTimeoutMs : timeoutMs,
|
|
}),
|
|
{ signal },
|
|
);
|
|
const code = Number(payload?.status?.apiCode);
|
|
// 600 ok, 601 empty, 602 partial: anything else is a refusal.
|
|
if (Number.isFinite(code) && (code < 600 || code > 603))
|
|
throw new KartaViewSourceError(
|
|
`KartaView refused the request (code ${code})`,
|
|
{ status: Number(payload?.status?.httpCode) || 0 },
|
|
);
|
|
return payload?.result ?? {};
|
|
} catch (error) {
|
|
if (signal?.aborted) throw error;
|
|
const timedOut = error?.message === NO_ANSWER && error.status === 0;
|
|
if (timedOut && timeouts++ < 1) continue;
|
|
if (error?.status !== 429 || attempt >= PHOTO_API_RETRIES) {
|
|
if (error?.status === 429)
|
|
throw new KartaViewSourceError(
|
|
'KartaView is rate-limiting requests — try again in a moment',
|
|
{ status: 429, retryAfterSec: error.retryAfterSec },
|
|
);
|
|
throw error;
|
|
}
|
|
await wait(
|
|
Math.min(
|
|
PHOTO_API_RETRY_MAX_MS,
|
|
Math.max(
|
|
retryBaseMs * 2 ** attempt,
|
|
(error.retryAfterSec ?? 0) * 1000,
|
|
),
|
|
),
|
|
signal,
|
|
);
|
|
}
|
|
}
|
|
}
|
|
|
|
return {
|
|
/** A coverage tile: `{lines: [{track: [{lat, lng}]}]}`. */
|
|
async getTile({ x, y, z }, { signal } = {}) {
|
|
const url = `${apiHost}/2.0/sequence/tiles/${x}/${y}/${z}.json`;
|
|
const once = () =>
|
|
tileLimiter.run(
|
|
() => getJson(url, { signal, timeoutMs: TILE_TIMEOUT_MS }),
|
|
{ signal },
|
|
);
|
|
try {
|
|
return await once();
|
|
} catch (error) {
|
|
// A cold dense tile can outlast the timeout; KartaView has it ready
|
|
// by the second ask.
|
|
if (signal?.aborted || error?.message !== NO_ANSWER) throw error;
|
|
return once();
|
|
}
|
|
},
|
|
|
|
/**
|
|
* Whether a photo file is there: true, false when it is gone (archived
|
|
* photos answer 409, and a HEAD says 200 regardless), or null when the
|
|
* storage did not say (timeout, network, 5xx). It GETs and stops at the
|
|
* headers.
|
|
*/
|
|
async probeImage(url, { signal } = {}) {
|
|
if (!url) return false;
|
|
const controller = new AbortController();
|
|
const onAbort = () => controller.abort(signal.reason);
|
|
if (signal?.aborted) throw signal.reason;
|
|
signal?.addEventListener('abort', onAbort, { once: true });
|
|
const timer = setTimeout(
|
|
() => controller.abort(),
|
|
IMAGE_PROBE_TIMEOUT_MS,
|
|
);
|
|
try {
|
|
const response = await fetchImpl(url, { signal: controller.signal });
|
|
if (response.ok) return true;
|
|
return GONE_STATUSES.includes(response.status) ? false : null;
|
|
} catch {
|
|
if (signal?.aborted) throw signal.reason;
|
|
return null;
|
|
} finally {
|
|
clearTimeout(timer);
|
|
signal?.removeEventListener('abort', onAbort);
|
|
// The body is not needed: drop it.
|
|
controller.abort();
|
|
}
|
|
},
|
|
|
|
/** Photo records around a point, nearest first. */
|
|
async nearestPhotos({ lat, lon }, { signal } = {}) {
|
|
const result = await photoApi(
|
|
'/2.0/photo/',
|
|
{
|
|
lat: lat.toFixed(7),
|
|
lng: lon.toFixed(7),
|
|
zoomLevel: String(NEAREST_SEARCH_ZOOM),
|
|
itemsPerPage: String(NEAREST_LIMIT),
|
|
},
|
|
{ signal },
|
|
);
|
|
return Array.isArray(result.data) ? result.data : [];
|
|
},
|
|
|
|
/** One photo record. */
|
|
async getPhoto(photoId, { signal } = {}) {
|
|
const result = await photoApi(
|
|
`/2.0/photo/${encodeURIComponent(photoId)}`,
|
|
null,
|
|
{ signal },
|
|
);
|
|
if (!result.data || typeof result.data !== 'object')
|
|
throw new KartaViewSourceError('KartaView has no such photo');
|
|
return result.data;
|
|
},
|
|
|
|
/** A page of a sequence's photos in capture order (1-based `page`). */
|
|
async getSequencePhotos(
|
|
sequenceId,
|
|
{ page, itemsPerPage },
|
|
{ signal } = {},
|
|
) {
|
|
const result = await photoApi(
|
|
`/2.0/sequence/${encodeURIComponent(sequenceId)}/photos`,
|
|
{ page: String(page), itemsPerPage: String(itemsPerPage) },
|
|
{ signal },
|
|
{
|
|
gate: pageLimiter,
|
|
timeoutMs: PAGE_TIMEOUT_MS,
|
|
firstTimeoutMs: PAGE_TIMEOUT_MS,
|
|
},
|
|
);
|
|
return {
|
|
photos: Array.isArray(result.data) ? result.data : [],
|
|
hasMore: result.hasMoreData === true,
|
|
};
|
|
},
|
|
};
|
|
}
|