pub struct Snapshot { /* private fields */ }Expand description
An immutable snapshot of sandbox state.
Implementations§
Source§impl Snapshot
impl Snapshot
Sourcepub fn save(&self, path: impl AsRef<Path>, tag: &OciTag) -> Result<OciDigest>
pub fn save(&self, path: impl AsRef<Path>, tag: &OciTag) -> Result<OciDigest>
Save this snapshot into an OCI Image Layout directory on disk.
The saved snapshot can be loaded later with
Snapshot::load.
Returns the OciDigest of the manifest that was written,
which Snapshot::load accepts as a stable handle to
this exact snapshot.
§path
The OCI Image Layout directory to write to. The directory at
path is created if absent. Its parent directory must exist.
If path holds no OCI layout, a new one is created. If it
holds one, this snapshot is added alongside the others. If
path holds something that is not a readable OCI layout, the
call fails and the directory is left unchanged.
§tag
A standard OCI tag that names this snapshot within the layout.
Snapshot::load can load the snapshot back by this tag.
A tag points to one snapshot at a time. If the layout has a snapshot under this tag, the tag is moved to the new snapshot. The old snapshot’s data stays on disk, reachable by its digest but not by this tag. Snapshots under other tags are untouched.
§Portability
Snapshot images are bound to the specific CPU architecture, hypervisor, and CPU vendor that the snapshot was created on. For example, a snapshot taken on an Intel x86_64 host with KVM can only be loaded on an Intel x86_64 host running KVM. Loading on any other host is rejected. A future version may relax this binding once a wider compatibility set is proven safe.
§Compatibility
While Hyperlight is at version 0.x.y the on-disk format is not stable. A snapshot written by one Hyperlight version is not guaranteed to load on a different Hyperlight version. An incompatible snapshot is always rejected at load time with a clear error. It can never load and then misbehave once the guest is running. Any release that breaks the format is called out in the Hyperlight changelog.
§Examples
let mut sandbox = SandboxBuilder::from_file("guest.bin").build()?;
// Capture the initialized state and write it to an OCI layout on disk.
let snapshot = sandbox.snapshot()?;
let tag = OciTag::new("latest")?;
let digest = snapshot.save("./guest_snapshot", &tag)?;Sourcepub fn load(
path: impl AsRef<Path>,
reference: impl Into<OciReference>,
) -> Result<Self>
pub fn load( path: impl AsRef<Path>, reference: impl Into<OciReference>, ) -> Result<Self>
Load a snapshot from an OCI Image Layout directory produced by
Snapshot::save.
§path
The OCI Image Layout directory to read from. It must hold a readable OCI layout containing at least one Hyperlight snapshot.
§reference
Determines which snapshot in the layout to load, given as
either an OciTag or an OciDigest. Loading fails if no
snapshot in the layout has the given tag or digest.
§Portability
Snapshot images are bound to the specific CPU architecture, hypervisor, and CPU vendor that the snapshot was created on. For example, a snapshot taken on an Intel x86_64 host with KVM can only be loaded on an Intel x86_64 host running KVM. Loading on any other host is rejected. A future version may relax this binding once a wider compatibility set is proven safe.
§Compatibility
While Hyperlight is at version 0.x.y the on-disk format is not stable. A snapshot written by one Hyperlight version is not guaranteed to load on a different Hyperlight version. An incompatible snapshot is always rejected at load time with a clear error. It can never load and then misbehave once the guest is running. Any release that breaks the format is called out in the Hyperlight changelog.
§Verification
This method does not check the manifest, config, memory, or transport blobs against their recorded sha256 digests. Load only from a layout you trust.
To check the digests on load at the expense of some
performance, use Snapshot::checked_load.
§File-mutation hazard
The snapshot blob stays memory-mapped while the returned
Snapshot or any sandbox built from it is alive. The existing
blob files in the layout at path must not be overwritten,
truncated, or deleted while the mapping is live. Doing so can
corrupt guest memory and can lead to undefined behavior.
§Examples
let tag = OciTag::new("latest")?;
let snapshot = Arc::new(Snapshot::load("./guest_snapshot", tag)?);
let mut sandbox = Sandbox::from_snapshot(snapshot, HostFunctions::default(), None)?;
let result: String = sandbox.call("Echo", "hello".to_string())?;Sourcepub fn checked_load(
path: impl AsRef<Path>,
reference: impl Into<OciReference>,
) -> Result<Self>
pub fn checked_load( path: impl AsRef<Path>, reference: impl Into<OciReference>, ) -> Result<Self>
Loads a snapshot like Snapshot::load. See its rustdoc for
path, reference, portability, and the file-mutation
hazard. This method additionally checks the manifest, config,
memory, and transport blobs against their recorded sha256 digests
before use, at the expense of some performance.
§Trust
A digest check does not prove the bytes are authentic. Anyone who edits a blob can recompute its digest to match, so a hostile layout passes the check. Load only from a source you trust.
Source§impl Snapshot
impl Snapshot
Sourcepub fn metadata<T>(&self, namespace: &str) -> Result<Option<T>>where
T: DeserializeOwned,
pub fn metadata<T>(&self, namespace: &str) -> Result<Option<T>>where
T: DeserializeOwned,
Deserializes the metadata stored under namespace as T.
Returns None if the namespace has no metadata.
§Errors
Returns an error if the JSON metadata cannot be deserialized as T.
§Examples
#[derive(Debug, PartialEq, Serialize, Deserialize)]
struct Metadata {
version: u32,
}
let snapshot =
snapshot.with_metadata("snapshot-metadata-namespace-v1", &Metadata { version: 1 })?;
let metadata = snapshot
.metadata::<Metadata>("snapshot-metadata-namespace-v1")?
.expect("metadata should exist");
assert_eq!(metadata, Metadata { version: 1 });Sourcepub fn with_metadata<T>(
&self,
namespace: impl Into<String>,
metadata: &T,
) -> Result<Arc<Self>>where
T: Serialize,
pub fn with_metadata<T>(
&self,
namespace: impl Into<String>,
metadata: &T,
) -> Result<Arc<Self>>where
T: Serialize,
Adds metadata to this snapshot and returns the result as a new
snapshot. Metadata already stored under namespace is replaced.
This snapshot remains unchanged. Metadata is saved and loaded with the snapshot.
§Errors
Returns an error if metadata cannot be serialized as JSON.
§Examples
#[derive(Debug, PartialEq, Serialize, Deserialize)]
struct Metadata {
version: u32,
}
let snapshot =
snapshot.with_metadata("snapshot-metadata-namespace-v1", &Metadata { version: 1 })?;
let metadata = snapshot
.metadata::<Metadata>("snapshot-metadata-namespace-v1")?
.expect("metadata should exist");
assert_eq!(metadata, Metadata { version: 1 });