feat(transport): negotiate bounded automatic message chunking
This commit is contained in:
1 parent
474afb3484
commit
8acffac985
20 files changed
+1332
-38
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user