nvx-rs: reserve the launch of a leased clone, and document the lock order

doc/usage.md

@@ -109,7 +109,7 @@ each code for callers of the `nvx` library.
 | `foreign-files` | 1 | `deprovision` found files that NVX does not own in the state directory, which the message names, and kept them with the directory. |
 | `outcome-report-exists` | 1 | A file exists at the `--outcome-report` path. |
 | `scratch-claimed` | 1 | Another sandbox claims the scratch image. |
-| `sandbox-leased` | 1 | The sandbox holds a lease of a template's generation already, which a release ends once its VM has exited. |
+| `sandbox-leased` | 1 | The sandbox holds a lease of a template's generation, which allows no other lease, and one launch of its clone, until a release ends it once its VM has exited. |
 | `template-ineligible` | 1 | The restore window of a template's generation, which the time contract of its capture sets, excludes the host's time, so no clone may restore it now. |
 | `template-tombstoned` | 1 | A tombstone quarantines the template's generation, which takes no new clones. |
 | `exited` | 1 | OpenVMM exited, as when a start fails, whose message names the category and status of OpenVMM's outcome report when it has one. |

nvx-rs/src/error.rs

@@ -154,8 +154,8 @@ pub enum ErrorCode {
     /// `template-tombstoned`: a tombstone quarantines the template's generation, which takes no
     /// new clones, while the clones that lease it keep their leases.
     TemplateTombstoned,
-    /// `sandbox-leased`: the sandbox holds a lease of a template's generation already, which a
-    /// release ends once its VM has exited.
+    /// `sandbox-leased`: the sandbox holds a lease of a template's generation, which allows no
+    /// other lease, and one launch of its clone, until a release ends it once its VM has exited.
     SandboxLeased,
 }
 

nvx-rs/src/host/cli/sandbox/lifecycle.rs

@@ -75,7 +75,7 @@ use crate::host::sandbox::distro::DISTRO_POLICY_REVISION;
 use crate::host::sandbox::scratch::CLAIM_RELEASE_WAIT;
 use crate::host::sandbox::{PreparedLaunch, SandboxLaunch, require_file};
 use crate::host::store::{
-    IdentityPart, LockedStore, OUTCOME_NAME, RUNTIME_NAME, Recovery, SandboxStore,
+    IdentityPart, LaunchId, LockedStore, OUTCOME_NAME, RUNTIME_NAME, Recovery, SandboxStore,
 };
 use crate::host::supervisor::{self, Launched, Reattached, StopOutcome, Vmm, VmmCommand};
 use crate::protocol::{CAPABILITY_LEN, GuestFeatures};
@@ -581,7 +581,8 @@ fn start_locked(
     ];
     let directory = std::env::current_dir().map_err(Exit::from_os_error)?;
     let mut command = Vec::new();
-    let mut starting = supervisor::launch(locked, &runtime, &capability, |endpoint| {
+    let launch = LaunchId::generate().map_err(error_with_cause)?;
+    let mut starting = supervisor::launch(locked, &launch, &runtime, &capability, |endpoint| {
         command = head;
         command.push(format!("listen={endpoint}"));
         command.extend(tail);

nvx-rs/src/host/instance.rs

@@ -68,8 +68,8 @@ use super::process::KILL_TIMEOUT;
 use super::report::{self, Report};
 use super::session::{self, ControlSession, ExecEvent, SessionError};
 use super::store::{
-    CallerFiles, IdentityPart, LockedStore, OUTCOME_NAME, Recovery, RemovalError, RuntimeIdentity,
-    RuntimeRecord, SOCKET_NAME, SandboxStore,
+    CallerFiles, IdentityPart, LaunchId, LockedStore, OUTCOME_NAME, Recovery, RemovalError,
+    RuntimeIdentity, RuntimeRecord, SOCKET_NAME, SandboxStore,
 };
 use super::supervisor::{self, Reattached, Starting, StopOutcome, Vmm, VmmCommand};
 use crate::error::{Error, ErrorCode, ErrorKind, Result};
@@ -706,14 +706,21 @@ impl LockedInstance {
         let endpoint = control_endpoint(&instance.store.socket_path())?;
         spec.fit_process_command_line(&spec.openvmm_arguments(&endpoint, &report)?, 0)?;
         let capability = generate_capability()?;
+        let launch = LaunchId::generate()?;
         let started = Instant::now();
-        let starting = supervisor::launch(&mut self.locked, runtime, &capability, |endpoint| {
-            let arguments = spec.openvmm_arguments(endpoint, &report)?;
-            spec.fit_process_command_line(&arguments, 0)?;
-            let mut command = VmmCommand::new(&spec.openvmm, arguments, instance.dir());
-            command.breakaway_from_job = spec.breakaway_from_job;
-            Ok(command)
-        })?;
+        let starting = supervisor::launch(
+            &mut self.locked,
+            &launch,
+            runtime,
+            &capability,
+            |endpoint| {
+                let arguments = spec.openvmm_arguments(endpoint, &report)?;
+                spec.fit_process_command_line(&arguments, 0)?;
+                let mut command = VmmCommand::new(&spec.openvmm, arguments, instance.dir());
+                command.breakaway_from_job = spec.breakaway_from_job;
+                Ok(command)
+            },
+        )?;
         let (pid, start_time) = {
             let reference = starting.process().reference();
             (reference.pid, reference.start_time)

nvx-rs/src/host/platform/mod.rs

@@ -100,6 +100,20 @@ pub(crate) fn parse_hex_id(digits: &str) -> Option<[u8; 16]> {
     Some(id)
 }
 
+/// Parses 64 hexadecimal digits, in either case, into the 32 bytes that they spell.
+pub(crate) fn parse_hex32(text: &str) -> Option<[u8; 32]> {
+    let digits = text.as_bytes();
+    if digits.len() != 64 {
+        return None;
+    }
+    let mut bytes = [0; 32];
+    for (byte, pair) in bytes.iter_mut().zip(digits.chunks_exact(2)) {
+        let nibble = |digit: u8| char::from(digit).to_digit(16);
+        *byte = u8::try_from(nibble(pair[0])? * 16 + nibble(pair[1])?).ok()?;
+    }
+    Some(bytes)
+}
+
 /// Parses the identity of a host as OpenVMM reads it: 32 hexadecimal digits, in either case,
 /// between optional braces and surrounding whitespace, ignoring dashes, as in `/etc/machine-id`
 /// and the Windows machine GUID.