Module cache_serialization

Expand description

Cache state serialization and restoration.

Provides a binary serializer / deserializer so a cache can be persisted to disk on shutdown and quickly restored on startup — avoiding a cold-start penalty where all traffic misses until the cache is re-warmed organically.

§Wire format

The on-disk format is a simple length-prefixed binary encoding; no external serialization dependency is needed.

┌─────────────────────────────────────────────────────┐
│ MAGIC   8 bytes   "OXICACHE"                        │
│ VERSION 2 bytes   u16 LE = 1                        │
│ FLAGS   2 bytes   u16 LE (reserved, must be 0)      │
│ N       4 bytes   u32 LE number of entries          │
│ ── per entry ──────────────────────────────────────  │
│   key_len   4 bytes  u32 LE                         │
│   key       key_len bytes UTF-8                     │
│   val_len   4 bytes  u32 LE                         │
│   value     val_len bytes raw bytes                 │
│   priority  4 bytes  u32 LE                         │
│   ttl_secs  8 bytes  u64 LE (0 = no TTL)           │
└─────────────────────────────────────────────────────┘

The format is intentionally simple and forward-compatible: unknown flags and trailing data are ignored on read.

Structs§

CacheRecord: A single key-value record with optional metadata.
DeserializeConfig: Configuration for the deserializer.

Enums§

SerializeError: Errors returned by serialization / deserialization functions.

Functions§

deserialize: Read CacheRecords from reader using the default DeserializeConfig.
deserialize_with_config: Read CacheRecords from reader with an explicit DeserializeConfig.
load_from_file: Restore records from the file at path.
load_from_file_with_config: Restore records from the file at path with explicit limits.
save_to_file: Persist records to the file at path, creating or truncating it.
serialize: Write a collection of CacheRecords to writer in the OXICACHE binary format.