perf(net): reduce status transport and controller memory overhead

[Patrick W. Healy (phealy)]

Summary

Production status-transport and controller CPU/allocation reductions, based on #743. No simulator or e2e files are included.

Stack: #731 -> #743 (status collection) -> #744 (this PR) -> #745 (health checks).

• Replace full JSON round trips during delta construction with typed protobuf deltas; separate critical changes from routine measurements.
• Implement compact peer-measurement updates end to end: shared schema/helpers, real node sender, controller validation/application, and a bounded-cardinality outcome metric.
• Negotiate compact support per WebSocket connection, allow only one outstanding update, and preserve full resynchronization, legacy JSON/protobuf handling, and noncompact HTTP fallback.
• Decode each controller WebSocket frame once. Reuse bounded size-class frame buffers and up to four idle gzip writers without retaining response contents or per-idle-connection large buffers.
• Reuse validated peer-identity digests and avoid copying every peer while constructing connectivity matrices.
• Preserve fix(net): validate OIDC pod bindings against informer caches #731's node-bound authentication and the reviewed initial-write/fallback behavior.

Validation

• Full normal and race-enabled tests passed for the node, controller, and internal/net/status/....
• Scoped make fmt, make lint (including actionlint), and controller/node builds passed.
• Regenerated protobuf using this base's pinned protoc and protoc-gen-go.
• Tests cover invalid columns/digests/revisions, conflicting identities, full resynchronization, field clearing, legacy fallback, cache/frame ownership, pool bounds, gzip response equivalence, and concurrent use.
• Comparative 2,000-peer sender benchmark: legacy JSON 9,704,104 B/op and 208,940 wire B/op; compact 492,894 B/op and 42,069 wire B/op.
• Comparative controller peer-update benchmark: full peers 2,980,994 B/op and 325,787 wire B/op; compact 878,846 B/op and 32,068 wire B/op.
• Pooled gzip discovery responses decreased from 1,208,898 to 1,792 B/op in the same benchmark run.

These measurements are controlled microbenchmarks, not a whole-cluster performance guarantee. Dense peer caches still grow with topology size, active frames still require memory, and periodic full refreshes remain necessary.

[Copilot]

🟢 Approval recommended

The changes are cohesive, extensively covered by new unit tests/benchmarks, and the updated node/controller implementations and documentation align with the stated transport and memory-reduction goals.

Pull request overview

This PR reduces allocation/CPU overhead in Unbounded net status transport by switching delta construction from JSON round-trips to typed protobuf deltas, adding a compact “peer measurements” delta path, and reusing buffers/writers in the controller WebSocket and gzip response paths.

Changes:

• Introduce typed protobuf NodeStatusDelta fields (timestamps/errors/source/pod info) and compact PeerMeasurements columns guarded by identity digests and revision checks.
• Update the node WebSocket publisher to batch critical vs stats updates, negotiate compact support via ACK, and enforce a single in-flight update per connection.
• Update the controller to decode protobuf frames once, apply compact peer-measurement deltas with bounded-cardinality metrics, reuse WebSocket frame buffers, and pool idle gzip writers; document the new behavior and scaling implications.

File summaries

