xrootd 0.1.11 → 0.2.0

package/README.md

@@ -1,23 +1,144 @@
-# XRootD Typescript Support
+# 🚀 XRootD TypeScript Support (`xrootd`)
 
-> [!WARNING]
-> **Working in process**. This package is currently under active development and not ready for production use. Stay tuned!
+A high-performance, enterprise-grade Node.js binding for the [XRootD](https://github.com/xrootd/xrootd) client library. Designed to bring seamless, extreme-throughput data access to the TypeScript ecosystem.
 
-- now complete: FileSystem/Url/Env
-- in progress: File/CopyProcess/ErrorProcess/And others
+> [!NOTE]
+> **Work in Progress**: This package is currently under active development. While core features are highly functional, the API may undergo minor refinements.
+
+
+## Supported Capabilities
+
+* **`FileSystem`**: Cluster-level operations (`stat`, `dirList`, `rm`, `mkdir`, `locate`).
+* **`File`**: High-performance I/O (`open`, `read`, `write`, `vectorRead`, server-side `clone`).
+* **`CopyProcess`**: Asynchronous, highly-parallel data transfers with real-time progress callbacks.
+* **`Env`**: Type-safe configuration management and OS-level auth protocol routing.
+* **`Url`**: XRootD-specific URI scheme parsing and validation.
+
+
+## Prerequisites
+
+To ensure compatibility with the pre-compiled native bindings, your environment must meet the following requirements:
+
+* **Node.js**: Version 20.x or higher.
+* **System Dependencies (Linux)**: Requires `libstdc++` providing `GLIBCXX_3.4.26` or newer (typically GCC 9+, e.g., CentOS 9 / Ubuntu 20.04+).
+* **System Dependencies (Macos)**: Requires macos 14 or later for arm64 architecture, macos 15 or later for intel architecture.
+* **Authentication**: Ensure your host machine has valid tickets (e.g., `kinit` for Kerberos) if accessing a secured cluster.
+
+
+## Installation
+
+```bash
+npm install xrootd
+# or
+yarn add xrootd
+
+```
 
 ---
 
-minimium gcc version for linux: GLIBCXX_3.4.26 (GCC 9 or newer) <br> minimium node version: node20
+## Usage Examples
+
+### 1. Configuration & Basic FileSystem
+
+```typescript
+import { Env, FileSystem } from 'xrootd';
+
+// Safely configure underlying XRootD environment
+Env.configure({
+    RequestTimeout: 30,       // Prevent 30-min infinite hangs (Node.js friendly)
+    WorkerThreads: 4,         // Boost underlying multiplexing
+    SecProtocol: 'krb5,unix'  // Force Kerberos or Unix socket auth
+});
+
+const fs = new FileSystem('root://eos01.ihep.ac.cn/');
+
+async function checkCluster() {
+    try {
+        const stat = await fs.stat('/eos/lhaaso/data');
+        console.log(`Directory size: ${stat.size} bytes`);
+        console.log(`Modified at: ${stat.modTimeAsString}`);
+    } catch (err: any) {
+        if (err.code === 'ENOENT') {
+            console.error('File not found in cluster.');
+        } else {
+            console.error(err.message);
+        }
+    }
+}
+
+```
+
+### 2. Zero-Copy File Reading
+
+```typescript
+import { File, OpenFlags } from 'xrootd';
+
+async function readHeader() {
+    const file = new File();
+    
+    // Auto-translates and handles C++ lifecycle
+    await file.open('root://eos01.ihep.ac.cn//eos/test.dat', OpenFlags.Read);
+    
+    // The returned buffer is a zero-copy mapping of C++ allocated memory
+    const buffer = await file.read(0n, 1024);
+    console.log(buffer.toString('utf-8'));
+    
+    await file.close();
+}
+
+```
+
+### 3. High-Performance CopyProcess with Progress
+
+```typescript
+import { CopyProcess } from 'xrootd';
+
+async function syncData() {
+    const cp = new CopyProcess();
+    
+    cp.addJob({
+        source: 'root://eos01.ihep.ac.cn//eos/data.raw',
+        target: '/local/disk/data.raw',
+        force: true,
+        parallelChunks: 4
+    });
+
+    await cp.prepare();
+    
+    const results = await cp.run((jobNum, processed, total) => {
+        const percent = ((processed / total) * 100).toFixed(2);
+        console.log(`Job ${jobNum} Progress: ${percent}%`);
+    });
+
+    console.log('Copy completed:', results);
+}
+
+```
+
+## ✨ Why `xrootd`? (Core Architecture)
+
+Unlike traditional Node.js C++ addons, `xrootd` is architected for **High Energy Physics (HEP)** and **Big Data** workloads:
+
+*  **True Native Async**: Bypasses the notoriously limited Node.js `libuv` thread pool (default 4 threads). It hooks directly into XRootD's underlying C++ event loop via N-API `ThreadSafeFunction`, allowing thousands of concurrent requests without blocking the V8 engine.
+*  **Absolute Zero-Copy I/O**: Implements direct memory handoffs. Data read from the EOS cluster is mounted directly as V8 `Buffer` objects without a single byte of internal memory copying, completely eliminating GC (Garbage Collection) pauses during heavy I/O.
+*  **Idiomatic Node.js Experience**: "Thin C++, Thick TS". Complex XRootD protocol errors (e.g., `3011`) are smartly translated into standard Node.js exceptions (e.g., `ENOENT`, `EACCES`), complete with system call contexts and retryable flags.
+*  **Zero-Config Authentication**: Bundles essential security plugins (Kerberos, SSS, Unix, Token) natively. Path injection is handled automatically under the hood—no more `[FATAL] Auth failed` or missing `.so` nightmares.
 
 ---
 
-License
+##  Licensing
+
+This project is released under a **Dual License** strategy to balance open-source compatibility and developer freedom:
 
-This project follows the dual license: [GNU GPLv3](LICENSE-GPLv3) and [MIT](LICENSE-MIT).
+1. **[GNU GPLv3](https://www.google.com/search?q=https://www.gnu.org/licenses/gpl-3.0.en.html)**: The native binding codebase adheres to the GPLv3 license to remain fully compatible with the upstream C++ XRootD project.
+2. **[MIT](https://www.google.com/search?q=https://opensource.org/licenses/MIT)**: The core TypeScript APIs, interface definitions, and glue layers are provided under the MIT license, allowing you to integrate the TS components into your own software architectures without viral restrictive requirements.
 
-The XRootD project is GPL, so this project is also GPL. However, the API of this project is provided under MIT license, so you can use this project in your project without any restriction.
+*Disclaimer: This project is a third-party community initiative built for modern web ecosystems and is not affiliated with, officially endorsed by, or sponsored by the core XRootD project.*
+
+---
 
+## Contributing
 
+We welcome contributions from the high-energy physics, astrophysics, and Node.js communities! Whether it's reporting bugs, improving documentation, or adding support for advanced XRootD features.
 
-This project is not affiliated with the XRootD project. It is a third-party project that provides a Node.js interface to the XRootD library.
+*Contribution guidelines coming soon.*

package/dist/index.cjs

@@ -144,13 +144,20 @@ var File = class {
 	async read(offset, size) {
 		return this._internal.Read(BigInt(offset), size);
 	}
+	async write(offset, arg1, arg2, arg3) {
+		if (Buffer.isBuffer(arg1)) return this._internal.Write(BigInt(offset), arg1);
+		else if (typeof arg1 === "number" && typeof arg2 === "number") return this._internal.WriteFd(BigInt(offset), arg1, arg2, arg3 !== void 0 ? BigInt(arg3) : void 0);
+		else throw new TypeError("Invalid arguments for write");
+	}
 	/**
-	* 写入文件块
-	* @param offset 偏移量
-	* @param buffer 要写入的数据
+	* 从本地 fd 写入文件块 (直接映射)
+	* @param offset 写入的起始字节偏移量。
+	* @param size 写入大小。
+	* @param fd 本地文件描述符 (fd)。
+	* @param fdoff 可选，从本地 fd 中读取的起始偏移。
 	*/
-	async write(offset, buffer) {
-		return this._internal.Write(BigInt(offset), buffer);
+	async writeFd(offset, size, fd, fdoff) {
+		return this._internal.WriteFd(BigInt(offset), size, fd, fdoff !== void 0 ? BigInt(fdoff) : void 0);
 	}
 	/**
 	* 同步文件缓冲区到磁盘
@@ -172,7 +179,9 @@ var File = class {
 		return this._internal.IsOpen();
 	}
 	async getProperty(name) {
-		return this._internal.GetProperty(name);
+		const ret = this._internal.GetProperty(name);
+		if (ret.success) return ret.value;
+		throw new Error("TODO");
 	}
 	async setProperty(name, value) {
 		return this._internal.SetProperty(name, value);
@@ -204,25 +213,37 @@ var File = class {
 	/**
 	* 设置文件的扩展属性
 	*/
-	async setXAttr(name, value) {
-		return this._internal.SetXAttr(name);
+	async setXAttrs(attrs) {
+		return this._internal.SetXAttr(attrs);
+	}
+	/**
+	* 设置文件的扩展属性
+	*/
+	async setXAttr(key, value) {
+		return (await this._internal.SetXAttr({ [key]: value }))[0].ok;
 	}
 	/**
 	* 获取文件的扩展属性
 	*/
-	async getXAttr(name) {
-		return this._internal.GetXAttr(name);
+	async getXAttrs(keys) {
+		return this._internal.GetXAttr(keys);
+	}
+	async getXAttr(key) {
+		return (await this._internal.GetXAttr([key]))[key];
 	}
 	/**
 	* 删除文件的扩展属性
 	*/
-	async delXAttr(name) {
-		return this._internal.DelXAttr(name);
+	async delXAttrs(keys) {
+		return this._internal.DelXAttr(keys);
+	}
+	async delXAttr(key) {
+		return (await this._internal.DelXAttr([key]))[0].ok;
 	}
 	/**
-	* 列出文件所有的扩展属性名称
+	* 列出文件所有的扩展属性和内容
 	*/
-	async listXAttr() {
+	async listXAttrs() {
 		return this._internal.ListXAttr();
 	}
 	/**
@@ -528,25 +549,34 @@ var FileSystem = class {
 	* @param targetPath 目标路径
 	* @param attrs 扩展属性键值对记录
 	*/
-	async setXAttr(targetPath, attrs) {
+	async setXAttrs(targetPath, attrs) {
 		return this._internal.SetXAttr(this._normalize(targetPath), attrs);
 	}
+	async setXAttr(targetPath, key, value) {
+		return (await this.setXAttrs(targetPath, { [key]: value }))[0].ok;
+	}
 	/**
 	* 获取扩展属性
 	* @param targetPath 目标路径
 	* @param keys 需要获取的属性名数组
 	*/
-	async getXAttr(targetPath, keys) {
+	async getXAttrs(targetPath, keys) {
 		return this._internal.GetXAttr(this._normalize(targetPath), keys);
 	}
+	async getXAttr(targetPath, key) {
+		return (await this.getXAttrs(targetPath, [key]))[key];
+	}
 	/**
 	* 删除指定的扩展属性
 	* @param targetPath 目标路径
 	* @param keys 需要删除的属性名数组
 	*/
-	async delXAttr(targetPath, keys) {
+	async delXAttrs(targetPath, keys) {
 		return this._internal.DelXAttr(this._normalize(targetPath), keys);
 	}
+	async delXAttr(targetPath, key) {
+		return (await this.delXAttrs(targetPath, [key]))[0].ok;
+	}
 	/**
 	* 列出目标文件或目录的所有扩展属性
 	*/
@@ -555,6 +585,47 @@ var FileSystem = class {
 	}
 };
 //#endregion
+//#region lib/copy.ts
+var CopyProcess = class {
+	nativeCp;
+	constructor() {
+		this.nativeCp = new nativeAddon.CopyProcess();
+	}
+	/**
+	* Add a job to the copy process synchronously
+	*/
+	addJob(config) {
+		this.nativeCp.AddJob(config);
+	}
+	/**
+	* Asynchronously prepare the jobs (resolve DNS, check endpoints, etc.)
+	*/
+	async prepare() {
+		return this.nativeCp.Prepare();
+	}
+	/**
+	* Run the copy process.
+	* @param onProgress Optional progress callback
+	* @returns Array of results corresponding to the jobs added
+	*/
+	async run(onProgress) {
+		if (onProgress) this.nativeCp.SetEventListener("progress", onProgress);
+		return this.nativeCp.Run();
+	}
+	/**
+	* Abort the running copy process.
+	*/
+	abort() {
+		this.nativeCp.CancelJob();
+	}
+	/**
+	* Abort the running copy process. (alias for abort)
+	*/
+	cancelJob() {
+		this.nativeCp.CancelJob();
+	}
+};
+//#endregion
 //#region lib/url.ts
 /**
 * 纯 TypeScript 实现的 XRootD URL 解析器
@@ -656,14 +727,91 @@ var XRootDUrl = class XRootDUrl {
 };
 //#endregion
 //#region lib/env.ts
-const Env = {
-	putInt: nativeAddon.Env.PutInt,
-	putString: nativeAddon.Env.PutString,
-	getInt: nativeAddon.Env.GetInt,
-	getString: nativeAddon.Env.GetString
+function checkIntRange(key, value) {
+	const num = Number(value);
+	if (num < -2147483648 || num > 2147483647) console.warn(`[xrootd] Warning: value ${value} for key "${key}" is out of 32-bit signed integer range [-2147483648, 2147483647]. It will be truncated.`);
+}
+var XRootDEnvironment = class {
+	constructor() {}
+	/**
+	* 设置整数配置项，返回是否设置成功。
+	*/
+	putInt(key, intVal) {
+		checkIntRange(key, intVal);
+		const success = nativeAddon.Env.PutInt(key, Number(intVal));
+		if (!success) console.warn(`[xrootd] Warning: Failed to set integer configuration "${key}"=${intVal}. It might have been overridden by a system environment variable.`);
+		return success;
+	}
+	/**
+	* 设置字符串配置项，返回是否设置成功。
+	*/
+	putString(key, strVal) {
+		if (key === "SecProtocol") {
+			process.env.XrdSecPROTOCOL = strVal;
+			process.env.XRD_SECPROTOCOL = strVal;
+			return true;
+		}
+		const success = nativeAddon.Env.PutString(key, strVal);
+		if (!success) console.warn(`[xrootd] Warning: Failed to set string configuration "${key}"="${strVal}". It might have been overridden by a system environment variable.`);
+		return success;
+	}
+	/**
+	* 设置布尔配置项，返回是否设置成功。
+	*/
+	putBoolean(key, boolVal) {
+		if (typeof boolVal === "boolean") boolVal = boolVal ? "true" : "false";
+		return this.putString(key, boolVal);
+	}
+	/**
+	* 获取整数配置项。
+	*/
+	getInt(key) {
+		return nativeAddon.Env.GetInt(key) ?? void 0;
+	}
+	/**
+	* 获取字符串配置项。
+	*/
+	getString(key) {
+		if (key === "SecProtocol") return process.env.XrdSecPROTOCOL ?? process.env.XRD_SECPROTOCOL ?? void 0;
+		return nativeAddon.Env.GetString(key) ?? void 0;
+	}
+	/**
+	* 批量安全地设置 XRootD 底层参数
+	*/
+	configure(config) {
+		for (const [key, value] of Object.entries(config)) {
+			if (value === void 0 || value === null) continue;
+			let success = true;
+			if (key === "SecProtocol") {
+				process.env.XrdSecPROTOCOL = String(value);
+				process.env.XRD_SECPROTOCOL = String(value);
+				continue;
+			}
+			if (typeof value === "number" || typeof value === "bigint") {
+				checkIntRange(key, value);
+				success = nativeAddon.Env.PutInt(key, Number(value));
+			} else if (typeof value === "string") success = nativeAddon.Env.PutString(key, value);
+			else if (typeof value === "boolean") success = nativeAddon.Env.PutString(key, value ? "true" : "false");
+			else {
+				console.warn(`[xrootd] Unhandled type ${typeof value} for key ${key}.`);
+				success = nativeAddon.Env.PutString(key, value.toString());
+			}
+			if (!success) console.warn(`[xrootd] Warning: Failed to set configuration "${key}"=${value}. It might have been overridden by a system environment variable.`);
+		}
+	}
+	get(key) {
+		if (key === "SecProtocol") return process.env.XrdSecPROTOCOL ?? process.env.XRD_SECPROTOCOL ?? void 0;
+		return nativeAddon.Env.GetInt(key) ?? nativeAddon.Env.GetString(key) ?? void 0;
+	}
 };
+const Env = new XRootDEnvironment();
+Env.configure({
+	RequestTimeout: 30,
+	WorkerThreads: 4
+});
 //#endregion
 exports.AccessMode = AccessMode;
+exports.CopyProcess = CopyProcess;
 exports.Env = Env;
 exports.File = File;
 exports.FileSystem = FileSystem;