xrootd 0.1.10 → 0.1.12

package/README.md

@@ -3,8 +3,8 @@
 > [!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
+- now complete: FileSystem/Url/Env/File
+- in progress: CopyProcess/ErrorProcess/And others
 
 ---
 

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);
 	}
 	/**
 	* 同步文件缓冲区到磁盘
@@ -656,12 +663,88 @@ 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.Env = Env;

package/dist/index.d.cts

@@ -76,6 +76,7 @@ interface INativeFile {
   Stat(): Promise<StatInfo>;
   Read(offset: bigint, size: number): Promise<Buffer>;
   Write(offset: bigint, buffer: Buffer): Promise<void>;
+  WriteFd(offset: bigint, size: number, fd: number, fdoff?: bigint): Promise<void>;
   Sync(): Promise<void>;
   Truncate(size: bigint): Promise<void>;
   IsOpen(): boolean;
@@ -196,11 +197,27 @@ declare class File$1 {
    */
   read(offset: bigint | number, size: number): Promise<Buffer>;
   /**
-   * 写入文件块
+   * 写入文件块 (Buffer 写入)
    * @param offset 偏移量
    * @param buffer 要写入的数据
    */
   write(offset: bigint | number, buffer: Buffer): Promise<void>;
+  /**
+   * 从本地 fd 写入文件块
+   * @param offset 写入的起始字节偏移量。
+   * @param size 写入大小。
+   * @param fd 本地文件描述符 (fd)。
+   * @param fdoff 可选，从本地 fd 中读取的起始偏移。
+   */
+  write(offset: bigint | number, size: number, fd: number, fdoff?: bigint | number): Promise<void>;
+  /**
+   * 从本地 fd 写入文件块 (直接映射)
+   * @param offset 写入的起始字节偏移量。
+   * @param size 写入大小。
+   * @param fd 本地文件描述符 (fd)。
+   * @param fdoff 可选，从本地 fd 中读取的起始偏移。
+   */
+  writeFd(offset: bigint | number, size: number, fd: number, fdoff?: bigint | number): Promise<void>;
   /**
    * 同步文件缓冲区到磁盘
    */
@@ -444,11 +461,301 @@ declare class XRootDUrl {
 }
 //#endregion
 //#region lib/env.d.ts
