README
¶
zapcodec
ZAP-native little-endian reflection codec for the Lux platform.
See LLM.md for the full module spec, wire format, and history.
import (
"github.com/luxfi/zapcodec"
"github.com/luxfi/utils/wrappers"
)
c := zapcodec.NewDefault()
_ = c.RegisterType(&MyConcrete{})
p := &wrappers.Packer{MaxSize: 1 << 20}
_ = c.MarshalInto(value, p)
For the canonical version-prefix outer layer used by the SDK wallet,
see github.com/luxfi/proto/zap_codec.NewVersionedManager.
Extracted from github.com/luxfi/codec/zapcodec in Wave 2G-Archive.
Documentation
¶
Overview ¶
Package zapcodec is the ZAP-native little-endian reflection codec.
Module history: this package originated inside github.com/luxfi/codec as codec/zapcodec, a drop-in replacement for codec/linearcodec that emits little-endian bytes. After the Wave 2G codec rip moved every production caller off github.com/luxfi/codec, zapcodec was extracted into its own top-level module so consumers (proto/zap_codec, the canonical wallet codec construction site) can depend on it without pulling in the archived codec module.
Wire-format delta vs the historical linearcodec:
- All multi-byte integers are little-endian. x86_64 and arm64 hardware is LE-native; LE writes map to single MOV instructions where BE writes need BSWAP.
- Interface type-id prefixes are uint32 LE (linearcodec used uint32 BE).
- String length prefix is uint16 LE (linearcodec used uint16 BE).
- Slice/map length prefixes are uint32 (same width as linearcodec, LE byte order).
- Bool is a single byte, struct fields are emitted in serialize-tag order — same as linearcodec.
Self-contained design (Hickey decomplection):
- VALUE: the wire codec choice. Today: little-endian reflection codec. The value lives here, in its own module, qualified by namespace.
- COMPOSITION: the public Codec interface (MarshalInto / UnmarshalFrom / Size) is satisfied by *codecImpl. Callers compose this with their own version-prefix outer layer (see proto/zap_codec.Manager for the canonical wiring).
- ORTHOGONAL: this package has no knowledge of any specific wire payload type (PVM/XVM/warp/...) — it's a generic reflection- driven (un)marshaller. Per-type registration happens at the caller via Codec.RegisterType.
Dependencies: the only external dependency is luxfi/utils/wrappers for the Packer type that crosses module boundaries on MarshalInto/UnmarshalFrom. The reflection-driven encoder body uses a local little-endian packer (zapcodec/packer.go) that aliases the wrappers.Packer's underlying buffer — no per-Marshal copy.
Index ¶
Constants ¶
const DefaultTagName = "serialize"
DefaultTagName is the struct tag this codec honours. Same value as the legacy luxfi/codec linearcodec used ("serialize") — the post- extraction wire format is byte-identical to what consumers expect.
Variables ¶
var ( ErrUnsupportedType = errors.New("zapcodec: unsupported type") ErrMaxSliceLenExceeded = errors.New("zapcodec: max slice length exceeded") ErrDoesNotImplementInterface = errors.New("zapcodec: does not implement interface") ErrUnexportedField = errors.New("zapcodec: unexported field") ErrMarshalZeroLength = errors.New("zapcodec: can't marshal zero length value") ErrUnmarshalZeroLength = errors.New("zapcodec: can't unmarshal zero length value") ErrMarshalNil = errors.New("zapcodec: can't marshal nil pointer") ErrUnmarshalNil = errors.New("zapcodec: can't unmarshal into nil") ErrDuplicateType = errors.New("zapcodec: duplicate type registration") )
Sentinel errors — same surface as the historical luxfi/codec sentinels so consumers asserting via errors.Is on the post-rename values get equivalent behaviour after the module move.
var ( // ErrInsufficientLength indicates the packer ran out of room (either // growing past MaxSize on write, or reading past the buffer on read). ErrInsufficientLength = errors.New("zapcodec: packer has insufficient length") )
Functions ¶
This section is empty.
Types ¶
type Codec ¶
type Codec interface {
// RegisterType assigns val the next sequential type-id so it can be
// (un)marshalled into an interface field at the same codec
// instance.
RegisterType(val interface{}) error
// SkipRegistrations bumps the next-type-id counter by n. Lets
// callers preserve historical type-id slot layouts during a
// migration window.
SkipRegistrations(n int)
// MarshalInto serialises value into p. value MAY be a pointer-to-
// interface (in which case the interface type-id prefix is written
// before the underlying value).
MarshalInto(value interface{}, p *wrappers.Packer) error
// UnmarshalFrom deserialises p into dest. dest MUST be a pointer.
UnmarshalFrom(p *wrappers.Packer, dest interface{}) error
// Size returns the on-wire size of value before any outer
// version-prefix layer the manager applies.
Size(value interface{}) (int, error)
}
Codec is the zapcodec public surface — the reflection-driven (un)marshaller plus a sequential-type-id registry.
Implementations are concurrency-safe: RegisterType / SkipRegistrations take an internal write lock; Marshal/Unmarshal/Size take a read lock only when inspecting the registry.
func New ¶
New returns a fresh zapcodec instance that honours the supplied struct-tag names. Concurrency-safe.
func NewDefault ¶
func NewDefault() Codec
NewDefault returns a zapcodec instance honouring the "serialize" struct tag — the canonical configuration.
type GeneralCodec ¶
GeneralCodec is the union of Codec and Registry — provided for structural symmetry with the historical luxfi/codec.GeneralCodec.
Source Files