From 1dd0258c0b4af51ea532428a863f634783f6ddf5 Mon Sep 17 00:00:00 2001 From: stopflock Date: Sat, 31 Jan 2026 17:35:42 -0600 Subject: [PATCH] cleanup, bump version --- DEVELOPER.md | 45 ++++++++------ NETWORK_STATUS_REFACTOR.md | 118 ------------------------------------- README.md | 1 - pubspec.yaml | 2 +- 4 files changed, 28 insertions(+), 138 deletions(-) delete mode 100644 NETWORK_STATUS_REFACTOR.md diff --git a/DEVELOPER.md b/DEVELOPER.md index dc109b6..eaf1db1 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -395,30 +395,39 @@ Local cache contains production data. Showing production nodes in sandbox mode w **Why separate from follow mode:** Users often want to follow their location while keeping the map oriented north. Previous "north up" follow mode was confusing because it didn't actually keep north up. This separation provides clear, predictable behavior. -### 10. Network Status Indicator (Simplified in v1.5.2+) +### 10. Network Status Indicator (Refactored in v2.6.1) **Purpose**: Show loading and error states for surveillance data fetching only -**Simplified approach (v1.5.2+):** -- **Surveillance data focus**: Only tracks node/camera data loading, not tile loading -- **Visual feedback**: Tiles show their own loading progress naturally -- **Reduced complexity**: Eliminated tile completion tracking and multiple issue types +**Brutalist approach (v2.6.1+):** +- **Single enum state**: Replaced multiple boolean flags with simple `NetworkRequestStatus` enum +- **User-initiated only**: Only tracks latest user-initiated requests (pan/zoom), background requests ignored +- **Auto-reset timers**: Different timeouts for different states (success: 2s, errors: 5s, rate limit: 2min) -**Status types:** -- **Loading**: Shows when fetching surveillance data from APIs -- **Success**: Brief confirmation when data loads successfully -- **Timeout**: Network request timeouts -- **Limit reached**: When node display limit is hit -- **API issues**: Overpass/OSM API problems only +**Status states:** +```dart +enum NetworkRequestStatus { + idle, // No indicator shown + loading, // Initial request in progress + splitting, // Request being split due to limits/timeouts + success, // Data loaded successfully (brief confirmation) + timeout, // Request timed out + rateLimited, // API rate limited + noData, // No offline data available + error, // Other network errors +} +``` -**What was removed:** -- Tile server issue tracking (tiles handle their own progress) -- "Both" network issue type (only surveillance data matters) -- Complex semaphore-based completion detection -- Tile-related status messages and localizations +**State transitions:** +- **Normal flow**: `idle` → `loading` → `success` → `idle` +- **Split requests**: `loading` → `splitting` → `success` → `idle` +- **Errors**: `loading` → `timeout/error/rateLimited` → `idle` -**Why the change:** -The previous approach tracked both tile loading and surveillance data, creating redundancy since tiles already show loading progress visually on the map. Users don't need to be notified about tile loading issues when they can see tiles loading/failing directly. Focusing only on surveillance data makes the indicator more purposeful and less noisy. +**Why the refactor:** +The previous system used multiple boolean flags with complex reconciliation logic, creating potential for conflicting states and race conditions. The new enum-based approach provides clear, explicit state management with predictable transitions and eliminates complexity while maintaining all functionality. + +**Request ownership:** +Only user-initiated requests (pan, zoom, manual refresh) report status. Background requests (pre-fetch, cache warming) complete silently to avoid status indicator noise. ### 11. Suspected Locations (v1.8.0+: SQLite Database Storage) diff --git a/NETWORK_STATUS_REFACTOR.md b/NETWORK_STATUS_REFACTOR.md deleted file mode 100644 index 1929365..0000000 --- a/NETWORK_STATUS_REFACTOR.md +++ /dev/null @@ -1,118 +0,0 @@ -# Network Status Refactor - v2.6.1 - -## Overview - -Completely rewrote the network status indicator system to use a simple enum-based approach instead of multiple boolean flags and complex timer management. - -## Key Changes - -### Before (Complex) -- Multiple boolean flags: `_overpassHasIssues`, `_isWaitingForData`, `_isTimedOut`, etc. -- Complex state reconciliation logic in `currentStatus` getter -- Multiple independent timers that could conflict -- Both foreground and background requests reporting status -- Inconsistent state transitions - -### After (Brutalist) -- Single enum: `NetworkRequestStatus` with 8 clear states -- Simple `_setStatus()` method handles all transitions and timers -- Only user-initiated requests report status (background requests ignored) -- Clear state ownership and no conflicting updates - -## New Status States - -```dart -enum NetworkRequestStatus { - idle, // No active requests (default, no indicator shown) - loading, // Initial request in progress - splitting, // Request being split due to limits/timeouts - success, // Data loaded successfully (auto-clears in 2s) - timeout, // Request timed out (auto-clears in 5s) - rateLimited, // API rate limited (auto-clears in 2min) - noData, // No offline data available (auto-clears in 3s) - error, // Other network errors (auto-clears in 5s) -} -``` - -## Behavior Changes - -### Request Splitting -- When a request needs to be split due to node limits or timeouts: - - Status transitions: `loading` → `splitting` → `success` - - Only the top-level (original) request manages status - - Sub-requests (quadrants) complete silently - -### Background vs User-Initiated Requests -- **User-initiated**: Pan/zoom actions, manual refresh - report status -- **Background**: Pre-fetch, cache warming - no status reporting -- Only one user-initiated request per area allowed at a time - -### Error Handling -- Rate limits: Clear red "Rate limited by server" with 2min timeout -- Network errors: Clear red "Network error" with 5s timeout -- Timeouts: Orange "Request timed out" with 5s timeout -- No data: Grey "No offline data" with 3s timeout - -## Files Modified - -### Core Implementation -- `lib/services/network_status.dart` - Complete rewrite (100+ lines → 60 lines) -- `lib/widgets/network_status_indicator.dart` - Updated to use new enum -- `lib/services/node_data_manager.dart` - Simplified status reporting logic - -### Status Reporting Cleanup -- `lib/services/map_data_submodules/nodes_from_osm_api.dart` - Removed independent status reporting - -### Localization -- Added new strings to all language files: - - `networkStatus.rateLimited` - - `networkStatus.networkError` - -### Documentation -- `assets/changelog.json` - Added v2.6.1 entry -- `test/services/network_status_test.dart` - Basic unit tests - -## Testing Checklist - -### Basic Functionality -- [ ] Initial app load shows no network indicator -- [ ] Pan/zoom to new area shows "Loading surveillance data..." -- [ ] Successful load shows "Surveillance data loaded" briefly (2s) -- [ ] Switch to offline mode, then pan - should show no indicator (instant data) - -### Error States -- [ ] Poor network → should show "Network error" (red, 5s timeout) -- [ ] Dense area that requires splitting → "Surveillance data slow" (orange) -- [ ] Offline area with no surveillance data → "No offline data" (grey, 3s) - -### Background vs Foreground -- [ ] Background requests (pre-fetch) should not affect indicator -- [ ] Only user pan/zoom actions should trigger status updates -- [ ] Multiple quick pan actions should not create conflicting status - -### Split Requests -- [ ] In very dense areas (SF, NYC), splitting should work correctly -- [ ] Status should transition: loading → splitting → success -- [ ] All quadrants must complete before showing success - -### Mode Switches -- [ ] Online → Offline: Any ongoing requests should not interfere -- [ ] Production → Sandbox: Should work with new request logic -- [ ] Manual refresh should reset and restart status properly - -## Potential Issues to Watch - -1. **Timer disposal**: Ensure timers are properly cancelled when app backgrounds -2. **Rapid status changes**: Quick pan actions shouldn't create flicker -3. **Split request coordination**: Verify all sub-requests complete properly -4. **Offline mode integration**: Status should be silent for instant offline data - -## Code Quality Improvements - -- **Reduced complexity**: 8 enum states vs 5+ boolean combinations -- **Single responsibility**: Each method does one clear thing -- **Brutalist approach**: Simple, explicit, easy to understand -- **Better debugging**: Clear state transitions with logging -- **Fewer race conditions**: Single timer per status type - -This refactor dramatically simplifies the network status system while maintaining all existing functionality and improving reliability. \ No newline at end of file diff --git a/README.md b/README.md index dc82dd0..847cfdb 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,6 @@ cp lib/keys.dart.example lib/keys.dart ### Needed Bugfixes - Default profile selection "" when editing an existing node -- Handle concurrent overpass requests better; cancel ongoing? Status indicator gets confused. - Make submission guide scarier - Tile cache trimming? Does fluttermap handle? - Filter NSI suggestions based on what has already been typed in diff --git a/pubspec.yaml b/pubspec.yaml index 575bb9e..914849c 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,7 +1,7 @@ name: deflockapp description: Map public surveillance infrastructure with OpenStreetMap publish_to: "none" -version: 2.6.0+44 # The thing after the + is the version code, incremented with each release +version: 2.6.1+45 # The thing after the + is the version code, incremented with each release environment: sdk: ">=3.5.0 <4.0.0" # oauth2_client 4.x needs Dart 3.5+