Struct VirtualFileSystem 

pub struct VirtualFileSystem { /* private fields */ }

Virtual filesystem manager for lessons

Implementations

impl VirtualFileSystem

pub fn new(lesson_id: &str, session_id: &str) -> Result<Self>

Create a new virtual filesystem for a lesson, on disk, holding the generic practice home (see VirtualFileSystem::seed_generic)

pub fn empty(lesson_id: &str, session_id: &str) -> Result<Self>

Create an empty virtual filesystem on disk: just the lesson home

pub fn in_memory() -> Self

Create an empty virtual filesystem held in memory: just the lesson home. Nothing is ever written to disk.

pub fn for_lesson(lesson: &Lesson, session_id: &str) -> Result<Self>

A sandbox on disk for lesson: its own setup files, plus the generic practice home for Operator lessons. Explorer lessons see only the files they set up. A setup file that can’t be written is logged and skipped.

pub fn for_lesson_in_memory(lesson: &Lesson) -> Result<Self>

VirtualFileSystem::for_lesson, held in memory

pub fn is_in_memory(&self) -> bool

Whether this sandbox is held in memory (rather than on disk)

pub fn seed_generic(&self) -> Result<()>

Seed the generic practice home: Documents, Downloads, Pictures, Music, Videos, projects and a .bashrc, with a few sample files

pub fn resolve_path(&self, virtual_path: &str) -> Result<PathBuf>

Get the real filesystem path for a virtual path.

All ./.. components are resolved lexically and the result is guaranteed to be contained within the sandbox root; paths that would escape it (e.g. ../../../../etc/hostname) return an error. A sandbox held in memory has no real paths: it returns the normalized virtual path (/lesson-home/...), so use VirtualFileSystem::metadata and friends rather than std::fs on the result.

pub fn get_current_dir(&self) -> &Path

Get current directory (virtual path)

pub fn get_current_dir_real(&self) -> PathBuf

Get current directory (real filesystem path; the virtual path for a sandbox held in memory)

pub fn metadata(&self, path: &str) -> Option<Meta>

What is at a path, or None when nothing is (or the path would leave the sandbox)

pub fn exists(&self, path: &str) -> bool

Something exists at this path

pub fn is_dir(&self, path: &str) -> bool

A folder exists at this path

pub fn is_file(&self, path: &str) -> bool

A file exists at this path

pub fn change_directory(&mut self, path: &str) -> Result<String>

Change directory (returns new virtual path)

pub fn list_directory(&self, path: Option<&str>) -> Result<Vec<DirEntry>>

List directory contents

pub fn get_tree(&self, max_depth: usize) -> Vec<TreeNode>

Get directory tree structure

pub fn read_file(&self, path: &str) -> Result<String>

Read file contents (cat command)

pub fn read_bytes(&self, path: &str) -> Result<Vec<u8>>

Read a file’s raw bytes

pub fn write_bytes(&self, path: &str, bytes: &[u8]) -> Result<()>

Write raw bytes to a file, replacing what it held

pub fn set_mode(&self, path: &str, mode: u32) -> Result<()>

Set a path’s permission bits. On a platform without them (a disk sandbox outside Unix) this does nothing.

pub fn create_directory(&self, path: &str, parents: bool) -> Result<()>

Create directory (mkdir command)

pub fn touch_file(&self, path: &str) -> Result<()>

Create or update file (touch command)

pub fn remove(&self, path: &str, recursive: bool, force: bool) -> Result<()>

Remove file or directory (rm command)

pub fn move_item(&self, source: &str, destination: &str) -> Result<()>

Move or rename file/directory (mv command)

pub fn copy( &self, source: &str, destination: &str, recursive: bool, ) -> Result<()>

Copy file or directory (cp command)

pub fn grep_file( &self, pattern: &str, path: &str, case_insensitive: bool, ) -> Result<Vec<(usize, String)>>

Search a file for lines containing pattern (grep command).

Returns the matching lines as (line_number, line) pairs (line numbers are 1-based). Matching is plain substring search; pass case_insensitive for -i behavior.

pub fn head_file(&self, path: &str, n: usize) -> Result<String>

Return the first n lines of a file (head command)

pub fn tail_file(&self, path: &str, n: usize) -> Result<String>

Return the last n lines of a file (tail command)

pub fn wc_file(&self, path: &str) -> Result<(usize, usize, usize)>

Count lines, words and bytes of a file (wc command).

Returns (lines, words, bytes).

pub fn write_file(&self, path: &str, content: &str, append: bool) -> Result<()>

Write content to file (for echo redirection, etc.)

pub fn seed_setup(&self, files: &[SetupFile]) -> Result<()>

Seed lesson starter files (the lesson’s setup list) into the sandbox, creating parent directories as needed. Paths are resolved through the same containment checks as every other operation, so a malicious setup path cannot escape the sandbox.

pub fn cleanup(&self) -> Result<()>

Clean up virtual filesystem

impl VirtualFileSystem

pub fn glob(&self, pattern: &str) -> Vec<String>

Expand a glob against the sandbox (*.txt, logs/day?.log). Only the last part of the path may hold a pattern. Returns the sorted matches, or nothing when none match.

pub fn find(&self, start: &str, query: &FindQuery) -> Result<Vec<String>>

find: walk each start path and list what matches, as paths written from the start path the way it was typed

pub fn disk_usage( &self, path: &str, summarize: bool, ) -> Result<Vec<(String, u64)>>

du: size in bytes of each folder under path (deepest first), or only path itself when summarize

pub fn tar_create( &self, archive: &str, inputs: &[String], gzip: bool, ) -> Result<Vec<String>>

tar -c: pack files and folders into an archive. Returns the entries written, for -v.

pub fn tar_list(&self, archive: &str) -> Result<Vec<String>>

tar -t: list an archive

pub fn tar_extract(&self, archive: &str, dest: &str) -> Result<Vec<String>>

tar -x: unpack into dest (files and folders only; nothing may land outside dest). Returns the entries written.

pub fn gzip(&self, path: &str) -> Result<String>

gzip FILE: compress to FILE.gz and remove FILE

pub fn gunzip(&self, path: &str) -> Result<String>

gunzip FILE.gz: decompress to FILE and remove FILE.gz

pub fn practice_ssh_key( &self, path: &str, kind: &str, comment: &str, ) -> Result<(String, String)>

ssh-keygen -f PATH -C COMMENT: write a PRACTICE key pair. The files have the real shape (a private key readable only by you, a one-line public key) but hold no key material.

Trait Implementations

impl Drop for VirtualFileSystem

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl PracticeWorld for VirtualFileSystem

fn locate(&self, lesson_path: &str) -> Option<PathBuf>

Real path for a path relative to the lesson home, if it stays inside

fn cwd_relative(&self) -> String

Current directory relative to the lesson home (“” at the home)

fn kind_at(&self, lesson_path: &str) -> Option<EntryKind>

What is at a path relative to the lesson home; None when the path would leave it. By default, the real file PracticeWorld::locate gives.

fn read_text(&self, lesson_path: &str) -> Option<String>

A text file’s contents, by a path relative to the lesson home. By default, read from the real file PracticeWorld::locate gives.