@context-fs/nfs

NFS v3 server and mount adapter for @context-fs/core. Mount virtual filesystems as real directories on macOS and Linux.

Installation

npm install @context-fs/nfs

Quick Start

import { createFileSystem, read } from "@context-fs/core";
import { mount } from "@context-fs/nfs";

const vfs = createFileSystem({
  "hello.txt": {
    [read]: () => "Hello from NFS!",
  },
});

// Mount and auto-cleanup with `await using`
await using handle = await mount(vfs, {
  mountPoint: "/tmp/my-vfs",
});

console.log(`Mounted at ${handle.mountPoint}`);
// Now accessible via normal filesystem operations:
// cat /tmp/my-vfs/hello.txt

API

mount(vfs, options)

Starts an NFS server and mounts it to a local directory.

const handle = await mount(vfs, {
  mountPoint: "/tmp/my-vfs", // Required: where to mount
  port: 2049, // Optional: NFS port (default: auto)
  host: "127.0.0.1", // Optional: bind address
  exportName: "/", // Optional: NFS export name
});

// Access mounted filesystem
// ...

// Cleanup
await handle.unmount();

MountHandle

interface MountHandle {
  mountPoint: string;
  port: number;
  host: string;
  unmount(): Promise<void>;
  [Symbol.asyncDispose](): Promise<void>; // For `await using`
}

serve(vfs, options)

Starts an NFS server without mounting. Useful for remote access or custom mount handling.

const server = await serve(vfs, {
  port: 2049, // Optional: defaults to random available port
  host: "0.0.0.0", // Optional: bind to all interfaces
  exportName: "/myfs", // Optional: NFS export path
});

console.log(`NFS server on ${server.getHost()}:${server.getPort()}`);

// Mount manually:
// sudo mount -t nfs -o port=2049,mountport=2049,nfsvers=3,tcp,nolocks localhost:/myfs /mnt/myfs

await server.stop();

Implementing Custom Providers

For advanced use cases, implement FileSystemProvider directly:

import {
  serve,
  type FileSystemProvider,
  type FileAttributes,
} from "@context-fs/nfs";

const provider: FileSystemProvider = {
  rootId: () => BigInt(1),

  async lookup(dirId, name) {
    // Return file ID for name in directory, or null if not found
    return BigInt(2);
  },

  async getattr(fileId) {
    // Return file attributes
    return {
      type: "file",
      mode: 0o644,
      size: BigInt(100),
      mtime: new Date(),
      ctime: new Date(),
      atime: new Date(),
    };
  },

  async read(fileId, offset, count) {
    // Return file data
    return {
      data: Buffer.from("file content"),
      eof: true,
    };
  },

  async readdir(dirId, cookie, count) {
    // Return directory entries
    return {
      entries: [{ fileId: BigInt(2), name: "file.txt" }],
      eof: true,
    };
  },

  // Optional methods for symlinks and writes
  async readlink(fileId) {
    return "/target/path";
  },

  async write(fileId, offset, data) {
    return { count: data.length };
  },

  isWritable(fileId) {
    return true;
  },
};

const server = await serve(provider, { port: 2049 });

Platform Requirements

macOS

Works out of the box. Uses the built-in NFS client.

Linux

Requires NFS client utilities:

# Debian/Ubuntu
sudo apt install nfs-common

# Fedora/RHEL
sudo dnf install nfs-utils

Windows

Not currently supported. Consider using WSL2.

Permissions

Mounting typically requires root/sudo privileges. The mount() function will prompt for sudo password if needed.

For development, you can run your Node.js process with elevated privileges, or configure your system to allow user mounts.

Related Packages

• @context-fs/core - Virtual filesystem core
• @context-fs/cli - CLI framework (uses this package)

License

MIT