Skip to main content

onnx_model_package/
lib.rs

1//! ORT model-package directory parsing, variant selection, and path resolution.
2
3use std::collections::BTreeMap;
4use std::fs;
5use std::path::{Component as PathComponent, Path, PathBuf};
6
7use indexmap::IndexMap;
8use serde::Deserialize;
9use serde_json::{Map, Value};
10use thiserror::Error;
11
12const MANIFEST_FILE: &str = "manifest.json";
13const COMPONENT_FILE: &str = "component.json";
14const MAX_JSON_BYTES: u64 = 4 * 1024 * 1024;
15
16/// Errors produced while opening, selecting, resolving, or validating a package.
17#[derive(Debug, Error)]
18pub enum PackageError {
19    #[error("failed to read {path}: {source}")]
20    Io {
21        path: PathBuf,
22        #[source]
23        source: std::io::Error,
24    },
25    #[error("invalid JSON in {path}: {source}")]
26    Json {
27        path: PathBuf,
28        #[source]
29        source: serde_json::Error,
30    },
31    #[error("invalid model package: {0}")]
32    Invalid(String),
33    #[error("component '{0}' was not found")]
34    UnknownComponent(String),
35    #[error("variant '{variant}' was not found in component '{component}'")]
36    UnknownVariant { component: String, variant: String },
37    #[error("no variant in component '{component}' matches {request}")]
38    NoMatchingVariant { component: String, request: String },
39}
40
41/// ORT package layout policy declared inside the (untrusted) manifest.
42#[derive(Debug, Clone, Copy, Default, Deserialize, PartialEq, Eq)]
43#[serde(rename_all = "lowercase")]
44pub enum PackageLayout {
45    /// All references must remain under the package root or a shared asset.
46    #[default]
47    Portable,
48    /// References may use absolute paths or parent traversal, but only when the
49    /// embedding application has separately opted in via
50    /// [`HostTrust::AllowInstalledLayout`]. The manifest declaring this layout
51    /// is never, on its own, sufficient to escape the package root.
52    Installed,
53}
54
55/// Caller-supplied trust policy governing whether an `installed`-layout package
56/// may resolve references outside the package root.
57///
58/// Packages are untrusted input (see `docs/genai/MODEL_PACKAGE.md` ยง7), so the
59/// manifest's own `layout` field must never be able to grant itself
60/// filesystem-escape privileges. Confinement is therefore always enforced
61/// unless the embedding application explicitly passes
62/// [`HostTrust::AllowInstalledLayout`], which it should only do for packages it
63/// has itself installed into a trusted location.
64#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
65pub enum HostTrust {
66    /// Always confine every reference to the package root, regardless of the
67    /// manifest `layout`. The safe default for downloaded/untrusted packages.
68    #[default]
69    Confined,
70    /// Permit `installed`-layout manifests to use absolute paths and `..`.
71    /// Only pass this for packages the host itself trusts.
72    AllowInstalledLayout,
73}
74
75/// An ORT 1.x package manifest.
76#[derive(Debug, Clone, Deserialize)]
77pub struct Manifest {
78    pub schema_version: String,
79    pub package_name: Option<String>,
80    pub package_version: Option<String>,
81    pub description: Option<String>,
82    #[serde(default)]
83    pub layout: PackageLayout,
84    pub components: IndexMap<String, ComponentReference>,
85    #[serde(default)]
86    pub shared_assets: BTreeMap<String, String>,
87    #[serde(default)]
88    pub additional_metadata: Map<String, Value>,
89    #[serde(flatten)]
90    pub unknown_fields: Map<String, Value>,
91}
92
93/// An inline component or a path to a component JSON file/directory.
94#[derive(Debug, Clone, Deserialize)]
95#[serde(untagged)]
96pub enum ComponentReference {
97    Inline(Box<Component>),
98    External(String),
99}
100
101/// A package component containing named executable variants.
102#[derive(Debug, Clone, Deserialize)]
103pub struct Component {
104    pub component_name: String,
105    pub variants: IndexMap<String, Variant>,
106    #[serde(default)]
107    pub additional_metadata: Map<String, Value>,
108    #[serde(flatten)]
109    pub unknown_fields: Map<String, Value>,
110}
111
112/// A named component variant.
113#[derive(Debug, Clone, Deserialize)]
114pub struct Variant {
115    pub variant_directory: String,
116    pub ep: Option<String>,
117    pub device: Option<String>,
118    pub compatibility_string: Option<String>,
119    #[serde(default)]
120    pub executor_info: Map<String, Value>,
121    #[serde(default)]
122    pub additional_metadata: Map<String, Value>,
123    #[serde(flatten)]
124    pub unknown_fields: Map<String, Value>,
125}
126
127/// Common executable fields understood from `executor_info["nxrt"]` or
128/// `executor_info["ort"]`.
129#[derive(Debug, Clone, Deserialize)]
130pub struct ExecutorInfo {
131    pub schema_version: Option<String>,
132    pub model_file: String,
133    pub genai_config: Option<String>,
134    pub inference_metadata: Option<String>,
135    pub tokenizer: Option<String>,
136    #[serde(default)]
137    pub session_options: BTreeMap<String, String>,
138    #[serde(default)]
139    pub provider_options: BTreeMap<String, String>,
140    #[serde(flatten)]
141    pub unknown_fields: Map<String, Value>,
142}
143
144/// Requested package variant attributes.
145#[derive(Debug, Clone, Default, PartialEq, Eq)]
146pub struct SelectionRequest {
147    pub variant: Option<String>,
148    pub execution_provider: Option<String>,
149    pub precision: Option<String>,
150}
151
152impl SelectionRequest {
153    /// Select a specific named variant.
154    #[must_use]
155    pub fn named(name: impl Into<String>) -> Self {
156        Self {
157            variant: Some(name.into()),
158            ..Self::default()
159        }
160    }
161
162    /// Select the first manifest-ordered variant matching an execution provider.
163    #[must_use]
164    pub fn for_execution_provider(execution_provider: impl Into<String>) -> Self {
165        Self {
166            execution_provider: Some(execution_provider.into()),
167            ..Self::default()
168        }
169    }
170}
171
172/// Fully resolved files for one selected variant.
173#[derive(Debug, Clone, PartialEq, Eq)]
174pub struct SelectedVariant {
175    pub component_name: String,
176    pub variant_name: String,
177    pub variant_directory: PathBuf,
178    pub model_path: PathBuf,
179    pub genai_config_path: Option<PathBuf>,
180    pub inference_metadata_path: Option<PathBuf>,
181    pub tokenizer_directory: Option<PathBuf>,
182}
183
184/// Open, parsed ORT model-package directory.
185#[derive(Debug, Clone)]
186pub struct ModelPackage {
187    root: PathBuf,
188    manifest: Manifest,
189    trust: HostTrust,
190}
191
192impl ModelPackage {
193    /// Open and structurally validate a package directory, confining every
194    /// reference to the package root regardless of the manifest `layout`.
195    ///
196    /// This is the safe entry point for untrusted (e.g. downloaded) packages.
197    pub fn open(root: impl AsRef<Path>) -> Result<Self, PackageError> {
198        Self::open_with_trust(root, HostTrust::Confined)
199    }
200
201    /// Open a package with an explicit caller-supplied trust policy.
202    ///
203    /// Pass [`HostTrust::AllowInstalledLayout`] only for packages the embedding
204    /// application itself trusts; with it, `installed`-layout manifests may
205    /// resolve absolute paths and `..` outside the package root. The default
206    /// [`HostTrust::Confined`] (used by [`ModelPackage::open`]) never permits
207    /// such escapes, even when the manifest declares `"layout": "installed"`.
208    pub fn open_with_trust(root: impl AsRef<Path>, trust: HostTrust) -> Result<Self, PackageError> {
209        let root = root.as_ref();
210        if !root.is_dir() {
211            return Err(PackageError::Invalid(format!(
212                "package directory does not exist: {}",
213                root.display()
214            )));
215        }
216        let manifest_path = root.join(MANIFEST_FILE);
217        let manifest: Manifest = read_json(&manifest_path)?;
218        validate_version(&manifest.schema_version, "package")?;
219        if manifest.components.is_empty() {
220            return Err(PackageError::Invalid(
221                "manifest components must not be empty".to_string(),
222            ));
223        }
224        let root = root.canonicalize().map_err(|source| PackageError::Io {
225            path: root.to_path_buf(),
226            source,
227        })?;
228        Ok(Self {
229            root,
230            manifest,
231            trust,
232        })
233    }
234
235    /// Return the parsed package manifest.
236    #[must_use]
237    pub fn manifest(&self) -> &Manifest {
238        &self.manifest
239    }
240
241    /// Select and resolve one executable component variant.
242    pub fn select(
243        &self,
244        component_name: &str,
245        request: &SelectionRequest,
246    ) -> Result<SelectedVariant, PackageError> {
247        let component = self.load_component(component_name)?;
248        let (variant_name, variant) = if let Some(requested_name) = &request.variant {
249            component
250                .variants
251                .get_key_value(requested_name)
252                .ok_or_else(|| PackageError::UnknownVariant {
253                    component: component_name.to_string(),
254                    variant: requested_name.clone(),
255                })?
256        } else {
257            component
258                .variants
259                .iter()
260                .find(|(_, variant)| variant_matches(variant, request))
261                .ok_or_else(|| PackageError::NoMatchingVariant {
262                    component: component_name.to_string(),
263                    request: describe_request(request),
264                })?
265        };
266
267        self.resolve_selected(component_name, variant_name, variant)
268    }
269
270    /// Validate every component, variant, executor payload, and referenced file.
271    pub fn validate(&self) -> Result<(), PackageError> {
272        for component_name in self.manifest.components.keys() {
273            let component = self.load_component(component_name)?;
274            if component.component_name != *component_name {
275                return Err(PackageError::Invalid(format!(
276                    "component map key '{component_name}' does not match component_name '{}'",
277                    component.component_name
278                )));
279            }
280            if component.variants.is_empty() {
281                return Err(PackageError::Invalid(format!(
282                    "component '{component_name}' has no variants"
283                )));
284            }
285            for (variant_name, variant) in &component.variants {
286                self.resolve_selected(component_name, variant_name, variant)?;
287            }
288        }
289        Ok(())
290    }
291
292    fn load_component(&self, name: &str) -> Result<Component, PackageError> {
293        let reference = self
294            .manifest
295            .components
296            .get(name)
297            .ok_or_else(|| PackageError::UnknownComponent(name.to_string()))?;
298        match reference {
299            ComponentReference::Inline(component) => Ok(component.as_ref().clone()),
300            ComponentReference::External(reference) => {
301                let mut path = self.resolve_path(&self.root, reference, true)?;
302                if path.is_dir() {
303                    // The implicit `component.json` under an external component
304                    // directory must pass the same confinement check as any
305                    // other reference; a symlinked component.json could
306                    // otherwise escape the package root.
307                    path = self.canonicalize_confined(&path.join(COMPONENT_FILE))?;
308                }
309                read_json(&path)
310            }
311        }
312    }
313
314    fn resolve_selected(
315        &self,
316        component_name: &str,
317        variant_name: &str,
318        variant: &Variant,
319    ) -> Result<SelectedVariant, PackageError> {
320        let variant_directory = self.resolve_path(&self.root, &variant.variant_directory, true)?;
321        if !variant_directory.is_dir() {
322            return Err(PackageError::Invalid(format!(
323                "variant '{variant_name}' directory is not a directory: {}",
324                variant_directory.display()
325            )));
326        }
327        let executor_info = self.load_executor_info(variant_name, variant, &variant_directory)?;
328        if let Some(version) = &executor_info.schema_version {
329            validate_version(version, "executor")?;
330        }
331        let model_path = self.resolve_path(&variant_directory, &executor_info.model_file, true)?;
332        ensure_file(&model_path, "model_file")?;
333        let genai_config_path = self.resolve_optional_file(
334            &variant_directory,
335            executor_info.genai_config.as_deref(),
336            "genai_config",
337        )?;
338        let inference_metadata_path = self.resolve_optional_file(
339            &variant_directory,
340            executor_info.inference_metadata.as_deref(),
341            "inference_metadata",
342        )?;
343        let tokenizer_directory = executor_info
344            .tokenizer
345            .as_deref()
346            .map(|reference| self.resolve_path(&variant_directory, reference, true))
347            .transpose()?;
348        if let Some(path) = &tokenizer_directory
349            && !path.is_dir()
350        {
351            return Err(PackageError::Invalid(format!(
352                "tokenizer reference is not a directory: {}",
353                path.display()
354            )));
355        }
356        for (key, reference) in &executor_info.session_options {
357            if matches!(
358                key.as_str(),
359                "session.model_external_initializers_file_folder_path" | "ep.context_file_path"
360            ) {
361                self.resolve_path(&variant_directory, reference, true)?;
362            }
363        }
364        Ok(SelectedVariant {
365            component_name: component_name.to_string(),
366            variant_name: variant_name.to_string(),
367            variant_directory,
368            model_path,
369            genai_config_path,
370            inference_metadata_path,
371            tokenizer_directory,
372        })
373    }
374
375    fn load_executor_info(
376        &self,
377        variant_name: &str,
378        variant: &Variant,
379        variant_directory: &Path,
380    ) -> Result<ExecutorInfo, PackageError> {
381        let (namespace, value) = variant
382            .executor_info
383            .get_key_value("nxrt")
384            .or_else(|| variant.executor_info.get_key_value("ort"))
385            .ok_or_else(|| {
386                PackageError::Invalid(format!(
387                    "variant '{variant_name}' has no executor_info.nxrt or executor_info.ort"
388                ))
389            })?;
390        match value {
391            Value::String(reference) => {
392                let path = self.resolve_path(variant_directory, reference, true)?;
393                read_json(&path)
394            }
395            Value::Object(_) => serde_json::from_value(value.clone()).map_err(|source| {
396                PackageError::Json {
397                    path: PathBuf::from(format!(
398                        "{MANIFEST_FILE}:components.*.variants.{variant_name}.executor_info.{namespace}"
399                    )),
400                    source,
401                }
402            }),
403            _ => Err(PackageError::Invalid(format!(
404                "executor_info.{namespace} for variant '{variant_name}' must be an object or path"
405            ))),
406        }
407    }
408
409    fn resolve_optional_file(
410        &self,
411        base: &Path,
412        reference: Option<&str>,
413        field: &str,
414    ) -> Result<Option<PathBuf>, PackageError> {
415        reference
416            .map(|reference| {
417                let path = self.resolve_path(base, reference, true)?;
418                ensure_file(&path, field)?;
419                Ok(path)
420            })
421            .transpose()
422    }
423
424    /// Whether references must be confined to the package root. Confinement is
425    /// always enforced unless the manifest declares the `installed` layout AND
426    /// the caller explicitly opted in via [`HostTrust::AllowInstalledLayout`].
427    fn confinement_enforced(&self) -> bool {
428        !(self.manifest.layout == PackageLayout::Installed
429            && self.trust == HostTrust::AllowInstalledLayout)
430    }
431
432    /// Canonicalize an existing path (resolving symlinks) and, when confinement
433    /// is enforced, reject it if the real path escapes the package root.
434    fn canonicalize_confined(&self, path: &Path) -> Result<PathBuf, PackageError> {
435        if !path.exists() {
436            return Err(PackageError::Invalid(format!(
437                "referenced path does not exist: {}",
438                path.display()
439            )));
440        }
441        let canonical = path.canonicalize().map_err(|source| PackageError::Io {
442            path: path.to_path_buf(),
443            source,
444        })?;
445        if self.confinement_enforced() && !canonical.starts_with(&self.root) {
446            return Err(PackageError::Invalid(format!(
447                "package reference resolves outside package root: {}",
448                path.display()
449            )));
450        }
451        Ok(canonical)
452    }
453
454    fn resolve_path(
455        &self,
456        base: &Path,
457        reference: &str,
458        must_exist: bool,
459    ) -> Result<PathBuf, PackageError> {
460        let path = if let Some(asset_reference) = reference.strip_prefix("sha256:") {
461            self.resolve_shared_asset(asset_reference)?
462        } else {
463            let reference_path = Path::new(reference);
464            if self.confinement_enforced() {
465                validate_portable_reference(reference_path)?;
466            }
467            if reference_path.is_absolute() {
468                reference_path.to_path_buf()
469            } else {
470                base.join(reference_path)
471            }
472        };
473        if must_exist {
474            return self.canonicalize_confined(&path);
475        }
476        Ok(path)
477    }
478
479    fn resolve_shared_asset(&self, reference: &str) -> Result<PathBuf, PackageError> {
480        let (digest, tail) = reference
481            .split_once('/')
482            .map_or((reference, None), |(digest, tail)| (digest, Some(tail)));
483        if digest.len() != 64
484            || !digest
485                .bytes()
486                .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
487        {
488            return Err(PackageError::Invalid(format!(
489                "invalid sha256 shared-asset reference: sha256:{reference}"
490            )));
491        }
492        let override_path = self
493            .manifest
494            .shared_assets
495            .get(&format!("sha256:{digest}"))
496            .or_else(|| self.manifest.shared_assets.get(digest));
497        let root = override_path.map_or_else(
498            || {
499                Ok(self
500                    .root
501                    .join("shared_assets")
502                    .join(format!("sha256-{digest}")))
503            },
504            |reference| {
505                let path = Path::new(reference);
506                if self.confinement_enforced() {
507                    validate_portable_reference(path)?;
508                }
509                Ok(if path.is_absolute() {
510                    path.to_path_buf()
511                } else {
512                    self.root.join(path)
513                })
514            },
515        )?;
516        let path = tail.map_or(root.clone(), |tail| root.join(tail));
517        self.canonicalize_confined(&path)
518    }
519}
520
521/// Probe whether a directory contains an ORT package manifest, while avoiding
522/// unrelated fixture/application files also named `manifest.json`.
523#[must_use]
524pub fn is_model_package_directory(path: impl AsRef<Path>) -> bool {
525    let path = path.as_ref();
526    let Ok(bytes) = fs::read(path.join(MANIFEST_FILE)) else {
527        return false;
528    };
529    let Ok(value) = serde_json::from_slice::<Value>(&bytes) else {
530        return has_package_suffix(path);
531    };
532    value.get("schema_version").is_some() && value.get("components").is_some()
533        || has_package_suffix(path)
534}
535
536fn has_package_suffix(path: &Path) -> bool {
537    path.extension().is_some_and(|extension| {
538        extension.eq_ignore_ascii_case("ortpackage") || extension.eq_ignore_ascii_case("nxpackage")
539    })
540}
541
542fn read_json<T: for<'de> Deserialize<'de>>(path: &Path) -> Result<T, PackageError> {
543    let metadata = fs::metadata(path).map_err(|source| PackageError::Io {
544        path: path.to_path_buf(),
545        source,
546    })?;
547    if metadata.len() > MAX_JSON_BYTES {
548        return Err(PackageError::Invalid(format!(
549            "JSON file exceeds {MAX_JSON_BYTES} bytes: {}",
550            path.display()
551        )));
552    }
553    let bytes = fs::read(path).map_err(|source| PackageError::Io {
554        path: path.to_path_buf(),
555        source,
556    })?;
557    serde_json::from_slice(&bytes).map_err(|source| PackageError::Json {
558        path: path.to_path_buf(),
559        source,
560    })
561}
562
563fn validate_version(version: &str, kind: &str) -> Result<(), PackageError> {
564    let (major, minor) = version.split_once('.').ok_or_else(|| {
565        PackageError::Invalid(format!("{kind} schema_version must be '<major>.<minor>'"))
566    })?;
567    let major = major.parse::<u64>().map_err(|_| {
568        PackageError::Invalid(format!("{kind} schema_version has a non-numeric major"))
569    })?;
570    minor.parse::<u64>().map_err(|_| {
571        PackageError::Invalid(format!("{kind} schema_version has a non-numeric minor"))
572    })?;
573    if major != 1 {
574        return Err(PackageError::Invalid(format!(
575            "unsupported {kind} schema major version {major}; supported major is 1"
576        )));
577    }
578    Ok(())
579}
580
581fn validate_portable_reference(path: &Path) -> Result<(), PackageError> {
582    if path.as_os_str().is_empty()
583        || path.is_absolute()
584        || path.components().any(|component| {
585            matches!(
586                component,
587                PathComponent::ParentDir | PathComponent::RootDir | PathComponent::Prefix(_)
588            )
589        })
590    {
591        return Err(PackageError::Invalid(format!(
592            "portable package reference escapes its base: {}",
593            path.display()
594        )));
595    }
596    Ok(())
597}
598
599fn ensure_file(path: &Path, field: &str) -> Result<(), PackageError> {
600    if path.is_file() {
601        Ok(())
602    } else {
603        Err(PackageError::Invalid(format!(
604            "{field} is not a file: {}",
605            path.display()
606        )))
607    }
608}
609
610fn variant_matches(variant: &Variant, request: &SelectionRequest) -> bool {
611    let execution_provider_matches = request.execution_provider.as_ref().is_none_or(|requested| {
612        variant
613            .ep
614            .as_ref()
615            .is_some_and(|actual| actual.eq_ignore_ascii_case(requested))
616    });
617    let precision_matches = request.precision.as_ref().is_none_or(|requested| {
618        variant
619            .additional_metadata
620            .get("precision")
621            .and_then(Value::as_str)
622            .is_some_and(|actual| actual.eq_ignore_ascii_case(requested))
623    });
624    execution_provider_matches && precision_matches
625}
626
627fn describe_request(request: &SelectionRequest) -> String {
628    let mut attributes = Vec::new();
629    if let Some(execution_provider) = &request.execution_provider {
630        attributes.push(format!("execution provider '{execution_provider}'"));
631    }
632    if let Some(precision) = &request.precision {
633        attributes.push(format!("precision '{precision}'"));
634    }
635    if attributes.is_empty() {
636        "the default selection".to_string()
637    } else {
638        attributes.join(" and ")
639    }
640}