{"id":29878282,"url":"https://github.com/yasufadhili/vfs","last_synced_at":"2025-07-31T07:03:44.272Z","repository":{"id":306561722,"uuid":"1026593017","full_name":"yasufadhili/vfs","owner":"yasufadhili","description":"Virtual File System Package for my Personal Projects","archived":false,"fork":false,"pushed_at":"2025-07-26T07:59:03.000Z","size":16,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-26T13:37:40.742Z","etag":null,"topics":["embed","file-system","go","golang","vfs","virtual-filesystem"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yasufadhili.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-26T07:41:47.000Z","updated_at":"2025-07-26T08:11:06.000Z","dependencies_parsed_at":"2025-07-26T13:37:45.926Z","dependency_job_id":"4033c9f4-88ef-42a5-a3d9-48dc3d33786f","html_url":"https://github.com/yasufadhili/vfs","commit_stats":null,"previous_names":["yasufadhili/vfs"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/yasufadhili/vfs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yasufadhili%2Fvfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yasufadhili%2Fvfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yasufadhili%2Fvfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yasufadhili%2Fvfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yasufadhili","download_url":"https://codeload.github.com/yasufadhili/vfs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yasufadhili%2Fvfs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268003452,"owners_count":24179290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["embed","file-system","go","golang","vfs","virtual-filesystem"],"created_at":"2025-07-31T07:01:44.176Z","updated_at":"2025-07-31T07:03:44.257Z","avatar_url":"https://github.com/yasufadhili.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VFS - Virtual File System Package\n\nA flexible, reusable virtual file system implementation in Go that seamlessly integrates in-memory, disk-based, and embedded filesystems.\nBuilt for my personal learning projects including compilers, networking tools, and cybersecurity utilities.\n\n## Features\n\n- **Multiple Filesystem Types**:\n  - **Memory**: Fast, in-memory file operations.\n  - **Disk**: A VFS that interacts directly with the local filesystem.\n  - **Hybrid**: A combination of in-memory and embedded filesystems.\n- **Unified Interface**: A single API for all VFS types.\n- **File Watching**: Monitor disk-based VFS for changes.\n- **Bundled Filesystems**: Register multiple embedded filesystems with custom prefixes.\n- **Advanced Operations**: Clone and merge filesystems.\n- **Flexible Configuration**: Options pattern for clean setup.\n- **Comprehensive File Ops**: Full CRUD operations, directory traversal, and pattern matching.\n- **Optional Logging**: Debug and error logging support.\n- **Testing-friendly**: Interface-based design for easy mocking.\n\n## Installation\n\n```bash\ngo get github.com/yasufadhili/vfs\n```\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n\t\"embed\"\n\t\"fmt\"\n\t\"log\"\n\t\"time\"\n\n\t\"github.com/yasufadhili/vfs\"\n)\n\n//go:embed stdlib/*\nvar stdlibFS embed.FS\n\nfunc main() {\n\t// 1. Create a hybrid VFS for in-memory and embedded files\n\thybridVFS := vfs.NewHybridVFS()\n\thybridVFS.RegisterBundled(\"stdlib\", stdlibFS, \"stdlib\")\n\n\t// 2. Create a disk-based VFS to watch for source file changes\n\tdiskVFS := vfs.NewDiskVFS(\"./src\", vfs.WithLogger(\u0026vfs.NullLogger{}))\n\tdefer diskVFS.Close()\n\n\t// 3. Watch for changes\n\tdiskVFS.Watch(\"/\", func(event vfs.WatchEvent) {\n\t\tlog.Printf(\"File %s changed: %s\", event.Path, event.Op)\n\t})\n\n\t// 4. Write a file to the hybrid VFS\n\thybridVFS.WriteFile(\"/main.go\", []byte(\"package main\"), 0644)\n\n\t// 5. Read from both memory and embedded files\n\tmainFile, _ := hybridVFS.ReadFileString(\"/main.go\")\n\tstdlibFile, _ := hybridVFS.ReadFileString(\"stdlib://core.go\")\n\n\tfmt.Printf(\"Main file: %s\n\", mainFile)\n\tfmt.Printf(\"Stdlib file: %s\n\", stdlibFile)\n\n\t// Keep the application running to receive watch events\n\ttime.Sleep(10 * time.Second)\n}\n```\n\n## Use Cases in My Projects\n\n### Compiler Projects\n```go\n// A hybrid VFS for the standard library and a disk VFS for user code\ncompilerVFS := vfs.NewHybridVFS()\ncompilerVFS.RegisterBundled(\"stdlib\", stdlibEmbed, \"lib\")\nuserCodeVFS := vfs.NewDiskVFS(\"./project\")\n\n// Compile with access to both user code and stdlib\nsourceCode, _ := userCodeVFS.ReadFileString(\"/main.jml\")\nstdlibCode, _ := compilerVFS.ReadFileString(\"stdlib://fmt.jml\")\n```\n\n### Network Tools\n```go\n// Load configuration from disk and embedded payloads\ntoolVFS := vfs.NewHybridVFS()\ntoolVFS.RegisterBundled(\"payloads\", payloadsEmbed, \"\")\ntoolVFS.LoadFromDisk(\"./configs\", \"/configs\")\n\n// Access both\npayload, _ := toolVFS.ReadFile(\"payloads://reverse_shell.bin\")\nconfig, _ := toolVFS.ReadFile(\"/configs/target.json\")\n```\n\n### Build Systems\n```go\n// Use different VFS for different stages of the build\nsourceVFS := vfs.NewDiskVFS(\"./project\")\nbuildVFS := vfs.NewMemoryVFS()\n\n// ... build process ...\n\n// Save the build artifacts to disk\nbuildVFS.SaveToDisk(\"/\", \"./build\")\n```\n\n## API Reference\n\n### Core Operations\n\n```go\n// File I/O\nReadFile(filename string) ([]byte, error)\nReadFileString(filename string) (string, error)\nWriteFile(filename string, data []byte, perm fs.FileMode) error\n\n// Directory operations\nMkdirAll(path string, perm fs.FileMode) error\nRemove(path string) error\nRemoveAll(path string) error\n\n// File system queries\nExists(path string) bool\nIsDir(path string) bool\nStat(path string) (fs.FileInfo, error)\n```\n\n### Directory Listing\n\n```go\n// List contents\nListFiles(dir string) ([]string, error)\nListDirs(dir string) ([]string, error)\nWalk(root string, walkFn filepath.WalkFunc) error\n\n// Pattern matching\nFindFiles(root, pattern string) ([]string, error)\n```\n\n### Utility Operations\n\n```go\n// File operations\nCopy(src, dst string) error\nMove(src, dst string) error\n\n// Disk integration\nLoadFromDisk(srcPath, destPath string) error\nSaveToDisk(srcPath, destPath string) error\n```\n\n### Advanced Operations\n\n```go\n// Clone a VFS\nClone() FileSystem\n\n// Merge one VFS into another\nMerge(other FileSystem, destPath string) error\n```\n\n### File Watching\n\n```go\n// Watch for file changes\nWatch(path string, action WatchAction) error\nStopWatch(path string) error\nStopAllWatches() error\nIsWatching(path string) bool\n```\n\n### Configuration\n\n```go\n// Factory functions\nNewMemoryVFS(opts ...Option) *VFS\nNewDiskVFS(rootPath string, opts ...Option) *VFS\nNewHybridVFS(opts ...Option) *VFS\n\n// Configuration options\nWithLogger(logger Logger) Option\nWithRoot(root string) Option\n\n// Register embedded filesystems\nRegisterBundled(prefix string, embedFS embed.FS, subdir string) error\n```\n\n## Path Conventions\n\n- **Regular files**: `/path/to/file.ext` or `path/to/file.ext`\n- **Bundled files**: `prefix://path/to/file.ext`\n- **Examples**:\n  - `stdlib://fmt.go` - Standard library file\n  - `templates://config.tmpl` - Template file\n  - `/src/main.go` - Regular VFS file\n\n## Dependencies\n\n- `github.com/spf13/afero` - Virtual filesystem abstraction\n- `github.com/fsnotify/fsnotify` - File system notifications\n- Go 1.16+ (for `embed.FS` support)\n\n## Project Structure\n\n```\nvfs/\n├── vfs.go          # Core interfaces and factory functions\n├── main.go         # Main VFS implementation\n├── bundled.go      # Embedded filesystem handling\n├── watch.go        # File watching implementation\n├── README.md       # This file\n├── examples/       # Usage examples\n└── vfs_test.go     # Test files\n```\n\n## Future Enhancements\n\n- [ ] Compression support for bundled files\n- [ ] Caching layer for frequently accessed files\n- [ ] Plugin system for custom filesystem backends\n- [ ] Metrics and performance monitoring\n\n## Notes\n\nThis is a personal project designed for my specific use cases in mainly learning compiler development, networking tools, and cybersecurity utilities. The API prioritises simplicity and flexibility over backwards compatibility—breaking changes may occur as I evolve the design based on real-world usage in my projects.\n\nThe package draws inspiration from Go's `embed.FS`, `afero`, and various VFS implementations I've encountered in systems programming and compiler design.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyasufadhili%2Fvfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyasufadhili%2Fvfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyasufadhili%2Fvfs/lists"}