VirtualFS/docs/backends.md

Backends

This page summarizes the built-in filesystem implementations in VirtualFS.

PhysicalFileSystem

Backs a virtual subtree with a real local directory.

Characteristics:

• writable
• creates the root directory if it does not exist
• maps virtual / separators to host-native separators internally
• supports native file and directory metadata

Good fit for:

• local content directories
• writable application storage
• test fixtures backed by temporary directories

MemoryFileSystem

Stores entries entirely in memory.

Characteristics:

• writable
• no physical path
• lightweight and fast for temporary content

Good fit for:

• generated content
• overlays
• temporary runtime state
• tests

ZipReadFileSystem

Exposes a ZIP archive as a read-only virtual filesystem.

Characteristics:

• read-only
• backed by SharpZipLib
• requires a seekable stream
• optional path scoping to a ZIP subdirectory
• optional regex filtering

Good fit for:

• packaged assets
• static content bundles
• immutable deployment artifacts

EmbeddedResourceFileSystem

Exposes assembly embedded resources as a read-only filesystem.

Characteristics:

• read-only
• backed by manifest resources
• optional root namespace trimming
• optional regex filtering

Good fit for:

• embedded templates
• application assets bundled in assemblies
• shipping immutable defaults inside an executable or library

FtpFileSystem

FTP-backed implementation using FluentFTP.

Characteristics:

• writable
• supports file, directory, and symlink listings
• supports recursive directory deletion
• opens a fresh FTP connection per operation

Good fit for:

• remote FTP stores where a fuller client implementation is needed

Notes:

• network operations are naturally slower than local backends
• deep copy/move operations may become expensive

SimpleFtpFileSystem

Minimal FTP implementation based on FtpWebRequest.

Characteristics:

• writable
• simpler than FtpFileSystem
• recursive delete is implemented in library code

Good fit for:

• compatibility scenarios
• cases where the simpler implementation is sufficient

SimpleFtpCachedFileSystem

Caching layer on top of SimpleFtpFileSystem.

Characteristics:

• caches directory listings by path
• updates cache on some mutations
• reduces repeated directory enumeration cost

Good fit for:

• FTP trees with repeated read-heavy directory access

SFtpFileSystem

SFTP-backed implementation using SSH.NET.

Characteristics:

• writable
• supports password authentication
• supports private key authentication
• can validate host fingerprint
• can forward exceptions to a callback

Good fit for:

• secure remote filesystem access over SFTP

Backend Selection Guidance

Choose a backend based on the shape of the content:

• use PhysicalFileSystem for local writable data
• use MemoryFileSystem for generated or ephemeral data
• use ZipReadFileSystem for immutable packaged assets
• use EmbeddedResourceFileSystem for assembly-bundled assets
• use FtpFileSystem or SFtpFileSystem for remote stores
• use SimpleFtpCachedFileSystem when FTP directory reads are repetitive

Common combinations:

• ZIP as a low-priority base layer + physical overrides as high priority
• physical content + memory-generated overlay
• embedded resources + memory patch layer