@archildata/client 0.1.13 → 0.8.2

package/README.md

@@ -1,168 +1,310 @@
 # @archildata/client
 
-High-performance Node.js bindings for the Archil distributed filesystem client.
+Node.js client for [Archil](https://archil.com) — a high-performance distributed filesystem that turns your cloud storage (S3, GCS, Azure Blob, R2) into something you can read, write, and run commands against like a local disk.
 
-## Overview
+## Quick Start: Connect an S3 Bucket
 
-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.
+This walks you through creating an Archil disk backed by your S3 bucket and running bash commands on it. The whole thing takes about two minutes.
 
-## Installation
+### 1. Sign up
+
+Go to [console.archil.com](https://console.archil.com) and create an account.
+
+### 2. Install
 
 ```bash
 npm install @archildata/client
 ```
 
-## Supported Platforms
+### 3. Create a disk
+
+An Archil "disk" is a filesystem that sits in front of your cloud storage. You create one by telling Archil which bucket to use. This doesn't move or copy your data — Archil reads and writes directly to your bucket.
+
+You also need to authorize a mount token on the disk. This is a separate credential from your API key — it's what clients use to connect to the disk's data plane. Pick any string as the principal (it's just an identifier).
+
+```typescript
+import { Archil } from '@archildata/client/api';
+
+const archil = new Archil({
+  apiKey: 'your-api-key',
+  region: 'aws-us-east-1',
+});
+
+const MOUNT_TOKEN = 'my-secret-mount-token';
+
+const disk = await archil.disks.create({
+  name: 'my-disk',
+  mounts: [{
+    type: 's3',
+    bucketName: 'my-bucket',
+    accessKeyId: 'AKIA...',
+    secretAccessKey: '...',
+  }],
+  authMethods: [{
+    type: 'token',
+    principal: MOUNT_TOKEN,
+    nickname: 'my-mount-token',
+    tokenSuffix: MOUNT_TOKEN.slice(-4),
+  }],
+});
+
+console.log(`Created disk: ${disk.organization}/${disk.name}`);
+```
+
+You only do this once. After that, the disk is available by name whenever you want to connect.
+
+### 4. Run bash commands on it
+
+Install `@archildata/just-bash` to get a shell that runs against your disk:
+
+```bash
+npm install @archildata/just-bash
+```
+
+Then connect using the mount token you authorized above:
 
-This package includes pre-built binaries for:
+```bash
+ARCHIL_TOKEN=my-secret-mount-token npx @archildata/just-bash aws-us-east-1 myaccount/my-disk
+```
 
-- **macOS** (Apple Silicon) - `darwin-arm64`
-- **Linux** (x86_64) - `linux-x64-gnu`
-- **Linux** (ARM64) - `linux-arm64-gnu`
+This drops you into an interactive shell. The files you see are the contents of your S3 bucket:
 
-Other platforms are not currently supported.
+```
+$ ls
+data/  logs/  config.json
 
-> **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).
+$ cat config.json
+{"version": 2, "debug": false}
 
-## Usage
+$ echo "hello from archil" > greeting.txt
+```
+
+Everything you do here — reads, writes, renames, deletes — goes through Archil to your bucket.
+
+## Using just-bash Programmatically
+
+The interactive shell is great for poking around, but you can also run bash commands from your own code. This is useful for scripts, CI pipelines, or anywhere you want to run shell commands against your disk without mounting it.
 
 ```typescript
 import { ArchilClient } from '@archildata/client';
+import { ArchilFs, createArchilCommand } from '@archildata/just-bash';
+import { Bash } from 'just-bash';
 
-// Connect to Archil
+// Connect to your disk
 const client = await ArchilClient.connect({
   region: 'aws-us-east-1',
-  diskName: 'myaccount/mydisk',
-  authToken: process.env.ARCHIL_TOKEN, // optional, uses IAM if not provided
+  diskName: 'myaccount/my-disk',
+  authToken: 'my-secret-mount-token',
 });
 
-// Get root directory attributes
-const rootAttrs = await client.getAttributes(1);
-console.log('Root size:', rootAttrs.size);
+// Create a filesystem adapter and a bash executor
+const fs = await ArchilFs.create(client);
+const bash = new Bash({
+  fs,
+  customCommands: [createArchilCommand(client, fs)],
+});
 
-// List directory contents
-const entries = await client.readDirectory(1);
-for (const entry of entries) {
-  console.log(`${entry.name} (inode: ${entry.inodeId})`);
-}
+// Run commands just like you would in a terminal
+const result = await bash.exec('ls -la /');
+console.log(result.stdout);
+
+// Write a file
+await bash.exec('echo "hello world" > /greeting.txt');
 
-// 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());
+// Read it back
+const cat = await bash.exec('cat /greeting.txt');
+console.log(cat.stdout); // "hello world"
 
-// Close when done
+// Clean up
 await client.close();
 ```
 
-## API
+You can also use the filesystem adapter directly without bash, if you just need standard file operations:
+
+```typescript
+const fs = await ArchilFs.create(client);
+
+// These work like their Node.js fs equivalents
+await fs.writeFile('/notes.txt', 'some content');
+const content = await fs.readFile('/notes.txt');
+const entries = await fs.readdir('/');
+const stats = await fs.stat('/notes.txt');
+await fs.mkdir('/mydir', { recursive: true });
+await fs.cp('/notes.txt', '/mydir/notes-copy.txt');
+await fs.rm('/notes.txt');
+```
+
+## Using the Native Client Directly
+
+For more control, you can use the `ArchilClient` directly. This gives you access to the full filesystem protocol — inodes, delegations, paginated directory reads, etc.
+
+### Connecting
+
+```typescript
+import { ArchilClient } from '@archildata/client';
+
+const client = await ArchilClient.connect({
+  region: 'aws-us-east-1',
+  diskName: 'myaccount/my-disk',
+  authToken: 'my-secret-mount-token',
+});
+```
+
+### Reading files
+
+Every file and directory on an Archil disk has an inode ID. The root directory is always inode `1`. You navigate by looking up names inside directories, then reading the inodes you find.
+
+```typescript
+// Look up a file by name in the root directory
+const entry = await client.lookupInode(1, 'config.json');
+
+// Read its contents
+const data = await client.readInode(entry.inodeId, 0, entry.attributes.size);
+console.log(data.toString());
+```
+
+### Listing directories
+
+```typescript
+const handle = await client.openDirectory(1);
+const page = await client.readDirectory(1, handle, 100);
+
+for (const entry of page.entries) {
+  console.log(`${entry.name} (${entry.inodeType})`);
+}
 
-### `ArchilClient`
+client.closeDirectory(1, handle);
+```
 
-The main client class for interacting with Archil filesystems.
+For large directories, pass the returned `page.nextCursor` back into `readDirectory` to get the next page. When `nextCursor` is `undefined`, you've seen everything.
 
-#### Connection Methods
+### Writing files
 
-- `connect(config)` - Connect using region and disk name (recommended)
-- `connectDirect(config)` - Connect directly to a server (for testing)
+Archil uses a delegation model for writes. Before you can write to a file, you "check out" a delegation on it — this tells the server you intend to modify it and gives you exclusive access. When you're done, you "check in" to release it so other clients can write.
 
-#### Metadata Operations
+```typescript
+// Check out the file to acquire a write delegation
+await client.checkout(inodeId);
 
-- `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
+// Write data
+await client.writeData(inodeId, 0, Buffer.from('new contents'));
 
-#### Data Operations
+// Make sure the write is durable on the server
+await client.sync();
 
-- `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
+// Release the delegation so other clients can write
+await client.checkin(inodeId);
+```
 
-#### Delegation Operations
+### Creating files and directories
 
-- `checkout(inodeId, options?)` - Acquire write delegation
-- `checkin(inodeId, options?)` - Release delegation
-- `checkinAll()` - Release all delegations
-- `listDelegations()` - List currently held delegations
+```typescript
+// Create a directory in root (inode 1)
+const dir = await client.create(1, 'mydir', {
+  inodeType: 'Directory',
+  uid: 1000,
+  gid: 1000,
+  mode: 0o755,
+});
 
-#### Mutation Operations
+// Create a file inside it
+const file = await client.create(dir.inodeId, 'data.txt', {
+  inodeType: 'File',
+  uid: 1000,
+  gid: 1000,
+  mode: 0o644,
+});
 
-- `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
+// Write to the new file
+await client.checkout(file.inodeId);
+await client.writeData(file.inodeId, 0, Buffer.from('file contents'));
+await client.checkin(file.inodeId);
+```
 
-### Types
+### Renaming and deleting
 
 ```typescript
-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"
-}
+await client.rename(parentInodeId, 'old.txt', parentInodeId, 'new.txt');
+await client.unlink(parentInodeId, 'new.txt');
+```
 
-interface UnixUser {
-  uid: number;
-  gid: number;
-}
+### Cleaning up
 
-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;
-}
+Always close the client when you're done. This flushes pending writes and releases any delegations you're still holding.
 
-interface DirectoryEntry {
-  name: string;
-  inodeId: number;
-  inodeType: string;
-}
+```typescript
+await client.close();
+```
 
-interface OperationOptions {
-  user?: UnixUser;    // Unix user context for permission checks
-}
+## Managing Disks
 
-interface CheckoutOptions {
-  force?: boolean;    // Force revoke existing delegations (default: false)
-  user?: UnixUser;    // Unix user context for permission checks
-}
+The control plane API lets you manage disks and access control after initial setup.
 
-interface SetAttrAttributes {
-  mode?: number;
-  uid?: number;
-  gid?: number;
-  size?: number;
-  atimeMs?: number;   // use -1 for current time
-  mtimeMs?: number;   // use -1 for current time
-}
+```typescript
+import { Archil } from '@archildata/client/api';
+
+const archil = new Archil({
+  apiKey: 'your-api-key',
+  region: 'aws-us-east-1',
+});
+
+// List your disks
+const disks = await archil.disks.list();
+
+// Get a specific disk by ID
+const disk = await archil.disks.get('dsk-xxx');
+
+// Authorize another mount token on an existing disk
+const CI_TOKEN = 'ci-mount-token';
+await disk.addUser({
+  type: 'token',
+  principal: CI_TOKEN,
+  nickname: 'ci-token',
+  tokenSuffix: CI_TOKEN.slice(-4),
+});
+
+// Remove access
+await disk.removeUser('token', CI_TOKEN);
+
+// Delete a disk (this does not delete your bucket data)
+await disk.delete();
 ```
 
-## Building
+### Going from a disk to a client
 
-This package uses napi-rs for native bindings. To build from source:
+If you have a `Disk` object from the API, you can connect directly without specifying the region and name again:
 
-```bash
-cd rust-libs/archil-node
-npm install
-npm run build
+```typescript
+const disk = await archil.disks.get('dsk-xxx');
+const client = await disk.mount({ authToken: '<your-token>' });
+
+// client is an ArchilClient — use it for reads, writes, etc.
+await client.close();
 ```
 
-## License
+## Supported Regions
+
+| Region             | Provider |
+| ------------------ | -------- |
+| `aws-us-east-1`   | AWS      |
+| `aws-us-west-2`   | AWS      |
+| `aws-eu-west-1`   | AWS      |
+| `gcp-us-central1` | GCP      |
+
+## Supported Storage Backends
+
+- **Amazon S3** (`type: 's3'`)
+- **Google Cloud Storage** (`type: 'gcs'`)
+- **Azure Blob Storage** (`type: 'azure-blob'`)
+- **Cloudflare R2** (`type: 'r2'`)
+- **S3-compatible services** (`type: 's3-compatible'`)
+
+## Platform Support
+
+The control plane API (`@archildata/client/api`) works on any platform — macOS, Windows, Linux.
+
+The native filesystem client (connecting to disks, reading/writing files) supports **Linux** (x64 or arm64, glibc) and **macOS** (Apple Silicon / arm64). On other platforms, the API-only imports still work.
+
+## Support
 
-Proprietary - Archil Inc.
+Questions, feature requests, or issues? Reach us at **support@archil.com**.