NfsSharp 0.1.3

NfsSharp

A full-featured .NET NFS client library supporting NFSv2, NFSv3, and NFSv4 with a single, version-agnostic API.

Features

• NFSv2, NFSv3, and NFSv4 support with automatic version negotiation
• Single NfsClient entry point — no version-specific code in your application
• NfsStream integrates seamlessly with all .NET I/O APIs (StreamReader, CopyToAsync, JsonSerializer, etc.)
• AUTH_NONE, AUTH_SYS, and RPCSEC_GSS stub (derive and override to add Kerberos)
• Auto version negotiation: tries NFSv4 → v3 → v2 when NfsVersion.Auto is used
• Retry on transient failures (socket errors, timeouts) with exponential back-off
• Fully seekable streams — NFS is a random-access protocol
• SetLength / SetLengthAsync for remote file truncation/extension
• Set file timestamps (AccessTime, ModifyTime) via NfsSetAttributes on all protocol versions
• Flush / FlushAsync issues an NFS COMMIT RPC to promote unstable writes to stable storage
• Multi-target: net10.0, net9.0, net8.0, and netstandard2.0

Installation

dotnet add package NfsSharp

Or search for NfsSharp in the NuGet Package Manager UI in Visual Studio.

Quick Start

using System.IO;

// Connect and mount
await using var nfs = new NfsClient("nfs.example.com", "/exports/data");
await nfs.ConnectAsync();

// List a directory
var entries = await nfs.ReadDirAsync("reports");
foreach (var entry in entries)
    Console.WriteLine($"{entry.Name}  ({entry.Attributes?.Size ?? 0} bytes)");

// Read a file with StreamReader
await using NfsStream stream = await nfs.OpenFileAsync("reports/q4.csv", FileAccess.Read);
using var reader = new StreamReader(stream);
string content = await reader.ReadToEndAsync();
Console.WriteLine(content);

// Write-only stream to a newly created/truncated file
await using var ws = await nfs.OpenFileAsync("output/result.txt", FileAccess.Write, create: true);
await using var writer = new StreamWriter(ws);
await writer.WriteLineAsync("Hello from NfsSharp!");
await ws.FlushAsync(); // issues NFS COMMIT

Authentication

// AUTH_NONE (default — no credentials)
var nfs = new NfsClient("nfs.example.com", "/export");

// AUTH_SYS (Unix credentials)
var creds = new AuthSysCredentials(
    machineName: "myclient",
    uid: 1000,
    gid: 1000,
    gidList: new uint[] { 100, 200 });
var nfs = new NfsClient("nfs.example.com", "/export", creds);

// RPCSEC_GSS (Kerberos stub — derive and override EncodeBody for full support)
// var creds = new MyKerberosCredentials();

NfsStream

NfsStream is a standard System.IO.Stream. It works with every .NET API that accepts a stream:

await using NfsStream stream = await nfs.OpenFileAsync("data/archive.json", FileAccess.ReadWrite);

// Copy to a local file
using var local = File.Create("archive.json");
await stream.CopyToAsync(local);

// Deserialize JSON directly
var obj = await JsonSerializer.DeserializeAsync<MyData>(stream);

// Truncate / extend a file
await stream.SetLengthAsync(0);   // truncate to empty
await stream.SetLengthAsync(4096); // extend to 4 KiB

// Commit unstable writes to stable storage
await stream.WriteAsync(data);
await stream.FlushAsync(); // issues NFS COMMIT

Downloading and Uploading Files

DownloadFileToLocalAsync and UploadFileFromLocalAsync bypass NfsStream and use parallel ranged NFS READ/WRITE calls for high-throughput bulk transfers.

// Download a remote file to a local path (4 workers, 4 MiB chunks by default)
await nfs.DownloadFileToLocalAsync("backups/db.tar.gz", "/tmp/db.tar.gz");

// Download with a progress callback and custom parallelism
var progress = new Progress<long>(bytes => Console.WriteLine($"Downloaded {bytes} bytes"));
await nfs.DownloadFileToLocalAsync(
    remotePath: "large/video.mp4",
    localPath: "/tmp/video.mp4",
    degreeOfParallelism: 8,
    chunkSize: 8 * 1024 * 1024, // 8 MiB chunks
    progress: progress);

// Upload a local file to a remote path (4 workers, 4 MiB chunks by default)
await nfs.UploadFileFromLocalAsync("/tmp/report.pdf", "reports/report.pdf");

// Upload with a progress callback and custom parallelism
var uploadProgress = new Progress<long>(bytes => Console.WriteLine($"Uploaded {bytes} bytes"));
await nfs.UploadFileFromLocalAsync(
    localPath: "/tmp/dataset.parquet",
    remotePath: "datasets/dataset.parquet",
    degreeOfParallelism: 8,
    chunkSize: 8 * 1024 * 1024, // 8 MiB chunks
    progress: uploadProgress);

Version Negotiation

// Auto: tries NFSv4 → v3 → v2 (default)
var nfs = new NfsClient("server", "/export", NfsVersion.Auto);

// Pin to a specific version
var nfsV3 = new NfsClient("server", "/export", NfsVersion.V3);
var nfsV4 = new NfsClient("server", "/export", NfsVersion.V4);

await nfs.ConnectAsync();
Console.WriteLine($"Negotiated: {nfs.NegotiatedVersion}"); // e.g. V3

API Reference (NfsClient)

Properties

Methods

Constructors

Note: automatic export discovery requires the server to advertise exactly one export. If multiple exports exist, pass exportPath explicitly.

GitHub Actions Setup

CI

The CI workflow runs automatically on every push and pull request. No setup is required.

Publishing to NuGet

1. Fork / clone this repository.
2. Go to Settings → Secrets and variables → Actions.
3. Click New repository secret and add:
   • Name: NUGET_API_KEY
   • Value: Your NuGet.org API key (scoped to push on the NfsSharp package)
4. For trusted publishing:
   • On NuGet.org, navigate to your package → Manage → Trusted publishers → Add GitHub Actions publisher.
   • Enter your GitHub org/repo and workflow file name (publish.yml).
   • Keep NuGet/login@v1 in .github/workflows/publish.yml; it exchanges OIDC for a short-lived NUGET_API_KEY output used by dotnet nuget push.
5. Tag a release to trigger the workflow:

   git tag v0.1.0
   git push origin v0.1.0
   

We accept donations

If you would like to support ongoing development:

• GitHub Sponsors: https://github.com/sponsors/itsWindows11
• GitHub profile: https://github.com/itsWindows11

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub. For large changes, open an issue first to discuss your approach.

License

MIT — see LICENSE for details.