Edison Jwa
01a4a9ed28
Add purpose, architecture, and public API summary to each crate README following chanora_resolver pattern. Update verification master plan with new evidence sources and entry/exit criteria.
40 lines
1.6 KiB
Markdown
40 lines
1.6 KiB
Markdown
# chanora_cache
|
|
|
|
Disposable content-addressed blob cache for avatar and icon files. Wraps `cacache` for crash safety and integrity verification. Separated from `chanora_storage` because cache owns reconstructible, disposable blob data with different durability and backup semantics.
|
|
|
|
## Architecture
|
|
|
|
- **`BlobCache`** — async blob store backed by cacache's content-v2 / index-v2 on-disk layout.
|
|
- Keys are protocol identifiers prefixed by type: `av_<32-char-hex>` for avatars (MD5), `ic_<decimal>` for icons (CRC32).
|
|
- Cacache handles dedup and SSRI integrity verification on every read.
|
|
- Corrupt entries are automatically removed on read failure.
|
|
- LRU eviction by timestamp when total size exceeds the configured cap.
|
|
|
|
## Public API Summary
|
|
|
|
### Types
|
|
|
|
| Type | Role |
|
|
|---|---|
|
|
| `BlobCache` | Content-addressed blob cache |
|
|
| `BlobCacheError` | Io, InvalidKey |
|
|
|
|
### Key methods on `BlobCache`
|
|
|
|
- `new(cache_dir, max_bytes)` — create or open the cache. `max_bytes = 0` disables eviction.
|
|
- `put(prefix, key, data)` — store a blob (async)
|
|
- `get(prefix, key)` → `Option<Vec<u8>>` — read a blob, with integrity check (async)
|
|
- `remove(prefix, key)` — delete a specific blob (async)
|
|
- `clear()` — delete all blobs (async)
|
|
- `total_size()` → `u64` — sum of all blob sizes (async)
|
|
- `evict()` — remove oldest entries until under `max_bytes` cap (async)
|
|
|
|
### Constants
|
|
|
|
- `PREFIX_AVATAR` = `"av_"` — avatar key prefix
|
|
- `PREFIX_ICON` = `"ic_"` — icon key prefix
|
|
|
|
## Key validation
|
|
|
|
Avatar keys must be exactly 32 hex characters. Icon keys must be non-empty decimal digits. Unknown prefixes are rejected. This prevents malformed entries from polluting the cache.
|