wal

Documentation

Overview

Package wal provides Write-Ahead Log appending and replay mechanisms for crash safety.

Every mutating transaction (Upsert or Delete) is atomically appended as an in-band CRC32-verified frame:

Upsert Frame Layout:

• Opcode: [1 byte] (0x01 = OpUpsert)
• Codec Payload: [Domain + RRSets binary frame]
• Checksum: [4 bytes uint32 CRC32-IEEE over Opcode + Codec Payload]

Delete Frame Layout:

• Opcode: [1 byte] (0x02 = OpDelete)
• Domain Length: [2 bytes uint16]
• Domain Name: [ASCII/UTF-8 bytes]
• Checksum: [4 bytes uint32 CRC32-IEEE over Opcode + Length + Domain Name]

Strict boundary validations are enforced to prevent corrupted stream replay and torn writes.

Index

• Constants
• Variables
• func Replay(r io.Reader, onUpsert func(string, dns.RRSets), onDelete func(string)) error
• type Writer
  • func NewWriter(file *os.File) *Writer
  • func (w *Writer) AppendDelete(domain string) error
  • func (w *Writer) AppendUpsert(domain string, records dns.RRSets) error
  • func (w *Writer) Flush() error

Constants

const (
	// OpUpsert identifies an insert or update transaction frame in the log.
	OpUpsert = byte(0x01)

	// OpDelete identifies a removal transaction frame in the log.
	OpDelete = byte(0x02)
)

Variables

var (
	// ErrCorruptedData indicates that stream bytes violate binary safety limits or checksum verification.
	ErrCorruptedData = errors.New("wal: corrupted stream data violates binary safety limits")

	// ErrCapacityExceeded indicates that a domain name or record count exceeds RFC 1035 safety bounds.
	ErrCapacityExceeded = errors.New("wal: element size or count exceeds binary safety limits")

	// ErrInvalidOpcode indicates that an unrecognized transaction operation byte was encountered.
	ErrInvalidOpcode = errors.New("wal: unknown operation code")

	// ErrTruncated indicates that the WAL file ends with an incomplete or truncated frame.
	ErrTruncated = errors.New("wal: truncated tail frame")
)

Functions

func Replay

func Replay(r io.Reader, onUpsert func(string, dns.RRSets), onDelete func(string)) error

Replay reads the WAL stream sequentially and executes the callbacks. It returns nil only on a clean EOF at frame boundaries. Any truncated frame or checksum mismatch is explicitly wrapped and returned.

Types

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer manages appending serialized mutation operations to the write-ahead log.

func NewWriter

func NewWriter(file *os.File) *Writer

NewWriter creates a new WAL writer wrapping the provided file.

func (*Writer) AppendDelete

func (w *Writer) AppendDelete(domain string) error

AppendDelete serializes and appends a delete operation frame to the log in a single atomic buffer write.

func (*Writer) AppendUpsert

func (w *Writer) AppendUpsert(domain string, records dns.RRSets) error

AppendUpsert serializes and appends an upsert operation frame to the log.

func (*Writer) Flush

func (w *Writer) Flush() error

Flush flushes buffered journal frames and forces a physical fsync to disk.