snapshot

Documentation

Overview

Package snapshot manages CRC32-verified state snapshots for persistent storage.

Snapshot framing layout (Big-Endian):

• Header:
• Magic: "KDNS" [4 bytes]
• Version: [1 byte] (0x01)
• Total Domains Count: [4 bytes uint32]
• Body:
• Stream of codec-encoded records: [N records]
• Trailer:
• Checksum: [4 bytes uint32 CRC32-IEEE over Header + Body]

Index

• Variables
• func CleanStaleTemp(dir string)
• func CreateTemp(root *os.Root, pattern string) (*os.File, string, error)
• func Load(r io.Reader, onRecord func(domain string, records dns.RRSets)) error
• func ReadChecksum(r io.ReaderAt, size int64) (uint32, error)
• func Save(w io.Writer, tree *radix.Tree) error

Variables

var (
	// ErrInvalidMagic indicates the snapshot header does not match the expected format.
	ErrInvalidMagic = errors.New("snapshot: invalid magic header")

	// ErrUnsupportedVer indicates that the snapshot format version is not supported.
	ErrUnsupportedVer = errors.New("snapshot: unsupported snapshot version")

	// ErrChecksumFailed indicates the CRC32 verification of the snapshot failed.
	ErrChecksumFailed = errors.New("snapshot: checksum verification failed")

	// ErrCorruptedData indicates that the stream data is corrupted and violates binary safety limits.
	ErrCorruptedData = errors.New("snapshot: corrupted stream data violates binary safety limits")

	// ErrCapacityExceeded indicates that an element exceeds binary safety limits.
	ErrCapacityExceeded = errors.New("snapshot: element size or count exceeds binary safety limits")
)

Functions

func CleanStaleTemp

func CleanStaleTemp(dir string)

CleanStaleTemp scans dir and deletes any orphaned temporary snapshot files (matching pattern "state-snap-*.tmp") left behind by previous abnormal process terminations (such as SIGKILL, OOM kills, kernel panics, or sudden power cuts).

In production environments where dir is persistent (e.g. Docker volumes or Kubernetes PersistentVolumes), CleanStaleTemp ensures that aborted temp writes never accumulate or leak disk space over time across daemon restarts.

It uses os.Root to confine removal within dir, preventing symlink-based path traversal.

func CreateTemp

func CreateTemp(root *os.Root, pattern string) (*os.File, string, error)

CreateTemp creates a new temporary file inside root, opens it for reading and writing, and returns the resulting file and its relative name within root. It uses the standard library algorithm from os.CreateTemp, but operates strictly via root.OpenFile with O_CREATE|O_EXCL, guaranteeing 100% filesystem root confinement.

func Load

func Load(r io.Reader, onRecord func(domain string, records dns.RRSets)) error

Load reads a binary compressed snapshot stream, streaming records directly into the onRecord callback, and verifies stream integrity via trailing CRC32 checksum.

func ReadChecksum

func ReadChecksum(r io.ReaderAt, size int64) (uint32, error)

ReadChecksum extracts the 4-byte CRC32-IEEE checksum from the snapshot trailer.

func Save

func Save(w io.Writer, tree *radix.Tree) error

Save serializes the entire radix tree state into a binary compressed stream. It writes domain count and compressed body length in the header using O(1) Tree.Len(), compresses data with flate.BestSpeed, enforces strict memory bounds, and appends a trailing CRC32 checksum.