feat: Wildlife Sightings layer from iNaturalist and Acartia

Recent community wildlife observations, as a new Wildlife group in the
layer panel.

- Server: keyless iNaturalist proxy (v2 observations with only the
  projected fields; undocumented v1 UTFGrid density tiles, decoded on the
  server) sharing one paced queue (burst 4, ~1/s, 60/min, 8,000/day budget,
  up to four in flight), in-memory caches and upstream-only cooldowns;
  Acartia Salish Sea marine-mammal feed rounded to 0.01 degrees with
  comments dropped.
- Layer: grid counts drawn as a soft view-ranked density glow; real sampled
  sightings as taxon badges at their true positions with ambient photo
  thumbnails and labels; obscured records stay privacy cells; a clicked
  sighting stays pinned through camera moves and refreshes.
- Anchored photo card per selection with the single iNaturalist link;
  attribution in the layer row and the Data attribution popover.
- Filters (CONFIRMED, taxa presets) round-trip in share links with token 9.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
Yehe LiuandClaude Opus 5.5 committed 2026-11-05 16:17:12 -05:00
1 parent edd6212793
commit 14f88b3e08
120 files changed
+21260 -285

No files matched your search

+179
View File
@@ -0,0 +1,179 @@
import { normalizeAcartiaSightings } from '../../src/layers/wildlifeSightings/records.js';
import { coalesceProxyRequest, readResponseJsonCapped } from './common/http.js';
import { makeRateLimiter, clientKey } from './common/rate-limit.js';
import { admitSameSiteKeyless } from './common/same-site.js';
import { providerUserAgent } from './common/userAgent.js';
const API_URL = 'https://acartia.io/api/v1/sightings/current';
// All views share the provider's seven-day snapshot.
const TTL_MS = 600_000;
const STALE_MAX_MS = 24 * 60 * 60_000;
const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
const TIMEOUT_MS = 15_000;
const COOLDOWN_MS = 60_000;
const COOLDOWN_MIN_MS = 5000;
const COOLDOWN_MAX_MS = 60 * 60_000;
const FAILURE_COOLDOWN_MS = 15_000;
/** Bound upstream Retry-After seconds or dates to five seconds–one hour. */
export function acartiaRetryCooldownMs(raw, nowMs) {
const value = typeof raw === 'string' ? raw.trim() : '';
if (value) {
const seconds = /^\d+(?:\.\d+)?$/.test(value) ? Number(value) : NaN;
const deadline =
!Number.isFinite(seconds) && /[a-z]/i.test(value)
? Date.parse(value)
: NaN;
const delay = Number.isFinite(seconds) ? seconds * 1000 : deadline - nowMs;
if (Number.isFinite(delay) && delay >= 0)
return Math.min(COOLDOWN_MAX_MS, Math.max(COOLDOWN_MIN_MS, delay));
}
return COOLDOWN_MS;
}
/** Salish Sea coverage. Precise coordinates and comments never enter cache. */
export function acartiaProxy({
fetchImpl = (...args) => globalThis.fetch(...args),
now = () => Date.now(),
cache = new Map(),
warn = (...args) => console.warn(...args),
} = {}) {
const inFlight = new Map();
const allow = makeRateLimiter({
windowMs: 60_000,
max: 60,
globalMax: 600,
now,
});
let cooldownUntil = 0;
let cooldownStatus = 429;
let warnedClamp = false;
const retrySeconds = () =>
Math.max(1, Math.ceil((cooldownUntil - now()) / 1000));
const unavailable = (status = 502) =>
Object.assign(new Error('acartia_unavailable'), {
status,
retryAfterS: retrySeconds(),
});
function coolDown(status, delay) {
const until = now() + delay;
if (until > cooldownUntil) {
cooldownUntil = until;
cooldownStatus = status;
} else if (status === 429 && now() < cooldownUntil) cooldownStatus = 429;
}
async function load() {
if (now() < cooldownUntil) throw unavailable(cooldownStatus);
const signal = AbortSignal.timeout(TIMEOUT_MS);
try {
const response = await fetchImpl(API_URL, {
signal,
redirect: 'error',
headers: {
Accept: 'application/json',
'User-Agent': providerUserAgent('wildlife-sightings'),
},
});
if (!response.ok) {
await response.body?.cancel().catch(() => {});
if (response.status === 429) {
const delay = acartiaRetryCooldownMs(
response.headers.get('retry-after'),
now(),
);
if (delay === COOLDOWN_MAX_MS && !warnedClamp) {
warnedClamp = true;
warn('[acartia-proxy] upstream cooldown capped at one hour');
}
coolDown(429, delay);
throw unavailable(429);
}
throw unavailable();
}
// This endpoint documents a JSON array, not a results/data envelope.
const payload = await readResponseJsonCapped(
response,
MAX_RESPONSE_BYTES,
signal,
);
const rows = normalizeAcartiaSightings(payload, now());
if (!rows?.length) throw new Error('invalid_snapshot');
return { fetchedAt: now(), rows };
} catch (error) {
if (error.status !== 429) coolDown(502, FAILURE_COOLDOWN_MS);
warn('[acartia-proxy] upstream refresh failed');
throw unavailable(error.status === 429 ? 429 : 502);
}
}
function age(entry) {
if (!entry) return Infinity;
const elapsed = now() - entry.savedAt;
return elapsed < 0 ? Infinity : elapsed;
}
async function acquire() {
const previous = cache.get('sightings');
if (age(previous) < TTL_MS) return { value: previous.value, stale: false };
if (age(previous) > STALE_MAX_MS) cache.delete('sightings');
try {
const { promise } = coalesceProxyRequest(
inFlight,
'sightings',
async () => {
const value = await load();
cache.set('sightings', { value, savedAt: now() });
return value;
},
);
return { value: await promise, stale: false };
} catch (error) {
if (age(previous) <= STALE_MAX_MS)
return { value: previous.value, stale: true };
throw error;
}
}
async function handler(req, res) {
const json = (status, value, { stale = false, retryAfterS } = {}) => {
if (res.destroyed) return;
res.writeHead(status, {
'Content-Type': 'application/json',
'Cache-Control': 'no-store',
...(status === 405 ? { Allow: 'GET' } : {}),
...(retryAfterS ? { 'Retry-After': String(retryAfterS) } : {}),
...(stale ? { 'X-Data-Stale': 'true' } : {}),
});
res.end(JSON.stringify(value));
};
if (admitSameSiteKeyless(req, res)) return;
if (req.method !== 'GET') return json(405, { error: 'method_not_allowed' });
const pathname = (req.url || '/').split('?')[0];
if (pathname !== '/sightings') return json(404, { error: 'unknown_route' });
if (!allow(clientKey(req)))
return json(429, { error: 'rate_limited' }, { retryAfterS: 60 });
try {
const { value, stale } = await acquire();
return json(200, stale ? { ...value, stale: true } : value, { stale });
} catch (error) {
return json(
error.status === 429 ? 429 : 502,
{ error: 'acartia_unavailable' },
{ retryAfterS: error.retryAfterS },
);
}
}
return {
name: 'acartia',
configureServer({ middlewares }) {
middlewares.use('/api/acartia', handler);
},
configurePreviewServer({ middlewares }) {
middlewares.use('/api/acartia', handler);
},
};
}