SquidStd.Vfs 0.28.0

<h1 align="center">SquidStd.Vfs</h1>

A path-based virtual filesystem abstraction for SquidStd with interchangeable backends. One interface (IVirtualFileSystem) is implemented by real directories, a single zip archive, and an in-memory store - and decorated by an encrypted vault in SquidStd.Crypto. VfsDirectories is a VFS-backed analogue of DirectoriesConfig, so named directory layouts work over any backend (a zip or an encrypted container can stand in for real folders).

Install

dotnet add package SquidStd.Vfs

Usage

using DryIoc;
using SquidStd.Vfs.Abstractions.Interfaces;
using SquidStd.Vfs.Extensions;
using SquidStd.Vfs.Services;

// Register a backend as IVirtualFileSystem (singleton).
container.RegisterVfs(_ => new PhysicalFileSystem("/var/lib/app/data"));
// or: new ZipFileSystem("/var/lib/app/data.zip")
// or: new InMemoryFileSystem()

var fs = container.Resolve<IVirtualFileSystem>();

await fs.WriteAllBytesAsync("docs/cv.pdf", bytes);
byte[]? data = await fs.ReadAllBytesAsync("docs/cv.pdf");

await foreach (var entry in fs.ListAsync("docs"))
{
    Console.WriteLine($"{entry.Path} ({entry.Size} bytes)");
}

await fs.DeleteAsync("docs/cv.pdf");

Named directories over any backend:

var dirs = new VfsDirectories(fs, ["data", "logs"]);
var target = dirs.Combine("data", "report.csv");   // "data/report.csv"
await fs.WriteAllBytesAsync(target, csvBytes);

Logical paths are normalized (forward slashes, root-relative) and reject .. traversal via SquidStd.Vfs.Abstractions.VfsPath.

Key types

Decorators

Decorators wrap any IVirtualFileSystem to add behaviour without touching the backend. Stack them in any order.

Composition example - S3 with a local disk cache for resilience to an unstable connection:

// S3 with a local disk cache for resilience to an unstable connection.
var fs = new CachingFileSystem(
    remote: s3FileSystem,
    cache:  new PhysicalFileSystem("/var/cache/app"));

Decorators are not registered via DI helpers; construct them explicitly and pass the result to RegisterVfs(...):

container.RegisterVfs(_ => new ReadOnlyFileSystem(new PhysicalFileSystem("/var/lib/app/data")));

Related

• Tutorial: Virtual filesystem

License

MIT - part of SquidStd.