@archildata/client

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 @archildata/client

Supported Platforms

This package includes pre-built binaries for:

• macOS (Apple Silicon) - darwin-arm64
• Linux (x86_64) - linux-x64-gnu
• Linux (ARM64) - linux-arm64-gnu

Other platforms are not currently supported.

Note: For best performance, run your application in the same region as your Archil disk (e.g., if your disk is in aws-us-east-1, deploy your app to AWS us-east-1).

Usage

import { ArchilClient } from '@archildata/client';

// Connect to Archil
const client = await ArchilClient.connect({
  region: 'aws-us-east-1',
  diskName: 'myaccount/mydisk',
  authToken: process.env.ARCHIL_TOKEN, // optional, uses IAM if not provided
});

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

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

// Read a file
const lookup = await client.lookupInode(1, 'myfile.txt');
const data = await client.readInode(lookup.inodeId, 0, 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

• connect(config) - Connect using region and disk name (recommended)
• connectDirect(config) - Connect directly to a server (for testing)

Metadata Operations

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

Data Operations

• readInode(inodeId, offset, length, options?) - Read file data
• writeData(inodeId, offset, data, options?) - Write file data (requires delegation)
• sync() - Sync all pending writes to server

Delegation Operations

• checkout(inodeId, options?) - Acquire write delegation
• checkin(inodeId, options?) - Release delegation
• checkinAll() - Release all delegations
• listDelegations() - List currently held delegations

Mutation Operations

• create(parentInodeId, name, attributes, options?) - Create file/directory
• unlink(parentInodeId, name, options?) - Delete file or empty directory
• rename(parentInodeId, name, newParentInodeId, newName, options?) - Move/rename
• setattr(inodeId, attributes, options) - Update file attributes (user required in options)
• setImmutable(inodeId) - Mark subtree as immutable
• setMutable(inodeId) - Mark subtree as mutable
• listImmutableSubtrees() - List immutable roots

Types

interface SimpleConnectionConfig {
  region: string;      // e.g., "aws-us-east-1"
  diskName: string;    // e.g., "myaccount/mydisk"
  authToken?: string;  // optional, uses IAM if not provided
  logLevel?: string;   // optional: "trace", "debug", "info", "warn", "error"
}

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

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

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

interface OperationOptions {
  user?: UnixUser;    // Unix user context for permission checks
}

interface CheckoutOptions {
  force?: boolean;    // Force revoke existing delegations (default: false)
  user?: UnixUser;    // Unix user context for permission checks
}

interface SetAttrAttributes {
  mode?: number;
  uid?: number;
  gid?: number;
  size?: number;
  atimeMs?: number;   // use -1 for current time
  mtimeMs?: number;   // use -1 for current time
}

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.