From 167aa947ce338d90af77eb22af04d08be25eea47 Mon Sep 17 00:00:00 2001 From: Said Date: Tue, 20 Oct 2026 00:11:31 +0100 Subject: [PATCH 01/13] fix(cctv): admit and bound HLS leases by peer --- docs/CURRENT-STATE.md | 7 ++++ scripts/package-boundaries.json | 2 + server/providers/cctv.js | 23 +++++++++-- server/providers/cctv/stream.js | 59 ++++++++++++++++++++++------- src/data/cctvHlsStream.test.mjs | 37 ++++++++++++++++++ src/data/cctvMediaFeedType.test.mjs | 43 +++++++++++++++++++++ 6 files changed, 154 insertions(+), 17 deletions(-) diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 55b7a63ab1..9d674d1055 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -1,5 +1,12 @@ # God's Eye View Current State +CCTV live-media requests are same-site gated before catalog or media work, including +HLS renewal, segment reads and DELETE cleanup. HLS leases belong to their socket +peer (IPv4-mapped IPv6 is normalized), with eight leases per peer across the two +global sessions. Peers behind the same NAT share that budget; this is resource +admission, not authentication. Native same-origin video and range requests remain +supported. + Shared distance checks use `src/geoDistance.js` with `{ lat, lon }` points and the IUGG mean spherical Earth radius, 6371.0088 km. `greatCircleKm` is canonical; `greatCircleMeters` is its exact metre conversion. Missing, diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index ca5dc0c7fa..fc9e4b5e98 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -187,6 +187,8 @@ "exports": ["./server/providers/cctv"], "modules": [ "server/providers/cctv.js", + "server/providers/common/same-site.js", + "src/localRequestGate.mjs", "server/providers/cctv/cap.js", "server/providers/cctv/groundHeights.js", "server/providers/cctv/catalog.js", diff --git a/server/providers/cctv.js b/server/providers/cctv.js index e549753e82..fc8f4f692d 100644 --- a/server/providers/cctv.js +++ b/server/providers/cctv.js @@ -17,6 +17,7 @@ import { CCTV_MAX_SOURCES_CEILING, } from './cctv/constants.js'; import { sanitizeCctvRangeHeader } from './cctv/range.js'; +import { admitSameSite } from './common/same-site.js'; import { createHlsPuller } from './cctv/stream.js'; import { googleServerApiKey } from './places/google-key.js'; export { CCTV_FRAME_FETCH_TIMEOUT_MS, fetchCctvImageFromUpstream }; @@ -135,11 +136,18 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) { }); server.middlewares.use('/api/cctv', async (req, res) => { try { + const url = new URL(req.url || '/', 'http://localhost'); + // Refuse before catalog I/O, session creation, renewal or release. + if (url.pathname.startsWith('/media/') && admitSameSite(req, res)) + return; + const clientId = String(req.socket?.remoteAddress || 'unknown').replace( + /^::ffff:/, + '', + ); const sources = await getCctvSources(); const sourceById = new Map( sources.map((source) => [source.id, source]), ); - const url = new URL(req.url || '/', 'http://localhost'); if (url.pathname === '/sources') { const body = { @@ -238,7 +246,7 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) { return; } if (req.method === 'DELETE') { - if (leaseId) puller.release(cameraId, leaseId); + if (leaseId) puller.release(cameraId, leaseId, clientId); res.writeHead(204); res.end(); return; @@ -268,6 +276,7 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) { url.searchParams.get('session'), Number(match[3]), leaseId, + clientId, ); res.writeHead(body ? 200 : 404, { 'Content-Type': 'video/mp2t', @@ -279,10 +288,15 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) { const downstream = watchDownstreamClose(res); let entry; const cancelPending = () => { - if (entry) puller.release(cameraId, leaseId); + if (entry) puller.release(cameraId, leaseId, clientId); }; try { - entry = await puller.ensure(cameraId, mediaUrl, leaseId); + entry = await puller.ensure( + cameraId, + mediaUrl, + leaseId, + clientId, + ); if (downstream.closed) { cancelPending(); return; @@ -296,6 +310,7 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) { entry, cameraId, leaseId, + clientId, ); if (downstream.closed) return; if (!playlist) throw new Error('Stream unavailable'); diff --git a/server/providers/cctv/stream.js b/server/providers/cctv/stream.js index 14d1743bb8..46608f294e 100644 --- a/server/providers/cctv/stream.js +++ b/server/providers/cctv/stream.js @@ -4,6 +4,7 @@ import { randomUUID } from 'node:crypto'; export const HLS_LIMITS = Object.freeze({ sessions: 2, leasesPerSession: 8, + leasesPerClient: 8, playlistBytes: 256 * 1024, segmentBytes: 4 * 1024 * 1024, sessionBytes: 24 * 1024 * 1024, @@ -138,25 +139,37 @@ export function createHlsPuller({ entry.upstream.clear(); entry.bytes = 0; }; - const release = (cameraId, leaseId) => { + const release = (cameraId, leaseId, clientId = 'legacy') => { const entry = active.get(cameraId); const lease = entry?.leases.get(leaseId); - if (!lease) return; + if (!lease || lease.clientId !== clientId) return; clearTimeout(lease.timer); entry.leases.delete(leaseId); if (!entry.leases.size) stop(cameraId, entry.token); }; - const touch = (entry, leaseId, create = false) => { + const touch = (entry, leaseId, create = false, clientId = 'legacy') => { let lease = entry.leases.get(leaseId); + if (lease && lease.clientId !== clientId) + throw new Error('HLS lease belongs to another client'); if (!lease) { + const clientLeases = [...active.values()].reduce( + (count, session) => + count + + [...session.leases.values()].filter( + (item) => item.clientId === clientId, + ).length, + 0, + ); + if (clientLeases >= limits.leasesPerClient) + throw new Error('HLS client lease capacity reached'); if (!create || entry.leases.size >= limits.leasesPerSession) throw new Error('HLS lease capacity reached'); - lease = {}; + lease = { clientId }; entry.leases.set(leaseId, lease); } clearTimeout(lease.timer); lease.timer = setTimeout( - () => release(entry.cameraId, leaseId), + () => release(entry.cameraId, leaseId, clientId), limits.idleMs, ); lease.timer.unref?.(); @@ -248,7 +261,12 @@ export function createHlsPuller({ } } }; - const ensure = async (cameraId, url, leaseId = 'legacy') => { + const ensure = async ( + cameraId, + url, + leaseId = 'legacy', + clientId = 'legacy', + ) => { if (closed) throw new Error('HLS service closed'); sameOriginHlsUrl(url, url); let entry = active.get(cameraId); @@ -257,7 +275,7 @@ export function createHlsPuller({ entry = null; } if (entry) { - touch(entry, leaseId, true); + touch(entry, leaseId, true, clientId); return entry; } // Reserve synchronously, before any await: concurrent creation is singleflight. @@ -279,8 +297,8 @@ export function createHlsPuller({ pendingDiscontinuity: false, discontinuitiesRemoved: 0, }; + touch(entry, leaseId, true, clientId); active.set(cameraId, entry); - touch(entry, leaseId, true); entry.polling = poll(entry); return entry; }; @@ -292,9 +310,14 @@ export function createHlsPuller({ } return false; }; - const buildPlaylist = async (entry, cameraId, leaseId = 'legacy') => { + const buildPlaylist = async ( + entry, + cameraId, + leaseId = 'legacy', + clientId = 'legacy', + ) => { if (entry.stopping || entry.segments.size < 2) return null; - touch(entry, leaseId); + touch(entry, leaseId, false, clientId); const segments = [...entry.segments.values()].sort((a, b) => a.seq - b.seq); const lines = [ '#EXTM3U', @@ -318,12 +341,22 @@ export function createHlsPuller({ } return lines.join('\n') + '\n'; }; - const getSegment = (cameraId, token, seq, leaseId = 'legacy') => { + const getSegment = ( + cameraId, + token, + seq, + leaseId = 'legacy', + clientId = 'legacy', + ) => { const entry = active.get(cameraId); - if (!entry || entry.token !== token || !entry.leases.has(leaseId)) + if ( + !entry || + entry.token !== token || + entry.leases.get(leaseId)?.clientId !== clientId + ) return null; const body = entry.segments.get(seq)?.body; - if (body) touch(entry, leaseId); + if (body) touch(entry, leaseId, false, clientId); return body || null; }; const shutdown = async () => { diff --git a/src/data/cctvHlsStream.test.mjs b/src/data/cctvHlsStream.test.mjs index a087eebdf8..01f5b15e48 100644 --- a/src/data/cctvHlsStream.test.mjs +++ b/src/data/cctvHlsStream.test.mjs @@ -223,3 +223,40 @@ test('an abandoned consumer expires while a renewed consumer keeps the session', assert.equal(entry.controller.signal.aborted, false); await manager.shutdown(); }); + +test('client lease ownership covers refresh, segments and release, with a bounded client budget', async (t) => { + const manager = createHlsPuller({ + limits: { ...HLS_LIMITS, leasesPerClient: 1, pollMs: 100000 }, + fetchImpl: async (url) => + new Response(url.endsWith('.m3u8') ? playlist : 'abc'), + }); + t.after(() => manager.shutdown()); + const entry = await manager.ensure('a', base, 'lease-a', 'peer-a'); + await manager.waitReady(entry); + await assert.rejects( + manager.ensure('a', base, 'lease-a', 'peer-b'), + /another client/, + ); + assert.equal( + manager.getSegment('a', entry.token, 0, 'lease-a', 'peer-b'), + null, + ); + await assert.rejects( + manager.buildPlaylist(entry, 'a', 'lease-a', 'peer-b'), + /another client/, + ); + manager.release('a', 'lease-a', 'peer-b'); + assert.equal(entry.leases.size, 1); + await assert.rejects( + manager.ensure('b', base, 'lease-b', 'peer-a'), + /client lease capacity/, + ); + assert.equal( + manager.stats().sessions, + 1, + 'failed admission reserves no session', + ); + await manager.ensure('b', base, 'lease-b', 'peer-b'); + manager.release('a', 'lease-a', 'peer-a'); + assert.equal(entry.stopping, true); +}); diff --git a/src/data/cctvMediaFeedType.test.mjs b/src/data/cctvMediaFeedType.test.mjs index 5791e433b1..e6ba9e3eb9 100644 --- a/src/data/cctvMediaFeedType.test.mjs +++ b/src/data/cctvMediaFeedType.test.mjs @@ -268,3 +268,46 @@ test('/frame does not follow a still camera off its origin', async (t) => { [STILL.url], ); }); + +test('cross-site media creation, segment reads and release fail before any catalog or media fetch', async (t) => { + let handler; + const originalFetch = globalThis.fetch; + let calls = 0; + globalThis.fetch = async () => { + calls++; + throw new Error('must not fetch'); + }; + t.after(() => { + globalThis.fetch = originalFetch; + }); + cctvProxy().configureServer({ + middlewares: { + use: (_path, fn) => { + handler = fn; + }, + }, + }); + for (const headers of [ + { origin: 'https://foreign.example' }, + { origin: 'null' }, + { 'sec-fetch-site': 'cross-site' }, + { 'sec-fetch-site': 'same-site' }, + ]) { + for (const [method, url] of [ + ['GET', '/media/camera?lease=test'], + ['DELETE', '/media/camera?lease=test'], + ['GET', '/media/camera/seg_0.ts?lease=test'], + ]) { + const { res } = recordingResponse(); + res.setHeader = (name, value) => { + res.headers[name] = value; + }; + await handler( + { method, url, headers: { host: 'localhost:4173', ...headers } }, + res, + ); + assert.equal(res.statusCode, 403); + } + } + assert.equal(calls, 0); +}); From a7160c62be9794875ecdd757b0f3b8141fd37dd4 Mon Sep 17 00:00:00 2001 From: Said Date: Tue, 20 Oct 2026 00:11:49 +0100 Subject: [PATCH 02/13] docs: record CCTV session admission fix --- changelog.d/1267-cctv-session-admission.md | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 changelog.d/1267-cctv-session-admission.md diff --git a/changelog.d/1267-cctv-session-admission.md b/changelog.d/1267-cctv-session-admission.md new file mode 100644 index 0000000000..c331e210d5 --- /dev/null +++ b/changelog.d/1267-cctv-session-admission.md @@ -0,0 +1,2 @@ +- Gate CCTV HLS media requests before session work, bind leases to the direct + peer, and bound per-peer leases across shared sessions (asturksever, #1267). From ad003118c5d27a437615e471e98d052150db1116 Mon Sep 17 00:00:00 2001 From: Said Date: Tue, 20 Oct 2026 01:06:53 +0100 Subject: [PATCH 03/13] fix(annotations): cull and budget surface height sampling --- docs/CURRENT-STATE.md | 2 + src/annotations/screenAnnotationRenderer.js | 42 +++++++- .../screenAnnotationRenderer.test.mjs | 102 +++++++++++++++++- 3 files changed, 143 insertions(+), 3 deletions(-) diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 55b7a63ab1..12a40da090 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -1,5 +1,7 @@ # God's Eye View Current State +Screen annotations reject hidden records and anchors wholly behind the camera or globe horizon before surface sampling. Unresolved visible heights share a 32-sample projection-pass budget, retry at most once per second per anchor on rendered frames, and retain no extra timer or listener. Unsettled points continue retrying as late terrain arrives; behind-camera, horizon and conservative frustum culls run before sampling. Validated heights remain settled in the bounded cache. + Shared distance checks use `src/geoDistance.js` with `{ lat, lon }` points and the IUGG mean spherical Earth radius, 6371.0088 km. `greatCircleKm` is canonical; `greatCircleMeters` is its exact metre conversion. Missing, diff --git a/src/annotations/screenAnnotationRenderer.js b/src/annotations/screenAnnotationRenderer.js index c6c214fffe..da06b37636 100644 --- a/src/annotations/screenAnnotationRenderer.js +++ b/src/annotations/screenAnnotationRenderer.js @@ -83,6 +83,9 @@ export function createScreenAnnotationRenderer( const heightCache = new Map(); const HEIGHT_CACHE_SOFT = 600; // target size; over this we evict keys not used this frame const HEIGHT_CACHE_HARD = 8000; // absolute ceiling (one big ring + others) — never exceeded + let cullingVolume = null; + const heightBounds = new Cesium.BoundingSphere(new Cesium.Cartesian3(), 9500); + let heightBudget = 32; let projGen = 0; // bumped each projection frame; entries used this frame are "hot" function trimHeightCache() { if (heightCache.size <= HEIGHT_CACHE_SOFT) return; @@ -123,6 +126,13 @@ export function createScreenAnnotationRenderer( heightCache.set(key, cached); return cached.h; } + const now = Date.now(); + if (cached && now < cached.nextAttempt) { + cached.gen = projGen; + return cached.h; + } + if (heightBudget <= 0) return cached?.h || 0; + heightBudget--; try { if ( scene.clampToHeightSupported && @@ -144,7 +154,12 @@ export function createScreenAnnotationRenderer( /* tiles not ready */ } const fallback = cached ? cached.h : 0; - heightCache.set(key, { h: fallback, settled: false, gen: projGen }); + heightCache.set(key, { + h: fallback, + settled: false, + gen: projGen, + nextAttempt: now + 1000, + }); trimHeightCache(); return fallback; } @@ -362,6 +377,24 @@ export function createScreenAnnotationRenderer( // Anchor at the real surface height (cached + validated), so marks sit on // the ground/building instead of at sea level. The settle-once cache keeps // it stable (no per-frame jitter that earlier broke nearby projections). + // Cheap conservative endpoint tests precede GPU-backed surface sampling. + // Testing the accepted height range avoids culling an elevated roof solely + // because its sea-level anchor lies just beyond the horizon. + const visibleAt = (height) => { + const point = Cesium.Cartesian3.fromDegrees(lon, lat, height); + Cesium.Cartesian3.subtract(point, scene.camera.positionWC, scratchDir); + return ( + Cesium.Cartesian3.dot(scratchDir, scene.camera.directionWC) > 0 && + occluder.isPointVisible(point) + ); + }; + Cesium.Cartesian3.fromDegrees(lon, lat, 0, undefined, heightBounds.center); + if ( + cullingVolume?.computeVisibility(heightBounds) === + Cesium.Intersect.OUTSIDE + ) + return null; + if (!visibleAt(0) && !visibleAt(9000)) return null; const world = Cesium.Cartesian3.fromDegrees( lon, lat, @@ -467,6 +500,13 @@ export function createScreenAnnotationRenderer( function projectAll() { if (!records.size) return; + heightBudget = 32; + cullingVolume = + scene.camera.frustum?.computeCullingVolume?.( + scene.camera.positionWC, + scene.camera.directionWC, + scene.camera.upWC, + ) || null; projGen += 1; // new frame: entries touched below are "hot" and survive trimming const trackedRect = trackedEntityRect(); occluder.cameraPosition = scene.camera.positionWC; diff --git a/src/annotations/screenAnnotationRenderer.test.mjs b/src/annotations/screenAnnotationRenderer.test.mjs index ef4509ed0c..94615e831f 100644 --- a/src/annotations/screenAnnotationRenderer.test.mjs +++ b/src/annotations/screenAnnotationRenderer.test.mjs @@ -152,10 +152,17 @@ test('outline upgrade preserves the existing SVG group identity', (t) => { }); const camera = { - positionWC: Cesium.Cartesian3.ZERO, - directionWC: Cesium.Cartesian3.ZERO, + positionWC: Cesium.Cartesian3.fromDegrees(-97.5, 31.2, 1000000), + directionWC: Cesium.Cartesian3.normalize( + Cesium.Cartesian3.negate( + Cesium.Cartesian3.fromDegrees(-97.5, 31.2), + new Cesium.Cartesian3(), + ), + new Cesium.Cartesian3(), + ), positionCartographic: { height: 1000 }, }; + t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', () => ({ x: 100, y: 100 })); const sampledAnchors = []; const scene = { camera, @@ -326,3 +333,94 @@ test('an add that throws after inserting its group unwinds instead of orphaning ); renderer.destroy(); }); + +test('hidden and back-facing annotations do not sample; visible unresolved heights have bounded retries', (t) => { + const previous = globalThis.document; + const previousRaf = globalThis.requestAnimationFrame; + globalThis.document = fakeDocument(); + globalThis.requestAnimationFrame = (fn) => { + fn(); + return 1; + }; + t.after(() => { + globalThis.document = previous; + globalThis.requestAnimationFrame = previousRaf; + }); + t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 1000 }); + t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', () => ({ + x: 100, + y: 100, + })); + const camera = { + positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 100000), + directionWC: new Cesium.Cartesian3(-1, 0, 0), + positionCartographic: { height: 100000 }, + moveEnd: new Cesium.Event(), + }; + let samples = 0; + const postRender = new Cesium.Event(); + const scene = { + camera, + canvas: { width: 800, height: 600 }, + postRender, + clampToHeightSupported: true, + clampToHeight() { + samples++; + }, + requestRender() {}, + }; + const renderer = createScreenAnnotationRenderer({ scene, camera }); + const mark = (id, lon) => ({ + id, + type: 'label', + anchor: { lon, lat: 0 }, + label: id, + }); + renderer.add(mark('far-side', 180)); + for (let i = 0; i < 100; i++) postRender.raiseEvent(); + assert.equal(samples, 0); + renderer.add(mark('near-side', 0)); + for (let i = 0; i < 100; i++) postRender.raiseEvent(); + assert.equal(samples, 1); + for (let i = 0; i < 10; i++) { + t.mock.timers.tick(1000); + postRender.raiseEvent(); + } + assert.equal(samples, 11); + camera.moveEnd.raiseEvent(); + postRender.raiseEvent(); + assert.equal(samples, 11, 'camera events cannot bypass the retry interval'); + renderer.update(mark('near-side', 0), { empty: true }); + t.mock.timers.tick(1000); + postRender.raiseEvent(); + assert.equal(samples, 11, 'hidden records do not sample'); + camera.directionWC = new Cesium.Cartesian3(1, 0, 0); + renderer.update(mark('near-side', 0)); + postRender.raiseEvent(); + assert.equal(samples, 11, 'behind-camera anchors do not sample'); + camera.directionWC = new Cesium.Cartesian3(-1, 0, 0); + camera.frustum = { + computeCullingVolume: () => ({ + computeVisibility: () => Cesium.Intersect.OUTSIDE, + }), + }; + postRender.raiseEvent(); + assert.equal(samples, 11, 'outside-frustum anchors do not sample'); + camera.frustum = null; + const before = samples; + renderer.add({ + id: 'large-area', + type: 'area', + label: 'Area', + ring: Array.from({ length: 100 }, (_, i) => [0.001 + i / 10000, 0]), + anchor: { lon: 0, lat: 0 }, + }); + assert.equal( + samples - before, + 32, + 'a projection pass caps synchronous surface work', + ); + renderer.destroy(); + assert.equal(camera.moveEnd.numberOfListeners, 0); + assert.equal(postRender.numberOfListeners, 0); +}); From f2b4162d768adca9d07d310fa923798e6b81b4eb Mon Sep 17 00:00:00 2001 From: Said Date: Tue, 20 Oct 2026 01:07:09 +0100 Subject: [PATCH 04/13] docs: record annotation fix --- changelog.d/1277-annotation-issue-fix.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/1277-annotation-issue-fix.md diff --git a/changelog.d/1277-annotation-issue-fix.md b/changelog.d/1277-annotation-issue-fix.md new file mode 100644 index 0000000000..6f17992372 --- /dev/null +++ b/changelog.d/1277-annotation-issue-fix.md @@ -0,0 +1 @@ +- Cull and budget surface height sampling (asturksever, #1277). From 5e9c14db83b26242ce8052f96a5ffeae979349ce Mon Sep 17 00:00:00 2001 From: Said Date: Tue, 20 Oct 2026 14:10:29 +0100 Subject: [PATCH 05/13] test: keep headful CCTV gate rendering when occluded --- changelog.d/1267-cctv-session-admission.md | 1 + scripts/qa-cctv-v2.mjs | 1 + 2 files changed, 2 insertions(+) diff --git a/changelog.d/1267-cctv-session-admission.md b/changelog.d/1267-cctv-session-admission.md index c331e210d5..c331222e70 100644 --- a/changelog.d/1267-cctv-session-admission.md +++ b/changelog.d/1267-cctv-session-admission.md @@ -1,2 +1,3 @@ - Gate CCTV HLS media requests before session work, bind leases to the direct peer, and bound per-peer leases across shared sessions (asturksever, #1267). +- Keep headful CCTV QA rendering active when its window is occluded (asturksever, #1267). diff --git a/scripts/qa-cctv-v2.mjs b/scripts/qa-cctv-v2.mjs index 88e0a5a2c4..a6abdffa34 100644 --- a/scripts/qa-cctv-v2.mjs +++ b/scripts/qa-cctv-v2.mjs @@ -454,6 +454,7 @@ async function main() { ...(HEADFUL ? [] : ['--use-gl=angle', '--use-angle=swiftshader']), '--disable-dev-shm-usage', '--disable-web-security', + '--disable-backgrounding-occluded-windows', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--window-size=1280,800', From aa4e0ca936775c2eb7b23e1875c64286dc9ef724 Mon Sep 17 00:00:00 2001 From: Said Turksever Date: Fri, 23 Oct 2026 12:30:39 +0100 Subject: [PATCH 06/13] Fix annotation height culling review findings (#1277) - Restrict the conservative frustum test to height sampling only: an endpoint outside it still projects at its cached or zero height, so an arrow with one off-frustum endpoint keeps its visible connector and label. - Test a settled height as the actual point; reject an unknown height before sampling only when both ends of the accepted -430..9000 m range fail the same constraint (behind camera, or below horizon), which the convexity of each rejection region makes a proof for the whole range. - Queue keys refused by an exhausted budget and reserve the next pass's budget for the oldest of them, so anchors beyond the first 32 are served under sparse passes while keeping 32 samples per pass and 1 s retries. - Add regressions with a real frustum, a low-angle authored camera, and 33 persistent points under sparse passes; consolidate CURRENT-STATE. Co-Authored-By: Claude Opus 5.5 --- docs/CURRENT-STATE.md | 10 +- src/annotations/screenAnnotationRenderer.js | 130 ++++++++---- .../screenAnnotationRenderer.test.mjs | 186 ++++++++++++++++++ 3 files changed, 291 insertions(+), 35 deletions(-) diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index f3e6ebd1b4..2adf7da33d 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -9,7 +9,15 @@ broader suffix variants. Follow-ups retain boundary provenance, and cancelled lookups preserve the previous analyst cohort and boundary source. Navigation search keeps a successful geocode, with no search or view-based region recovery. -Screen annotations reject hidden records and anchors wholly behind the camera or globe horizon before surface sampling. Unresolved visible heights share a 32-sample projection-pass budget, retry at most once per second per anchor on rendered frames, and retain no extra timer or listener. Unsettled points continue retrying as late terrain arrives; behind-camera, horizon and conservative frustum culls run before sampling. Validated heights remain settled in the bounded cache. +Screen annotations skip hidden records and, before surface sampling, reject an +unsettled anchor only when its whole accepted height range (-430 to 9000 m) is +behind the camera or below the globe horizon; a settled height is tested as the +actual point. Anchors outside the conservative frustum still project at their +cached or zero height, so a partly visible arrow keeps its connector, but do +not sample. Unresolved visible heights share a 32-sample projection-pass budget, +served oldest-refused first, retry at most once per second per anchor on +rendered frames, and retain no extra timer or listener. Validated heights remain +settled in the bounded cache. Terrain height requests accept at most 64 points, matching the browser service's existing batch size and one bounded upstream chunk. Larger requests return HTTP diff --git a/src/annotations/screenAnnotationRenderer.js b/src/annotations/screenAnnotationRenderer.js index da06b37636..d7fda32acd 100644 --- a/src/annotations/screenAnnotationRenderer.js +++ b/src/annotations/screenAnnotationRenderer.js @@ -83,9 +83,20 @@ export function createScreenAnnotationRenderer( const heightCache = new Map(); const HEIGHT_CACHE_SOFT = 600; // target size; over this we evict keys not used this frame const HEIGHT_CACHE_HARD = 8000; // absolute ceiling (one big ring + others) — never exceeded + // Accepted surface-height range; samples outside it are treated as misses. + const MIN_SURFACE_HEIGHT = -430; + const MAX_SURFACE_HEIGHT = 9000; + const HEIGHT_SAMPLE_BUDGET = 32; // clampToHeight calls per projection pass + const HEIGHT_RETRY_MS = 1000; // minimum interval between misses per anchor let cullingVolume = null; const heightBounds = new Cesium.BoundingSphere(new Cesium.Cartesian3(), 9500); - let heightBudget = 32; + // Fair sampling: keys refused by an exhausted budget queue in arrival order, + // and each pass reserves budget for the oldest queued keys first, so a fixed + // iteration order cannot starve anchors beyond the first budget's worth. + let heightQueue = new Set(); // keys refused in earlier passes, oldest first + let heightReserved = new Set(); // queued keys this pass serves first + let heightRefused = new Set(); // keys refused during this pass + let heightBudget = HEIGHT_SAMPLE_BUDGET; // unreserved slots left this pass let projGen = 0; // bumped each projection frame; entries used this frame are "hot" function trimHeightCache() { if (heightCache.size <= HEIGHT_CACHE_SOFT) return; @@ -113,10 +124,20 @@ export function createScreenAnnotationRenderer( return PALETTE[anno.color] || PALETTE.primary; } + function clearHeights() { + heightCache.clear(); + heightQueue.clear(); + } + + function heightKey(lon, lat) { + return `${lon.toFixed(5)},${lat.toFixed(5)}`; + } + // Best-effort surface height under a coordinate (clamps onto the 3D tiles). // Returns 0 until the tile loads, then caches the validated height. - function groundHeight(lon, lat) { - const key = `${lon.toFixed(5)},${lat.toFixed(5)}`; + // canSample=false returns the cached height (or 0) without surface sampling. + function groundHeight(lon, lat, canSample = true) { + const key = heightKey(lon, lat); const cached = heightCache.get(key); if (cached && cached.settled) { // Mark hot for this frame + bump to most-recently-used so heights for live @@ -127,12 +148,19 @@ export function createScreenAnnotationRenderer( return cached.h; } const now = Date.now(); - if (cached && now < cached.nextAttempt) { + if (cached && (!canSample || now < cached.nextAttempt)) { cached.gen = projGen; return cached.h; } - if (heightBudget <= 0) return cached?.h || 0; - heightBudget--; + if (!canSample) return 0; + if (heightReserved.has(key)) { + heightReserved.delete(key); + } else if (heightBudget > 0) { + heightBudget--; + } else { + heightRefused.add(key); + return cached?.h || 0; + } try { if ( scene.clampToHeightSupported && @@ -143,7 +171,11 @@ export function createScreenAnnotationRenderer( ); if (c) { const h = Cesium.Cartographic.fromCartesian(c).height; - if (Number.isFinite(h) && h > -430 && h < 9000) { + if ( + Number.isFinite(h) && + h > MIN_SURFACE_HEIGHT && + h < MAX_SURFACE_HEIGHT + ) { heightCache.set(key, { h, settled: true, gen: projGen }); trimHeightCache(); return h; @@ -158,7 +190,7 @@ export function createScreenAnnotationRenderer( h: fallback, settled: false, gen: projGen, - nextAttempt: now + 1000, + nextAttempt: now + HEIGHT_RETRY_MS, }); trimHeightCache(); return fallback; @@ -325,7 +357,7 @@ export function createScreenAnnotationRenderer( } catch { /* never inserted */ } - if (records.size === 0) heightCache.clear(); + if (records.size === 0) clearHeights(); throw error; } } @@ -377,29 +409,30 @@ export function createScreenAnnotationRenderer( // Anchor at the real surface height (cached + validated), so marks sit on // the ground/building instead of at sea level. The settle-once cache keeps // it stable (no per-frame jitter that earlier broke nearby projections). - // Cheap conservative endpoint tests precede GPU-backed surface sampling. - // Testing the accepted height range avoids culling an elevated roof solely - // because its sea-level anchor lies just beyond the horizon. - const visibleAt = (height) => { - const point = Cesium.Cartesian3.fromDegrees(lon, lat, height); - Cesium.Cartesian3.subtract(point, scene.camera.positionWC, scratchDir); - return ( - Cesium.Cartesian3.dot(scratchDir, scene.camera.directionWC) > 0 && - occluder.isPointVisible(point) + // A settled height is tested as the actual point below. An unknown height + // is rejected before GPU-backed surface sampling only when the whole + // accepted height range is proven hidden by one constraint. + let height; + if (heightCache.get(heightKey(lon, lat))?.settled) { + height = groundHeight(lon, lat); + } else { + if (heightRangeHidden(lon, lat)) return null; + // The frustum restricts sampling only; an endpoint outside it still + // projects (at its cached or zero height) so a partly visible arrow, + // route or ring keeps its on-screen connector and label. + Cesium.Cartesian3.fromDegrees( + lon, + lat, + 0, + undefined, + heightBounds.center, ); - }; - Cesium.Cartesian3.fromDegrees(lon, lat, 0, undefined, heightBounds.center); - if ( - cullingVolume?.computeVisibility(heightBounds) === - Cesium.Intersect.OUTSIDE - ) - return null; - if (!visibleAt(0) && !visibleAt(9000)) return null; - const world = Cesium.Cartesian3.fromDegrees( - lon, - lat, - groundHeight(lon, lat), - ); + const inFrustum = + cullingVolume?.computeVisibility(heightBounds) !== + Cesium.Intersect.OUTSIDE; + height = groundHeight(lon, lat, inFrustum); + } + const world = Cesium.Cartesian3.fromDegrees(lon, lat, height); // Reject points behind the camera (they produce wrapped/extreme coords). Cesium.Cartesian3.subtract(world, scene.camera.positionWC, scratchDir); if (Cesium.Cartesian3.dot(scratchDir, scene.camera.directionWC) <= 0) @@ -419,6 +452,21 @@ export function createScreenAnnotationRenderer( return { x: win.x, y: win.y }; } + // Points along one surface normal are linear in height, and each rejection + // region (behind the camera plane; the occluder's cone beyond the horizon + // plane) is convex. So when both height-range endpoints fail the SAME test, + // every intermediate height fails it too. Mixed failures prove nothing. + function heightRangeHidden(lon, lat) { + const low = Cesium.Cartesian3.fromDegrees(lon, lat, MIN_SURFACE_HEIGHT); + const high = Cesium.Cartesian3.fromDegrees(lon, lat, MAX_SURFACE_HEIGHT); + const behind = (point) => { + Cesium.Cartesian3.subtract(point, scene.camera.positionWC, scratchDir); + return Cesium.Cartesian3.dot(scratchDir, scene.camera.directionWC) <= 0; + }; + if (behind(low) && behind(high)) return true; + return !occluder.isPointVisible(low) && !occluder.isPointVisible(high); + } + // Tracked-entity z-order: the tracked aircraft is a Cesium billboard in the // CANVAS, which sits BELOW this SVG overlay (z-90, HTML over canvas). So a screen mark // could hide it. After layout, any mark whose ACTUAL projected bounding box (rings, @@ -500,7 +548,14 @@ export function createScreenAnnotationRenderer( function projectAll() { if (!records.size) return; - heightBudget = 32; + // Serve the oldest refused keys first; the rest of the budget is open. + heightReserved = new Set(); + for (const key of heightQueue) { + if (heightReserved.size >= HEIGHT_SAMPLE_BUDGET) break; + heightReserved.add(key); + } + heightBudget = HEIGHT_SAMPLE_BUDGET - heightReserved.size; + heightRefused = new Set(); cullingVolume = scene.camera.frustum?.computeCullingVolume?.( scene.camera.positionWC, @@ -653,6 +708,13 @@ export function createScreenAnnotationRenderer( } } } + // Still-refused queued keys keep their place; new refusals join the back. + // Keys no longer requesting a sample (settled, culled, removed) drop out. + const nextQueue = new Set(); + for (const key of heightQueue) + if (heightRefused.has(key)) nextQueue.add(key); + for (const key of heightRefused) nextQueue.add(key); + heightQueue = nextQueue; // Keep clustered callouts readable. const placed = []; @@ -733,7 +795,7 @@ export function createScreenAnnotationRenderer( }, 360); records.delete(anno.id); // Board emptied → drop accumulated height samples (natural reset point). - if (records.size === 0) heightCache.clear(); + if (records.size === 0) clearHeights(); } function sync() { @@ -753,7 +815,7 @@ export function createScreenAnnotationRenderer( /* gone */ } records.clear(); - heightCache.clear(); + clearHeights(); } return { add, update, remove, sync, destroy }; diff --git a/src/annotations/screenAnnotationRenderer.test.mjs b/src/annotations/screenAnnotationRenderer.test.mjs index 94615e831f..aba1faec34 100644 --- a/src/annotations/screenAnnotationRenderer.test.mjs +++ b/src/annotations/screenAnnotationRenderer.test.mjs @@ -424,3 +424,189 @@ test('hidden and back-facing annotations do not sample; visible unresolved heigh assert.equal(camera.moveEnd.numberOfListeners, 0); assert.equal(postRender.numberOfListeners, 0); }); + +function sampledLon(world) { + const carto = Cesium.Cartographic.fromCartesian(world); + return Number(Cesium.Math.toDegrees(carto.longitude).toFixed(5)); +} + +function installDom(t) { + const previous = globalThis.document; + const previousRaf = globalThis.requestAnimationFrame; + globalThis.document = fakeDocument(); + globalThis.requestAnimationFrame = (fn) => { + fn(); + return 1; + }; + t.after(() => { + globalThis.document = previous; + globalThis.requestAnimationFrame = previousRaf; + }); +} + +function squareFrustum() { + const frustum = new Cesium.PerspectiveFrustum(); + frustum.fov = Cesium.Math.toRadians(60); + frustum.aspectRatio = 1; + frustum.near = 1; + frustum.far = 1e8; + return frustum; +} + +test('an arrow with one endpoint outside a real frustum keeps its visible connector', (t) => { + installDom(t); + t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', (_scene, world) => + sampledLon(world) > 0.1 ? { x: 1100, y: 400 } : { x: 400, y: 400 }, + ); + // 5 km straight down over (0, 0): east is +Y, north is +Z in ECEF here. + const camera = { + positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 5000), + directionWC: new Cesium.Cartesian3(-1, 0, 0), + upWC: new Cesium.Cartesian3(0, 0, 1), + positionCartographic: { height: 5000 }, + frustum: squareFrustum(), + }; + const sampled = []; + const postRender = new Cesium.Event(); + const scene = { + camera, + canvas: { width: 800, height: 800 }, + postRender, + clampToHeightSupported: true, + clampToHeight(world) { + sampled.push(sampledLon(world)); + return world; + }, + }; + // The 0.2-degree endpoint (~22 km east) is well beyond the side plane plus + // the 9.5 km height-bound radius, yet in front of the camera and the horizon. + const far = Cesium.Cartesian3.fromDegrees(0.2, 0, 0); + const volume = camera.frustum.computeCullingVolume( + camera.positionWC, + camera.directionWC, + camera.upWC, + ); + assert.equal( + volume.computeVisibility(new Cesium.BoundingSphere(far, 9500)), + Cesium.Intersect.OUTSIDE, + ); + const renderer = createScreenAnnotationRenderer({ scene, camera }); + renderer.add({ + id: 'partial-arrow', + type: 'arrow', + label: 'Ridge', + anchor: { lon: 0, lat: 0 }, + to: { lon: 0.2, lat: 0 }, + }); + postRender.raiseEvent(); + const { group } = findAnnotationGroup(globalThis.document); + assert.equal(group.style.display, '', 'the arrow stays drawn'); + const path = group.children.find((child) => child.classList.contains('gev-anno-arrow')); + assert.match(path.getAttribute('d'), /^M 400\.0 400\.0 Q .* 1100\.0 400\.0$/); + assert.deepEqual([...new Set(sampled)], [0], 'only the in-frustum endpoint samples'); + renderer.destroy(); +}); + +test('a low-angle cached roof stays visible when range endpoints fail different tests', (t) => { + installDom(t); + t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', () => ({ x: 400, y: 380 })); + // Camera 1 m above the ellipsoid, heading east, pitched 25 degrees down. + const pitch = Cesium.Math.toRadians(25); + const camera = { + positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 1), + directionWC: new Cesium.Cartesian3(-Math.sin(pitch), Math.cos(pitch), 0), + upWC: new Cesium.Cartesian3(Math.cos(pitch), Math.sin(pitch), 0), + positionCartographic: { height: 1 }, + frustum: squareFrustum(), + }; + const roofLon = 4000 / 111319.49; + let samples = 0; + const postRender = new Cesium.Event(); + const scene = { + camera, + canvas: { width: 800, height: 800 }, + postRender, + clampToHeightSupported: true, + clampToHeight() { + samples++; + return Cesium.Cartesian3.fromDegrees(roofLon, 0, 20); + }, + }; + // Sanity: height 0 is beyond the horizon and 9000 m is behind the camera, + // while the 20 m roof itself is in front and above the horizon. + const occluder = new Cesium.EllipsoidalOccluder(Cesium.Ellipsoid.WGS84, camera.positionWC); + const ahead = (h) => { + const p = Cesium.Cartesian3.fromDegrees(roofLon, 0, h); + const v = Cesium.Cartesian3.subtract(p, camera.positionWC, new Cesium.Cartesian3()); + return Cesium.Cartesian3.dot(v, camera.directionWC) > 0; + }; + assert.equal(occluder.isPointVisible(Cesium.Cartesian3.fromDegrees(roofLon, 0, 0)), false); + assert.equal(ahead(9000), false); + assert.equal(ahead(20), true); + assert.equal(occluder.isPointVisible(Cesium.Cartesian3.fromDegrees(roofLon, 0, 20)), true); + + const renderer = createScreenAnnotationRenderer({ scene, camera }); + renderer.add({ id: 'roof', type: 'label', label: 'Roof', anchor: { lon: roofLon, lat: 0 } }); + const { group } = findAnnotationGroup(globalThis.document); + assert.equal(samples, 1, 'the unknown height is sampled, not culled'); + assert.equal(group.style.display, ''); + for (let i = 0; i < 5; i++) postRender.raiseEvent(); + assert.equal(samples, 1, 'the settled height is reused'); + assert.equal(group.style.display, '', 'the cached roof point is tested and shown'); + renderer.destroy(); +}); + +test('height retries beyond the first budget are served under sparse passes', (t) => { + installDom(t); + t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 1000 }); + t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', () => ({ x: 100, y: 100 })); + const camera = { + positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 100000), + directionWC: new Cesium.Cartesian3(-1, 0, 0), + positionCartographic: { height: 100000 }, + }; + const lons = Array.from({ length: 33 }, (_, i) => Number(((i + 1) / 1000).toFixed(3))); + const last = lons.at(-1); + let tilesReady = false; + let pass = []; + const postRender = new Cesium.Event(); + const scene = { + camera, + canvas: { width: 800, height: 600 }, + postRender, + clampToHeightSupported: true, + clampToHeight(world) { + const lon = sampledLon(world); + pass.push(lon); + return tilesReady && lon === last ? Cesium.Cartesian3.fromDegrees(lon, 0, 12) : undefined; + }, + }; + const renderer = createScreenAnnotationRenderer({ scene, camera }); + for (const lon of lons) { + renderer.add({ id: `p${lon}`, type: 'label', label: 'P', anchor: { lon, lat: 0 } }); + } + assert.ok(pass.includes(last), 'every point gets its initial miss'); + tilesReady = true; // tiles under the final point arrive after its miss + const lastSamples = []; + for (let i = 0; i < 4; i++) { + t.mock.timers.tick(1000); + pass = []; + postRender.raiseEvent(); + assert.ok(pass.length <= 32, `pass ${i} keeps the 32-sample budget`); + lastSamples.push(pass.filter((lon) => lon === last).length); + } + assert.ok(lastSamples.slice(0, 2).includes(1), 'the 33rd point is served within two passes'); + assert.equal(lastSamples.at(-1), 0, 'and then stays settled'); + // Points refused in one pass are served first in the next: every point is + // retried within any two consecutive sparse passes. + pass = []; + t.mock.timers.tick(1000); + postRender.raiseEvent(); + const firstPass = pass; + pass = []; + t.mock.timers.tick(1000); + postRender.raiseEvent(); + const served = new Set([...firstPass, ...pass]); + for (const lon of lons.slice(0, -1)) assert.ok(served.has(lon), `${lon} retried`); + renderer.destroy(); +}); From 0781b4a8de501095df0107229a99927c01b8b29f Mon Sep 17 00:00:00 2001 From: Said Turksever Date: Tue, 10 Nov 2026 23:54:40 +0000 Subject: [PATCH 07/13] fix(annotations): repair the main merge and port the sampling tests (#1277) The last merge of main kept four tests on a DOM harness that main had removed, so they threw ReferenceError and CI failed. They now run on the store-backed board. The merge had also dropped main's empty-board publish, the leaving/byKey clear in destroy, and three unrelated CURRENT-STATE paragraphs; all are restored. The projection now builds each height-cache key once per point, and the changelog entry says what changed. --- changelog.d/1277-annotation-issue-fix.md | 5 +- docs/CURRENT-STATE.md | 18 ++++++ src/annotations/screenAnnotationRenderer.js | 20 ++++--- .../screenAnnotationRenderer.test.mjs | 58 +++++++++---------- 4 files changed, 64 insertions(+), 37 deletions(-) diff --git a/changelog.d/1277-annotation-issue-fix.md b/changelog.d/1277-annotation-issue-fix.md index 6f17992372..ba5eb97f3b 100644 --- a/changelog.d/1277-annotation-issue-fix.md +++ b/changelog.d/1277-annotation-issue-fix.md @@ -1 +1,4 @@ -- Cull and budget surface height sampling (asturksever, #1277). +- Stop screen annotations sampling surface height for marks that are hidden, + behind the camera or over the horizon. Visible marks still waiting for + terrain share 32 samples per projection pass and retry once a second, so a + large board no longer stalls the frame (asturksever, #1277). diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 45562707da..2c919bcbf9 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -127,6 +127,24 @@ broader suffix variants. Follow-ups retain boundary provenance, and cancelled lookups preserve the previous analyst cohort and boundary source. Navigation search keeps a successful geocode, with no search or view-based region recovery. +Manager-owned periodic network updates pause while the document is hidden. Returning to a visible tab runs one overdue update per enabled layer without overlapping an active refresh and restarts that layer's polling schedule from the return, so the next poll follows one interval later whether or not the catch-up update succeeds; explicit refresh requests remain available. Transit also defers camera-driven feed admission while hidden and rechecks coverage on return. Visibility listeners are released with their polling intervals. + +Overpass reserves each normalized query before its disk-cache lookup. The +initial disk lookup, upstream quota admission, fetching and memory publication +are coalesced under that reservation. A caller that joined a reservation +rejected by another client's quota retries admission with its own quota. +Stale fallback runs per response after the reservation is released, and disk +writes finish asynchronously. Settled and rejected reservations are removed +only while they still own their map entry. + +External ALPR tags, surveillance-tool fields, voice context text and compact +analyst strings become one line of at most 180 characters (scene labels: 120). +Empty ALPR values stay null, and the cap never splits a surrogate pair. +Canonical analyst identifiers such as `id` and `routeId` stay unchanged, because +voice follow-ups match on them and bikeshare uses the raw station name as its +ID. The text is still untrusted: normalization does not prevent prompt +injection. + Screen annotations skip hidden records and, before surface sampling, reject an unsettled anchor only when its whole accepted height range (-430 to 9000 m) is behind the camera or below the globe horizon; a settled height is tested as the diff --git a/src/annotations/screenAnnotationRenderer.js b/src/annotations/screenAnnotationRenderer.js index 48e64ddb88..301402f983 100644 --- a/src/annotations/screenAnnotationRenderer.js +++ b/src/annotations/screenAnnotationRenderer.js @@ -153,9 +153,8 @@ export function createScreenAnnotationRenderer( // Best-effort surface height under a coordinate (clamps onto the 3D tiles). // Returns 0 until the tile loads, then caches the validated height. // canSample=false returns the cached height (or 0) without surface sampling. - function groundHeight(lon, lat, canSample = true) { - const key = heightKey(lon, lat); - const cached = heightCache.get(key); + // `key` and `cached` are the caller's cache lookup for this coordinate. + function groundHeight(lon, lat, key, cached, canSample = true) { if (cached && cached.settled) { // Mark hot for this frame + bump to most-recently-used so heights for live // marks survive eviction while places we've navigated away from age out. @@ -413,9 +412,11 @@ export function createScreenAnnotationRenderer( // A settled height is tested as the actual point below. An unknown height // is rejected before GPU-backed surface sampling only when the whole // accepted height range is proven hidden by one constraint. + const key = heightKey(lon, lat); + const cached = heightCache.get(key); let height; - if (heightCache.get(heightKey(lon, lat))?.settled) { - height = groundHeight(lon, lat); + if (cached?.settled) { + height = groundHeight(lon, lat, key, cached); } else { if (heightRangeHidden(lon, lat)) return null; // The frustum restricts sampling only; an endpoint outside it still @@ -431,7 +432,7 @@ export function createScreenAnnotationRenderer( const inFrustum = cullingVolume?.computeVisibility(heightBounds) !== Cesium.Intersect.OUTSIDE; - height = groundHeight(lon, lat, inFrustum); + height = groundHeight(lon, lat, key, cached, inFrustum); } const world = Cesium.Cartesian3.fromDegrees(lon, lat, height); // Reject points behind the camera (they produce wrapped/extreme coords). @@ -552,7 +553,10 @@ export function createScreenAnnotationRenderer( } function projectAll() { - if (!records.size) return; + if (!records.size) { + publish(); + return; + } // Serve the oldest refused keys first; the rest of the budget is open. heightReserved = new Set(); for (const key of heightQueue) { @@ -931,6 +935,8 @@ export function createScreenAnnotationRenderer( store.publish(null); } records.clear(); + leaving.clear(); + byKey.clear(); clearHeights(); } diff --git a/src/annotations/screenAnnotationRenderer.test.mjs b/src/annotations/screenAnnotationRenderer.test.mjs index ae7cbcef2c..3dec5314e0 100644 --- a/src/annotations/screenAnnotationRenderer.test.mjs +++ b/src/annotations/screenAnnotationRenderer.test.mjs @@ -584,17 +584,7 @@ test('a mark hidden from Draw is not drawn or placed, and comes back when shown' }); test('hidden and back-facing annotations do not sample; visible unresolved heights have bounded retries', (t) => { - const previous = globalThis.document; - const previousRaf = globalThis.requestAnimationFrame; - globalThis.document = fakeDocument(); - globalThis.requestAnimationFrame = (fn) => { - fn(); - return 1; - }; - t.after(() => { - globalThis.document = previous; - globalThis.requestAnimationFrame = previousRaf; - }); + const store = samplingBoard(t); t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 1000 }); t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', () => ({ x: 100, @@ -618,7 +608,7 @@ test('hidden and back-facing annotations do not sample; visible unresolved heigh }, requestRender() {}, }; - const renderer = createScreenAnnotationRenderer({ scene, camera }); + const renderer = samplingRenderer(store, scene); const mark = (id, lon) => ({ id, type: 'label', @@ -679,18 +669,29 @@ function sampledLon(world) { return Number(Cesium.Math.toDegrees(carto.longitude).toFixed(5)); } -function installDom(t) { - const previous = globalThis.document; +/** + * A board with no view mounted, for tests that count surface samples: the + * renderer projects on `add` and on each post-render event, and the store + * holds what it would draw. Animation frames run at once. + */ +function samplingBoard(t) { const previousRaf = globalThis.requestAnimationFrame; - globalThis.document = fakeDocument(); globalThis.requestAnimationFrame = (fn) => { fn(); return 1; }; t.after(() => { - globalThis.document = previous; globalThis.requestAnimationFrame = previousRaf; }); + return useScreenAnnotationsStore(createPinia()); +} + +/** The renderer under test, on the given board and scene. */ +function samplingRenderer(store, scene) { + return createScreenAnnotationRenderer( + { scene, camera: scene.camera, trackedEntity: null }, + { store, activeTrackedReadoutId: () => null }, + ); } function squareFrustum() { @@ -703,7 +704,7 @@ function squareFrustum() { } test('an arrow with one endpoint outside a real frustum keeps its visible connector', (t) => { - installDom(t); + const store = samplingBoard(t); t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', (_scene, world) => sampledLon(world) > 0.1 ? { x: 1100, y: 400 } : { x: 400, y: 400 }, ); @@ -739,7 +740,7 @@ test('an arrow with one endpoint outside a real frustum keeps its visible connec volume.computeVisibility(new Cesium.BoundingSphere(far, 9500)), Cesium.Intersect.OUTSIDE, ); - const renderer = createScreenAnnotationRenderer({ scene, camera }); + const renderer = samplingRenderer(store, scene); renderer.add({ id: 'partial-arrow', type: 'arrow', @@ -748,16 +749,16 @@ test('an arrow with one endpoint outside a real frustum keeps its visible connec to: { lon: 0.2, lat: 0 }, }); postRender.raiseEvent(); - const { group } = findAnnotationGroup(globalThis.document); - assert.equal(group.style.display, '', 'the arrow stays drawn'); - const path = group.children.find((child) => child.classList.contains('gev-anno-arrow')); - assert.match(path.getAttribute('d'), /^M 400\.0 400\.0 Q .* 1100\.0 400\.0$/); + const [mark] = store.board.marks; + assert.equal(mark.display, '', 'the arrow stays drawn'); + const path = mark.children.find((child) => child.attrs.class?.includes('gev-anno-arrow')); + assert.match(path.attrs.d, /^M 400\.0 400\.0 Q .* 1100\.0 400\.0$/); assert.deepEqual([...new Set(sampled)], [0], 'only the in-frustum endpoint samples'); renderer.destroy(); }); test('a low-angle cached roof stays visible when range endpoints fail different tests', (t) => { - installDom(t); + const store = samplingBoard(t); t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', () => ({ x: 400, y: 380 })); // Camera 1 m above the ellipsoid, heading east, pitched 25 degrees down. const pitch = Cesium.Math.toRadians(25); @@ -794,19 +795,18 @@ test('a low-angle cached roof stays visible when range endpoints fail different assert.equal(ahead(20), true); assert.equal(occluder.isPointVisible(Cesium.Cartesian3.fromDegrees(roofLon, 0, 20)), true); - const renderer = createScreenAnnotationRenderer({ scene, camera }); + const renderer = samplingRenderer(store, scene); renderer.add({ id: 'roof', type: 'label', label: 'Roof', anchor: { lon: roofLon, lat: 0 } }); - const { group } = findAnnotationGroup(globalThis.document); assert.equal(samples, 1, 'the unknown height is sampled, not culled'); - assert.equal(group.style.display, ''); + assert.equal(store.board.marks[0].display, ''); for (let i = 0; i < 5; i++) postRender.raiseEvent(); assert.equal(samples, 1, 'the settled height is reused'); - assert.equal(group.style.display, '', 'the cached roof point is tested and shown'); + assert.equal(store.board.marks[0].display, '', 'the cached roof point is tested and shown'); renderer.destroy(); }); test('height retries beyond the first budget are served under sparse passes', (t) => { - installDom(t); + const store = samplingBoard(t); t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 1000 }); t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', () => ({ x: 100, y: 100 })); const camera = { @@ -830,7 +830,7 @@ test('height retries beyond the first budget are served under sparse passes', (t return tilesReady && lon === last ? Cesium.Cartesian3.fromDegrees(lon, 0, 12) : undefined; }, }; - const renderer = createScreenAnnotationRenderer({ scene, camera }); + const renderer = samplingRenderer(store, scene); for (const lon of lons) { renderer.add({ id: `p${lon}`, type: 'label', label: 'P', anchor: { lon, lat: 0 } }); } From 40daecadbe0de7e2ca57ce559a3939a3104a4edd Mon Sep 17 00:00:00 2001 From: German Khokhlov Date: Thu, 19 Nov 2026 19:09:56 +0400 Subject: [PATCH 08/13] fix(annotations): keep an arrow whose unsampled far end is past the 0 m horizon (#1277) An endpoint outside the frustum is not sampled and projects at its 0 m stand-in height. The horizon test then judged that stand-in, so an arrow whose far end lies beyond the sea-level horizon but above it at its real height disappeared with its label. Such an endpoint now skips the point horizon test; the height-range test still drops endpoints that are provably hidden, and settled or in-frustum anchors keep the point test. Adds a regression with a real frustum and occluder (camera 100 m up, far end 56 km away on 100 m terrain). CURRENT-STATE and the changelog now say the 32-sample budget applies per projection pass, and the redundant helper comment in the test is gone. --- changelog.d/1277-annotation-issue-fix.md | 5 +- docs/CURRENT-STATE.md | 13 +-- src/annotations/screenAnnotationRenderer.js | 13 ++- .../screenAnnotationRenderer.test.mjs | 94 ++++++++++++++++++- 4 files changed, 112 insertions(+), 13 deletions(-) diff --git a/changelog.d/1277-annotation-issue-fix.md b/changelog.d/1277-annotation-issue-fix.md index ba5eb97f3b..29437bebd8 100644 --- a/changelog.d/1277-annotation-issue-fix.md +++ b/changelog.d/1277-annotation-issue-fix.md @@ -1,4 +1,5 @@ - Stop screen annotations sampling surface height for marks that are hidden, behind the camera or over the horizon. Visible marks still waiting for - terrain share 32 samples per projection pass and retry once a second, so a - large board no longer stalls the frame (asturksever, #1277). + terrain share 32 samples per projection pass and retry once a second, so + drawing a large board no longer stalls the app for seconds (asturksever, + #1277). diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index c4514ceb9c..2976dd53af 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -148,12 +148,13 @@ injection. Screen annotations skip hidden records and, before surface sampling, reject an unsettled anchor only when its whole accepted height range (-430 to 9000 m) is behind the camera or below the globe horizon; a settled height is tested as the -actual point. Anchors outside the conservative frustum still project at their -cached or zero height, so a partly visible arrow keeps its connector, but do -not sample. Unresolved visible heights share a 32-sample projection-pass budget, -served oldest-refused first, retry at most once per second per anchor on -rendered frames, and retain no extra timer or listener. Validated heights remain -settled in the bounded cache. +actual point. Anchors outside the conservative frustum do not sample and still +project at their cached or zero height, without the horizon test that this +stand-in height cannot decide, so a partly visible arrow keeps its connector. +Unresolved visible heights share a 32-sample budget per projection pass (each +board change and each rendered frame runs one), served oldest-refused first, +retry at most once per second per anchor, and retain no extra timer or +listener. Validated heights remain settled in the bounded cache. Terrain height requests accept at most 64 points, matching the browser service's existing batch size and one bounded upstream chunk. Larger requests return HTTP diff --git a/src/annotations/screenAnnotationRenderer.js b/src/annotations/screenAnnotationRenderer.js index 301402f983..8c0d724e79 100644 --- a/src/annotations/screenAnnotationRenderer.js +++ b/src/annotations/screenAnnotationRenderer.js @@ -415,13 +415,15 @@ export function createScreenAnnotationRenderer( const key = heightKey(lon, lat); const cached = heightCache.get(key); let height; + let horizonTest = true; if (cached?.settled) { height = groundHeight(lon, lat, key, cached); } else { if (heightRangeHidden(lon, lat)) return null; // The frustum restricts sampling only; an endpoint outside it still - // projects (at its cached or zero height) so a partly visible arrow, - // route or ring keeps its on-screen connector and label. + // projects (at its cached or zero height, without the horizon test) + // so a partly visible arrow, route or ring keeps its on-screen + // connector and label. Cesium.Cartesian3.fromDegrees( lon, lat, @@ -433,14 +435,17 @@ export function createScreenAnnotationRenderer( cullingVolume?.computeVisibility(heightBounds) !== Cesium.Intersect.OUTSIDE; height = groundHeight(lon, lat, key, cached, inFrustum); + horizonTest = inFrustum; } const world = Cesium.Cartesian3.fromDegrees(lon, lat, height); // Reject points behind the camera (they produce wrapped/extreme coords). Cesium.Cartesian3.subtract(world, scene.camera.positionWC, scratchDir); if (Cesium.Cartesian3.dot(scratchDir, scene.camera.directionWC) <= 0) return null; - // Reject points beyond the globe horizon. - if (!occluder.isPointVisible(world)) return null; + // Reject points beyond the globe horizon. An unsampled stand-in height + // outside the frustum cannot decide it: the range test above found no + // proof that the real height is hidden. + if (horizonTest && !occluder.isPointVisible(world)) return null; const win = Cesium.SceneTransforms.worldToWindowCoordinates( scene, world, diff --git a/src/annotations/screenAnnotationRenderer.test.mjs b/src/annotations/screenAnnotationRenderer.test.mjs index 3dec5314e0..c6f2afe06d 100644 --- a/src/annotations/screenAnnotationRenderer.test.mjs +++ b/src/annotations/screenAnnotationRenderer.test.mjs @@ -686,7 +686,6 @@ function samplingBoard(t) { return useScreenAnnotationsStore(createPinia()); } -/** The renderer under test, on the given board and scene. */ function samplingRenderer(store, scene) { return createScreenAnnotationRenderer( { scene, camera: scene.camera, trackedEntity: null }, @@ -757,6 +756,99 @@ test('an arrow with one endpoint outside a real frustum keeps its visible connec renderer.destroy(); }); +// An arrow whose far end lies outside the frustum (so it is not sampled) and +// beyond the horizon at the 0 m stand-in height, but above it at its real +// 100 m height, keeps its connector and label. +test('an arrow whose unsampled far end is past the 0 m horizon keeps its connector', (t) => { + const previousRaf = globalThis.requestAnimationFrame; + globalThis.requestAnimationFrame = (fn) => { + fn(); + return 1; + }; + t.after(() => { + globalThis.requestAnimationFrame = previousRaf; + }); + const W = 800; + const H = 800; + const half = Cesium.Math.toRadians(30); + const frustum = new Cesium.PerspectiveFrustum(); + frustum.fov = 2 * half; + frustum.aspectRatio = 1; + frustum.near = 1; + frustum.far = 1e8; + // 100 m above the ellipsoid at (0, 0), level, looking due east. + const camera = { + positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 100), + directionWC: new Cesium.Cartesian3(0, 1, 0), + upWC: new Cesium.Cartesian3(1, 0, 0), + positionCartographic: { height: 100 }, + frustum, + }; + // A real perspective projection matching the frustum above. + t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', (_scene, world, result) => { + const right = Cesium.Cartesian3.cross(camera.directionWC, camera.upWC, new Cesium.Cartesian3()); + const v = Cesium.Cartesian3.subtract(world, camera.positionWC, new Cesium.Cartesian3()); + const z = Cesium.Cartesian3.dot(v, camera.directionWC); + const out = result || new Cesium.Cartesian2(); + out.x = ((Cesium.Cartesian3.dot(v, right) / z / Math.tan(half) + 1) / 2) * W; + out.y = ((1 - Cesium.Cartesian3.dot(v, camera.upWC) / z / Math.tan(half)) / 2) * H; + return out; + }); + // Near end 2 km east; far end 56 km away, 50 degrees north of the view axis. + const near = { lon: Number((2000 / 111319.49).toFixed(5)), lat: 0 }; + const bearing = Cesium.Math.toRadians(50); + const far = { + lon: Number(((56000 * Math.cos(bearing)) / 111319.49).toFixed(5)), + lat: Number(((56000 * Math.sin(bearing)) / 110574).toFixed(5)), + }; + const surface = { [near.lon]: 10, [far.lon]: 100 }; + const postRender = new Cesium.Event(); + const scene = { + camera, + canvas: { width: W, height: H }, + postRender, + clampToHeightSupported: true, + clampToHeight(world) { + const c = Cesium.Cartographic.fromCartesian(world); + const h = surface[Number(Cesium.Math.toDegrees(c.longitude).toFixed(5))]; + return h === undefined ? undefined : Cesium.Cartesian3.fromRadians(c.longitude, c.latitude, h); + }, + }; + + // Preconditions: the scenario is the one described above. + const occluder = new Cesium.EllipsoidalOccluder(Cesium.Ellipsoid.WGS84, camera.positionWC); + const farAt = (h) => Cesium.Cartesian3.fromDegrees(far.lon, far.lat, h); + assert.equal(occluder.isPointVisible(farAt(100)), true, 'far end above the horizon at 100 m'); + assert.equal(occluder.isPointVisible(farAt(0)), false, 'far end past the horizon at 0 m'); + const volume = frustum.computeCullingVolume(camera.positionWC, camera.directionWC, camera.upWC); + assert.equal( + volume.computeVisibility(new Cesium.BoundingSphere(farAt(0), 9500)), + Cesium.Intersect.OUTSIDE, + 'far end outside the frustum plus the 9.5 km sampling sphere', + ); + const farWin = Cesium.SceneTransforms.worldToWindowCoordinates(scene, farAt(100)); + assert.ok(farWin.x > -W && farWin.x < 0, 'far end off-screen left, inside [-w, 2w]'); + + const store = useScreenAnnotationsStore(createPinia()); + const renderer = createScreenAnnotationRenderer( + { scene, camera, trackedEntity: null }, + { store, activeTrackedReadoutId: () => null }, + ); + t.after(() => renderer.destroy()); + renderer.add({ + id: 'long-arrow', + type: 'arrow', + label: 'Ridge', + anchor: near, + to: far, + }); + for (let i = 0; i < 3; i++) postRender.raiseEvent(); + const [mark] = store.board.marks; + assert.equal(mark.display, '', 'the arrow stays drawn'); + const path = mark.children.find((child) => child.attrs.class?.includes('gev-anno-arrow')); + assert.match(path.attrs.d, /^M 400\.0 4\d\d\.\d Q /, 'the connector starts at the on-screen end'); +}); + test('a low-angle cached roof stays visible when range endpoints fail different tests', (t) => { const store = samplingBoard(t); t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', () => ({ x: 400, y: 380 })); From 0699876e4e23c4c50a4f46f194252f703b29827b Mon Sep 17 00:00:00 2001 From: German Khokhlov Date: Thu, 19 Nov 2026 19:59:01 +0400 Subject: [PATCH 09/13] fix(cctv): keep main's HLS leases and test them through the middleware Drop the per-peer lease budget and the lease-to-address binding. Main's keyless same-site gate already refuses cross-site media requests, while the budget capped a shared address (Docker gateway, reverse proxy, NAT) at 8 leases across both sessions and still let one address hold both. A lease now keeps working when its viewer reconnects from a new address. Add a middleware test that drives the HLS playlist, segment and DELETE for viewers on one shared address, on distinct addresses and after an address change, and fold the media cases (segment read, DELETE, no catalog request) into the cross-site table test. Remove the redundant puppeteer flag, the CURRENT-STATE paragraph and the changelog fragment, which no longer describe a change. --- changelog.d/1267-cctv-session-admission.md | 3 - docs/CURRENT-STATE.md | 7 - scripts/qa-cctv-v2.mjs | 1 - server/providers/cctv.js | 17 +- server/providers/cctv/stream.js | 59 ++----- src/data/cctvHlsMiddleware.test.mjs | 174 +++++++++++++++++++++ src/data/cctvHlsStream.test.mjs | 37 ----- src/data/cctvMediaFeedType.test.mjs | 76 +++------ 8 files changed, 212 insertions(+), 162 deletions(-) delete mode 100644 changelog.d/1267-cctv-session-admission.md create mode 100644 src/data/cctvHlsMiddleware.test.mjs diff --git a/changelog.d/1267-cctv-session-admission.md b/changelog.d/1267-cctv-session-admission.md deleted file mode 100644 index c331222e70..0000000000 --- a/changelog.d/1267-cctv-session-admission.md +++ /dev/null @@ -1,3 +0,0 @@ -- Gate CCTV HLS media requests before session work, bind leases to the direct - peer, and bound per-peer leases across shared sessions (asturksever, #1267). -- Keep headful CCTV QA rendering active when its window is occluded (asturksever, #1267). diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index a8a24d54a9..51dd971fe0 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -185,13 +185,6 @@ The browser continues to split larger workloads into sequential 64-point request Traffic holds continuous rendering only while enabled with shown animated dots, a pulsing jam heat-line, or road lines whose geometry is still building (replaced lines stay drawn until their successors are ready, so a rebuild never blinks; one set builds at a time, and of the rebuilds asked for meanwhile only the newest runs, when that build finishes; turning lines off removes them at once); hidden dots (`dots` off) and settled flow lines hold nothing. Empty and high-altitude views release the hold. A failed load leaves no hold only when no animated content is retained: if an earlier load succeeded, ingestion keeps its animated points and the hold stays. Population admission reacquires the hold and resets animation time. Clear, disable, and destroy also release it. Retained fading dots keep animation alive until they are removed. When the last point leaves mid height correction, the correction is settled at once, before the hold is released, so it cannot keep the layer reporting loading. -CCTV live-media requests are same-site gated before catalog or media work, including -HLS renewal, segment reads and DELETE cleanup. HLS leases belong to their socket -peer (IPv4-mapped IPv6 is normalized), with eight leases per peer across the two -global sessions. Peers behind the same NAT share that budget; this is resource -admission, not authentication. Native same-origin video and range requests remain -supported. - Shared distance checks use `src/geoDistance.js` with `{ lat, lon }` points and the IUGG mean spherical Earth radius, 6371.0088 km. `greatCircleKm` is canonical; `greatCircleMeters` is its exact metre conversion. Missing, diff --git a/scripts/qa-cctv-v2.mjs b/scripts/qa-cctv-v2.mjs index 6758001ef7..84eb09f6c1 100644 --- a/scripts/qa-cctv-v2.mjs +++ b/scripts/qa-cctv-v2.mjs @@ -452,7 +452,6 @@ async function main() { ...(HEADFUL ? [] : ['--use-gl=angle', '--use-angle=swiftshader']), '--disable-dev-shm-usage', '--disable-web-security', - '--disable-backgrounding-occluded-windows', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--window-size=1280,800', diff --git a/server/providers/cctv.js b/server/providers/cctv.js index 3153012b83..5b5222a058 100644 --- a/server/providers/cctv.js +++ b/server/providers/cctv.js @@ -264,10 +264,6 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) { // keyless gate keeps the routes reachable behind a reverse proxy; the // key-bearing Street View fallback below has its own check. if (admitSameSiteKeyless(req, res)) return; - const clientId = String(req.socket?.remoteAddress || 'unknown').replace( - /^::ffff:/, - '', - ); const sources = await getCctvSources(); const sourceById = new Map( sources.map((source) => [source.id, source]), @@ -379,7 +375,7 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) { return; } if (req.method === 'DELETE') { - if (leaseId) puller.release(cameraId, leaseId, clientId); + if (leaseId) puller.release(cameraId, leaseId); res.writeHead(204); res.end(); return; @@ -409,7 +405,6 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) { url.searchParams.get('session'), Number(match[3]), leaseId, - clientId, ); res.writeHead(body ? 200 : 404, { 'Content-Type': 'video/mp2t', @@ -421,15 +416,10 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) { const downstream = watchDownstreamClose(res); let entry; const cancelPending = () => { - if (entry) puller.release(cameraId, leaseId, clientId); + if (entry) puller.release(cameraId, leaseId); }; try { - entry = await puller.ensure( - cameraId, - mediaUrl, - leaseId, - clientId, - ); + entry = await puller.ensure(cameraId, mediaUrl, leaseId); if (downstream.closed) { cancelPending(); return; @@ -443,7 +433,6 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) { entry, cameraId, leaseId, - clientId, ); if (downstream.closed) return; if (!playlist) throw new Error('Stream unavailable'); diff --git a/server/providers/cctv/stream.js b/server/providers/cctv/stream.js index eb5477f762..4e37cda208 100644 --- a/server/providers/cctv/stream.js +++ b/server/providers/cctv/stream.js @@ -4,7 +4,6 @@ import { randomUUID } from 'node:crypto'; export const HLS_LIMITS = Object.freeze({ sessions: 2, leasesPerSession: 8, - leasesPerClient: 8, playlistBytes: 256 * 1024, // High-resolution cameras can exceed 4 MiB in a single ten-second TS segment. // Retained data still shares the independent 24 MiB session budget below. @@ -141,37 +140,25 @@ export function createHlsPuller({ entry.upstream.clear(); entry.bytes = 0; }; - const release = (cameraId, leaseId, clientId = 'legacy') => { + const release = (cameraId, leaseId) => { const entry = active.get(cameraId); const lease = entry?.leases.get(leaseId); - if (!lease || lease.clientId !== clientId) return; + if (!lease) return; clearTimeout(lease.timer); entry.leases.delete(leaseId); if (!entry.leases.size) stop(cameraId, entry.token); }; - const touch = (entry, leaseId, create = false, clientId = 'legacy') => { + const touch = (entry, leaseId, create = false) => { let lease = entry.leases.get(leaseId); - if (lease && lease.clientId !== clientId) - throw new Error('HLS lease belongs to another client'); if (!lease) { - const clientLeases = [...active.values()].reduce( - (count, session) => - count + - [...session.leases.values()].filter( - (item) => item.clientId === clientId, - ).length, - 0, - ); - if (clientLeases >= limits.leasesPerClient) - throw new Error('HLS client lease capacity reached'); if (!create || entry.leases.size >= limits.leasesPerSession) throw new Error('HLS lease capacity reached'); - lease = { clientId }; + lease = {}; entry.leases.set(leaseId, lease); } clearTimeout(lease.timer); lease.timer = setTimeout( - () => release(entry.cameraId, leaseId, clientId), + () => release(entry.cameraId, leaseId), limits.idleMs, ); lease.timer.unref?.(); @@ -263,12 +250,7 @@ export function createHlsPuller({ } } }; - const ensure = async ( - cameraId, - url, - leaseId = 'legacy', - clientId = 'legacy', - ) => { + const ensure = async (cameraId, url, leaseId = 'legacy') => { if (closed) throw new Error('HLS service closed'); sameOriginHlsUrl(url, url); let entry = active.get(cameraId); @@ -277,7 +259,7 @@ export function createHlsPuller({ entry = null; } if (entry) { - touch(entry, leaseId, true, clientId); + touch(entry, leaseId, true); return entry; } // Reserve synchronously, before any await: concurrent creation is singleflight. @@ -299,8 +281,8 @@ export function createHlsPuller({ pendingDiscontinuity: false, discontinuitiesRemoved: 0, }; - touch(entry, leaseId, true, clientId); active.set(cameraId, entry); + touch(entry, leaseId, true); entry.polling = poll(entry); return entry; }; @@ -312,14 +294,9 @@ export function createHlsPuller({ } return false; }; - const buildPlaylist = async ( - entry, - cameraId, - leaseId = 'legacy', - clientId = 'legacy', - ) => { + const buildPlaylist = async (entry, cameraId, leaseId = 'legacy') => { if (entry.stopping || entry.segments.size < 2) return null; - touch(entry, leaseId, false, clientId); + touch(entry, leaseId); const segments = [...entry.segments.values()].sort((a, b) => a.seq - b.seq); const lines = [ '#EXTM3U', @@ -343,22 +320,12 @@ export function createHlsPuller({ } return lines.join('\n') + '\n'; }; - const getSegment = ( - cameraId, - token, - seq, - leaseId = 'legacy', - clientId = 'legacy', - ) => { + const getSegment = (cameraId, token, seq, leaseId = 'legacy') => { const entry = active.get(cameraId); - if ( - !entry || - entry.token !== token || - entry.leases.get(leaseId)?.clientId !== clientId - ) + if (!entry || entry.token !== token || !entry.leases.has(leaseId)) return null; const body = entry.segments.get(seq)?.body; - if (body) touch(entry, leaseId, false, clientId); + if (body) touch(entry, leaseId); return body || null; }; const shutdown = async () => { diff --git a/src/data/cctvHlsMiddleware.test.mjs b/src/data/cctvHlsMiddleware.test.mjs new file mode 100644 index 0000000000..301c9796e9 --- /dev/null +++ b/src/data/cctvHlsMiddleware.test.mjs @@ -0,0 +1,174 @@ +// Live HLS through the real /api/cctv middleware: playlist, segment and +// release. HLS leases are random per-playback ids, not bound to the socket +// address, so viewers who share one address (a Docker bridge gateway, a reverse +// proxy, NAT) get the whole per-session budget, and a viewer whose address +// changes mid-playback keeps its lease. +// +// Run with: npm test (node --test) +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { cctvProxy } from '../../server/providers/cctv.js'; + +const camera = (id) => ({ + id, + name: id, + lat: 30.27, + lon: -97.74, + feedType: 'hls', + url: `https://cams.upstream.invalid/${id}/list.m3u8`, +}); +const PLAYLIST = + '#EXTM3U\n#EXT-X-MEDIA-SEQUENCE:12\n#EXTINF:2,\na.ts\n#EXTINF:2,\nb.ts\n#EXTINF:2,\nc.ts\n'; +const lease = (index) => + `00000000-0000-4000-8000-${String(index).padStart(12, '0')}`; + +/** Collects what a handler wrote, the way a Node ServerResponse would. */ +function recordingResponse() { + const chunks = []; + let finished; + const done = new Promise((resolve) => { + finished = resolve; + }); + const res = { + statusCode: 0, + headers: {}, + writableEnded: false, + body: '', + writeHead(status, headers) { + res.statusCode = status; + res.headers = { ...res.headers, ...headers }; + }, + setHeader(name, value) { + res.headers[name] = value; + }, + write(chunk) { + chunks.push(Buffer.from(chunk)); + return true; + }, + end(chunk) { + if (chunk) chunks.push(Buffer.from(chunk)); + res.writableEnded = true; + res.body = Buffer.concat(chunks).toString('utf8'); + finished(); + }, + on() {}, + once() {}, + emit() {}, + destroy() {}, + }; + return { res, done }; +} + +/** Mount the provider over two HLS cameras whose upstream always answers. */ +function mount(t) { + const before = { + json: process.env.CCTV_SOURCES_JSON, + file: process.env.CCTV_SOURCES_FILE, + austin: process.env.CCTV_FORCE_AUSTIN, + }; + process.env.CCTV_SOURCES_JSON = JSON.stringify([ + camera('cam-a'), + camera('cam-b'), + ]); + process.env.CCTV_SOURCES_FILE = 'absent-source-file.json'; + process.env.CCTV_FORCE_AUSTIN = '0'; + const nativeFetch = globalThis.fetch; + // The puller binds fetch when cctvProxy() creates it, so mock first. + globalThis.fetch = async (url) => + new Response(String(url).endsWith('.m3u8') ? PLAYLIST : 'abc'); + let handler; + const closers = []; + cctvProxy().configureServer({ + httpServer: { on: (_event, fn) => closers.push(fn) }, + middlewares: { use: (_route, fn) => (handler = fn) }, + }); + t.after(() => { + for (const fn of closers) fn(); + globalThis.fetch = nativeFetch; + for (const [name, value] of [ + ['CCTV_SOURCES_JSON', before.json], + ['CCTV_SOURCES_FILE', before.file], + ['CCTV_FORCE_AUSTIN', before.austin], + ]) { + if (value === undefined) delete process.env[name]; + else process.env[name] = value; + } + }); + return async (url, remoteAddress, method = 'GET') => { + const { res, done } = recordingResponse(); + await handler( + { + url, + method, + headers: { host: 'localhost:4173', 'sec-fetch-site': 'same-origin' }, + socket: { remoteAddress }, + on() {}, + }, + res, + ); + await done; + return res; + }; +} + +/** Open a playlist and return the first segment path it lists. */ +async function openPlaylist(call, cameraId, leaseId, remoteAddress) { + const res = await call(`/media/${cameraId}?lease=${leaseId}`, remoteAddress); + assert.equal(res.statusCode, 200, `playlist ${cameraId} ${leaseId}`); + const segment = res.body + .split('\n') + .find((line) => line.startsWith('/api/cctv/media/')); + assert.ok(segment, 'the playlist lists a segment'); + return segment.replace('/api/cctv', ''); +} + +test('viewers on distinct addresses open, read and release their own leases', async (t) => { + const call = mount(t); + const viewers = Array.from({ length: 9 }, (_, index) => ({ + camera: index < 5 ? 'cam-a' : 'cam-b', + lease: lease(index), + // IPv4-mapped form, as a dual-stack listener reports it. + peer: `::ffff:192.168.1.${20 + index}`, + })); + for (const viewer of viewers) + viewer.segment = await openPlaylist( + call, + viewer.camera, + viewer.lease, + viewer.peer, + ); + for (const viewer of viewers) + assert.equal((await call(viewer.segment, viewer.peer)).statusCode, 200); + for (const viewer of viewers) { + const release = await call( + `/media/${viewer.camera}?lease=${viewer.lease}`, + viewer.peer, + 'DELETE', + ); + assert.equal(release.statusCode, 204); + } +}); + +test('viewers behind one shared address get every session slot', async (t) => { + const call = mount(t); + const shared = '::ffff:172.17.0.1'; + for (let index = 0; index < 8; index++) + await openPlaylist(call, 'cam-a', lease(index), shared); + const segment = await openPlaylist(call, 'cam-b', lease(8), shared); + assert.equal((await call(segment, shared)).statusCode, 200); +}); + +test('a lease keeps working after its viewer reconnects from another address', async (t) => { + const call = mount(t); + await openPlaylist(call, 'cam-a', lease(0), '192.168.1.20'); + const segment = await openPlaylist(call, 'cam-a', lease(0), '192.168.1.21'); + assert.equal((await call(segment, '192.168.1.21')).statusCode, 200); + const release = await call( + `/media/cam-a?lease=${lease(0)}`, + '192.168.1.21', + 'DELETE', + ); + assert.equal(release.statusCode, 204); + // Released from the new address: the same lease can no longer read segments. + assert.equal((await call(segment, '192.168.1.21')).statusCode, 404); +}); diff --git a/src/data/cctvHlsStream.test.mjs b/src/data/cctvHlsStream.test.mjs index 1dc7eb8785..4a5f4afbc9 100644 --- a/src/data/cctvHlsStream.test.mjs +++ b/src/data/cctvHlsStream.test.mjs @@ -294,40 +294,3 @@ test('an abandoned consumer expires while a renewed consumer keeps the session', assert.equal(entry.controller.signal.aborted, false); await manager.shutdown(); }); - -test('client lease ownership covers refresh, segments and release, with a bounded client budget', async (t) => { - const manager = createHlsPuller({ - limits: { ...HLS_LIMITS, leasesPerClient: 1, pollMs: 100000 }, - fetchImpl: async (url) => - new Response(url.endsWith('.m3u8') ? playlist : 'abc'), - }); - t.after(() => manager.shutdown()); - const entry = await manager.ensure('a', base, 'lease-a', 'peer-a'); - await manager.waitReady(entry); - await assert.rejects( - manager.ensure('a', base, 'lease-a', 'peer-b'), - /another client/, - ); - assert.equal( - manager.getSegment('a', entry.token, 0, 'lease-a', 'peer-b'), - null, - ); - await assert.rejects( - manager.buildPlaylist(entry, 'a', 'lease-a', 'peer-b'), - /another client/, - ); - manager.release('a', 'lease-a', 'peer-b'); - assert.equal(entry.leases.size, 1); - await assert.rejects( - manager.ensure('b', base, 'lease-b', 'peer-a'), - /client lease capacity/, - ); - assert.equal( - manager.stats().sessions, - 1, - 'failed admission reserves no session', - ); - await manager.ensure('b', base, 'lease-b', 'peer-b'); - manager.release('a', 'lease-a', 'peer-a'); - assert.equal(entry.stopping, true); -}); diff --git a/src/data/cctvMediaFeedType.test.mjs b/src/data/cctvMediaFeedType.test.mjs index dff7779699..1ff221cb65 100644 --- a/src/data/cctvMediaFeedType.test.mjs +++ b/src/data/cctvMediaFeedType.test.mjs @@ -155,9 +155,9 @@ function mount(t, respond) { }); assert.ok(handler, 'the CCTV provider must mount a middleware'); - const call = async (path, headers = {}) => { + const call = async (path, headers = {}, method = 'GET') => { const { res, done } = recordingResponse(); - await handler({ url: path, headers, method: 'GET', on() {} }, res); + await handler({ url: path, headers, method, on() {} }, res); await done; return res; }; @@ -401,24 +401,35 @@ test('every CCTV route refuses cross-site requests and admits the app itself', a }), ); const host = 'localhost:5173'; - const paths = [ - '/sources', - '/health', - `/stream/${STILL.id}`, - `/frame/${STILL.id}`, - `/media/${VIDEO.id}`, + const lease = '00000000-0000-4000-8000-000000000000'; + const routes = [ + ['GET', '/sources'], + ['GET', '/health'], + ['GET', `/stream/${STILL.id}`], + ['GET', `/frame/${STILL.id}`], + ['GET', `/media/${VIDEO.id}`], + ['GET', `/media/${VIDEO.id}/seg_0.ts?lease=${lease}`], + ['DELETE', `/media/${VIDEO.id}?lease=${lease}`], ]; + // A catalog refresh would fetch the live packs: a refused request must not + // start one. + process.env.CCTV_FORCE_AUSTIN = '1'; for (const headers of [ { host, 'sec-fetch-site': 'cross-site' }, { host, 'sec-fetch-site': 'same-site' }, { host, origin: 'https://elsewhere.example' }, { host, origin: 'null' }, ]) - for (const path of paths) { - const res = await app.call(path, headers); - assert.equal(res.statusCode, 403, `${path} ${JSON.stringify(headers)}`); + for (const [method, path] of routes) { + const res = await app.call(path, headers, method); + assert.equal( + res.statusCode, + 403, + `${method} ${path} ${JSON.stringify(headers)}`, + ); } assert.deepEqual(app.requests, [], 'a refused request reached an upstream'); + process.env.CCTV_FORCE_AUSTIN = '0'; for (const headers of [ { host, 'sec-fetch-site': 'same-origin' }, { host, origin: `http://${host}` }, @@ -528,46 +539,3 @@ test('a forwarded same-origin request reaches every CCTV route but not the Stree assert.equal(direct.body, 'street-view'); assert.equal(streetViewCalls(), 1); }); - -test('cross-site media creation, segment reads and release fail before any catalog or media fetch', async (t) => { - let handler; - const originalFetch = globalThis.fetch; - let calls = 0; - globalThis.fetch = async () => { - calls++; - throw new Error('must not fetch'); - }; - t.after(() => { - globalThis.fetch = originalFetch; - }); - cctvProxy().configureServer({ - middlewares: { - use: (_path, fn) => { - handler = fn; - }, - }, - }); - for (const headers of [ - { origin: 'https://foreign.example' }, - { origin: 'null' }, - { 'sec-fetch-site': 'cross-site' }, - { 'sec-fetch-site': 'same-site' }, - ]) { - for (const [method, url] of [ - ['GET', '/media/camera?lease=test'], - ['DELETE', '/media/camera?lease=test'], - ['GET', '/media/camera/seg_0.ts?lease=test'], - ]) { - const { res } = recordingResponse(); - res.setHeader = (name, value) => { - res.headers[name] = value; - }; - await handler( - { method, url, headers: { host: 'localhost:4173', ...headers } }, - res, - ); - assert.equal(res.statusCode, 403); - } - } - assert.equal(calls, 0); -}); From 4e1f004a83760b795e904c53ecb74ae47eefe848 Mon Sep 17 00:00:00 2001 From: Said Turksever Date: Thu, 19 Nov 2026 17:45:15 +0000 Subject: [PATCH 10/13] fix(cctv): keep a camera's health when an HLS viewer is refused for capacity A full lease or session budget fell into the general catch and marked the camera degraded, although its upstream was fine and other viewers were watching it. Capacity refusals now throw HlsCapacityError and still answer 503 with Retry-After, without touching health. Tests: fill all 16 lease slots from one shared address and pin the refusal of a ninth viewer and a third session, keep a second lease alive so the released-lease 404 is the lease check, and share recordingResponse between the two middleware test files. --- changelog.d/1267-cctv-hls-capacity-health.md | 3 + server/providers/cctv.js | 19 +++-- server/providers/cctv/stream.js | 7 +- src/data/cctvHlsMiddleware.test.mjs | 82 +++++++++----------- src/data/cctvMediaFeedType.test.mjs | 38 +-------- src/data/cctvRecordingResponse.mjs | 38 +++++++++ 6 files changed, 93 insertions(+), 94 deletions(-) create mode 100644 changelog.d/1267-cctv-hls-capacity-health.md create mode 100644 src/data/cctvRecordingResponse.mjs diff --git a/changelog.d/1267-cctv-hls-capacity-health.md b/changelog.d/1267-cctv-hls-capacity-health.md new file mode 100644 index 0000000000..0b79ea13c5 --- /dev/null +++ b/changelog.d/1267-cctv-hls-capacity-health.md @@ -0,0 +1,3 @@ +- Stop reporting a live HLS camera as degraded when a viewer is refused because + every lease or session slot is taken; the refusal still answers 503 with + `Retry-After` (Said Turksever, German Khokhlov, #1267). diff --git a/server/providers/cctv.js b/server/providers/cctv.js index 5b5222a058..57589ee787 100644 --- a/server/providers/cctv.js +++ b/server/providers/cctv.js @@ -18,7 +18,7 @@ import { import { sanitizeCctvRangeHeader } from './cctv/range.js'; import { admitSameSiteKeyless } from './common/same-site.js'; import { PROXY_SIGNALS } from '../../src/localRequestGate.mjs'; -import { createHlsPuller } from './cctv/stream.js'; +import { createHlsPuller, HlsCapacityError } from './cctv/stream.js'; import { isMlitRiverAdjustmentImage } from './cctv/worldCameras.js'; import { ottawaAuthorizedFrameUrl } from './cctv/ottawa.js'; import { googleServerApiKey } from './places/google-key.js'; @@ -449,13 +449,16 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) { 'X-CCTV-Session': entry.token, }); res.end(playlist); - } catch { - setHealth(cameraId, { - status: 'degraded', - sourceKind: 'fallback', - label: source?.provider || 'Configured source', - message: 'Live HLS unavailable', - }); + } catch (error) { + // A full lease or session budget says nothing about the source: + // leave the health its other viewers see untouched. + if (!(error instanceof HlsCapacityError)) + setHealth(cameraId, { + status: 'degraded', + sourceKind: 'fallback', + label: source?.provider || 'Configured source', + message: 'Live HLS unavailable', + }); if (!downstream.closed) { res.writeHead(503, { 'Content-Type': 'application/json', diff --git a/server/providers/cctv/stream.js b/server/providers/cctv/stream.js index 4e37cda208..8b4b046d6e 100644 --- a/server/providers/cctv/stream.js +++ b/server/providers/cctv/stream.js @@ -16,6 +16,9 @@ export const HLS_LIMITS = Object.freeze({ readyMs: 12000, }); +/** Every lease or session slot is taken: the source itself has not failed. */ +export class HlsCapacityError extends Error {} + /** Refuse redirects; count actual streamed bytes, including chunked responses. */ export async function fetchHlsBytes( url, @@ -152,7 +155,7 @@ export function createHlsPuller({ let lease = entry.leases.get(leaseId); if (!lease) { if (!create || entry.leases.size >= limits.leasesPerSession) - throw new Error('HLS lease capacity reached'); + throw new HlsCapacityError('HLS lease capacity reached'); lease = {}; entry.leases.set(leaseId, lease); } @@ -264,7 +267,7 @@ export function createHlsPuller({ } // Reserve synchronously, before any await: concurrent creation is singleflight. if (active.size >= limits.sessions) - throw new Error('HLS session capacity reached'); + throw new HlsCapacityError('HLS session capacity reached'); entry = { cameraId, url, diff --git a/src/data/cctvHlsMiddleware.test.mjs b/src/data/cctvHlsMiddleware.test.mjs index 301c9796e9..de446b4a47 100644 --- a/src/data/cctvHlsMiddleware.test.mjs +++ b/src/data/cctvHlsMiddleware.test.mjs @@ -8,6 +8,7 @@ import { test } from 'node:test'; import assert from 'node:assert/strict'; import { cctvProxy } from '../../server/providers/cctv.js'; +import { recordingResponse } from './cctvRecordingResponse.mjs'; const camera = (id) => ({ id, @@ -22,54 +23,16 @@ const PLAYLIST = const lease = (index) => `00000000-0000-4000-8000-${String(index).padStart(12, '0')}`; -/** Collects what a handler wrote, the way a Node ServerResponse would. */ -function recordingResponse() { - const chunks = []; - let finished; - const done = new Promise((resolve) => { - finished = resolve; - }); - const res = { - statusCode: 0, - headers: {}, - writableEnded: false, - body: '', - writeHead(status, headers) { - res.statusCode = status; - res.headers = { ...res.headers, ...headers }; - }, - setHeader(name, value) { - res.headers[name] = value; - }, - write(chunk) { - chunks.push(Buffer.from(chunk)); - return true; - }, - end(chunk) { - if (chunk) chunks.push(Buffer.from(chunk)); - res.writableEnded = true; - res.body = Buffer.concat(chunks).toString('utf8'); - finished(); - }, - on() {}, - once() {}, - emit() {}, - destroy() {}, - }; - return { res, done }; -} - -/** Mount the provider over two HLS cameras whose upstream always answers. */ +/** Mount the provider over three HLS cameras whose upstream always answers. */ function mount(t) { const before = { json: process.env.CCTV_SOURCES_JSON, file: process.env.CCTV_SOURCES_FILE, austin: process.env.CCTV_FORCE_AUSTIN, }; - process.env.CCTV_SOURCES_JSON = JSON.stringify([ - camera('cam-a'), - camera('cam-b'), - ]); + process.env.CCTV_SOURCES_JSON = JSON.stringify( + ['cam-a', 'cam-b', 'cam-c'].map(camera), + ); process.env.CCTV_SOURCES_FILE = 'absent-source-file.json'; process.env.CCTV_FORCE_AUSTIN = '0'; const nativeFetch = globalThis.fetch; @@ -82,6 +45,7 @@ function mount(t) { httpServer: { on: (_event, fn) => closers.push(fn) }, middlewares: { use: (_route, fn) => (handler = fn) }, }); + assert.ok(handler, 'the CCTV provider must mount a middleware'); t.after(() => { for (const fn of closers) fn(); globalThis.fetch = nativeFetch; @@ -149,13 +113,34 @@ test('viewers on distinct addresses open, read and release their own leases', as } }); -test('viewers behind one shared address get every session slot', async (t) => { +test('viewers behind one shared address get every slot, and no more', async (t) => { const call = mount(t); const shared = '::ffff:172.17.0.1'; - for (let index = 0; index < 8; index++) - await openPlaylist(call, 'cam-a', lease(index), shared); - const segment = await openPlaylist(call, 'cam-b', lease(8), shared); + const health = async (id) => + JSON.parse((await call('/health', shared)).body).cameras.find( + (entry) => entry.id === id, + ); + let segment; + for (let index = 0; index < 16; index++) + segment = await openPlaylist( + call, + index < 8 ? 'cam-a' : 'cam-b', + lease(index), + shared, + ); assert.equal((await call(segment, shared)).statusCode, 200); + // A ninth viewer of a full session and a third session are both refused, + // without reporting a camera whose upstream is fine as degraded. + for (const cameraId of ['cam-a', 'cam-c']) { + const refused = await call(`/media/${cameraId}?lease=${lease(16)}`, shared); + assert.equal(refused.statusCode, 503, cameraId); + assert.equal(refused.headers['Retry-After'], '2'); + } + assert.equal((await health('cam-a')).status, 'ok'); + assert.equal(await health('cam-c'), undefined); + // A released slot is free for the next viewer. + await call(`/media/cam-a?lease=${lease(0)}`, shared, 'DELETE'); + await openPlaylist(call, 'cam-a', lease(16), shared); }); test('a lease keeps working after its viewer reconnects from another address', async (t) => { @@ -163,12 +148,15 @@ test('a lease keeps working after its viewer reconnects from another address', a await openPlaylist(call, 'cam-a', lease(0), '192.168.1.20'); const segment = await openPlaylist(call, 'cam-a', lease(0), '192.168.1.21'); assert.equal((await call(segment, '192.168.1.21')).statusCode, 200); + // A second viewer keeps the session alive, so the 404 below is the released + // lease and not a stopped session. + const other = await openPlaylist(call, 'cam-a', lease(1), '192.168.1.30'); const release = await call( `/media/cam-a?lease=${lease(0)}`, '192.168.1.21', 'DELETE', ); assert.equal(release.statusCode, 204); - // Released from the new address: the same lease can no longer read segments. assert.equal((await call(segment, '192.168.1.21')).statusCode, 404); + assert.equal((await call(other, '192.168.1.30')).statusCode, 200); }); diff --git a/src/data/cctvMediaFeedType.test.mjs b/src/data/cctvMediaFeedType.test.mjs index 1ff221cb65..e3dfc60064 100644 --- a/src/data/cctvMediaFeedType.test.mjs +++ b/src/data/cctvMediaFeedType.test.mjs @@ -9,6 +9,7 @@ import { test } from 'node:test'; import assert from 'node:assert/strict'; import { Readable } from 'node:stream'; import { cctvProxy } from '../../server/providers/cctv.js'; +import { recordingResponse } from './cctvRecordingResponse.mjs'; const STILL = { id: 'still-fixture', @@ -63,43 +64,6 @@ function upstreamResponse({ status = 200, headers = {}, body = 'payload' }) { }; } -/** Collects what a handler wrote, the way a Node ServerResponse would. */ -function recordingResponse() { - const chunks = []; - let finished; - const done = new Promise((resolve) => { - finished = resolve; - }); - const res = { - statusCode: 0, - headers: {}, - writableEnded: false, - body: '', - writeHead(status, headers) { - res.statusCode = status; - res.headers = { ...res.headers, ...headers }; - }, - setHeader(name, value) { - res.headers[name] = value; - }, - write(chunk) { - chunks.push(Buffer.from(chunk)); - return true; - }, - end(chunk) { - if (chunk) chunks.push(Buffer.from(chunk)); - res.writableEnded = true; - res.body = Buffer.concat(chunks).toString('utf8'); - finished(); - }, - on() {}, - once() {}, - emit() {}, - destroy() {}, - }; - return { res, done }; -} - /** * Mount the real provider over the fixture cameras and answer every upstream * request from the supplied function. diff --git a/src/data/cctvRecordingResponse.mjs b/src/data/cctvRecordingResponse.mjs new file mode 100644 index 0000000000..5d45e38a8f --- /dev/null +++ b/src/data/cctvRecordingResponse.mjs @@ -0,0 +1,38 @@ +// Test support for the CCTV middleware tests: no test file of its own. + +/** Collects what a handler wrote, the way a Node ServerResponse would. */ +export function recordingResponse() { + const chunks = []; + let finished; + const done = new Promise((resolve) => { + finished = resolve; + }); + const res = { + statusCode: 0, + headers: {}, + writableEnded: false, + body: '', + writeHead(status, headers) { + res.statusCode = status; + res.headers = { ...res.headers, ...headers }; + }, + setHeader(name, value) { + res.headers[name] = value; + }, + write(chunk) { + chunks.push(Buffer.from(chunk)); + return true; + }, + end(chunk) { + if (chunk) chunks.push(Buffer.from(chunk)); + res.writableEnded = true; + res.body = Buffer.concat(chunks).toString('utf8'); + finished(); + }, + on() {}, + once() {}, + emit() {}, + destroy() {}, + }; + return { res, done }; +} From fdf7ed93ce117d2d7d025426d83d07c6f3e02bb2 Mon Sep 17 00:00:00 2001 From: German Khokhlov Date: Fri, 20 Nov 2026 03:39:09 +0400 Subject: [PATCH 11/13] fix(annotations): sample arrow, route and area points outside the view (#1277) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A point of an arrow, route or area outside the view frustum was not sampled and stood in at 0 m, so a partly visible arrow could hide, point at the wrong place or vanish behind the eye. Such points are sampled again within the 32-sample budget and the one-second retry, as on main; lone points outside the view still skip sampling. The 0 m stand-in exceptions are removed. Also from review: shared viewPlanes for transit and the renderer, a −430..9000 m segment test against the view planes, tighter tests and shorter docs. --- changelog.d/1277-annotation-issue-fix.md | 10 +- docs/CURRENT-STATE.md | 18 +- src/annotations/screenAnnotationRenderer.js | 155 +++--- .../screenAnnotationRenderer.test.mjs | 449 ++++++++++++------ src/geo/frustum.js | 20 + src/layers/transit/rendering.js | 19 +- src/testSupport/fakeCesiumScene.mjs | 2 +- 7 files changed, 408 insertions(+), 265 deletions(-) diff --git a/changelog.d/1277-annotation-issue-fix.md b/changelog.d/1277-annotation-issue-fix.md index 29437bebd8..cffd40a520 100644 --- a/changelog.d/1277-annotation-issue-fix.md +++ b/changelog.d/1277-annotation-issue-fix.md @@ -1,5 +1,5 @@ -- Stop screen annotations sampling surface height for marks that are hidden, - behind the camera or over the horizon. Visible marks still waiting for - terrain share 32 samples per projection pass and retry once a second, so - drawing a large board no longer stalls the app for seconds (asturksever, - #1277). +- Drawing a large board of screen annotations no longer stalls the app for + seconds: marks behind the camera, past the horizon or out of view no longer + sample the surface height under them, and marks still waiting for the map + surface to load share a small sampling budget and retry once a second + (asturksever, #1277). diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index f8b179f1d1..8ecdd7c399 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -178,16 +178,14 @@ voice follow-ups match on them and bikeshare uses the raw station name as its ID. The text is still untrusted: normalization does not prevent prompt injection. -Screen annotations skip hidden records and, before surface sampling, reject an -unsettled anchor only when its whole accepted height range (-430 to 9000 m) is -behind the camera or below the globe horizon; a settled height is tested as the -actual point. Anchors outside the conservative frustum do not sample and still -project at their cached or zero height, without the horizon test that this -stand-in height cannot decide, so a partly visible arrow keeps its connector. -Unresolved visible heights share a 32-sample budget per projection pass (each -board change and each rendered frame runs one), served oldest-refused first, -retry at most once per second per anchor, and retain no extra timer or -listener. Validated heights remain settled in the bounded cache. +`src/annotations/screenAnnotationRenderer.js` does not sample the surface +height under an anchor whose whole accepted height range (-430 to 9000 m) is +behind the camera or below the globe horizon; such an anchor is hidden. A lone +point whose range lies outside one plane of the view frustum is not sampled +either. Points of arrows, routes and areas are sampled even outside the view, +so the visible part of a mark runs to their real height. Until sampled, a point +is projected at 0 m. At most 32 samples run per `projectAll()` pass, +oldest-refused first, and each anchor retries a miss at most once a second. Terrain height requests accept at most 64 points, matching the browser service's existing batch size and one bounded upstream chunk. Larger requests return HTTP diff --git a/src/annotations/screenAnnotationRenderer.js b/src/annotations/screenAnnotationRenderer.js index 88205fa0d4..371a3aacd1 100644 --- a/src/annotations/screenAnnotationRenderer.js +++ b/src/annotations/screenAnnotationRenderer.js @@ -9,9 +9,9 @@ import { nextTick } from 'vue'; import { useScreenAnnotationsStore } from '../ui/stores/screenAnnotations.js'; import { applicationPinia } from '../ui/vueRuntime.js'; import { heightsOf } from '../queries/heights.js'; -import { fromDegrees, fromDegreesInto, toLonLatH } from '../geo/ellipsoid.js'; -import { frustumPlanes, sphereOutside } from '../geo/frustum.js'; -import { distance } from '../geo/vector.js'; +import { fromDegrees, toLonLatH } from '../geo/ellipsoid.js'; +import { viewPlanes } from '../geo/frustum.js'; +import { distance, dot } from '../geo/vector.js'; import { canvasOf as sceneCanvasOf, findCamera, @@ -88,11 +88,12 @@ export function createScreenAnnotationRenderer( const arrowMarkers = new Map(); let viewBox = null; - // The eye this frame is projected from (the camera port's pose), and the - // query port and canvas it is projected through, read once per pass. + // Read the camera pose, query port, canvas and view-frustum planes once + // per projection pass. let pose = null; let passQuery = null; let passCanvas = null; + let cullingPlanes = null; // The renderer's canvas; a viewer with no renderer bound, its own. const canvasOf = () => sceneCanvasOf(viewer); const records = new Map(); // anno.id -> { key, anno, group, parts } @@ -115,15 +116,12 @@ export function createScreenAnnotationRenderer( const MAX_SURFACE_HEIGHT = 9000; const HEIGHT_SAMPLE_BUDGET = 32; // clampNow calls per projection pass const HEIGHT_RETRY_MS = 1000; // minimum interval between misses per anchor - let cullingPlanes = null; // the pass's view frustum (`frustumPlanes`) - const HEIGHT_BOUNDS_RADIUS = 9500; // m about the 0 m point: every accepted height - const heightBoundsCenter = { x: 0, y: 0, z: 0 }; // Fair sampling: keys refused by an exhausted budget queue in arrival order, // and each pass reserves budget for the oldest queued keys first, so a fixed // iteration order cannot starve anchors beyond the first budget's worth. - let heightQueue = new Set(); // keys refused in earlier passes, oldest first - let heightReserved = new Set(); // queued keys this pass serves first - let heightRefused = new Set(); // keys refused during this pass + const heightQueue = new Set(); + const heightReserved = new Set(); // queued keys this pass serves first + const heightRefused = new Set(); // keys refused during this pass let heightBudget = HEIGHT_SAMPLE_BUDGET; // unreserved slots left this pass let projGen = 0; // bumped each projection frame; entries used this frame are "hot" function trimHeightCache() { @@ -161,12 +159,11 @@ export function createScreenAnnotationRenderer( return `${lon.toFixed(5)},${lat.toFixed(5)}`; } - // Best-effort surface height under a coordinate (clamps onto the 3D tiles). - // Returns 0 until the tile loads, then caches the validated height. - // canSample=false returns the cached height (or 0) without surface sampling. + // Best-effort surface height under a coordinate (clamps onto the 3D tiles): + // the validated height once the tile loads, null until then. // `key` and `cached` are the caller's cache lookup for this coordinate. - function groundHeight(lon, lat, key, cached, canSample = true) { - if (cached && cached.settled) { + function groundHeight(lon, lat, key, cached) { + if (cached?.settled) { // Mark hot for this frame + bump to most-recently-used so heights for live // marks survive eviction while places we've navigated away from age out. cached.gen = projGen; @@ -175,18 +172,17 @@ export function createScreenAnnotationRenderer( return cached.h; } const now = Date.now(); - if (cached && (!canSample || now < cached.nextAttempt)) { + if (cached && now < cached.nextAttempt) { cached.gen = projGen; - return cached.h; + return null; } - if (!canSample) return 0; if (heightReserved.has(key)) { heightReserved.delete(key); } else if (heightBudget > 0) { heightBudget--; } else { heightRefused.add(key); - return cached?.h || 0; + return null; } try { const heights = heightsOf(viewer); @@ -209,15 +205,13 @@ export function createScreenAnnotationRenderer( } catch { /* tiles not ready */ } - const fallback = cached ? cached.h : 0; heightCache.set(key, { - h: fallback, settled: false, gen: projGen, nextAttempt: now + HEIGHT_RETRY_MS, }); trimHeightCache(); - return fallback; + return null; } function add(anno) { @@ -413,49 +407,35 @@ export function createScreenAnnotationRenderer( // Area-type updates route through the hybrid proxy only. } - function project(lon, lat, allowOffscreen = false) { + // The window position of a point at its surface height (0 m until that is + // sampled), or null when it is not in view. A point of an arrow, route or + // area (`connector`) is sampled even outside the view, so the part of the + // mark that is in view runs to the real height of the part that is not. + function project(lon, lat, allowOffscreen = false, connector = false) { + if (!pose) return null; // Anchor at the real surface height (cached + validated), so marks sit on // the ground/building instead of at sea level. The settle-once cache keeps // it stable (no per-frame jitter that earlier broke nearby projections). - // A settled height is tested as the actual point below. An unknown height - // is rejected before GPU-backed surface sampling only when the whole - // accepted height range is proven hidden by one constraint. const key = heightKey(lon, lat); const cached = heightCache.get(key); - let height; - let horizonTest = true; - if (cached?.settled) { - height = groundHeight(lon, lat, key, cached); - } else { - if (heightRangeHidden(lon, lat)) return null; - // The frustum restricts sampling only; an endpoint outside it still - // projects (at its cached or zero height, without the horizon test) - // so a partly visible arrow, route or ring keeps its on-screen - // connector and label. - fromDegreesInto(lon, lat, 0, heightBoundsCenter); - const inFrustum = - !cullingPlanes || - !sphereOutside(cullingPlanes, heightBoundsCenter, HEIGHT_BOUNDS_RADIUS); - height = groundHeight(lon, lat, key, cached, inFrustum); - horizonTest = inFrustum; + let sample = true; + if (!cached?.settled) { + // Unsettled: before sampling, cull only if the whole height range is hidden. + const low = fromDegrees(lon, lat, MIN_SURFACE_HEIGHT); + const high = fromDegrees(lon, lat, MAX_SURFACE_HEIGHT); + if (heightRangeHidden(low, high)) return null; + // A lone point outside the view is not sampled; the entry keeps its + // retry time. + sample = connector || !rangeOutsideView(low, high); + if (!sample && cached) cached.gen = projGen; } - const world = fromDegrees(lon, lat, height); - if (!pose) return null; + const height = sample ? groundHeight(lon, lat, key, cached) : null; + const world = fromDegrees(lon, lat, height ?? 0); // Reject points behind the camera (they produce wrapped/extreme coords). - const eye = pose.position; - const look = pose.direction; - if ( - (world.x - eye.x) * look.x + - (world.y - eye.y) * look.y + - (world.z - eye.z) * look.z <= - 0 - ) - return null; - // Reject points beyond the globe horizon. An unsampled stand-in height - // outside the frustum cannot decide it: the range test above found no - // proof that the real height is hidden. + if (behindEye(world)) return null; + // Reject points beyond the globe horizon. const query = passQuery; - if (!query || (horizonTest && query.isOccluded(world))) return null; + if (!query || query.isOccluded(world)) return null; const win = query.project(world); if (!win || !Number.isFinite(win.x) || !Number.isFinite(win.y)) return null; // Reject absurd off-screen projections (anchor not in view). @@ -474,20 +454,30 @@ export function createScreenAnnotationRenderer( // region (behind the camera plane; the occluder's cone beyond the horizon // plane) is convex. So when both height-range endpoints fail the SAME test, // every intermediate height fails it too. Mixed failures prove nothing. - // With no pose (no eye to test from) nothing is proven hidden. - function heightRangeHidden(lon, lat) { - if (!pose) return false; - const low = fromDegrees(lon, lat, MIN_SURFACE_HEIGHT); - const high = fromDegrees(lon, lat, MAX_SURFACE_HEIGHT); + function heightRangeHidden(low, high) { + if (behindEye(low) && behindEye(high)) return true; + return Boolean(passQuery?.isOccluded(low) && passQuery.isOccluded(high)); + } + + // Whether the height range lies wholly outside one view-frustum plane, so + // no accepted height under the point is in view. + function rangeOutsideView(low, high) { + if (!cullingPlanes) return false; + for (const { normal, w } of cullingPlanes) + if (dot(normal, low) + w < 0 && dot(normal, high) + w < 0) return true; + return false; + } + + // Whether `point` is on or behind the camera plane (needs a pose). + function behindEye(point) { const eye = pose.position; const look = pose.direction; - const behind = (point) => + return ( (point.x - eye.x) * look.x + (point.y - eye.y) * look.y + (point.z - eye.z) * look.z <= - 0; - if (behind(low) && behind(high)) return true; - return Boolean(passQuery?.isOccluded(low) && passQuery.isOccluded(high)); + 0 + ); } // Tracked-entity z-order: the tracked aircraft is a Cesium billboard in the @@ -569,23 +559,16 @@ export function createScreenAnnotationRenderer( publish(); return; } - // Serve the oldest refused keys first; the rest of the budget is open. - heightReserved = new Set(); + heightReserved.clear(); for (const key of heightQueue) { if (heightReserved.size >= HEIGHT_SAMPLE_BUDGET) break; heightReserved.add(key); } heightBudget = HEIGHT_SAMPLE_BUDGET - heightReserved.size; - heightRefused = new Set(); + heightRefused.clear(); projGen += 1; // new frame: entries touched below are "hot" and survive trimming pose = findCamera(viewer)?.pose() ?? null; - // A pose with no perspective frustum culls nothing. - cullingPlanes = - Number.isFinite(pose?.fovy) && - Number.isFinite(pose.aspectRatio) && - Number.isFinite(pose.near) - ? frustumPlanes(pose) - : null; + cullingPlanes = viewPlanes(pose); passQuery = findQuery(viewer); passCanvas = canvasOf(); const trackedRect = trackedEntityRect(); @@ -622,7 +605,9 @@ export function createScreenAnnotationRenderer( const polygons = anno.polygons?.length ? anno.polygons : [[anno.ring]]; for (const polygon of polygons) { const projectedRings = polygon.map((ring) => - ring.map(([lon, lat]) => project(lon, lat, polygon.length > 1)), + ring.map(([lon, lat]) => + project(lon, lat, polygon.length > 1, true), + ), ); // Keep the historical visible-outer projection, but never fill over // an unprojectable hole or hide another independently visible part. @@ -656,8 +641,8 @@ export function createScreenAnnotationRenderer( group.display = 'none'; } } else if (anno.type === 'arrow' && parts.path) { - const a = project(anno.anchor.lon, anno.anchor.lat); - const b = project(anno.to.lon, anno.to.lat); + const a = project(anno.anchor.lon, anno.anchor.lat, false, true); + const b = project(anno.to.lon, anno.to.lat, false, true); if (a && b) { // gentle arc so the connector reads as a drawn gesture, not a ruler line const mx = (a.x + b.x) / 2; @@ -682,7 +667,9 @@ export function createScreenAnnotationRenderer( group.display = 'none'; } } else if (anno.type === 'route' && parts.poly) { - const projected = anno.path.map((pt) => project(pt.lon, pt.lat)); + const projected = anno.path.map((pt) => + project(pt.lon, pt.lat, false, true), + ); const pts = []; for (const p of projected) { if (p) pts.push(`${p.x.toFixed(1)},${p.y.toFixed(1)}`); @@ -746,11 +733,9 @@ export function createScreenAnnotationRenderer( } // Still-refused queued keys keep their place; new refusals join the back. // Keys no longer requesting a sample (settled, culled, removed) drop out. - const nextQueue = new Set(); for (const key of heightQueue) - if (heightRefused.has(key)) nextQueue.add(key); - for (const key of heightRefused) nextQueue.add(key); - heightQueue = nextQueue; + if (!heightRefused.has(key)) heightQueue.delete(key); + for (const key of heightRefused) heightQueue.add(key); // Keep clustered callouts readable. const placed = []; diff --git a/src/annotations/screenAnnotationRenderer.test.mjs b/src/annotations/screenAnnotationRenderer.test.mjs index e15923383c..cca738aae8 100644 --- a/src/annotations/screenAnnotationRenderer.test.mjs +++ b/src/annotations/screenAnnotationRenderer.test.mjs @@ -188,7 +188,7 @@ test('outline upgrade preserves the existing SVG group identity', async (t) => { ), positionCartographic: { height: 1000 }, }; - t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', () => ({ x: 100, y: 100 })); + projectTo(t, { x: 100, y: 100 }); const sampledAnchors = []; const scene = sceneFor(camera, { canvas: { clientWidth: 1280, clientHeight: 720, width: 1280, height: 720 }, @@ -597,16 +597,12 @@ test('a mark hidden from Draw is not drawn or placed, and comes back when shown' test('hidden and back-facing annotations do not sample; visible unresolved heights have bounded retries', (t) => { const store = samplingBoard(t); t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 1000 }); - t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', () => ({ - x: 100, - y: 100, - })); + projectTo(t, { x: 100, y: 100 }); const camera = { positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 100000), directionWC: new Cesium.Cartesian3(-1, 0, 0), upWC: new Cesium.Cartesian3(0, 0, 1), positionCartographic: { height: 100000 }, - moveEnd: new Cesium.Event(), }; let samples = 0; const postRender = new Cesium.Event(); @@ -618,7 +614,6 @@ test('hidden and back-facing annotations do not sample; visible unresolved heigh sampleHeight() { samples++; }, - requestRender() {}, }; const renderer = samplingRenderer(store, scene); const mark = (id, lon) => ({ @@ -633,24 +628,31 @@ test('hidden and back-facing annotations do not sample; visible unresolved heigh renderer.add(mark('near-side', 0)); for (let i = 0; i < 100; i++) postRender.raiseEvent(); assert.equal(samples, 1); - for (let i = 0; i < 10; i++) { + t.mock.timers.tick(999); + postRender.raiseEvent(); + assert.equal(samples, 1, 'no retry within a second of the miss'); + t.mock.timers.tick(1); + postRender.raiseEvent(); + assert.equal(samples, 2, 'one retry once a second has passed'); + for (let i = 0; i < 9; i++) { t.mock.timers.tick(1000); postRender.raiseEvent(); } assert.equal(samples, 11); - camera.moveEnd.raiseEvent(); - postRender.raiseEvent(); - assert.equal(samples, 11, 'camera events cannot bypass the retry interval'); renderer.update(mark('near-side', 0), { empty: true }); t.mock.timers.tick(1000); postRender.raiseEvent(); assert.equal(samples, 11, 'hidden records do not sample'); + // With no perspective frustum (no view planes), only the range's + // behind-camera test keeps this anchor from sampling. camera.directionWC = new Cesium.Cartesian3(1, 0, 0); + camera.frustum = new Cesium.OrthographicOffCenterFrustum(); renderer.update(mark('near-side', 0)); postRender.raiseEvent(); assert.equal(samples, 11, 'behind-camera anchors do not sample'); + delete camera.frustum; // Turned 45 degrees east: the anchor is in front and above the horizon, - // but outside the 60-degree frustum plus the 9.5 km height-bound radius. + // but outside the 60-degree frustum at every accepted height. camera.directionWC = new Cesium.Cartesian3(-Math.SQRT1_2, Math.SQRT1_2, 0); postRender.raiseEvent(); assert.equal(samples, 11, 'outside-frustum anchors do not sample'); @@ -669,23 +671,14 @@ test('hidden and back-facing annotations do not sample; visible unresolved heigh 'a projection pass caps synchronous surface work', ); renderer.destroy(); - assert.equal(camera.moveEnd.numberOfListeners, 0); assert.equal(postRender.numberOfListeners, 0); }); -function sampledLon(world) { - return cartographicLon(Cesium.Cartographic.fromCartesian(world)); -} - function cartographicLon(carto) { return Number(Cesium.Math.toDegrees(carto.longitude).toFixed(5)); } -/** - * A board with no view mounted, for tests that count surface samples: the - * renderer projects on `add` and on each post-render event, and the store - * holds what it would draw. Animation frames run at once. - */ +/** A board with no view mounted: tests read the store's marks. Animation frames run at once. */ function samplingBoard(t) { const previousRaf = globalThis.requestAnimationFrame; globalThis.requestAnimationFrame = (fn) => { @@ -698,23 +691,12 @@ function samplingBoard(t) { return useScreenAnnotationsStore(createPinia()); } -/** - * The renderer over `scene`, its camera port's pose taking the double - * camera's own `upWC` where it has one (the fake scene's pose is +Y up), so - * the frustum the renderer culls with is the double's. - */ +/** The screen renderer over a viewer double around `scene`. */ function samplingRenderer(store, scene) { - const viewer = { scene, camera: scene.camera, trackedEntity: null }; - const { camera } = bindFakeCesiumScene(viewer); - const pose = camera.pose; - camera.pose = () => { - const up = scene.camera.upWC; - return up ? { ...pose(), up: { x: up.x, y: up.y, z: up.z } } : pose(); - }; - return createScreenAnnotationRenderer(viewer, { - store, - activeTrackedReadoutId: () => null, - }); + return createScreenAnnotationRenderer( + { scene, camera: scene.camera, trackedEntity: null }, + { store, activeTrackedReadoutId: () => null }, + ); } function squareFrustum() { @@ -726,19 +708,63 @@ function squareFrustum() { return frustum; } -test('an arrow with one endpoint outside a real frustum keeps its visible connector', (t) => { - const store = samplingBoard(t); - t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', (_scene, world) => - sampledLon(world) > 0.1 ? { x: 1100, y: 400 } : { x: 400, y: 400 }, - ); - // 5 km straight down over (0, 0): east is +Y, north is +Z in ECEF here. - const camera = { - positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 5000), - directionWC: new Cesium.Cartesian3(-1, 0, 0), - upWC: new Cesium.Cartesian3(0, 0, 1), - positionCartographic: { height: 5000 }, +const metresEast = (m) => Number((m / 111319.49).toFixed(5)); // degrees of longitude at the equator +const metresNorth = (m) => Number((m / 110574).toFixed(5)); // degrees of latitude at the equator +const at = (p, h) => Cesium.Cartesian3.fromDegrees(p.lon, p.lat, h); + +/** + * A camera double `height` m above (0, 0) looking due east (+Y), pitched + * `pitchDeg` up (+X is up there). + */ +function eastwardCamera(height, pitchDeg = 0) { + const p = Cesium.Math.toRadians(pitchDeg); + return { + positionWC: Cesium.Cartesian3.fromDegrees(0, 0, height), + directionWC: new Cesium.Cartesian3(Math.sin(p), Math.cos(p), 0), + upWC: new Cesium.Cartesian3(Math.cos(p), -Math.sin(p), 0), + positionCartographic: { height }, frustum: squareFrustum(), }; +} + +/** The drawn end point of the board's only arrow, or null when it is hidden. */ +function arrowEnd(store) { + const [mark] = store.board.marks; + const path = mark.children.find((child) => child?.attrs?.class?.includes('gev-anno-arrow')); + const end = path?.attrs.d?.match(/(-?[\d.]+) (-?[\d.]+)$/); + return mark.display === '' && end ? { x: Number(end[1]), y: Number(end[2]) } : null; +} + +/** + * Project through `camera` (position, direction, up, square frustum) onto an + * 800 x 800 canvas for the test's length; returns that projection. + */ +function projectThrough(t, camera, size = 800) { + const tan = Math.tan(camera.frustum.fov / 2); + const toWindow = (world) => { + const right = Cesium.Cartesian3.cross(camera.directionWC, camera.upWC, new Cesium.Cartesian3()); + const v = Cesium.Cartesian3.subtract(world, camera.positionWC, new Cesium.Cartesian3()); + const z = Cesium.Cartesian3.dot(v, camera.directionWC); + return { + x: ((Cesium.Cartesian3.dot(v, right) / z / tan + 1) / 2) * size, + y: ((1 - Cesium.Cartesian3.dot(v, camera.upWC) / z / tan) / 2) * size, + }; + }; + projectTo(t, (_scene, world) => toWindow(world)); + return toWindow; +} + +/** Whether `point`'s accepted heights (a 9.5 km sphere holds them) are all outside `camera`'s frustum. */ +function outsideFrustum(camera, point) { + const volume = camera.frustum.computeCullingVolume(camera.positionWC, camera.directionWC, camera.upWC); + return volume.computeVisibility(new Cesium.BoundingSphere(point, 9500)) === Cesium.Intersect.OUTSIDE; +} + +/** + * An 800 x 800 scene over `camera` whose surface under a longitude is + * `surface(lon)`; `sampled` lists the sampled longitudes. + */ +function surfaceScene(camera, surface) { const sampled = []; const postRender = new Cesium.Event(); const scene = { @@ -747,111 +773,72 @@ test('an arrow with one endpoint outside a real frustum keeps its visible connec postRender, sampleHeightSupported: true, sampleHeight(cartographic) { - sampled.push(cartographicLon(cartographic)); - return 0; + const lon = cartographicLon(cartographic); + sampled.push(lon); + return surface(lon); }, }; - // The 0.2-degree endpoint (~22 km east) is well beyond the side plane plus - // the 9.5 km height-bound radius, yet in front of the camera and the horizon. - const far = Cesium.Cartesian3.fromDegrees(0.2, 0, 0); - const volume = camera.frustum.computeCullingVolume( - camera.positionWC, - camera.directionWC, - camera.upWC, - ); - assert.equal( - volume.computeVisibility(new Cesium.BoundingSphere(far, 9500)), - Cesium.Intersect.OUTSIDE, - ); + return { scene, postRender, sampled }; +} + +test('an arrow with one endpoint outside a real frustum keeps its visible connector', (t) => { + const store = samplingBoard(t); + // 30 km straight down over (0, 0): east is +Y, north is +Z in ECEF here. + const camera = { + positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 30000), + directionWC: new Cesium.Cartesian3(-1, 0, 0), + upWC: new Cesium.Cartesian3(0, 0, 1), + positionCartographic: { height: 30000 }, + frustum: squareFrustum(), + }; + const toWindow = projectThrough(t, camera); + // 35 km east: in front of the camera and the horizon, but outside the + // frustum at every accepted height. + const far = { lon: metresEast(35000), lat: 0 }; + assert.ok(outsideFrustum(camera, at(far, 0))); + const farWin = toWindow(at(far, 0)); + assert.ok(farWin.x > 800 && farWin.x < 1600, 'far end off-screen right, inside the 2w limit'); + const { scene, postRender, sampled } = surfaceScene(camera, () => 0); const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); renderer.add({ id: 'partial-arrow', type: 'arrow', label: 'Ridge', anchor: { lon: 0, lat: 0 }, - to: { lon: 0.2, lat: 0 }, + to: far, }); postRender.raiseEvent(); const [mark] = store.board.marks; assert.equal(mark.display, '', 'the arrow stays drawn'); const path = mark.children.find((child) => child.attrs.class?.includes('gev-anno-arrow')); - assert.match(path.attrs.d, /^M 400\.0 400\.0 Q .* 1100\.0 400\.0$/); - assert.deepEqual([...new Set(sampled)], [0], 'only the in-frustum endpoint samples'); - renderer.destroy(); + assert.ok(path.attrs.d.startsWith('M 400.0 400.0 Q ')); + assert.ok(path.attrs.d.endsWith(` ${farWin.x.toFixed(1)} ${farWin.y.toFixed(1)}`)); + assert.deepEqual([...new Set(sampled)], [0, far.lon], 'the off-view end samples too'); }); -// An arrow whose far end lies outside the frustum (so it is not sampled) and -// beyond the horizon at the 0 m stand-in height, but above it at its real -// 100 m height, keeps its connector and label. -test('an arrow whose unsampled far end is past the 0 m horizon keeps its connector', (t) => { - const previousRaf = globalThis.requestAnimationFrame; - globalThis.requestAnimationFrame = (fn) => { - fn(); - return 1; - }; - t.after(() => { - globalThis.requestAnimationFrame = previousRaf; - }); - const W = 800; - const H = 800; - const half = Cesium.Math.toRadians(30); - const frustum = new Cesium.PerspectiveFrustum(); - frustum.fov = 2 * half; - frustum.aspectRatio = 1; - frustum.near = 1; - frustum.far = 1e8; - // 100 m above the ellipsoid at (0, 0), level, looking due east. - const camera = { - positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 100), - directionWC: new Cesium.Cartesian3(0, 1, 0), - upWC: new Cesium.Cartesian3(1, 0, 0), - positionCartographic: { height: 100 }, - frustum, - }; - // A real perspective projection matching the frustum above. - t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', (_scene, world, result) => { - const right = Cesium.Cartesian3.cross(camera.directionWC, camera.upWC, new Cesium.Cartesian3()); - const v = Cesium.Cartesian3.subtract(world, camera.positionWC, new Cesium.Cartesian3()); - const z = Cesium.Cartesian3.dot(v, camera.directionWC); - const out = result || new Cesium.Cartesian2(); - out.x = ((Cesium.Cartesian3.dot(v, right) / z / Math.tan(half) + 1) / 2) * W; - out.y = ((1 - Cesium.Cartesian3.dot(v, camera.upWC) / z / Math.tan(half)) / 2) * H; - return out; - }); - // Near end 2 km east; far end 56 km away, 50 degrees north of the view axis. - const near = { lon: Number((2000 / 111319.49).toFixed(5)), lat: 0 }; +// The far end lies outside the frustum and beyond the horizon at 0 m, but +// above it at its real 100 m height: it is sampled, so the arrow keeps its +// connector and label. +test('an arrow whose far end is past the horizon only at 0 m keeps its connector', (t) => { + const store = samplingBoard(t); + const camera = eastwardCamera(100); + const toWindow = projectThrough(t, camera); + const near = { lon: metresEast(2000), lat: 0 }; const bearing = Cesium.Math.toRadians(50); const far = { - lon: Number(((56000 * Math.cos(bearing)) / 111319.49).toFixed(5)), - lat: Number(((56000 * Math.sin(bearing)) / 110574).toFixed(5)), + lon: metresEast(56000 * Math.cos(bearing)), + lat: metresNorth(56000 * Math.sin(bearing)), }; const surface = { [near.lon]: 10, [far.lon]: 100 }; - const postRender = new Cesium.Event(); - const scene = { - camera, - canvas: { width: W, height: H }, - postRender, - sampleHeightSupported: true, - sampleHeight(cartographic) { - return surface[cartographicLon(cartographic)]; - }, - }; - - // Preconditions: the scenario is the one described above. + const { scene, postRender } = surfaceScene(camera, (lon) => surface[lon]); const occluder = new Cesium.EllipsoidalOccluder(Cesium.Ellipsoid.WGS84, camera.positionWC); - const farAt = (h) => Cesium.Cartesian3.fromDegrees(far.lon, far.lat, h); - assert.equal(occluder.isPointVisible(farAt(100)), true, 'far end above the horizon at 100 m'); - assert.equal(occluder.isPointVisible(farAt(0)), false, 'far end past the horizon at 0 m'); - const volume = frustum.computeCullingVolume(camera.positionWC, camera.directionWC, camera.upWC); - assert.equal( - volume.computeVisibility(new Cesium.BoundingSphere(farAt(0), 9500)), - Cesium.Intersect.OUTSIDE, - 'far end outside the frustum plus the 9.5 km sampling sphere', - ); - const farWin = Cesium.SceneTransforms.worldToWindowCoordinates(scene, farAt(100)); - assert.ok(farWin.x > -W && farWin.x < 0, 'far end off-screen left, inside [-w, 2w]'); + assert.equal(occluder.isPointVisible(at(far, 100)), true, 'far end above the horizon at 100 m'); + assert.equal(occluder.isPointVisible(at(far, 0)), false, 'far end past the horizon at 0 m'); + assert.ok(outsideFrustum(camera, at(far, 0)), 'far end outside the frustum at every accepted height'); + const farWin = toWindow(at(far, 100)); + assert.ok(farWin.x > -800 && farWin.x < 0, 'far end off-screen left, inside [-w, 2w]'); - const store = useScreenAnnotationsStore(createPinia()); const renderer = samplingRenderer(store, scene); t.after(() => renderer.destroy()); renderer.add({ @@ -868,9 +855,158 @@ test('an arrow whose unsampled far end is past the 0 m horizon keeps its connect assert.match(path.attrs.d, /^M 400\.0 4\d\d\.\d Q /, 'the connector starts at the on-screen end'); }); +test('an arrow whose end crosses the 2h screen limit only at 0 m keeps its connector', (t) => { + const store = samplingBoard(t); + const camera = eastwardCamera(18000); + const toWindow = projectThrough(t, camera); + const start = { lon: metresEast(40000), lat: 0 }; + const end = { lon: metresEast(10000), lat: 0 }; + const { scene, postRender, sampled } = surfaceScene(camera, (lon) => (lon === end.lon ? 1500 : 0)); + assert.ok(toWindow(at(start, 0)).y < 800, 'start on screen'); + assert.ok(outsideFrustum(camera, at(end, 0)), 'end sphere outside the frustum'); + assert.ok(toWindow(at(end, 1500)).y < 1600, 'end inside the limit at its real height'); + assert.ok(toWindow(at(end, 0)).y > 1600, 'end past the limit at 0 m'); + const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); + renderer.add({ id: 'a', type: 'arrow', label: 'Ridge', anchor: start, to: end }); + for (let i = 0; i < 3; i++) postRender.raiseEvent(); + assert.equal(store.board.marks[0].display, '', 'the partly visible arrow stays drawn'); + assert.deepEqual([...new Set(sampled)], [start.lon, end.lon], 'the off-view end samples too'); +}); + +test('an upward-looking arrow keeps a far end that is behind the eye only at 0 m', (t) => { + const store = samplingBoard(t); + const camera = eastwardCamera(100, 59); + projectThrough(t, camera); + // Roofs: 132 m 19 m east (in view), 145 m 12 m west (above the view). + const start = { lon: metresEast(19), lat: 0 }; + const end = { lon: metresEast(-12), lat: 0 }; + const { scene, postRender } = surfaceScene(camera, (lon) => (lon === start.lon ? 132 : 145)); + const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); + renderer.add({ id: 'up', type: 'arrow', label: 'Tower', anchor: start, to: end }); + for (let i = 0; i < 4; i++) postRender.raiseEvent(); + const drawn = arrowEnd(store); + assert.ok(drawn, 'the arrow from the on-screen roof is drawn'); + assert.ok(drawn.y < 0 && drawn.y > -800, `the connector leaves through the top edge (end y ${drawn.y})`); +}); + +test('an arrow crossing the view between two off-view ends on a plateau is drawn', (t) => { + const store = samplingBoard(t); + const camera = eastwardCamera(4000); + projectThrough(t, camera); + // Both ends 2 km ahead and 2 km to either side on a 4000 m plateau: at 0 m + // both fall past the 2h limit, at 4000 m the arc crosses the screen. + const a = { lon: metresEast(2000), lat: metresNorth(2000) }; + const b = { lon: metresEast(2000), lat: metresNorth(-2000) }; + const { scene, postRender } = surfaceScene(camera, () => 4000); + const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); + renderer.add({ id: 'plateau', type: 'arrow', label: 'Pass', anchor: a, to: b }); + for (let i = 0; i < 4; i++) postRender.raiseEvent(); + const drawn = arrowEnd(store); + assert.ok(drawn, 'the arrow is drawn'); + assert.ok(Math.abs(drawn.y - 400) < 5, `the connector crosses at eye level (end y ${drawn.y})`); +}); + +test('an arrow to an off-view peak points at the peak, not at 0 m below it', (t) => { + const store = samplingBoard(t); + const camera = eastwardCamera(4000); + projectThrough(t, camera); + // From a 4000 m plateau 2 km ahead to a 4500 m peak just left of the view. + const start = { lon: metresEast(2000), lat: 0 }; + const end = { lon: metresEast(1000), lat: metresNorth(900) }; + const { scene, postRender } = surfaceScene(camera, (lon) => (lon === start.lon ? 4000 : 4500)); + const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); + renderer.add({ id: 'peak', type: 'arrow', label: 'Peak', anchor: start, to: end }); + for (let i = 0; i < 4; i++) postRender.raiseEvent(); + const drawn = arrowEnd(store); + assert.ok(drawn, 'the arrow is drawn'); + assert.ok( + Math.abs(drawn.x + 223.8) < 2 && Math.abs(drawn.y - 53.8) < 2, + `end at the 4500 m projection (-223.8, 53.8), got (${drawn.x}, ${drawn.y})`, + ); +}); + +test('a lone label beyond the horizon just outside the view stays hidden', (t) => { + const store = samplingBoard(t); + const camera = eastwardCamera(100); + const toWindow = projectThrough(t, camera); + const bearing = Cesium.Math.toRadians(34); + const anchor = { + lon: metresEast(200000 * Math.cos(bearing)), + lat: metresNorth(200000 * Math.sin(bearing)), + }; + const occluder = new Cesium.EllipsoidalOccluder(Cesium.Ellipsoid.WGS84, camera.positionWC); + assert.equal(occluder.isPointVisible(at(anchor, 0)), false, 'beyond the horizon at 0 m'); + assert.ok(outsideFrustum(camera, at(anchor, 0)), 'sphere outside the frustum'); + assert.ok(toWindow(at(anchor, 0)).x > -800, 'projection inside [-w, 2w]'); + const { scene, postRender } = surfaceScene(camera, () => 0); + const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); + renderer.add({ id: 'l', type: 'label', label: 'Far city', anchor }); + for (let i = 0; i < 3; i++) postRender.raiseEvent(); + assert.equal(store.board.marks[0].display, 'none', 'its callout does not peek in at the left edge'); +}); + +test('an arrow wholly beyond the horizon is not drawn across the screen', (t) => { + const store = samplingBoard(t); + const camera = eastwardCamera(100); + projectThrough(t, camera); + const a = { lon: metresEast(80000), lat: metresNorth(67000) }; + const b = { lon: metresEast(80000), lat: metresNorth(-67000) }; + const occluder = new Cesium.EllipsoidalOccluder(Cesium.Ellipsoid.WGS84, camera.positionWC); + for (const point of [a, b]) { + assert.equal(occluder.isPointVisible(at(point, 0)), false, 'end beyond the horizon at 0 m'); + assert.ok(outsideFrustum(camera, at(point, 0)), 'end sphere outside the frustum'); + } + const { scene, postRender } = surfaceScene(camera, () => 0); + const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); + renderer.add({ id: 'x', type: 'arrow', label: 'Ghost', anchor: a, to: b }); + for (let i = 0; i < 3; i++) postRender.raiseEvent(); + assert.equal(store.board.marks[0].display, 'none', 'no ghost connector'); +}); + +test('a visible area ring keeps a vertex past the horizon only at 0 m', (t) => { + const store = samplingBoard(t); + const camera = eastwardCamera(100); + const toWindow = projectThrough(t, camera); + const bearing = Cesium.Math.toRadians(50); + const far = { lon: metresEast(56000 * Math.cos(bearing)), lat: metresNorth(56000 * Math.sin(bearing)) }; + const nearLon = metresEast(2000); + const vertices = [ + { lon: nearLon, lat: metresNorth(300) }, + { lon: nearLon, lat: metresNorth(-300) }, + far, + ]; + const occluder = new Cesium.EllipsoidalOccluder(Cesium.Ellipsoid.WGS84, camera.positionWC); + assert.ok(outsideFrustum(camera, at(far, 0))); + assert.equal(occluder.isPointVisible(at(far, 0)), false); + assert.equal(occluder.isPointVisible(at(far, 100)), true); + const { scene, postRender, sampled } = surfaceScene(camera, (lon) => (lon === far.lon ? 100 : 10)); + const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); + renderer.add({ + id: 'triangle', type: 'area', label: 'Ridge', anchor: vertices[0], + ring: vertices.map(({ lon, lat }) => [lon, lat]), + }); + postRender.raiseEvent(); + const [mark] = store.board.marks; + assert.equal(mark.display, '', 'the triangle stays drawn'); + const path = mark.children.find((child) => child.attrs.class?.includes('gev-anno-area')); + const coords = vertices.map((p) => { + const { x, y } = toWindow(at(p, p === far ? 100 : 10)); + return `${x.toFixed(1)},${y.toFixed(1)}`; + }); + assert.equal(path.attrs.d, `M ${coords.join(' L ')} Z`, 'the far vertex sits at its real height'); + assert.deepEqual(sampled, [nearLon, nearLon, far.lon], 'the off-view vertex samples too'); +}); + test('a low-angle cached roof stays visible when range endpoints fail different tests', (t) => { const store = samplingBoard(t); - t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', () => ({ x: 400, y: 380 })); + projectTo(t, { x: 400, y: 380 }); // Camera 1 m above the ellipsoid, heading east, pitched 25 degrees down. const pitch = Cesium.Math.toRadians(25); const camera = { @@ -919,7 +1055,7 @@ test('a low-angle cached roof stays visible when range endpoints fail different test('height retries beyond the first budget are served under sparse passes', (t) => { const store = samplingBoard(t); t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 1000 }); - t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', () => ({ x: 100, y: 100 })); + projectTo(t, { x: 100, y: 100 }); const camera = { positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 100000), directionWC: new Cesium.Cartesian3(-1, 0, 0), @@ -957,16 +1093,37 @@ test('height retries beyond the first budget are served under sparse passes', (t } assert.ok(lastSamples.slice(0, 2).includes(1), 'the 33rd point is served within two passes'); assert.equal(lastSamples.at(-1), 0, 'and then stays settled'); - // Points refused in one pass are served first in the next: every point is - // retried within any two consecutive sparse passes. - pass = []; - t.mock.timers.tick(1000); - postRender.raiseEvent(); - const firstPass = pass; - pass = []; - t.mock.timers.tick(1000); - postRender.raiseEvent(); - const served = new Set([...firstPass, ...pass]); - for (const lon of lons.slice(0, -1)) assert.ok(served.has(lon), `${lon} retried`); renderer.destroy(); }); + +test('points refused longest are sampled before newer refusals', (t) => { + const store = samplingBoard(t); + t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 1000 }); + projectTo(t, { x: 100, y: 100 }); + const camera = { + positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 100000), + directionWC: new Cesium.Cartesian3(-1, 0, 0), + positionCartographic: { height: 100000 }, + }; + const lons = Array.from({ length: 65 }, (_, i) => Number(((i + 1) / 1000).toFixed(3))); + let pass = []; + const { scene, postRender } = surfaceScene(camera, (lon) => { + pass.push(lon); + }); + const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); + for (const lon of lons) { + renderer.add({ id: `p${lon}`, type: 'label', label: 'P', anchor: { lon, lat: 0 } }); + } + assert.deepEqual(pass, lons, 'every point gets its first miss'); + const passes = []; + for (let i = 0; i < 3; i++) { + t.mock.timers.tick(1000); + pass = []; + postRender.raiseEvent(); + passes.push(pass); + } + assert.deepEqual(passes[0], lons.slice(0, 32), 'a pass serves the first 32 in board order'); + assert.deepEqual(passes[1], lons.slice(32, 64), 'the next serves the 32 refused longest'); + assert.deepEqual(passes[2], [...lons.slice(0, 31), lons[64]], 'then the rest of the queue, before newer refusals'); +}); diff --git a/src/geo/frustum.js b/src/geo/frustum.js index 614d2fa500..162b505549 100644 --- a/src/geo/frustum.js +++ b/src/geo/frustum.js @@ -47,6 +47,26 @@ export function frustumPlanes(pose) { return [left, rightPlane, bottom, top, nearPlane, farPlane]; } +/** + * `frustumPlanes(pose)`, or null when the pose does not describe a + * perspective frustum: no position, direction or up, or no finite `fovy`, + * `aspectRatio` or `near` (an orthographic camera, no camera). + * @param {object|null|undefined} pose + * @returns {ReturnType|null} + */ +export function viewPlanes(pose) { + if ( + !pose?.position || + !pose.direction || + !pose.up || + !Number.isFinite(pose.fovy) || + !Number.isFinite(pose.aspectRatio) || + !Number.isFinite(pose.near) + ) + return null; + return frustumPlanes(pose); +} + /** * Whether a sphere is wholly outside `planes` (from `frustumPlanes`), as * the default renderer's `CullingVolume.computeVisibility` reports diff --git a/src/layers/transit/rendering.js b/src/layers/transit/rendering.js index 6a6cda15f3..c98f8d0e6d 100644 --- a/src/layers/transit/rendering.js +++ b/src/layers/transit/rendering.js @@ -9,7 +9,7 @@ import { poseSignature } from '../../render/camera/poseSignature.js'; import { heightsOf } from '../../queries/heights.js'; import { fromDegreesInto } from '../../geo/ellipsoid.js'; import { Vec3 } from '../../geo/vector.js'; -import { frustumPlanes } from '../../geo/frustum.js'; +import { viewPlanes } from '../../geo/frustum.js'; import { perspectiveCourseRotation } from '../../data/screenRotation.js'; import { PLACED_WAKE_MS, @@ -1074,23 +1074,6 @@ export function createRendering({ state, services, parts }) { ); } - /** - * The planes of the frustum the camera looks through, as the default - * renderer culls with them, or null when the pose does not describe one. - */ - function viewPlanes(pose) { - if ( - !pose?.position || - !pose.direction || - !pose.up || - !Number.isFinite(pose.fovy) || - !Number.isFinite(pose.aspectRatio) || - !Number.isFinite(pose.near) - ) - return null; - return frustumPlanes(pose); - } - function refreshVisibility() { if (!state._enabled) return 0; const now = Date.now(); diff --git a/src/testSupport/fakeCesiumScene.mjs b/src/testSupport/fakeCesiumScene.mjs index 35f7e605f0..741e74d012 100644 --- a/src/testSupport/fakeCesiumScene.mjs +++ b/src/testSupport/fakeCesiumScene.mjs @@ -234,7 +234,7 @@ export function bindFakeCesiumScene( direction: c?.directionWC ? plain(c.directionWC) : { x: 0, y: 0, z: -1 }, - up: { x: 0, y: 1, z: 0 }, + up: c?.upWC ? plain(c.upWC) : { x: 0, y: 1, z: 0 }, right: { x: 1, y: 0, z: 0 }, // An orthographic frustum has none, as the Cesium port reports it. fovy: From ed38a1ab3fddfd0a62af4663e461910ab591a713 Mon Sep 17 00:00:00 2001 From: German Khokhlov Date: Fri, 20 Nov 2026 11:48:22 +0400 Subject: [PATCH 12/13] fix(cctv): keep an HLS camera's health through the refused viewer's frame A viewer refused for capacity falls back to /frame after hls.js gives up. For a pullable HLS camera without a snapshot, /frame only has a placeholder or a Street View frame, which says nothing about the stream, yet it wrote degraded over the health that /media owns. /frame now leaves that health as it is; a dead upstream is still reported through /media. Tests: the middleware suite covers both fallbacks, a real upstream failure that still degrades, and cross-site segment and release refusals on a live HLS lease; capacity checks use HLS_LIMITS and HlsCapacityError; the three CCTV suites share one provider harness in src/testSupport. CURRENT-STATE and the changelog fragment describe the refusal. --- changelog.d/1267-cctv-hls-capacity-health.md | 5 +- docs/CURRENT-STATE.md | 5 +- server/providers/cctv.js | 50 ++-- server/providers/cctv/stream.js | 2 +- src/data/cctvHlsMiddleware.test.mjs | 231 ++++++++++--------- src/data/cctvHlsStream.test.mjs | 8 +- src/data/cctvMediaFeedType.test.mjs | 72 +----- src/data/cctvMediaRange.test.mjs | 102 +------- src/data/cctvRecordingResponse.mjs | 38 --- src/testSupport/cctvProviderHarness.mjs | 91 ++++++++ 10 files changed, 283 insertions(+), 321 deletions(-) delete mode 100644 src/data/cctvRecordingResponse.mjs create mode 100644 src/testSupport/cctvProviderHarness.mjs diff --git a/changelog.d/1267-cctv-hls-capacity-health.md b/changelog.d/1267-cctv-hls-capacity-health.md index 0b79ea13c5..a86c90e82a 100644 --- a/changelog.d/1267-cctv-hls-capacity-health.md +++ b/changelog.d/1267-cctv-hls-capacity-health.md @@ -1,3 +1,4 @@ - Stop reporting a live HLS camera as degraded when a viewer is refused because - every lease or session slot is taken; the refusal still answers 503 with - `Retry-After` (Said Turksever, German Khokhlov, #1267). + every viewer or session slot is taken: the refusal answers 503 with + `Retry-After`, and the frame shown in its place leaves the camera's health + as it was (asturksever, gekh, #1267). diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 51dd971fe0..9537e97727 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -9582,7 +9582,10 @@ its paint loop. Camera deactivation destroys the decoder, and fatal playback errors revert to the labeled frame fallback. Camera changes clear the old panel frame. hls.js is imported only when an HLS camera starts. Two live sessions may coexist with at most eight independent consumer leases each; no-access lease -expiry is 15 seconds. Closing one consumer leaves other consumers running. Lease +expiry is 15 seconds. A viewer refused because every lease or session slot is +taken gets 503 with `Retry-After: 2` and leaves the camera's health unchanged; +so does its frame fallback, since an HLS camera without a snapshot has no frame +of its own. Closing one consumer leaves other consumers running. Lease ids use `crypto.randomUUID` where the page is a secure context and an equivalent v4 id from `crypto.getRandomValues` on plain-HTTP LAN pages. Encrypted/fMP4/byte-range playlists fail closed. Performance and live agency reliability require recorded validation. diff --git a/server/providers/cctv.js b/server/providers/cctv.js index 57589ee787..d5ad30ba80 100644 --- a/server/providers/cctv.js +++ b/server/providers/cctv.js @@ -23,6 +23,11 @@ import { isMlitRiverAdjustmentImage } from './cctv/worldCameras.js'; import { ottawaAuthorizedFrameUrl } from './cctv/ottawa.js'; import { googleServerApiKey } from './places/google-key.js'; export { CCTV_FRAME_FETCH_TIMEOUT_MS, fetchCctvImageFromUpstream }; + +/** An http(s) .m3u8 URL: what the HLS puller behind /media can play. */ +const isPullableHlsUrl = (url) => + /^https?:\/\//i.test(url) && /\.m3u8(?:\?|$)/i.test(url); + /** * Vite plugin: CCTV camera proxy with source registry, frame/media serving, * fallback chain (upstream -> Street View -> synthetic SVG), and health tracking. @@ -386,10 +391,7 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) { return; } if (feedType === 'hls') { - if ( - !/^https?:\/\//i.test(mediaUrl) || - !/\.m3u8(?:\?|$)/i.test(mediaUrl) - ) { + if (!isPullableHlsUrl(mediaUrl)) { res.writeHead(503, { 'Content-Type': 'application/json' }); res.end( JSON.stringify({ @@ -450,8 +452,7 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) { }); res.end(playlist); } catch (error) { - // A full lease or session budget says nothing about the source: - // leave the health its other viewers see untouched. + // A capacity refusal says nothing about the source: keep its health. if (!(error instanceof HlsCapacityError)) setHealth(cameraId, { status: 'degraded', @@ -653,6 +654,13 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) { (!isVideoFeedType(normalizeFeedType(source?.feedType)) ? source?.url : ''); + // /media reports a pullable HLS camera's health. Without a snapshot of + // its own, the placeholder or Street View frame here says nothing about + // its stream, so it leaves that health as it is. + const keepHealth = + normalizeFeedType(source?.feedType) === 'hls' && + !source?.snapshotUrl && + isPullableHlsUrl(source?.url || ''); const upstreamImage = source?.pack === 'world-cameras' @@ -747,12 +755,13 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) { pitch, }); if (sv?.ok) { - setHealth(cameraId, { - status: 'degraded', - sourceKind: 'streetview', - label: 'Google Street View', - message: 'Fallback Street View frame', - }); + if (!keepHealth) + setHealth(cameraId, { + status: 'degraded', + sourceKind: 'streetview', + label: 'Google Street View', + message: 'Fallback Street View frame', + }); res.writeHead(200, { 'Content-Type': sv.contentType, 'Cache-Control': 'no-store', @@ -771,14 +780,15 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) { : 'NO UPSTREAM CONFIGURED', }); - setHealth(cameraId, { - status: 'degraded', - sourceKind: 'synthetic', - label: source?.provider || 'Synthetic fallback', - message: source?.url - ? 'Upstream unavailable' - : 'No source configured', - }); + if (!keepHealth) + setHealth(cameraId, { + status: 'degraded', + sourceKind: 'synthetic', + label: source?.provider || 'Synthetic fallback', + message: source?.url + ? 'Upstream unavailable' + : 'No source configured', + }); res.writeHead(200, { 'Content-Type': 'image/svg+xml', diff --git a/server/providers/cctv/stream.js b/server/providers/cctv/stream.js index 8b4b046d6e..e1d22ae5f7 100644 --- a/server/providers/cctv/stream.js +++ b/server/providers/cctv/stream.js @@ -16,7 +16,7 @@ export const HLS_LIMITS = Object.freeze({ readyMs: 12000, }); -/** Every lease or session slot is taken: the source itself has not failed. */ +/** Every lease or session slot is taken, or the viewer's lease ended mid-request: the source itself has not failed. */ export class HlsCapacityError extends Error {} /** Refuse redirects; count actual streamed bytes, including chunked responses. */ diff --git a/src/data/cctvHlsMiddleware.test.mjs b/src/data/cctvHlsMiddleware.test.mjs index de446b4a47..4be55b7783 100644 --- a/src/data/cctvHlsMiddleware.test.mjs +++ b/src/data/cctvHlsMiddleware.test.mjs @@ -1,15 +1,13 @@ -// Live HLS through the real /api/cctv middleware: playlist, segment and -// release. HLS leases are random per-playback ids, not bound to the socket -// address, so viewers who share one address (a Docker bridge gateway, a reverse -// proxy, NAT) get the whole per-session budget, and a viewer whose address -// changes mid-playback keeps its lease. -// -// Run with: npm test (node --test) +// Live HLS through the real /api/cctv middleware. Leases are random +// per-playback ids, not bound to the socket address, and a viewer refused for +// capacity leaves the camera's health as it was. import { test } from 'node:test'; import assert from 'node:assert/strict'; -import { cctvProxy } from '../../server/providers/cctv.js'; -import { recordingResponse } from './cctvRecordingResponse.mjs'; +import { HLS_LIMITS } from '../../server/providers/cctv/stream.js'; +import { mountCctvProvider } from '../testSupport/cctvProviderHarness.mjs'; +const perSession = HLS_LIMITS.leasesPerSession; +const SAME_ORIGIN = { host: 'localhost:4173', 'sec-fetch-site': 'same-origin' }; const camera = (id) => ({ id, name: id, @@ -23,61 +21,29 @@ const PLAYLIST = const lease = (index) => `00000000-0000-4000-8000-${String(index).padStart(12, '0')}`; -/** Mount the provider over three HLS cameras whose upstream always answers. */ -function mount(t) { - const before = { - json: process.env.CCTV_SOURCES_JSON, - file: process.env.CCTV_SOURCES_FILE, - austin: process.env.CCTV_FORCE_AUSTIN, - }; - process.env.CCTV_SOURCES_JSON = JSON.stringify( - ['cam-a', 'cam-b', 'cam-c'].map(camera), - ); - process.env.CCTV_SOURCES_FILE = 'absent-source-file.json'; - process.env.CCTV_FORCE_AUSTIN = '0'; - const nativeFetch = globalThis.fetch; - // The puller binds fetch when cctvProxy() creates it, so mock first. - globalThis.fetch = async (url) => - new Response(String(url).endsWith('.m3u8') ? PLAYLIST : 'abc'); - let handler; - const closers = []; - cctvProxy().configureServer({ - httpServer: { on: (_event, fn) => closers.push(fn) }, - middlewares: { use: (_route, fn) => (handler = fn) }, +/** Mount the provider over three HLS cameras; `failing` upstreams answer 500. */ +function mount(t, failing = []) { + const upstream = []; + const app = mountCctvProvider(t, { + cameras: ['cam-a', 'cam-b', 'cam-c'].map(camera), + fetch: async (url) => { + upstream.push(String(url)); + if (failing.some((id) => String(url).includes(`/${id}/`))) + return new Response('', { status: 500 }); + return new Response(String(url).endsWith('.m3u8') ? PLAYLIST : 'abc'); + }, }); - assert.ok(handler, 'the CCTV provider must mount a middleware'); - t.after(() => { - for (const fn of closers) fn(); - globalThis.fetch = nativeFetch; - for (const [name, value] of [ - ['CCTV_SOURCES_JSON', before.json], - ['CCTV_SOURCES_FILE', before.file], - ['CCTV_FORCE_AUSTIN', before.austin], - ]) { - if (value === undefined) delete process.env[name]; - else process.env[name] = value; - } - }); - return async (url, remoteAddress, method = 'GET') => { - const { res, done } = recordingResponse(); - await handler( - { - url, - method, - headers: { host: 'localhost:4173', 'sec-fetch-site': 'same-origin' }, - socket: { remoteAddress }, - on() {}, - }, - res, - ); - await done; - return res; - }; + return { ...app, upstream }; } /** Open a playlist and return the first segment path it lists. */ async function openPlaylist(call, cameraId, leaseId, remoteAddress) { - const res = await call(`/media/${cameraId}?lease=${leaseId}`, remoteAddress); + const res = await call( + `/media/${cameraId}?lease=${leaseId}`, + SAME_ORIGIN, + 'GET', + remoteAddress, + ); assert.equal(res.statusCode, 200, `playlist ${cameraId} ${leaseId}`); const segment = res.body .split('\n') @@ -86,77 +52,136 @@ async function openPlaylist(call, cameraId, leaseId, remoteAddress) { return segment.replace('/api/cctv', ''); } -test('viewers on distinct addresses open, read and release their own leases', async (t) => { - const call = mount(t); - const viewers = Array.from({ length: 9 }, (_, index) => ({ - camera: index < 5 ? 'cam-a' : 'cam-b', - lease: lease(index), - // IPv4-mapped form, as a dual-stack listener reports it. - peer: `::ffff:192.168.1.${20 + index}`, - })); - for (const viewer of viewers) - viewer.segment = await openPlaylist( - call, - viewer.camera, - viewer.lease, - viewer.peer, - ); - for (const viewer of viewers) - assert.equal((await call(viewer.segment, viewer.peer)).statusCode, 200); - for (const viewer of viewers) { - const release = await call( - `/media/${viewer.camera}?lease=${viewer.lease}`, - viewer.peer, - 'DELETE', - ); - assert.equal(release.statusCode, 204); - } -}); - test('viewers behind one shared address get every slot, and no more', async (t) => { - const call = mount(t); + assert.equal(HLS_LIMITS.sessions, 2, 'the test fills both sessions'); + const { call, health } = mount(t); const shared = '::ffff:172.17.0.1'; - const health = async (id) => - JSON.parse((await call('/health', shared)).body).cameras.find( - (entry) => entry.id === id, - ); let segment; - for (let index = 0; index < 16; index++) + for (let index = 0; index < 2 * perSession; index++) segment = await openPlaylist( call, - index < 8 ? 'cam-a' : 'cam-b', + index < perSession ? 'cam-a' : 'cam-b', lease(index), shared, ); - assert.equal((await call(segment, shared)).statusCode, 200); + assert.equal( + (await call(segment, SAME_ORIGIN, 'GET', shared)).statusCode, + 200, + ); + const before = await health('cam-a'); // A ninth viewer of a full session and a third session are both refused, // without reporting a camera whose upstream is fine as degraded. for (const cameraId of ['cam-a', 'cam-c']) { - const refused = await call(`/media/${cameraId}?lease=${lease(16)}`, shared); + const refused = await call( + `/media/${cameraId}?lease=${lease(2 * perSession)}`, + SAME_ORIGIN, + 'GET', + shared, + ); assert.equal(refused.statusCode, 503, cameraId); assert.equal(refused.headers['Retry-After'], '2'); } - assert.equal((await health('cam-a')).status, 'ok'); + assert.deepEqual(await health('cam-a'), before); assert.equal(await health('cam-c'), undefined); // A released slot is free for the next viewer. - await call(`/media/cam-a?lease=${lease(0)}`, shared, 'DELETE'); - await openPlaylist(call, 'cam-a', lease(16), shared); + await call(`/media/cam-a?lease=${lease(0)}`, SAME_ORIGIN, 'DELETE', shared); + await openPlaylist(call, 'cam-a', lease(2 * perSession), shared); }); test('a lease keeps working after its viewer reconnects from another address', async (t) => { - const call = mount(t); + const { call } = mount(t); await openPlaylist(call, 'cam-a', lease(0), '192.168.1.20'); const segment = await openPlaylist(call, 'cam-a', lease(0), '192.168.1.21'); - assert.equal((await call(segment, '192.168.1.21')).statusCode, 200); + assert.equal( + (await call(segment, SAME_ORIGIN, 'GET', '192.168.1.21')).statusCode, + 200, + ); // A second viewer keeps the session alive, so the 404 below is the released // lease and not a stopped session. const other = await openPlaylist(call, 'cam-a', lease(1), '192.168.1.30'); const release = await call( `/media/cam-a?lease=${lease(0)}`, - '192.168.1.21', + SAME_ORIGIN, 'DELETE', + '192.168.1.21', ); assert.equal(release.statusCode, 204); - assert.equal((await call(segment, '192.168.1.21')).statusCode, 404); - assert.equal((await call(other, '192.168.1.30')).statusCode, 200); + assert.equal( + (await call(segment, SAME_ORIGIN, 'GET', '192.168.1.21')).statusCode, + 404, + ); + assert.equal( + (await call(other, SAME_ORIGIN, 'GET', '192.168.1.30')).statusCode, + 200, + ); +}); + +test('ninth viewer frame fallback preserves active camera health', async (t) => { + const { call, health } = mount(t); + let segment; + for (let index = 0; index < perSession; index++) + segment = await openPlaylist(call, 'cam-a', lease(index)); + const before = await health('cam-a'); + assert.equal(before.status, 'ok'); + const refused = await call( + `/media/cam-a?lease=${lease(perSession)}`, + SAME_ORIGIN, + ); + assert.equal(refused.statusCode, 503); + const frame = await call( + '/frame/cam-a?label=cam-a&lat=30.27&lon=-97.74', + SAME_ORIGIN, + ); + assert.equal(frame.statusCode, 200); + assert.equal( + (await call(segment, SAME_ORIGIN)).statusCode, + 200, + 'admitted viewer still plays', + ); + assert.deepEqual(await health('cam-a'), before); +}); + +test('third camera frame fallback keeps absent health', async (t) => { + const { call, health, upstream } = mount(t); + await openPlaylist(call, 'cam-a', lease(0)); + await openPlaylist(call, 'cam-b', lease(1)); + const refused = await call(`/media/cam-c?lease=${lease(2)}`, SAME_ORIGIN); + assert.equal(refused.statusCode, 503); + assert.equal(await health('cam-c'), undefined); + const frame = await call( + '/frame/cam-c?label=cam-c&lat=30.27&lon=-97.74', + SAME_ORIGIN, + ); + assert.equal(frame.statusCode, 200); + assert.equal(upstream.filter((url) => url.includes('/cam-c/')).length, 0); + assert.equal( + await health('cam-c'), + undefined, + 'the fallback frame wrote cam-c health', + ); +}); + +test('a failing HLS upstream with free slots is still reported degraded', async (t) => { + const { call, health } = mount(t, ['cam-c']); + const res = await call(`/media/cam-c?lease=${lease(0)}`, SAME_ORIGIN); + assert.equal(res.statusCode, 503); + assert.equal(res.headers['Retry-After'], '2'); + const row = await health('cam-c'); + assert.deepEqual( + { status: row.status, message: row.message }, + { status: 'degraded', message: 'Live HLS unavailable' }, + ); +}); + +test('a cross-site request can neither read nor release a live HLS lease', async (t) => { + const { call } = mount(t); + const segment = await openPlaylist(call, 'cam-a', lease(0)); + const crossSite = { host: 'localhost:4173', 'sec-fetch-site': 'cross-site' }; + assert.equal((await call(segment, crossSite)).statusCode, 403); + assert.equal( + (await call(`/media/cam-a?lease=${lease(0)}`, crossSite, 'DELETE')) + .statusCode, + 403, + ); + assert.equal((await call(segment, SAME_ORIGIN)).statusCode, 200); }); diff --git a/src/data/cctvHlsStream.test.mjs b/src/data/cctvHlsStream.test.mjs index 4a5f4afbc9..5041a5c163 100644 --- a/src/data/cctvHlsStream.test.mjs +++ b/src/data/cctvHlsStream.test.mjs @@ -5,6 +5,7 @@ import { fetchHlsBytes, parseHlsMedia, HLS_LIMITS, + HlsCapacityError, } from '../../server/providers/cctv/stream.js'; const playlist = '#EXTM3U\n#EXT-X-MEDIA-SEQUENCE:12\n#EXTINF:2,\na.ts\n#EXTINF:2,\nb.ts\n#EXTINF:2,\nc.ts\n'; @@ -144,7 +145,7 @@ test('one session is reserved before await; disk-free cache and capacity remain manager.ensure('a', base), ]); assert.equal(a, b); - await assert.rejects(manager.ensure('b', base)); + await assert.rejects(manager.ensure('b', base), HlsCapacityError); assert.equal(await manager.waitReady(a), true); assert.deepEqual(manager.stats(), { sessions: 1, bytes: 6 }); const text = await manager.buildPlaylist(a, 'a'); @@ -261,7 +262,10 @@ test('two consumers share downloads but release and abandoned expiry are indepen await manager.waitReady(a); assert.equal(downloads, 4); // One manifest and three segments, not per consumer. assert.equal(a.leases.size, 2); - await assert.rejects(manager.ensure('camera', base, 'viewer-c')); + await assert.rejects( + manager.ensure('camera', base, 'viewer-c'), + HlsCapacityError, + ); manager.release('camera', 'viewer-a'); assert.equal(manager.stats().sessions, 1); assert.equal(manager.getSegment('camera', a.token, 0, 'viewer-a'), null); diff --git a/src/data/cctvMediaFeedType.test.mjs b/src/data/cctvMediaFeedType.test.mjs index e3dfc60064..d75610a272 100644 --- a/src/data/cctvMediaFeedType.test.mjs +++ b/src/data/cctvMediaFeedType.test.mjs @@ -8,8 +8,7 @@ import { test } from 'node:test'; import assert from 'node:assert/strict'; import { Readable } from 'node:stream'; -import { cctvProxy } from '../../server/providers/cctv.js'; -import { recordingResponse } from './cctvRecordingResponse.mjs'; +import { mountCctvProvider } from '../testSupport/cctvProviderHarness.mjs'; const STILL = { id: 'still-fixture', @@ -64,72 +63,17 @@ function upstreamResponse({ status = 200, headers = {}, body = 'payload' }) { }; } -/** - * Mount the real provider over the fixture cameras and answer every upstream - * request from the supplied function. - */ +/** Mount the real provider over the fixture cameras, recording upstream requests. */ function mount(t, respond) { - const before = { - json: process.env.CCTV_SOURCES_JSON, - file: process.env.CCTV_SOURCES_FILE, - austin: process.env.CCTV_FORCE_AUSTIN, - serverKey: process.env.GOOGLE_MAPS_SERVER_API_KEY, - browserKey: process.env.GOOGLE_MAPS_API_KEY, - }; - process.env.CCTV_SOURCES_JSON = JSON.stringify([ - STILL, - STILL_ALIAS, - VIDEO, - WEBM, - MJPEG, - ]); - process.env.CCTV_SOURCES_FILE = 'absent-source-file.json'; - process.env.CCTV_FORCE_AUSTIN = '0'; - // No Street View key: a /frame miss lands on the synthetic billboard rather - // than a network call this file does not model. - delete process.env.GOOGLE_MAPS_SERVER_API_KEY; - delete process.env.GOOGLE_MAPS_API_KEY; - const nativeFetch = globalThis.fetch; const requests = []; - globalThis.fetch = async (url, init = {}) => { - requests.push({ url: String(url), redirect: init.redirect }); - return respond({ url: String(url), init }); - }; - t.after(() => { - globalThis.fetch = nativeFetch; - for (const [name, value] of [ - ['CCTV_SOURCES_JSON', before.json], - ['CCTV_SOURCES_FILE', before.file], - ['CCTV_FORCE_AUSTIN', before.austin], - ['GOOGLE_MAPS_SERVER_API_KEY', before.serverKey], - ['GOOGLE_MAPS_API_KEY', before.browserKey], - ]) { - if (value === undefined) delete process.env[name]; - else process.env[name] = value; - } - }); - - let handler = null; - cctvProxy().configureServer({ - middlewares: { - use: (_route, fn) => { - handler = fn; - }, + const app = mountCctvProvider(t, { + cameras: [STILL, STILL_ALIAS, VIDEO, WEBM, MJPEG], + fetch: async (url, init = {}) => { + requests.push({ url: String(url), redirect: init.redirect }); + return respond({ url: String(url), init }); }, }); - assert.ok(handler, 'the CCTV provider must mount a middleware'); - - const call = async (path, headers = {}, method = 'GET') => { - const { res, done } = recordingResponse(); - await handler({ url: path, headers, method, on() {} }, res); - await done; - return res; - }; - const health = async (id) => { - const res = await call('/health'); - return JSON.parse(res.body).cameras.find((entry) => entry.id === id); - }; - return { call, health, requests }; + return { ...app, requests }; } test('a still camera is refused by /media without any upstream request', async (t) => { diff --git a/src/data/cctvMediaRange.test.mjs b/src/data/cctvMediaRange.test.mjs index 9f279bdc77..42021d3c28 100644 --- a/src/data/cctvMediaRange.test.mjs +++ b/src/data/cctvMediaRange.test.mjs @@ -9,7 +9,7 @@ import assert from 'node:assert/strict'; import http from 'node:http'; import net from 'node:net'; import { Readable, Writable } from 'node:stream'; -import { cctvProxy } from '../../server/providers/cctv.js'; +import { mountCctvProvider } from '../testSupport/cctvProviderHarness.mjs'; import { proxyMediaResponse } from '../../server/providers/cctv/media.js'; import { sanitizeCctvRangeHeader } from '../../server/providers/cctv/range.js'; import { CCTV_MEDIA_MAX_BODY_BYTES as CAP } from '../../server/providers/cctv/constants.js'; @@ -131,99 +131,21 @@ function upstreamResponse({ status = 206, headers = {}, body = 'payload' }) { }; } -/** Collects what a handler wrote, the way a Node ServerResponse would. */ -function recordingResponse() { - const chunks = []; - let finished; - const done = new Promise((resolve) => { - finished = resolve; - }); - const res = { - statusCode: 0, - headers: {}, - writableEnded: false, - body: '', - writeHead(status, headers) { - res.statusCode = status; - res.headers = headers || {}; - }, - write(chunk) { - chunks.push(Buffer.from(chunk)); - return true; - }, - end(chunk) { - if (chunk) chunks.push(Buffer.from(chunk)); - res.writableEnded = true; - res.body = Buffer.concat(chunks).toString('utf8'); - finished(); - }, - on() {}, - once() {}, - emit() {}, - destroy() {}, - }; - return { res, done }; -} - -/** - * Mount the real provider, serve one camera, and answer its upstream from the - * supplied function. - */ +/** Mount the real provider over the fixture cameras, recording upstream requests. */ function mount(t, respond) { - const before = { - json: process.env.CCTV_SOURCES_JSON, - file: process.env.CCTV_SOURCES_FILE, - austin: process.env.CCTV_FORCE_AUSTIN, - }; - process.env.CCTV_SOURCES_JSON = JSON.stringify([CAMERA]); - process.env.CCTV_SOURCES_FILE = 'absent-source-file.json'; - process.env.CCTV_FORCE_AUSTIN = '0'; - const nativeFetch = globalThis.fetch; const requests = []; - globalThis.fetch = async (url, init = {}) => { - requests.push({ - url: String(url), - headers: init.headers || {}, - signal: init.signal || null, - }); - return respond({ url: String(url), init }); - }; - t.after(() => { - globalThis.fetch = nativeFetch; - for (const [name, value] of [ - ['CCTV_SOURCES_JSON', before.json], - ['CCTV_SOURCES_FILE', before.file], - ['CCTV_FORCE_AUSTIN', before.austin], - ]) { - if (value === undefined) delete process.env[name]; - else process.env[name] = value; - } - }); - - let handler = null; - const plugin = cctvProxy(); - plugin.configureServer({ - middlewares: { - use: (_route, fn) => { - handler = fn; - }, + const app = mountCctvProvider(t, { + cameras: [CAMERA], + fetch: async (url, init = {}) => { + requests.push({ + url: String(url), + headers: init.headers || {}, + signal: init.signal || null, + }); + return respond({ url: String(url), init }); }, }); - assert.ok(handler, 'the CCTV provider must mount a middleware'); - - /** Drive one request through the mounted handler. */ - const call = async (path, headers = {}) => { - const { res, done } = recordingResponse(); - await handler({ url: path, headers, method: 'GET', on() {} }, res); - await done; - return res; - }; - /** Read the camera's current health entry. */ - const health = async () => { - const res = await call('/health'); - return JSON.parse(res.body).cameras.find(({ id }) => id === CAMERA.id); - }; - return { call, health, requests, handler: (req, res) => handler(req, res) }; + return { ...app, requests, health: () => app.health(CAMERA.id) }; } test('a canonical range reaches the upstream and its 206 is passed through', async (t) => { diff --git a/src/data/cctvRecordingResponse.mjs b/src/data/cctvRecordingResponse.mjs deleted file mode 100644 index 5d45e38a8f..0000000000 --- a/src/data/cctvRecordingResponse.mjs +++ /dev/null @@ -1,38 +0,0 @@ -// Test support for the CCTV middleware tests: no test file of its own. - -/** Collects what a handler wrote, the way a Node ServerResponse would. */ -export function recordingResponse() { - const chunks = []; - let finished; - const done = new Promise((resolve) => { - finished = resolve; - }); - const res = { - statusCode: 0, - headers: {}, - writableEnded: false, - body: '', - writeHead(status, headers) { - res.statusCode = status; - res.headers = { ...res.headers, ...headers }; - }, - setHeader(name, value) { - res.headers[name] = value; - }, - write(chunk) { - chunks.push(Buffer.from(chunk)); - return true; - }, - end(chunk) { - if (chunk) chunks.push(Buffer.from(chunk)); - res.writableEnded = true; - res.body = Buffer.concat(chunks).toString('utf8'); - finished(); - }, - on() {}, - once() {}, - emit() {}, - destroy() {}, - }; - return { res, done }; -} diff --git a/src/testSupport/cctvProviderHarness.mjs b/src/testSupport/cctvProviderHarness.mjs new file mode 100644 index 0000000000..8b7369470e --- /dev/null +++ b/src/testSupport/cctvProviderHarness.mjs @@ -0,0 +1,91 @@ +import { cctvProxy } from '../../server/providers/cctv.js'; + +/** Collects what a handler wrote, the way a Node ServerResponse would. */ +export function recordingResponse() { + const chunks = []; + let finished; + const done = new Promise((resolve) => { + finished = resolve; + }); + const res = { + statusCode: 0, + headers: {}, + writableEnded: false, + body: '', + writeHead(status, headers) { + res.statusCode = status; + res.headers = { ...res.headers, ...headers }; + }, + setHeader(name, value) { + res.headers[name] = value; + }, + write(chunk) { + chunks.push(Buffer.from(chunk)); + return true; + }, + end(chunk) { + if (chunk) chunks.push(Buffer.from(chunk)); + res.writableEnded = true; + res.body = Buffer.concat(chunks).toString('utf8'); + finished(); + }, + on() {}, + once() {}, + emit() {}, + destroy() {}, + }; + return { res, done }; +} + +export function mountCctvProvider(t, { cameras, fetch }) { + const saved = {}; + for (const name of [ + 'CCTV_SOURCES_JSON', + 'CCTV_SOURCES_FILE', + 'CCTV_FORCE_AUSTIN', + 'GOOGLE_MAPS_SERVER_API_KEY', + 'GOOGLE_MAPS_API_KEY', + ]) + saved[name] = process.env[name]; + + const nativeFetch = globalThis.fetch; + const closers = []; + t.after(() => { + for (const close of closers) close(); + globalThis.fetch = nativeFetch; + for (const [name, value] of Object.entries(saved)) { + if (value === undefined) delete process.env[name]; + else process.env[name] = value; + } + }); + + process.env.CCTV_SOURCES_JSON = JSON.stringify(cameras); + process.env.CCTV_SOURCES_FILE = 'absent-source-file.json'; + process.env.CCTV_FORCE_AUSTIN = '0'; + // No Street View key: a /frame miss lands on the synthetic billboard. + delete process.env.GOOGLE_MAPS_SERVER_API_KEY; + delete process.env.GOOGLE_MAPS_API_KEY; + // The HLS puller binds fetch when cctvProxy() creates it, so mock first. + globalThis.fetch = fetch; + let handler; + cctvProxy().configureServer({ + httpServer: { on: (_event, fn) => closers.push(fn) }, + middlewares: { use: (_route, fn) => (handler = fn) }, + }); + if (!handler) throw new Error('the CCTV provider must mount a middleware'); + + const call = async (path, headers = {}, method = 'GET', remoteAddress) => { + const { res, done } = recordingResponse(); + await handler( + { url: path, headers, method, socket: { remoteAddress }, on() {} }, + res, + ); + await done; + return res; + }; + const health = async (id) => { + const res = await call('/health'); + return JSON.parse(res.body).cameras.find((entry) => entry.id === id); + }; + return { call, health, handler }; +} From 58d2c23860b4bfe19ab676b9d4ec40cee1a67c63 Mon Sep 17 00:00:00 2001 From: German Khokhlov Date: Fri, 20 Nov 2026 12:29:50 +0400 Subject: [PATCH 13/13] fix(cctv): label a refused viewer's frame fallback instead of the live row MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit /frame now keeps a pullable HLS camera's shared health, so a viewer refused for capacity saw its placeholder or Street View frame under the live row's LIVE · OK badge and "Live HLS connected". When a video camera is shown on its frame fallback while the row says live, the panel badge now reads FALLBACK · DEGRADED and the meta line drops the live message; the shared row stays as it is for the other viewers. --- changelog.d/1267-cctv-hls-capacity-health.md | 5 +- docs/CURRENT-STATE.md | 4 +- src/data/cctvRefusedViewerBadge.test.mjs | 85 ++++++++++++++++++++ src/ui/cctvFrames.js | 13 +++ src/ui/cctvPresentation.js | 13 ++- 5 files changed, 113 insertions(+), 7 deletions(-) create mode 100644 src/data/cctvRefusedViewerBadge.test.mjs diff --git a/changelog.d/1267-cctv-hls-capacity-health.md b/changelog.d/1267-cctv-hls-capacity-health.md index a86c90e82a..e40c0762e1 100644 --- a/changelog.d/1267-cctv-hls-capacity-health.md +++ b/changelog.d/1267-cctv-hls-capacity-health.md @@ -1,4 +1,5 @@ - Stop reporting a live HLS camera as degraded when a viewer is refused because every viewer or session slot is taken: the refusal answers 503 with - `Retry-After`, and the frame shown in its place leaves the camera's health - as it was (asturksever, gekh, #1267). + `Retry-After`, the frame shown in its place leaves the camera's health + as it was, and that viewer's panel labels the frame `FALLBACK · DEGRADED` + rather than live (asturksever, gekh, #1267). diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index a05ed3c4ae..ee9c7e6d95 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -9658,7 +9658,9 @@ coexist with at most eight independent consumer leases each; no-access lease expiry is 15 seconds. A viewer refused because every lease or session slot is taken gets 503 with `Retry-After: 2` and leaves the camera's health unchanged; so does its frame fallback, since an HLS camera without a snapshot has no frame -of its own. Closing one consumer leaves other consumers running. Lease +of its own. That viewer's panel badge reads FALLBACK · DEGRADED and its meta +line drops the live health message, since the shared live health does not +describe the frame it shows. Closing one consumer leaves other consumers running. Lease ids use `crypto.randomUUID` where the page is a secure context and an equivalent v4 id from `crypto.getRandomValues` on plain-HTTP LAN pages. Encrypted/fMP4/byte-range playlists fail closed. Performance and live agency reliability require recorded validation. diff --git a/src/data/cctvRefusedViewerBadge.test.mjs b/src/data/cctvRefusedViewerBadge.test.mjs new file mode 100644 index 0000000000..8231eb0e83 --- /dev/null +++ b/src/data/cctvRefusedViewerBadge.test.mjs @@ -0,0 +1,85 @@ +// Reproduction: a viewer refused for HLS capacity is shown its fallback frame +// under a badge that still reads the shared live health ("LIVE · OK"). +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { HLS_LIMITS } from '../../server/providers/cctv/stream.js'; +import { mountCctvProvider } from '../testSupport/cctvProviderHarness.mjs'; +import { presentCctvSourceBadge } from '../ui/cctvFrames.js'; +import { presentCctvPanel } from '../ui/cctvPresentation.js'; + +const SAME_ORIGIN = { host: 'localhost:4173', 'sec-fetch-site': 'same-origin' }; +const PLAYLIST = + '#EXTM3U\n#EXT-X-TARGETDURATION:2\n#EXT-X-MEDIA-SEQUENCE:12\n#EXTINF:2,\na.ts\n#EXTINF:2,\nb.ts\n#EXTINF:2,\nc.ts\n'; +const lease = (index) => + `00000000-0000-4000-8000-${String(index).padStart(12, '0')}`; +const camera = (id) => ({ + id, + name: id, + lat: 30.27, + lon: -97.74, + feedType: 'hls', + url: `https://cams.upstream.invalid/${id}/list.m3u8`, +}); + +test('a capacity-refused viewer is not shown its fallback frame as live and ok', async (t) => { + assert.equal(HLS_LIMITS.sessions, 2); + const { call, health } = mountCctvProvider(t, { + cameras: ['cam-a', 'cam-b', 'cam-c'].map(camera), + fetch: async (url) => + new Response(String(url).endsWith('.m3u8') ? PLAYLIST : 'abc'), + }); + const open = (id, index) => + call(`/media/${id}?lease=${lease(index)}`, SAME_ORIGIN); + // cam-c played earlier and was released: its row is live/ok. + assert.equal((await open('cam-c', 0)).statusCode, 200); + assert.equal( + (await call(`/media/cam-c?lease=${lease(0)}`, SAME_ORIGIN, 'DELETE')) + .statusCode, + 204, + ); + // Two other viewers now hold both camera sessions. + assert.equal((await open('cam-a', 1)).statusCode, 200); + assert.equal((await open('cam-b', 2)).statusCode, 200); + // The cam-c viewer is refused and falls back to the frame. + const refused = await open('cam-c', 3); + assert.equal(refused.statusCode, 503); + const frame = await call('/frame/cam-c', SAME_ORIGIN); + assert.equal(frame.statusCode, 200); + assert.equal(frame.headers['X-CCTV-Source'], 'synthetic'); + assert.match(frame.body, /UPSTREAM UNAVAILABLE/); + const row = await health('cam-c'); + // The badge the panel derives for this viewer, in image (fallback) mode. + const shown = { + feedType: 'hls', + isVideo: false, + sourceKind: row?.sourceKind || 'configured', + sourceStatus: row?.status || 'unknown', + sourceMessage: row?.message || '', + }; + const badge = presentCctvSourceBadge(shown, true, { + loading: false, + error: false, + hasFrame: true, + }); + assert.notEqual( + badge.label, + 'LIVE · OK', + `fallback frame (${frame.headers['X-CCTV-Source']}) labelled ${badge.label}; health message "${row?.message}"`, + ); + const { meta } = presentCctvPanel( + { + enabled: true, + activeCameraId: 'cam-c', + activeCamera: { + ...shown, + id: 'cam-c', + city: 'Austin', + headingDeg: 0, + fovDeg: 60, + rangeM: 100, + }, + }, + true, + ); + assert.doesNotMatch(meta, /Live HLS connected/); +}); diff --git a/src/ui/cctvFrames.js b/src/ui/cctvFrames.js index 7617111748..171a67fb34 100644 --- a/src/ui/cctvFrames.js +++ b/src/ui/cctvFrames.js @@ -186,6 +186,14 @@ export function _settleCctvFrame(token, src, ok) { ); } +/** Shared live health describes the stream even when this viewer shows a frame. */ +export function isCctvLiveFrameFallback(activeCamera) { + return ( + activeCamera?.isVideo === false && + String(activeCamera.sourceKind || '').toLowerCase() === 'live' + ); +} + /** The source badge's label and frame state for the camera and preview. */ export function presentCctvSourceBadge(activeCamera, enabled, frame) { if (!enabled || !activeCamera) @@ -194,6 +202,11 @@ export function presentCctvSourceBadge(activeCamera, enabled, frame) { return { label: t('FRAME · LOADING'), state: 'loading' }; if (frame.error && !frame.hasFrame) return { label: t('FRAME · UNAVAILABLE'), state: 'error' }; + if (isCctvLiveFrameFallback(activeCamera)) + return { + label: `${cctvSourceKindLabel('fallback')} · ${cctvSourceStatusLabel('degraded')}`, + state: 'ready', + }; const kind = cctvSourceKindLabel( activeCamera.sourceKind || activeCamera.feedType || 'unknown', ); diff --git a/src/ui/cctvPresentation.js b/src/ui/cctvPresentation.js index 2f4cb8584e..92653e0ad7 100644 --- a/src/ui/cctvPresentation.js +++ b/src/ui/cctvPresentation.js @@ -1,5 +1,9 @@ import { getLocale, keepCodesWithValues, msg, t, tn } from '../i18n/index.js'; -import { cctvSourceLabelText, cctvSourceMessageText } from './cctvFrames.js'; +import { + cctvSourceLabelText, + cctvSourceMessageText, + isCctvLiveFrameFallback, +} from './cctvFrames.js'; import { createCctvVideoSurface } from './cctvVideo.js'; import { presentCctvCalibration } from './cctvCalibration.js'; @@ -96,9 +100,10 @@ function metaText(state, enabled, activeCamera, catalogCount) { const provider = cctvSourceLabelText( activeCamera.sourceLabel || activeCamera.provider || 'Configured Source', ); - const statusMsg = activeCamera.sourceMessage - ? ` · ${cctvSourceMessageText(activeCamera.sourceMessage)}` - : ''; + const statusMsg = + activeCamera.sourceMessage && !isCctvLiveFrameFallback(activeCamera) + ? ` · ${cctvSourceMessageText(activeCamera.sourceMessage)}` + : ''; // A partner-supplied feed inside a pack names its owner here. const credit = activeCamera.credit ? ` · ${activeCamera.credit}` : ''; const calBadge = activeCamera.calBadge