Virtual File System (VFS) Module

This module provides a pluggable virtual filesystem interface that allows different storage backends to implement a common set of filesystem operations.

Interface

The VFS interface (VFSImplementation) defines the following operations:

Basic Operations

• root_get() !FSEntry - Get the root directory entry

File Operations

• file_create(path string) !FSEntry - Create a new file
• file_read(path string) ![]u8 - Read file contents as bytes
• file_write(path string, data []u8) ! - Write bytes to a file
• file_delete(path string) ! - Delete a file

Directory Operations

• dir_create(path string) !FSEntry - Create a new directory
• dir_list(path string) ![]FSEntry - List directory contents
• dir_delete(path string) ! - Delete a directory

Symlink Operations

• link_create(target_path string, link_path string) !FSEntry - Create a symbolic link
• link_read(path string) !string - Read symlink target
• link_delete(path string) ! - Delete a symlink

Common Operations

• exists(path string) bool - Check if path exists
• get(path string) !FSEntry - Get entry at path
• rename(old_path string, new_path string) !FSEntry - Rename/move an entry
• copy(src_path string, dst_path string) !FSEntry - Copy an entry
• move(src_path string, dst_path string) !FSEntry - Move an entry
• delete(path string) ! - Delete any type of entry
• destroy() ! - Clean up VFS resources

FSEntry Interface

All filesystem entries implement the FSEntry interface:

interface FSEntry {
    get_metadata() Metadata
    get_path() string
    is_dir() bool
    is_file() bool
    is_symlink() bool
}

Implementations

Local Filesystem (vfs_local)

Direct passthrough to the operating system's filesystem.

Features:- Native filesystem access

• Full POSIX compliance
• Preserves file permissions and metadata

Database Filesystem (vfs_db)

Stores files and metadata in a database backend.

Features:- Persistent storage in database

• Transactional operations
• Structured metadata storage

Nested Filesystem (vfs_nested)

Allows mounting other VFS implementations at specific paths.

Features:- Composite filesystem views

• Mix different implementations
• Flexible organization

Implementation Standards

When creating a new VFS implementation:

1. Directory Structure:

vfs_<name>/
├── factory.v           # Implementation factory/constructor
├── vfs_implementation.v # Core interface implementation
├── model_*.v          # Data structure definitions
├── README.md          # Implementation documentation
└── *_test.v          # Tests

2. Naming Conventions:

• Implementation module: vfs_<name>
• Main struct: <Name>VFS (e.g., LocalVFS, DatabaseVFS)
• Factory function: new_<name>_vfs()

3. Error Handling:

• Use descriptive error messages
• Include path information in errors
• Handle edge cases (e.g., missing files, type mismatches)

4. Documentation:

• Document implementation-specific behavior
• Note any limitations or special features
• Include usage examples

Usage Example

import vfs

fn main() ! {
    // Create a local filesystem implementation
    mut fs := vfs.new_vfs('local', '/tmp/test')!

    // Create and write to a file
    fs.file_create('test.txt')!
    fs.file_write('test.txt', 'Hello, World!'.bytes())!

    // Read file contents
    content := fs.file_read('test.txt')!
    println(content.bytestr())

    // Create and list directory
    fs.dir_create('subdir')!
    entries := fs.dir_list('subdir')!

    // Create symlink
    fs.link_create('test.txt', 'test_link.txt')!

    // Clean up
    fs.destroy()!
}

Contributing

To add a new VFS implementation:

1. Create a new directory vfs_<name> following the structure above
2. Implement the VFSImplementation interface
3. Add factory function to create your implementation
4. Include comprehensive tests
5. Document implementation details and usage
6. Update the main VFS documentation

Testing

Each implementation must include tests that verify:- All interface methods

• Error conditions
• Edge cases
• Implementation-specific features

Run tests with:

v test vfs/

fn new_metadata(metadata Metadata) Metadata

mkdir creates a new directory with default permissions

interface FSEntry {
	get_metadata() Metadata
	// get_path() string
	is_dir() bool
	is_file() bool
	is_symlink() bool
}

FSEntry represents a filesystem entry (file, directory, or symlink)

interface VFSImplementation {
mut:
	// Basic operations
	root_get() !FSEntry

	// File operations
	file_create(path string) !FSEntry
	file_read(path string) ![]u8
	file_write(path string, data []u8) !
	file_concatenate(path string, data []u8) !
	file_delete(path string) !

	// Directory operations
	dir_create(path string) !FSEntry
	dir_list(path string) ![]FSEntry
	dir_delete(path string) !

	// Symlink operations
	link_create(target_path string, link_path string) !FSEntry
	link_read(path string) !string
	link_delete(path string) !

	// Common operations
	exists(path string) bool
	get(path string) !FSEntry
	rename(old_path string, new_path string) !FSEntry
	copy(src_path string, dst_path string) !FSEntry
	move(src_path string, dst_path string) !FSEntry
	delete(path string) !

	// FSEntry Operations
	get_path(entry &FSEntry) !string

	print() !

	// Cleanup operation
	destroy() !
}

VFSImplementation defines the interface that all vfscore implementations must follow

enum FileType {
	file
	directory
	symlink
}

FileType represents the type of a filesystem entry

struct Metadata {
pub mut:
	id          u32    @[required] // unique identifier used as key in DB
	name        string @[required] // name of file or directory
	file_type   FileType
	size        u64
	created_at  i64 // unix epoch timestamp
	modified_at i64 // unix epoch timestamp
	accessed_at i64 // unix epoch timestamp
	mode        u32 // file permissions
	owner       string
	group       string
}

Metadata represents the common metadata for both files and directories

fn (m Metadata) created_time() time.Time

Get time.Time objects from epochs

fn (m Metadata) modified_time() time.Time

fn (m Metadata) accessed_time() time.Time

fn (mut m Metadata) modified()

fn (mut m Metadata) accessed()