feat: per-origin HTTP concurrency limiter for COG layers

[kylebarron]

Huge reduction in network requests with the MosaicLayer

before, scrolling around generates many many requests that aren't cancelled when panning around the map. You can see we fetch almost 300MB of data before loading the data in the end viewport location

Screen.Recording.2026-05-19.at.5.20.43.PM-clip.mov

after we've only fetched 150MB of data even after a ton of scrolling. The request cancellation is working much better:

Screen.Recording.2026-05-19.at.5.16.37.PM.mov

Closes #555

---

Summary

Adds a shared, per-origin HTTP concurrency limiter that caps concurrent tile-data fetches per host across all COGLayer / MultiCOGLayer / MosaicLayer instances on a page, with dynamic, viewport-aware priority so center-of-screen sources jump the queue.

The problem this addresses. Most COGs we target live on AWS S3 (or similar), which serves HTTP/1.1 only. Browsers cap concurrent HTTP/1.1 connections per origin at ~6 (Chrome). deck.gl's Tileset2D ships a RequestScheduler({ maxRequests: 6 }) per-TileLayer instance — so two COGLayers on the same S3 bucket can each schedule 6 → ≥12 in flight → the browser queues the excess. Worse, those queued requests stick around when the viewport pans, blocking fresh requests behind stale ones. The cap has to be per origin, shared across layers, and the queue has to re-order on pan so newly-central sources are serviced before stale edge sources.

What's in this PR

In @developmentseed/geotiff:

• ConcurrencyLimiter interface — acquire(url, signal?, getPriority?: () => Priority): Promise<() => void>. Signal-aware: a queued request whose signal aborts (e.g. user panned away) is dropped before any network I/O fires, no slot burned.
• Priority type — number | readonly number[]. Numbers compare numerically; arrays compare lexicographically with missing trailing elements treated as 0, so [1] and [1, 0, 0] are equivalent and [1, -1] jumps ahead of [1]. Lower = serviced sooner.
• Dynamic priority — getPriority is a callback, re-invoked on every slot-open. Panning the viewport re-sorts the queue without any explicit "reprioritize" call. A linear-scan find-min on release is the right primitive here (a heap can't represent priorities that move under it).
• PerOriginSemaphore class — default impl. Maintains Map<origin, Semaphore> internally; one PerOriginSemaphore({ maxRequests: 6 }) shared across layers gates each origin to 6 in flight, independently.
• LimiterMiddleware class — chunkd SourceMiddleware, shape matches SourceChunk / SourceCache. Slotted into the existing header-source SourceView after the cache, so cache hits short-circuit and never burn a slot — only uncached network reads gate. Data source path gets a tiny SourceView of its own with just the middleware, so every tile-data fetch gates.
• GeoTIFF.fromUrl(url, { concurrencyLimiter?, getPriority? }) — accepts a limiter (non-null → installed; null or omitted → no gating) and an optional priority callback forwarded to the limiter for every fetch through this GeoTIFF's sources.
• Semaphore (the FIFO + priority primitive) stays internal. Public surface: ConcurrencyLimiter (type), Priority (type), PerOriginSemaphore (class).

In @developmentseed/deck.gl-geotiff:

• defaultConcurrencyLimiter — a module-level new PerOriginSemaphore({ maxRequests: 6 }). Referenced from COGLayer, MultiCOGLayer, and MosaicLayer's defaultProps.concurrencyLimiter, so any two layers on the same origin share one cap out of the box, zero user setup.
• concurrencyLimiter?: ConcurrencyLimiter | null prop on COGLayer, MultiCOGLayer, and MosaicLayer. Pass your own to override; pass null to disable.
• MosaicLayer priority — computes a getPriority per source (euclidean distance from source.bbox center to the current viewport center, in degree-space) and threads it, along with the layer's concurrencyLimiter, through getSource's opts. A consumer's getSource can spread opts straight into GeoTIFF.fromUrl so both wire up automatically.
• fetchGeoTIFF accepts the options and forwards them to GeoTIFF.fromUrl.

Cancellation flow

1. deck.gl pans → Tileset2D._pruneRequests aborts unselected in-flight tiles.
2. Each tile's AbortSignal propagates through getTileData → fetchTile → dataSource.fetch(..., { signal }).
3. LimiterMiddleware forwards the signal to limiter.acquire(url, signal, getPriority):
   • Already aborted → reject immediately, no slot consumed.
   • Aborted while queued in the inner Semaphore → splice from queue, reject, no slot consumed.
   • Aborted in-flight (after acquire) → underlying fetch aborts via its own signal handling; finally releases the slot.

Priority flow

1. MosaicLayer.getTileData builds a getPriority closure that reads this.context.viewport lazily, so each invocation sees the current viewport (not the one at queue time).
2. The closure is passed to getSource(opts); example app spreads opts into GeoTIFF.fromUrl.
3. LimiterMiddleware forwards it to every acquire call.
4. Semaphore.release linear-scans pending waiters, calls each one's getPriority(), picks the min, and resumes it. Panning the viewport between releases mutates the values the next scan sees — no explicit re-queue.

Out of scope (deferred)

• Multi-tile request coalescing (the TileBatcher / getMultiTileData thread from the design discussion). The interaction with deck.gl's _pruneRequests (which only fires when ongoing > maxRequests) made it more involved than expected — gating + priority first is cleanly mergeable and unblocks the cross-layer pain point; coalescing follows.
• Subclassing Tileset2D to fire abort signals on onTileUnload regardless of maxRequests.
• Upstream deck.gl proposals (getTileDataBatched, public pruneRequests, etc.) — captured in the spec.
• A standalone @developmentseed/concurrency package — the limiter primitives live in @developmentseed/geotiff for now; extractable later when/if a non-geotiff source format wants to share an instance.

Spec

dev-docs/specs/2026-05-19-concurrency-limiter-design.md.

Test plan

• pnpm --filter @developmentseed/geotiff test — passes. New: Semaphore (FIFO + signal + dynamic priority) tests, PerOriginSemaphore tests, LimiterMiddleware tests, fromUrl({ concurrencyLimiter, getPriority }) integration tests with SourceHttp.fetch stubbed. The 17 pre-existing integration-rasterio.test.ts failures are unrelated (missing local .npy fixtures).
• pnpm --filter @developmentseed/deck.gl-geotiff test — passes. concurrency-limiter.test.ts confirms COGLayer / MultiCOGLayer / MosaicLayer all default concurrencyLimiter to the same module-level PerOriginSemaphore instance.
• pnpm --filter @developmentseed/geotiff typecheck + pnpm --filter @developmentseed/deck.gl-geotiff typecheck — clean.
• pnpm biome check packages/geotiff packages/deck.gl-geotiff examples/naip-mosaic — clean.
• Manual: naip-mosaic example with ~100 COGs in view — first rendered tile is now near viewport center (was bottom-left), time-to-first-render dropped from ~5s to sub-second.

Part of #273 (the multi-tile coalescing other half is a follow-up).

🤖 Generated with Claude Code

[kylebarron]

I think it would be cleaner if we defined a middleware class similar to SourceChunk and SourceCache that we could slot in, rather than overriding the fetch like this.

Also what's the benefit of not limiting header fetches? Those still count too, right?

[kylebarron]

Can we put this into a helper function instead of having it inline? It's verbose.

Maybe something like function createGetPriorityCallback?

[kylebarron]

I think this might be clearer as a helper function

[kylebarron]

Ok after a LOT of back and forth I think this PR is ready to merge!