Documentation
¶
Overview ¶
Package codec is the single source of layout truth for fixed-size wire types: a generic, bounds-checked Encode/Decode pair (raw memcpy of the struct, little-endian host layout) and a Cursor writer for variable-size encoders.
Wire type contract ¶
The memcpy format is only sound for POD structs with a frozen layout. Every type passed to Encode/Decode/Put must therefore:
- Contain no pointer, slice, map, string, chan, func, or interface field at any nesting depth (enforced by TestWireTypesArePOD).
- Keep its size and every field offset equal to the golden constants in guard_test.go. Any layout change fails CI until the constants are bumped deliberately (enforced by TestWireTypeLayoutGolden).
Style rule for wire structs ¶
Declare layout, don't inherit it: order fields largest-first (8-byte fields, then 4-byte, then smaller) and spell out any padding explicitly as `_ [N]byte` so the byte image is what the source says, not what the compiler chose. New wire types must be added to the registry in guard_test.go before they are published on the bus.
Index ¶
- Variables
- func AppendJSONBool(dst []byte, v bool) []byte
- func AppendJSONFloat(dst []byte, f float64) []byte
- func AppendJSONInt(dst []byte, n int64) []byte
- func AppendJSONString(dst []byte, s string) []byte
- func AppendJSONUint(dst []byte, n uint64) []byte
- func Decode[T any](buf []byte) (T, error)
- func Encode[T any](buf []byte, v *T) error
- func Put[T any](c *Cursor, v *T)
- func Size[T any]() int
- type Cursor
Constants ¶
This section is empty.
Variables ¶
var ErrBufferTooSmall = errors.New("buffer too small")
ErrBufferTooSmall is returned when the provided buffer cannot hold (Encode) or provide (Decode) the full wire representation of the value. The message deliberately carries no package prefix: it predates this package (event/command re-export the same value) and is pinned by the msglog JSONL golden in core/msgbus.
Functions ¶
func AppendJSONBool ¶
AppendJSONBool appends true or false.
func AppendJSONFloat ¶
AppendJSONFloat appends a float64 in shortest round-trip decimal form.
func AppendJSONInt ¶
AppendJSONInt appends a signed integer in decimal.
func AppendJSONString ¶
AppendJSONString appends a JSON-encoded string (including quotes) to dst. Alloc-free when dst has enough capacity.
func AppendJSONUint ¶
AppendJSONUint appends an unsigned integer in decimal.
func Decode ¶
Decode copies buf into a new local value of T (bounds-checked memcpy). The returned value does not alias buf, so it stays valid after the buffer is released, and the copy works from unaligned source offsets.
func Encode ¶
Encode writes the raw memory of *v into buf (bounds-checked memcpy). T must be a registered POD wire type (see guard_test.go): no pointers, slices, maps, strings, chans, funcs, or interfaces anywhere in the struct.
Types ¶
type Cursor ¶
type Cursor struct {
// contains filtered or unexported fields
}
Cursor is a bounds-checked sequential writer over a byte slice with a sticky error, replacing hand-maintained `pos += 8` offset arithmetic in variable-size encoders. All integer writes are little-endian (the wire byte order). After the last write, check Err() once.
func (*Cursor) Err ¶
Err returns the sticky error (nil, or ErrBufferTooSmall once any write did not fit). Writes after a failure are no-ops.
Source Files