improve coverage and documentation

Author: wasm-forge

ic-wasi-polyfill/src/lib.rs

@@ -1867,13 +1867,16 @@ pub unsafe extern "C" fn raw_init(seed: *const u8, len: usize) {
     })
 }
 
-// the init function ensures the module is not thrown away by the linker
-// seed       -  The seed of the random numbers, up to 32 byte array can be used.
-// env_pairs  -  The pre-defined environment variables.
-//
-// Example:
-// init(&[12,3,54,1], &[("PATH", "/usr/bin"), ("UID", "1028"), ("HOME", "/home/user")]);
-#[allow(clippy::missing_safety_doc)]
+/// Initializes the runtime environment and random number generator.
+///
+/// # Parameters
+/// - `seed`: A byte slice (up to 32 bytes) used to seed the random number generator.
+/// - `env_pairs`: A list of key-value pairs representing environment variables to initialize.
+///
+/// # Safety
+/// This function calls an `unsafe` function `raw_init`, passing a raw pointer and length of the seed slice.
+/// It is safe to call this function as long as `seed` is a valid slice.
+///
 pub fn init(seed: &[u8], env_pairs: &[(&str, &str)]) {
     ENV.with(|env| {
         let mut env = env.borrow_mut();
@@ -1916,10 +1919,12 @@ pub fn init_with_memory_manager<M: Memory + 'static>(
     init(seed, env_pairs);
 }
 
-// mount external memory onto a file to speed-up file access. All further file reads and writes be forwarded to this memory.
-// file_name    -  Name of the host file to mount on
-// memory       -  Memory to use as file storage
-//
+/// Mounts external memory onto a file to speed-up file access. All further file reads and writes be forwarded to this memory.
+///
+/// # Parameters
+/// - `file_name`    -  Name of the host file to mount on
+/// - `memory`       -  Memory to use as an actual file storage
+///
 pub fn mount_memory_file(file_name: &str, memory: Box<dyn Memory>) -> i32 {
     FS.with(|fs| {
         let mut fs = fs.borrow_mut();
@@ -1933,9 +1938,11 @@ pub fn mount_memory_file(file_name: &str, memory: Box<dyn Memory>) -> i32 {
     })
 }
 
-// unmount external memory from a host file. All further file reads and writes are written to a normal file.
-// file_name    -  Name of the host file holding the mount
-//
+/// unmounts external memory from a host file. All further file reads and writes are written to a normal file.
+///
+/// # Parameters
+/// `file_name`    -  Name of the host file holding the mount
+///
 pub fn unmount_memory_file(file_name: &str) -> i32 {
     FS.with(|fs| {
         let mut fs = fs.borrow_mut();
@@ -1949,9 +1956,11 @@ pub fn unmount_memory_file(file_name: &str) -> i32 {
     })
 }
 
-// initialize mouned memory with the contents of the host file.
-// file_name    -  Name of the host file holding the mount
-//
+/// Initializes mouned memory with the contents of the host file.
+///
+/// # Parameters
+/// `file_name`    -  Name of the host file holding the mount
+///
 pub fn init_memory_file(file_name: &str) -> i32 {
     FS.with(|fs| {
         let mut fs = fs.borrow_mut();
@@ -1965,9 +1974,11 @@ pub fn init_memory_file(file_name: &str) -> i32 {
     })
 }
 
-// Store memory contents into the host file.
-// file_name    -  Name of the host file holding the mount
-//
+/// Store memory contents into the host file.
+///
+/// # Parameters
+/// `file_name`    -  Name of the host file holding the mount
+///
 pub fn store_memory_file(file_name: &str) -> i32 {
     FS.with(|fs| {
         let mut fs = fs.borrow_mut();

ic-wasi-polyfill/tests/common.rs

@@ -42,14 +42,14 @@ pub fn create_test_file_with_content(parent_fd: Fd, file_name: &str, content: Ve
             0,
             new_file_name.as_ptr(),
             new_file_name.len() as i32,
-            (wasi::OFLAGS_CREAT | wasi::OFLAGS_TRUNC | wasi::OFLAGS_EXCL) as i32,
+            (wasi::OFLAGS_CREAT | wasi::OFLAGS_TRUNC) as i32,
             DEFAULT_RIGHTS,
             DEFAULT_RIGHTS,
             0,
             (&mut file_fd) as *mut u32,
         )
     };
-    assert!(res == 0);
+    assert_eq!(res, 0);
 
     let mut src = Vec::new();
 
@@ -138,3 +138,48 @@ pub fn read_directory(root_fd: Fd) -> Vec<String> {
 
     folders
 }
+
+#[allow(clippy::missing_safety_doc)]
+pub fn fd_close(fd: Fd) {
+    __ic_custom_fd_close(fd);
+}
+
+#[allow(clippy::missing_safety_doc)]
+pub fn read_file_to_string(file: &str) -> String {
+    let mut file_fd = 0u32;
+
+    let res = unsafe {
+        __ic_custom_path_open(
+            3,
+            0,
+            file.as_ptr(),
+            file.len() as i32,
+            0,
+            DEFAULT_RIGHTS,
+            DEFAULT_RIGHTS,
+            0,
+            (&mut file_fd) as *mut u32,
+        )
+    };
+
+    assert_eq!(res, 0);
+
+    // read buffers
+    let mut buf_to_read = vec![0u8; 1024];
+
+    let read_buf = [wasi::Iovec {
+        buf: buf_to_read.as_mut_ptr(),
+        buf_len: buf_to_read.len(),
+    }];
+
+    let mut bytes_read: wasi::Size = 0;
+
+    // reading from root folder
+    let res: i32 = unsafe { __ic_custom_fd_read(file_fd, read_buf.as_ptr(), 1, &mut bytes_read) };
+    assert_eq!(res, 0, "fd_read error");
+
+    buf_to_read.truncate(bytes_read);
+
+    // Convert to UTF-8 String (returning String or panic if invalid UTF-8)
+    String::from_utf8(buf_to_read).expect("Invalid UTF-8 in file")
+}

ic-wasi-polyfill/tests/lib_tests.rs

@@ -1,5 +1,7 @@
 mod common;
 
+use std::fs::read_to_string;
+
 use common::*;
 use ic_wasi_polyfill::wasi::{self, Fd};
 use ic_wasi_polyfill::wasi_helpers::DIRENT_SIZE;
@@ -1405,3 +1407,61 @@ fn test_ic_custom_fd_fdstat_set_rights_success() {
         assert_eq!(fdstat.fs_rights_inheriting, 6 & common::DEFAULT_RIGHTS);
     }
 }
+
+#[test]
+fn test_mounts() {
+    let dir_fd = 3;
+
+    init(&[], &[]);
+
+    let memory = new_vector_memory();
+    let file_name = "file.txt";
+    let hello_message = "Hello host".to_string();
+    let hello_message2 = "Hello from regular file".to_string();
+
+    mount_memory_file(file_name, Box::new(memory.clone()));
+
+    // write something into a host memory file
+    let fd = create_test_file_with_content(dir_fd, file_name, vec![hello_message.clone()]);
+    fd_close(fd);
+
+    // the memory should contain the file now
+    let v: Vec<u8> = memory.borrow().clone();
+    assert_eq!(&v[0..hello_message.len()], hello_message.as_bytes());
+
+    let str = read_file_to_string(file_name);
+    assert_eq!(str, hello_message);
+
+    // unmount file, the file.txt should become empty
+    unmount_memory_file(file_name);
+    let str = read_file_to_string(file_name);
+    assert_eq!(str, "".to_string());
+
+    // mount again, the old content should recover
+    mount_memory_file(file_name, Box::new(memory.clone()));
+    let str = read_file_to_string(file_name);
+    assert_eq!(str, hello_message);
+
+    // store mounted contents into the host file, check the host file content is renewed
+    store_memory_file(file_name);
+    unmount_memory_file(file_name);
+    let str = read_file_to_string(file_name);
+    assert_eq!(str, hello_message);
+
+    // write some other content message,
+    // check there is a new content now
+    let fd = create_test_file_with_content(dir_fd, file_name, vec![hello_message2.clone()]);
+    fd_close(fd);
+    let str = read_file_to_string(file_name);
+    assert_eq!(str, hello_message2);
+
+    // after mounting, we still have the old content
+    mount_memory_file(file_name, Box::new(memory.clone()));
+    let str = read_file_to_string(file_name);
+    assert_eq!(str, hello_message);
+
+    // initializing should recover the data from the host file to the mounted memory
+    init_memory_file(file_name);
+    let str = read_file_to_string(file_name);
+    assert_eq!(str, hello_message2);
+}