Struct FileHeader 

pub struct FileHeader {
    pub format_major: u16,
    pub format_minor: u16,
    pub page_size: u16,
    pub feature_flags: u32,
    pub page_count: u64,
    pub root_catalog: u64,
    pub freelist_head: u64,
    pub wal_salt: [u8; 16],
    pub file_uuid: [u8; 16],
    pub kdf_salt: [u8; 32],
}

In-memory representation of the page-0 file header.

Constructed by decode_header or by the pager when initialising a new file. Field semantics are documented in docs/format.md.

Fields

format_major: u16

Format major version. Must equal FORMAT_MAJOR.

format_minor: u16

Format minor version. Must satisfy <= FORMAT_MINOR for write access; readers tolerate higher minors.

page_size: u16

On-disk page size. Must equal PAGE_SIZE at format major 0.

feature_flags: u32

Phase 3 (issue #8): per-file feature-bit mask. Bit 0 = “uses LZ4 page compression”; other bits reserved (MUST be zero — readers reject unknown bits as Error::InvalidFormat).

page_count: u64

Number of pages in the file, including page 0.

root_catalog: u64

Root catalog page-id, or 0 if the catalog is empty.

freelist_head: u64

First page on the freelist, or 0 if the freelist is empty.

wal_salt: [u8; 16]

Salt for WAL frame hashes. Written by M3; zero in M2.

file_uuid: [u8; 16]

Stable file UUID. Written by M3; zero in M2.

kdf_salt: [u8; 32]

Phase 4 (issue #9): 32-byte salt for the HKDF-SHA256 per-file page-key derivation. Plaintext on disk (page 0 is never encrypted); the file’s actual page-encryption key is HKDF-SHA256(ikm=user_key, salt=kdf_salt, info=b"obj-page-encryption-v1"). Always zero on format_minor < 2 files; CSPRNG-generated on creation of format_minor = 2 files with feature_flags bit 1 set.

#60 (integrity posture): the kdf_salt lives in the plaintext page-0 header and is protected ONLY by the header’s own CRC. It is NOT bound into any page’s AEAD associated data (page AD is just page_id; see crypto.rs), so the AEAD tag does not authenticate it. Its integrity therefore rests on two independent layers: (1) the page-0 header CRC detects accidental corruption, and (2) any tampering that survives the CRC changes the derived page key, which surfaces as Error::EncryptionKeyInvalid (wrong-key detection) on the first page decrypt rather than as silent plaintext disclosure. Binding the salt into page AD is deliberately NOT done — it would be a format-affecting change.

Implementations

impl FileHeader

pub const fn new_empty() -> Self

Header for a freshly-initialised database: just page 0, no catalog, empty freelist, zero WAL salt and UUID (M3 fills the latter two).

Phase 8 (issue #17): every v1.0 writer stamps format_major = 1, format_minor = 2 — the feature-complete frozen baseline. feature_flags = 0 because this constructor produces a plain (no-compression, no-encryption) file; the other new_empty_* constructors set the corresponding feature_flags bits.

pub const fn new_empty_with_compression() -> Self

Phase 3 (issue #8): header for a freshly-initialised compression-capable database. feature_flags bit 0 set; format_minor is the frozen v1.0 feature-complete value (FORMAT_MINOR = 2). Everything else matches FileHeader::new_empty.

pub const fn new_empty_with_encryption(kdf_salt: [u8; 32]) -> Self

Phase 4 (issue #9): header for a freshly-initialised encryption-capable database. format_minor = 2, feature_flags bit 1 set, kdf_salt populated from the caller-supplied CSPRNG bytes. Compression (bit 0) is left OFF; the higher-level FileHeader::new_empty_with_encryption_and_compression constructor sets both bits.

pub const fn new_empty_with_encryption_and_compression( kdf_salt: [u8; 32], ) -> Self

Phase 4 (issue #9): header for a freshly-initialised database that uses BOTH compression AND encryption. The layering order is compress-then-encrypt: the 4092-byte raw body is compressed (Phase 3 path), the resulting 4096-byte logical page is encrypted (Phase 4 path), and the encrypted ciphertext (+ nonce + tag) lands on disk as a 4136-byte physical page.

Trait Implementations

impl Clone for FileHeader

fn clone(&self) -> FileHeader

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for FileHeader

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

Formats the value using the given formatter.

impl PartialEq for FileHeader

fn eq(&self, other: &FileHeader) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for FileHeader

impl Eq for FileHeader

impl StructuralPartialEq for FileHeader