Robbiblubber.Util.FileStorageAdapters.LocalFileSystem 1.0.2

robbiblubber.org Local File System Adapter Library

The robbiblubber.org Local File System Adapter Library provides access to the local file system through the common API defined by the FileStorageAdapters Library. Applications can work with local files and directories through IFile, IDirectory, and IElement without depending directly on System.IO.

The adapter supports every platform on which the targeted .NET runtime and the required local file-system APIs are available. Paths, directory separators, root directories, and file-system behavior are resolved using the native runtime environment.

The repository can be found at https://bitbucket.org/robbiblubber/robbiblubber.util.filestorageadapters.net/. API documentation is available from https://robbiblubber.lima-city.org/. For general information see http://robbiblubber.org/.

The robbiblubber.org Local File System Adapter Library is provided under the MIT license and may be used without restrictions under the conditions of this license agreement.

Opening a Directory

LfsAdapter implements IAdapter and is stateless. A local directory can be opened through an adapter instance:

using Robbiblubber.Util.FileStorageAdapters;
using Robbiblubber.Util.FileStorageAdapters.LocalFileSystem;

IAdapter adapter = new LfsAdapter();
IDirectory directory = adapter.OpenDirectory("/var/data");

The static convenience method can also open a directory (a Windows path is shown here):

IDirectory directory = LfsAdapter.Open("C:\\Data");

The path must identify an existing directory. The returned IDirectory instance is the initial context for navigation and file operations. It does not restrict access to that directory tree: navigation remains subject to the permissions of the current process.

Persisted Attachment Configurations

LfsAttachConfig stores the initial local directory and can also be used directly:

using System.Text.Json.Nodes;

LfsAttachConfig config = new("C:\\Data");
JsonObject data = config.Serialize();

AttachConfig restored = AttachConfig.Open(data);
LfsAdapter restoredAdapter = (LfsAdapter) restored.CreateAdapter();
IDirectory restoredDirectory = restoredAdapter.OpenDirectory(restored.InitialPath);

Supported Operations

The adapter supports the operations provided by the FileStorageAdapters base library, including:

• listing and asynchronously enumerating local files and directories;
• resolving elements by relative or absolute path;
• reading files as streams;
• creating and deleting files and directories;
• copying and moving files and directory trees;
• uploading local files and directories through the common adapter API;
• downloading files and directory trees; and
• filtering directory contents with file-system-style expressions.

Files may be copied or moved between the local file system and any other FileStorageAdapters implementation. Cross-adapter file transfers use streams; directory transfers are performed recursively.

Platform Behavior

Local paths are normalized with System.IO.Path.GetFullPath. Both / and \ are accepted as logical path separators by the common API and are translated to the native directory separator for operations within a directory. Pass a native platform path to LfsAdapter.Open or OpenDirectory. Relative initial paths are resolved against the process's current working directory.

Name filters are case-insensitive on Windows and case-sensitive on other platforms. Actual path lookup and access rules remain subject to the mounted file system, the operating system, and the permissions of the current process.

Asynchronous stream operations use asynchronous FileStream instances. Some directory operations, such as enumeration, creation, and deletion, are backed by synchronous System.IO APIs because the .NET runtime does not provide equivalent asynchronous primitives. Cancellation is checked between individual enumeration and transfer operations.

Metadata

Local elements expose their native absolute path, creation time, modification time, and size. A directory's size is calculated recursively from its contained files and may therefore require access to the complete directory tree.

Content types and ETags are not supplied by the local file-system adapter and are returned as null.

Symbolic Links and Junctions

Linked directories are excluded from recursive directory-size calculations. Recursive copy and download operations for symbolic directory links and Windows junctions are deliberately rejected to prevent cycles and access outside the expected directory tree.

Deleting a represented directory link removes the link itself rather than the directory to which it points.

Example

IDirectory directory = LfsAdapter.Open("C:\\Data");

IFile source = await directory.GetFileAsync("input/report.txt");
await using Stream content = await source.ReadAsync();

IDirectory output = await directory.CreateDirectoryAsync("output");
IFile copy = await output.CreateFileAsync(
    "report.txt",
    content,
    overwrite: true);

Console.WriteLine(copy.Path);

Streams returned by ReadAsync are owned by the caller and must be disposed. Streams supplied to CreateFileAsync remain owned by the caller and are not disposed by the adapter.

Conflict guarantees

Local file and directory objects retain an immutable path and create independent metadata objects per access. Local file moves use File.Move, including its overwrite handling. Atomicity depends on the filesystem and volume boundary. Recursive and cross-adapter transfers are not transactions.

Staged file writes

CreateFileAsync stages contents in a short-named temporary file in the destination directory. The completed stream is closed before the destination is published. Cancellation and source/write failures before publication leave an existing destination intact. Create-only publication never overwrites a concurrent creator. Existing files are replaced using File.Replace; unsupported replacement operations fail without a delete-and-copy fallback. The shared FileBase.DownloadAsync uses the same staging mechanism for local downloads.

Replacement changes the directory entry: other hard links keep referencing the old file. Unix mode bits are preserved; ownership, extended attributes and ACL behavior depend on the platform. Concurrent external metadata changes are not transactional. Publication requires permission to create and replace entries in the parent directory. Cancellation cannot roll back publication once it has started, and cleanup after a failure is best effort.

The package-free regression checks can be run with:

dotnet run --project tests/LocalWriteChecks/LocalWriteChecks.csproj