xrootd 0.1.6

package/dist/index.d.cts

@@ -0,0 +1,454 @@
+import { Readable, Writable } from "node:stream";
+
+//#region lib/types.d.ts
+type PropertyList = Record<string, string | number | boolean>;
+interface IXRootDError extends Error {
+  xrdStatus: number;
+  xrdCode: number;
+  xrdErrNo: number;
+  xrdErrMsg: string;
+}
+interface StatInfo {
+  id: string;
+  size: bigint;
+  flags: number;
+  modTime: number;
+  accessTime: number;
+  changeTime: number;
+  modTimeAsString: string;
+  accessTimeAsString: string;
+  changeTimeAsString: string;
+  modeAsString: string;
+  modeAsOctString: string;
+  owner: string;
+  group: string;
+  checksum: string;
+  get modeOctal(): string;
+  get modeString(): string;
+  get isFile(): boolean;
+  get isDir(): boolean;
+  get isOther(): boolean;
+  get isOffline(): boolean;
+  get isPOSCPending(): boolean;
+  get isReadable(): boolean;
+  get isWritable(): boolean;
+  get isBackUpExists(): boolean;
+}
+interface LocationInfo {
+  address: string;
+  type: number;
+  accessType: number;
+}
+interface ReadChunkRequest {
+  offset: bigint | number;
+  size: number;
+}
+interface StatVFSInfo {
+  nodesRW: bigint;
+  freeRW: bigint;
+  utilizationRW: number;
+  nodesStaging: bigint;
+  freeStaging: bigint;
+  utilizationStaging: number;
+}
+interface DirListEntry {
+  name: string;
+  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);
+}
+/**
+ * 对应 src/core/XrdNodeFile.cc 中 Init 暴露的类
+ */
+interface INativeFile {
+  Open(url: string, flags: number, mode: number): Promise<void>;
+  Close(): Promise<void>;
+  Stat(): Promise<StatInfo>;
+  Read(offset: bigint, size: number): Promise<Buffer>;
+  Write(offset: bigint, buffer: Buffer): Promise<void>;
+  Sync(): Promise<void>;
+  Truncate(size: bigint): Promise<void>;
+  IsOpen(): boolean;
+  GetProperty(name: string): {
+    success: boolean;
+    value: string;
+  };
+  SetProperty(name: string, value: string): boolean;
+  VectorRead(chunks: ReadChunkRequest[]): Promise<Buffer[]>;
+  ReadChunks(chunks: ReadChunkRequest[]): Promise<Buffer[]>;
+  SetXAttr(attrs: Record<string, string>): Promise<XAttrStatusResult[]>;
+  GetXAttr(keys: string[]): Promise<Record<string, string>>;
+  DelXAttr(keys: string[]): Promise<XAttrStatusResult[]>;
+  ListXAttr(): Promise<Record<string, string>>;
+  Clone(list: CloneLocationRequest[]): Promise<void>;
+}
+interface ReadStreamOptions {
+  start?: bigint;
+  end?: bigint;
+  /**
+   * 每次从底层读取的块大小 (默认 64KB)
+   */
+  highWaterMark?: number;
+}
+interface WriteStreamOptions {
+  start?: bigint;
+}
+interface CloneLocationRequest {
+  srcFile: File;
+  dstOffset: bigint | number;
+  srcOffset: bigint | number;
+  length: bigint | number;
+}
+//#endregion
+//#region lib/enums.d.ts
+/**
+ * XrdCl::OpenFlags - 文件打开选项
+ * @see src/XProtocol/XProtocol.hh:XOpenRequestOption
+ * @see src/XrdCl/XrdClFileSystem.hh:OpenFlags::Flags
+ */
+declare const OpenFlags: {
+  readonly None: 0;
+  readonly Compress: 1;
+  readonly Delete: 2;
+  readonly Force: 4;
+  readonly New: 8;
+  readonly Read: 16;
+  readonly Update: 32;
+  readonly Refresh: 128;
+  readonly MakePath: 256;
+  readonly IntentDirList: 1024;
+  readonly Replica: 2048;
+  readonly POSC: 4096;
+  readonly NoWait: 8192;
+  readonly SeqIO: 16384;
+  readonly Write: 32768;
+  readonly PrefName: 256;
+  readonly Dup: 65536;
+  readonly Samefs: 131072;
+};
+type OpenFlags = typeof OpenFlags[keyof typeof OpenFlags];
+/**
+ * XrdCl::Access - 文件访问权限模式
+ * @see src/XProtocol/XProtocol.hh:XOpenRequestMode
+ * @see src/XrdCl/XrdClFileSystem.hh:Access::Mode
+ */
+declare const AccessMode: {
+  readonly None: 0;
+  readonly UR: 256;
+  readonly UW: 128;
+  readonly UX: 64;
+  readonly GR: 32;
+  readonly GW: 16;
+  readonly GX: 8;
+  readonly OR: 4;
+  readonly OW: 2;
+  readonly OX: 1;
+};
+type AccessMode = number;
+/**
+ * XrdCl::MkDirFlags - 目录创建选项
+ * @see src/XrdCl/XrdClFileSystem.hh:MkDirFlags::Flags
+ */
+declare const MkDirFlags: {
+  readonly None: 0;
+  readonly MakePath: 1;
+};
+type MkDirFlags = typeof MkDirFlags[keyof typeof MkDirFlags];
+//#endregion
+//#region lib/file.d.ts
+/**
+ * XRootD File 客户端
+ * 提供对远程文件的异步读写操作及 Node.js 风格的流式接口。
+ */
+declare class File$1 {
+  private _internal;
+  constructor(internalInstance?: INativeFile);
+  /**
+   * 打开远程文件
+   * @param url 目标地址 (如 root://server//path/to/file)
+   * @param flags 打开标志位
+   * @param mode 访问权限模式
+   */
+  open(url: string, flags?: OpenFlags, mode?: AccessMode): Promise<void>;
+  /**
+   * 关闭文件
+   */
+  close(): Promise<void>;
+  /**
+   * 获取文件状态
+   */
+  stat(): Promise<StatInfo>;
+  /**
+   * 读取文件块 (Zero-Copy from C++)
+   * @param offset 偏移量 (支持 >2GB)
+   * @param size 读取字节数
+   * @returns 包含数据的 Node.js Buffer
+   */
+  read(offset: bigint | number, size: number): Promise<Buffer>;
+  /**
+   * 写入文件块
+   * @param offset 偏移量
+   * @param buffer 要写入的数据
+   */
+  write(offset: bigint | number, buffer: Buffer): Promise<void>;
+  /**
+   * 同步文件缓冲区到磁盘
+   */
+  sync(): Promise<void>;
+  /**
+   * 截断文件
+   * @param size 目标大小
+   */
+  truncate(size: bigint | number): Promise<void>;
+  /**
+   * 检查本地实例状态 (同步操作)
+   */
+  isOpen(): boolean;
+  getProperty(name: string): Promise<string>;
+  setProperty(name: string, value: string): Promise<void>;
+  /**
+   * 向量化读取 (Vector Read)
+   * 在单个请求中从文件的多个非连续区域读取数据，极大地减少网络往返开销。
+   * @param chunks 包含 offset 和 size 的读取请求数组
+   * @returns 与请求数组顺序对应的 Buffer 数组
+   */
+  vectorRead(chunks: ReadChunkRequest[]): Promise<Buffer[]>;
+  /**
+   * 读取块 (Read Chunks)
+   * 类似于 VectorRead，但底层实现可能利用更高级的预读或多路复用策略。
+   */
+  readChunks(chunks: ReadChunkRequest[]): Promise<Buffer[]>;
+  /**
+   * 设置文件的扩展属性
+   */
+  setXAttr(name: string, value: string): Promise<void>;
+  /**
+   * 获取文件的扩展属性
+   */
+  getXAttr(name: string): Promise<string>;
+  /**
+   * 删除文件的扩展属性
+   */
+  delXAttr(name: string): Promise<void>;
+  /**
+   * 列出文件所有的扩展属性名称
+   */
+  listXAttr(): Promise<string[]>;
+  /**
+   * 将其他文件的指定区间在服务器端克隆到当前文件
+   * 当前文件必须以写入/更新模式打开
+   */
+  clone(locations: CloneLocationRequest[]): Promise<void>;
+  /**
+   * 创建一个可读流 (Readable Stream)
+   * 使得 XRootD 文件可以无缝 pipe 到其他 Node.js 流 (如本地 fs, HTTP response)
+   */
+  createReadStream(options?: ReadStreamOptions): Readable;
+  /**
+   * 创建一个可写流 (Writable Stream)
+   * 支持通过 pipe 将大量数据流式写入 XRootD 服务器
+   */
+  createWriteStream(options?: WriteStreamOptions): Writable;
+}
+//#endregion
+//#region lib/filesystem.d.ts
+/**
+ * XRootD FileSystem 客户端
+ * 提供对远程服务器目录和文件的通用管理操作。
+ */
+declare class FileSystem {
+  private _internal;
+  readonly serverUrl: string;
+  /**
+   * 实例化一个 FileSystem 客户端
+   * @param url 服务器地址 (例如: 'root://eospublic.cern.ch')
+   */
+  constructor(url: string);
+  /**
+   * 内部辅助方法：确保路径是标准的 Unix 绝对路径
+   */
+  private _normalize;
+  /**
+   * 定位文件在集群中的具体数据节点
+   * @param filePath 目标文件路径
+   * @param flags 定位标志位 (默认 0)
+   * @returns 包含主机、端口等信息的数组
+   */
+  locate(filePath: string, flags?: number): Promise<LocationInfo[]>;
+  /**
+   * 获取文件或目录的状态信息
+   * @param targetPath 目标路径
+   */
+  stat(targetPath: string): Promise<StatInfo>;
+  /**
+   * 删除远程文件
+   * @param filePath 要删除的文件路径
+   */
+  rm(filePath: string): Promise<void>;
+  /**
+   * 创建远程目录
+   * @param dirPath 目录路径
+   * @param flags 标志位 (例如 MakePath，允许创建多级父目录)
+   * @param mode 访问权限模式 (默认 0755 对应的 AccessMode)
+   */
+  mkdir(dirPath: string, flags?: MkDirFlags, mode?: AccessMode): Promise<void>;
+  /**
+   * 删除远程目录 (目录必须为空)
+   * @param dirPath 要删除的目录路径
+   */
+  rmdir(dirPath: string): Promise<void>;
+  /**
+   * 移动或重命名文件/目录
+   * @param source 源路径
+   * @param dest 目标路径
+   */
+  mv(source: string, dest: string): Promise<void>;
+  /**
+   * 列出目录下的所有文件和子目录名
+   * @param dirPath 目录路径
+   * @param flags 标志位 (例如是否显示隐藏文件)
+   */
+  dirList(dirPath: string, flags?: number): Promise<DirListEntry[]>;
+  /**
+   * 检查文件或目录是否存在
+   * (通过捕获 stat 的错误来实现，类似于老版本 Node 的 fs.exists)
+   * @param targetPath 目标路径
+   */
+  exists(targetPath: string): Promise<boolean>;
+  /**
+   * 确保目录存在。如果目录不存在，则会自动创建它及其所有父目录。
+   * (类似于 fs-extra 的 ensureDir 或 mkdir -p)
+   * @param dirPath 目标目录
+   */
+  ensureDir(dirPath: string): Promise<void>;
+  /**
+   * 深度定位：返回包含所有数据节点副本的详细物理位置信息
+   */
+  deepLocate(filePath: string, flags?: number): Promise<LocationInfo[]>;
+  /**
+   * 在不打开文件的情况下，直接截断目标文件
+   */
+  truncate(filePath: string, size: bigint | number): Promise<void>;
+  /**
+   * 更改远程文件或目录的访问权限
+   */
+  chmod(targetPath: string, mode: AccessMode): Promise<void>;
+  /**
+   * 探活：检查远端文件系统服务是否响应
+   */
+  ping(): Promise<void>;
+  /**
+   * 获取虚拟文件系统(VFS)的状态（如磁盘总容量、剩余可用空间）
+   */
+  statVFS(targetPath: string): Promise<StatVFSInfo>;
+  /**
+   * 获取当前连接协议的详细属性
+   */
+  protocol(): Promise<PropertyList>;
+  /**
+   * 发送带外查询指令到数据节点 (通常用于 XRootD 的高级自定义插件)
+   */
+  query(queryCode: number, args: Buffer): Promise<Buffer>;
+  /**
+   * 发送通用信息到服务器
+   */
+  sendInfo(info: string): Promise<Buffer>;
+  /**
+   * 发送缓存操作信息给集群
+   */
+  sendCache(info: string): Promise<Buffer>;
+  /**
+   * 数据预热/暂存 (Staging)：
+   * 在处理海量物理数据时，通知存储集群将特定的冷数据（如磁带上的文件）提前拉取到磁盘缓存。
+   * @param targetPaths 需要预热的路径数组
+   * @param flags 预热策略标志
+   * @param priority 优先级
+   */
+  prepare(targetPaths: string[], flags?: number, priority?: number): Promise<Buffer>;
+  /**
+   * 获取文件系统属性
+   */
+  getProperty(name: string): {
+    success: boolean;
+    value: string;
+  };
+  /**
+   * 设置文件系统属性
+   */
+  setProperty(name: string, value: string): boolean;
+  /**
+   * 设置扩展属性
+   * @param targetPath 目标路径
+   * @param attrs 扩展属性键值对记录
+   */
+  setXAttr(targetPath: string, attrs: Record<string, string>): Promise<XAttrStatusResult[]>;
+  /**
+   * 获取扩展属性
+   * @param targetPath 目标路径
+   * @param keys 需要获取的属性名数组
+   */
+  getXAttr(targetPath: string, keys: string[]): Promise<Record<string, string>>;
+  /**
+   * 删除指定的扩展属性
+   * @param targetPath 目标路径
+   * @param keys 需要删除的属性名数组
+   */
+  delXAttr(targetPath: string, keys: string[]): Promise<XAttrStatusResult[]>;
+  /**
+   * 列出目标文件或目录的所有扩展属性
+   */
+  listXAttr(targetPath: string): Promise<Record<string, string>>;
+}
+//#endregion
+//#region lib/url.d.ts
+/**
+ * 纯 TypeScript 实现的 XRootD URL 解析器
+ * 安全、轻量，避免跨越 C++ N-API 边界
+ */
+declare class XRootDUrl {
+  private _url;
+  readonly isValid: boolean;
+  constructor(urlString: string);
+  get protocol(): string;
+  set protocol(protocol: string);
+  get hostName(): string;
+  set hostName(hostName: string);
+  get port(): number;
+  set port(port: number | string);
+  get userName(): string;
+  set userName(userName: string);
+  get password(): string;
+  set password(password: string);
+  get hostId(): string;
+  set pathWithParams(path: string);
+  get pathWithParams(): string;
+  set searchParams(params: string);
+  get searchParams(): string;
+  set anchor(anchor: string);
+  get anchor(): string;
+  set path(path: string);
+  get path(): string;
+  getParams(): Record<string, string>;
+  toString(): string;
+  static isValid(urlString: string): boolean;
+}
+//#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;
+};
+//#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 };