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 pub artifact_path: String,
1134 pub files: Vec<RegisteredModelFile>,
1135}
1136
1137#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1138pub struct RegisteredModelFile {
1139 pub path: String,
1140 pub sha256: String,
1141}
1142
1143pub const INSTALLATION_MANIFEST_FILE: &str = "installation.json";
1144
1145#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1146#[serde(rename_all = "snake_case")]
1147pub enum CompiledStatus {
1148 Ready,
1149 Missing,
1150 Corrupt,
1151 Unsupported,
1152}
1153
1154#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1155pub struct CompiledArtifactManifest {
1156 pub path: PathBuf,
1157 pub identity: String,
1158}
1159
1160#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
1161pub struct InstallationManifest {
1162 pub schema_version: u32,
1163 pub model: String,
1164 pub model_revision: String,
1165 pub model_checksum: String,
1166 pub runtime_version: String,
1167 pub runtime_requirement: String,
1168 pub backend: String,
1169 pub os: String,
1170 pub architecture: String,
1171 pub installed_at_unix_seconds: u64,
1172 pub compiled_status: CompiledStatus,
1173 pub compiled_artifact: Option<CompiledArtifactManifest>,
1174}
1175
1176impl InstallationManifest {
1177 pub fn read(package: &Path) -> Result<Self, AcquisitionError> {
1178 let path = package.join(INSTALLATION_MANIFEST_FILE);
1179 let bytes = fs::read(&path).map_err(|error| AcquisitionError::InvalidPackage {
1180 path: path.clone(),
1181 reason: format!(
1182 "installation is not ready: {error}; run `ml-runtime model doctor {}`",
1183 package
1184 .parent()
1185 .and_then(Path::file_name)
1186 .and_then(|name| name.to_str())
1187 .unwrap_or("MODEL")
1188 ),
1189 })?;
1190 serde_json::from_slice(&bytes).map_err(|error| AcquisitionError::InvalidPackage {
1191 path,
1192 reason: format!("invalid installation manifest: {error}"),
1193 })
1194 }
1195
1196 pub fn write_atomic(&self, package: &Path) -> Result<(), AcquisitionError> {
1197 let destination = package.join(INSTALLATION_MANIFEST_FILE);
1198 let temporary = package.join(format!(".{INSTALLATION_MANIFEST_FILE}.tmp"));
1199 let bytes = serde_json::to_vec_pretty(self)
1200 .map_err(|error| AcquisitionError::InvalidRequest(error.to_string()))?;
1201 let mut output = fs::File::create(&temporary)
1202 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1203 output
1204 .write_all(&bytes)
1205 .and_then(|()| output.sync_all())
1206 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1207 fs::rename(&temporary, &destination)
1208 .map_err(|error| AcquisitionError::Io(error.to_string()))
1209 }
1210}
1211
1212#[derive(Clone, Debug, Default)]
1213pub struct BuiltinModelRegistry;
1214
1215impl BuiltinModelRegistry {
1216 pub fn list(&self) -> Vec<RegisteredModel> {
1217 vec![laya_registration()]
1218 }
1219
1220 pub fn resolve(&self, name: &str) -> Result<RegisteredModel, AcquisitionError> {
1221 self.list()
1222 .into_iter()
1223 .find(|model| model.name == name)
1224 .ok_or_else(|| {
1225 AcquisitionError::InvalidRequest(format!("unknown registered model {name:?}"))
1226 })
1227 }
1228}
1229
1230fn laya_registration() -> RegisteredModel {
1231 const REVISION: &str = "fff78b2d9750c6b748fe8c90fcbf8bed0a1522a9";
1232 let files = [
1233 (
1234 "coreml_config.json",
1235 "990b99a736f64c87da57b203d7953c4c1c79c18b615580db894e9c24bda42ab5",
1236 ),
1237 (
1238 "validation.json",
1239 "709e1a0ac95a7bf73df0b5a8582423c9f40c80a1b4edd3499a77a1ac2ac39731",
1240 ),
1241 (
1242 "encoder/config.json",
1243 "bf3ab80598fdccf414855a2ce80f22859e4492d06ca8a62ddd1cfb63972f8979",
1244 ),
1245 (
1246 "rl_agent_config.json",
1247 "ae287b56bbcf5f8c4f4541ae9dfd00c914c4c48b940b8398c3058af37ba92bbd",
1248 ),
1249 (
1250 "tokenizer/tokenizer.json",
1251 "6c8aaa9a542084f2457eab775d4eeb51f92a70c0fd9de28d5edb0ddec3c08d30",
1252 ),
1253 (
1254 "tokenizer/tokenizer_config.json",
1255 "50044de60daaa73df97d262e15a40d4faf0160e7d742df64b377877a1320dd12",
1256 ),
1257 (
1258 "model.mlpackage/Manifest.json",
1259 "41bab6e532f727e8809c76906f41026a48ef9b276c56068b3d68270a13981e20",
1260 ),
1261 (
1262 "model.mlpackage/Data/com.apple.CoreML/model.mlmodel",
1263 "dc6a6383ad4a2f04f7525924b0dfb830429dedc44387f143a2f87782e39aeab0",
1264 ),
1265 (
1266 "model.mlpackage/Data/com.apple.CoreML/weights/weight.bin",
1267 "5872b9f6530c20a845b69c0cb75aa141e9c89ffdd5f36529c3708cec9b7a7a83",
1268 ),
1269 ]
1270 .into_iter()
1271 .map(|(path, sha256)| RegisteredModelFile {
1272 path: path.to_owned(),
1273 sha256: sha256.to_owned(),
1274 })
1275 .collect();
1276 RegisteredModel {
1277 name: "laya".to_owned(),
1278 revision: REVISION.to_owned(),
1279 source: format!("https://huggingface.co/aac6fef/laya-coreml/resolve/{REVISION}"),
1280 backend: "coreml".to_owned(),
1281 runtime_requirement: ">=0.1.0".to_owned(),
1282 format: ModelFormat::CoreMl,
1283 artifact_path: "model.mlpackage".to_owned(),
1284 files,
1285 }
1286}
1287
1288pub fn default_model_root() -> Result<PathBuf, AcquisitionError> {
1289 if let Some(root) = std::env::var_os("ML_RUNTIME_MODEL_DIR") {
1290 return Ok(PathBuf::from(root));
1291 }
1292 #[cfg(target_os = "windows")]
1293 if let Some(root) = std::env::var_os("LOCALAPPDATA") {
1294 return Ok(PathBuf::from(root).join("ml-runtime/models"));
1295 }
1296 let home = std::env::var_os("HOME").ok_or_else(|| {
1297 AcquisitionError::InvalidRequest(
1298 "cannot determine model directory; set ML_RUNTIME_MODEL_DIR".to_owned(),
1299 )
1300 })?;
1301 #[cfg(target_os = "windows")]
1302 return Ok(PathBuf::from(home).join("AppData/Local/ml-runtime/models"));
1303 #[cfg(target_os = "macos")]
1304 return Ok(PathBuf::from(home).join("Library/Application Support/ml-runtime/models"));
1305 #[cfg(not(any(target_os = "macos", target_os = "windows")))]
1306 Ok(PathBuf::from(home).join(".local/share/ml-runtime/models"))
1307}
1308
1309#[derive(Clone, Debug, PartialEq, Eq)]
1310pub struct RegisteredInstallResult {
1311 pub package_path: PathBuf,
1312 pub already_installed: bool,
1313}
1314
1315pub struct RegisteredModelInstaller {
1316 root: PathBuf,
1317 client: reqwest::Client,
1318 config: AcquisitionConfig,
1319}
1320
1321impl RegisteredModelInstaller {
1322 pub fn new(root: impl Into<PathBuf>) -> Result<Self, AcquisitionError> {
1323 let client = reqwest::Client::builder()
1324 .redirect(reqwest::redirect::Policy::limited(10))
1325 .build()
1326 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1327 Ok(Self {
1328 root: root.into(),
1329 client,
1330 config: AcquisitionConfig::default(),
1331 })
1332 }
1333
1334 pub fn with_config(mut self, config: AcquisitionConfig) -> Self {
1335 self.config = config;
1336 self
1337 }
1338
1339 pub fn installed_path(&self, model: &RegisteredModel) -> PathBuf {
1340 self.root.join(&model.name).join(&model.revision)
1341 }
1342
1343 pub fn validate(
1344 &self,
1345 model: &RegisteredModel,
1346 package: &Path,
1347 ) -> Result<(), AcquisitionError> {
1348 let manifest =
1349 ModelPackage::open(package).map_err(|reason| AcquisitionError::InvalidPackage {
1350 path: package.to_path_buf(),
1351 reason,
1352 })?;
1353 let id = package_id(&manifest)?;
1354 let expected =
1355 ModelId::new(&model.name, &model.revision).map_err(AcquisitionError::Catalog)?;
1356 if id != expected || manifest.manifest.format != model.format {
1357 return Err(AcquisitionError::IdentityMismatch {
1358 requested: expected,
1359 found: id,
1360 });
1361 }
1362 if manifest.manifest.artifact.path != model.artifact_path {
1363 return Err(AcquisitionError::InvalidPackage {
1364 path: package.to_path_buf(),
1365 reason: format!(
1366 "registered artifact path must be {:?}, got {:?}",
1367 model.artifact_path, manifest.manifest.artifact.path
1368 ),
1369 });
1370 }
1371 if !runtime_requirement_satisfied(&model.runtime_requirement, env!("CARGO_PKG_VERSION")) {
1372 return Err(AcquisitionError::InvalidPackage {
1373 path: package.to_path_buf(),
1374 reason: format!(
1375 "model requires runtime {}, current runtime is {}",
1376 model.runtime_requirement,
1377 env!("CARGO_PKG_VERSION")
1378 ),
1379 });
1380 }
1381 for file in &model.files {
1382 let path = safe_registered_path(package, &file.path)?;
1383 let actual = sha256_file_streaming(&path)?;
1384 if !actual.eq_ignore_ascii_case(&file.sha256) {
1385 return Err(AcquisitionError::InvalidPackage {
1386 path,
1387 reason: format!("sha256 mismatch: expected {}, got {actual}", file.sha256),
1388 });
1389 }
1390 }
1391 Ok(())
1392 }
1393
1394 pub async fn install(
1395 &self,
1396 model: &RegisteredModel,
1397 source_override: Option<&str>,
1398 mode: InstallMode,
1399 cancellation: Option<&CancellationToken>,
1400 ) -> Result<RegisteredInstallResult, AcquisitionError> {
1401 let final_path = self.installed_path(model);
1402 if final_path.exists() && mode == InstallMode::KeepExisting {
1403 self.validate(model, &final_path)?;
1404 return Ok(RegisteredInstallResult {
1405 package_path: final_path,
1406 already_installed: true,
1407 });
1408 }
1409 fs::create_dir_all(&self.root).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1410 let staging_root = self.root.join(".staging");
1411 fs::create_dir_all(&staging_root)
1412 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1413 let staging = staging_root.join(format!("{}-{}", model.name, std::process::id()));
1414 if staging.exists() {
1415 fs::remove_dir_all(&staging)
1416 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1417 }
1418 fs::create_dir_all(&staging).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1419 let source = source_override.unwrap_or(&model.source);
1420 let result = async {
1421 let mut downloaded = 0_u64;
1422 if source.starts_with("https://") || source.starts_with("http://") {
1423 validate_http_uri(source, false)?;
1424 for file in &model.files {
1425 if cancellation.is_some_and(CancellationToken::is_cancelled) {
1426 return Err(AcquisitionError::Cancelled);
1427 }
1428 let destination = safe_registered_path(&staging, &file.path)?;
1429 if let Some(parent) = destination.parent() {
1430 fs::create_dir_all(parent)
1431 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1432 }
1433 self.download_file(
1434 &format!("{}/{}", source.trim_end_matches('/'), file.path),
1435 &destination,
1436 &mut downloaded,
1437 cancellation,
1438 )
1439 .await?;
1440 }
1441 } else {
1442 let source = Path::new(source);
1443 if !source.is_dir() {
1444 return Err(AcquisitionError::InvalidRequest(format!(
1445 "registered model source is not a directory: {}",
1446 source.display()
1447 )));
1448 }
1449 for file in &model.files {
1450 let from = safe_registered_path(source, &file.path)?;
1451 let to = safe_registered_path(&staging, &file.path)?;
1452 if let Some(parent) = to.parent() {
1453 fs::create_dir_all(parent)
1454 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1455 }
1456 let size = fs::metadata(&from)
1457 .map_err(|error| AcquisitionError::Io(error.to_string()))?
1458 .len();
1459 downloaded = downloaded.saturating_add(size);
1460 if downloaded > self.config.max_download_bytes {
1461 return Err(AcquisitionError::LimitExceeded {
1462 limit: self.config.max_download_bytes,
1463 actual: downloaded,
1464 });
1465 }
1466 fs::copy(&from, &to)
1467 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1468 }
1469 }
1470 write_registered_manifest(&staging, model)?;
1471 self.validate(model, &staging)?;
1472 let parent = final_path.parent().expect("registered model has parent");
1473 fs::create_dir_all(parent).map_err(|error| AcquisitionError::Io(error.to_string()))?;
1474 if final_path.exists() {
1475 if mode != InstallMode::Replace {
1476 return Err(AcquisitionError::AlreadyInstalled(
1477 ModelId::new(&model.name, &model.revision)
1478 .map_err(AcquisitionError::Catalog)?,
1479 ));
1480 }
1481 let backup = parent.join(format!(".replace-{}", std::process::id()));
1482 fs::rename(&final_path, &backup)
1483 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1484 if let Err(error) = fs::rename(&staging, &final_path) {
1485 let _ = fs::rename(&backup, &final_path);
1486 return Err(AcquisitionError::Io(error.to_string()));
1487 }
1488 let _ = fs::remove_dir_all(backup);
1489 } else {
1490 fs::rename(&staging, &final_path)
1491 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1492 }
1493 Ok(RegisteredInstallResult {
1494 package_path: final_path.clone(),
1495 already_installed: false,
1496 })
1497 }
1498 .await;
1499 if staging.exists() {
1500 let _ = fs::remove_dir_all(staging);
1501 }
1502 result
1503 }
1504
1505 async fn download_file(
1506 &self,
1507 url: &str,
1508 destination: &Path,
1509 downloaded: &mut u64,
1510 cancellation: Option<&CancellationToken>,
1511 ) -> Result<(), AcquisitionError> {
1512 validate_http_uri(url, false)?;
1513 let mut response = tokio::time::timeout(
1514 std::time::Duration::from_secs(self.config.timeout_secs),
1515 self.client.get(url).send(),
1516 )
1517 .await
1518 .map_err(|_| AcquisitionError::Io(format!("download timed out: {url}")))?
1519 .map_err(|error| AcquisitionError::Io(error.to_string()))?
1520 .error_for_status()
1521 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1522 let mut output = fs::File::create(destination)
1523 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1524 while let Some(chunk) = response
1525 .chunk()
1526 .await
1527 .map_err(|error| AcquisitionError::Io(error.to_string()))?
1528 {
1529 if cancellation.is_some_and(CancellationToken::is_cancelled) {
1530 return Err(AcquisitionError::Cancelled);
1531 }
1532 *downloaded = downloaded.saturating_add(chunk.len() as u64);
1533 if *downloaded > self.config.max_download_bytes {
1534 return Err(AcquisitionError::LimitExceeded {
1535 limit: self.config.max_download_bytes,
1536 actual: *downloaded,
1537 });
1538 }
1539 output
1540 .write_all(&chunk)
1541 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1542 }
1543 output
1544 .sync_all()
1545 .map_err(|error| AcquisitionError::Io(error.to_string()))
1546 }
1547}
1548
1549fn safe_registered_path(root: &Path, relative: &str) -> Result<PathBuf, AcquisitionError> {
1550 let relative = Path::new(relative);
1551 if relative.is_absolute()
1552 || relative
1553 .components()
1554 .any(|component| !matches!(component, std::path::Component::Normal(_)))
1555 {
1556 return Err(AcquisitionError::InvalidRequest(
1557 "registered file path must remain inside the package".to_owned(),
1558 ));
1559 }
1560 Ok(root.join(relative))
1561}
1562
1563fn sha256_file_streaming(path: &Path) -> Result<String, AcquisitionError> {
1564 let mut file = fs::File::open(path).map_err(|error| AcquisitionError::InvalidPackage {
1565 path: path.to_path_buf(),
1566 reason: error.to_string(),
1567 })?;
1568 let mut digest = Sha256::new();
1569 let mut buffer = vec![0_u8; 8 * 1024 * 1024];
1570 loop {
1571 let count = file
1572 .read(&mut buffer)
1573 .map_err(|error| AcquisitionError::Io(error.to_string()))?;
1574 if count == 0 {
1575 break;
1576 }
1577 digest.update(&buffer[..count]);
1578 }
1579 Ok(format!("{:x}", digest.finalize()))
1580}
1581
1582fn write_registered_manifest(
1583 destination: &Path,
1584 model: &RegisteredModel,
1585) -> Result<(), AcquisitionError> {
1586 let manifest = ModelManifest {
1587 schema_version: 1,
1588 id: model.name.clone(),
1589 model_version: Some(model.revision.clone()),
1590 version: None,
1591 format: model.format.clone(),
1592 artifact: ArtifactSpec {
1593 path: model.artifact_path.clone(),
1594 size_bytes: None,
1595 sha256: None,
1596 },
1597 metadata: BTreeMap::from([
1598 ("backend".to_owned(), model.backend.clone()),
1599 ("source".to_owned(), model.source.clone()),
1600 ("registry_revision".to_owned(), model.revision.clone()),
1601 (
1602 "runtime_requirement".to_owned(),
1603 model.runtime_requirement.clone(),
1604 ),
1605 ]),
1606 inputs: Vec::new(),
1607 outputs: Vec::new(),
1608 };
1609 fs::write(
1610 destination.join("manifest.json"),
1611 serde_json::to_vec_pretty(&manifest)
1612 .map_err(|error| AcquisitionError::InvalidRequest(error.to_string()))?,
1613 )
1614 .map_err(|error| AcquisitionError::Io(error.to_string()))
1615}
1616
1617pub fn runtime_requirement_satisfied(requirement: &str, current: &str) -> bool {
1618 let Some(required) = requirement.strip_prefix(">=") else {
1619 return requirement == current || requirement == "*";
1620 };
1621 let key = |version: &str| {
1622 let mut parts = version
1623 .split('.')
1624 .map(|part| part.parse::<u64>().unwrap_or(0));
1625 (
1626 parts.next().unwrap_or(0),
1627 parts.next().unwrap_or(0),
1628 parts.next().unwrap_or(0),
1629 )
1630 };
1631 key(current) >= key(required)
1632}
1633
1634#[derive(Clone)]
1635pub struct ModelHandle {
1636 model_id: String,
1637 backend: String,
1638 format: ModelFormat,
1639 inner: Arc<dyn Any + Send + Sync>,
1640}
1641
1642impl ModelHandle {
1643 pub fn new(
1644 model_id: impl Into<String>,
1645 backend: impl Into<String>,
1646 format: ModelFormat,
1647 inner: Arc<dyn Any + Send + Sync>,
1648 ) -> Self {
1649 Self {
1650 model_id: model_id.into(),
1651 backend: backend.into(),
1652 format,
1653 inner,
1654 }
1655 }
1656
1657 pub fn id(&self) -> &str {
1658 &self.model_id
1659 }
1660
1661 pub fn backend(&self) -> &str {
1662 &self.backend
1663 }
1664
1665 pub fn format(&self) -> &ModelFormat {
1666 &self.format
1667 }
1668
1669 pub fn state<T: Any + Send + Sync>(&self) -> Option<&T> {
1670 self.inner.as_ref().downcast_ref::<T>()
1671 }
1672}
1673
1674impl std::fmt::Debug for ModelHandle {
1675 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1676 f.debug_struct("ModelHandle")
1677 .field("model_id", &self.model_id)
1678 .field("backend", &self.backend)
1679 .field("format", &self.format)
1680 .finish_non_exhaustive()
1681 }
1682}
1683
1684#[cfg(test)]
1685mod tests {
1686 use super::{
1687 ArtifactSpec, BuiltinModelRegistry, CompiledArtifactManifest, CompiledStatus,
1688 FilesystemModelCatalog, InstallMode, InstallationManifest, ModelCatalog, ModelFormat,
1689 ModelManifest, ModelReference, RegisteredModel, RegisteredModelFile,
1690 RegisteredModelInstaller,
1691 };
1692 use std::{fs, path::PathBuf};
1693
1694 #[test]
1695 fn accepts_lowercase_manifest_formats() {
1696 let manifest: ModelManifest = serde_json::from_str(
1697 r#"{"id":"example","format":"onnx","artifact":"artifacts/model.onnx"}"#,
1698 )
1699 .unwrap();
1700 assert_eq!(manifest.format, ModelFormat::Onnx);
1701 }
1702
1703 #[test]
1704 fn builtin_registry_pins_laya_distribution_metadata() {
1705 let laya = BuiltinModelRegistry.resolve("laya").unwrap();
1706 assert_eq!(laya.backend, "coreml");
1707 assert_eq!(laya.format, ModelFormat::CoreMl);
1708 assert_eq!(laya.artifact_path, "model.mlpackage");
1709 assert!(laya.source.contains(&laya.revision));
1710 assert!(laya
1711 .files
1712 .iter()
1713 .any(|file| file.path.ends_with("weights/weight.bin")));
1714 assert!(BuiltinModelRegistry.resolve("missing").is_err());
1715 }
1716
1717 #[test]
1718 fn installation_manifest_round_trips_atomically() {
1719 let root = std::env::temp_dir().join(format!(
1720 "ml-runtime-installation-manifest-{}",
1721 std::process::id()
1722 ));
1723 fs::create_dir_all(&root).unwrap();
1724 let manifest = InstallationManifest {
1725 schema_version: 1,
1726 model: "laya".to_owned(),
1727 model_revision: "revision".to_owned(),
1728 model_checksum: "model-hash".to_owned(),
1729 runtime_version: "0.1.0".to_owned(),
1730 runtime_requirement: ">=0.1.0".to_owned(),
1731 backend: "coreml".to_owned(),
1732 os: "macos".to_owned(),
1733 architecture: "aarch64".to_owned(),
1734 installed_at_unix_seconds: 1,
1735 compiled_status: CompiledStatus::Ready,
1736 compiled_artifact: Some(CompiledArtifactManifest {
1737 path: root.join("compiled.mlmodelc"),
1738 identity: "compiled-hash".to_owned(),
1739 }),
1740 };
1741 manifest.write_atomic(&root).unwrap();
1742 assert_eq!(InstallationManifest::read(&root).unwrap(), manifest);
1743 assert!(!root.join(".installation.json.tmp").exists());
1744 let _ = fs::remove_dir_all(root);
1745 }
1746
1747 #[tokio::test]
1748 async fn registered_installer_discovers_validates_and_rejects_corruption() {
1749 let root = std::env::temp_dir().join(format!(
1750 "ml-runtime-registered-install-{}",
1751 std::process::id()
1752 ));
1753 let source = root.join("source");
1754 let installed = root.join("installed");
1755 std::fs::create_dir_all(source.join("model.mlpackage")).unwrap();
1756 std::fs::write(source.join("config.json"), b"config").unwrap();
1757 std::fs::write(source.join("model.mlpackage/Manifest.json"), b"package").unwrap();
1758 let digest = |path: &std::path::Path| super::sha256_file_streaming(path).unwrap();
1759 let model = RegisteredModel {
1760 name: "fixture".to_owned(),
1761 revision: "revision-1".to_owned(),
1762 source: "https://example.invalid/fixture".to_owned(),
1763 backend: "coreml".to_owned(),
1764 runtime_requirement: ">=0.1.0".to_owned(),
1765 format: ModelFormat::CoreMl,
1766 artifact_path: "model.mlpackage".to_owned(),
1767 files: vec![
1768 RegisteredModelFile {
1769 path: "config.json".to_owned(),
1770 sha256: digest(&source.join("config.json")),
1771 },
1772 RegisteredModelFile {
1773 path: "model.mlpackage/Manifest.json".to_owned(),
1774 sha256: digest(&source.join("model.mlpackage/Manifest.json")),
1775 },
1776 ],
1777 };
1778 let installer = RegisteredModelInstaller::new(&installed).unwrap();
1779 let result = installer
1780 .install(
1781 &model,
1782 Some(source.to_str().unwrap()),
1783 InstallMode::KeepExisting,
1784 None,
1785 )
1786 .await
1787 .unwrap();
1788 assert_eq!(result.package_path, installed.join("fixture/revision-1"));
1789 assert!(result.package_path.join("manifest.json").is_file());
1790 installer.validate(&model, &result.package_path).unwrap();
1791
1792 let existing = installer
1793 .install(
1794 &model,
1795 Some(source.to_str().unwrap()),
1796 InstallMode::KeepExisting,
1797 None,
1798 )
1799 .await
1800 .unwrap();
1801 assert!(existing.already_installed);
1802 std::fs::write(existing.package_path.join("config.json"), b"corrupt").unwrap();
1803 assert!(installer.validate(&model, &existing.package_path).is_err());
1804 let _ = std::fs::remove_dir_all(root);
1805 }
1806
1807 #[test]
1808 fn accepts_artifact_integrity_metadata() {
1809 let manifest: ModelManifest = serde_json::from_str(
1810 r#"{"id":"example","format":"onnx","artifact":{"path":"model.onnx","size_bytes":3,"sha256":"abc"}}"#,
1811 )
1812 .unwrap();
1813 assert_eq!(
1814 manifest.artifact,
1815 ArtifactSpec {
1816 path: "model.onnx".to_owned(),
1817 size_bytes: Some(3),
1818 sha256: Some("abc".to_owned()),
1819 }
1820 );
1821 }
1822
1823 #[tokio::test]
1824 async fn discovers_and_resolves_existing_packages_deterministically() {
1825 let root = std::env::temp_dir().join(format!("ml-runtime-catalog-{}", std::process::id()));
1826 let first = root.join("nested/example-linear");
1827 fs::create_dir_all(first.join("artifacts")).unwrap();
1828 fs::write(
1829 first.join("manifest.json"),
1830 r#"{"id":"example-linear","model_version":"1.0.0","format":"unknown","artifact":"artifacts/model.json"}"#,
1831 )
1832 .unwrap();
1833 fs::write(first.join("artifacts/model.json"), "{}").unwrap();
1834
1835 let catalog = FilesystemModelCatalog::new(&root);
1836 let models = catalog.list().await.unwrap();
1837 assert_eq!(models[0].id.to_string(), "example-linear@1.0.0");
1838 let resolved = catalog
1839 .resolve(&ModelReference::id(
1840 "example-linear",
1841 Some("1.0.0".to_owned()),
1842 ))
1843 .await
1844 .unwrap();
1845 assert_eq!(resolved.package_path, PathBuf::from(&first));
1846 fs::remove_dir_all(root).unwrap();
1847 }
1848
1849 #[tokio::test]
1850 async fn installs_verified_package_atomically_and_refreshes_catalog() {
1851 use super::{
1852 AcquisitionConfig, FileModelSource, InstallMode, InstallResult, ModelFetchRequest,
1853 ModelId, ModelInstaller, ModelSourceReference,
1854 };
1855 use std::sync::Arc;
1856 let root = std::env::temp_dir().join(format!("ml-runtime-install-{}", std::process::id()));
1857 let source_root = root.join("source");
1858 let catalog_root = root.join("models");
1859 fs::create_dir_all(source_root.join("artifacts")).unwrap();
1860 fs::write(
1861 source_root.join("manifest.json"),
1862 r#"{"id":"acquired","model_version":"1.0.0","format":"unknown","artifact":"artifacts/model.bin"}"#,
1863 )
1864 .unwrap();
1865 fs::write(source_root.join("artifacts/model.bin"), b"model").unwrap();
1866
1867 let catalog = Arc::new(FilesystemModelCatalog::new(&catalog_root));
1868 let installer = ModelInstaller::new(&catalog_root)
1869 .with_catalog(Arc::clone(&catalog))
1870 .with_config(AcquisitionConfig {
1871 max_download_bytes: 1024,
1872 timeout_secs: 30,
1873 });
1874 let request = ModelFetchRequest {
1875 model: ModelId::new("acquired", "1.0.0").unwrap(),
1876 source: ModelSourceReference::Path(source_root.clone()),
1877 };
1878 let result = installer
1879 .install(
1880 &FileModelSource::new(),
1881 &request,
1882 InstallMode::KeepExisting,
1883 None,
1884 )
1885 .await
1886 .unwrap();
1887 assert!(matches!(result, InstallResult::Installed(_)));
1888 assert_eq!(catalog.list().await.unwrap().len(), 1);
1889 let existing = installer
1890 .install(
1891 &FileModelSource::new(),
1892 &request,
1893 InstallMode::KeepExisting,
1894 None,
1895 )
1896 .await
1897 .unwrap();
1898 assert!(matches!(existing, InstallResult::AlreadyInstalled(_)));
1899 assert!(!catalog_root
1900 .join(".staging")
1901 .join("acquired-1.0.0-")
1902 .exists());
1903 fs::remove_dir_all(root).unwrap();
1904 }
1905
1906 #[tokio::test]
1907 async fn rejects_identity_mismatch_without_catalog_entry() {
1908 use super::{
1909 FileModelSource, InstallMode, ModelFetchRequest, ModelId, ModelInstaller,
1910 ModelSourceReference,
1911 };
1912 use std::sync::Arc;
1913 let root = std::env::temp_dir().join(format!("ml-runtime-mismatch-{}", std::process::id()));
1914 let source = root.join("source");
1915 fs::create_dir_all(source.join("artifacts")).unwrap();
1916 fs::write(
1917 source.join("manifest.json"),
1918 r#"{"id":"other","model_version":"1.0.0","format":"unknown","artifact":"artifacts/model.bin"}"#,
1919 )
1920 .unwrap();
1921 fs::write(source.join("artifacts/model.bin"), b"model").unwrap();
1922 let catalog = Arc::new(FilesystemModelCatalog::new(root.join("models")));
1923 let installer = ModelInstaller::new(root.join("models")).with_catalog(Arc::clone(&catalog));
1924 let request = ModelFetchRequest {
1925 model: ModelId::new("requested", "1.0.0").unwrap(),
1926 source: ModelSourceReference::Path(source),
1927 };
1928 assert!(matches!(
1929 installer
1930 .install(
1931 &FileModelSource::new(),
1932 &request,
1933 InstallMode::KeepExisting,
1934 None
1935 )
1936 .await,
1937 Err(super::AcquisitionError::IdentityMismatch { .. })
1938 ));
1939 assert!(catalog.list().await.unwrap().is_empty());
1940 fs::remove_dir_all(root).unwrap();
1941 }
1942}