112 lines
6.0 KiB
Markdown
112 lines
6.0 KiB
Markdown
# 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.
|