Skip to content

perf(app): reduce uplink, history, and background work - #894

Merged
frahlg merged 3 commits into
masterfrom
agent/box-web-connection-performance
Aug 11, 2026
Merged

perf(app): reduce uplink, history, and background work#894
frahlg merged 3 commits into
masterfrom
agent/box-web-connection-performance

Conversation

@frahlg

@frahlg frahlg commented Aug 11, 2026

Copy link
Copy Markdown
Member

Summary

  • honor the app's 1 Hz visible and 0.2 Hz hidden telemetry request
  • accept an optional subscription in hello while keeping the old hello then sub flow
  • move history reads off the uplink reader, cancel superseded work, bound query ranges, and read all series with one SQLite query per tile
  • stream API replies through one fixed chunk buffer
  • stop hidden status and live-history polling while keeping both paths single-flight
  • bound dashboard status and history reads to 15 seconds so a half-open request cannot block later refreshes

Measured impact

These are protocol counts and an Apple M5 microbenchmark, not Raspberry Pi or production timings.

  • hidden lane-0 traffic falls by 80%, from 1 Hz to 0.2 Hz
  • at 512 bytes plus 24 bytes of Noise transport overhead, that avoids about 35.3 MiB per hidden client per day before WebSocket and TLS overhead
  • the paired client and box save one post-Noise round trip before the first snapshot
  • a four-series history tile uses one SQLite read instead of four
  • the status and live-history pollers schedule no new requests while hidden, avoiding up to 5,400 status GETs and 60 live-history GETs per hour
  • repeated timer ticks do not start more work while a slow status or history request is active
  • the 8 MiB API writer benchmark moved from a 47.6 ms median on d947370c to 2.54 ms here across five runs; allocated bytes fell from about 47.5 MB to 39.1 MB

Benchmark command:

go test -run '^$' -bench '^BenchmarkAPIWriterLargeResponse' -benchmem -count=5 ./internal/appproto

Compatibility and safety

  • all new protocol fields are optional
  • a new app falls back to the old separate sub message when the box does not acknowledge the inline subscription
  • cadence changes keep the session bucket and telemetry sequence
  • unknown additive history series remain in the result as MISSING columns
  • history work has one worker per session, a 15-second deadline, context-aware SQLite reads, and latest-query-wins cancellation
  • dashboard status and history reads also have a 15-second deadline that covers body decoding and releases their single-flight gate on timeout
  • the API writer reports the exact accepted byte count on a partial write error

Checks

  • make verify
  • pre-commit make verify
  • pre-push make verify-all, including Linux arm64, Linux amd64, and Windows amd64 builds
  • go test -race ./internal/appproto ./internal/appuplink ./internal/state
  • npm test: 328/328
  • protocol contract copies match byte for byte
  • shared UI token check passes with no drift
  • independent code review found no remaining P0 or P1 issue; its P2 half-open-read finding is fixed and covered by a deterministic regression test

Proof limits and follow-ups

  • Chrome DevTools tracing was unavailable in this environment, so this PR makes no Core Web Vitals, Raspberry Pi CPU, or live relay latency claim
  • other dashboard modules such as plan and connected chart components keep their existing poll timers; a dashboard-wide visibility owner is separate work
  • the relay still broadcasts encrypted box frames to every app stream; the companion app drops foreign authenticated-encryption failures without exceptions or stack logs
  • directed relay routing needs a separate wire change that does not expose session identity
  • a LAN or WebRTC carrier needs a separate threat model, discovery design, and measured fallback
  • closed history tiles are not cached on the box because restored hardware counters can write into older ledger buckets

Companion web client PR: srcfl/ftw-webapp#42

@frahlg
frahlg marked this pull request as ready for review August 11, 2026 07:06
@frahlg
frahlg merged commit f9297c0 into master Aug 11, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant