Documentation
¶
Overview ¶
Package framing provides bounded length-delimited framing for streaming codec values over a byte transport.
WriteFrame and ReadFrame move a single length-prefixed payload; the generic WriteValue / ReadValue helpers combine framing with a codec. A maximum frame size bounds memory, a clean EOF between frames is reported as io.EOF, and truncated prefixes or payloads surface as transport errors distinct from a clean end of stream.
Package framing provides bounded length-delimited framing for streaming structured-text payloads.
A frame is a 4-byte big-endian unsigned length prefix followed by exactly that many payload bytes. Every read is bounded by an explicit maximum so a malformed or hostile peer can never make a reader allocate without limit. Use it to carry one codec-encoded value per frame over any blocking io.Reader/io.Writer transport (a pipe, a socket, a subprocess's stdio).
WriteValue / ReadValue encode and decode typed values through an injected codec; WriteFrame / ReadFrame move raw payload bytes when the caller owns serialization.
Index ¶
- Constants
- func DecodeValue[T any](c codec.Codec, payload []byte) (T, error)
- func ReadFrame(r io.Reader, maxBytes int) ([]byte, error)
- func ReadValue[T any](r io.Reader, c codec.Codec, maxBytes int) (T, error)
- func WriteFrame(w io.Writer, payload []byte, maxBytes int) error
- func WriteValue[T any](w io.Writer, c codec.Codec, value T, maxBytes int) error
Constants ¶
const DefaultMaxFrameBytes = 16 * 1024 * 1024
DefaultMaxFrameBytes is the default maximum accepted payload size for a single frame (16 MiB). It is generous enough for large structured payloads yet bounded so a corrupt length prefix cannot trigger an unbounded allocation.
Variables ¶
This section is empty.
Functions ¶
func DecodeValue ¶
DecodeValue decodes an already-read frame payload into T through codec.
It is split from ReadValue so a caller that must inspect one frame as more than one shape can decode the same bytes without re-reading the stream. It returns a typed error (cause preserved) if payload is not valid UTF-8 or does not decode into T.
func ReadFrame ¶
ReadFrame reads one length-delimited frame, bounded by maxBytes.
It returns io.EOF (with a nil payload) on a clean end-of-stream observed before any length byte — the peer closed the connection between frames. A partial prefix or payload is a hard transport error, and a length above maxBytes is rejected before any allocation.
func ReadValue ¶
ReadValue reads one frame and decodes it into T through codec.
It returns io.EOF on a clean end-of-stream between frames, or a typed error (cause preserved) on a transport failure or a payload that does not decode into T.
func WriteFrame ¶
WriteFrame writes one length-delimited frame carrying payload. A plain io.Writer suffices; flushing any buffered transport is the caller's concern.
It returns a typed error if payload exceeds maxBytes or the underlying writer fails (cause preserved).
Types ¶
This section is empty.
Source Files