// Package agentwire carries bounded logical Agent messages over WebSocket. // It does not assign command IDs, event sequences, or durable acknowledgements. package agentwire import ( "encoding/binary" "errors" "math" ) const ( Subprotocol = "rvbox.agent.v1.chunked" PacketBytes = 16 << 10 headerBytes = 9 complete = byte(0) data = byte(1) control = byte(2) ) var ( ErrPacket = errors.New("invalid agent transport packet") ErrMessageTooBig = errors.New("agent transport message exceeds logical limit") ) // Encoder retains one immutable logical message and allocates one wire packet // at a time. Two fragment lanes reuse the server's control/data distinction; // no fragment IDs are needed on an ordered, connection-scoped stream. type Encoder struct { payload []byte offset int kind byte chunked bool } func NewEncoder(payload []byte, maximum uint64, chunked, priority bool) (*Encoder, error) { if len(payload) == 0 { return nil, ErrPacket } if uint64(len(payload)) > maximum || uint64(len(payload)) > math.MaxUint32 { return nil, ErrMessageTooBig } kind := data if priority { kind = control } return &Encoder{payload: payload, chunked: chunked, kind: kind}, nil } // Next returns a packet and whether it finishes this logical message. func (encoder *Encoder) Next() ([]byte, bool) { if encoder.offset == len(encoder.payload) { return nil, true } if !encoder.chunked { encoder.offset = len(encoder.payload) return encoder.payload, true } if len(encoder.payload) < PacketBytes { packet := make([]byte, len(encoder.payload)+1) copy(packet[1:], encoder.payload) encoder.offset = len(encoder.payload) return packet, true } end := min(len(encoder.payload), encoder.offset+PacketBytes-headerBytes) packet := make([]byte, headerBytes+end-encoder.offset) packet[0] = encoder.kind binary.BigEndian.PutUint32(packet[1:5], uint32(len(encoder.payload))) binary.BigEndian.PutUint32(packet[5:9], uint32(encoder.offset)) copy(packet[headerBytes:], encoder.payload[encoder.offset:end]) encoder.offset = end return packet, end == len(encoder.payload) } type partial struct { total uint32 bytes []byte } // Decoder is owned by one network reader. At most one incomplete message per // lane is retained, each bounded by Maximum before allocation. Complete small // messages can bypass either partial lane. Errors are connection-fatal. type Decoder struct { Maximum uint64 lanes [2]partial } func (decoder *Decoder) Push(packet []byte) ([]byte, error) { if len(packet) == 0 || len(packet) > PacketBytes { return nil, ErrPacket } if packet[0] == complete { if len(packet) == 1 { return nil, ErrPacket } if uint64(len(packet)-1) > decoder.Maximum { return nil, ErrMessageTooBig } return packet[1:], nil } if (packet[0] != data && packet[0] != control) || len(packet) <= headerBytes { return nil, ErrPacket } total := binary.BigEndian.Uint32(packet[1:5]) offset := binary.BigEndian.Uint32(packet[5:9]) if uint64(total) > decoder.Maximum { return nil, ErrMessageTooBig } length := uint32(len(packet) - headerBytes) if total < PacketBytes || offset > total || length > total-offset { return nil, ErrPacket } lane := &decoder.lanes[packet[0]-1] if lane.bytes == nil { if offset != 0 { return nil, ErrPacket } lane.total = total lane.bytes = make([]byte, 0, int(total)) } if lane.total != total || uint64(offset) != uint64(len(lane.bytes)) { return nil, ErrPacket } lane.bytes = append(lane.bytes, packet[headerBytes:]...) if uint32(len(lane.bytes)) != total { return nil, nil } result := lane.bytes *lane = partial{} return result, nil }