@archil/node

High-performance Node.js bindings for the Archil distributed filesystem client.

Overview

This package provides low-level N-API bindings to the Archil client library, exposing the ArchilService trait methods directly to JavaScript/TypeScript. It's designed for use cases where you need direct protocol access without FUSE overhead.

Installation

npm install @archil/node

Usage

import { ArchilClient } from '@archil/node';

// Connect to Archil (authenticated via mount server)
const client = await ArchilClient.connectAuthenticated({
  mountServer: 'https://mount.archil.io',
  mountName: 'my-account/my-disk',
});

// Get root directory attributes
const rootAttrs = await client.getAttributes(1n);
console.log('Root size:', rootAttrs.size);

// List directory contents
const entries = await client.readDirectory(1n);
for (const entry of entries) {
  console.log(`${entry.name} (inode: ${entry.inodeId})`);
}

// Read a file
const lookup = await client.lookupInode(1n, 'myfile.txt');
const data = await client.readInode(lookup.inodeId, 0n, 1024);
console.log('File content:', data.toString());

// Close when done
await client.close();

API

ArchilClient

The main client class for interacting with Archil filesystems.

Connection Methods

• connectDirect(config) - Connect directly to a server (for testing)
• connectAuthenticated(config) - Connect via mount server with authentication

Metadata Operations

• getAttributes(inodeId, user?) - Get inode attributes
• lookupInode(parentInodeId, name, user?) - Lookup entry by name
• readDirectory(inodeId, offset?, cookie?, user?) - List directory entries
• getExtendedAttribute(inodeId, name, user?) - Get xattr value
• listExtendedAttributes(inodeId, user?) - List xattr names

Data Operations

• readInode(inodeId, offset, length, user?) - Read file data

Delegation Operations

• checkout(inodeId, force?, user?) - Acquire write delegation
• checkin(inodeId, user?) - Release delegation
• checkinAll() - Release all delegations

Mutation Operations

• conditionalCreate(parentInodeId, name, childInodeId, attributes, user?) - Create file/directory
• setImmutable(inodeId) - Mark subtree as immutable
• setMutable(inodeId) - Mark subtree as mutable
• listImmutableSubtrees() - List immutable roots

Types

All inode IDs and file offsets use JavaScript bigint for 64-bit support:

interface UnixUser {
  uid: number;
  gid: number;
}

interface InodeAttributes {
  inodeId: bigint;
  inodeType: 'File' | 'Directory' | 'Symlink' | ...;
  size: bigint;
  uid: number;
  gid: number;
  mode: number;
  nlink: number;
  ctimeMs: number;
  atimeMs: number;
  mtimeMs: number;
  btimeMs: number;
  rdev?: bigint;
  symlinkTarget?: string;
}

interface DirectoryEntry {
  name: string;
  inodeId: bigint;
  inodeType: string;
}

Building

This package uses napi-rs for native bindings. To build from source:

cd rust-libs/archil-node
npm install
npm run build

License

Proprietary - Archil Inc.