Documentation
¶
Overview ¶
Package encoding provides canonical, bounded binary frames for CRDT state.
Index ¶
- Constants
- Variables
- func AppendTag(dst []byte, tag crdt.Tag) []byte
- func AppendUvarint(dst []byte, value uint64) []byte
- func ConvertFrameV1ToV2(data []byte, limits Limits) ([]byte, error)
- func ConvertFrameV2ToV1(data []byte, limits Limits) ([]byte, error)
- func MarshalFrame(frame Frame) ([]byte, error)
- func MarshalFrameV2(frame Frame) ([]byte, error)
- func MarshalFrameV2WithLimits(frame Frame, limits Limits) ([]byte, error)
- func MarshalFrameV2WithPayload(typeID uint64, codecID string, payloadLength int, writePayload PayloadWriter) ([]byte, error)
- func MarshalFrameV2WithPayloadAndLimits(typeID uint64, codecID string, payloadLength int, limits Limits, ...) ([]byte, error)
- func MarshalFrameWithPayload(typeID uint64, codecID string, payloadLength int, writePayload PayloadWriter) ([]byte, error)
- func MarshalFrameWithPayloadAndLimits(typeID uint64, codecID string, payloadLength int, limits Limits, ...) ([]byte, error)
- func ReadBytes(data []byte, position, max int) ([]byte, int, bool)
- func ReadTag(data []byte, position, maxStringBytes int) (crdt.Tag, int, bool)
- func ReadUvarint(data []byte, position int) (uint64, int, bool)
- func TagSize(tag crdt.Tag) int
- func UvarintSize(value uint64) int
- type DecoderLimits
- type Frame
- type Limits
- type PayloadWriter
Constants ¶
const FormatVersion uint64 = 1
FormatVersion identifies the original canonical frame layout. It remains the default for existing MarshalFrame callers and is immutable on the wire.
const FormatVersionV2 uint64 = 2
FormatVersionV2 identifies the compression-aware frame layout. It preserves a frame's TypeID, CodecID, and decoded payload, but records an explicit payload encoding so peers can negotiate the transport representation without changing CRDT semantics.
Variables ¶
var ( ErrInvalidFrame = errors.New("encoding: invalid frame") ErrFrameLimit = errors.New("encoding: frame limit exceeded") )
Functions ¶
func AppendUvarint ¶
AppendUvarint appends the unique shortest representation of value.
func ConvertFrameV1ToV2 ¶ added in v1.0.24
ConvertFrameV1ToV2 converts one validated v1 frame without changing its CRDT payload. It is useful for stores or providers that retain a v1 producer API while negotiating v2 at their transport boundary.
func ConvertFrameV2ToV1 ¶ added in v1.0.24
ConvertFrameV2ToV1 converts one validated v2 frame without changing its CRDT payload. It provides an explicit downgrade path for a separately negotiated legacy peer; it never happens implicitly during decoding.
func MarshalFrame ¶
MarshalFrame returns the canonical v1 encoding of frame.
func MarshalFrameV2 ¶ added in v1.0.24
MarshalFrameV2 returns a compression-aware v2 frame. The encoder chooses raw payload bytes for small or incompressible inputs and DEFLATE only when it makes the complete v2 envelope smaller. V2 changes representation, not CRDT semantics: TypeID, CodecID, and the decoded payload are unchanged.
func MarshalFrameV2WithLimits ¶ added in v1.0.24
MarshalFrameV2WithLimits returns a bounded v2 frame. Callers must negotiate FormatVersionV2 before sending it: older peers correctly reject this format.
func MarshalFrameV2WithPayload ¶ added in v1.0.29
func MarshalFrameV2WithPayload(typeID uint64, codecID string, payloadLength int, writePayload PayloadWriter) ([]byte, error)
MarshalFrameV2WithPayload writes a bounded v2 payload directly into its final raw envelope when compression is not considered. For larger payloads, it uses a bounded temporary buffer so it can choose the smaller raw or DEFLATE representation. The writer has the same lifetime contract as PayloadWriter: it must fill only the supplied payload and must not retain it.
func MarshalFrameV2WithPayloadAndLimits ¶ added in v1.0.29
func MarshalFrameV2WithPayloadAndLimits(typeID uint64, codecID string, payloadLength int, limits Limits, writePayload PayloadWriter) ([]byte, error)
MarshalFrameV2WithPayloadAndLimits is MarshalFrameV2WithPayload with explicit output limits. For raw interactive payloads it validates the final v2 frame budget before invoking writePayload, avoiding a temporary payload allocation and copy. A payload at or above the compression threshold keeps a bounded temporary buffer because mode selection depends on its bytes.
func MarshalFrameWithPayload ¶
func MarshalFrameWithPayload(typeID uint64, codecID string, payloadLength int, writePayload PayloadWriter) ([]byte, error)
MarshalFrameWithPayload returns the canonical v1 frame for a payload written directly into its final output buffer. When writePayload follows the PayloadWriter buffer-lifetime contract, this function owns the envelope and computes a checksum matching the completed payload.
func MarshalFrameWithPayloadAndLimits ¶ added in v1.0.23
func MarshalFrameWithPayloadAndLimits(typeID uint64, codecID string, payloadLength int, limits Limits, writePayload PayloadWriter) ([]byte, error)
MarshalFrameWithPayloadAndLimits returns the canonical v1 frame for a payload written directly into its final output buffer while enforcing every supplied output limit. This lets protocol encoders preflight a local change against the exact frame budget their peer will enforce before mutating local CRDT state.
func ReadBytes ¶
ReadBytes reads a length-prefixed byte sequence without allocating. max is an explicit bound for the sequence and must be non-negative.
func ReadTag ¶
ReadTag decodes one bounded canonical tag without retaining data's backing storage. The caller owns the returned tag value.
func ReadUvarint ¶
ReadUvarint reads one shortest-form unsigned varint at position. It rejects truncated, overflowing, and non-canonical encodings.
func UvarintSize ¶
UvarintSize returns the size of value's canonical unsigned-varint encoding.
Types ¶
type DecoderLimits ¶
type DecoderLimits struct {
MaxFrameBytes int
MaxPayload int
MaxCodecID int
MaxElements int
MaxTags int
MaxStringBytes int
}
DecoderLimits bounds decoder allocation and input work. All limits must be positive. MaxElements and MaxTags apply to a single decoded payload.
func DefaultLimits ¶
func DefaultLimits() DecoderLimits
DefaultLimits returns conservative bounds for in-memory library use. It returns a value rather than exposing mutable process-wide configuration.
type Frame ¶
type Frame struct {
TypeID uint64
CodecID string
Payload []byte
// contains filtered or unexported fields
}
Frame is the versioned outer envelope of a CRDT state or delta payload.
func UnmarshalFrame ¶
UnmarshalFrame validates and decodes one complete canonical v1 frame. Its returned payload is independent of data and remains safe to retain.
func UnmarshalFrameView ¶ added in v1.0.23
UnmarshalFrameView validates and decodes one complete canonical v1 frame without copying the payload. The returned Payload aliases data, so callers must not retain it or modify data while the view is in use. Use UnmarshalFrame when a caller-owned payload is required.
This is intended for bounded decoders that validate and copy only the fields they retain. Validation, including the checksum, completes before the view is returned. A v2 DEFLATE payload is reconstructed during validation and is therefore owned by the returned Frame rather than aliased to data.
type PayloadWriter ¶
PayloadWriter writes exactly one framed payload into the supplied buffer. The buffer has the requested payload length and is only valid for the duration of the call. Writers must not retain or modify it after returning.
Source Files