Expand description
§nfs-crust
An async NFSv4.1 client for Rust applications that want to access an export without creating an OS mount point.
nfs-crust presents a small, object-like API over real files and directories.
It is designed for immutable records such as log chunks, segments, and
content-addressed blobs. Files are written through a temporary name and
published atomically, so readers never see a partial destination.
[!WARNING] This project is experimental. Its authors do not use it in production, and the implementation has not yet received a full human review.
§When It Fits
nfs-crust is a good fit when:
- files are written once and then read without modification;
- each file can be buffered in memory;
- the application needs low-overhead access to an NFS export from Tokio; and
- atomic publication matters more than a general-purpose filesystem API.
It is not a POSIX filesystem implementation. There is no public streaming API, random-write API, or access to NFS file handles and stateids.
§Quick Start
Add the crate to your application:
[dependencies]
nfs-crust = "0.1"The minimum supported Rust version is 1.97. Your application supplies the Tokio runtime.
use bytes::Bytes;
use nfs_crust::{Error, NfsClient, PutMode};
#[tokio::main]
async fn main() -> Result<(), Error> {
let client = NfsClient::builder("127.0.0.1:2049", "/")
.connect()
.await?;
client
.put(
"chunks/00000001",
Bytes::from_static(b"abcdef"),
PutMode::IfNotExists,
)
.await?;
let body = client.get("chunks/00000001").await?;
assert_eq!(&body[..], b"abcdef");
Ok(())
}The first builder argument is the NFS server address and the second is the
export path. The resulting NfsClient acts as a virtual mount. It is cloneable
and can be shared across Tokio tasks; NFSv4.1 session slots bound concurrent
protocol work.
§API
All paths are relative to the configured export.
| Method | Behavior |
|---|---|
put(path, body, mode) | Atomically publishes a complete file, creating parent directories as needed. |
get(path) | Reads a complete file into Bytes. |
get_known_size(path, size) | Reads a complete file without a separate size lookup. |
get_range(path, range) | Reads a byte range into Bytes. |
entry_info(path) | Returns the file type and size. |
delete(path) | Removes a file or empty directory. Missing paths are accepted. |
list_page(directory, limit, token) | Returns one page of direct children. |
sweep_temp_files(directory, age) | Removes stale temporary files left by interrupted puts. |
Leading and trailing slashes are ignored. Empty interior components, NUL,
. and .. are rejected rather than normalized, so paths cannot escape the
export root. Directory operations may address the root; file operations may
not.
§Writes
put writes to a uniquely named temporary file in the destination directory,
commits and verifies it, then publishes it atomically.
PutMode::Overwritecreates or replaces the destination.PutMode::IfNotExistsreturnsError::AlreadyExistsif the destination is occupied.
If the client loses the server’s reply during publication, it returns
Error::OutcomeUnknown. The operation is not replayed because it may already
have succeeded, and replaying it could overwrite another writer. Applications
should reconcile the destination using their own record identity or content
checks.
A process that dies during put may leave a temporary file. Use
sweep_temp_files with an age greater than the longest expected write plus
clock skew. A sweep can partially succeed; if a reply is lost after removal
starts, it also returns Error::OutcomeUnknown.
§Reads and Listing
Reads return buffered Bytes and are capped at 128 MiB by default.
get_known_size avoids the size lookup but returns
Error::FileSizeMismatch if the supplied size is stale. get_range stops at
EOF when the requested range extends beyond the file.
list_page lists direct children only. It does not recurse or treat paths as
key prefixes. Pass the returned continuation token to the next call; the
client never follows pagination implicitly. List entries contain only a name
and root-relative path, so use entry_info when type or size is needed.
§TLS and AWS EFS
Use TlsConfig when the server supports NFS over TLS:
use nfs_crust::{NfsClient, TlsConfig};
let hostname = "fs-1234567890abcdef0.efs.us-east-1.amazonaws.com";
let client = NfsClient::builder(format!("{hostname}:2049"), "/")
.tls(TlsConfig::new(hostname))
.connect()
.await?;The TLS server name must match the endpoint certificate. If the connection
address is an IP address, still pass the certificate’s DNS name to
TlsConfig::new.
AWS EFS IAM client authorization is available behind the aws-efs feature:
nfs-crust = { version = "0.1", features = ["aws-efs"] }Applications load AWS credentials, usually with aws-config, and supply the
credential provider through EfsIamConfig. The client uses it to generate a
short-lived EFS client certificate for each TLS connection. NFS operations
continue to use AUTH_SYS credentials.
§Performance and Configuration
Small reads and puts are combined into as few NFS compounds as possible. Large
reads and writes are chunked and pipelined across session slots. One
NfsClient currently uses one TCP connection; applications that hit a
per-connection throughput limit can create multiple clients and distribute
work across them.
Defaults are tuned for bounded memory use and EFS-style request pricing:
- 64 requested session slots, with at most 16 used by one pipelined operation;
- 1 MiB read and write chunks, with 128 KiB read granularity;
- 30 second connect and operation timeouts;
- a 128 MiB buffered-read limit; and
- file and directory modes of
0644and0755.
The builder exposes the commonly useful limits. In particular, servers that
charge only for bytes returned may benefit from raising read_granularity
toward read_chunk_size. Benchmark against the real server and network path.
NFS servers may serialize mutations within a directory. Hash-sharding keys across subdirectories can reduce contention and keep listing pages small.
§Security
AUTH_SYS provides numeric user and group identity, not cryptographic authentication. Use plaintext NFS only on a trusted, access-controlled network, or use TLS when the server supports it. Keep filesystem permissions and export policy restrictive.
On Unix, the default AUTH_SYS credential uses the process’s effective user and
group IDs plus supplementary groups. Other platforms must configure an
explicit AuthSys value.
The client bounds RPC records, decoded values, compound sizes, file handles, and buffered reads. It does not persist AWS credentials.
§More Detail
- Architecture notes cover NFS compounds, session and reconnect behavior, concurrency, and protocol safety boundaries.
- Testing notes cover the embedded test server and external interoperability suite.
- Benchmark notes cover the benchmark harness and report generation.
- Published benchmark reports provide sanitized AWS EFS comparisons with the Linux NFSv4.1 client.
Licensed under the MIT License.
Structs§
- AuthSys
- AUTH_SYS credentials used for NFS RPC calls.
- Continuation
Token - Opaque continuation token returned by paged directory requests.
- EfsIam
Config - AWS EFS IAM authorization settings.
- Entry
Info - Metadata returned by
NfsClient::entry_info. - List
Entry - Directory entry returned by
NfsClient::list_page. - List
Result - One page of directory entries.
- NfsClient
- A cloneable asynchronous NFSv4.1 client for one export.
- NfsClient
Builder - Builder for configuring and connecting an
NfsClient. - TlsConfig
- TLS settings for RPC transport connections.
Enums§
- Entry
Kind - File type for a directory entry.
- Error
- Errors returned by the NFS client.
- PutMode
- Publish behavior for
NfsClient::putwhen the destination exists.