feat(transport): negotiate bounded automatic message chunking

This commit is contained in:
cabbage committed 2026-11-09 08:50:51 +00:00
1 parent 474afb3484
commit 8acffac985
20 files changed
+1332 -38

No files matched your search

+111
View File
@@ -0,0 +1,111 @@
# Automatic Agent transport chunking
## Status and scope
**Offline only.** The user explicitly held deployment on 2026-11-09. Development,
isolated tests, and ordinary source commits are authorized; live service updates
and replacement of published installers for this feature are not.
The shared `internal/agentwire` package splits a logical protobuf message into
bounded packets and assembles it before the existing Agent handler sees it.
Scripts, output, large inline commands, stdin, and reconciliation all use the
same transport path. Business-level script/output chunks remain unchanged.
This handles messages larger than a wire packet, not requests exceeding the
configured logical limits. The normal 1 MiB envelope, 768 KiB execution spec,
64 KiB raw chunk and 10 MiB script limits, existing quotas, and Control API
admission rules still apply. A request beyond its logical limit is rejected;
fragmentation does not raise limits or make unbounded snapshots valid.
## Negotiation and compatibility
Both WebSocket endpoints advertise `rvbox.agent.v1.chunked` using the standard
`Sec-WebSocket-Protocol` handshake. Framing is enabled only if that exact
subprotocol is selected. Otherwise the existing one-binary-message-per-envelope
format remains in use. No client-version guessing, protobuf capability fields,
database migration, or operator configuration knob is required.
New client/old server and old client/new server retain the raw format. Old
clients do not gain a reassembler from a server upgrade; their existing 32 KiB
reader can still reject large inline commands, stdin, or reconciliation. The
server's existing 16 KiB script chunks continue to support pending uploads to
those clients. Proxy configurations must preserve the negotiated subprotocol
header in both directions.
## Packet format
Each negotiated packet is one binary WebSocket message of at most 16,384 bytes.
The WebSocket library enforces that aggregate message bound even when a peer
fragments it into native WebSocket continuation frames. Compression remains
disabled at the WebSocket layer.
| First byte | Remaining bytes | Meaning |
| --- | --- | --- |
| `0` | Serialized logical message | Complete message; payload is 1–16,383 bytes. |
| `1` | uint32 total length, uint32 offset, data | Fragment of a data-lane message. |
| `2` | uint32 total length, uint32 offset, data | Fragment of a control-lane message. |
Integers use big-endian order. Fragment headers occupy nine bytes including the
kind; data is nonempty and at most 16,375 bytes. Fragmented messages have total
length at least 16,384 bytes. The declared length is checked against the local
logical envelope ceiling before allocation. Offset starts at zero and must
equal the assembled prefix length; total length must stay constant. Gaps,
overlaps, duplicate prefixes, changed totals, unknown kinds, empty packets,
overflowing ranges, and oversized messages are fatal framing errors. There is
no recursive interpretation of an assembled payload as another transport packet.
The final fragment is identified by offset plus data length equalling total
length. The next logical message starts again at offset zero. Ordered WebSocket
delivery and one in-flight message per lane remove the need for fragment UUIDs,
extra event sequences, final flags, or transport acknowledgements. Existing
payload/request hashes remain validated after assembly; no additional transport
checksum or durable fragment ledger is introduced.
## Ordering, liveness, and bounds
One connection-scoped decoder owns two bounded partial buffers, one per lane.
Complete small messages can overtake either partial message. A large control
message can complete while a data message is paused. The server's sole writer
keeps lane order, checks heartbeat state between packets, and drains a bounded
control burst between data packets so data also progresses. Write deadlines
apply to each packet; a slow complete logical message can take longer than one
packet deadline while continuing to make progress.
Parent operation deadlines still apply.
`Written` and `OnWritten` remain whole-message barriers. A partially transmitted
dispatch cannot release dependent stdin or signals, and a partial reconciliation
result cannot enable new work. The decoder delivers no partial envelope to
protobuf validation, storage, execution, or acknowledgement handlers.
One read pump per connection handles control frames even when the application
is sending a large message. It has one complete-message delivery slot. Partial
buffers are individually limited by the logical ceiling; the queued/in-flight
complete messages are also bounded. Valid packet traffic updates server
liveness before assembly finishes. Socket close cancels the pump, including a
blocked delivery. There is no goroutine, queue, or persistence record per packet.
Client concurrent logical writes are serialized. The server uses its existing
single writer, with bounded control preemption and separate fragment lanes.
On disconnect, partial buffers are discarded with the connection. A new
connection cannot finish an old tail. Existing durable commands/events/stdin
and reconciliation supply replay; IDs, event digests, sequences, newline
behavior, and idempotency are unchanged.
## Offline verification
Run `scripts/build verify` in the established Docker toolchain. Focused checks:
```sh
docker compose -f deploy/compose.yaml run --rm toolchain \
go test -race ./internal/agentwire ./internal/client/agent \
./internal/server/session ./test/integration/clientagent
```
The tests cover exact packet/logical boundaries, malformed declarations and
ordering, bounded allocation, two-lane preemption, whole-message write barriers,
heartbeat/Pong progress, concurrent writes, partial-disconnect replay, TLS,
old/new fallback in both directions, large output/dispatch/reconciliation, and
large stdin preserving one write sequence/newline/idempotency result. Fuzz
seeds exercise the decoder during normal tests; run a longer fuzz campaign in
the same isolated toolchain when needed. None of these commands deploys the
feature or contacts the live workstation.