dandri/meshcore-analyzer
1
0
Fork 0
mirror of https://github.com/Kpa-clawbot/meshcore-analyzer.git synced 2026-08-07 01:40:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: trim release notes — less book, more changelog

Browse Source
This commit is contained in:
you
2026-04-08 06:56:50 +00:00
parent cde62166cb
commit f5d25f75c6
1 changed files with 42 additions and 193 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/release-notes/v3.5.0.md
+42 -193
View File
@@ -1,14 +1,13 @@
# CoreScope v3.5.0 Release Notes
# CoreScope v3.5.0
**95 commits** since v3.4.1 — the biggest release yet.
95 commits since v3.4.1.
---
## 🐳 Pre-built Docker Images — One-Line Deploy
## 🐳 Pre-built Docker Images
CoreScope now publishes pre-built Docker images to GitHub Container Registry. **No more building from source.**
No more building from source.
### Quick start
```bash
docker run -d --name corescope \
-p 80:80 -p 1883:1883 \
@@ -16,233 +15,83 @@ docker run -d --name corescope \
ghcr.io/kpa-clawbot/corescope:latest
```
### Transitioning from source builds
**Transitioning?** Stop your old container, keep your data volume, `docker pull ghcr.io/kpa-clawbot/corescope:latest`, run with the same mount. Done.
If you're currently building your own image:
Tags: `latest` (stable), `vX.Y.Z` (pinned), `edge` (master tip).
1. **Stop your existing container** — `docker stop corescope && docker rm corescope`
2. **Keep your data volume** — your SQLite DB and config.json are preserved in the bind mount
3. **Pull the pre-built image** — `docker pull ghcr.io/kpa-clawbot/corescope:latest`
4. **Run with your existing data** — mount the same volume:
```bash
docker run -d --name corescope \
-p 80:80 -p 1883:1883 \
-v /path/to/your/data:/app/data \
ghcr.io/kpa-clawbot/corescope:latest
```
### Image tags
- `ghcr.io/kpa-clawbot/corescope:latest` — latest stable release
- `ghcr.io/kpa-clawbot/corescope:vX.Y.Z` — pinned version (recommended for production)
- `ghcr.io/kpa-clawbot/corescope:edge` — tip of master (unstable, for testing)
### Zero-config defaults
No `config.json` required. The server starts with sensible defaults: HTTP on port 80 (via Caddy), internal MQTT broker on 1883, SQLite in `/app/data/`. Drop a `config.json` into your data volume to customize.
### New environment variables
- `DISABLE_CADDY=true` — skip the Caddy reverse proxy (if you bring your own)
- `DISABLE_MOSQUITTO=true` — skip the internal MQTT broker (if using an external one)
New env vars: `DISABLE_CADDY=true`, `DISABLE_MOSQUITTO=true`.
---
## ⚡ Performance
## ⚡ 35 Performance Fixes
**35 performance optimizations** — CoreScope now serves HTTP within 2 minutes on any database size.
### Headlines
- **Packets page**: p50 83% faster, p95 97% faster
- **Topology analytics**: p50 83% faster
- **Async backfill**: resolved_path backfill runs in the background — server is responsive during startup even with millions of observations
- **Memory**: prefix map capped at 8 chars (10x memory reduction)
### Backend
- Incremental max ID tracking — no more full table scans on ingest
- Batched eviction index cleanup
- Combined filter passes (single scan instead of chained)
- Single sort for RF analytics arrays
- Early time filter in node analytics
- In-memory hop resolution (eliminates N+1 DB queries)
- Incremental distance index updates
- Region observer caching (30s TTL)
- Store stats: 5→2 concurrent queries
- Subpath detail index instead of full packet scan
- Grouped packets: cached observer count, deferred map construction
### Frontend
- Coalesced WebSocket renders with requestAnimationFrame
- Replaced N+1 API calls with bulk `expand=observations` query
- Parallelized `replayRecent()` fetches
- Map markers repositioned on zoom instead of full rebuild
- Network status computed client-side
- Combined 4 subpath API calls into single bulk endpoint
- Batched observation fetching eliminates N+1 on sort
- Timeline updates skipped when tab is hidden
- Incremental DOM diff in virtual scroll
- Lazy observation maps in `txToMap`
- og-image compressed from 1.1MB to 235KB
- Packets p50 **83% faster**, p95 **97% faster**
- Server serves HTTP within **2 minutes** on any DB size (async backfill)
- Prefix map memory **10x reduction**
- N+1 API calls eliminated across packets, observations, subpaths, hop resolution
- WebSocket renders coalesced with rAF, map markers repositioned instead of rebuilt
---
## 🔬 RF Health Dashboard
New **RF Health** tab on the Analytics page with comprehensive observer radio metrics:
- **Small multiples grid** — one card per observer showing key metrics at a glance
- **Noise floor column chart** — color-coded bars (green/yellow/red by threshold) replacing the old line chart. Hover tooltips show exact dBm + timestamp
- **Airtime charts** — TX/RX airtime with delta computation
- **Error rate tracking** — receive errors per observer over time
- **Battery charts** — observer battery level monitoring
- **Region filter** — filter RF metrics by geographic region
- **Observer detail** — click any observer to see detailed metrics in a side panel
New Analytics tab: per-observer noise floor (color-coded columns), airtime, error rates, battery. Region filter. Click any observer for detail panel.
---
## 🗺️ Live Map Enhancements
## 🗺️ Live Map
### TRACE packet real path visualization
Trace packets now show where the trace **actually reached** vs the full intended route:
- **Solid animated line** for completed hops
- **Dashed/ghosted line** (25% opacity) for unreached hops
- Helps operators see exactly where traces fail
### Movable panels
- Overlay panels (feed, legend, node detail) have corner-position toggle buttons
- Non-scrolling panel headers keep controls accessible
- Panels remember their position in localStorage
### Collapsible panels
- All live map panels can be collapsed to just their header bar
- Medium breakpoint responsive layout
- **TRACE real path**: solid line for completed hops, dashed ghost for unreached
- **Movable panels**: corner toggle + non-scrolling headers
- **Collapsible panels**
---
## 📊 Analytics & Data
## 📊 Data Accuracy
### Hash Stats accuracy
- "By Repeaters" section now correctly filters to repeater-role nodes only (was including companions/rooms)
- Hash size display correctly shows "Unknown" for zero-hop direct adverts instead of misleading "1 byte"
### Prefix Tool
- New tab on the Analytics page showing prefix collision data
- Text consistency improvements
### Paths through node accuracy
- Fixed prefix collision bug where packets through a different node with the same 2-char prefix were incorrectly shown
- Now uses `resolved_path` (neighbor affinity graph) for accurate disambiguation
### Table sorting
- Sortable column headers on nodes list, neighbor tables, observer tables, and packets table
- Sort indicators (▲/▼) show active sort column and direction
- Stable sort with timestamp tiebreaker
- Hash Stats "By Repeaters" actually filters by repeater role now
- Zero-hop adverts show "Unknown" hash size instead of wrong "1 byte"
- "Paths through node" uses resolved_path to prevent prefix collisions
- Table sorting works on all tables (nodes, neighbors, observers, packets)
---
## 🔗 Deep Linking
- **Nodes page**: URL updates with node pubkey, tab, and search state
- **Packets page**: URL includes time window and region filter
- **Channels page**: URL reflects selected channel and node
- **Analytics page**: URL includes active tab
*Note: Packet filter expressions and desktop node selection deep links are coming in a follow-up.*
Nodes, packets, channels, analytics tabs reflected in URL hash. Shareable/bookmarkable.
---
## 🎨 UI/UX
## 🎨 UI
### Distance unit preference
- Choose between km, mi, or auto (locale-based) in the Customizer → Display tab
- Small imperial distances show in feet (not "0.0 mi")
- Analytics, node neighbors, and all distance displays respect the setting
### Channel color highlighting
- Assign colors to channels for visual distinction in live feed and packets table
- 8-color palette, left-border encoding
- Color dots on channels page and live feed items for easy access
- Persists in localStorage
### Mobile accessibility
- Touch targets minimum 44×44px
- ARIA labels on interactive elements
- Small viewport support improvements
### Map byte-size filter
- Filter map markers by packet size
### OpenAPI / Swagger
- Auto-generated OpenAPI 3.0 spec at **`/api/spec`** — returns the full API schema as JSON
- Interactive Swagger UI at **`/api/docs`** — browse and test all endpoints from your browser
- Spec is generated from route definitions, always in sync with the running server
- Useful for bot developers, integrators, and anyone building on top of CoreScope
- Example: `curl https://your-instance/api/spec | jq .info`
- **Distance units**: km/mi/auto in Customizer
- **Channel colors**: 8-color palette, color dots on channels + live feed
- **Mobile**: 44px touch targets, ARIA labels
- **Map byte-size filter**
- **OpenAPI**: interactive Swagger UI at `/api/docs`, spec at `/api/spec`
---
## 🔒 Security
### API key enforcement
- Weak/default API keys (e.g., "test", "admin", "password") are rejected at startup
- Write endpoints blocked when no API key is configured
- Startup warning when API key is missing
### License
- Changed to GPL v3
- Weak API keys rejected at startup
- License changed to GPL v3
---
## 🐛 Bug Fixes
## 🐛 14 Bug Fixes
- Fixed `originLat` out-of-scope ReferenceError killing live map animations
- Fixed zero-hop direct adverts showing incorrect hash size
- Fixed live map animations stuck on any advert (block-scoping bug)
- Fixed hash stats including non-repeater nodes
- Fixed paths-through-node showing unrelated packets (prefix collision)
- Fixed channel color picker completely non-functional (data shape mismatch)
- Fixed panel corner toggle buttons invisible/scrolling away
- Fixed table sorting broken on all node tables (attribute mismatch)
- Fixed `time.Tick` leak in prune goroutine
- Fixed View Route on Map button on packet detail page
- Fixed virtual scroll row height measurement
- Fixed collision cache not respecting TTL config
- Fixed prefix map unbounded memory growth (capped at 8 chars)
- Fixed memory eviction using inaccurate memory estimates (now uses runtime heap stats)
originLat scoping crash, zero-hop hash size, live map animation stuck, hash stats including non-repeaters, paths-through-node prefix collision, channel color picker dead code, panel buttons invisible, table sorting broken, time.Tick leak, View Route button, vscroll measurement, collision cache TTL, prefix map unbounded growth, memory eviction accuracy.
---
## 🏗️ Infrastructure
## Upgrading from v3.4.1
- CI pipeline consolidated: build → test → publish to GHCR → deploy staging
- Staging compose: standard ports (80/1883), no memory limit
- CI build time reduced from ~14 min to ~3-4 min (removed arm64 QEMU cross-compilation)
```bash
docker pull ghcr.io/kpa-clawbot/corescope:v3.5.0
docker stop corescope && docker rm corescope
docker run -d --name corescope -p 80:80 -p 1883:1883 \
-v /your/data:/app/data ghcr.io/kpa-clawbot/corescope:v3.5.0
```
---
## 📖 Documentation
- Deployment guide with Docker quick start, compose examples, and configuration reference
- User guide: getting started, page descriptions, config options, FAQ
- OpenAPI 3.0 spec (auto-generated from route definitions)
- Security analysis: AES-128-ECB block-level vulnerability assessment
- Lock ordering documentation for concurrent access patterns
---
## Upgrading
### From v3.4.1
1. Pull the new image: `docker pull ghcr.io/kpa-clawbot/corescope:v3.5.0`
2. Stop and remove old container: `docker stop corescope && docker rm corescope`
3. Start with the new image (keep your data volume):
```bash
docker run -d --name corescope \
-p 80:80 -p 1883:1883 \
-v /your/data:/app/data \
ghcr.io/kpa-clawbot/corescope:v3.5.0
```
**First startup note:** The server will backfill `resolved_path` data for existing observations in the background. The HTTP server is available within ~2 minutes. Full backfill may take longer on large databases but does not block serving.
### Breaking changes
- None. All API endpoints are backward compatible.
- `resolved_path` is added to API responses (new field, `omitempty` — won't break existing clients).
First startup backfills `resolved_path` in the background. Server is responsive within ~2 minutes. No breaking changes.