hyprstream_core/storage/
model_ref.rs1use anyhow::{bail, Result};
4use serde::{Deserialize, Serialize};
5use std::fmt;
6use uuid::Uuid;
7
8pub use git2db::GitRef;
10
11#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
19pub struct ModelRef {
20 #[deprecated(
34 since = "0.1.0",
35 note = "prefer at:// / did: federated ModelRefs (#395); use ModelRef::name() for read access"
36 )]
37 pub model: String,
38 pub git_ref: GitRef,
39}
40
41impl ModelRef {
42 #[allow(deprecated)] pub fn new(model: String) -> Self {
45 Self {
46 model,
47 git_ref: GitRef::DefaultBranch,
48 }
49 }
50
51 #[allow(deprecated)] pub fn with_ref(model: String, git_ref: GitRef) -> Self {
54 Self { model, git_ref }
55 }
56
57 #[allow(deprecated)]
65 pub fn name(&self) -> &str {
66 &self.model
67 }
68
69 #[allow(deprecated)] pub fn parse(s: &str) -> Result<Self> {
72 if let Ok(uuid) = Uuid::parse_str(s) {
74 return Ok(ModelRef {
75 model: uuid.to_string(),
76 git_ref: GitRef::DefaultBranch,
77 });
78 }
79
80 let (model, git_ref) = match s.split_once(':') {
82 Some((m, r)) => {
83 let git_ref = GitRef::parse(r)
85 .map_err(|e| anyhow::anyhow!("Failed to parse git ref '{}': {}", r, e))?;
86 (m.to_owned(), git_ref)
87 }
88 None => (s.to_owned(), GitRef::DefaultBranch),
89 };
90
91 validate_model_name(&model)?;
93
94 Ok(ModelRef { model, git_ref })
95 }
96
97 pub fn git_ref_str(&self) -> Option<String> {
99 match &self.git_ref {
100 GitRef::DefaultBranch => None,
101 _ => Some(self.git_ref.display_name()),
102 }
103 }
104}
105
106impl fmt::Display for ModelRef {
109 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
110 match &self.git_ref {
111 GitRef::DefaultBranch => write!(f, "{}", self.name()),
112 _ => write!(f, "{}:{}", self.name(), self.git_ref.display_name()),
113 }
114 }
115}
116
117impl std::str::FromStr for ModelRef {
118 type Err = anyhow::Error;
119
120 fn from_str(s: &str) -> Result<Self> {
121 Self::parse(s)
122 }
123}
124
125pub fn validate_model_name(name: &str) -> Result<()> {
127 if Uuid::parse_str(name).is_ok() {
129 return Ok(());
130 }
131
132 const MAX_LEN: usize = 50;
133 const RESERVED: &[&str] = &["api", "system", "admin", "registry", "test"];
134
135 if name.is_empty() || name.len() > MAX_LEN {
136 bail!("Model name must be 1-{} characters", MAX_LEN);
137 }
138
139 if name.chars().any(
142 |c| {
143 c.is_ascii_control() || c == ' ' || c == '~' || c == '^' || c == ':' || c == '?' || c == '*' || c == '[' || c == '\\' || c == '\t' || c == '\n' || c == '\r'
155 }, ) {
157 bail!("Model name contains invalid characters (spaces, control chars, or Git-forbidden chars)");
158 }
159
160 if name.contains("..") {
162 bail!("Model name cannot contain consecutive dots (..)");
163 }
164
165 if name.ends_with(".lock") {
167 bail!("Model name cannot end with '.lock'");
168 }
169
170 if name == "@" {
172 bail!("Model name cannot be '@'");
173 }
174
175 if name.contains("@{") {
177 bail!("Model name cannot contain '@{{' sequence");
178 }
179
180 if name.starts_with('.') || name.ends_with('.') {
182 bail!("Model name cannot start or end with dot");
183 }
184
185 if RESERVED.contains(&name) {
187 bail!("Model name '{}' is reserved", name);
188 }
189
190 Ok(())
191}
192
193#[cfg(test)]
194mod tests {
195 use super::*;
196
197 #[test]
198 #[allow(deprecated)] fn test_parse_model_ref() -> Result<()> {
200 let ref1 = ModelRef::parse("llama3")?;
202 assert_eq!(ref1.model, "llama3");
203 assert_eq!(ref1.git_ref, GitRef::DefaultBranch);
204
205 let ref2 = ModelRef::parse("llama3:main")?;
207 assert_eq!(ref2.model, "llama3");
208 assert_eq!(ref2.git_ref, GitRef::Branch("main".to_owned()));
209
210 let ref3 = ModelRef::parse("llama3:tags/v2.0")?;
212 assert_eq!(ref3.model, "llama3");
213 assert_eq!(ref3.git_ref, GitRef::Tag("v2.0".to_owned()));
214
215 let ref4 = ModelRef::parse("llama3:1234567890abcdef1234567890abcdef12345678")?;
217 assert_eq!(ref4.model, "llama3");
218 assert!(
219 matches!(ref4.git_ref, GitRef::Commit(oid) if oid.to_string() == "1234567890abcdef1234567890abcdef12345678")
220 );
221
222 let ref5 = ModelRef::parse("llama3:HEAD~1")?;
224 assert_eq!(ref5.model, "llama3");
225 assert_eq!(ref5.git_ref, GitRef::Revspec("HEAD~1".to_owned()));
226
227 let uuid = "550e8400-e29b-41d4-a716-446655440000";
229 let ref6 = ModelRef::parse(uuid)?;
230 assert_eq!(ref6.model, uuid);
231 assert_eq!(ref6.git_ref, GitRef::DefaultBranch);
232 Ok(())
233 }
234
235 #[test]
236 fn test_git_ref_parsing() -> Result<()> {
237 assert_eq!(GitRef::parse("main")?, GitRef::Branch("main".to_owned()));
239 assert!(matches!(GitRef::parse("tags/v1.0.0")?, GitRef::Tag(_)));
241 assert!(matches!(
242 GitRef::parse("HEAD~1")?,
243 GitRef::Revspec(_) | GitRef::DefaultBranch
244 ));
245 assert!(matches!(GitRef::parse("main^2")?, GitRef::Revspec(_)));
246
247 let sha = "1234567890abcdef1234567890abcdef12345678";
249 assert!(matches!(GitRef::parse(sha)?, GitRef::Commit(oid) if oid.to_string() == sha));
250
251 assert!(matches!(GitRef::parse("1234567")?, GitRef::Revspec(_)));
253 Ok(())
254 }
255
256 #[test]
257 fn test_git_ref_display() -> Result<()> {
258 assert_eq!(GitRef::DefaultBranch.display_name(), "HEAD");
260 assert_eq!(GitRef::Branch("main".to_owned()).display_name(), "main");
261 assert!(GitRef::Tag("v1.0".to_owned())
263 .display_name()
264 .contains("v1.0"));
265 assert_eq!(
266 GitRef::Revspec("HEAD~1".to_owned()).display_name(),
267 "HEAD~1"
268 );
269
270 let oid = git2db::Oid::from_str("1234567890abcdef1234567890abcdef12345678")?;
271 assert!(GitRef::Commit(oid).display_name().contains("12345678"));
273 Ok(())
274 }
275
276 #[test]
277 fn test_model_ref_compatibility() -> Result<()> {
278 let model_ref = ModelRef::parse("llama3:main")?;
280
281 assert_eq!(model_ref.git_ref_str(), Some("main".to_owned()));
283
284 assert_eq!(model_ref.to_string(), "llama3:main");
286
287 let default_ref = ModelRef::parse("llama3")?;
289 assert_eq!(default_ref.to_string(), "llama3");
290 assert_eq!(default_ref.git_ref_str(), None);
291 Ok(())
292 }
293
294 #[test]
295 fn test_validate_model_name() {
296 assert!(validate_model_name("llama3").is_ok());
298 assert!(validate_model_name("gpt-2").is_ok());
299 assert!(validate_model_name("model-123").is_ok());
300 assert!(validate_model_name("Qwen3-4B").is_ok()); assert!(validate_model_name("GPT-4").is_ok()); assert!(validate_model_name("Model").is_ok()); assert!(validate_model_name("Qwen3-0.6B").is_ok()); assert!(validate_model_name("model-v1.2.3").is_ok()); assert!(validate_model_name("model_with_underscores").is_ok()); assert!(validate_model_name("model/submodel").is_ok()); assert!(validate_model_name("org-name_model.v1").is_ok()); assert!(validate_model_name("123model").is_ok()); assert!(validate_model_name("model+special").is_ok()); assert!(validate_model_name("model=equals").is_ok()); assert!(validate_model_name("").is_err()); assert!(validate_model_name(".model").is_err()); assert!(validate_model_name("model.").is_err()); assert!(validate_model_name("model..name").is_err()); assert!(validate_model_name("model.lock").is_err()); assert!(validate_model_name("@").is_err()); assert!(validate_model_name("model@{ref}").is_err()); assert!(validate_model_name("api").is_err()); assert!(validate_model_name("model with spaces").is_err()); assert!(validate_model_name("model~1").is_err()); assert!(validate_model_name("model^HEAD").is_err()); assert!(validate_model_name("model:tag").is_err()); assert!(validate_model_name("model?query").is_err()); assert!(validate_model_name("model*glob").is_err()); assert!(validate_model_name("model[bracket]").is_err()); }
329
330 #[test]
331 fn test_git_ref_validation() -> Result<()> {
332 assert!(matches!(GitRef::parse("main")?, GitRef::Branch(_)));
336 assert!(matches!(
337 GitRef::parse("feature/new-model")?,
338 GitRef::Branch(_)
339 ));
340
341 assert!(matches!(GitRef::parse("tags/v1.0.0")?, GitRef::Tag(_)));
343 assert!(matches!(GitRef::parse("refs/tags/v2.1")?, GitRef::Tag(_)));
344
345 assert!(matches!(GitRef::parse("HEAD")?, GitRef::DefaultBranch));
348 assert!(matches!(GitRef::parse("main~1")?, GitRef::Revspec(_)));
349 assert!(matches!(GitRef::parse("HEAD^")?, GitRef::Revspec(_)));
350 assert!(matches!(
351 GitRef::parse("branch..other")?,
352 GitRef::Revspec(_)
353 ));
354 assert!(matches!(
355 GitRef::parse("branch@{HEAD}")?,
356 GitRef::Revspec(_)
357 ));
358
359 assert!(matches!(
361 GitRef::parse("1234567890abcdef1234567890abcdef12345678")?,
362 GitRef::Commit(_)
363 ));
364
365 assert!(git2::Reference::is_valid_name("refs/heads/main"));
367 assert!(git2::Reference::is_valid_name("refs/tags/v1.0.0"));
368 assert!(git2::Reference::is_valid_name(
369 "refs/heads/feature/new-model"
370 ));
371 assert!(git2::Reference::is_valid_name("HEAD"));
372 Ok(())
373 }
374}