# 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