Robbiblubber.Util.FileStorageAdapters 1.0.2

robbiblubber.org File Storage Adapters Library

The robbiblubber.org File Storage Adapters Library provides a common API for accessing file-oriented storage systems. Applications can work with files and directories independently of the underlying storage technology, while adapters handle the details of local file systems, FTP servers, SharePoint document libraries, and other storage providers.

The library supports synchronous and asynchronous operations. Asynchronous methods accept a CancellationToken and form the primitive API used by adapter implementations; the common base classes provide the corresponding synchronous operations and other functionality that can be composed from these primitives.

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 File Storage Adapters Library is provided under the MIT license and may be used without restrictions under the conditions of this license agreement.

Storage Model

Storage content is represented through three core interfaces:

• IElement defines common metadata and operations for files and directories.
• IFile represents readable file content exposed as a Stream.
• IDirectory provides navigation, enumeration, creation, upload, and lookup operations.

Each storage adapter implements IAdapter. Calling OpenDirectory(path) returns an initial IDirectory from which its contents can be accessed.

The library also provides ElementBase, FileBase, and DirectoryBase. Adapter implementations only need to supply the native asynchronous operations and metadata that cannot be derived from another operation.

Supported Operations

The common API includes:

• listing and asynchronously enumerating files and directories;
• resolving files, directories, and generic elements by path;
• reading files as streams;
• creating and deleting files and directories;
• copying and moving elements;
• uploading local files and directory trees;
• downloading files and directory trees; and
• filtering directory contents using file-system-style expressions.

Copy and move operations may cross file-system boundaries. Where no native operation is available, files are transferred through streams and directories are processed recursively. A cross-file-system move is therefore implemented as a successful copy followed by deletion of the source and is not atomic.

Paths

The API uses / as its provider-independent path separator. Backslashes are accepted and normalized to forward slashes.

• Paths beginning with / are resolved from the root directory.
• Relative paths are resolved from the current directory context.
• . refers to the current directory.
• .. refers to the parent directory and does not traverse beyond the root.

The root is defined by the adapter: for SharePoint it is the selected document library; for remote file systems it is the root exposed by the server. Opening an initial directory does not by itself restrict navigation to that directory.

Adapter implementations translate these logical paths to the native addressing scheme of their storage provider. The local adapter also accepts native absolute paths, such as C:\Data on Windows. For path-based operations on a file, relative destinations are resolved from its parent directory.

Overwrite and Merge Behavior

File operations do not overwrite existing content unless overwrite is set to true. CopyToAsync(destination) copies the source into that directory under its existing name. Use the overload with a name argument to rename the copy; copying a directory creates or merges that named child directory.

When a directory is copied or uploaded with overwrite: true and the target directory already exists, its contents are merged. Existing files with the same name are replaced, while unrelated files already present in the target remain unchanged. This is a merge operation, not a synchronization operation.

Copying a directory into itself or one of its descendants is rejected. Adapters may override the common identity checks when provider-specific identifiers are required to detect this reliably.

Example

using Robbiblubber.Util.FileStorageAdapters;

// Pass initialized adapters; their lifetime remains the caller's responsibility.
static async Task CopyReportAsync(IAdapter sourceAdapter, IAdapter targetAdapter)
{
    IDirectory source = sourceAdapter.OpenDirectory("/documents");
    IDirectory target = targetAdapter.OpenDirectory("/incoming");

    IFile file = await source.GetFileAsync("report.pdf");
    await file.CopyToAsync(target, "report.pdf", overwrite: true);
}

The source and target may belong to different adapter implementations. For example, a file may be copied from SharePoint to an FTP server without the calling application depending on either provider-specific API.

Adapters

The adapter projects cover:

• local file systems;
• FTP and FTPS servers;
• POSIX file systems accessed through SSH commands;
• SFTP servers; and
• SharePoint document libraries through Microsoft Graph.

Additional adapters can be added by implementing IAdapter and deriving their file and directory representations from the supplied base classes.

Persisted Attachment Configurations

Serialized attachment configurations contain an adapter discriminator. AttachConfig.Open uses this value to create the corresponding concrete configuration type:

using System.Text.Json.Nodes;
using Robbiblubber.Util.FileStorageAdapters;

JsonObject data = JsonNode.Parse(File.ReadAllText("attachment.json"))!.AsObject();
AttachConfig config = AttachConfig.Open(data);

IAdapter adapter = config.CreateAdapter();
using IDisposable? adapterLifetime = adapter as IDisposable;
IDirectory directory = adapter.OpenDirectory(config.InitialPath);

Adapter libraries register their configuration factory when their assembly is loaded. A host providing an additional adapter can register its configuration type with AttachConfig.Register<TConfig>.

Streams, Lifetime, and Cancellation

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.

Adapters that implement IDisposable should be disposed after their elements and streams are no longer in use. IAdapter itself does not require IDisposable; code managing adapters generically must check for it.

Synchronous wrappers block until their asynchronous operation completes. Cancellation is cooperative and does not roll back completed writes. A failed or cancelled recursive transfer can leave a partially populated destination. The common API does not guarantee preservation of permissions, timestamps, version history, or other provider-specific metadata when copying content.