rootle_provider/
id.rs

1//! Typed identity for the provider seam (plans/0025): the three
2//! nouns that cross every boundary — which repo, which content, which
3//! revision — as opaque newtypes instead of naked `String`s. The bug
4//! classes this kills: a sha where a ref was meant, a ref where a
5//! repo id was meant, a repo id formatted differently at two sites.
6//!
7//! Wire discipline: the protocol is stringly by design (reader
8//! tolerance, opaque ids); these types are the *Rust* vocabulary.
9//! They are `#[serde(transparent)]` so wire models can adopt them
10//! without format changes. Millers-pane structure (separate
11//! owner/name) is a UI concern and stays untyped — the joined id is
12//! minted where the seam begins.
13
14use serde::{Deserialize, Serialize};
15
16macro_rules! opaque_id {
17    ($name:ident, $doc:literal) => {
18        #[doc = $doc]
19        #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
20        #[serde(transparent)]
21        pub struct $name(String);
22
23        impl $name {
24            /// The wire/UI form, verbatim.
25            pub fn as_str(&self) -> &str {
26                &self.0
27            }
28        }
29
30        impl std::fmt::Display for $name {
31            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
32                f.write_str(&self.0)
33            }
34        }
35
36        impl From<String> for $name {
37            fn from(value: String) -> Self {
38                $name(value)
39            }
40        }
41
42        impl From<&str> for $name {
43            fn from(value: &str) -> Self {
44                $name(value.to_string())
45            }
46        }
47
48        impl AsRef<str> for $name {
49            fn as_ref(&self) -> &str {
50                &self.0
51            }
52        }
53    };
54}
55
56opaque_id!(
57    RepoId,
58    "Opaque `\"group/project\"` repo identity (protocol: the UI never\n\
59     parses it; each backend owns its grammar)."
60);
61
62opaque_id!(
63    Sha,
64    "Opaque content id: MUST change when content changes (the cache\n\
65     is content-keyed and immutable). A commit sha on backends that\n\
66     have them; whatever the adapter guarantees otherwise."
67);
68
69opaque_id!(
70    GitRef,
71    "A resolvable revision name — branch, tag, or commit sha — as the\n\
72     backend interprets it (`repo/tree`'s `ref` param). `None` at a\n\
73     call site means the default branch; this type never encodes it."
74);
75
76opaque_id!(
77    RepoPath,
78    "An opaque repository-relative path, not a host filesystem path."
79);
80opaque_id!(
81    OrgId,
82    "An opaque organization or group identity, independent of its displayed caption."
83);
84
85impl Sha {
86    pub fn short(&self) -> String {
87        self.as_str().chars().take(7).collect()
88    }
89}
90
91/// Domain-tagged request generation. Different pipelines cannot compare
92/// clocks, even though both happen to be represented by an integer.
93#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
94pub struct Generation<Domain> {
95    value: u64,
96    domain: std::marker::PhantomData<Domain>,
97}
98
99impl<Domain> Default for Generation<Domain> {
100    fn default() -> Self {
101        Self {
102            value: 0,
103            domain: std::marker::PhantomData,
104        }
105    }
106}
107
108impl<Domain: Copy + PartialEq> Generation<Domain> {
109    pub fn tick(&mut self) -> Self {
110        self.value = self
111            .value
112            .checked_add(1)
113            .expect("request generation exhausted");
114        *self
115    }
116
117    pub fn is_current(&self, other: Self) -> bool {
118        *self == other
119    }
120}
121
122impl<Domain> std::fmt::Display for Generation<Domain> {
123    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
124        self.value.fmt(formatter)
125    }
126}
127
128/// Diagnostic/wire serialization exposes the count without weakening the
129/// domain-typed comparison API or round-tripping through Display.
130impl<Domain> serde::Serialize for Generation<Domain> {
131    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
132        serializer.serialize_u64(self.value)
133    }
134}
135
136#[cfg(test)]
137mod tests {
138    use super::*;
139
140    #[test]
141    fn generation_guards_drop_stale_captures() {
142        let mut clock = Generation::<()>::default();
143        let spawn = clock.tick();
144        assert!(clock.is_current(spawn));
145        let _newer = clock.tick();
146        assert!(!clock.is_current(spawn));
147    }
148}
rootle_provider/id.rs

rootle_provider/
id.rs
