@archildata/client 0.1.13 → 0.8.2

package/{index.d.ts → native.d.ts}

@@ -73,13 +73,49 @@ export interface DirectoryEntry {
   /** Type of the entry (File, Directory, etc.) */
   inodeType: string
 }
+/** Parameters for creating a new inode */
+export interface CreateInodeParams {
+  /** Type of inode to create (File, Directory, Symlink, etc.) */
+  inodeType: string
+  /** Owner user ID */
+  uid: number
+  /** Owner group ID */
+  gid: number
+  /** Unix permission mode */
+  mode: number
+  /** Device ID for block/char devices */
+  rdev?: number
+  /** Symlink target if creating a symlink */
+  symlinkTarget?: string
+}
+/** Result of creating a new inode */
+export interface CreateResult {
+  /** Inode ID of the created entry */
+  inodeId: number
+  /** Final attributes of the created inode (includes SGID inheritance, etc.) */
+  attributes: InodeAttributes
+}
+/** A page of directory entries for paginated reading */
+export interface DirectoryPage {
+  /** Entries in this page */
+  entries: Array<DirectoryEntry>
+  /** Opaque cursor for the next page, or undefined if this is the last page */
+  nextCursor?: string
+}
 /** Lookup response containing inode info */
 export interface LookupResponse {
-  /** Inode ID of the found entry (-1 if not found) */
+  /** Inode ID of the found entry */
   inodeId: number
   /** Attributes of the found inode */
   attributes: InodeAttributes
 }
