xrootd 0.1.11 → 0.2.0

package/dist/index.d.mts

@@ -8,6 +8,18 @@ interface IXRootDError extends Error {
   xrdErrNo: number;
   xrdErrMsg: string;
 }
+type XRootDOkError = {
+  ok: true;
+} | ({
+  ok: false;
+} & IXRootDError);
+type XAttrStatusResult = {
+  ok: true;
+  name: string;
+} | ({
+  ok: false;
+  name: string;
+} & IXRootDError);
 interface StatInfo {
   id: string;
   size: bigint;
@@ -56,16 +68,10 @@ interface DirListEntry {
   hostAddress: string;
   stat: StatInfo | null;
 }
-interface XAttrStatusResult {
-  name: string;
-  isOk: boolean;
-  code: number;
-  message: string;
-}
 declare class XRootDError extends Error {
   code: number;
   status: number;
-  constructor(status: IXRootDError);
+  constructor(status: XRootDOkError);
 }
 /**
  * 对应 src/core/XrdNodeFile.cc 中 Init 暴露的类
@@ -76,6 +82,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;
@@ -92,6 +99,65 @@ interface INativeFile {
   ListXAttr(): Promise<Record<string, string>>;
   Clone(list: CloneLocationRequest[]): Promise<void>;
 }
+interface CopyJobConfig {
+  /** original source URL */
+  source: string;
+  /** target directory or file */
+  target: string;
+  /** maximum number sources */
+  sourceLimit?: number;
+  /** overwrite target if exists */
+  force?: boolean;
+  /** persistify only on successful close */
+  posc?: boolean;
+  /** ignore locking semantics on destination */
+  coerce?: boolean;
+  /** create path to the file if it doesn't exist */
+  makeDir?: boolean;
+  /** "first" try third party copy, if it fails try normal copy; "only" only try third party copy */
+  thirdParty?: string;
+  /** "none"    - no checksumming
+      "end2end" - end to end checksumming
+      "source"  - calculate checksum at source
+      "target"  - calculate checksum at target */
+  checkSumMode?: "none" | "end2end" | "source" | "target";
+  /** type of the checksum to be used */
+  checkSumType?: string;
+  /** checksum preset */
+  checkSumPreset?: string;
+  /** size of a copy chunks in bytes */
+  chunkSize?: number;
+  /** number of chunks that should be requested in parallel
+   *
+   * [uint8_t]
+   */
+  parallelChunks?: number;
+  /** time limit for successfull initialization of the copy job
+   * [time_t]
+   */
+  initTimeout?: number;
+  /** time limit for the actual copy to finish
+   * [time_t]
+   */
+  tpcTimeout?: number;
+  /** support for the case where the size source file may change during reading process */
+  dynamicSource?: boolean;
+}
+interface CopyJobResult {
+  /** checksum at source, if requested */
+  sourceCheckSum?: string;
+  /** checksum at target, if requested */
+  targetCheckSum?: string;
+  /** file size */
+  size: bigint;
+  /** status of the copy operation */
+  status?: XRootDOkError;
+  /** all sources used */
+  sources?: string[];
+  /** the actual disk server target */
+  realTarget?: string;
+}
+type ProgressCallback = (jobNum: number, processed: number, total: number) => void;
 interface ReadStreamOptions {
   start?: bigint;
   end?: bigint;
@@ -196,11 +262,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>;
   /**
    * 同步文件缓冲区到磁盘
    */
@@ -215,7 +297,7 @@ declare class File$1 {
    */
   isOpen(): boolean;
   getProperty(name: string): Promise<string>;
-  setProperty(name: string, value: string): Promise<void>;
+  setProperty(name: string, value: string): Promise<boolean>;
   /**
    * 向量化读取 (Vector Read)
    * 在单个请求中从文件的多个非连续区域读取数据，极大地减少网络往返开销。
@@ -231,19 +313,25 @@ declare class File$1 {
   /**
    * 设置文件的扩展属性
    */
-  setXAttr(name: string, value: string): Promise<void>;
+  setXAttrs(attrs: Record<string, string>): Promise<XAttrStatusResult[]>;
+  /**
+   * 设置文件的扩展属性
+   */
+  setXAttr(key: string, value: string): Promise<boolean>;
   /**
    * 获取文件的扩展属性
    */
-  getXAttr(name: string): Promise<string>;
+  getXAttrs(keys: string[]): Promise<Record<string, string>>;
+  getXAttr(key: string): Promise<string>;
   /**
    * 删除文件的扩展属性
    */
-  delXAttr(name: string): Promise<void>;
+  delXAttrs(keys: string[]): Promise<XAttrStatusResult[]>;
+  delXAttr(key: string): Promise<boolean>;
   /**
-   * 列出文件所有的扩展属性名称
+   * 列出文件所有的扩展属性和内容
    */
-  listXAttr(): Promise<string[]>;
+  listXAttrs(): Promise<Record<string, string>>;
   /**
    * 将其他文件的指定区间在服务器端克隆到当前文件
    * 当前文件必须以写入/更新模式打开
@@ -391,25 +479,56 @@ declare class FileSystem {
    * @param targetPath 目标路径
    * @param attrs 扩展属性键值对记录
    */
-  setXAttr(targetPath: string, attrs: Record<string, string>): Promise<XAttrStatusResult[]>;
+  setXAttrs(targetPath: string, attrs: Record<string, string>): Promise<XAttrStatusResult[]>;
+  setXAttr(targetPath: string, key: string, value: string): Promise<boolean>;
   /**
    * 获取扩展属性
    * @param targetPath 目标路径
    * @param keys 需要获取的属性名数组
    */
-  getXAttr(targetPath: string, keys: string[]): Promise<Record<string, string>>;
+  getXAttrs(targetPath: string, keys: string[]): Promise<Record<string, string>>;
+  getXAttr(targetPath: string, key: string): Promise<string>;
   /**
    * 删除指定的扩展属性
    * @param targetPath 目标路径
    * @param keys 需要删除的属性名数组
    */
-  delXAttr(targetPath: string, keys: string[]): Promise<XAttrStatusResult[]>;
+  delXAttrs(targetPath: string, keys: string[]): Promise<XAttrStatusResult[]>;
+  delXAttr(targetPath: string, key: string): Promise<boolean>;
   /**
    * 列出目标文件或目录的所有扩展属性
    */
   listXAttr(targetPath: string): Promise<Record<string, string>>;
 }
 //#endregion
+//#region lib/copy.d.ts
+declare class CopyProcess {
+  private nativeCp;
+  constructor();
+  /**
+   * Add a job to the copy process synchronously
+   */
+  addJob(config: CopyJobConfig): void;
+  /**
+   * Asynchronously prepare the jobs (resolve DNS, check endpoints, etc.)
+   */
+  prepare(): Promise<void>;
+  /**
+   * Run the copy process.
+   * @param onProgress Optional progress callback
+   * @returns Array of results corresponding to the jobs added
+   */
+  run(onProgress?: ProgressCallback): Promise<CopyJobResult[]>;
+  /**
+   * Abort the running copy process.
+   */
+  abort(): void;
+  /**
+   * Abort the running copy process. (alias for abort)
+   */
+  cancelJob(): void;
+}
+//#endregion
 //#region lib/url.d.ts
 /**
  * 纯 TypeScript 实现的 XRootD URL 解析器
@@ -444,11 +563,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 };
+export { AccessMode, CopyProcess, 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 };