The highest tagged major version is
Documentation
¶
Overview ¶
Package wire contains the compact, versioned on-the-wire format used by cascache to store values in the underlying Provider. It provides zero-copy decoders and pre-sized encoders for both single entries and bulk entries.
Encoding choices:
- All integers are big-endian (network byte order).
- A 4-byte ASCII magic ("CASC") allows quick format discrimination.
- A 1-byte version enables forward/backward compatibility in place.
- "kind" distinguishes single vs bulk payloads.
- The payload after the fixed header is codec-opaque ([]byte).
- Decoders are written for bounds safety: every slice operation is preceded by length checks; on any mismatch they return ErrCorrupt.
- Decoders return subslices of the original buffer for payloads (zero-copy). NOTE: holding any subslice is sufficient to keep the backing array alive. If you need to retain or mutate the payload beyond the frame’s lifetime, make your own copy.
- Encode paths pre-compute capacity and bytes.Buffer.Grow to avoid realloc.
- Bulk decode allocates exactly one string per item to materialize the key (stable map key semantics).
Strict framing:
- Decoders require that a frame consume the entire buffer (no trailing bytes). This detects corruption/foreign writers early.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrCorrupt is returned when a byte slice doesn't conform to the expected // structure (bad magic/version/kind/lengths). ErrCorrupt = errors.New("corrupt entry") )
Functions ¶
func DecodeSingle ¶
DecodeSingle parses a single entry and returns (gen, payload). The returned payload is a zero-copy subslice of b and must be treated as read-only.
func EncodeBulk ¶
EncodeBulk encodes a bulk set of items in a single value.
Layout (big-endian):
magic(4) | ver(1) | kind(1=bulk) | n(u32) repeated n times: keyLen(u16) | key(keyLen) | gen(u64) | vlen(u32) | payload(vlen)
Returns an error if item count or payload lengths exceed uint32, or if any key length is 0 or > 65535 (u16).
func EncodeSingle ¶
EncodeSingle encodes a single entry.
Layout (big-endian):
magic(4) | ver(1) | kind(1=single) | gen(u64) | vlen(u32) | payload(vlen)
The payload is the codec-encoded value. gen is the per-key generation used for read-side validation (CAS). Payload length is limited to <= 2^32-1 bytes.
Types ¶
type BulkItem ¶
BulkItem holds one member of a bulk-encoded set.
func DecodeBulk ¶
DecodeBulk parses a bulk entry into items. Each item’s Payload is a zero-copy subslice of b and must be treated as read-only.
For each item, Payload is a zero-copy subslice of b. Key is converted to a string (one allocation per item). Duplicate keys in the stored items are allowed; the last occurrence wins.
Source Files