+/** Result of opening a file */
+export interface OpenFileResult {
+  /** File handle to use for subsequent operations */
+  fileHandle: number
+  /** Whether auto-checkout occurred (delegation will be checked in on release) */
+  needsCheckin: boolean
+}
 /** Connection configuration for direct server connections */
 export interface DirectConnectionConfig {
   /** Server address (e.g., "localhost:8080") */
@@ -218,16 +254,14 @@ export declare class ArchilClient {
   close(): Promise<number>
   /** Get attributes for an inode (uses cache). */
   getAttributes(inodeId: number, options?: OperationOptions | undefined | null): Promise<InodeAttributes>
-  /** Lookup an entry by name in a directory (uses cache). */
-  lookupInode(parentInodeId: number, name: string, options?: OperationOptions | undefined | null): Promise<LookupResponse>
-  /**
-   * Read directory entries.
-   *
-   * Uses the cache layer via snapshot_and_synchronize_directory to ensure
-   * the dirent cache is properly populated. This ensures that subsequent
-   * lookup_inode calls can find the entries returned here.
-   */
-  readDirectory(inodeId: number, options?: OperationOptions | undefined | null): Promise<Array<DirectoryEntry>>
+  /** Lookup an entry by name in a directory (uses cache). Returns null if not found. */
+  lookupInode(parentInodeId: number, name: string, options?: OperationOptions | undefined | null): Promise<LookupResponse | null>
+  /** Open a directory for paginated reading. Returns a file handle. */
+  openDirectory(inodeId: number, options?: OperationOptions | undefined | null): Promise<number>
+  /** Read a page of directory entries using a handle from openDirectory. */
+  readDirectory(inodeId: number, fileHandle: number, limit: number, cursor?: string | undefined | null, options?: OperationOptions | undefined | null): Promise<DirectoryPage>
+  /** Close a directory handle opened with openDirectory. */
+  closeDirectory(inodeId: number, fileHandle: number): void
   /** Get an extended attribute value. */
   getExtendedAttribute(inodeId: number, name: string, options?: OperationOptions | undefined | null): Promise<Buffer | null>
   /** List all extended attribute names. */
@@ -336,10 +370,20 @@ export declare class ArchilClient {
    *
    * Automatically chooses between unconditional create (if we have a delegation
    * on the parent) and conditional create (if we need the server to issue a delegation).
+   */
+  create(parentInodeId: number, name: string, params: CreateInodeParams, options?: OperationOptions | undefined | null): Promise<CreateResult>
+  /**
+   * Open a file for reading or writing.
    *
-   * Returns the inode ID of the created file.
+   * @param accessType - 0 for read, 1 for write, 2 for read-write
    */
-  create(parentInodeId: number, name: string, attributes: InodeAttributes, options?: OperationOptions | undefined | null): Promise<number>
+  openFile(inodeId: number, accessType: number, options?: OperationOptions | undefined | null): Promise<OpenFileResult>
+  /** Release (close) a file handle. */
+  releaseFile(inodeId: number, fileHandle: number, options?: OperationOptions | undefined | null): Promise<void>
+  /** Read the target of a symlink. */
+  readlink(inodeId: number, options?: OperationOptions | undefined | null): Promise<string>
+  /** Check access permissions for an inode. */
+  checkAccess(inodeId: number, mask: number, options?: OperationOptions | undefined | null): Promise<void>
   /** Mark an inode subtree as immutable. */
   setImmutable(inodeId: number): Promise<void>
   /** Mark an inode subtree as mutable (reverse of set_immutable). */

package/native.js

@@ -0,0 +1,99 @@
+/* eslint-disable */
+
+const { existsSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+// Bundlers (tsup, webpack, esbuild, etc.) cannot handle native .node addons.
+// They either silently drop the binary or replace require() with their own
+// resolution, which breaks at runtime. Detect this early with a clear message.
+if (typeof __dirname === 'undefined' || !existsSync(__dirname)) {
+  throw new Error(
+    '@archildata/client contains a native Node.js addon (.node binary) that cannot be loaded ' +
+    'through a bundler (tsup, webpack, esbuild, etc.). Import @archildata/client from ' +
+    'unbundled code only — for example, mark it as external in your bundler config.'
+  )
+}
+
+const SUPPORTED_PLATFORMS = {
+  'linux-x64-gnu': {
+    localFile: 'archildata-client.linux-x64-gnu.node',
+    package: '@archildata/client-linux-x64-gnu',
+  },
+  'linux-arm64-gnu': {
+    localFile: 'archildata-client.linux-arm64-gnu.node',
+    package: '@archildata/client-linux-arm64-gnu',
+  },
+  'darwin-arm64': {
+    localFile: 'archildata-client.darwin-arm64.node',
+    package: '@archildata/client-darwin-arm64',
+  },
+}
+
+function isMusl() {
+  const report = process.report && process.report.getReport && process.report.getReport()
+  if (report) {
+    return !report.header.glibcVersionRuntime
+  }
+  try {
+    const lddPath = require('child_process').execSync('which ldd').toString().trim()
+    return require('fs').readFileSync(lddPath, 'utf8').includes('musl')
+  } catch {
+    return true
+  }
+}
+
+let platformKey
+if (platform === 'darwin') {
+  platformKey = `darwin-${arch}`
+} else if (platform === 'linux') {
+  if (isMusl()) {
+    throw new Error(
+      `@archildata/client does not support musl-based Linux distros (e.g. Alpine). ` +
+      `Current platform: ${platform}/${arch}/musl.`
+    )
+  }
+  platformKey = `linux-${arch}-gnu`
+} else {
+  throw new Error(
+    `@archildata/client only supports Linux (x64, arm64) and macOS (arm64). ` +
+    `Current platform: ${platform}/${arch}.`
+  )
+}
+
+const target = SUPPORTED_PLATFORMS[platformKey]
+
+if (!target) {
+  throw new Error(
+    `@archildata/client does not support ${platform}/${arch}. ` +
+    `Supported platforms: Linux x64, Linux arm64, macOS arm64.`
+  )
+}
+
+let nativeBinding
+
+// Local .node file takes precedence (development builds)
+const localPath = join(__dirname, target.localFile)
+if (existsSync(localPath)) {
+  nativeBinding = require(localPath)
+} else {
+  try {
+    nativeBinding = require(target.package)
+  } catch (e) {
+    throw new Error(
+      `Failed to load native binding for ${platformKey}. ` +
+      `Tried platform package '${target.package}' but it was not installed.\n\n` +
+      `If you're using npm, reinstall with: npm install @archildata/client\n` +
+      `If you're using a bundler (tsup, webpack, esbuild), mark @archildata/client ` +
+      `as external — native .node addons cannot be bundled.\n\n` +
+      `Original error: ${e.message}`
+    )
+  }
+}
+
+const { initLogging, ArchilClient, JsInodeType } = nativeBinding
+
+module.exports.initLogging = initLogging
+module.exports.ArchilClient = ArchilClient
+module.exports.JsInodeType = JsInodeType

package/package.json

@@ -1,24 +1,46 @@
 {
   "name": "@archildata/client",
-  "version": "0.1.13",
+  "version": "0.8.2",
   "description": "High-performance Node.js client for Archil distributed filesystem",
-  "main": "index.js",
-  "types": "index.d.ts",
+  "main": "main.js",
+  "types": "main.d.ts",
+  "exports": {
+    ".": {
+      "types": "./main.d.ts",
+      "import": "./main.mjs",
+      "require": "./main.js"
+    },
+    "./api": {
+      "types": "./dist/api/index.d.ts",
+      "import": "./dist/api/index.mjs",
+      "require": "./dist/api/index.js"
+    },
+    "./native": {
+      "types": "./native.d.ts",
+      "require": "./native.js"
+    }
+  },
   "napi": {
     "name": "archildata-client",
     "triples": {
-      "defaults": true,
+      "defaults": false,
       "additional": [
-        "aarch64-apple-darwin",
         "aarch64-unknown-linux-gnu",
-        "x86_64-apple-darwin",
-        "x86_64-unknown-linux-gnu"
+        "x86_64-unknown-linux-gnu",
+        "aarch64-apple-darwin"
       ]
     }
   },
   "license": "UNLICENSED",
+  "dependencies": {
+    "openapi-fetch": "^0.13.5"
+  },
   "devDependencies": {
-    "@napi-rs/cli": "^2.18.0"
+    "@napi-rs/cli": "^2.18.0",
+    "@types/node": "^20.19.33",
+    "openapi-typescript": "^7.6.1",
+    "tsup": "^8.4.0",
+    "typescript": "^5.9.3"
   },
   "engines": {
     "node": ">= 18"
@@ -27,21 +49,17 @@
     "artifacts": "napi artifacts",
     "build": "napi build --platform --release",
     "build:debug": "napi build --platform",
-    "test": "node --test test/*.js",
-    "universal": "napi universal",
-    "version": "napi version"
+    "build:api": "npm run generate && tsup src/api/index.ts --format cjs,esm --dts --outDir dist/api",
+    "generate": "openapi-typescript ../../api/controlplane/openapi.yaml -o src/api/generated/openapi.d.ts"
   },
   "files": [
-    "index.js",
-    "index.d.ts",
+    "native.js",
+    "native.d.ts",
+    "main.js",
+    "main.mjs",
+    "main.d.ts",
+    "dist/",
     "*.node",
     "README.md"
-  ],
-  "keywords": [
-    "archil",
-    "filesystem",
-    "distributed",
-    "napi",
-    "native"
   ]
-}
+}

package/index.js

@@ -1,317 +0,0 @@
-/* tslint:disable */
-/* eslint-disable */
-/* prettier-ignore */
-
-/* auto-generated by NAPI-RS */
-
-const { existsSync, readFileSync } = require('fs')
-const { join } = require('path')
-
-const { platform, arch } = process
-
-let nativeBinding = null
-let localFileExisted = false
-let loadError = null
-
-function isMusl() {
-  // For Node 10
-  if (!process.report || typeof process.report.getReport !== 'function') {
-    try {
-      const lddPath = require('child_process').execSync('which ldd').toString().trim()
-      return readFileSync(lddPath, 'utf8').includes('musl')
-    } catch (e) {
-      return true
-    }
-  } else {
-    const { glibcVersionRuntime } = process.report.getReport().header
-    return !glibcVersionRuntime
-  }
-}
-
-switch (platform) {
-  case 'android':
-    switch (arch) {
-      case 'arm64':
-        localFileExisted = existsSync(join(__dirname, 'archildata-client.android-arm64.node'))
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./archildata-client.android-arm64.node')
-          } else {
-            nativeBinding = require('@archildata/client-android-arm64')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      case 'arm':
-        localFileExisted = existsSync(join(__dirname, 'archildata-client.android-arm-eabi.node'))
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./archildata-client.android-arm-eabi.node')
-          } else {
-            nativeBinding = require('@archildata/client-android-arm-eabi')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      default:
-        throw new Error(`Unsupported architecture on Android ${arch}`)
-    }
-    break
-  case 'win32':
-    switch (arch) {
-      case 'x64':
-        localFileExisted = existsSync(
-          join(__dirname, 'archildata-client.win32-x64-msvc.node')
-        )
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./archildata-client.win32-x64-msvc.node')
-          } else {
-            nativeBinding = require('@archildata/client-win32-x64-msvc')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      case 'ia32':
-        localFileExisted = existsSync(
-          join(__dirname, 'archildata-client.win32-ia32-msvc.node')
-        )
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./archildata-client.win32-ia32-msvc.node')
-          } else {
-            nativeBinding = require('@archildata/client-win32-ia32-msvc')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      case 'arm64':
-        localFileExisted = existsSync(
-          join(__dirname, 'archildata-client.win32-arm64-msvc.node')
-        )
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./archildata-client.win32-arm64-msvc.node')
-          } else {
-            nativeBinding = require('@archildata/client-win32-arm64-msvc')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      default:
-        throw new Error(`Unsupported architecture on Windows: ${arch}`)
-    }
-    break
-  case 'darwin':
-    localFileExisted = existsSync(join(__dirname, 'archildata-client.darwin-universal.node'))
-    try {
-      if (localFileExisted) {
-        nativeBinding = require('./archildata-client.darwin-universal.node')
-      } else {
-        nativeBinding = require('@archildata/client-darwin-universal')
-      }
-      break
-    } catch {}
-    switch (arch) {
-      case 'x64':
-        localFileExisted = existsSync(join(__dirname, 'archildata-client.darwin-x64.node'))
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./archildata-client.darwin-x64.node')
-          } else {
-            nativeBinding = require('@archildata/client-darwin-x64')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      case 'arm64':
-        localFileExisted = existsSync(
-          join(__dirname, 'archildata-client.darwin-arm64.node')
-        )
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./archildata-client.darwin-arm64.node')
-          } else {
-            nativeBinding = require('@archildata/client-darwin-arm64')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      default:
-        throw new Error(`Unsupported architecture on macOS: ${arch}`)
-    }
-    break
-  case 'freebsd':
-    if (arch !== 'x64') {
-      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
-    }
-    localFileExisted = existsSync(join(__dirname, 'archildata-client.freebsd-x64.node'))
-    try {
-      if (localFileExisted) {
-        nativeBinding = require('./archildata-client.freebsd-x64.node')
-      } else {
-        nativeBinding = require('@archildata/client-freebsd-x64')
-      }
-    } catch (e) {
-      loadError = e
-    }
-    break
-  case 'linux':
-    switch (arch) {
-      case 'x64':
-        if (isMusl()) {
-          localFileExisted = existsSync(
-            join(__dirname, 'archildata-client.linux-x64-musl.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./archildata-client.linux-x64-musl.node')
-            } else {
-              nativeBinding = require('@archildata/client-linux-x64-musl')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        } else {
-          localFileExisted = existsSync(
-            join(__dirname, 'archildata-client.linux-x64-gnu.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./archildata-client.linux-x64-gnu.node')
-            } else {
-              nativeBinding = require('@archildata/client-linux-x64-gnu')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        }
-        break
-      case 'arm64':
-        if (isMusl()) {
-          localFileExisted = existsSync(
-            join(__dirname, 'archildata-client.linux-arm64-musl.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./archildata-client.linux-arm64-musl.node')
-            } else {
-              nativeBinding = require('@archildata/client-linux-arm64-musl')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        } else {
-          localFileExisted = existsSync(
-            join(__dirname, 'archildata-client.linux-arm64-gnu.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./archildata-client.linux-arm64-gnu.node')
-            } else {
-              nativeBinding = require('@archildata/client-linux-arm64-gnu')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        }
-        break
-      case 'arm':
-        if (isMusl()) {
-          localFileExisted = existsSync(
-            join(__dirname, 'archildata-client.linux-arm-musleabihf.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./archildata-client.linux-arm-musleabihf.node')
-            } else {
-              nativeBinding = require('@archildata/client-linux-arm-musleabihf')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        } else {
-          localFileExisted = existsSync(
-            join(__dirname, 'archildata-client.linux-arm-gnueabihf.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./archildata-client.linux-arm-gnueabihf.node')
-            } else {
-              nativeBinding = require('@archildata/client-linux-arm-gnueabihf')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        }
-        break
-      case 'riscv64':
-        if (isMusl()) {
-          localFileExisted = existsSync(
-            join(__dirname, 'archildata-client.linux-riscv64-musl.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./archildata-client.linux-riscv64-musl.node')
-            } else {
-              nativeBinding = require('@archildata/client-linux-riscv64-musl')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        } else {
-          localFileExisted = existsSync(
-            join(__dirname, 'archildata-client.linux-riscv64-gnu.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./archildata-client.linux-riscv64-gnu.node')
-            } else {
-              nativeBinding = require('@archildata/client-linux-riscv64-gnu')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        }
-        break
-      case 's390x':
-        localFileExisted = existsSync(
-          join(__dirname, 'archildata-client.linux-s390x-gnu.node')
-        )
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./archildata-client.linux-s390x-gnu.node')
-          } else {
-            nativeBinding = require('@archildata/client-linux-s390x-gnu')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      default:
-        throw new Error(`Unsupported architecture on Linux: ${arch}`)
-    }
-    break
-  default:
-    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
-}
-
-if (!nativeBinding) {
-  if (loadError) {
-    throw loadError
-  }
-  throw new Error(`Failed to load native binding`)
-}
-
-const { initLogging, ArchilClient, JsInodeType } = nativeBinding
-
-module.exports.initLogging = initLogging
-module.exports.ArchilClient = ArchilClient
-module.exports.JsInodeType = JsInodeType