mant_protocol/
update.rs

1//! Process result contracts for explicit cache mutations.
2
3use schemars::JsonSchema;
4use serde::{Deserialize, Serialize};
5
6/// Exact schema marker for an explicit tldr cache update result.
7#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
8pub enum TldrCacheUpdateSchema {
9    /// Version 1 of the tldr cache maintenance result.
10    #[serde(rename = "mant.tldr-update/v1")]
11    V1,
12}
13
14impl TldrCacheUpdateSchema {
15    /// Serialized identifier of the current result contract.
16    pub const ID: &'static str = "mant.tldr-update/v1";
17}
18
19/// How an explicit tldr cache refresh changed local state.
20#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
21#[serde(rename_all = "kebab-case")]
22pub enum TldrCacheAction {
23    /// A cache did not exist and was cloned.
24    Cloned,
25    /// An existing cache advanced or was refreshed.
26    Updated,
27}
28
29/// Result of an explicit `mant --update-tldr` operation.
30#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
31#[serde(rename_all = "camelCase")]
32#[schemars(extend("$id" = "urn:mant:tldr-update:v1"))]
33pub struct TldrCacheUpdate {
34    /// Exact response schema discriminator.
35    pub schema: TldrCacheUpdateSchema,
36    /// Mutation performed by the client-specific update path.
37    pub action: TldrCacheAction,
38    /// Updated cache directory, when the client exposes it.
39    #[serde(skip_serializing_if = "Option::is_none")]
40    pub cache_dir: Option<String>,
41    /// External tldr client used for the operation, when applicable.
42    #[serde(skip_serializing_if = "Option::is_none")]
43    pub client: Option<String>,
44    /// Trimmed human-readable client output, when useful.
45    #[serde(skip_serializing_if = "Option::is_none")]
46    pub output: Option<String>,
47    /// Resulting cache revision, when discoverable.
48    #[serde(skip_serializing_if = "Option::is_none")]
49    pub revision: Option<String>,
50}
51
52#[cfg(test)]
53mod tests {
54    use serde_json::json;
55
56    use super::{TldrCacheAction, TldrCacheUpdate, TldrCacheUpdateSchema};
57
58    #[test]
59    fn cache_update_uses_a_stable_camel_case_shape() {
60        let update = TldrCacheUpdate {
61            schema: TldrCacheUpdateSchema::V1,
62            action: TldrCacheAction::Cloned,
63            cache_dir: Some("/cache/mant/tldr-pages".to_owned()),
64            client: None,
65            output: None,
66            revision: Some("abc123".to_owned()),
67        };
68
69        assert_eq!(
70            serde_json::to_value(update).expect("serialize update"),
71            json!({
72                "schema": "mant.tldr-update/v1",
73                "action": "cloned",
74                "cacheDir": "/cache/mant/tldr-pages",
75                "revision": "abc123"
76            })
77        );
78    }
79}
mant_protocol/update.rs

mant_protocol/
update.rs
