feat(archive): layered box export and import primitives

sdks/c/include/boxlite.h

@@ -149,14 +149,14 @@ typedef struct FFIError {
   char *message;
 } FFIError;
 
-typedef struct RuntimeHandle CBoxliteRuntime;
-
-typedef struct OptionsHandle CBoxliteOptions;
-
 typedef struct BoxHandle CBoxHandle;
 
 typedef struct FFIError CBoxliteError;
 
+typedef struct RuntimeHandle CBoxliteRuntime;
+
+typedef struct OptionsHandle CBoxliteOptions;
+
 // Box creation completion.
 typedef void (*CBoxCreateBoxCb)(CBoxHandle*, CBoxliteError*, void*);
 
@@ -469,6 +469,17 @@ enum BoxliteErrorCode boxlite_advanced_options_set_capabilities_drop(CAdvancedBo
                                                                      const char *const *capabilities,
                                                                      int count);
 
+enum BoxliteErrorCode boxlite_box_export(CBoxHandle *handle,
+                                         const char *dest_path,
+                                         char **out_path,
+                                         CBoxliteError *out_error);
+
+enum BoxliteErrorCode boxlite_runtime_import_box(CBoxliteRuntime *runtime,
+                                                 const char *archive_path,
+                                                 const char *name,
+                                                 CBoxHandle **out_handle,
+                                                 CBoxliteError *out_error);
+
 enum BoxliteErrorCode boxlite_create_box(CBoxliteRuntime *runtime,
                                          CBoxliteOptions *opts,
                                          CBoxCreateBoxCb cb,

sdks/c/src/archive.rs

@@ -0,0 +1,145 @@
+//! Box archive export/import operations for the BoxLite C SDK.
+
+use std::os::raw::c_char;
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use boxlite::BoxliteError;
+use boxlite::runtime::options::{BoxArchive, ExportOptions};
+
+use crate::box_handle::BoxHandle;
+use crate::error::{BoxliteErrorCode, FFIError, null_pointer_error, write_error};
+use crate::runtime::RuntimeHandle;
+use crate::util::{alloc_c_string, c_str_to_string};
+use crate::{CBoxHandle, CBoxliteError, CBoxliteRuntime};
+
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn boxlite_box_export(
+    handle: *mut CBoxHandle,
+    dest_path: *const c_char,
+    out_path: *mut *mut c_char,
+    out_error: *mut CBoxliteError,
+) -> BoxliteErrorCode {
+    box_export(handle, dest_path, out_path, out_error)
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn boxlite_runtime_import_box(
+    runtime: *mut CBoxliteRuntime,
+    archive_path: *const c_char,
+    name: *const c_char,
+    out_handle: *mut *mut CBoxHandle,
+    out_error: *mut CBoxliteError,
+) -> BoxliteErrorCode {
+    runtime_import_box(runtime, archive_path, name, out_handle, out_error)
+}
+
+unsafe fn box_export(
+    handle: *mut BoxHandle,
+    dest_path: *const c_char,
+    out_path: *mut *mut c_char,
+    out_error: *mut FFIError,
+) -> BoxliteErrorCode {
+    unsafe {
+        if handle.is_null() {
+            write_error(out_error, null_pointer_error("handle"));
+            return BoxliteErrorCode::InvalidArgument;
+        }
+        if out_path.is_null() {
+            write_error(out_error, null_pointer_error("out_path"));
+            return BoxliteErrorCode::InvalidArgument;
+        }
+        let dest = match c_str_to_string(dest_path) {
+            Ok(s) => PathBuf::from(s),
+            Err(e) => {
+                write_error(out_error, e);
+                return BoxliteErrorCode::InvalidArgument;
+            }
+        };
+
+        let handle_ref = &*handle;
+        let lite = handle_ref.handle.clone();
+        match handle_ref
+            .tokio_rt
+            .block_on(lite.export(ExportOptions::default(), &dest))
+        {
+            Ok(archive) => {
+                let path = archive.path().to_string_lossy().into_owned();
+                let c_path = alloc_c_string(&path);
+                if c_path.is_null() {
+                    write_error(
+                        out_error,
+                        BoxliteError::Internal("archive path contains interior NUL".into()),
+                    );
+                    return BoxliteErrorCode::Internal;
+                }
+                *out_path = c_path;
+                BoxliteErrorCode::Ok
+            }
+            Err(e) => {
+                write_error(out_error, e);
+                BoxliteErrorCode::Internal
+            }
+        }
+    }
+}
+
+unsafe fn runtime_import_box(
+    runtime: *mut RuntimeHandle,
+    archive_path: *const c_char,
+    name: *const c_char,
+    out_handle: *mut *mut CBoxHandle,
+    out_error: *mut FFIError,
+) -> BoxliteErrorCode {
+    unsafe {
+        if runtime.is_null() {
+            write_error(out_error, null_pointer_error("runtime"));
+            return BoxliteErrorCode::InvalidArgument;
+        }
+        if out_handle.is_null() {
+            write_error(out_error, null_pointer_error("out_handle"));
+            return BoxliteErrorCode::InvalidArgument;
+        }
+        let archive_path = match c_str_to_string(archive_path) {
+            Ok(s) => PathBuf::from(s),
+            Err(e) => {
+                write_error(out_error, e);
+                return BoxliteErrorCode::InvalidArgument;
+            }
+        };
+        let name = if name.is_null() {
+            None
+        } else {
+            match c_str_to_string(name) {
+                Ok(s) => Some(s),
+                Err(e) => {
+                    write_error(out_error, e);
+                    return BoxliteErrorCode::InvalidArgument;
+                }
+            }
+        };
+
+        let runtime_ref = &*runtime;
+        let runtime_clone = runtime_ref.runtime.clone();
+        let tokio_rt = runtime_ref.tokio_rt.clone();
+        let task_tokio_rt = tokio_rt.clone();
+
+        match tokio_rt.block_on(runtime_clone.import_box(BoxArchive::new(archive_path), name)) {
+            Ok(handle) => {
+                let box_id = handle.id().clone();
+                let boxed = Box::new(BoxHandle {
+                    handle: Arc::new(handle),
+                    box_id,
+                    tokio_rt: task_tokio_rt,
+                    queue: runtime_ref.queue.clone(),
+                });
+                *out_handle = Box::into_raw(boxed);
+                BoxliteErrorCode::Ok
+            }
+            Err(e) => {
+                write_error(out_error, e);
+                BoxliteErrorCode::Internal
+            }
+        }
+    }
+}

sdks/c/src/lib.rs

@@ -8,6 +8,7 @@
 #![allow(clippy::too_many_arguments)]
 
 mod advanced_options;
+mod archive;
 mod box_handle;
 mod copy;
 mod error;
@@ -67,6 +68,7 @@ pub type BoxliteCommand = exec::BoxliteCommand;
 pub type CAdvancedBoxOptions = advanced_options::AdvancedBoxOptionsHandle;
 
 pub use advanced_options::*;
+pub use archive::*;
 pub use box_handle::*;
 pub use copy::*;
 pub use error::*;

sdks/go/archive.go

@@ -0,0 +1,62 @@
+package boxlite
+
+/*
+#include "bridge.h"
+#include <stdlib.h>
+*/
+import "C"
+import (
+	"context"
+	"unsafe"
+)
+
+// Export writes the box archive into dest and returns the archive path.
+func (b *Box) Export(ctx context.Context, dest string) (string, error) {
+	if err := ctx.Err(); err != nil {
+		return "", err
+	}
+
+	cDest := toCString(dest)
+	defer C.free(unsafe.Pointer(cDest))
+
+	var outPath *C.char
+	var cerr C.CBoxliteError
+	code := C.boxlite_box_export(b.handle, cDest, &outPath, &cerr)
+	if code != C.Ok {
+		return "", freeError(&cerr)
+	}
+	defer freeBoxliteString(outPath)
+
+	return cString(outPath), ctx.Err()
+}
+
+// Import restores an archive into this runtime. If name is empty, the archive's
+// recorded box name is used.
+func (r *Runtime) Import(ctx context.Context, archivePath, name string) (*Box, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+
+	cArchive := toCString(archivePath)
+	defer C.free(unsafe.Pointer(cArchive))
+	var cName *C.char
+	if name != "" {
+		cName = toCString(name)
+		defer C.free(unsafe.Pointer(cName))
+	}
+
+	var outHandle *C.CBoxHandle
+	var cerr C.CBoxliteError
+	code := C.boxlite_runtime_import_box(r.handle, cArchive, cName, &outHandle, &cerr)
+	if code != C.Ok {
+		return nil, freeError(&cerr)
+	}
+
+	if err := ctx.Err(); err != nil {
+		if outHandle != nil {
+			C.boxlite_box_free(outHandle)
+		}
+		return nil, err
+	}
+	return newBoxFromHandle(r, outHandle, name), nil
+}

sdks/node/src/snapshot_options.rs

@@ -21,7 +21,7 @@ pub struct JsExportOptions {}
 
 impl From<JsExportOptions> for ExportOptions {
     fn from(_js: JsExportOptions) -> Self {
-        ExportOptions {}
+        ExportOptions::default()
     }
 }
 

sdks/python/src/snapshot_options.rs

@@ -37,7 +37,7 @@ impl PyExportOptions {
 
 impl From<PyExportOptions> for ExportOptions {
     fn from(_py: PyExportOptions) -> Self {
-        ExportOptions {}
+        ExportOptions::default()
     }
 }
 

src/boxlite/src/db/base_disk.rs

@@ -96,8 +96,8 @@ impl BaseDiskStore {
         let conn = self.db.conn();
         db_err!(conn.execute(
             "INSERT INTO base_disk \
-             (id, source_box_id, name, kind, base_path, created_at, json) \
-             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)",
+             (id, source_box_id, name, kind, base_path, created_at, json, digest) \
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
             rusqlite::params![
                 &disk.id,
                 &disk.source_box_id,
@@ -106,11 +106,43 @@ impl BaseDiskStore {
                 &disk.disk_info.base_path,
                 disk.created_at,
                 json,
+                &disk.digest,
             ],
         ))?;
         Ok(())
     }
 
+    /// Find a base disk by its content digest.
+    ///
+    /// Only layers whose digest has already been computed are visible here;
+    /// see [`BaseDisk::digest`] for why it is filled in lazily.
+    pub(crate) fn find_by_digest(&self, digest: &str) -> BoxliteResult<Option<BaseDiskInfo>> {
+        let conn = self.db.conn();
+        let result = db_err!(
+            conn.query_row(
+                "SELECT id, source_box_id, name, kind, base_path, \
+                 created_at, json FROM base_disk WHERE digest = ?1",
+                rusqlite::params![digest],
+                row_to_record,
+            )
+            .optional()
+        )?;
+        Ok(result)
+    }
+
+    /// Record a layer's content digest, in both the indexed column and the
+    /// JSON blob so the two cannot drift.
+    pub(crate) fn set_digest(&self, id: &BaseDiskID, digest: &str) -> BoxliteResult<()> {
+        let conn = self.db.conn();
+        db_err!(conn.execute(
+            "UPDATE base_disk \
+             SET digest = ?2, json = json_set(json, '$.digest', ?2) \
+             WHERE id = ?1",
+            rusqlite::params![id, digest],
+        ))?;
+        Ok(())
+    }
+
     /// Find a base disk by its ID.
     #[allow(dead_code)] // used in lineage.rs tests
     pub(crate) fn find_by_id(&self, id: &BaseDiskID) -> BoxliteResult<Option<BaseDiskInfo>> {
@@ -330,6 +362,7 @@ mod tests {
                 size_bytes: 512,
             },
             created_at: chrono::Utc::now().timestamp(),
+            digest: None,
         }
     }
 
@@ -686,6 +719,7 @@ mod tests {
                 size_bytes: 1024,
             },
             created_at: 1700000000,
+            digest: None,
         };
         store.insert(&disk).unwrap();
 

src/boxlite/src/db/migration/mod.rs

@@ -11,6 +11,7 @@ mod v5_to_v6;
 mod v6_to_v7;
 mod v7_to_v8;
 mod v8_to_v9;
+mod v9_to_v10;
 
 use std::path::Path;
 
@@ -81,5 +82,6 @@ fn all_migrations() -> Vec<Box<dyn Migration>> {
         Box::new(v6_to_v7::MoveDisksAndAddBaseDisk),
         Box::new(v7_to_v8::RenameNetworkSpec),
         Box::new(v8_to_v9::PreservePublishedPorts),
+        Box::new(v9_to_v10::AddBaseDiskDigest),
     ]
 }