1use serde::{Deserialize, Serialize};
37use std::fmt;
38
39#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
41#[serde(tag = "source", rename_all = "snake_case")]
42pub enum Reference {
43 Ollama {
44 namespace: String,
46 name: String,
47 tag: String,
48 },
49 HuggingFace {
50 owner: String,
51 repo: String,
52 revision: String,
54 quant: Option<String>,
57 },
58 Local { path: String },
60 Url {
63 url: String,
64 sha256: Option<String>,
68 },
69}
70
71#[derive(Debug, Clone, PartialEq, Eq)]
72pub struct ParseError(pub String);
73
74impl fmt::Display for ParseError {
75 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
76 write!(f, "{}", self.0)
77 }
78}
79
80impl std::error::Error for ParseError {}
81
82fn bad(msg: impl Into<String>) -> ParseError {
83 ParseError(msg.into())
84}
85
86impl Reference {
87 pub fn parse(input: &str) -> Result<Reference, ParseError> {
89 let s = input.trim();
90 if s.is_empty() {
91 return Err(bad("empty model reference"));
92 }
93
94 if let Some(rest) = strip_scheme(s, "hf") {
109 return parse_hf(rest);
110 }
111 if let Some(rest) = strip_scheme(s, "huggingface") {
112 return parse_hf(rest);
113 }
114 if let Some(rest) = strip_scheme(s, "ollama") {
115 return parse_ollama(rest);
116 }
117 if let Some(rest) = strip_scheme(s, "file") {
118 if rest.is_empty() {
119 return Err(bad("file: needs a path"));
120 }
121 return Ok(Reference::Local {
122 path: rest.to_string(),
123 });
124 }
125 if s.starts_with("http://") || s.starts_with("https://") {
132 return parse_url(s);
133 }
134
135 if looks_like_path(s) {
137 return Ok(Reference::Local {
138 path: s.to_string(),
139 });
140 }
141
142 parse_ollama(s)
145 }
146
147 pub fn key(&self) -> String {
153 match self {
154 Reference::Ollama {
155 namespace,
156 name,
157 tag,
158 } => {
159 format!("ollama/{namespace}/{name}:{tag}")
160 }
161 Reference::HuggingFace {
162 owner,
163 repo,
164 revision,
165 quant,
166 } => {
167 let q = quant.as_deref().unwrap_or("auto");
168 format!("hf/{owner}/{repo}@{revision}#{q}")
169 }
170 Reference::Local { path } => format!("local/{path}"),
171 Reference::Url { url, .. } => format!("url/{url}"),
172 }
173 }
174
175 pub fn display_name(&self) -> String {
177 match self {
178 Reference::Ollama {
179 namespace,
180 name,
181 tag,
182 } if namespace == "library" => {
183 format!("{name}:{tag}")
184 }
185 Reference::Ollama {
186 namespace,
187 name,
188 tag,
189 } => format!("{namespace}/{name}:{tag}"),
190 Reference::HuggingFace {
191 owner, repo, quant, ..
192 } => match quant {
193 Some(q) => format!("{owner}/{repo}@{q}"),
194 None => format!("{owner}/{repo}"),
195 },
196 Reference::Local { path } => path
197 .rsplit('/')
198 .next()
199 .unwrap_or(path)
200 .trim_end_matches(".gguf")
201 .to_string(),
202 Reference::Url { url, .. } => {
203 let without_query = url.split(['?', '#']).next().unwrap_or(url);
206 without_query
207 .rsplit('/')
208 .next()
209 .filter(|s| !s.is_empty())
210 .unwrap_or(url)
211 .trim_end_matches(".gguf")
212 .to_string()
213 }
214 }
215 }
216
217 pub fn needs_download(&self) -> bool {
218 !matches!(self, Reference::Local { .. })
219 }
220}
221
222fn strip_scheme<'a>(s: &'a str, scheme: &str) -> Option<&'a str> {
223 let lower = s.to_ascii_lowercase();
224 let prefix = format!("{scheme}:");
225 if lower.starts_with(&format!("{prefix}//")) {
228 Some(&s[prefix.len() + 2..])
229 } else if lower.starts_with(&prefix) {
230 Some(&s[prefix.len()..])
231 } else {
232 None
233 }
234}
235
236fn looks_like_path(s: &str) -> bool {
237 s.starts_with('.')
238 || s.starts_with('/')
239 || s.starts_with('~')
240 || s.ends_with(".gguf")
241 || (s.len() > 2 && s.as_bytes()[1] == b':' && (s.contains('\\') || s.contains('/')))
243}
244
245fn parse_hf(rest: &str) -> Result<Reference, ParseError> {
246 if rest.is_empty() {
247 return Err(bad("hf: needs an owner/repo"));
248 }
249 let (head, revision) = match rest.split_once('#') {
252 Some((h, r)) if !r.is_empty() => (h, r.to_string()),
253 Some(_) => return Err(bad("empty revision after '#'")),
254 None => (rest, "main".to_string()),
255 };
256 let (path, quant) = match head.split_once('@') {
257 Some((p, q)) if !q.is_empty() => (p, Some(q.to_string())),
258 Some(_) => return Err(bad("empty quantization after '@'")),
259 None => (head, None),
260 };
261
262 let mut parts = path.split('/');
263 let owner = parts.next().unwrap_or("");
264 let repo = parts.next().unwrap_or("");
265 if owner.is_empty() || repo.is_empty() || parts.next().is_some() {
266 return Err(bad(format!(
267 "expected owner/repo, got \"{path}\" — a HuggingFace reference has exactly two parts"
268 )));
269 }
270
271 Ok(Reference::HuggingFace {
272 owner: owner.to_string(),
273 repo: repo.to_string(),
274 revision,
275 quant,
276 })
277}
278
279fn parse_url(s: &str) -> Result<Reference, ParseError> {
283 match s.split_once('#') {
284 None => Ok(Reference::Url {
285 url: s.to_string(),
286 sha256: None,
287 }),
288 Some((url, frag)) => {
289 let hex = frag.strip_prefix("sha256:").ok_or_else(|| {
290 bad(format!(
291 "unrecognised fragment \"#{frag}\" on a URL reference — \
292 the only one hearth understands is #sha256:HEX"
293 ))
294 })?;
295 if hex.is_empty() || !hex.chars().all(|c| c.is_ascii_hexdigit()) {
296 return Err(bad(format!("\"{hex}\" after #sha256: is not a hex digest")));
297 }
298 Ok(Reference::Url {
299 url: url.to_string(),
300 sha256: Some(hex.to_ascii_lowercase()),
301 })
302 }
303 }
304}
305
306fn parse_ollama(rest: &str) -> Result<Reference, ParseError> {
307 if rest.is_empty() {
308 return Err(bad("ollama: needs a model name"));
309 }
310 let (path, tag) = match rest.rsplit_once(':') {
311 Some((p, t)) if !t.is_empty() && !t.contains('/') => (p, t.to_string()),
312 Some((_, "")) => return Err(bad("empty tag after ':'")),
313 _ => (rest, "latest".to_string()),
314 };
315
316 let mut parts = path.split('/');
317 let first = parts.next().unwrap_or("");
318 let second = parts.next();
319 if parts.next().is_some() {
320 return Err(bad(format!(
321 "expected name or namespace/name, got \"{path}\""
322 )));
323 }
324 let (namespace, name) = match second {
325 None => ("library".to_string(), first.to_string()),
327 Some(n) => (first.to_string(), n.to_string()),
328 };
329 if name.is_empty() || namespace.is_empty() {
330 return Err(bad(format!("incomplete model name: \"{rest}\"")));
331 }
332
333 Ok(Reference::Ollama {
334 namespace,
335 name,
336 tag,
337 })
338}
339
340#[cfg(test)]
341mod file_scheme_tests {
342 use super::*;
343
344 #[test]
349 fn a_file_url_yields_a_path_you_can_actually_open() {
350 for (input, want) in [
351 ("file:/models/muse.gguf", "/models/muse.gguf"),
352 ("file:./muse.gguf", "./muse.gguf"),
353 ("file:muse.gguf", "muse.gguf"),
354 ("file:/models/model.bin", "/models/model.bin"),
357 ] {
358 match Reference::parse(input).expect(input) {
359 Reference::Local { path } => assert_eq!(path, want, "for {input}"),
360 other => panic!("{input} should be Local, got {other:?}"),
361 }
362 }
363 }
364
365 #[test]
366 fn a_bare_path_still_works_without_a_scheme() {
367 for input in ["/models/muse.gguf", "./muse.gguf", "~/models/muse.gguf"] {
368 match Reference::parse(input).expect(input) {
369 Reference::Local { path } => assert_eq!(path, input),
370 other => panic!("{input} should be Local, got {other:?}"),
371 }
372 }
373 }
374
375 #[test]
376 fn a_windows_path_is_not_mistaken_for_a_scheme() {
377 for input in [r"C:\models\muse.gguf", "C:/models/muse.gguf"] {
381 match Reference::parse(input).expect(input) {
382 Reference::Local { path } => assert_eq!(path, input),
383 other => panic!("{input} should be Local, got {other:?}"),
384 }
385 }
386 }
387
388 #[test]
389 fn the_other_schemes_still_win_over_the_path_heuristic() {
390 assert!(matches!(
393 Reference::parse("hf:TheBloke/X-GGUF").unwrap(),
394 Reference::HuggingFace { .. }
395 ));
396 assert!(matches!(
397 Reference::parse("ollama:library/llama3:latest").unwrap(),
398 Reference::Ollama { .. }
399 ));
400 }
401
402 #[test]
403 fn an_empty_file_scheme_is_an_error_not_an_empty_path() {
404 assert!(Reference::parse("file:").is_err());
406 }
407
408 #[test]
409 fn display_name_is_the_model_name_now_that_the_scheme_is_gone() {
410 let r = Reference::parse("file:/models/muse.gguf").unwrap();
415 assert_eq!(r.display_name(), "muse");
416 assert_eq!(r.key(), "local//models/muse.gguf");
417 }
418}
419
420#[cfg(test)]
421mod url_scheme_tests {
422 use super::*;
423
424 #[test]
429 fn a_gguf_url_is_not_mistaken_for_a_local_path() {
430 for scheme in ["http", "https"] {
431 let input = format!("{scheme}://example.com/models/model.gguf");
432 match Reference::parse(&input).expect(&input) {
433 Reference::Url { url, sha256 } => {
434 assert_eq!(url, input);
435 assert_eq!(sha256, None);
436 }
437 other => panic!("{input} should be Url, got {other:?}"),
438 }
439 }
440 }
441
442 #[test]
443 fn a_pinned_sha256_fragment_is_read_and_lowercased() {
444 let r = Reference::parse(
445 "https://example.com/m.gguf#sha256:DEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEF",
446 )
447 .unwrap();
448 match r {
449 Reference::Url { sha256, .. } => assert_eq!(
450 sha256.as_deref(),
451 Some("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef")
452 ),
453 other => panic!("expected Url, got {other:?}"),
454 }
455 }
456
457 #[test]
458 fn a_fragment_that_is_not_sha256_is_a_named_error() {
459 let err = Reference::parse("https://example.com/m.gguf#refs/pr/3").unwrap_err();
460 assert!(err.0.contains("sha256:"), "{}", err.0);
461 }
462
463 #[test]
464 fn a_non_hex_digest_is_refused_rather_than_stored_wrong() {
465 let err = Reference::parse("https://example.com/m.gguf#sha256:not-hex").unwrap_err();
466 assert!(err.0.contains("not a hex digest"), "{}", err.0);
467 }
468
469 #[test]
470 fn an_empty_digest_fragment_is_refused() {
471 assert!(Reference::parse("https://example.com/m.gguf#sha256:").is_err());
472 }
473
474 #[test]
475 fn display_name_is_the_filename_with_the_query_string_dropped() {
476 let r = Reference::parse("https://cdn.example.com/models/muse.gguf?token=abc123").unwrap();
477 assert_eq!(
478 r.display_name(),
479 "muse",
480 "a query-string token must never end up in a model name"
481 );
482 }
483
484 #[test]
485 fn display_name_falls_back_to_the_whole_url_when_the_path_is_empty() {
486 let r = Reference::parse("https://example.com/").unwrap();
487 assert_eq!(r.display_name(), "https://example.com/");
488 }
489
490 #[test]
491 fn key_is_stable_across_calls_for_the_same_url() {
492 let r = Reference::parse("https://example.com/m.gguf").unwrap();
493 assert_eq!(
494 r.key(),
495 Reference::parse("https://example.com/m.gguf")
496 .unwrap()
497 .key()
498 );
499 assert_eq!(r.key(), "url/https://example.com/m.gguf");
500 }
501
502 #[test]
503 fn a_url_needs_a_download_like_every_non_local_reference() {
504 let r = Reference::parse("https://example.com/m.gguf").unwrap();
505 assert!(r.needs_download());
506 }
507}