Skip to main content

hyperlight_host/sandbox/snapshot/file/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2025 The Hyperlight Authors.
3
4//! OCI Image Layout serde for [`Snapshot`]. See
5//! `docs/snapshot-oci-format.md` for the on-disk format.
6
7mod config;
8mod digest;
9mod fsutil;
10mod media_types;
11pub(crate) mod reference;
12mod transport;
13
14use std::path::{Path, PathBuf};
15
16use hyperlight_common::flatbuffer_wrappers::host_function_details::HostFunctionDetails;
17use hyperlight_common::vmem::PAGE_SIZE;
18use oci_spec::image::{
19    Descriptor, DescriptorBuilder, ImageIndex, ImageIndexBuilder, ImageManifest,
20    ImageManifestBuilder, MediaType, SCHEMA_VERSION,
21};
22
23use self::config::{Arch, CpuVendor, HostFunction, Hypervisor, MemoryLayout, OciSnapshotConfig};
24use self::digest::{Digest256, oci_digest, parse_oci_digest, verify_blob_bytes, verify_blob_file};
25use self::fsutil::{put_blob, put_blob_if_absent, read_bounded, replace_file_atomic};
26use self::media_types::{
27    ANNOTATION_ARCH, ANNOTATION_CPU, ANNOTATION_HYPERVISOR, ANNOTATION_REF_NAME,
28};
29pub(super) use self::media_types::{
30    MT_CONFIG_CURRENT, MT_CONFIG_V1, MT_CONFIG_V2, MT_CONFIG_V3, MT_SNAPSHOT_CURRENT,
31    MT_SNAPSHOT_V1, MT_TRANSPORT_CURRENT, MT_TRANSPORT_V1, SNAPSHOT_ABI_VERSION,
32};
33use self::reference::{OciDigest, OciReference, OciTag};
34use super::{NextAction, Snapshot};
35use crate::mem::layout::SandboxMemoryLayout;
36use crate::mem::memory_region::MemoryRegionFlags;
37use crate::mem::shared_mem::{ReadonlySharedMemory, SharedMemory};
38
39pub(super) const OCI_LAYOUT_VERSION: &str = "1.0.0";
40
41/// Short golden-tag token for the host CPU vendor, or `None` if the
42/// goldens do not cover it. Exposed for the snapshot golden tests so
43/// they share the host crate's vendor detection.
44#[doc(hidden)]
45pub fn host_cpu_vendor_golden_tag() -> Option<&'static str> {
46    CpuVendor::current().golden_tag()
47}
48
49/// Maximum size of any JSON blob read from disk during load:
50/// `oci-layout`, `index.json`, the OCI image manifest, and the
51/// Hyperlight config blob. Bounds the allocation done before parsing.
52const MAX_JSON_BLOB_SIZE: u64 = 1024 * 1024;
53
54/// Reject a JSON artifact larger than the cap the loader reads with
55/// [`read_bounded`]. The writer holds to the same cap so every layout
56/// it writes can be read back. `what` names the artifact in the error.
57fn check_json_blob_size(what: &str, len: usize) -> crate::Result<()> {
58    if len as u64 > MAX_JSON_BLOB_SIZE {
59        return Err(crate::new_error!(
60            "{} of {} bytes exceeds the {} byte maximum for a snapshot artifact",
61            what,
62            len,
63            MAX_JSON_BLOB_SIZE
64        ));
65    }
66    Ok(())
67}
68
69/// Select one manifest descriptor from `index` by `reference`.
70///
71/// A tag matches the `org.opencontainers.image.ref.name` annotation
72/// and must be unique. A digest matches the manifest content digest.
73/// Identical manifests shared across tags select the first, since
74/// they are byte-for-byte equal.
75fn select_manifest<'a>(
76    index: &'a ImageIndex,
77    reference: &OciReference,
78    path: &Path,
79) -> crate::Result<&'a Descriptor> {
80    match reference {
81        OciReference::Tag(tag) => {
82            let mut matching = index.manifests().iter().filter(|d| {
83                d.annotations()
84                    .as_ref()
85                    .and_then(|a| a.get(ANNOTATION_REF_NAME))
86                    .map(|s| s.as_str() == tag.as_str())
87                    .unwrap_or(false)
88            });
89            match (matching.next(), matching.next()) {
90                (None, _) => {
91                    let known: Vec<&str> = index
92                        .manifests()
93                        .iter()
94                        .filter_map(|d| {
95                            d.annotations()
96                                .as_ref()
97                                .and_then(|a| a.get(ANNOTATION_REF_NAME))
98                                .map(|s| s.as_str())
99                        })
100                        .collect();
101                    Err(crate::new_error!(
102                        "no manifest tagged {:?} in OCI layout {:?}. Available tags: {:?}",
103                        tag.as_str(),
104                        path,
105                        known
106                    ))
107                }
108                (Some(_), Some(_)) => Err(crate::new_error!(
109                    "OCI layout {:?} has multiple manifests tagged {:?}; tags must be unique",
110                    path,
111                    tag.as_str()
112                )),
113                (Some(d), None) => Ok(d),
114            }
115        }
116        OciReference::Digest(digest) => index
117            .manifests()
118            .iter()
119            .find(|d| d.digest().to_string() == digest.as_str())
120            .ok_or_else(|| {
121                crate::new_error!(
122                    "no manifest with digest {} in OCI layout {:?}",
123                    digest.as_str(),
124                    path
125                )
126            }),
127    }
128}
129
130fn read_layout_marker(path: &Path) -> crate::Result<()> {
131    let layout_bytes = read_bounded(&path.join("oci-layout"), MAX_JSON_BLOB_SIZE)
132        .map_err(|e| crate::new_error!("failed to read oci-layout: {}", e))?;
133    let layout_json: serde_json::Value = serde_json::from_slice(&layout_bytes)
134        .map_err(|e| crate::new_error!("oci-layout is not valid JSON: {}", e))?;
135    let v = layout_json
136        .get("imageLayoutVersion")
137        .and_then(|v| v.as_str())
138        .ok_or_else(|| crate::new_error!("oci-layout missing imageLayoutVersion field"))?;
139    if v != OCI_LAYOUT_VERSION {
140        return Err(crate::new_error!(
141            "unsupported OCI image layout version {:?} (expected {:?})",
142            v,
143            OCI_LAYOUT_VERSION
144        ));
145    }
146    Ok(())
147}
148
149fn load_manifest(
150    path: &Path,
151    blobs_dir: &Path,
152    reference: &OciReference,
153    verify_blobs: bool,
154) -> crate::Result<ImageManifest> {
155    let index_bytes = read_bounded(&path.join("index.json"), MAX_JSON_BLOB_SIZE)
156        .map_err(|e| crate::new_error!("failed to read index.json: {}", e))?;
157    let index: ImageIndex = serde_json::from_slice(&index_bytes)
158        .map_err(|e| crate::new_error!("failed to parse index.json: {}", e))?;
159    if index.schema_version() != SCHEMA_VERSION {
160        return Err(crate::new_error!(
161            "unsupported OCI index schemaVersion {} (expected {})",
162            index.schema_version(),
163            SCHEMA_VERSION
164        ));
165    }
166    if let Some(media_type) = index.media_type()
167        && !matches!(media_type, MediaType::ImageIndex)
168    {
169        return Err(crate::new_error!(
170            "OCI index has unexpected media type {} (expected {})",
171            media_type.to_string(),
172            MediaType::ImageIndex.to_string()
173        ));
174    }
175    let manifest_desc = select_manifest(&index, reference, path)?;
176    if !matches!(manifest_desc.media_type(), MediaType::ImageManifest) {
177        return Err(crate::new_error!(
178            "manifest descriptor for {} has unexpected media type {} (expected {})",
179            reference,
180            manifest_desc.media_type().to_string(),
181            MediaType::ImageManifest.to_string()
182        ));
183    }
184    let manifest_bytes = load_blob(
185        "manifest",
186        blobs_dir,
187        manifest_desc,
188        MAX_JSON_BLOB_SIZE,
189        verify_blobs,
190    )?;
191    let manifest: ImageManifest = serde_json::from_slice(&manifest_bytes)
192        .map_err(|e| crate::new_error!("failed to parse OCI manifest JSON: {}", e))?;
193    if manifest.schema_version() != SCHEMA_VERSION {
194        return Err(crate::new_error!(
195            "unsupported OCI manifest schemaVersion {} (expected {})",
196            manifest.schema_version(),
197            SCHEMA_VERSION
198        ));
199    }
200    if let Some(media_type) = manifest.media_type()
201        && !matches!(media_type, MediaType::ImageManifest)
202    {
203        return Err(crate::new_error!(
204            "OCI manifest has unexpected media type {} (expected {})",
205            media_type.to_string(),
206            MediaType::ImageManifest.to_string()
207        ));
208    }
209    Ok(manifest)
210}
211
212fn load_config(
213    blobs_dir: &Path,
214    cfg_desc: &Descriptor,
215    verify_blobs: bool,
216) -> crate::Result<OciSnapshotConfig> {
217    let cfg_bytes = load_blob(
218        "config",
219        blobs_dir,
220        cfg_desc,
221        MAX_JSON_BLOB_SIZE,
222        verify_blobs,
223    )?;
224    let cfg: OciSnapshotConfig = serde_json::from_slice(&cfg_bytes)
225        .map_err(|e| crate::new_error!("failed to parse Hyperlight config JSON: {}", e))?;
226    cfg.validate_for_load()?;
227    Ok(cfg)
228}
229
230fn open_snapshot_blob(
231    blobs_dir: &Path,
232    snap_desc: &Descriptor,
233    expected_blob_len: u64,
234    verify_blobs: bool,
235) -> crate::Result<std::fs::File> {
236    let snap_hex = parse_oci_digest(snap_desc.digest())?;
237    let snap_path = blobs_dir.join(&snap_hex);
238
239    let mut snap_file = self::fsutil::open_no_follow(&snap_path)?;
240
241    let snap_file_len = snap_file
242        .metadata()
243        .map_err(|e| crate::new_error!("failed to stat snapshot blob: {}", e))?
244        .len();
245    if snap_file_len != expected_blob_len {
246        return Err(crate::new_error!(
247            "snapshot blob size mismatch: file is {} bytes, expected {} (memory_size)",
248            snap_file_len,
249            expected_blob_len,
250        ));
251    }
252    if snap_file_len != snap_desc.size() {
253        return Err(crate::new_error!(
254            "snapshot blob size {} disagrees with OCI descriptor size {}",
255            snap_file_len,
256            snap_desc.size()
257        ));
258    }
259    if verify_blobs {
260        verify_blob_file("snapshot", &mut snap_file, &snap_hex)?;
261    }
262    Ok(snap_file)
263}
264
265/// Read a bounded OCI blob and check its descriptor size and optional digest.
266fn load_blob(
267    label: &str,
268    blobs_dir: &Path,
269    descriptor: &Descriptor,
270    max_size: u64,
271    verify_blobs: bool,
272) -> crate::Result<Vec<u8>> {
273    let hex = parse_oci_digest(descriptor.digest())?;
274    let bytes = read_bounded(&blobs_dir.join(&hex), max_size)?;
275    if bytes.len() as u64 != descriptor.size() {
276        return Err(crate::new_error!(
277            "{label} blob size mismatch: descriptor says {}, file is {}",
278            descriptor.size(),
279            bytes.len()
280        ));
281    }
282    if verify_blobs {
283        verify_blob_bytes(label, &bytes, &hex)?;
284    }
285    Ok(bytes)
286}
287
288impl Snapshot {
289    /// Save this snapshot into an OCI Image Layout directory on disk.
290    /// The saved snapshot can be loaded later with
291    /// [`Snapshot::load`].
292    ///
293    /// Returns the [`OciDigest`] of the manifest that was written,
294    /// which [`Snapshot::load`] accepts as a stable handle to
295    /// this exact snapshot.
296    ///
297    /// # `path`
298    ///
299    /// The OCI Image Layout directory to write to. The directory at
300    /// `path` is created if absent. Its parent directory must exist.
301    ///
302    /// If `path` holds no OCI layout, a new one is created. If it
303    /// holds one, this snapshot is added alongside the others. If
304    /// `path` holds something that is not a readable OCI layout, the
305    /// call fails and the directory is left unchanged.
306    ///
307    /// # `tag`
308    ///
309    /// A standard OCI tag that names this snapshot within the layout.
310    /// [`Snapshot::load`] can load the snapshot back by this tag.
311    ///
312    /// A tag points to one snapshot at a time. If the layout has a
313    /// snapshot under this tag, the tag is moved to the new snapshot.
314    /// The old snapshot's data stays on disk, reachable by its
315    /// digest but not by this tag. Snapshots under other tags are
316    /// untouched.
317    ///
318    /// # Portability
319    ///
320    /// Snapshot images are bound to the specific CPU architecture,
321    /// hypervisor, and CPU vendor that the snapshot was created on.
322    /// For example, a snapshot taken on an Intel x86_64 host with KVM
323    /// can only be loaded on an Intel x86_64 host running KVM. Loading
324    /// on any other host is rejected. A future version may relax this
325    /// binding once a wider compatibility set is proven safe.
326    ///
327    /// # Compatibility
328    ///
329    /// While Hyperlight is at version 0.x.y the on-disk format is not
330    /// stable. A snapshot written by one Hyperlight version is not
331    /// guaranteed to load on a different Hyperlight version. An
332    /// incompatible snapshot is always rejected at load time with a
333    /// clear error. It can never load and then misbehave once the
334    /// guest is running. Any release that breaks the format is called
335    /// out in the Hyperlight changelog.
336    ///
337    /// # Examples
338    ///
339    /// ```no_run
340    /// # use hyperlight_host::SandboxBuilder;
341    /// # use hyperlight_host::sandbox::snapshot::OciTag;
342    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
343    /// let mut sandbox = SandboxBuilder::from_file("guest.bin").build()?;
344    ///
345    /// // Capture the initialized state and write it to an OCI layout on disk.
346    /// let snapshot = sandbox.snapshot()?;
347    /// let tag = OciTag::new("latest")?;
348    /// let digest = snapshot.save("./guest_snapshot", &tag)?;
349    /// # Ok(())
350    /// # }
351    /// ```
352    pub fn save(&self, path: impl AsRef<Path>, tag: &OciTag) -> crate::Result<OciDigest> {
353        let path = path.as_ref();
354
355        // Building the config can reject the snapshot. Do it before
356        // writing any file.
357        let cfg = self.build_config()?;
358        let cfg_bytes = serde_json::to_vec_pretty(&cfg)
359            .map_err(|e| crate::new_error!("failed to serialise config JSON: {}", e))?;
360        check_json_blob_size("config blob", cfg_bytes.len())?;
361
362        // The parent directory must already exist. `path` itself is
363        // created if absent. An existing regular file at `path` is
364        // rejected by the underlying `create_dir`.
365        match path.parent() {
366            Some(p) if !p.as_os_str().is_empty() => {
367                let parent_meta = std::fs::metadata(p).map_err(|e| {
368                    crate::new_error!("save: parent directory {:?} not accessible: {}", p, e)
369                })?;
370                if !parent_meta.is_dir() {
371                    return Err(crate::new_error!(
372                        "save: parent of {:?} is not a directory",
373                        path
374                    ));
375                }
376            }
377            _ => {}
378        }
379        match std::fs::create_dir(path) {
380            Ok(()) => {}
381            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
382                let meta = std::fs::metadata(path)
383                    .map_err(|e| crate::new_error!("save: failed to stat {:?}: {}", path, e))?;
384                if !meta.is_dir() {
385                    return Err(crate::new_error!(
386                        "save: {:?} exists and is not a directory",
387                        path
388                    ));
389                }
390            }
391            Err(e) => {
392                return Err(crate::new_error!(
393                    "save: failed to create layout dir {:?}: {}",
394                    path,
395                    e
396                ));
397            }
398        }
399
400        // Validate any pre-existing `oci-layout` marker before
401        // touching anything else, so a foreign layout (future
402        // version, hand-edited file) is reported without altering
403        // the directory.
404        let layout_marker = path.join("oci-layout");
405        let marker_existed = layout_marker
406            .try_exists()
407            .map_err(|e| crate::new_error!("save: failed to stat {:?}: {}", layout_marker, e))?;
408        if marker_existed {
409            let bytes = read_bounded(&layout_marker, MAX_JSON_BLOB_SIZE).map_err(|e| {
410                crate::new_error!("save: failed to read existing oci-layout: {}", e)
411            })?;
412            let v: serde_json::Value = serde_json::from_slice(&bytes).map_err(|e| {
413                crate::new_error!("save: existing oci-layout is not valid JSON: {}", e)
414            })?;
415            match v.get("imageLayoutVersion").and_then(|s| s.as_str()) {
416                Some(s) if s == OCI_LAYOUT_VERSION => {}
417                Some(other) => {
418                    return Err(crate::new_error!(
419                        "save: existing imageLayoutVersion {:?} is unsupported (expected {:?})",
420                        other,
421                        OCI_LAYOUT_VERSION
422                    ));
423                }
424                None => {
425                    return Err(crate::new_error!(
426                        "save: existing oci-layout is missing imageLayoutVersion"
427                    ));
428                }
429            }
430        }
431
432        let index_path = path.join("index.json");
433        let index_existed = index_path
434            .try_exists()
435            .map_err(|e| crate::new_error!("save: failed to stat {:?}: {}", index_path, e))?;
436        let mut manifests: Vec<Descriptor> = if index_existed {
437            let bytes = read_bounded(&index_path, MAX_JSON_BLOB_SIZE).map_err(|e| {
438                crate::new_error!("save: failed to read existing index.json: {}", e)
439            })?;
440            let existing: ImageIndex = serde_json::from_slice(&bytes).map_err(|e| {
441                crate::new_error!(
442                    "save: existing index.json is not a valid OCI image index: {}",
443                    e
444                )
445            })?;
446            existing.manifests().to_vec()
447        } else {
448            Vec::new()
449        };
450
451        let new_desc = self.write_blobs_and_build_descriptor(path, tag, &cfg, &cfg_bytes)?;
452        let written_digest = OciDigest::from_oci_spec_digest(new_desc.digest());
453
454        // Replacement is by tag, not by digest: a new snapshot may
455        // hash to a different value but still claim the same logical
456        // ref. Blobs from the replaced manifest become orphans.
457        manifests.retain(|d| {
458            d.annotations()
459                .as_ref()
460                .and_then(|a| a.get(ANNOTATION_REF_NAME))
461                .map(|s| s.as_str() != tag.as_str())
462                .unwrap_or(true)
463        });
464        manifests.push(new_desc);
465
466        let index = ImageIndexBuilder::default()
467            .schema_version(SCHEMA_VERSION)
468            .media_type(MediaType::ImageIndex)
469            .manifests(manifests)
470            .build()
471            .map_err(|e| crate::new_error!("failed to build OCI index: {}", e))?;
472        let index_bytes = serde_json::to_vec_pretty(&index)
473            .map_err(|e| crate::new_error!("failed to serialise OCI index: {}", e))?;
474        check_json_blob_size("index.json", index_bytes.len())?;
475
476        // Write the marker before the index swap. A loader that sees
477        // the new index requires the marker; ordering them this way
478        // keeps the layout valid at every step.
479        if !marker_existed {
480            let layout_bytes = serde_json::to_vec(&serde_json::json!({
481                "imageLayoutVersion": OCI_LAYOUT_VERSION,
482            }))
483            .map_err(|e| crate::new_error!("failed to serialise oci-layout: {}", e))?;
484            replace_file_atomic(&layout_marker, &layout_bytes)?;
485        }
486
487        // Index swap is the commit point.
488        replace_file_atomic(&index_path, &index_bytes)?;
489
490        Ok(written_digest)
491    }
492
493    fn write_blobs_and_build_descriptor(
494        &self,
495        dir: &Path,
496        tag: &OciTag,
497        cfg: &OciSnapshotConfig,
498        cfg_bytes: &[u8],
499    ) -> crate::Result<Descriptor> {
500        let memory_bytes = self.state.memory.as_slice();
501        let memory_size = memory_bytes.len();
502        if memory_size == 0 || !memory_size.is_multiple_of(PAGE_SIZE) {
503            return Err(crate::new_error!(
504                "snapshot memory size {} must be a non-zero multiple of PAGE_SIZE",
505                memory_size
506            ));
507        }
508
509        let blobs_dir = dir.join("blobs").join("sha256");
510        std::fs::create_dir_all(&blobs_dir).map_err(|e| {
511            crate::new_error!("failed to create OCI blobs dir {:?}: {}", blobs_dir, e)
512        })?;
513
514        // Snapshot blob: the raw memory bytes.
515        let snapshot_digest = Digest256::from_bytes(memory_bytes);
516        put_blob_if_absent(&blobs_dir, &snapshot_digest, memory_bytes)?;
517
518        // Transport blob: the canonical ring image omitted from memory.
519        let transport = self.state.virtq.as_ref().ok_or_else(|| {
520            crate::new_error!("initialized snapshot has no canonical transport state")
521        })?;
522        let transport_bytes = transport::encode(transport)?;
523        let transport_digest = Digest256::from_bytes(&transport_bytes);
524        put_blob(&blobs_dir, &transport_digest, &transport_bytes)?;
525
526        // Config blob.
527        let cfg_digest = Digest256::from_bytes(cfg_bytes);
528        put_blob(&blobs_dir, &cfg_digest, cfg_bytes)?;
529
530        // Manifest blob.
531        let config_descriptor = DescriptorBuilder::default()
532            .media_type(MediaType::Other(MT_CONFIG_CURRENT.to_string()))
533            .digest(oci_digest(&cfg_digest)?)
534            .size(cfg_bytes.len() as u64)
535            .build()
536            .map_err(|e| crate::new_error!("failed to build config descriptor: {}", e))?;
537        let snapshot_descriptor = DescriptorBuilder::default()
538            .media_type(MediaType::Other(MT_SNAPSHOT_CURRENT.to_string()))
539            .digest(oci_digest(&snapshot_digest)?)
540            .size(memory_size as u64)
541            .build()
542            .map_err(|e| crate::new_error!("failed to build snapshot descriptor: {}", e))?;
543        let transport_descriptor = DescriptorBuilder::default()
544            .media_type(MediaType::Other(MT_TRANSPORT_CURRENT.to_string()))
545            .digest(oci_digest(&transport_digest)?)
546            .size(transport_bytes.len() as u64)
547            .build()
548            .map_err(|e| crate::new_error!("failed to build transport descriptor: {}", e))?;
549        // `artifactType` is set equal to `config.mediaType` per OCI
550        // image-spec "Guidelines for Artifact Usage". Registries
551        // surface this on the distribution-spec referrers API. Tools
552        // that read only `config.mediaType` see the same value.
553        let manifest = ImageManifestBuilder::default()
554            .schema_version(SCHEMA_VERSION)
555            .media_type(MediaType::ImageManifest)
556            .artifact_type(MediaType::Other(MT_CONFIG_CURRENT.to_string()))
557            .config(config_descriptor)
558            .layers(vec![snapshot_descriptor, transport_descriptor])
559            .build()
560            .map_err(|e| crate::new_error!("failed to build OCI manifest: {}", e))?;
561        let manifest_bytes = serde_json::to_vec_pretty(&manifest)
562            .map_err(|e| crate::new_error!("failed to serialise OCI manifest: {}", e))?;
563        check_json_blob_size("manifest blob", manifest_bytes.len())?;
564        let manifest_digest = Digest256::from_bytes(&manifest_bytes);
565        put_blob(&blobs_dir, &manifest_digest, &manifest_bytes)?;
566
567        let mut anns = std::collections::HashMap::new();
568        anns.insert(ANNOTATION_REF_NAME.to_string(), tag.as_str().to_string());
569        anns.insert(ANNOTATION_ARCH.to_string(), cfg.arch.as_str().to_string());
570        anns.insert(
571            ANNOTATION_HYPERVISOR.to_string(),
572            cfg.hypervisor.as_str().to_string(),
573        );
574        anns.insert(
575            ANNOTATION_CPU.to_string(),
576            cfg.cpu_vendor.as_str().to_string(),
577        );
578        DescriptorBuilder::default()
579            .media_type(MediaType::ImageManifest)
580            .digest(oci_digest(&manifest_digest)?)
581            .size(manifest_bytes.len() as u64)
582            .annotations(anns)
583            .build()
584            .map_err(|e| crate::new_error!("failed to build manifest descriptor: {}", e))
585    }
586
587    fn build_config(&self) -> crate::Result<OciSnapshotConfig> {
588        let (entrypoint_addr, sregs) = match (self.state.next_action, self.state.sregs.as_ref()) {
589            (NextAction::Call(addr), Some(sregs)) => (addr, sregs),
590            (NextAction::Call(_), None) => {
591                return Err(crate::new_error!(
592                    "snapshot inconsistent: Call entrypoint must have sregs"
593                ));
594            }
595            (NextAction::Initialise(_), _) => {
596                return Err(crate::new_error!(
597                    "pre-init snapshots cannot be persisted. Only a snapshot taken after the guest has run can be saved to disk"
598                ));
599            }
600            #[cfg(test)]
601            (NextAction::None, _) => {
602                return Err(crate::new_error!(
603                    "snapshot with NextAction::None cannot be persisted"
604                ));
605            }
606        };
607
608        if self.state.virtq.is_none() {
609            return Err(crate::new_error!(
610                "initialized snapshot has no canonical transport state"
611            ));
612        }
613
614        let host_functions = match &self.state.host_functions.host_functions {
615            Some(v) => v.iter().map(HostFunction::from).collect(),
616            None => Vec::new(),
617        };
618
619        let l = &self.state.layout;
620        Ok(OciSnapshotConfig {
621            hyperlight_version: env!("CARGO_PKG_VERSION").to_string(),
622            arch: Arch::current(),
623            abi_version: SNAPSHOT_ABI_VERSION,
624            hypervisor: Hypervisor::current()
625                .ok_or_else(|| crate::new_error!("no hypervisor available to tag snapshot"))?,
626            cpu_vendor: CpuVendor::current(),
627            stack_top_gva: self.state.stack_top_gva,
628            entrypoint_addr,
629            original_entrypoint_addr: self.state.original_entrypoint,
630            sregs: *sregs,
631            #[cfg(target_arch = "x86_64")]
632            msrs: self
633                .state
634                .msrs
635                .as_ref()
636                .ok_or_else(|| crate::new_error!("snapshot has no MSR state"))?
637                .clone(),
638            layout: MemoryLayout {
639                heap_size: l.heap_size(),
640                code_size: l.code_size(),
641                code_virt_base: l.get_guest_code_gva() as u64,
642                init_data_size: l.init_data_size(),
643                init_data_permissions: l.init_data_permissions().map(|f| f.bits()),
644                scratch_size: l.get_scratch_size(),
645                g2h_queue_size: l.get_g2h_queue_size(),
646                h2g_queue_size: l.get_h2g_queue_size(),
647                g2h_buffer_size: l.get_g2h_buffer_size(),
648                h2g_buffer_size: l.get_h2g_buffer_size(),
649                g2h_pool_pages: l.get_g2h_pool_pages(),
650                h2g_pool_pages: l.get_h2g_pool_pages(),
651                snapshot_size: l.snapshot_size(),
652                pt_size: l.pt_size(),
653            },
654            memory_size: self.state.memory.mem_size() as u64,
655            host_functions,
656            snapshot_generation: self.state.snapshot_generation,
657            metadata: self.metadata.clone(),
658        })
659    }
660
661    /// Load a snapshot from an OCI Image Layout directory produced by
662    /// [`Snapshot::save`].
663    ///
664    /// # `path`
665    ///
666    /// The OCI Image Layout directory to read from. It must hold a
667    /// readable OCI layout containing at least one Hyperlight
668    /// snapshot.
669    ///
670    /// # `reference`
671    ///
672    /// Determines which snapshot in the layout to load, given as
673    /// either an [`OciTag`] or an [`OciDigest`]. Loading fails if no
674    /// snapshot in the layout has the given tag or digest.
675    ///
676    /// # Portability
677    ///
678    /// Snapshot images are bound to the specific CPU architecture,
679    /// hypervisor, and CPU vendor that the snapshot was created on.
680    /// For example, a snapshot taken on an Intel x86_64 host with KVM
681    /// can only be loaded on an Intel x86_64 host running KVM. Loading
682    /// on any other host is rejected. A future version may relax this
683    /// binding once a wider compatibility set is proven safe.
684    ///
685    /// # Compatibility
686    ///
687    /// While Hyperlight is at version 0.x.y the on-disk format is not
688    /// stable. A snapshot written by one Hyperlight version is not
689    /// guaranteed to load on a different Hyperlight version. An
690    /// incompatible snapshot is always rejected at load time with a
691    /// clear error. It can never load and then misbehave once the
692    /// guest is running. Any release that breaks the format is called
693    /// out in the Hyperlight changelog.
694    ///
695    /// # Verification
696    ///
697    /// This method does not check the manifest, config, memory, or transport
698    /// blobs against their recorded sha256 digests. Load only from a
699    /// layout you trust.
700    ///
701    /// To check the digests on load at the expense of some
702    /// performance, use [`Snapshot::checked_load`].
703    ///
704    /// # File-mutation hazard
705    ///
706    /// The snapshot blob stays memory-mapped while the returned
707    /// `Snapshot` or any sandbox built from it is alive. The existing
708    /// blob files in the layout at `path` must not be overwritten,
709    /// truncated, or deleted while the mapping is live. Doing so can
710    /// corrupt guest memory and can lead to undefined behavior.
711    ///
712    /// # Examples
713    ///
714    /// ```no_run
715    /// # use std::sync::Arc;
716    /// # use hyperlight_host::{HostFunctions, Sandbox};
717    /// # use hyperlight_host::sandbox::snapshot::{OciTag, Snapshot};
718    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
719    /// let tag = OciTag::new("latest")?;
720    /// let snapshot = Arc::new(Snapshot::load("./guest_snapshot", tag)?);
721    /// let mut sandbox = Sandbox::from_snapshot(snapshot, HostFunctions::default(), None)?;
722    /// let result: String = sandbox.call("Echo", "hello".to_string())?;
723    /// # Ok(())
724    /// # }
725    /// ```
726    pub fn load(path: impl AsRef<Path>, reference: impl Into<OciReference>) -> crate::Result<Self> {
727        Self::load_inner(path.as_ref(), &reference.into(), false)
728    }
729
730    /// Loads a snapshot like [`Snapshot::load`]. See its rustdoc for
731    /// `path`, `reference`, portability, and the file-mutation
732    /// hazard. This method additionally checks the manifest, config,
733    /// memory, and transport blobs against their recorded sha256 digests
734    /// before use, at the expense of some performance.
735    ///
736    /// # Trust
737    ///
738    /// A digest check does not prove the bytes are authentic. Anyone
739    /// who edits a blob can recompute its digest to match, so a
740    /// hostile layout passes the check. Load only from a source you
741    /// trust.
742    pub fn checked_load(
743        path: impl AsRef<Path>,
744        reference: impl Into<OciReference>,
745    ) -> crate::Result<Self> {
746        Self::load_inner(path.as_ref(), &reference.into(), true)
747    }
748
749    fn load_inner(
750        path: &Path,
751        reference: &OciReference,
752        verify_blobs: bool,
753    ) -> crate::Result<Self> {
754        let meta = std::fs::metadata(path)
755            .map_err(|e| crate::new_error!("load failed to stat {:?}: {}", path, e))?;
756        if !meta.is_dir() {
757            return Err(crate::new_error!("load path {:?} is not a directory", path));
758        }
759
760        let blobs_dir: PathBuf = path.join("blobs").join("sha256");
761
762        // 1. oci-layout
763        read_layout_marker(path)?;
764
765        // 2. index.json -> manifest descriptor for `reference`.
766        //    Multiple manifests are valid in an OCI Image Layout. A
767        //    tag selects the one whose
768        //    `org.opencontainers.image.ref.name` annotation matches it
769        //    (two manifests sharing a tag is a malformed layout). A
770        //    digest selects the descriptor carrying that manifest
771        //    digest.
772        let manifest = load_manifest(path, &blobs_dir, reference, verify_blobs)?;
773        let cfg_desc = manifest.config();
774        // Loader dispatch on config media type.
775        let cfg_media = cfg_desc.media_type().to_string();
776        match cfg_media.as_str() {
777            MT_CONFIG_V3 => {}
778            MT_CONFIG_V1 | MT_CONFIG_V2 => {
779                return Err(crate::new_error!(
780                    "snapshot config media type {:?} is incompatible with snapshot ABI {}",
781                    cfg_media,
782                    SNAPSHOT_ABI_VERSION
783                ));
784            }
785            other => {
786                return Err(crate::new_error!(
787                    "unexpected config media type {:?} (supported: {:?})",
788                    other,
789                    MT_CONFIG_V3
790                ));
791            }
792        }
793        // `artifactType` mirrors `config.mediaType` (manifest.md
794        // "Guidelines for Artifact Usage"). The OCI spec leaves this
795        // field OPTIONAL. A Hyperlight snapshot requires it to be
796        // present and equal to `config.mediaType` so loaders can
797        // distinguish a Hyperlight artifact from an arbitrary
798        // manifest that happens to share blob layout.
799        match manifest.artifact_type() {
800            Some(at) if at.to_string() == cfg_media => {}
801            Some(at) => {
802                return Err(crate::new_error!(
803                    "OCI manifest artifactType {:?} does not match config media type {:?}",
804                    at.to_string(),
805                    cfg_media
806                ));
807            }
808            None => {
809                return Err(crate::new_error!(
810                    "OCI manifest is missing required artifactType (expected {:?})",
811                    cfg_media
812                ));
813            }
814        }
815        let layers = manifest.layers();
816        if layers.len() != 2 {
817            return Err(crate::new_error!(
818                "expected exactly two OCI layers (memory and transport), found {}",
819                layers.len()
820            ));
821        }
822        let snap_desc = &layers[0];
823        let snap_media = snap_desc.media_type().to_string();
824        match snap_media.as_str() {
825            MT_SNAPSHOT_V1 => {}
826            other => {
827                return Err(crate::new_error!(
828                    "unexpected snapshot layer media type {:?} (supported: {:?})",
829                    other,
830                    MT_SNAPSHOT_V1
831                ));
832            }
833        }
834        let transport_desc = &layers[1];
835        let transport_media = transport_desc.media_type().to_string();
836        match transport_media.as_str() {
837            MT_TRANSPORT_V1 => {}
838            other => {
839                return Err(crate::new_error!(
840                    "unexpected transport layer media type {:?} (supported: {:?})",
841                    other,
842                    MT_TRANSPORT_V1
843                ));
844            }
845        }
846
847        // 4. config blob
848        let cfg = load_config(&blobs_dir, cfg_desc, verify_blobs)?;
849
850        // 5. snapshot blob: open once, hash and mmap the same
851        //    handle so an attacker cannot swap the file between
852        //    verification and mapping.
853        let snap_file = open_snapshot_blob(&blobs_dir, snap_desc, cfg.memory_size, verify_blobs)?;
854        let transport_bytes = load_blob(
855            "transport",
856            &blobs_dir,
857            transport_desc,
858            transport::MAX_BLOB_SIZE,
859            verify_blobs,
860        )?;
861
862        // 6. Reconstruct layout.
863        let mut sbox_cfg = crate::sandbox::SandboxConfiguration::default();
864        sbox_cfg.set_heap_size(cfg.layout.heap_size as u64);
865        sbox_cfg.set_scratch_size(cfg.layout.scratch_size);
866        sbox_cfg.set_g2h_queue_size(cfg.layout.g2h_queue_size);
867        sbox_cfg.set_h2g_queue_size(cfg.layout.h2g_queue_size);
868        sbox_cfg.set_g2h_buffer_size(cfg.layout.g2h_buffer_size);
869        sbox_cfg.set_h2g_buffer_size(cfg.layout.h2g_buffer_size);
870        sbox_cfg.set_g2h_pool_pages(cfg.layout.g2h_pool_pages);
871        sbox_cfg.set_h2g_pool_pages(cfg.layout.h2g_pool_pages);
872        let init_data_perms = match cfg.layout.init_data_permissions {
873            None => None,
874            Some(bits) => Some(MemoryRegionFlags::from_bits(bits).ok_or_else(|| {
875                crate::new_error!(
876                    "snapshot init_data_permissions {:#x} contains unknown flag bits",
877                    bits
878                )
879            })?),
880        };
881        let mut layout = SandboxMemoryLayout::new(
882            sbox_cfg,
883            cfg.layout.code_size,
884            cfg.layout.init_data_size,
885            init_data_perms,
886        )?;
887        let code_gva = if cfg.layout.code_virt_base == 0 {
888            layout.get_guest_code_gpa() as u64
889        } else {
890            cfg.layout.code_virt_base
891        };
892        layout.set_code_gva(code_gva)?;
893        // `snapshot_size` and `pt_size` are independent fields.
894        if let Some(pt) = cfg.layout.pt_size {
895            layout.set_pt_size(pt)?;
896        }
897        layout.set_snapshot_size(cfg.layout.snapshot_size);
898
899        // `snapshot_size` is the guest-visible prefix mapped into the
900        // snapshot region. It must cover at least the regions the
901        // layout fields describe (code, PEB, heap, init data),
902        // otherwise the guest mapping is too short to back them. The
903        // `snapshot_size + pt_size == memory_size` invariant alone
904        // does not bound `snapshot_size` from below, since a smaller
905        // `snapshot_size` can be offset by a larger `pt_size`.
906        let required_memory_size = layout.get_memory_size()? as u64;
907        if (layout.snapshot_size() as u64) < required_memory_size {
908            return Err(crate::new_error!(
909                "snapshot snapshot_size ({}) is smaller than the layout size ({})",
910                layout.snapshot_size(),
911                required_memory_size
912            ));
913        }
914
915        let virtq = transport::decode(&layout, &transport_bytes)?;
916
917        // 7. mmap the snapshot blob (file-backed CoW). The blob is
918        //    the raw memory image. `ReadonlySharedMemory::from_file`
919        //    surrounds it with host guard pages. The guest mapping
920        //    of the snapshot region covers only the data prefix
921        //    (`snapshot_size`). The PT tail sits past that prefix
922        //    in the host mapping and is copied into the scratch
923        //    region on restore. Keeping it out of the guest mapping
924        //    of the snapshot region avoids overlap with
925        //    `map_file_cow` regions installed immediately after the
926        //    snapshot in guest PA space.
927        let memory = ReadonlySharedMemory::from_file(&snap_file, layout.snapshot_size())?;
928
929        // The size validation in `open_snapshot_blob` stats the file
930        // before mapping. Nothing prevents the file from being
931        // truncated between that stat and the mmap, which would leave
932        // the mapping shorter than the config claims and make restore
933        // read past the end. Compare the mapped length against
934        // `memory_size` to reject a file mutated under us.
935        if memory.mem_size() as u64 != cfg.memory_size {
936            return Err(crate::new_error!(
937                "mapped snapshot size ({}) does not match config memory_size ({}); the blob may have changed during loading",
938                memory.mem_size(),
939                cfg.memory_size
940            ));
941        }
942
943        // 8. Build the next action + sregs back from the config.
944        let next_action = NextAction::Call(cfg.entrypoint_addr);
945
946        // 9. Reconstitute host_functions metadata.
947        let snapshot_generation = cfg.snapshot_generation;
948        let host_funcs_vec: Vec<
949            hyperlight_common::flatbuffer_wrappers::host_function_definition::HostFunctionDefinition,
950        > = cfg.host_functions.into_iter().map(Into::into).collect();
951        let host_functions = if host_funcs_vec.is_empty() {
952            HostFunctionDetails {
953                host_functions: None,
954            }
955        } else {
956            HostFunctionDetails {
957                host_functions: Some(host_funcs_vec),
958            }
959        };
960
961        Ok(Snapshot {
962            state: std::sync::Arc::new(super::SnapshotState {
963                layout,
964                memory,
965                load_info: crate::mem::exe::LoadInfo::dummy(),
966                stack_top_gva: cfg.stack_top_gva,
967                sregs: Some(cfg.sregs),
968                #[cfg(target_arch = "x86_64")]
969                msrs: Some(cfg.msrs),
970                next_action,
971                original_entrypoint: cfg.original_entrypoint_addr,
972                snapshot_generation,
973                host_functions,
974                virtq: Some(virtq),
975            }),
976            metadata: cfg.metadata,
977        })
978    }
979}