Struct EntryMetadata 

#[repr(C)]
pub struct EntryMetadata {
    pub key_hash: u64,
    pub prev_offset: u64,
    pub checksum: [u8; 4],
}

Metadata structure for an append-only storage entry.

This structure stores metadata associated with each entry in the append-only storage. It includes a hash of the key for quick lookups, an offset pointing to the previous entry in the chain, and a checksum for integrity verification.

Entry Storage Layout

Aligned entry (non-tombstone):

Offset Range	Field	Size (Bytes)	Description
P .. P+pad	Pre-Pad (optional)	pad	Zero bytes to align payload start
P+pad .. N	Payload	N-(P+pad)	Variable-length data
N .. N+8	Key Hash	8	64-bit XXH3 key hash
N+8 .. N+16	Prev Offset	8	Absolute offset of previous tail
N+16 .. N+20	Checksum	4	CRC32C of payload

Where:

• pad = (A - (prev_tail % A)) & (A - 1), A = PAYLOAD_ALIGNMENT.
• The next entry starts at N + 20.

Tombstone (deletion marker):

Offset Range	Field	Size (Bytes)	Description
T .. T+1	Payload	1	Single byte 0x00
T+1 .. T+21	Metadata	20	Key hash, prev, crc32c

Notes:

• Using the previous tail in Prev Offset lets us insert pre-pad while keeping chain traversal unambiguous.
• Readers compute payload_start = prev_offset + prepad_len(prev_offset) and use the current metadata position as payload_end.

Notes

• The prev_offset forms a backward-linked chain for each key.
• The checksum is not cryptographically secure but serves as a quick integrity check.
• The first entry for a key has prev_offset = 0, indicating no previous version.

Fields

key_hash: u64

prev_offset: u64

checksum: [u8; 4]

Implementations

impl EntryMetadata

pub fn new(key_hash: u64, prev_offset: u64, checksum: [u8; 4]) -> EntryMetadata

pub fn serialize(&self) -> [u8; 20]

Serializes the metadata into a byte array.

Converts the EntryMetadata structure into a fixed-size array for efficient storage. The serialized format ensures compatibility with disk storage and memory-mapped access.

Format:

• Encodes the key hash, previous offset, and checksum into their respective byte ranges.
• Uses little-endian encoding for numeric values.

Returns:

• A byte array containing the serialized metadata.

pub fn deserialize(data: &[u8]) -> EntryMetadata

Deserializes a byte slice into an EntryMetadata instance.

Reconstructs an EntryMetadata structure from a byte slice, following the predefined binary format. Extracts the key hash, previous offset, and checksum while ensuring correctness through explicit range-based indexing.

Parameters:

• data: A byte slice containing the serialized metadata.

Returns:

• A reconstructed EntryMetadata instance.

Panics:

• If the provided data slice is too small.

Trait Implementations

impl Clone for EntryMetadata

fn clone(&self) -> EntryMetadata

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EntryMetadata

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.