-declare const Env: {
-  readonly putInt: (key: string, value: number) => void;
-  readonly putString: (key: string, value: string) => void;
-  readonly getInt: (key: string) => number | null;
-  readonly getString: (key: string) => string | null;
-};
+type String = string;
+type Int = number | bigint;
+type Bool = 'true' | 'false';
+/**
+ * XRootD 底层客户端环境变量配置
+ * 参考自: XrdClConstants.hh 与 XrdClDefaultEnv.cc
+ */
+interface XRootDEnvConfig {
+  /**
+   * 每个通道的子流数量，用于多路复用并行传输。默认值: 1
+   */
+  SubStreamsPerChannel?: Int;
+  /**
+   * 默认的请求超时时间 (秒)。
+   * 注意: XRootD C++ 默认是 1800（30 分钟），本 Node.js 库初始化时重置为 30。
+   */
+  RequestTimeout?: Int;
+  /**
+   * 连接重试次数。默认值: 5
+   */
+  ConnectionRetry?: Int;
+  /**
+   * 连接窗口时间 (秒)。如果在该窗口内没有成功建立连接，则报错。默认值: 120
+   */
+  ConnectionWindow?: Int;
+  /**
+   * 流超时时间 (秒)。默认值: 60
+   */
+  StreamTimeout?: Int;
+  /**
+   * 超时检测的时间精度/分辨率 (秒)。默认值: 15
+   */
+  TimeoutResolution?: Int;
+  /**
+   * 流错误统计的时间窗口长度 (秒)。默认值: 1800
+   */
+  StreamErrorWindow?: Int;
+  /**
+   * 是否启用多进程 fork 处理器，用于管理多线程 fork 同步。默认值: 1
+   */
+  RunForkHandler?: Int;
+  /**
+   * 重定向的最大限制次数。默认值: 16
+   */
+  RedirectLimit?: Int;
+  /**
+   * 内部工作线程数。默认值: 3。注意：本 Node.js 库初始化时重置为 4。
+   */
+  WorkerThreads?: Int;
+  /**
+   * 并发运行的事件循环数量。默认值: 10
+   */
+  ParallelEvtLoop?: Int;
+  /**
+   * 是否启用 TCP_NODELAY (禁用 Nagle 算法)。默认值: Linux 下为 1，OSX 下为 0
+   */
+  NoDelay?: Int;
+  /**
+   * 异步 I/O 通知使用的信号（0 表示不使用）。默认值: 0
+   */
+  AioSignal?: Int;
+  /**
+   * Copy 复制过程所使用的基本分块大小 (字节)。默认值: 8388608 (8MB)
+   */
+  CPChunkSize?: Int;
+  /**
+   * Copy 过程中同时并发传输的分块数量。默认值: 4
+   */
+  CPParallelChunks?: Int;
+  /**
+   * Copy 任务的初始化阶段超时时间 (秒)。默认值: 600
+   */
+  CPInitTimeout?: Int;
+  /**
+   * 第三方复制 (Third Party Copy, TPC) 过程超时时间 (秒)。默认值: 1800
+   */
+  CPTPCTimeout?: Int;
+  /**
+   * 整个 Copy 复制任务的总体超时时间 (秒，0 表示不限制)。默认值: 0
+   */
+  CPTimeout?: Int;
+  /**
+   * 扩展 Copy 的单次写入最大块大小 (字节)。默认值: 134217728 (128MB)
+   */
+  XCpBlockSize?: Int;
+  /**
+   * 写入被引导至负载均衡器时的重试次数上限。默认值: 3
+   */
+  RetryWrtAtLBLimit?: Int;
+  /**
+   * Copy 任务的重试次数。默认值: 0
+   */
+  CpRetry?: Int;
+  /**
+   * 在 Copy 复制传输时，是否启用渐进式读写。默认值: 1
+   */
+  CpUsePgWrtRd?: Int;
+  /**
+   * 复制文件时是否保留扩展属性 (XAttrs)。默认值: 0
+   */
+  PreserveXAttrs?: Int;
+  /**
+   * Copy 任务失败后的重试策略。默认值: "force"
+   */
+  CpRetryPolicy?: 'force' | 'continue';
+  /**
+   * Copy 操作的目标类型。默认值: ""
+   */
+  CpTarget?: String;
+  /**
+   * 是否启用 TCP Keep-Alive。默认值: 0
+   */
+  TCPKeepAlive?: Int;
+  /**
+   * TCP 空闲多长时间后发送首次 Keep-Alive 探测包 (秒)。默认值: 7200
+   */
+  TCPKeepAliveTime?: Int;
+  /**
+   * 两次 TCP Keep-Alive 探测包 of 发送间隔时间 (秒)。默认值: 75
+   */
+  TCPKeepAliveInterval?: Int;
+  /**
+   * 连接断开前，最大允许的 TCP Keep-Alive 探测未响应次数。默认值: 9
+   */
+  TCPKeepAliveProbes?: Int;
+  /**
+   * 数据服务器连接的生存时间 (TTL，秒)。默认值: 300
+   */
+  DataServerTTL?: Int;
+  /**
+   * 负载均衡器连接的生存时间 (TTL，秒)。默认值: 1200
+   */
+  LoadBalancerTTL?: Int;
+  /**
+   * 解析 IP 后是否禁止打乱顺序 (打乱顺序有利于负载均衡)。默认值: 0
+   */
+  IPNoShuffle?: Int;
+  /**
+   * 定位端点时是否记录并排除已尝试失败的地址。默认值: 1
+   */
+  PreserveLocateTried?: Int;
+  /**
+   * DNS 解析时是否优先选择 IPv4 而非 IPv6。默认值: 0
+   */
+  PreferIPv4?: Int;
+  /**
+   * 首选的 Poller 轮询器实现。默认值: "built-in"
+   */
+  PollerPreference?: 'built-in' | (string & {});
+  /**
+   * 使用的网络协议栈 (如 "IPAuto", "IPv4", "IPv6")。默认值: "IPAuto"
+   */
+  NetworkStack?: 'IPAuto' | 'IPv4' | 'IPv6' | 'IPv4Mapped6' | 'IPAll';
+  /**
+   * 读数据失败时的恢复策略。默认值: "true"
+   */
+  ReadRecovery?: Bool;
+  /**
+   * 写数据失败时的恢复策略。默认值: "true"
+   */
+  WriteRecovery?: Bool;
+  /**
+   * 打开文件失败时的恢复策略。默认值: "true"
+   */
+  OpenRecovery?: Bool;
+  /**
+   * 是否启用 Metalink 解析和处理。默认值: 1
+   */
+  MetalinkProcessing?: Int;
+  /**
+   * 是否允许解析本地存储 of Metalink 文件。默认值: 0
+   */
+  LocalMetalinkFile?: Int;
+  /**
+   * 等待 Metalink 下载的最大时间 (秒)。默认值: 60
+   */
+  MaxMetalinkWait?: Int;
+  /**
+   * 是否对 Zip 文件的 Metalink 执行校验和检查。默认值: 0
+   */
+  ZipMtlnCksum?: Int;
+  /**
+   * 强制使用的安全协议，例如 "unix" 或 "krb5,unix"（底层通过系统环境变量设置）。
+   */
+  SecProtocol?: 'unix' | 'sss' | 'krb5' | 'pwd' | 'gsi' | 'host' | 'ztn' | (string & {});
+  /**
+   * 未授权 (Permission Denied) 时，触发自动刷新证书并重试的次数上限。默认值: 3
+   */
+  NotAuthorizedRetryLimit?: Int;
+  /**
+   * 如果 TLS 握手失败，是否允许降级为非 TLS 明文传输。默认值: 0
+   */
+  NoTlsOK?: Int;
+  /**
+   * 是否只对控制通道加密（控制通道加密，数据通道明文）。默认值: 0
+   */
+  TlsNoData?: Int;
+  /**
+   * 获取 Metalink 配置文件时是否启用 TLS。默认值: 0
+   */
+  TlsMetalink?: Int;
+  /**
+   * 是否在访问非渐进式文件时要求 TLS。默认值: 0
+   */
+  WantTlsOnNoPgrw?: Int;
+  /**
+   * TLS 调试级别（如 "OFF", "INFO", "DEBUG"）。默认值: "OFF"
+   */
+  TlsDbgLvl?: 'OFF' | 'CTX' | 'SOK' | 'SIO' | 'ALL' | 'OUT' | 'INFO' | 'DEBUG' | (string & {});
+  /**
+   * 是否启用多协议通道支持。默认值: 0
+   */
+  MultiProtocol?: Int;
+  /**
+   * 日志文件路径。底层拦截设置，直接对 C++ logger 生效。默认值: ""
+   */
+  LogFile?: String;
+  /**
+   * 调试日志级别（如 "Dump", "Debug", "Info", "Warning", "Error", ""）。底层拦截设置。
+   */
+  DebugLevel?: 'Dump' | 'Debug' | 'Info' | 'Warning' | 'Error' | '';
+  /**
+   * 日志掩码，指定哪些子系统输出日志。底层拦截设置。
+   */
+  LogMask?: String;
+  /**
+   * 客户端配置文件加载目录。默认值: ""
+   */
+  ClConfDir?: String;
+  /**
+   * 默认客户端配置文件的绝对路径。默认值: ""
+   */
+  DefaultClConfFile?: String;
+  /**
+   * 安全或传输插件配置文件的加载目录。默认值: ""
+   */
+  PlugInConfDir?: String;
+  /**
+   * 指定动态加载的插件名称。默认值: ""
+   */
+  PlugIn?: String;
+  /**
+   * 外部客户端监控插件动态链接库的加载路径。默认值: ""
+   */
+  ClientMonitor?: String;
+  /**
+   * 传递给外部客户端监控插件的参数字符串。默认值: ""
+   */
+  ClientMonitorParam?: String;
+  /**
+   * 应用的标识名称。默认值: 当前可执行文件名
+   */
+  AppName?: String;
+  /**
+   * 监控上报信息内容。默认值: ""
+   */
+  MonInfo?: String;
+}
+type KeysOfValue<T, TValue> = { [K in keyof T]: T[K] extends TValue ? K : never }[keyof T];
+type XRootDEnvConfigIntKey = KeysOfValue<Required<XRootDEnvConfig>, Int>;
+type XRootDEnvConfigBoolKey = KeysOfValue<Required<XRootDEnvConfig>, Bool>;
+type XRootDEnvConfigStringKey = KeysOfValue<Required<XRootDEnvConfig>, String>;
+declare class XRootDEnvironment {
+  constructor();
+  /**
+   * 设置整数配置项，返回是否设置成功。
+   */
+  putInt(key: XRootDEnvConfigIntKey, intVal: number | bigint): boolean;
+  /**
+   * 设置字符串配置项，返回是否设置成功。
+   */
+  putString(key: XRootDEnvConfigStringKey | XRootDEnvConfigBoolKey, strVal: string): boolean;
+  /**
+   * 设置布尔配置项，返回是否设置成功。
+   */
+  putBoolean(key: XRootDEnvConfigBoolKey, boolVal: boolean | Bool): boolean;
+  /**
+   * 获取整数配置项。
+   */
+  getInt(key: XRootDEnvConfigIntKey): number | undefined;
+  /**
+   * 获取字符串配置项。
+   */
+  getString(key: XRootDEnvConfigStringKey): string | undefined;
+  /**
+   * 批量安全地设置 XRootD 底层参数
+   */
+  configure(config: XRootDEnvConfig): void;
+  /**
+   * 获取指定配置
+   */
+  get(key: XRootDEnvConfigBoolKey): string | undefined;
+  get(key: XRootDEnvConfigStringKey): string | undefined;
+  get(key: XRootDEnvConfigIntKey): number | undefined;
+}
+declare const Env: XRootDEnvironment;
 //#endregion
 export { AccessMode, Env, File$1 as File, FileSystem, type LocationInfo, MkDirFlags, OpenFlags, type PropertyList, type ReadChunkRequest, type ReadStreamOptions, type StatInfo, type StatVFSInfo, XRootDUrl as URL, type WriteStreamOptions, type XRootDError };

