157 lines
4.1 KiB
Markdown
157 lines
4.1 KiB
Markdown
# 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:
|
|
|
|
```v
|
|
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
|
|
|
|
```v
|
|
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:
|
|
```bash
|
|
v test vfs/
|