docsrs_cli/cache/types.rs
1//! Public cache inventory types and layout constants.
2
3use serde::{Deserialize, Serialize};
4
5/// Bump when HTML/JSON parse semantics change so stale entries are ignored.
6pub const CACHE_PARSER_VERSION: &str = "1";
7/// Default entry TTL (24 hours).
8pub const DEFAULT_CACHE_TTL_SECS: u64 = 86_400;
9/// Default on-disk budget (256 MiB). `0` means unlimited.
10pub const DEFAULT_MAX_CACHE_BYTES: u64 = 256 * 1024 * 1024;
11/// Hard ceiling for on-disk cache meta JSON (poisoned-entry guard).
12///
13/// Legitimate `CacheMeta` is a few hundred bytes (URLs + digests). A multi-KiB
14/// ceiling leaves headroom while blocking multi-GiB `read_to_string` aborts.
15pub const MAX_CACHE_META_BYTES: u64 = 64 * 1024;
16/// On-disk layout version under the cache root.
17pub(super) const CACHE_LAYOUT: &str = "http/v1";
18
19/// Aggregate cache inventory for `cache stats` / doctor.
20#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
21pub struct CacheStats {
22 /// Absolute cache root path.
23 pub root: String,
24 /// On-disk layout subdirectory (for example `http/v1`).
25 pub layout: String,
26 /// Number of complete cache entries (meta+body pairs).
27 pub entries: u64,
28 /// Total bytes used by meta and body files.
29 pub total_bytes: u64,
30 /// Configured soft budget (`0` = unlimited).
31 pub max_bytes: u64,
32 /// Configured TTL in seconds.
33 pub ttl_secs: u64,
34 /// Parser version used for cache keys.
35 pub parser_version: String,
36}
37
38/// Result of `cache clear`.
39#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
40pub struct CacheClearResult {
41 /// Absolute cache root path that was cleared.
42 pub root: String,
43 /// Number of entries removed.
44 pub removed_entries: u64,
45 /// Bytes reclaimed from deleted files.
46 pub freed_bytes: u64,
47}
48
49/// On-disk JSON metadata for one cache entry.
50///
51/// `deny_unknown_fields`: local meta is product-owned; extra keys mean tamper or
52/// schema drift → treat as miss (fail closed at the serde boundary).
53#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
54#[serde(deny_unknown_fields)]
55pub(super) struct CacheMeta {
56 pub(super) url: String,
57 pub(super) parser_version: String,
58 pub(super) accept: String,
59 pub(super) status: u16,
60 pub(super) content_type: Option<String>,
61 pub(super) final_url: String,
62 pub(super) stored_at_unix: u64,
63 pub(super) body_sha256: String,
64 /// SHA-256 of the cache key material (url + parser + accept).
65 pub(super) input_sha256: String,
66}
67
68impl CacheMeta {
69 /// True when digest fields look like SHA-256 hex (shape check before body I/O).
70 pub(super) fn digests_look_valid(&self) -> bool {
71 super::hex::is_sha256_hex(&self.body_sha256)
72 && super::hex::is_sha256_hex(&self.input_sha256)
73 }
74}
75
76#[derive(Debug)]
77pub(super) struct EntryOnDisk {
78 pub(super) key: String,
79 pub(super) stored_at_unix: u64,
80 pub(super) bytes: u64,
81}