snapshot

Documentation

Overview

Package snapshot provides point-in-time snapshot and restore functionality.

Snapshots capture the complete state of all markets including order books, sequence numbers, and configuration. They include CRC32 checksums for integrity validation and use atomic file writes to prevent corruption.

Key features:

• Complete market state capture
• CRC32 checksum validation
• Atomic file writes (temp + rename)
• JSON format for readability
• Corruption detection on read
• Per-market isolation

File format:

• Header with metadata and schema version
• Per-market segments with checksums
• Footer with market index
• JSON encoding for debugging

Example usage:

// Take snapshot
snapshots, seqID := engine.TakeSnapshot()
writer := snapshot.NewWriter("./snapshots")
err := writer.WriteSnapshot(snapshots, seqID)

// Restore from snapshot
reader := snapshot.NewReader("./snapshots")
metadata, snapshots, err := reader.ReadSnapshot()
if err != nil {
    // Handle corruption
}
engine.RestoreFromSnapshot(snapshots)

Snapshots should be taken periodically (e.g., every 1000 commands) to enable fast recovery without replaying entire event log.

Index

• Constants
• type MarketSegment
• type OrderBookSnapshot
• type Reader
  • func NewReader(snapshotDir string) *Reader
  • func (r *Reader) ReadSnapshot() (*SnapshotMetadata, []*OrderBookSnapshot, error)
• type SnapshotFileFooter
• type SnapshotMetadata
• type Writer
  • func NewWriter(targetDir string) *Writer
  • func (w *Writer) WriteSnapshot(snapshots []*OrderBookSnapshot, globalSeqID uint64) error

Constants

const (
	SchemaVersion   = 1
	EngineVersion   = "v0.8.0"
	TempDirPrefix   = "snapshot-tmp-"
	SnapshotBinFile = "snapshot.bin"
	MetadataFile    = "metadata.json"
)

Types

type MarketSegment

type MarketSegment struct {
	MarketID string `json:"market_id"`
	Offset   int64  `json:"offset"`   // Start offset in file
	Length   int64  `json:"length"`   // Length in bytes
	Checksum uint32 `json:"checksum"` // CRC32 of segment
}

MarketSegment contains metadata for a market's data in snapshot.bin

type OrderBookSnapshot

type OrderBookSnapshot struct {
	MarketID     string                  `json:"market_id"`
	SeqID        uint64                  `json:"seq_id"`          // Current sequence ID
	LastCmdSeqID uint64                  `json:"last_cmd_seq_id"` // Last processed command sequence
	TradeID      uint64                  `json:"trade_id"`        // Current trade sequence
	Bids         []*order.Order          `json:"bids"`            // Ordered list of bids
	Asks         []*order.Order          `json:"asks"`            // Ordered list of asks
	State        protocol.OrderBookState `json:"state"`           // Market state
	MinLotSize   decimal.Decimal         `json:"min_lot_size"`    // Min trade unit
}

OrderBookSnapshot contains the full state of a single OrderBook

type Reader

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

Reader handles snapshot reading

func NewReader

func NewReader(snapshotDir string) *Reader

NewReader creates a new snapshot reader

func (*Reader) ReadSnapshot

func (r *Reader) ReadSnapshot() (*SnapshotMetadata, []*OrderBookSnapshot, error)

ReadSnapshot reads and validates a complete snapshot

type SnapshotFileFooter

type SnapshotFileFooter struct {
	Markets []MarketSegment `json:"markets"` // Index of market segments
}

SnapshotFileFooter is stored at the end of snapshot.bin

type SnapshotMetadata

type SnapshotMetadata struct {
	SchemaVersion      int    `json:"schema_version"`         // Version for backward compatibility
	Timestamp          int64  `json:"timestamp"`              // Unix nano
	GlobalLastCmdSeqID uint64 `json:"global_last_cmd_seq_id"` // Global max sequence
	EngineVersion      string `json:"engine_version"`         // Engine version
	SnapshotChecksum   uint32 `json:"snapshot_checksum"`      // CRC32 of snapshot.bin
}

SnapshotMetadata holds the global metadata for a snapshot

type Writer

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

Writer handles snapshot writing

func NewWriter

func NewWriter(targetDir string) *Writer

NewWriter creates a new snapshot writer

func (*Writer) WriteSnapshot

func (w *Writer) WriteSnapshot(snapshots []*OrderBookSnapshot, globalSeqID uint64) error

WriteSnapshot writes a complete snapshot atomically