1use async_trait::async_trait;
2use serde::{Deserialize, Serialize};
3use sha2::{Digest, Sha256};
4use std::{
5 any::Any,
6 collections::BTreeMap,
7 fs,
8 io::{Read, Write},
9 path::{Path, PathBuf},
10 sync::Arc,
11};
12use tokio_util::sync::CancellationToken;
13
14pub type ModelMetadata = BTreeMap<String, String>;
15
16#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Hash, Ord, PartialOrd)]
18pub struct ModelId {
19 pub name: String,
20 pub version: String,
21}
22
23impl ModelId {
24 pub fn new(name: impl Into<String>, version: impl Into<String>) -> Result<Self, CatalogError> {
25 let id = Self {
26 name: name.into(),
27 version: version.into(),
28 };
29 id.validate()?;
30 Ok(id)
31 }
32
33 pub fn parse(reference: &str) -> Result<Self, CatalogError> {
34 let (name, version) = reference
35 .rsplit_once('@')
36 .ok_or_else(|| CatalogError::InvalidIdentity(reference.to_owned()))?;
37 Self::new(name, version)
38 }
39
40 pub fn validate(&self) -> Result<(), CatalogError> {
41 if self.name.is_empty()
42 || self.version.is_empty()
43 || self.name.contains(['/', '\\', '@'])
44 || self.version.contains(['/', '\\', '@'])
45 || self.name.contains("..")
46 || self.version.contains("..")
47 {
48 return Err(CatalogError::InvalidIdentity(format!(
49 "{}@{}",
50 self.name, self.version
51 )));
52 }
53 Ok(())
54 }
55}
56
57impl std::fmt::Display for ModelId {
58 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
59 write!(f, "{}@{}", self.name, self.version)
60 }
61}
62
63#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Hash)]
64pub enum ModelFormat {
65 #[serde(rename = "onnx", alias = "Onnx")]
66 Onnx,
67 #[serde(rename = "coreml", alias = "CoreMl")]
68 CoreMl,
69 #[serde(rename = "gguf", alias = "Gguf")]
70 Gguf,
71 #[serde(rename = "safetensors", alias = "Safetensors")]
72 Safetensors,
73 #[serde(rename = "tensorrt", alias = "TensorRt")]
74 TensorRt,
75 #[serde(rename = "unknown", alias = "Unknown")]
76 Unknown,
77}
78
79#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
80pub enum ModelLocation {
81 Path(String),
82 Uri(String),
83 Embedded(String),
84 Memory,
85}
86
87#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
89pub struct ModelSpec {
90 pub id: String,
91 pub version: Option<String>,
92 pub format: ModelFormat,
93 pub location: ModelLocation,
94 pub metadata: ModelMetadata,
95}
96
97#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
98pub struct ModelManifest {
99 #[serde(default = "default_schema_version")]
100 pub schema_version: u32,
101 #[serde(alias = "name")]
102 pub id: String,
103 #[serde(default)]
104 pub model_version: Option<String>,
105 #[serde(default)]
106 pub version: Option<String>,
107 pub format: ModelFormat,
108 #[serde(alias = "artifact_path")]
109 pub artifact: ArtifactSpec,
110 #[serde(default)]
111 pub metadata: ModelMetadata,
112 #[serde(default)]
113 pub inputs: Vec<ModelTensorSpec>,
114 #[serde(default)]
115 pub outputs: Vec<ModelTensorSpec>,
116}
117
118#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
119pub struct ArtifactSpec {
120 pub path: String,
121 #[serde(default)]
122 pub size_bytes: Option<u64>,
123 #[serde(default)]
124 pub sha256: Option<String>,
125}
126
127impl<'de> Deserialize<'de> for ArtifactSpec {
128 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
129 where
130 D: serde::Deserializer<'de>,
131 {
132 #[derive(Deserialize)]
133 #[serde(untagged)]
134 enum Input {
135 Path(String),
136 Metadata {
137 path: String,
138 #[serde(default)]
139 size_bytes: Option<u64>,
140 #[serde(default)]
141 sha256: Option<String>,
142 },
143 }
144 match Input::deserialize(deserializer)? {
145 Input::Path(path) => Ok(Self {
146 path,
147 size_bytes: None,
148 sha256: None,
149 }),
150 Input::Metadata {
151 path,
152 size_bytes,
153 sha256,
154 } => Ok(Self {
155 path,
156 size_bytes,
157 sha256,
158 }),
159 }
160 }
161}
162
163#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
164pub struct ModelTensorSpec {
165 pub name: String,
166 #[serde(default)]
167 pub data_type: Option<String>,
168 #[serde(default)]
169 pub shape: Option<Vec<i64>>,
170}
171
172fn default_schema_version() -> u32 {
173 1
174}
175
176#[derive(Clone, Debug, PartialEq, Eq)]
177pub struct ModelPackage {
178 pub manifest: ModelManifest,
179 pub root: PathBuf,
180 pub artifact: PathBuf,
181}
182
183impl ModelPackage {
184 pub fn open(root: impl AsRef<Path>) -> Result<Self, String> {
185 let root = root.as_ref().to_path_buf();
186 let manifest_path = root.join("manifest.json");
187 let manifest: ModelManifest = serde_json::from_slice(
188 &fs::read(&manifest_path)
189 .map_err(|error| format!("read {}: {error}", manifest_path.display()))?,
190 )
191 .map_err(|error| format!("parse {}: {error}", manifest_path.display()))?;
192 if manifest.schema_version != 1 {
193 return Err(format!(
194 "unsupported model manifest schema version {}",
195 manifest.schema_version
196 ));
197 }
198 let artifact_name = manifest.artifact.path.as_str();
199 if artifact_name.is_empty() {
200 return Err("model artifact path is empty".to_owned());
201 }
202 let artifact_path = Path::new(artifact_name);
203 if artifact_path.is_absolute()
204 || artifact_path
205 .components()
206 .any(|component| matches!(component, std::path::Component::ParentDir))
207 {
208 return Err("model artifact path must stay inside the model package".to_owned());
209 }
210 let artifact = root.join(artifact_name);
211 let canonical_root = root
212 .canonicalize()
213 .map_err(|error| format!("resolve model package: {error}"))?;
214 let canonical_artifact = artifact
215 .canonicalize()
216 .map_err(|error| format!("resolve model artifact: {error}"))?;
217 if canonical_artifact.strip_prefix(&canonical_root).is_err() {
218 return Err("model artifact must be inside the model package".to_owned());
219 }
220
221 if !artifact.is_file() && !artifact.is_dir() {
222 return Err(format!(
223 "model artifact does not exist: {}",
224 artifact.display()
225 ));
226 }
227 Self::reject_symlinks(&artifact)
228 .map_err(|reason| format!("model artifact is unsafe: {reason}"))?;
229 Ok(Self {
230 manifest,
231 root,
232 artifact,
233 })
234 }
235
236 fn reject_symlinks(path: &Path) -> Result<(), String> {
237 let metadata = fs::symlink_metadata(path).map_err(|error| error.to_string())?;
238 if metadata.file_type().is_symlink() {
239 return Err("symbolic links are not allowed".to_owned());
240 }
241 if metadata.is_dir() {
242 for entry in fs::read_dir(path).map_err(|error| error.to_string())? {
243 Self::reject_symlinks(&entry.map_err(|error| error.to_string())?.path())?;
244 }
245 }
246 Ok(())
247 }
248
249 pub fn spec(&self) -> ModelSpec {
250 ModelSpec {
251 id: self.manifest.id.clone(),
252 version: self
253 .manifest
254 .model_version
255 .clone()
256 .or_else(|| self.manifest.version.clone()),
257 format: self.manifest.format.clone(),
258 location: ModelLocation::Path(self.artifact.display().to_string()),
259 metadata: self.manifest.metadata.clone(),
260 }
261 }
262
263 pub fn validate_artifact(&self) -> Result<(), CatalogError> {
264 if let Some(expected) = self.manifest.artifact.size_bytes {
265 let actual = artifact_size(&self.artifact)?;
266 if actual != expected {
267 return Err(CatalogError::ArtifactIntegrity {
268 model: self.manifest.id.clone(),
269 reason: format!("size mismatch: expected {expected}, got {actual}"),
270 });
271 }
272 }
273 if let Some(expected) = self.manifest.artifact.sha256.as_deref() {
274 let actual = sha256(&self.artifact)?;
275 if !expected.eq_ignore_ascii_case(&actual) {
276 return Err(CatalogError::ArtifactIntegrity {
277 model: self.manifest.id.clone(),
278 reason: format!("sha256 mismatch: expected {expected}, got {actual}"),
279 });
280 }
281 }
282 Ok(())
283 }
284}
285
286impl ModelSpec {
287 pub fn new(id: impl Into<String>, format: ModelFormat, location: ModelLocation) -> Self {
288 Self {
289 id: id.into(),
290 version: None,
291 format,
292 location,
293 metadata: ModelMetadata::new(),
294 }
295 }
296}
297
298fn artifact_size(path: &Path) -> Result<u64, CatalogError> {
299 if path.is_file() {
300 return Ok(fs::metadata(path)
301 .map_err(|error| CatalogError::Io(error.to_string()))?
302 .len());
303 }
304 let mut total = 0;
305 for entry in fs::read_dir(path).map_err(|error| CatalogError::Io(error.to_string()))? {
306 total += artifact_size(
307 &entry
308 .map_err(|error| CatalogError::Io(error.to_string()))?
309 .path(),
310 )?;
311 }
312 Ok(total)
313}
314
315fn sha256(path: &Path) -> Result<String, CatalogError> {
316 let mut digest = Sha256::new();
317 if path.is_file() {
318 digest.update(fs::read(path).map_err(|error| CatalogError::Io(error.to_string()))?);
319 } else {
320 let mut entries = fs::read_dir(path)
321 .map_err(|error| CatalogError::Io(error.to_string()))?
322 .collect::<Result<Vec<_>, _>>()
323 .map_err(|error| CatalogError::Io(error.to_string()))?;
324 entries.sort_by_key(|entry| entry.path());
325 for entry in entries {
326 digest.update(sha256(&entry.path())?.as_bytes());
327 }
328 }
329 Ok(format!("{:x}", digest.finalize()))
330}
331
332#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
334pub struct ModelDescriptor {
335 pub id: ModelId,
336 pub format: ModelFormat,
337 pub package_path: PathBuf,
338 pub manifest: ModelManifest,
339}
340
341impl ModelDescriptor {
342 pub fn spec(&self) -> ModelSpec {
343 ModelPackage {
344 manifest: self.manifest.clone(),
345 root: self.package_path.clone(),
346 artifact: self.package_path.join(&self.manifest.artifact.path),
347 }
348 .spec()
349 }
350}
351
352#[derive(Clone, Debug, PartialEq, Eq)]
353pub enum CatalogError {
354 Io(String),
355 InvalidIdentity(String),
356 InvalidPackage { path: PathBuf, reason: String },
357 ModelNotFound(String),
358 AmbiguousModel(String),
359 DuplicateIdentity(ModelId),
360 ArtifactIntegrity { model: String, reason: String },
361}
362
363impl std::fmt::Display for CatalogError {
364 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
365 match self {
366 Self::Io(reason) => write!(f, "catalog unavailable: {reason}"),
367 Self::InvalidIdentity(identity) => write!(f, "invalid model identity: {identity}"),
368 Self::InvalidPackage { path, reason } => {
369 write!(f, "invalid model package {}: {reason}", path.display())
370 }
371 Self::ModelNotFound(model) => write!(f, "model not found: {model}"),
372 Self::AmbiguousModel(model) => write!(f, "ambiguous model: {model}"),
373 Self::DuplicateIdentity(id) => write!(f, "duplicate model identity: {id}"),
374 Self::ArtifactIntegrity { model, reason } => {
375 write!(f, "artifact integrity failure for {model}: {reason}")
376 }
377 }
378 }
379}
380
381impl std::error::Error for CatalogError {}
382
383#[async_trait]
384pub trait ModelCatalog: Send + Sync {
385 async fn list(&self) -> Result<Vec<ModelDescriptor>, CatalogError>;
386 async fn resolve(&self, reference: &ModelReference) -> Result<ModelDescriptor, CatalogError>;
387 async fn validate(&self, id: &ModelId) -> Result<(), CatalogError>;
388 async fn refresh(&self) -> Result<(), CatalogError>;
389}
390
391#[derive(Clone, Debug)]
392pub struct FilesystemModelCatalog {
393 roots: Vec<PathBuf>,
394}
395
396impl FilesystemModelCatalog {
397 pub fn new(root: impl Into<PathBuf>) -> Self {
398 Self {
399 roots: vec![root.into()],
400 }
401 }
402
403 pub fn from_roots(roots: impl IntoIterator<Item = PathBuf>) -> Self {
404 Self {
405 roots: roots.into_iter().collect(),
406 }
407 }
408
409 pub fn roots(&self) -> &[PathBuf] {
410 &self.roots
411 }
412
413 fn discover(&self) -> Result<Vec<ModelDescriptor>, CatalogError> {
414 let mut packages = Vec::new();
415 for root in &self.roots {
416 discover_dirs(root, &mut packages)?;
417 }
418 packages.sort_by_key(|descriptor| {
419 (
420 descriptor.id.name.clone(),
421 descriptor.id.version.clone(),
422 format!("{:?}", descriptor.format),
423 descriptor.package_path.clone(),
424 )
425 });
426 for pair in packages.windows(2) {
427 if pair[0].id == pair[1].id {
428 return Err(CatalogError::DuplicateIdentity(pair[0].id.clone()));
429 }
430 }
431 Ok(packages)
432 }
433}
434
435fn discover_dirs(path: &Path, packages: &mut Vec<ModelDescriptor>) -> Result<(), CatalogError> {
436 if !path.is_dir() {
437 return Err(CatalogError::Io(format!(
438 "root is not a directory: {}",
439 path.display()
440 )));
441 }
442 if path.join("manifest.json").is_file() {
443 let package = ModelPackage::open(path).map_err(|reason| CatalogError::InvalidPackage {
444 path: path.to_path_buf(),
445 reason,
446 })?;
447 let version = package
448 .manifest
449 .model_version
450 .clone()
451 .or_else(|| package.manifest.version.clone())
452 .ok_or_else(|| CatalogError::InvalidPackage {
453 path: path.to_path_buf(),
454 reason: "model version is required".to_owned(),
455 })?;
456 let id = ModelId::new(package.manifest.id.clone(), version)?;
457 packages.push(ModelDescriptor {
458 id,
459 format: package.manifest.format.clone(),
460 package_path: path.to_path_buf(),
461 manifest: package.manifest,
462 });
463 return Ok(());
464 }
465 let mut entries = fs::read_dir(path)
466 .map_err(|error| CatalogError::Io(format!("read {}: {error}", path.display())))?
467 .collect::<Result<Vec<_>, _>>()
468 .map_err(|error| CatalogError::Io(error.to_string()))?;
469 entries.sort_by_key(|entry| entry.path());
470 for entry in entries {
471 if entry
472 .file_type()
473 .map_err(|error| CatalogError::Io(error.to_string()))?
474 .is_dir()
475 {
476 discover_dirs(&entry.path(), packages)?;
477 }
478 }
479 Ok(())
480}
481
482#[async_trait]
483impl ModelCatalog for FilesystemModelCatalog {
484 async fn list(&self) -> Result<Vec<ModelDescriptor>, CatalogError> {
485 self.discover()
486 }
487
488 async fn resolve(&self, reference: &ModelReference) -> Result<ModelDescriptor, CatalogError> {
489 let (name, version) = match reference {
490 ModelReference::Id { id, version } => (id.as_str(), version.as_deref()),
491 ModelReference::Spec(spec) => {
492 return Err(CatalogError::InvalidIdentity(spec.id.clone()))
493 }
494 };
495 if name.is_empty() || name.contains(['/', '\\', '@']) || name.contains("..") {
496 return Err(CatalogError::InvalidIdentity(name.to_owned()));
497 }
498 let matches = self
499 .discover()?
500 .into_iter()
501 .filter(|descriptor| {
502 descriptor.id.name == name
503 && version.is_none_or(|version| descriptor.id.version == version)
504 })
505 .collect::<Vec<_>>();
506 match matches.as_slice() {
507 [] => Err(CatalogError::ModelNotFound(match version {
508 Some(version) => format!("{name}@{version}"),
509 None => name.to_owned(),
510 })),
511 [descriptor] => Ok(descriptor.clone()),
512 _ => Err(CatalogError::AmbiguousModel(name.to_owned())),
513 }
514 }
515
516 async fn validate(&self, id: &ModelId) -> Result<(), CatalogError> {
517 let descriptor = self
518 .discover()?
519 .into_iter()
520 .find(|descriptor| descriptor.id == *id)
521 .ok_or_else(|| CatalogError::ModelNotFound(id.to_string()))?;
522 ModelPackage::open(&descriptor.package_path)
523 .map_err(|reason| CatalogError::InvalidPackage {
524 path: descriptor.package_path.clone(),
525 reason,
526 })?
527 .validate_artifact()
528 }
529
530 async fn refresh(&self) -> Result<(), CatalogError> {
531 self.discover().map(|_| ())
532 }
533}
534
535#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
537pub enum ModelReference {
538 Id { id: String, version: Option<String> },
539 Spec(ModelSpec),
540}
541
542impl ModelReference {
543 pub fn id(id: impl Into<String>, version: Option<String>) -> Self {
544 Self::Id {
545 id: id.into(),
546 version,
547 }
548 }
549
550 pub fn versioned(id: impl Into<String>, version: impl Into<String>) -> Self {
551 Self::id(id, Some(version.into()))
552 }
553
554 pub fn latest(id: impl Into<String>) -> Self {
555 Self::id(id, None)
556 }
557}
558
559impl From<ModelSpec> for ModelReference {
560 fn from(value: ModelSpec) -> Self {
561 Self::Spec(value)
562 }
563}
564
565#[derive(Clone, Debug, PartialEq, Eq)]
566pub struct ModelFetchRequest {
567 pub model: ModelId,
568 pub source: ModelSourceReference,
569}
570
571#[derive(Clone, Debug, PartialEq, Eq)]
572pub enum ModelSourceReference {
573 Path(PathBuf),
574 Uri(String),
575}
576
577#[derive(Clone, Debug)]
578pub struct AcquisitionConfig {
579 pub max_download_bytes: u64,
580 pub timeout_secs: u64,
581}
582
583impl Default for AcquisitionConfig {
584 fn default() -> Self {
585 Self {
586 max_download_bytes: 4 * 1024 * 1024 * 1024,
587 timeout_secs: 300,
588 }
589 }
590}
591
592#[derive(Clone, Debug, PartialEq, Eq)]
593pub struct ModelArtifact {
594 pub package_path: PathBuf,
595 pub bytes: u64,
596 pub sha256: String,
597}
598
599#[derive(Clone, Debug, PartialEq, Eq)]
600pub enum InstallMode {
601 KeepExisting,
602 Replace,
603}
604
605#[derive(Clone, Debug, PartialEq, Eq)]
606pub enum InstallResult {
607 Installed(ModelDescriptor),
608 AlreadyInstalled(ModelDescriptor),
609}
610
611#[derive(Clone, Debug, PartialEq, Eq)]
612pub enum AcquisitionError {
613 Io(String),
614 InvalidRequest(String),
615 Cancelled,
616 LimitExceeded { limit: u64, actual: u64 },
617 InvalidPackage { path: PathBuf, reason: String },
618 IdentityMismatch { requested: ModelId, found: ModelId },
619 AlreadyInstalled(ModelId),
620 Catalog(CatalogError),
621}
622
623impl std::fmt::Display for AcquisitionError {
624 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
625 match self {
626 Self::Io(reason) => write!(f, "acquisition I/O error: {reason}"),
627 Self::InvalidRequest(reason) => write!(f, "invalid acquisition request: {reason}"),
628 Self::Cancelled => write!(f, "model acquisition cancelled"),
629 Self::LimitExceeded { limit, actual } => {
630 write!(f, "model acquisition exceeds {limit} bytes (got {actual})")
631 }
632 Self::InvalidPackage { path, reason } => {
633 write!(f, "invalid model package {}: {reason}", path.display())
634 }
635 Self::IdentityMismatch { requested, found } => {
636 write!(f, "requested model {requested}, package contains {found}")
637 }
638 Self::AlreadyInstalled(id) => write!(f, "model already installed: {id}"),
639 Self::Catalog(error) => error.fmt(f),
640 }
641 }
642}
643
644impl std::error::Error for AcquisitionError {}
645
646#[async_trait]
647pub trait ModelSource: Send + Sync {
648 async fn fetch(
649 &self,
650 request: &ModelFetchRequest,
651 destination: &Path,
652 config: &AcquisitionConfig,
653 cancellation: Option<&CancellationToken>,
654 ) -> Result<ModelArtifact, AcquisitionError>;
655}
656
657#[derive(Clone, Debug, Default)]
658pub struct FileModelSource;
659
660impl FileModelSource {
661 pub fn new() -> Self {
662 Self
663 }
664}
665
666#[async_trait]
667impl ModelSource for FileModelSource {
668 async fn fetch(
669 &self,
670 request: &ModelFetchRequest,
671 destination: &Path,
672 config: &AcquisitionConfig,
673 cancellation: Option<&CancellationToken>,
674 ) -> Result<ModelArtifact, AcquisitionError> {
675 let source = match &request.source {
676 ModelSourceReference::Path(path) => path,
677 ModelSourceReference::Uri(_) => {
678 return Err(AcquisitionError::InvalidRequest(
679 "file source requires a filesystem path".to_owned(),
680 ))
681 }
682 };
683 if !source.is_dir() {
684 return Err(AcquisitionError::InvalidRequest(format!(
685 "model source is not a package directory: {}",
686 source.display()
687 )));
688 }
689 copy_package(source, destination, config.max_download_bytes, cancellation)?;
690 let package =
691 ModelPackage::open(destination).map_err(|reason| AcquisitionError::InvalidPackage {
692 path: destination.to_path_buf(),
693 reason,
694 })?;
695 package
696 .validate_artifact()
697 .map_err(AcquisitionError::Catalog)?;
698 let id = package_id(&package)?;
699 if id != request.model {
700 return Err(AcquisitionError::IdentityMismatch {
701 requested: request.model.clone(),
702 found: id,
703 });
704 }
705 Ok(ModelArtifact {
706 package_path: destination.to_path_buf(),
707 bytes: artifact_size(&package.artifact).map_err(|error| match error {
708 CatalogError::Io(reason) => AcquisitionError::Io(reason),
709 other => AcquisitionError::Catalog(other),
710 })?,
711 sha256: sha256(&package.artifact).map_err(|error| match error {
712 CatalogError::Io(reason) => AcquisitionError::Io(reason),
713 other => AcquisitionError::Catalog(other),
714 })?,
715 })
716 }
717}
718
719#[derive(Clone, Debug)]
720pub struct HttpModelSource {
721 client: reqwest::Client,
722 allow_insecure_http: bool,
723}
724
725impl HttpModelSource {
726 pub fn new() -> Result<Self, AcquisitionError> {
727 let client = reqwest::Client::builder()
728 .redirect(reqwest::redirect::Policy::limited(5))
729 .build()
730 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
731 Ok(Self {
732 client,
733 allow_insecure_http: false,
734 })
735 }
736
737 pub fn allow_insecure_http(mut self, allow: bool) -> Self {
738 self.allow_insecure_http = allow;
739 self
740 }
741}
742
743#[async_trait]
744impl ModelSource for HttpModelSource {
745 async fn fetch(
746 &self,
747 request: &ModelFetchRequest,
748 destination: &Path,
749 config: &AcquisitionConfig,
750 cancellation: Option<&CancellationToken>,
751 ) -> Result<ModelArtifact, AcquisitionError> {
752 let base = match &request.source {
753 ModelSourceReference::Uri(uri) => uri.trim_end_matches('/').to_owned(),
754 ModelSourceReference::Path(_) => {
755 return Err(AcquisitionError::InvalidRequest(
756 "HTTP source requires a URI".to_owned(),
757 ))
758 }
759 };
760 let manifest_url = if base.ends_with("manifest.json") {
761 base
762 } else {
763 format!("{base}/manifest.json")
764 };
765 validate_http_uri(&manifest_url, self.allow_insecure_http)?;
766 let response = tokio::time::timeout(
767 std::time::Duration::from_secs(config.timeout_secs),
768 self.client.get(&manifest_url).send(),
769 )
770 .await
771 .map_err(|_| AcquisitionError::Io("manifest request timed out".to_owned()))?
772 .map_err(|error| AcquisitionError::Io(error.to_string()))?
773 .error_for_status()
774 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
775 let manifest: ModelManifest =
776 response
777 .json()
778 .await
779 .map_err(|error| AcquisitionError::InvalidPackage {
780 path: destination.to_path_buf(),
781 reason: error.to_string(),
782 })?;
783 let version = manifest
784 .model_version
785 .clone()
786 .or_else(|| manifest.version.clone())
787 .ok_or_else(|| AcquisitionError::InvalidPackage {
788 path: destination.to_path_buf(),
789 reason: "model version is required".to_owned(),
790 })?;
791 let found =
792 ModelId::new(manifest.id.clone(), version).map_err(AcquisitionError::Catalog)?;
793 if found != request.model {
794 return Err(AcquisitionError::IdentityMismatch {
795 requested: request.model.clone(),
796 found,
797 });
798 }
799 let artifact_path = Path::new(&manifest.artifact.path);
800 if artifact_path.is_absolute()
801 || artifact_path
802 .components()
803 .any(|component| matches!(component, std::path::Component::ParentDir))
804 {
805 return Err(AcquisitionError::InvalidPackage {
806 path: destination.to_path_buf(),
807 reason: "artifact path must stay inside the package".to_owned(),
808 });
809 }
810 let artifact_url = format!(
811 "{}/{}",
812 manifest_url
813 .trim_end_matches("manifest.json")
814 .trim_end_matches('/'),
815 manifest.artifact.path
816 );
817 validate_http_uri(&artifact_url, self.allow_insecure_http)?;
818 let response = self
819 .client
820 .get(artifact_url)
821 .send()
822 .await
823 .map_err(|error| AcquisitionError::Io(error.to_string()))?
824 .error_for_status()
825 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
826 if response
827 .content_length()
828 .is_some_and(|size| size > config.max_download_bytes)
829 {
830 return Err(AcquisitionError::LimitExceeded {
831 limit: config.max_download_bytes,
832 actual: response.content_length().unwrap_or_default(),
833 });
834 }
835 fs::create_dir_all(
836 destination.join(artifact_path.parent().unwrap_or_else(|| Path::new(""))),
837 )
838 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
839 fs::write(
840 destination.join(artifact_path),
841 download_body(response, config, cancellation).await?,
842 )
843 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
844 fs::write(
845 destination.join("manifest.json"),
846 serde_json::to_vec(&manifest).map_err(|error| AcquisitionError::InvalidPackage {
847 path: destination.to_path_buf(),
848 reason: error.to_string(),
849 })?,
850 )
851 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
852 let package =
853 ModelPackage::open(destination).map_err(|reason| AcquisitionError::InvalidPackage {
854 path: destination.to_path_buf(),
855 reason,
856 })?;
857 package
858 .validate_artifact()
859 .map_err(AcquisitionError::Catalog)?;
860 Ok(ModelArtifact {
861 package_path: destination.to_path_buf(),
862 bytes: artifact_size(&package.artifact).map_err(AcquisitionError::Catalog)?,
863 sha256: sha256(&package.artifact).map_err(AcquisitionError::Catalog)?,
864 })
865 }
866}
867
868fn validate_http_uri(uri: &str, allow_insecure_http: bool) -> Result<(), AcquisitionError> {
869 let parsed = reqwest::Url::parse(uri)
870 .map_err(|error| AcquisitionError::InvalidRequest(error.to_string()))?;
871 if parsed.scheme() != "https" && !(allow_insecure_http && parsed.scheme() == "http") {
872 return Err(AcquisitionError::InvalidRequest(
873 "model acquisition requires HTTPS".to_owned(),
874 ));
875 }
876 Ok(())
877}
878
879async fn download_body(
880 mut response: reqwest::Response,
881 config: &AcquisitionConfig,
882 cancellation: Option<&CancellationToken>,
883) -> Result<Vec<u8>, AcquisitionError> {
884 let mut body = Vec::new();
885 while let Some(chunk) = response
886 .chunk()
887 .await
888 .map_err(|error| AcquisitionError::Io(error.to_string()))?
889 {
890 if cancellation.is_some_and(CancellationToken::is_cancelled) {
891 return Err(AcquisitionError::Cancelled);
892 }
893 if body.len() as u64 + chunk.len() as u64 > config.max_download_bytes {
894 return Err(AcquisitionError::LimitExceeded {
895 limit: config.max_download_bytes,
896 actual: body.len() as u64 + chunk.len() as u64,
897 });
898 }
899 body.extend_from_slice(&chunk);
900 }
901 Ok(body)
902}
903
904#[derive(Clone)]
905pub struct ModelInstaller {
906 root: PathBuf,
907 catalog: Option<Arc<dyn ModelCatalog>>,
908 config: AcquisitionConfig,
909}
910
911impl ModelInstaller {
912 pub fn new(root: impl Into<PathBuf>) -> Self {
913 Self {
914 root: root.into(),
915 catalog: None,
916 config: AcquisitionConfig::default(),
917 }
918 }
919
920 pub fn with_catalog<C: ModelCatalog + 'static>(mut self, catalog: Arc<C>) -> Self {
921 self.catalog = Some(catalog);
922 self
923 }
924
925 pub fn with_config(mut self, config: AcquisitionConfig) -> Self {
926 self.config = config;
927 self
928 }
929
930 pub async fn install<S: ModelSource>(
931 &self,
932 source: &S,
933 request: &ModelFetchRequest,
934 mode: InstallMode,
935 cancellation: Option<&CancellationToken>,
936 ) -> Result<InstallResult, AcquisitionError> {
937 request
938 .model
939 .validate()
940 .map_err(AcquisitionError::Catalog)?;
941 if let Some(catalog) = &self.catalog {
942 if let Ok(existing) = catalog
943 .resolve(&ModelReference::id(
944 request.model.name.clone(),
945 Some(request.model.version.clone()),
946 ))
947 .await
948 {
949 catalog
950 .validate(&existing.id)
951 .await
952 .map_err(AcquisitionError::Catalog)?;
953 if mode == InstallMode::KeepExisting {
954 return Ok(InstallResult::AlreadyInstalled(existing));
955 }
956 }
957 }
958 if let Some(token) = cancellation {
959 if token.is_cancelled() {
960 return Err(AcquisitionError::Cancelled);
961 }
962 }
963 fs::create_dir_all(&self.root).map_err(|error| AcquisitionError::Io(error.to_string()))?;
964 let staging_root = self.root.join(".staging");
965 fs::create_dir_all(&staging_root)
966 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
967 let staging = staging_root.join(format!(
968 "{}-{}-{}",
969 request.model.name,
970 request.model.version,
971 std::process::id()
972 ));
973 if staging.exists() {
974 fs::remove_dir_all(&staging)
975 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
976 }
977 fs::create_dir_all(&staging).map_err(|error| AcquisitionError::Io(error.to_string()))?;
978 let result = async {
979 source
980 .fetch(request, &staging, &self.config, cancellation)
981 .await?;
982 if cancellation.is_some_and(CancellationToken::is_cancelled) {
983 return Err(AcquisitionError::Cancelled);
984 }
985 let package = ModelPackage::open(&staging).map_err(|reason| {
986 AcquisitionError::InvalidPackage {
987 path: staging.clone(),
988 reason,
989 }
990 })?;
991 package
992 .validate_artifact()
993 .map_err(AcquisitionError::Catalog)?;
994 let found = package_id(&package)?;
995 if found != request.model {
996 return Err(AcquisitionError::IdentityMismatch {
997 requested: request.model.clone(),
998 found,
999 });
1000 }
1001 let final_path = self
1002 .root
1003 .join(&request.model.name)
1004 .join(&request.model.version);
1005 let parent = final_path.parent().expect("model version has a parent");
1006 fs::create_dir_all(parent).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1007 if final_path.exists() {
1008 if mode == InstallMode::Replace {
1009 let backup = parent.join(format!(".replace-{}", std::process::id()));
1010 fs::rename(&final_path, &backup)
1011 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1012 if let Err(error) = fs::rename(&staging, &final_path) {
1013 let _ = fs::rename(&backup, &final_path);
1014 return Err(AcquisitionError::Io(error.to_string()));
1015 }
1016 let _ = fs::remove_dir_all(backup);
1017 } else {
1018 return Err(AcquisitionError::AlreadyInstalled(request.model.clone()));
1019 }
1020 } else {
1021 fs::rename(&staging, &final_path)
1022 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1023 }
1024 let catalog = self.catalog.as_ref().ok_or_else(|| {
1025 AcquisitionError::InvalidRequest(
1026 "a catalog is required to finish installation".to_owned(),
1027 )
1028 })?;
1029 catalog.refresh().await.map_err(AcquisitionError::Catalog)?;
1030 let descriptor = catalog
1031 .resolve(&ModelReference::id(
1032 request.model.name.clone(),
1033 Some(request.model.version.clone()),
1034 ))
1035 .await
1036 .map_err(AcquisitionError::Catalog)?;
1037 Ok(InstallResult::Installed(descriptor))
1038 }
1039 .await;
1040 if staging.exists() {
1041 let _ = fs::remove_dir_all(&staging);
1042 }
1043 result
1044 }
1045}
1046
1047fn package_id(package: &ModelPackage) -> Result<ModelId, AcquisitionError> {
1048 let version = package
1049 .manifest
1050 .model_version
1051 .clone()
1052 .or_else(|| package.manifest.version.clone())
1053 .ok_or_else(|| AcquisitionError::InvalidPackage {
1054 path: package.root.clone(),
1055 reason: "model version is required".to_owned(),
1056 })?;
1057 ModelId::new(package.manifest.id.clone(), version).map_err(AcquisitionError::Catalog)
1058}
1059
1060fn copy_package(
1061 source: &Path,
1062 destination: &Path,
1063 limit: u64,
1064 cancellation: Option<&CancellationToken>,
1065) -> Result<(), AcquisitionError> {
1066 let mut bytes = 0;
1067 copy_package_entry(source, destination, &mut bytes, limit, cancellation)?;
1068 Ok(())
1069}
1070
1071fn copy_package_entry(
1072 source: &Path,
1073 destination: &Path,
1074 bytes: &mut u64,
1075 limit: u64,
1076 cancellation: Option<&CancellationToken>,
1077) -> Result<(), AcquisitionError> {
1078 if cancellation.is_some_and(CancellationToken::is_cancelled) {
1079 return Err(AcquisitionError::Cancelled);
1080 }
1081 let metadata =
1082 fs::symlink_metadata(source).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1083 if metadata.file_type().is_symlink() {
1084 return Err(AcquisitionError::InvalidPackage {
1085 path: source.to_path_buf(),
1086 reason: "symbolic links are not allowed".to_owned(),
1087 });
1088 }
1089 if metadata.is_dir() {
1090 fs::create_dir_all(destination).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1091 let mut entries = fs::read_dir(source)
1092 .map_err(|error| AcquisitionError::Io(error.to_string()))?
1093 .collect::<Result<Vec<_>, _>>()
1094 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1095 entries.sort_by_key(|entry| entry.path());
1096 for entry in entries {
1097 copy_package_entry(
1098 &entry.path(),
1099 &destination.join(entry.file_name()),
1100 bytes,
1101 limit,
1102 cancellation,
1103 )?;
1104 }
1105 } else if metadata.is_file() {
1106 *bytes = bytes.saturating_add(metadata.len());
1107 if *bytes > limit {
1108 return Err(AcquisitionError::LimitExceeded {
1109 limit,
1110 actual: *bytes,
1111 });
1112 }
1113 fs::copy(source, destination).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1114 } else {
1115 return Err(AcquisitionError::InvalidPackage {
1116 path: source.to_path_buf(),
1117 reason: "unsupported filesystem entry".to_owned(),
1118 });
1119 }
1120 Ok(())
1121}
1122
1123#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1126pub struct RegisteredModel {
1127 pub name: String,
1128 pub revision: String,
1129 pub source: String,
1130 pub backend: String,
1131 pub runtime_requirement: String,
1132 pub format: ModelFormat,
1133 #[serde(default)]
1134 pub platforms: Vec<String>,
1135 #[serde(default)]
1136 pub architectures: Vec<String>,
1137 pub artifact_path: String,
1138 pub files: Vec<RegisteredModelFile>,
1139}
1140
1141#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1142pub struct RegisteredModelFile {
1143 pub path: String,
1144 pub sha256: String,
1145}
1146
1147pub const INSTALLATION_MANIFEST_FILE: &str = "installation.json";
1148
1149#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1150#[serde(rename_all = "snake_case")]
1151pub enum CompiledStatus {
1152 Ready,
1153 Missing,
1154 Corrupt,
1155 Unsupported,
1156}
1157
1158#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1159pub struct CompiledArtifactManifest {
1160 pub path: PathBuf,
1161 pub identity: String,
1162}
1163
1164#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1165pub struct InstallationManifest {
1166 pub schema_version: u32,
1167 pub model: String,
1168 pub model_revision: String,
1169 pub model_checksum: String,
1170 pub runtime_version: String,
1171 pub runtime_requirement: String,
1172 pub backend: String,
1173 pub os: String,
1174 pub architecture: String,
1175 pub installed_at_unix_seconds: u64,
1176 pub compiled_status: CompiledStatus,
1177 pub compiled_artifact: Option<CompiledArtifactManifest>,
1178}
1179
1180impl InstallationManifest {
1181 pub fn read(package: &Path) -> Result<Self, AcquisitionError> {
1182 let path = package.join(INSTALLATION_MANIFEST_FILE);
1183 let bytes = fs::read(&path).map_err(|error| AcquisitionError::InvalidPackage {
1184 path: path.clone(),
1185 reason: format!(
1186 "installation is not ready: {error}; run `ml-runtime model doctor {}`",
1187 package
1188 .parent()
1189 .and_then(Path::file_name)
1190 .and_then(|name| name.to_str())
1191 .unwrap_or("MODEL")
1192 ),
1193 })?;
1194 serde_json::from_slice(&bytes).map_err(|error| AcquisitionError::InvalidPackage {
1195 path,
1196 reason: format!("invalid installation manifest: {error}"),
1197 })
1198 }
1199
1200 pub fn write_atomic(&self, package: &Path) -> Result<(), AcquisitionError> {
1201 let destination = package.join(INSTALLATION_MANIFEST_FILE);
1202 let temporary = package.join(format!(".{INSTALLATION_MANIFEST_FILE}.tmp"));
1203 let bytes = serde_json::to_vec_pretty(self)
1204 .map_err(|error| AcquisitionError::InvalidRequest(error.to_string()))?;
1205 let mut output = fs::File::create(&temporary)
1206 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1207 output
1208 .write_all(&bytes)
1209 .and_then(|()| output.sync_all())
1210 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1211 fs::rename(&temporary, &destination)
1212 .map_err(|error| AcquisitionError::Io(error.to_string()))
1213 }
1214}
1215
1216#[derive(Clone, Debug, Default)]
1217pub struct BuiltinModelRegistry;
1218
1219impl BuiltinModelRegistry {
1220 pub fn list(&self) -> Vec<RegisteredModel> {
1221 self.all()
1222 .into_iter()
1223 .filter(|model| model.supports_platform(std::env::consts::OS, std::env::consts::ARCH))
1224 .collect()
1225 }
1226
1227 pub fn resolve(&self, name: &str) -> Result<RegisteredModel, AcquisitionError> {
1228 self.resolve_for(name, std::env::consts::OS, std::env::consts::ARCH)
1229 }
1230
1231 pub fn resolve_for(
1232 &self,
1233 name: &str,
1234 platform: &str,
1235 architecture: &str,
1236 ) -> Result<RegisteredModel, AcquisitionError> {
1237 let registrations: Vec<_> = self
1238 .all()
1239 .into_iter()
1240 .filter(|model| model.name == name)
1241 .collect();
1242 if registrations.is_empty() {
1243 return Err(AcquisitionError::InvalidRequest(format!(
1244 "unknown registered model {name:?}"
1245 )));
1246 }
1247 registrations
1248 .iter()
1249 .find(|model| model.supports_platform(platform, architecture))
1250 .cloned()
1251 .ok_or_else(|| AcquisitionError::InvalidRequest(format!(
1252 "registered model {name:?} has no backend for platform {platform}/{architecture}; available variants: {}",
1253 registrations
1254 .iter()
1255 .map(|model| format!("{} ({}/{})", model.backend, model.platforms.join("|"), model.architectures.join("|")))
1256 .collect::<Vec<_>>()
1257 .join(", ")
1258 )))
1259 }
1260
1261 fn all(&self) -> Vec<RegisteredModel> {
1262 vec![laya_coreml_registration(), laya_onnx_registration()]
1263 }
1264}
1265
1266impl RegisteredModel {
1267 pub fn supports_platform(&self, platform: &str, architecture: &str) -> bool {
1268 (self.platforms.is_empty() || self.platforms.iter().any(|value| value == platform))
1269 && (self.architectures.is_empty()
1270 || self.architectures.iter().any(|value| value == architecture))
1271 }
1272}
1273
1274fn laya_coreml_registration() -> RegisteredModel {
1275 const REVISION: &str = "fff78b2d9750c6b748fe8c90fcbf8bed0a1522a9";
1276 let files = [
1277 (
1278 "coreml_config.json",
1279 "990b99a736f64c87da57b203d7953c4c1c79c18b615580db894e9c24bda42ab5",
1280 ),
1281 (
1282 "validation.json",
1283 "709e1a0ac95a7bf73df0b5a8582423c9f40c80a1b4edd3499a77a1ac2ac39731",
1284 ),
1285 (
1286 "encoder/config.json",
1287 "bf3ab80598fdccf414855a2ce80f22859e4492d06ca8a62ddd1cfb63972f8979",
1288 ),
1289 (
1290 "rl_agent_config.json",
1291 "ae287b56bbcf5f8c4f4541ae9dfd00c914c4c48b940b8398c3058af37ba92bbd",
1292 ),
1293 (
1294 "tokenizer/tokenizer.json",
1295 "6c8aaa9a542084f2457eab775d4eeb51f92a70c0fd9de28d5edb0ddec3c08d30",
1296 ),
1297 (
1298 "tokenizer/tokenizer_config.json",
1299 "50044de60daaa73df97d262e15a40d4faf0160e7d742df64b377877a1320dd12",
1300 ),
1301 (
1302 "model.mlpackage/Manifest.json",
1303 "41bab6e532f727e8809c76906f41026a48ef9b276c56068b3d68270a13981e20",
1304 ),
1305 (
1306 "model.mlpackage/Data/com.apple.CoreML/model.mlmodel",
1307 "dc6a6383ad4a2f04f7525924b0dfb830429dedc44387f143a2f87782e39aeab0",
1308 ),
1309 (
1310 "model.mlpackage/Data/com.apple.CoreML/weights/weight.bin",
1311 "5872b9f6530c20a845b69c0cb75aa141e9c89ffdd5f36529c3708cec9b7a7a83",
1312 ),
1313 ]
1314 .into_iter()
1315 .map(|(path, sha256)| RegisteredModelFile {
1316 path: path.to_owned(),
1317 sha256: sha256.to_owned(),
1318 })
1319 .collect();
1320 RegisteredModel {
1321 name: "laya".to_owned(),
1322 revision: REVISION.to_owned(),
1323 source: format!("https://huggingface.co/aac6fef/laya-coreml/resolve/{REVISION}"),
1324 backend: "coreml".to_owned(),
1325 runtime_requirement: ">=0.1.0".to_owned(),
1326 format: ModelFormat::CoreMl,
1327 platforms: vec!["macos".to_owned()],
1328 architectures: vec!["aarch64".to_owned()],
1329 artifact_path: "model.mlpackage".to_owned(),
1330 files,
1331 }
1332}
1333
1334fn laya_onnx_registration() -> RegisteredModel {
1335 const REVISION: &str = "68f27dfe5a27a54fb2b1fefc432f43f972e90868";
1336 let files = [
1337 (
1338 "laya.onnx",
1339 "a874eb254b58b0fcb1e7ad56fbb188c29d64e08c9a46b689433e1f52c66dba1e",
1340 ),
1341 (
1342 "laya.onnx.data",
1343 "487746363a8da57bcadb4345352997d22a0fb90d70aa22c6856668d023242aba",
1344 ),
1345 (
1346 "laya_config.json",
1347 "5049005dc6ae3ca5e82cc7d85c421357d5c543817300c8e8c5281ddbc69bb561",
1348 ),
1349 (
1350 "tokenizer/tokenizer.json",
1351 "6c8aaa9a542084f2457eab775d4eeb51f92a70c0fd9de28d5edb0ddec3c08d30",
1352 ),
1353 (
1354 "tokenizer/tokenizer_config.json",
1355 "50044de60daaa73df97d262e15a40d4faf0160e7d742df64b377877a1320dd12",
1356 ),
1357 ]
1358 .into_iter()
1359 .map(|(path, sha256)| RegisteredModelFile {
1360 path: path.to_owned(),
1361 sha256: sha256.to_owned(),
1362 })
1363 .collect();
1364 RegisteredModel {
1365 name: "laya".to_owned(),
1366 revision: REVISION.to_owned(),
1367 source: format!("https://huggingface.co/receptron/laya-onnx/resolve/{REVISION}"),
1368 backend: "onnx".to_owned(),
1369 runtime_requirement: ">=0.2.2".to_owned(),
1370 format: ModelFormat::Onnx,
1371 platforms: vec!["linux".to_owned()],
1372 architectures: vec!["x86_64".to_owned(), "aarch64".to_owned()],
1373 artifact_path: "laya.onnx".to_owned(),
1374 files,
1375 }
1376}
1377
1378pub fn default_model_root() -> Result<PathBuf, AcquisitionError> {
1379 if let Some(root) = std::env::var_os("ML_RUNTIME_MODEL_DIR") {
1380 return Ok(PathBuf::from(root));
1381 }
1382 #[cfg(target_os = "windows")]
1383 if let Some(root) = std::env::var_os("LOCALAPPDATA") {
1384 return Ok(PathBuf::from(root).join("ml-runtime/models"));
1385 }
1386 let home = std::env::var_os("HOME").ok_or_else(|| {
1387 AcquisitionError::InvalidRequest(
1388 "cannot determine model directory; set ML_RUNTIME_MODEL_DIR".to_owned(),
1389 )
1390 })?;
1391 #[cfg(target_os = "windows")]
1392 return Ok(PathBuf::from(home).join("AppData/Local/ml-runtime/models"));
1393 #[cfg(target_os = "macos")]
1394 return Ok(PathBuf::from(home).join("Library/Application Support/ml-runtime/models"));
1395 #[cfg(not(any(target_os = "macos", target_os = "windows")))]
1396 Ok(PathBuf::from(home).join(".local/share/ml-runtime/models"))
1397}
1398
1399#[derive(Clone, Debug, PartialEq, Eq)]
1400pub struct RegisteredInstallResult {
1401 pub package_path: PathBuf,
1402 pub already_installed: bool,
1403}
1404
1405pub struct RegisteredModelInstaller {
1406 root: PathBuf,
1407 client: reqwest::Client,
1408 config: AcquisitionConfig,
1409}
1410
1411impl RegisteredModelInstaller {
1412 pub fn new(root: impl Into<PathBuf>) -> Result<Self, AcquisitionError> {
1413 let client = reqwest::Client::builder()
1414 .redirect(reqwest::redirect::Policy::limited(10))
1415 .build()
1416 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1417 Ok(Self {
1418 root: root.into(),
1419 client,
1420 config: AcquisitionConfig::default(),
1421 })
1422 }
1423
1424 pub fn with_config(mut self, config: AcquisitionConfig) -> Self {
1425 self.config = config;
1426 self
1427 }
1428
1429 pub fn installed_path(&self, model: &RegisteredModel) -> PathBuf {
1430 self.root.join(&model.name).join(&model.revision)
1431 }
1432
1433 pub fn validate(
1434 &self,
1435 model: &RegisteredModel,
1436 package: &Path,
1437 ) -> Result<(), AcquisitionError> {
1438 validate_registration(model)?;
1439 let manifest =
1440 ModelPackage::open(package).map_err(|reason| AcquisitionError::InvalidPackage {
1441 path: package.to_path_buf(),
1442 reason,
1443 })?;
1444 let id = package_id(&manifest)?;
1445 let expected =
1446 ModelId::new(&model.name, &model.revision).map_err(AcquisitionError::Catalog)?;
1447 if id != expected || manifest.manifest.format != model.format {
1448 return Err(AcquisitionError::IdentityMismatch {
1449 requested: expected,
1450 found: id,
1451 });
1452 }
1453 if manifest.manifest.artifact.path != model.artifact_path {
1454 return Err(AcquisitionError::InvalidPackage {
1455 path: package.to_path_buf(),
1456 reason: format!(
1457 "registered artifact path must be {:?}, got {:?}",
1458 model.artifact_path, manifest.manifest.artifact.path
1459 ),
1460 });
1461 }
1462 for (key, expected) in [
1463 ("backend", model.backend.as_str()),
1464 ("platforms", model.platforms.join(",").as_str()),
1465 ("architectures", model.architectures.join(",").as_str()),
1466 ] {
1467 if manifest.manifest.metadata.get(key).map(String::as_str) != Some(expected) {
1468 return Err(AcquisitionError::InvalidPackage {
1469 path: package.join("manifest.json"),
1470 reason: format!("registered metadata {key:?} is missing or incorrect"),
1471 });
1472 }
1473 }
1474 if !runtime_requirement_satisfied(&model.runtime_requirement, env!("CARGO_PKG_VERSION")) {
1475 return Err(AcquisitionError::InvalidPackage {
1476 path: package.to_path_buf(),
1477 reason: format!(
1478 "model requires runtime {}, current runtime is {}",
1479 model.runtime_requirement,
1480 env!("CARGO_PKG_VERSION")
1481 ),
1482 });
1483 }
1484 for file in &model.files {
1485 let path = safe_registered_path(package, &file.path)?;
1486 let actual = sha256_file_streaming(&path)?;
1487 if !actual.eq_ignore_ascii_case(&file.sha256) {
1488 return Err(AcquisitionError::InvalidPackage {
1489 path,
1490 reason: format!("sha256 mismatch: expected {}, got {actual}", file.sha256),
1491 });
1492 }
1493 }
1494 Ok(())
1495 }
1496
1497 pub async fn install(
1498 &self,
1499 model: &RegisteredModel,
1500 source_override: Option<&str>,
1501 mode: InstallMode,
1502 cancellation: Option<&CancellationToken>,
1503 ) -> Result<RegisteredInstallResult, AcquisitionError> {
1504 validate_registration(model)?;
1505 if !model.supports_platform(std::env::consts::OS, std::env::consts::ARCH) {
1506 return Err(AcquisitionError::InvalidRequest(format!(
1507 "model {} backend {} does not support {}/{}",
1508 model.name,
1509 model.backend,
1510 std::env::consts::OS,
1511 std::env::consts::ARCH
1512 )));
1513 }
1514 let final_path = self.installed_path(model);
1515 if final_path.exists() && mode == InstallMode::KeepExisting {
1516 self.validate(model, &final_path)?;
1517 return Ok(RegisteredInstallResult {
1518 package_path: final_path,
1519 already_installed: true,
1520 });
1521 }
1522 fs::create_dir_all(&self.root).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1523 let staging_root = self.root.join(".staging");
1524 fs::create_dir_all(&staging_root)
1525 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1526 let staging = staging_root.join(format!("{}-{}", model.name, std::process::id()));
1527 if staging.exists() {
1528 fs::remove_dir_all(&staging)
1529 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1530 }
1531 fs::create_dir_all(&staging).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1532 let source = source_override.unwrap_or(&model.source);
1533 let result = async {
1534 let mut downloaded = 0_u64;
1535 if source.starts_with("https://") || source.starts_with("http://") {
1536 validate_http_uri(source, false)?;
1537 for file in &model.files {
1538 if cancellation.is_some_and(CancellationToken::is_cancelled) {
1539 return Err(AcquisitionError::Cancelled);
1540 }
1541 let destination = safe_registered_path(&staging, &file.path)?;
1542 if let Some(parent) = destination.parent() {
1543 fs::create_dir_all(parent)
1544 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1545 }
1546 self.download_file(
1547 &format!("{}/{}", source.trim_end_matches('/'), file.path),
1548 &destination,
1549 &mut downloaded,
1550 cancellation,
1551 )
1552 .await?;
1553 }
1554 } else {
1555 let source = Path::new(source);
1556 if !source.is_dir() {
1557 return Err(AcquisitionError::InvalidRequest(format!(
1558 "registered model source is not a directory: {}",
1559 source.display()
1560 )));
1561 }
1562 for file in &model.files {
1563 let from = safe_registered_path(source, &file.path)?;
1564 let to = safe_registered_path(&staging, &file.path)?;
1565 if let Some(parent) = to.parent() {
1566 fs::create_dir_all(parent)
1567 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1568 }
1569 let size = fs::metadata(&from)
1570 .map_err(|error| AcquisitionError::Io(error.to_string()))?
1571 .len();
1572 downloaded = downloaded.saturating_add(size);
1573 if downloaded > self.config.max_download_bytes {
1574 return Err(AcquisitionError::LimitExceeded {
1575 limit: self.config.max_download_bytes,
1576 actual: downloaded,
1577 });
1578 }
1579 fs::copy(&from, &to)
1580 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1581 }
1582 }
1583 write_registered_manifest(&staging, model)?;
1584 self.validate(model, &staging)?;
1585 let parent = final_path.parent().expect("registered model has parent");
1586 fs::create_dir_all(parent).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1587 if final_path.exists() {
1588 if mode != InstallMode::Replace {
1589 return Err(AcquisitionError::AlreadyInstalled(
1590 ModelId::new(&model.name, &model.revision)
1591 .map_err(AcquisitionError::Catalog)?,
1592 ));
1593 }
1594 let backup = parent.join(format!(".replace-{}", std::process::id()));
1595 fs::rename(&final_path, &backup)
1596 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1597 if let Err(error) = fs::rename(&staging, &final_path) {
1598 let _ = fs::rename(&backup, &final_path);
1599 return Err(AcquisitionError::Io(error.to_string()));
1600 }
1601 let _ = fs::remove_dir_all(backup);
1602 } else {
1603 fs::rename(&staging, &final_path)
1604 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1605 }
1606 Ok(RegisteredInstallResult {
1607 package_path: final_path.clone(),
1608 already_installed: false,
1609 })
1610 }
1611 .await;
1612 if staging.exists() {
1613 let _ = fs::remove_dir_all(staging);
1614 }
1615 result
1616 }
1617
1618 async fn download_file(
1619 &self,
1620 url: &str,
1621 destination: &Path,
1622 downloaded: &mut u64,
1623 cancellation: Option<&CancellationToken>,
1624 ) -> Result<(), AcquisitionError> {
1625 validate_http_uri(url, false)?;
1626 let mut response = tokio::time::timeout(
1627 std::time::Duration::from_secs(self.config.timeout_secs),
1628 self.client.get(url).send(),
1629 )
1630 .await
1631 .map_err(|_| AcquisitionError::Io(format!("download timed out: {url}")))?
1632 .map_err(|error| AcquisitionError::Io(error.to_string()))?
1633 .error_for_status()
1634 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1635 let mut output = fs::File::create(destination)
1636 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1637 while let Some(chunk) = response
1638 .chunk()
1639 .await
1640 .map_err(|error| AcquisitionError::Io(error.to_string()))?
1641 {
1642 if cancellation.is_some_and(CancellationToken::is_cancelled) {
1643 return Err(AcquisitionError::Cancelled);
1644 }
1645 *downloaded = downloaded.saturating_add(chunk.len() as u64);
1646 if *downloaded > self.config.max_download_bytes {
1647 return Err(AcquisitionError::LimitExceeded {
1648 limit: self.config.max_download_bytes,
1649 actual: *downloaded,
1650 });
1651 }
1652 output
1653 .write_all(&chunk)
1654 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1655 }
1656 output
1657 .sync_all()
1658 .map_err(|error| AcquisitionError::Io(error.to_string()))
1659 }
1660}
1661
1662fn validate_registration(model: &RegisteredModel) -> Result<(), AcquisitionError> {
1663 if model.name.is_empty()
1664 || model.revision.is_empty()
1665 || model.source.is_empty()
1666 || model.backend.is_empty()
1667 || model.artifact_path.is_empty()
1668 || model.platforms.iter().any(String::is_empty)
1669 || model.architectures.iter().any(String::is_empty)
1670 {
1671 return Err(AcquisitionError::InvalidRequest(
1672 "registered model metadata is incomplete".to_owned(),
1673 ));
1674 }
1675 let mut paths = std::collections::BTreeSet::new();
1676 for file in &model.files {
1677 if !paths.insert(&file.path)
1678 || file.sha256.len() != 64
1679 || !file.sha256.bytes().all(|byte| byte.is_ascii_hexdigit())
1680 {
1681 return Err(AcquisitionError::InvalidRequest(format!(
1682 "registered file {:?} has a duplicate path or invalid SHA-256",
1683 file.path
1684 )));
1685 }
1686 }
1687 if !paths.contains(&model.artifact_path)
1688 && !paths
1689 .iter()
1690 .any(|path| path.starts_with(&format!("{}/", model.artifact_path)))
1691 {
1692 return Err(AcquisitionError::InvalidRequest(format!(
1693 "registered artifact {:?} has no checksummed file entry",
1694 model.artifact_path
1695 )));
1696 }
1697 Ok(())
1698}
1699
1700fn safe_registered_path(root: &Path, relative: &str) -> Result<PathBuf, AcquisitionError> {
1701 let relative = Path::new(relative);
1702 if relative.is_absolute()
1703 || relative
1704 .components()
1705 .any(|component| !matches!(component, std::path::Component::Normal(_)))
1706 {
1707 return Err(AcquisitionError::InvalidRequest(
1708 "registered file path must remain inside the package".to_owned(),
1709 ));
1710 }
1711 Ok(root.join(relative))
1712}
1713
1714fn sha256_file_streaming(path: &Path) -> Result<String, AcquisitionError> {
1715 let mut file = fs::File::open(path).map_err(|error| AcquisitionError::InvalidPackage {
1716 path: path.to_path_buf(),
1717 reason: error.to_string(),
1718 })?;
1719 let mut digest = Sha256::new();
1720 let mut buffer = vec![0_u8; 8 * 1024 * 1024];
1721 loop {
1722 let count = file
1723 .read(&mut buffer)
1724 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1725 if count == 0 {
1726 break;
1727 }
1728 digest.update(&buffer[..count]);
1729 }
1730 Ok(format!("{:x}", digest.finalize()))
1731}
1732
1733fn write_registered_manifest(
1734 destination: &Path,
1735 model: &RegisteredModel,
1736) -> Result<(), AcquisitionError> {
1737 let manifest = ModelManifest {
1738 schema_version: 1,
1739 id: model.name.clone(),
1740 model_version: Some(model.revision.clone()),
1741 version: None,
1742 format: model.format.clone(),
1743 artifact: ArtifactSpec {
1744 path: model.artifact_path.clone(),
1745 size_bytes: None,
1746 sha256: None,
1747 },
1748 metadata: BTreeMap::from([
1749 ("backend".to_owned(), model.backend.clone()),
1750 ("platforms".to_owned(), model.platforms.join(",")),
1751 ("architectures".to_owned(), model.architectures.join(",")),
1752 ("source".to_owned(), model.source.clone()),
1753 ("registry_revision".to_owned(), model.revision.clone()),
1754 (
1755 "runtime_requirement".to_owned(),
1756 model.runtime_requirement.clone(),
1757 ),
1758 ]),
1759 inputs: Vec::new(),
1760 outputs: Vec::new(),
1761 };
1762 fs::write(
1763 destination.join("manifest.json"),
1764 serde_json::to_vec_pretty(&manifest)
1765 .map_err(|error| AcquisitionError::InvalidRequest(error.to_string()))?,
1766 )
1767 .map_err(|error| AcquisitionError::Io(error.to_string()))
1768}
1769
1770pub fn runtime_requirement_satisfied(requirement: &str, current: &str) -> bool {
1771 let Some(required) = requirement.strip_prefix(">=") else {
1772 return requirement == current || requirement == "*";
1773 };
1774 let key = |version: &str| {
1775 let mut parts = version
1776 .split('.')
1777 .map(|part| part.parse::<u64>().unwrap_or(0));
1778 (
1779 parts.next().unwrap_or(0),
1780 parts.next().unwrap_or(0),
1781 parts.next().unwrap_or(0),
1782 )
1783 };
1784 key(current) >= key(required)
1785}
1786
1787#[derive(Clone)]
1788pub struct ModelHandle {
1789 model_id: String,
1790 backend: String,
1791 format: ModelFormat,
1792 inner: Arc<dyn Any + Send + Sync>,
1793}
1794
1795impl ModelHandle {
1796 pub fn new(
1797 model_id: impl Into<String>,
1798 backend: impl Into<String>,
1799 format: ModelFormat,
1800 inner: Arc<dyn Any + Send + Sync>,
1801 ) -> Self {
1802 Self {
1803 model_id: model_id.into(),
1804 backend: backend.into(),
1805 format,
1806 inner,
1807 }
1808 }
1809
1810 pub fn id(&self) -> &str {
1811 &self.model_id
1812 }
1813
1814 pub fn backend(&self) -> &str {
1815 &self.backend
1816 }
1817
1818 pub fn format(&self) -> &ModelFormat {
1819 &self.format
1820 }
1821
1822 pub fn state<T: Any + Send + Sync>(&self) -> Option<&T> {
1823 self.inner.as_ref().downcast_ref::<T>()
1824 }
1825}
1826
1827impl std::fmt::Debug for ModelHandle {
1828 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1829 f.debug_struct("ModelHandle")
1830 .field("model_id", &self.model_id)
1831 .field("backend", &self.backend)
1832 .field("format", &self.format)
1833 .finish_non_exhaustive()
1834 }
1835}
1836
1837#[cfg(test)]
1838mod tests {
1839 use super::{
1840 ArtifactSpec, BuiltinModelRegistry, CompiledArtifactManifest, CompiledStatus,
1841 FilesystemModelCatalog, InstallMode, InstallationManifest, ModelCatalog, ModelFormat,
1842 ModelManifest, ModelReference, RegisteredModel, RegisteredModelFile,
1843 RegisteredModelInstaller,
1844 };
1845 use std::{fs, path::PathBuf};
1846
1847 #[test]
1848 fn accepts_lowercase_manifest_formats() {
1849 let manifest: ModelManifest = serde_json::from_str(
1850 r#"{"id":"example","format":"onnx","artifact":"artifacts/model.onnx"}"#,
1851 )
1852 .unwrap();
1853 assert_eq!(manifest.format, ModelFormat::Onnx);
1854 }
1855
1856 #[test]
1857 fn builtin_registry_pins_laya_distribution_metadata() {
1858 let coreml = BuiltinModelRegistry
1859 .resolve_for("laya", "macos", "aarch64")
1860 .unwrap();
1861 assert_eq!(coreml.backend, "coreml");
1862 assert_eq!(coreml.format, ModelFormat::CoreMl);
1863 assert_eq!(coreml.artifact_path, "model.mlpackage");
1864 assert!(coreml.source.contains(&coreml.revision));
1865 assert!(coreml
1866 .files
1867 .iter()
1868 .any(|file| file.path.ends_with("weights/weight.bin")));
1869 let onnx = BuiltinModelRegistry
1870 .resolve_for("laya", "linux", "x86_64")
1871 .unwrap();
1872 assert_eq!(onnx.backend, "onnx");
1873 assert_eq!(onnx.format, ModelFormat::Onnx);
1874 assert_eq!(onnx.artifact_path, "laya.onnx");
1875 assert!(onnx.files.iter().all(|file| file.sha256.len() == 64));
1876 assert!(BuiltinModelRegistry
1877 .resolve_for("laya", "windows", "x86_64")
1878 .unwrap_err()
1879 .to_string()
1880 .contains("no backend for platform"));
1881 assert!(BuiltinModelRegistry.resolve("missing").is_err());
1882 }
1883
1884 #[test]
1885 fn installation_manifest_round_trips_atomically() {
1886 let root = std::env::temp_dir().join(format!(
1887 "ml-runtime-installation-manifest-{}",
1888 std::process::id()
1889 ));
1890 fs::create_dir_all(&root).unwrap();
1891 let manifest = InstallationManifest {
1892 schema_version: 1,
1893 model: "laya".to_owned(),
1894 model_revision: "revision".to_owned(),
1895 model_checksum: "model-hash".to_owned(),
1896 runtime_version: "0.1.0".to_owned(),
1897 runtime_requirement: ">=0.1.0".to_owned(),
1898 backend: "coreml".to_owned(),
1899 os: "macos".to_owned(),
1900 architecture: "aarch64".to_owned(),
1901 installed_at_unix_seconds: 1,
1902 compiled_status: CompiledStatus::Ready,
1903 compiled_artifact: Some(CompiledArtifactManifest {
1904 path: root.join("compiled.mlmodelc"),
1905 identity: "compiled-hash".to_owned(),
1906 }),
1907 };
1908 manifest.write_atomic(&root).unwrap();
1909 assert_eq!(InstallationManifest::read(&root).unwrap(), manifest);
1910 assert!(!root.join(".installation.json.tmp").exists());
1911 let _ = fs::remove_dir_all(root);
1912 }
1913
1914 #[tokio::test]
1915 async fn registered_installer_discovers_validates_and_rejects_corruption() {
1916 let root = std::env::temp_dir().join(format!(
1917 "ml-runtime-registered-install-{}",
1918 std::process::id()
1919 ));
1920 let source = root.join("source");
1921 let installed = root.join("installed");
1922 std::fs::create_dir_all(source.join("model.mlpackage")).unwrap();
1923 std::fs::write(source.join("config.json"), b"config").unwrap();
1924 std::fs::write(source.join("model.mlpackage/Manifest.json"), b"package").unwrap();
1925 let digest = |path: &std::path::Path| super::sha256_file_streaming(path).unwrap();
1926 let model = RegisteredModel {
1927 name: "fixture".to_owned(),
1928 revision: "revision-1".to_owned(),
1929 source: "https://example.invalid/fixture".to_owned(),
1930 backend: "coreml".to_owned(),
1931 runtime_requirement: ">=0.1.0".to_owned(),
1932 format: ModelFormat::CoreMl,
1933 platforms: vec![],
1934 architectures: vec![],
1935 artifact_path: "model.mlpackage".to_owned(),
1936 files: vec![
1937 RegisteredModelFile {
1938 path: "config.json".to_owned(),
1939 sha256: digest(&source.join("config.json")),
1940 },
1941 RegisteredModelFile {
1942 path: "model.mlpackage/Manifest.json".to_owned(),
1943 sha256: digest(&source.join("model.mlpackage/Manifest.json")),
1944 },
1945 ],
1946 };
1947 let installer = RegisteredModelInstaller::new(&installed).unwrap();
1948 let result = installer
1949 .install(
1950 &model,
1951 Some(source.to_str().unwrap()),
1952 InstallMode::KeepExisting,
1953 None,
1954 )
1955 .await
1956 .unwrap();
1957 assert_eq!(result.package_path, installed.join("fixture/revision-1"));
1958 assert!(result.package_path.join("manifest.json").is_file());
1959 installer.validate(&model, &result.package_path).unwrap();
1960
1961 let existing = installer
1962 .install(
1963 &model,
1964 Some(source.to_str().unwrap()),
1965 InstallMode::KeepExisting,
1966 None,
1967 )
1968 .await
1969 .unwrap();
1970 assert!(existing.already_installed);
1971 std::fs::write(existing.package_path.join("config.json"), b"corrupt").unwrap();
1972 assert!(installer.validate(&model, &existing.package_path).is_err());
1973 let _ = std::fs::remove_dir_all(root);
1974 }
1975
1976 #[test]
1977 fn registered_model_rejects_missing_or_malformed_checksums() {
1978 let root = std::env::temp_dir().join(format!(
1979 "ml-runtime-registration-validation-{}",
1980 std::process::id()
1981 ));
1982 let installer = RegisteredModelInstaller::new(&root).unwrap();
1983 let mut model = RegisteredModel {
1984 name: "fixture".to_owned(),
1985 revision: "revision".to_owned(),
1986 source: "https://example.invalid/model".to_owned(),
1987 backend: "onnx".to_owned(),
1988 runtime_requirement: ">=0.1.0".to_owned(),
1989 format: ModelFormat::Onnx,
1990 platforms: vec![],
1991 architectures: vec![],
1992 artifact_path: "model.onnx".to_owned(),
1993 files: vec![],
1994 };
1995 assert!(super::validate_registration(&model).is_err());
1996 model.files.push(RegisteredModelFile {
1997 path: "model.onnx".to_owned(),
1998 sha256: "not-a-sha256".to_owned(),
1999 });
2000 assert!(super::validate_registration(&model).is_err());
2001 assert!(installer.validate(&model, &root).is_err());
2002 }
2003
2004 #[test]
2005 fn accepts_artifact_integrity_metadata() {
2006 let manifest: ModelManifest = serde_json::from_str(
2007 r#"{"id":"example","format":"onnx","artifact":{"path":"model.onnx","size_bytes":3,"sha256":"abc"}}"#,
2008 )
2009 .unwrap();
2010 assert_eq!(
2011 manifest.artifact,
2012 ArtifactSpec {
2013 path: "model.onnx".to_owned(),
2014 size_bytes: Some(3),
2015 sha256: Some("abc".to_owned()),
2016 }
2017 );
2018 }
2019
2020 #[tokio::test]
2021 async fn discovers_and_resolves_existing_packages_deterministically() {
2022 let root = std::env::temp_dir().join(format!("ml-runtime-catalog-{}", std::process::id()));
2023 let first = root.join("nested/example-linear");
2024 fs::create_dir_all(first.join("artifacts")).unwrap();
2025 fs::write(
2026 first.join("manifest.json"),
2027 r#"{"id":"example-linear","model_version":"1.0.0","format":"unknown","artifact":"artifacts/model.json"}"#,
2028 )
2029 .unwrap();
2030 fs::write(first.join("artifacts/model.json"), "{}").unwrap();
2031
2032 let catalog = FilesystemModelCatalog::new(&root);
2033 let models = catalog.list().await.unwrap();
2034 assert_eq!(models[0].id.to_string(), "example-linear@1.0.0");
2035 let resolved = catalog
2036 .resolve(&ModelReference::id(
2037 "example-linear",
2038 Some("1.0.0".to_owned()),
2039 ))
2040 .await
2041 .unwrap();
2042 assert_eq!(resolved.package_path, PathBuf::from(&first));
2043 fs::remove_dir_all(root).unwrap();
2044 }
2045
2046 #[tokio::test]
2047 async fn installs_verified_package_atomically_and_refreshes_catalog() {
2048 use super::{
2049 AcquisitionConfig, FileModelSource, InstallMode, InstallResult, ModelFetchRequest,
2050 ModelId, ModelInstaller, ModelSourceReference,
2051 };
2052 use std::sync::Arc;
2053 let root = std::env::temp_dir().join(format!("ml-runtime-install-{}", std::process::id()));
2054 let source_root = root.join("source");
2055 let catalog_root = root.join("models");
2056 fs::create_dir_all(source_root.join("artifacts")).unwrap();
2057 fs::write(
2058 source_root.join("manifest.json"),
2059 r#"{"id":"acquired","model_version":"1.0.0","format":"unknown","artifact":"artifacts/model.bin"}"#,
2060 )
2061 .unwrap();
2062 fs::write(source_root.join("artifacts/model.bin"), b"model").unwrap();
2063
2064 let catalog = Arc::new(FilesystemModelCatalog::new(&catalog_root));
2065 let installer = ModelInstaller::new(&catalog_root)
2066 .with_catalog(Arc::clone(&catalog))
2067 .with_config(AcquisitionConfig {
2068 max_download_bytes: 1024,
2069 timeout_secs: 30,
2070 });
2071 let request = ModelFetchRequest {
2072 model: ModelId::new("acquired", "1.0.0").unwrap(),
2073 source: ModelSourceReference::Path(source_root.clone()),
2074 };
2075 let result = installer
2076 .install(
2077 &FileModelSource::new(),
2078 &request,
2079 InstallMode::KeepExisting,
2080 None,
2081 )
2082 .await
2083 .unwrap();
2084 assert!(matches!(result, InstallResult::Installed(_)));
2085 assert_eq!(catalog.list().await.unwrap().len(), 1);
2086 let existing = installer
2087 .install(
2088 &FileModelSource::new(),
2089 &request,
2090 InstallMode::KeepExisting,
2091 None,
2092 )
2093 .await
2094 .unwrap();
2095 assert!(matches!(existing, InstallResult::AlreadyInstalled(_)));
2096 assert!(!catalog_root
2097 .join(".staging")
2098 .join("acquired-1.0.0-")
2099 .exists());
2100 fs::remove_dir_all(root).unwrap();
2101 }
2102
2103 #[tokio::test]
2104 async fn rejects_identity_mismatch_without_catalog_entry() {
2105 use super::{
2106 FileModelSource, InstallMode, ModelFetchRequest, ModelId, ModelInstaller,
2107 ModelSourceReference,
2108 };
2109 use std::sync::Arc;
2110 let root = std::env::temp_dir().join(format!("ml-runtime-mismatch-{}", std::process::id()));
2111 let source = root.join("source");
2112 fs::create_dir_all(source.join("artifacts")).unwrap();
2113 fs::write(
2114 source.join("manifest.json"),
2115 r#"{"id":"other","model_version":"1.0.0","format":"unknown","artifact":"artifacts/model.bin"}"#,
2116 )
2117 .unwrap();
2118 fs::write(source.join("artifacts/model.bin"), b"model").unwrap();
2119 let catalog = Arc::new(FilesystemModelCatalog::new(root.join("models")));
2120 let installer = ModelInstaller::new(root.join("models")).with_catalog(Arc::clone(&catalog));
2121 let request = ModelFetchRequest {
2122 model: ModelId::new("requested", "1.0.0").unwrap(),
2123 source: ModelSourceReference::Path(source),
2124 };
2125 assert!(matches!(
2126 installer
2127 .install(
2128 &FileModelSource::new(),
2129 &request,
2130 InstallMode::KeepExisting,
2131 None
2132 )
2133 .await,
2134 Err(super::AcquisitionError::IdentityMismatch { .. })
2135 ));
2136 assert!(catalog.list().await.unwrap().is_empty());
2137 fs::remove_dir_all(root).unwrap();
2138 }
2139}