package/dist/index.d.mts

@@ -76,6 +76,7 @@ interface INativeFile {
   Stat(): Promise<StatInfo>;
   Read(offset: bigint, size: number): Promise<Buffer>;
   Write(offset: bigint, buffer: Buffer): Promise<void>;
+  WriteFd(offset: bigint, size: number, fd: number, fdoff?: bigint): Promise<void>;
   Sync(): Promise<void>;
   Truncate(size: bigint): Promise<void>;
   IsOpen(): boolean;
@@ -196,11 +197,27 @@ declare class File$1 {
    */
   read(offset: bigint | number, size: number): Promise<Buffer>;
   /**
-   * 写入文件块
+   * 写入文件块 (Buffer 写入)
    * @param offset 偏移量
    * @param buffer 要写入的数据
    */
   write(offset: bigint | number, buffer: Buffer): Promise<void>;
+  /**
+   * 从本地 fd 写入文件块
+   * @param offset 写入的起始字节偏移量。
+   * @param size 写入大小。
+   * @param fd 本地文件描述符 (fd)。
+   * @param fdoff 可选，从本地 fd 中读取的起始偏移。
+   */
+  write(offset: bigint | number, size: number, fd: number, fdoff?: bigint | number): Promise<void>;
+  /**
+   * 从本地 fd 写入文件块 (直接映射)
+   * @param offset 写入的起始字节偏移量。
+   * @param size 写入大小。
+   * @param fd 本地文件描述符 (fd)。
+   * @param fdoff 可选，从本地 fd 中读取的起始偏移。
+   */
+  writeFd(offset: bigint | number, size: number, fd: number, fdoff?: bigint | number): Promise<void>;
   /**
    * 同步文件缓冲区到磁盘
    */
@@ -444,11 +461,301 @@ declare class XRootDUrl {
 }
 //#endregion
 //#region lib/env.d.ts
-declare const Env: {
-  readonly putInt: (key: string, value: number) => void;
-  readonly putString: (key: string, value: string) => void;
-  readonly getInt: (key: string) => number | null;
-  readonly getString: (key: string) => string | null;
-};
+type String = string;
+type Int = number | bigint;
+type Bool = 'true' | 'false';
+/**
+ * XRootD 底层客户端环境变量配置
+ * 参考自: XrdClConstants.hh 与 XrdClDefaultEnv.cc
+ */
+interface XRootDEnvConfig {
+  /**
+   * 每个通道的子流数量，用于多路复用并行传输。默认值: 1
+   */
+  SubStreamsPerChannel?: Int;
+  /**
+   * 默认的请求超时时间 (秒)。
+   * 注意: XRootD C++ 默认是 1800（30 分钟），本 Node.js 库初始化时重置为 30。
+   */
+  RequestTimeout?: Int;
+  /**
+   * 连接重试次数。默认值: 5
+   */
+  ConnectionRetry?: Int;
+  /**
+   * 连接窗口时间 (秒)。如果在该窗口内没有成功建立连接，则报错。默认值: 120
+   */
+  ConnectionWindow?: Int;
+  /**
+   * 流超时时间 (秒)。默认值: 60
+   */
+  StreamTimeout?: Int;
+  /**
+   * 超时检测的时间精度/分辨率 (秒)。默认值: 15
+   */
+  TimeoutResolution?: Int;
+  /**
+   * 流错误统计的时间窗口长度 (秒)。默认值: 1800
+   */
+  StreamErrorWindow?: Int;
+  /**
+   * 是否启用多进程 fork 处理器，用于管理多线程 fork 同步。默认值: 1
+   */
+  RunForkHandler?: Int;
+  /**
+   * 重定向的最大限制次数。默认值: 16
+   */
+  RedirectLimit?: Int;
+  /**
+   * 内部工作线程数。默认值: 3。注意：本 Node.js 库初始化时重置为 4。
+   */
+  WorkerThreads?: Int;
+  /**
+   * 并发运行的事件循环数量。默认值: 10
+   */
+  ParallelEvtLoop?: Int;
+  /**
+   * 是否启用 TCP_NODELAY (禁用 Nagle 算法)。默认值: Linux 下为 1，OSX 下为 0
+   */
+  NoDelay?: Int;
+  /**
+   * 异步 I/O 通知使用的信号（0 表示不使用）。默认值: 0
+   */
+  AioSignal?: Int;
+  /**
+   * Copy 复制过程所使用的基本分块大小 (字节)。默认值: 8388608 (8MB)
+   */
+  CPChunkSize?: Int;
+  /**
+   * Copy 过程中同时并发传输的分块数量。默认值: 4
+   */
+  CPParallelChunks?: Int;
+  /**
+   * Copy 任务的初始化阶段超时时间 (秒)。默认值: 600
+   */
+  CPInitTimeout?: Int;
+  /**
+   * 第三方复制 (Third Party Copy, TPC) 过程超时时间 (秒)。默认值: 1800
+   */
+  CPTPCTimeout?: Int;
+  /**
+   * 整个 Copy 复制任务的总体超时时间 (秒，0 表示不限制)。默认值: 0
+   */
+  CPTimeout?: Int;
+  /**
+   * 扩展 Copy 的单次写入最大块大小 (字节)。默认值: 134217728 (128MB)
+   */
+  XCpBlockSize?: Int;
+  /**
+   * 写入被引导至负载均衡器时的重试次数上限。默认值: 3
+   */
+  RetryWrtAtLBLimit?: Int;
+  /**
+   * Copy 任务的重试次数。默认值: 0
+   */
+  CpRetry?: Int;
+  /**
+   * 在 Copy 复制传输时，是否启用渐进式读写。默认值: 1
+   */
+  CpUsePgWrtRd?: Int;
+  /**
+   * 复制文件时是否保留扩展属性 (XAttrs)。默认值: 0
+   */
+  PreserveXAttrs?: Int;
+  /**
+   * Copy 任务失败后的重试策略。默认值: "force"
+   */
+  CpRetryPolicy?: 'force' | 'continue';
+  /**
+   * Copy 操作的目标类型。默认值: ""
+   */
+  CpTarget?: String;
+  /**
+   * 是否启用 TCP Keep-Alive。默认值: 0
+   */
+  TCPKeepAlive?: Int;
+  /**
+   * TCP 空闲多长时间后发送首次 Keep-Alive 探测包 (秒)。默认值: 7200
+   */
+  TCPKeepAliveTime?: Int;
+  /**
+   * 两次 TCP Keep-Alive 探测包 of 发送间隔时间 (秒)。默认值: 75
+   */
+  TCPKeepAliveInterval?: Int;
+  /**
+   * 连接断开前，最大允许的 TCP Keep-Alive 探测未响应次数。默认值: 9
+   */
+  TCPKeepAliveProbes?: Int;
+  /**
+   * 数据服务器连接的生存时间 (TTL，秒)。默认值: 300
+   */
+  DataServerTTL?: Int;
+  /**
+   * 负载均衡器连接的生存时间 (TTL，秒)。默认值: 1200
+   */
+  LoadBalancerTTL?: Int;
+  /**
+   * 解析 IP 后是否禁止打乱顺序 (打乱顺序有利于负载均衡)。默认值: 0
+   */
+  IPNoShuffle?: Int;
+  /**
+   * 定位端点时是否记录并排除已尝试失败的地址。默认值: 1
+   */
+  PreserveLocateTried?: Int;
+  /**
+   * DNS 解析时是否优先选择 IPv4 而非 IPv6。默认值: 0
+   */
+  PreferIPv4?: Int;
+  /**
+   * 首选的 Poller 轮询器实现。默认值: "built-in"
+   */
+  PollerPreference?: 'built-in' | (string & {});
+  /**
+   * 使用的网络协议栈 (如 "IPAuto", "IPv4", "IPv6")。默认值: "IPAuto"
+   */
+  NetworkStack?: 'IPAuto' | 'IPv4' | 'IPv6' | 'IPv4Mapped6' | 'IPAll';
+  /**
+   * 读数据失败时的恢复策略。默认值: "true"
+   */
+  ReadRecovery?: Bool;
+  /**
+   * 写数据失败时的恢复策略。默认值: "true"
+   */
+  WriteRecovery?: Bool;
+  /**
+   * 打开文件失败时的恢复策略。默认值: "true"
+   */
+  OpenRecovery?: Bool;
+  /**
+   * 是否启用 Metalink 解析和处理。默认值: 1
+   */
+  MetalinkProcessing?: Int;
+  /**
+   * 是否允许解析本地存储 of Metalink 文件。默认值: 0
+   */
+  LocalMetalinkFile?: Int;
+  /**
+   * 等待 Metalink 下载的最大时间 (秒)。默认值: 60
+   */
+  MaxMetalinkWait?: Int;
+  /**
+   * 是否对 Zip 文件的 Metalink 执行校验和检查。默认值: 0
+   */
+  ZipMtlnCksum?: Int;
+  /**
+   * 强制使用的安全协议，例如 "unix" 或 "krb5,unix"（底层通过系统环境变量设置）。
+   */
+  SecProtocol?: 'unix' | 'sss' | 'krb5' | 'pwd' | 'gsi' | 'host' | 'ztn' | (string & {});
+  /**
+   * 未授权 (Permission Denied) 时，触发自动刷新证书并重试的次数上限。默认值: 3
+   */
+  NotAuthorizedRetryLimit?: Int;
+  /**
+   * 如果 TLS 握手失败，是否允许降级为非 TLS 明文传输。默认值: 0
+   */
+  NoTlsOK?: Int;
+  /**
+   * 是否只对控制通道加密（控制通道加密，数据通道明文）。默认值: 0
+   */
+  TlsNoData?: Int;
+  /**
+   * 获取 Metalink 配置文件时是否启用 TLS。默认值: 0
+   */
+  TlsMetalink?: Int;
+  /**
+   * 是否在访问非渐进式文件时要求 TLS。默认值: 0
+   */
+  WantTlsOnNoPgrw?: Int;
+  /**
+   * TLS 调试级别（如 "OFF", "INFO", "DEBUG"）。默认值: "OFF"
+   */
+  TlsDbgLvl?: 'OFF' | 'CTX' | 'SOK' | 'SIO' | 'ALL' | 'OUT' | 'INFO' | 'DEBUG' | (string & {});
+  /**
+   * 是否启用多协议通道支持。默认值: 0
+   */
+  MultiProtocol?: Int;
+  /**
+   * 日志文件路径。底层拦截设置，直接对 C++ logger 生效。默认值: ""
+   */
+  LogFile?: String;
+  /**
+   * 调试日志级别（如 "Dump", "Debug", "Info", "Warning", "Error", ""）。底层拦截设置。
+   */
+  DebugLevel?: 'Dump' | 'Debug' | 'Info' | 'Warning' | 'Error' | '';
+  /**
+   * 日志掩码，指定哪些子系统输出日志。底层拦截设置。
+   */
+  LogMask?: String;
+  /**
+   * 客户端配置文件加载目录。默认值: ""
+   */
+  ClConfDir?: String;
+  /**
+   * 默认客户端配置文件的绝对路径。默认值: ""
+   */
+  DefaultClConfFile?: String;
+  /**
+   * 安全或传输插件配置文件的加载目录。默认值: ""
+   */
+  PlugInConfDir?: String;
+  /**
+   * 指定动态加载的插件名称。默认值: ""
+   */
+  PlugIn?: String;
+  /**
+   * 外部客户端监控插件动态链接库的加载路径。默认值: ""
+   */
+  ClientMonitor?: String;
+  /**
+   * 传递给外部客户端监控插件的参数字符串。默认值: ""
+   */
+  ClientMonitorParam?: String;
+  /**
+   * 应用的标识名称。默认值: 当前可执行文件名
+   */
+  AppName?: String;
+  /**
+   * 监控上报信息内容。默认值: ""
+   */
+  MonInfo?: String;
+}
+type KeysOfValue<T, TValue> = { [K in keyof T]: T[K] extends TValue ? K : never }[keyof T];
+type XRootDEnvConfigIntKey = KeysOfValue<Required<XRootDEnvConfig>, Int>;
+type XRootDEnvConfigBoolKey = KeysOfValue<Required<XRootDEnvConfig>, Bool>;
+type XRootDEnvConfigStringKey = KeysOfValue<Required<XRootDEnvConfig>, String>;
+declare class XRootDEnvironment {
+  constructor();
+  /**
+   * 设置整数配置项，返回是否设置成功。
+   */
+  putInt(key: XRootDEnvConfigIntKey, intVal: number | bigint): boolean;
+  /**
+   * 设置字符串配置项，返回是否设置成功。
+   */
+  putString(key: XRootDEnvConfigStringKey | XRootDEnvConfigBoolKey, strVal: string): boolean;
+  /**
+   * 设置布尔配置项，返回是否设置成功。
+   */
+  putBoolean(key: XRootDEnvConfigBoolKey, boolVal: boolean | Bool): boolean;
+  /**
+   * 获取整数配置项。
+   */
+  getInt(key: XRootDEnvConfigIntKey): number | undefined;
+  /**
+   * 获取字符串配置项。
+   */
+  getString(key: XRootDEnvConfigStringKey): string | undefined;
+  /**
+   * 批量安全地设置 XRootD 底层参数
+   */
+  configure(config: XRootDEnvConfig): void;
+  /**
+   * 获取指定配置
+   */
+  get(key: XRootDEnvConfigBoolKey): string | undefined;
+  get(key: XRootDEnvConfigStringKey): string | undefined;
+  get(key: XRootDEnvConfigIntKey): number | undefined;
+}
+declare const Env: XRootDEnvironment;
 //#endregion
 export { AccessMode, Env, File$1 as File, FileSystem, type LocationInfo, MkDirFlags, OpenFlags, type PropertyList, type ReadChunkRequest, type ReadStreamOptions, type StatInfo, type StatVFSInfo, XRootDUrl as URL, type WriteStreamOptions, type XRootDError };

package/dist/index.mjs

@@ -119,13 +119,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);
 	}
 	/**
 	* 同步文件缓冲区到磁盘
@@ -631,11 +638,87 @@ 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
 export { AccessMode, Env, File, FileSystem, MkDirFlags, OpenFlags, XRootDUrl as URL };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xrootd",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Prebuilt Node.js Native Addon for XRootD, allowing JS access to EOS file systems",
   "type": "module",
   "exports": {
@@ -70,7 +70,6 @@
   ],
   "gypfile": false,
   "scripts": {
-    "install": "echo 'Skip implicit node-gyp rebuild. Handled by explicit build.'",
     "build:tsc": "tsc --noEmit",
     "build:ts": "tsdown",
     "build:addon": "node-gyp rebuild",