LiteBox 9P Protocol Support: Implementation Status and Usage Guide

LiteBox currently provides a placeholder 9P file-system implementation in litebox/src/fs/nine_p.rs that will replace VSBox's 9P client to enable remote directory mounting via the Plan 9 protocol.

The microsoft/litebox repository defines a skeletal 9P protocol support module designed to eventually handle network-backed file system operations. This implementation follows the same trait-based architecture as LiteBox's existing in-memory and tar-based file systems, providing a unified interface for sandboxed environments to access remote directories without copying data into local memory.

Architectural Overview of LiteBox 9P Protocol Support

The 9P protocol support in LiteBox is structured around a trait-based file system abstraction that mirrors the design of other storage backends in the project.

The nine_p Module Structure

The core implementation resides in litebox/src/fs/nine_p.rs, which declares the FileSystem struct:

// From litebox/src/fs/nine_p.rs
pub struct FileSystem<Platform: crate::sync::RawSyncPrimitivesProvider> {
    // Fields will hold connection state to remote 9P server
    _phantom: std::marker::PhantomData<Platform>,
}

This struct is generic over a Platform type parameter, consistent with LiteBox's cross-platform abstraction strategy. The module is publicly re-exported through litebox/src/fs/mod.rs, making it available as litebox::fs::nine_p.

Integration with the FileSystem Trait

The nine_p::FileSystem implements the same FileSystem trait used by in_mem::FileSystem and tar_ro::FileSystem. This trait defines standard operations like open, read, write, and seek, allowing user code to interact with 9P-mounted directories using identical syntax to local storage.

Current Implementation Status

As of the latest source code, the LiteBox 9P protocol support remains a placeholder awaiting full implementation.

Placeholder Methods in nine_p.rs

All trait methods in litebox/src/fs/nine_p.rs currently contain todo!() macros:

impl<Platform: crate::sync::RawSyncPrimitivesProvider> FileSystem for FileSystem<Platform> {
    fn open(&self, path: &str, flags: OFlags, mode: Mode) -> Result<Fd, Error> {
        todo!()
    }
    
    fn read(&self, fd: &Fd, buf: &mut [u8], offset: Option<u64>) -> Result<usize, Error> {
        todo!()
    }
    
    // Additional methods (write, seek, close, etc.) follow same pattern
}

This skeleton establishes the API contract while the actual 9P wire protocol logic is being migrated from VSBox.

Debug Workaround in litebox_runner_snp

Until the 9P protocol support is functional, litebox_runner_snp/src/main.rs contains a debug-only workaround that pre-loads host files into an in-memory file system:

/// Pre-defined file paths to load from host for testing purposes.
#[cfg(debug_assertions)]
const HOST_FILE_PATHS: &[&str] = &[
    "/out/hello",
    "/out/efault",
    "/out/thread_exit",
    "/out/tcp_server",
];

#[cfg(debug_assertions)]
fn load_host_files_into_fs<Platform: litebox::sync::RawSyncPrimitivesProvider>(
    in_mem_fs: &mut litebox::fs::in_mem::FileSystem<Platform>,
) {
    // Creates /out, loads each file from the host via VSBox's "load_file_from_host"
    // call, and writes it into the in-memory FS.
}

The source code contains an explicit comment indicating this code will be removed after the 9P file system migration from VSBox is complete.

Intended Usage of 9P Protocol Support

When fully implemented, LiteBox's 9P protocol support will enable mounting remote directories through the Plan 9 file system protocol. The intended usage pattern follows the standard LiteBox file system construction pattern.

Creating a 9P-Backed File System

Developers will instantiate the 9P file system using the platform-specific constructor:

use litebox::{LiteBox, platform::Provider};
use litebox::fs::nine_p;

fn init_filesystem<P: Provider + Sync + 'static>(litebox: &LiteBox<P>) -> impl FileSystem {
    // Create the 9P filesystem (future implementation)
    let fs = nine_p::FileSystem::<P>::new(litebox);
    
    // Connect to the host-provided 9P server (example address)
    // fs.connect("tcp://127.0.0.1:5640").expect("cannot connect to 9P server");
    
    fs
}

Combining with Other File Systems

The 9P file system can be layered with other storage backends using the default_fs helper on LinuxShimBuilder, allowing a fallback hierarchy:

let tar_fs = litebox::fs::tar_ro::FileSystem::new(litebox, tar_data);
let ninep_fs = init_filesystem(&litebox);

shim_builder.set_fs(
    shim_builder.default_fs(ninep_fs, tar_fs)   // 9P becomes the primary FS
);

Performing File Operations

Once mounted, operations use the standard FileSystem trait interface:

let fd = ninep_fs.open("/etc/hostname", OFlags::RDONLY, Mode::empty())?;
let mut buf = [0u8; 128];
let n = ninep_fs.read(&fd, &mut buf, None)?;
println!("Hostname file ({} bytes): {}", n, std::str::from_utf8(&buf[..n])?);

Migration from VSBox

LiteBox's 9P protocol support is explicitly designed as a replacement for the 9P client previously provided by VSBox. The architecture allows LiteBox to either import VSBox's existing client implementation or develop a native replacement that conforms to the same FileSystem trait interface.

The migration path involves:

1. Implementing the wire protocol logic in litebox/src/fs/nine_p.rs
2. Removing the debug-only host file pre-loader from litebox_runner_snp/src/main.rs
3. Updating LinuxShimBuilder configurations to use nine_p::FileSystem instead of in-memory workarounds

Summary

• LiteBox defines a placeholder 9P protocol support module at litebox/src/fs/nine_p.rs that implements the FileSystem trait but currently contains only todo!() stubs.
• The 9P implementation follows the same trait-based architecture as in_mem::FileSystem and tar_ro::FileSystem, ensuring API compatibility across storage backends.
• Debug builds currently use a temporary host-file pre-loader in litebox_runner_snp/src/main.rs that will be removed once 9P support is functional.
• When complete, the 9P protocol support will enable mounting remote directories via the Plan 9 file system protocol without copying data into the sandbox's memory.
• The design allows layering 9P with other file systems using LinuxShimBuilder::default_fs() to create fallback hierarchies.

Frequently Asked Questions

What is the current status of 9P protocol support in LiteBox?

LiteBox currently contains a placeholder implementation in litebox/src/fs/nine_p.rs. The module defines the FileSystem struct and implements the required trait, but all methods contain todo!() macros indicating they are not yet functional. The code structure follows the same pattern as the working in_mem and tar_ro file systems.

How will LiteBox use the 9P protocol once implemented?

Once fully implemented, LiteBox will use the 9P protocol to mount remote directories from a host or network server directly into the sandboxed environment. This eliminates the need to pre-load files into an in-memory file system. The 9P-backed file system will implement the standard FileSystem trait, allowing code to open, read, write, and seek remote files using the same API as local storage.

Why does LiteBox have a debug-only file loader in litebox_runner_snp?

The litebox_runner_snp/src/main.rs file contains a debug-only workaround that pre-loads specific host files into an in-memory file system. This temporary code exists only until the 9P protocol support is migrated from VSBox to LiteBox. The loader is wrapped in #[cfg(debug_assertions)] attributes and includes comments indicating it will be removed once nine_p::FileSystem is functional.

Can the 9P file system be combined with other storage backends?

Yes, LiteBox's architecture allows layering the 9P file system with other backends such as tar_ro::FileSystem. Using the default_fs method on LinuxShimBuilder, developers can create a fallback hierarchy where the 9P file system serves as the primary storage, with other file systems providing default or fallback content. This pattern maintains the uniform FileSystem trait interface across all storage types.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}