Parallelize quadrant fetching and add smart 429 retry

[dougborg]

Closes #109

Summary

• Parallelizes quadrant fetches with Future.wait() instead of sequential for-loop — at max split depth (3), up to 64 requests can overlap instead of running one-by-one
• Adds dynamic concurrency limiter (_AsyncSemaphore) sized from Overpass /api/status slot count, so we never exceed the server's per-IP rate limit
• Replaces "sleep 30s and give up" 429 behavior with smart retry: polls /api/status until a slot is available, retries up to 2 times, and resizes the semaphore with the latest observed slot count
• Cancels stale fetch requests via a generation counter — when the user pans/zooms mid-fetch, queued sub-requests bail out instead of blocking the semaphore for the area the user actually wants to see

What changed

lib/services/overpass_service.dart

• HTTP client injection via constructor (OverpassService({http.Client? client})) following the RoutingService pattern — enables mock-based testing
• getSlotCount() — queries /api/status and parses Rate limit: N, falls back to 4
• waitForSlot() — polls /api/status until "slots available now" appears, parsing "in N seconds" for smart delay, bounded by maxWait (default 2 min)

lib/services/node_data_manager.dart

• DI constructors — NodeDataManager._({OverpassService?, NodeSpatialCache?}) + NodeDataManager.forTesting() factory
• _AsyncSemaphore — resizable async semaphore; resize() wakes queued waiters when capacity increases; capacity clamped to >= 1 to prevent deadlock; uses Queue for O(1) dequeue
• Lazy semaphore init — _semaphoreInitFuture caches the init Future so concurrent calls get the same instance
• fetchWithSplitting now wraps fetchNodes in semaphore.run() and handles RateLimitError by polling + retrying (max 2)
• _fetchSplitAreas now uses Future.wait() for parallel quadrant fetching
• splitBounds renamed from _splitBounds, made static + @visibleForTesting for direct unit testing
• Generation counter for stale-fetch cancellation:
  • _fetchGeneration int incremented each getNodesFor() call
  • _isStale(int? generation) checked at 6 cooperative checkpoints throughout the fetch pipeline (before semaphore, inside lambda, before splitting, before/after waitForSlot, top of _fetchSplitAreas)
  • null generation (offline download, map_data_provider.dart) is never stale — zero regression risk
  • Stale requests that already completed in-flight still cache their data (valid if user pans back); short-circuited stale requests don't mark the area as fetched

lib/services/node_spatial_cache.dart

• Added NodeSpatialCache.forTesting() constructor

test/services/node_data_manager_test.dart (new)

23 tests using mocktail + fake_async:

• splitBounds — correct quadrant geometry, exact tiling (no gaps/overlaps)
• getSlotCount — parses rate limit, falls back on HTTP/network failure
• waitForSlot — immediate return, wait-and-repoll, unparseable fallback, slot count changes (all using FakeAsync)
• fetchWithSplitting — happy path, NodeLimitError split, max depth, rate limit retry + cap
• _fetchSplitAreas — partial failure (1/4 fails), total failure, recursive splitting
• Stale fetch cancellation — skips fetch entirely, prevents HTTP call inside lambda, prevents recursive splitting, skips waitForSlot, null generation backward compat
• Semaphore init — concurrent calls deduplicate

Design notes

The semaphore is safe without locks because Dart's event loop is single-threaded: microtasks from Completer.complete() drain sequentially before new events can enter run(). Each woken waiter re-checks while (_current >= _maxConcurrent) before proceeding.

/api/status is not polled on every request

The /api/status endpoint is only hit in two situations:

1. Once per app lifetime — getSlotCount() is called during semaphore initialization, and the result is cached via _semaphoreInitFuture ??=. All subsequent requests reuse the cached semaphore instance with no network call.
2. Only when rate-limited — waitForSlot() is called inside the on RateLimitError handler, and only up to 2 times per request (capped by rateLimitRetries). This is where we poll until a slot opens up, then resize the semaphore with the fresh count.

Stale fetch cancellation avoids ~95% of wasted work

We can't cancel in-flight HTTP requests (the http package has no CancelToken), but the generation counter prevents queued/pending work from starting. Since only 4 requests run concurrently while up to 60 may be queued, this captures the vast majority of the benefit without changing the HTTP layer.

Test plan

• flutter analyze — 0 issues
• flutter test — 23/23 pass in node_data_manager_test
• Manual: navigate to a surveillance-dense area (e.g. London, DC) → verify splitting is faster and debug logs show Overpass semaphore: N slots
• Manual: trigger rate limit → verify Waiting N seconds for slot appears and request retries successfully
• Manual: rapid panning in a dense area → stale requests should cancel, new area loads faster

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR improves Overpass-based node fetching performance and resilience by parallelizing quadrant fetches during splitting and adding adaptive rate-limit handling based on Overpass /api/status.

Changes:

• Parallelize quadrant fetching via Future.wait() while limiting total concurrency with a resizable async semaphore.
• Add /api/status support in OverpassService to derive slot count and to poll until a slot is available for smarter 429 retries.
• Add DI hooks and new unit tests covering splitting, semaphore init, and rate-limit behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
lib/services/overpass_service.dart	Injects HTTP client and adds /api/status helpers (getSlotCount, waitForSlot) to support adaptive concurrency + 429 retry.
lib/services/node_data_manager.dart	Introduces _AsyncSemaphore, rate-limit retry behavior, and parallel quadrant fetching in _fetchSplitAreas.
lib/services/node_spatial_cache.dart	Adds a forTesting() constructor to support test setup.
test/services/node_data_manager_test.dart	Adds extensive tests for splitting geometry, status parsing/polling, retries, and semaphore init deduplication.
COMMENT	Adds an unrelated note/snippet that doesn’t appear connected to the PR’s purpose.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.