File	Description
internal/net/status/proto/status.proto	Adds peer_measurements capability to ACK, extends typed deltas, and defines PeerMeasurements compact columns.
internal/net/status/proto/status.pb.go	Regenerates Go protobuf bindings for the updated status schema.
internal/net/status/measurements.go	Adds shared helpers for peer identity digests, metadata comparison, and compact measurements encoding.
internal/net/status/measurements_test.go	Adds unit coverage for digest unambiguity, duplicate detection, and metadata equality behavior.
docs/net/operations.md	Documents connectivity-matrix omission threshold and controller transport pooling behavior.
docs/net/configuration.md	Updates transport semantics/docs: protobuf deltas, critical vs stats behavior, compact negotiation, and sizing guidance.
cmd/unbounded-net-node/status_websocket_auth_test.go	Adjusts WS tests to account for required initial ACK ordering.
cmd/unbounded-net-node/status_server.go	Removes JSON delta computation from production WS path; adds ACK gating, typed delta usage, peer sorting, and ACK timeout handling.
cmd/unbounded-net-node/status_proto.go	Removes JSON-delta-to-proto conversion; standardizes zero-time handling via statusUnixNano.
cmd/unbounded-net-node/status_legacy_delta_test.go	Retains legacy JSON delta helpers for compatibility tests/benchmarks only.
cmd/unbounded-net-node/status_delta.go	Adds typed delta construction, compact measurement selection, canonical peer ordering, and “critical vs stats” snapshot logic.
cmd/unbounded-net-node/status_delta_test.go	Adds extensive tests/benchmarks for typed delta semantics, compact compatibility, field clearing, ordering, and ACK negotiation.
cmd/unbounded-net-node/status_ack.go	Introduces per-connection ACK state (revision/resync/pending/compact) with protobuf+JSON fallback decoding.
cmd/unbounded-net-controller/ws_frame_buffer.go	Implements bounded size-class pooled frame buffers and a single-read frame acquisition path.
cmd/unbounded-net-controller/ws_frame_buffer_test.go	Adds correctness/ownership/allocation tests and benchmarks for pooled frame reads.
cmd/unbounded-net-controller/status_proto.go	Adds typed-delta parsing for new fields, single-decode protobuf WS handling, and measurement/full conflict checks.
cmd/unbounded-net-controller/status_proto_test.go	Updates tests to use the new decode+handle flow and validates identity extraction via decode.
cmd/unbounded-net-controller/server.go	Switches WS reads to pooled frame buffers; decodes protobuf once; pools gzip writers in the gzip handler.
cmd/unbounded-net-controller/proto_ws_identity_test.go	Adds tests ensuring protobuf identity validation happens before registration/cache mutation.
cmd/unbounded-net-controller/peer_measurements.go	Implements controller-side validation/application of compact measurement columns with optional identity memoization.
cmd/unbounded-net-controller/peer_measurements_test.go	Adds tests/benchmarks for compact apply behavior, immutability, rejection semantics, and ACK capability propagation.
cmd/unbounded-net-controller/peer_identity_cache_test.go	Adds tests/benchmarks for identity-digest memoization correctness, invalidation, and concurrency behavior.
cmd/unbounded-net-controller/node_status.go	Extends cache delta application to support compact measurements, typed clears, and a per-entry identity memo.
cmd/unbounded-net-controller/metrics.go	Adds bounded-cardinality metric for compact peer-measurement update outcomes.
cmd/unbounded-net-controller/memory_bench_test.go	Adds benchmarks for protobuf WS decode/apply and connectivity-matrix size gating.
cmd/unbounded-net-controller/matrix_memory_test.go	Adds tests ensuring oversize scopes omit matrices without mutating snapshots or copying peer data.
cmd/unbounded-net-controller/gzip_writer_pool.go	Introduces a small bounded pool for idle gzip writers to reduce per-request allocations.
cmd/unbounded-net-controller/gzip_writer_pool_test.go	Adds behavior equivalence tests, pooling bounds/detachment tests, failure-path tests, and benchmarks for gzip pooling.
cmd/unbounded-net-controller/cni_status_test.go	Updates proto WS handling in CNI guard tests to use the new decode+handle helper.
cmd/unbounded-net-controller/cluster_status.go	Avoids per-node peer-slice copies for connectivity matrices; filters peers at read time and enforces size gating.

Review details

Files not reviewed (1)

• internal/net/status/proto/status.pb.go: Generated file

• Files reviewed: 29/30 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

The protocol, cache concurrency, authentication path, and pooled resource-lifecycle changes warrant final human review despite strong test coverage.

Review details

Files not reviewed (1)

• internal/net/status/proto/status.pb.go: Generated file

• Files reviewed: 29/30 changed files
• Comments generated: 0 new
• Review effort level: Balanced