xrootd 0.1.6

package/LICENSE-MIT

@@ -0,0 +1,7 @@
+Copyright 2026 Aluria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# XRootD Typescript Support
+
+> [!WARNING]
+> **Working in process**. This package is currently under active development and not ready for production use. Stay tuned!
+
+- now complete: FileSystem/Url/Env
+- in progress: File/CopyProcess/ErrorProcess/And others
+
+---
+
+minimium gcc version for linux: GLIBCXX_3.4.26 (GCC 9 or newer) <br> minimium node version: node20
+
+---
+
+License
+
+This project follows the dual license: [GNU GPLv3](LICENSE-GPLv3) and [MIT](LICENSE-MIT).
+
+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.
+
+
+
+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.

package/dist/index.cjs

@@ -0,0 +1,672 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let node_stream = require("node:stream");
+let node_gyp_build = require("node-gyp-build");
+node_gyp_build = __toESM(node_gyp_build, 1);
+let node_path = require("node:path");
+node_path = __toESM(node_path, 1);
+let node_url = require("node:url");
+//#region lib/native.ts
+const nativeAddon = (0, node_gyp_build.default)(node_path.default.resolve(__dirname, ".."));
+//#endregion
+//#region lib/enums.ts
+/**
+* XrdCl::OpenFlags - 文件打开选项
+* @see src/XProtocol/XProtocol.hh:XOpenRequestOption
+* @see src/XrdCl/XrdClFileSystem.hh:OpenFlags::Flags
+*/
+const OpenFlags = {
+	None: 0,
+	Compress: 1,
+	Delete: 2,
+	Force: 4,
+	New: 8,
+	Read: 16,
+	Update: 32,
+	Refresh: 128,
+	MakePath: 256,
+	IntentDirList: 1024,
+	Replica: 2048,
+	POSC: 4096,
+	NoWait: 8192,
+	SeqIO: 16384,
+	Write: 32768,
+	PrefName: 256,
+	Dup: 65536,
+	Samefs: 131072
+};
+/**
+* XrdCl::Access - 文件访问权限模式
+* @see src/XProtocol/XProtocol.hh:XOpenRequestMode
+* @see src/XrdCl/XrdClFileSystem.hh:Access::Mode
+*/
+const AccessMode = {
+	None: 0,
+	UR: 256,
+	UW: 128,
+	UX: 64,
+	GR: 32,
+	GW: 16,
+	GX: 8,
+	OR: 4,
+	OW: 2,
+	OX: 1
+};
+/**
+* XrdCl::MkDirFlags - 目录创建选项
+* @see src/XrdCl/XrdClFileSystem.hh:MkDirFlags::Flags
+*/
+const MkDirFlags = {
+	None: 0,
+	MakePath: 1
+};
+const StatFlags = {
+	XBitSet: 1,
+	//!< Executable/searchable bit set
+	IsDir: 2,
+	//!< This is a directory
+	Other: 4,
+	//!< Neither a file nor a directory
+	Offline: 8,
+	//!< File is not online (ie. on disk)
+	POSCPending: 64,
+	//!< File opened with POST flag, not yet successfully closed
+	IsReadable: 16,
+	//!< Read access is allowed
+	IsWritable: 32,
+	//!< Write access is allowed
+	BackUpExists: 128
+};
+//!< Back up copy exists
+//#endregion
+//#region lib/file.ts
+/**
+* XRootD File 客户端
+* 提供对远程文件的异步读写操作及 Node.js 风格的流式接口。
+*/
+var File = class {
+	_internal;
+	constructor(internalInstance) {
+		if (internalInstance) this._internal = internalInstance;
+		else {
+			if (!nativeAddon || !nativeAddon.File) throw new Error("Native addon not loaded properly.");
+			this._internal = new nativeAddon.File();
+		}
+	}
+	/**
+	* 打开远程文件
+	* @param url 目标地址 (如 root://server//path/to/file)
+	* @param flags 打开标志位
+	* @param mode 访问权限模式
+	*/
+	async open(url, flags = OpenFlags.None, mode = AccessMode.None) {
+		return this._internal.Open(url, flags, mode);
+	}
+	/**
+	* 关闭文件
+	*/
+	async close() {
+		return this._internal.Close();
+	}
+	/**
+	* 获取文件状态
+	*/
+	async stat() {
+		return this._internal.Stat();
+	}
+	/**
+	* 读取文件块 (Zero-Copy from C++)
+	* @param offset 偏移量 (支持 >2GB)
+	* @param size 读取字节数
+	* @returns 包含数据的 Node.js Buffer
+	*/
+	async read(offset, size) {
+		return this._internal.Read(BigInt(offset), size);
+	}
+	/**
+	* 写入文件块
+	* @param offset 偏移量
+	* @param buffer 要写入的数据
+	*/
+	async write(offset, buffer) {
+		return this._internal.Write(BigInt(offset), buffer);
+	}
+	/**
+	* 同步文件缓冲区到磁盘
+	*/
+	async sync() {
+		return this._internal.Sync();
+	}
+	/**
+	* 截断文件
+	* @param size 目标大小
+	*/
+	async truncate(size) {
+		return this._internal.Truncate(BigInt(size));
+	}
+	/**
+	* 检查本地实例状态 (同步操作)
+	*/
+	isOpen() {
+		return this._internal.IsOpen();
+	}
+	async getProperty(name) {
+		return this._internal.GetProperty(name);
+	}
+	async setProperty(name, value) {
+		return this._internal.SetProperty(name, value);
+	}
+	/**
+	* 向量化读取 (Vector Read)
+	* 在单个请求中从文件的多个非连续区域读取数据，极大地减少网络往返开销。
+	* @param chunks 包含 offset 和 size 的读取请求数组
+	* @returns 与请求数组顺序对应的 Buffer 数组
+	*/
+	async vectorRead(chunks) {
+		const normalizedChunks = chunks.map((c) => ({
+			offset: BigInt(c.offset),
+			size: c.size
+		}));
+		return this._internal.VectorRead(normalizedChunks);
+	}
+	/**
+	* 读取块 (Read Chunks)
+	* 类似于 VectorRead，但底层实现可能利用更高级的预读或多路复用策略。
+	*/
+	async readChunks(chunks) {
+		const normalizedChunks = chunks.map((c) => ({
+			offset: BigInt(c.offset),
+			size: c.size
+		}));
+		return this._internal.ReadChunks(normalizedChunks);
+	}
+	/**
+	* 设置文件的扩展属性
+	*/
+	async setXAttr(name, value) {
+		return this._internal.SetXAttr(name);
+	}
+	/**
+	* 获取文件的扩展属性
+	*/
+	async getXAttr(name) {
+		return this._internal.GetXAttr(name);
+	}
+	/**
+	* 删除文件的扩展属性
+	*/
+	async delXAttr(name) {
+		return this._internal.DelXAttr(name);
+	}
+	/**
+	* 列出文件所有的扩展属性名称
+	*/
+	async listXAttr() {
+		return this._internal.ListXAttr();
+	}
+	/**
+	* 将其他文件的指定区间在服务器端克隆到当前文件
+	* 当前文件必须以写入/更新模式打开
+	*/
+	clone(locations) {
+		return this._internal.Clone(locations);
+	}
+	/**
+	* 创建一个可读流 (Readable Stream)
+	* 使得 XRootD 文件可以无缝 pipe 到其他 Node.js 流 (如本地 fs, HTTP response)
+	*/
+	createReadStream(options = {}) {
+		let currentOffset = options.start ?? 0n;
+		const endOffset = options.end;
+		const chunkSize = options.highWaterMark ?? 64 * 1024;
+		const self = this;
+		return new node_stream.Readable({
+			highWaterMark: chunkSize,
+			async read(size) {
+				try {
+					let bytesToRead = size;
+					if (endOffset !== void 0) {
+						const remaining = endOffset - currentOffset + 1n;
+						if (remaining <= 0n) {
+							this.push(null);
+							return;
+						}
+						if (remaining < BigInt(bytesToRead)) bytesToRead = Number(remaining);
+					}
+					const buffer = await self.read(currentOffset, bytesToRead);
+					if (buffer.length === 0) this.push(null);
+					else {
+						currentOffset += BigInt(buffer.length);
+						this.push(buffer);
+					}
+				} catch (err) {
+					this.destroy(err instanceof Error ? err : new Error(String(err)));
+				}
+			}
+		});
+	}
+	/**
+	* 创建一个可写流 (Writable Stream)
+	* 支持通过 pipe 将大量数据流式写入 XRootD 服务器
+	*/
+	createWriteStream(options = {}) {
+		let currentOffset = options.start ?? 0n;
+		const self = this;
+		return new node_stream.Writable({
+			async write(chunk, encoding, callback) {
+				try {
+					const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, encoding);
+					await self.write(currentOffset, buffer);
+					currentOffset += BigInt(buffer.length);
+					callback();
+				} catch (err) {
+					callback(err instanceof Error ? err : new Error(String(err)));
+				}
+			},
+			async writev(chunks, callback) {
+				try {
+					const buffers = chunks.map((c) => Buffer.isBuffer(c.chunk) ? c.chunk : Buffer.from(c.chunk, c.encoding));
+					const masterBuffer = Buffer.concat(buffers);
+					await self.write(currentOffset, masterBuffer);
+					currentOffset += BigInt(masterBuffer.length);
+					callback();
+				} catch (err) {
+					callback(err instanceof Error ? err : new Error(String(err)));
+				}
+			}
+		});
+	}
+};
+//#endregion
+//#region lib/utils.ts
+function reverseStr(str) {
+	let reversed = "";
+	for (let i = str.length - 1; i >= 0; i--) reversed += str.charAt(i);
+	return reversed;
+}
+function isXrdError(e) {
+	return e instanceof Error && "xrdStatus" in e && typeof e.xrdStatus === "number" && e.xrdStatus > 0;
+}
+//#endregion
+//#region lib/filesystem.ts
+/**
+* XRootD FileSystem 客户端
+* 提供对远程服务器目录和文件的通用管理操作。
+*/
+var FileSystem = class {
+	_internal;
+	serverUrl;
+	/**
+	* 实例化一个 FileSystem 客户端
+	* @param url 服务器地址 (例如: 'root://eospublic.cern.ch')
+	*/
+	constructor(url) {
+		if (!nativeAddon || !nativeAddon.FileSystem) throw new Error("Native addon not loaded properly. Cannot instantiate FileSystem.");
+		this.serverUrl = url;
+		this._internal = new nativeAddon.FileSystem(url);
+	}
+	/**
+	* 内部辅助方法：确保路径是标准的 Unix 绝对路径
+	*/
+	_normalize(targetPath) {
+		const posixPath = node_path.posix.normalize(targetPath);
+		return posixPath.startsWith("/") ? posixPath : "/" + posixPath;
+	}
+	/**
+	* 定位文件在集群中的具体数据节点
+	* @param filePath 目标文件路径
+	* @param flags 定位标志位 (默认 0)
+	* @returns 包含主机、端口等信息的数组
+	*/
+	async locate(filePath, flags = 0) {
+		return this._internal.Locate(this._normalize(filePath), flags);
+	}
+	/**
+	* 获取文件或目录的状态信息
+	* @param targetPath 目标路径
+	*/
+	async stat(targetPath) {
+		const rawStat = await this._internal.Stat(this._normalize(targetPath));
+		return {
+			...rawStat,
+			get modeOctal() {
+				return reverseStr(rawStat.modeAsOctString);
+			},
+			get modeString() {
+				return reverseStr(rawStat.modeAsString);
+			},
+			get isFile() {
+				return (rawStat.flags & StatFlags.IsDir) === 0 && (rawStat.flags & StatFlags.Other) === 0;
+			},
+			get isDir() {
+				return (rawStat.flags & StatFlags.IsDir) !== 0;
+			},
+			get isOther() {
+				return (rawStat.flags & StatFlags.Other) !== 0;
+			},
+			get isOffline() {
+				return (rawStat.flags & StatFlags.Offline) !== 0;
+			},
+			get isPOSCPending() {
+				return (rawStat.flags & StatFlags.POSCPending) !== 0;
+			},
+			get isReadable() {
+				return (rawStat.flags & StatFlags.IsReadable) !== 0;
+			},
+			get isWritable() {
+				return (rawStat.flags & StatFlags.IsWritable) !== 0;
+			},
+			get isBackUpExists() {
+				return (rawStat.flags & StatFlags.BackUpExists) !== 0;
+			}
+		};
+	}
+	/**
+	* 删除远程文件
+	* @param filePath 要删除的文件路径
+	*/
+	async rm(filePath) {
+		return this._internal.Rm(this._normalize(filePath));
+	}
+	/**
+	* 创建远程目录
+	* @param dirPath 目录路径
+	* @param flags 标志位 (例如 MakePath，允许创建多级父目录)
+	* @param mode 访问权限模式 (默认 0755 对应的 AccessMode)
+	*/
+	async mkdir(dirPath, flags = MkDirFlags.None, mode = AccessMode.UR | AccessMode.UW | AccessMode.UX | AccessMode.GR | AccessMode.GX | AccessMode.OR | AccessMode.OX) {
+		return this._internal.MkDir(this._normalize(dirPath), flags, mode);
+	}
+	/**
+	* 删除远程目录 (目录必须为空)
+	* @param dirPath 要删除的目录路径
+	*/
+	async rmdir(dirPath) {
+		return this._internal.RmDir(this._normalize(dirPath));
+	}
+	/**
+	* 移动或重命名文件/目录
+	* @param source 源路径
+	* @param dest 目标路径
+	*/
+	async mv(source, dest) {
+		return this._internal.Mv(this._normalize(source), this._normalize(dest));
+	}
+	/**
+	* 列出目录下的所有文件和子目录名
+	* @param dirPath 目录路径
+	* @param flags 标志位 (例如是否显示隐藏文件)
+	*/
+	async dirList(dirPath, flags = 0) {
+		return this._internal.DirList(this._normalize(dirPath), flags);
+	}
+	/**
+	* 检查文件或目录是否存在
+	* (通过捕获 stat 的错误来实现，类似于老版本 Node 的 fs.exists)
+	* @param targetPath 目标路径
+	*/
+	async exists(targetPath) {
+		try {
+			await this.stat(targetPath);
+			return true;
+		} catch (err) {
+			debugger;
+			if (isXrdError(err)) {
+				if (err.xrdErrNo === 3011) return false;
+			}
+			throw err;
+		}
+	}
+	/**
+	* 确保目录存在。如果目录不存在，则会自动创建它及其所有父目录。
+	* (类似于 fs-extra 的 ensureDir 或 mkdir -p)
+	* @param dirPath 目标目录
+	*/
+	async ensureDir(dirPath) {
+		if (!await this.exists(dirPath)) await this.mkdir(dirPath, MkDirFlags.MakePath);
+	}
+	/**
+	* 深度定位：返回包含所有数据节点副本的详细物理位置信息
+	*/
+	async deepLocate(filePath, flags = 0) {
+		return this._internal.DeepLocate(this._normalize(filePath), flags);
+	}
+	/**
+	* 在不打开文件的情况下，直接截断目标文件
+	*/
+	async truncate(filePath, size) {
+		return this._internal.Truncate(this._normalize(filePath), size);
+	}
+	/**
+	* 更改远程文件或目录的访问权限
+	*/
+	async chmod(targetPath, mode) {
+		return this._internal.ChMod(this._normalize(targetPath), mode);
+	}
+	/**
+	* 探活：检查远端文件系统服务是否响应
+	*/
+	async ping() {
+		return this._internal.Ping();
+	}
+	/**
+	* 获取虚拟文件系统(VFS)的状态（如磁盘总容量、剩余可用空间）
+	*/
+	async statVFS(targetPath) {
+		return this._internal.StatVFS(this._normalize(targetPath));
+	}
+	/**
+	* 获取当前连接协议的详细属性
+	*/
+	async protocol() {
+		return this._internal.Protocol();
+	}
+	/**
+	* 发送带外查询指令到数据节点 (通常用于 XRootD 的高级自定义插件)
+	*/
+	async query(queryCode, args) {
+		return this._internal.Query(queryCode, args);
+	}
+	/**
+	* 发送通用信息到服务器
+	*/
+	async sendInfo(info) {
+		return this._internal.SendInfo(info);
+	}
+	/**
+	* 发送缓存操作信息给集群
+	*/
+	async sendCache(info) {
+		return this._internal.SendCache(info);
+	}
+	/**
+	* 数据预热/暂存 (Staging)：
+	* 在处理海量物理数据时，通知存储集群将特定的冷数据（如磁带上的文件）提前拉取到磁盘缓存。
+	* @param targetPaths 需要预热的路径数组
+	* @param flags 预热策略标志
+	* @param priority 优先级
+	*/
+	async prepare(targetPaths, flags = 0, priority = 0) {
+		const normalizedPaths = targetPaths.map((p) => this._normalize(p));
+		return this._internal.Prepare(normalizedPaths, flags, priority);
+	}
+	/**
+	* 获取文件系统属性
+	*/
+	getProperty(name) {
+		return this._internal.GetProperty(name);
+	}
+	/**
+	* 设置文件系统属性
+	*/
+	setProperty(name, value) {
+		return this._internal.SetProperty(name, value);
+	}
+	/**
+	* 设置扩展属性
+	* @param targetPath 目标路径
+	* @param attrs 扩展属性键值对记录
+	*/
+	async setXAttr(targetPath, attrs) {
+		return this._internal.SetXAttr(this._normalize(targetPath), attrs);
+	}
+	/**
+	* 获取扩展属性
+	* @param targetPath 目标路径
+	* @param keys 需要获取的属性名数组
+	*/
+	async getXAttr(targetPath, keys) {
+		return this._internal.GetXAttr(this._normalize(targetPath), keys);
+	}
+	/**
+	* 删除指定的扩展属性
+	* @param targetPath 目标路径
+	* @param keys 需要删除的属性名数组
+	*/
+	async delXAttr(targetPath, keys) {
+		return this._internal.DelXAttr(this._normalize(targetPath), keys);
+	}
+	/**
+	* 列出目标文件或目录的所有扩展属性
+	*/
+	async listXAttr(targetPath) {
+		return this._internal.ListXAttr(this._normalize(targetPath));
+	}
+};
+//#endregion
+//#region lib/url.ts
+/**
+* 纯 TypeScript 实现的 XRootD URL 解析器
+* 安全、轻量，避免跨越 C++ N-API 边界
+*/
+var XRootDUrl = class XRootDUrl {
+	_url;
+	isValid;
+	constructor(urlString) {
+		this._url = new node_url.URL(urlString);
+		this.isValid = true;
+		if (![
+			"root",
+			"xrootd",
+			"xroot",
+			"file"
+		].includes(this.protocol)) {
+			console.error("Invalid XRootD URL protocol.");
+			this.isValid = false;
+		} else if (this.hostName.length === 0) this.isValid = false;
+	}
+	get protocol() {
+		return this._url.protocol.replace(/:$/, "");
+	}
+	set protocol(protocol) {
+		this._url.protocol = protocol;
+	}
+	get hostName() {
+		return this._url.hostname;
+	}
+	set hostName(hostName) {
+		this._url.hostname = hostName;
+	}
+	get port() {
+		return this._url.port ? parseInt(this._url.port, 10) : 1094;
+	}
+	set port(port) {
+		this._url.port = port.toString();
+	}
+	get userName() {
+		return this._url.username;
+	}
+	set userName(userName) {
+		this._url.username = userName;
+	}
+	get password() {
+		return this._url.password;
+	}
+	set password(password) {
+		this._url.password = password;
+	}
+	get hostId() {
+		const u = this._url.username;
+		if (u.length === 0) return this._url.host;
+		else if (this._url.password.length > 0) return `${u}:${this._url.password}@${this._url.host}`;
+		else return `${u}@${this._url.host}`;
+	}
+	set pathWithParams(path) {
+		const [p, s] = path.split("?", 2);
+		this._url.pathname = "/" + p;
+		this._url.search = s ?? "";
+	}
+	get pathWithParams() {
+		return this.path + this._url.search;
+	}
+	set searchParams(params) {
+		this._url.search = params;
+	}
+	get searchParams() {
+		return this._url.search;
+	}
+	set anchor(anchor) {
+		this._url.hash = anchor;
+	}
+	get anchor() {
+		return this._url.hash;
+	}
+	set path(path) {
+		this._url.pathname = "/" + path;
+	}
+	get path() {
+		return this._url.pathname.replace(/^\/+/, "/");
+	}
+	getParams() {
+		const params = {};
+		for (const [key, value] of this._url.searchParams.entries()) params[key] = value;
+		return params;
+	}
+	toString() {
+		return this._url.toString();
+	}
+	static isValid(urlString) {
+		try {
+			return new XRootDUrl(urlString).isValid;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+//#region lib/env.ts
+const Env = {
+	putInt: nativeAddon.Env.PutInt,
+	putString: nativeAddon.Env.PutString,
+	getInt: nativeAddon.Env.GetInt,
+	getString: nativeAddon.Env.GetString
+};
+//#endregion
+exports.AccessMode = AccessMode;
+exports.Env = Env;
+exports.File = File;
+exports.FileSystem = FileSystem;
+exports.MkDirFlags = MkDirFlags;
+exports.OpenFlags = OpenFlags;
+exports.URL = XRootDUrl;