Skip to main content

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}