xrootd 0.2.3 → 1.0.0-beta.2

package/dist/index.d.mts

@@ -1,864 +1,663 @@
-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;
-}
-type XRootDOkError = {
-  ok: true;
-} | ({
-  ok: false;
-} & IXRootDError);
-type XAttrStatusResult = {
-  ok: true;
-  name: string;
-} | ({
-  ok: false;
-  name: string;
-} & IXRootDError);
-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;
+//#region src/transport/interface.d.ts
+interface ITransport {
+  connect(host: string, port: number, useTls?: boolean): Promise<void>;
+  send(data: Buffer): Promise<void>;
+  onData(callback: (chunk: Buffer) => void): void;
+  removeDataHandler(callback: (chunk: Buffer) => void): void;
+  onClose(callback: () => void): void;
+  onError(callback: (err: Error) => void): void;
+  close(): Promise<void>;
+  destroy(): void;
 }
-declare class XRootDError extends Error {
-  code: number;
+//#endregion
+//#region src/transport/framer.d.ts
+/** Complete XRootD response frame */
+interface Frame {
+  streamId: Buffer;
   status: number;
-  constructor(status: XRootDOkError);
+  dlen: number;
+  body: Buffer;
 }
 /**
- * 对应 src/core/XrdNodeFile.cc 中 Init 暴露的类
+ * Frame parser: handles TCP fragmentation, splits byte stream into complete XRootD response frames.
+ *
+ * XRootD response format:
+ *   streamid[2] + status[2] + dlen[4] + body[dlen]
+ *   Fixed header 8 bytes + variable body
  */
-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>;
-  WriteFd(offset: bigint, size: number, fd: number, fdoff?: bigint): 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 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;
+declare class Framer {
+  private pending;
+  /** Feed raw bytes, return parsed complete frames (0 or more) */
+  feed(chunk: Buffer): Frame[];
 }
-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;
+//#endregion
+//#region src/transport/multiplexer.d.ts
+interface MultiplexerOptions {
+  maxRedirects?: number;
+  onRedirect?: (host: string, port: number) => Promise<void>;
 }
-type ProgressCallback = (jobNum: number, processed: number, total: number) => void;
-interface ReadStreamOptions {
-  start?: bigint;
-  end?: bigint;
-  /**
-   * 每次从底层读取的块大小 (默认 64KB)
-   */
-  highWaterMark?: number;
+/**
+ * Layer 3 Multiplexer
+ *
+ * Maintains streamId → Promise mapping.
+ * Generates incremental stream IDs, stores pending requests in Map,
+ * resolves when Framer delivers matching response frames.
+ */
+declare class Multiplexer {
+  private transport;
+  private framer;
+  private pending;
+  private nextStreamId;
+  private timeout;
+  private sweepTimer;
+  private closed;
+  private redirectCount;
+  private maxRedirects;
+  private onRedirect?;
+  constructor(transport: ITransport, options?: MultiplexerOptions);
+  private allocateStreamId;
+  request(requestId: number, body: Uint8Array, data?: Uint8Array): Promise<Frame>;
+  private handleFrame;
+  private handleWaitResponse;
+  private handleRedirectResponse;
+  private retryRequest;
+  private sweepTimeouts;
+  setTimeout(ms: number): void;
+  resetRedirectCount(): void;
+  getTransport(): ITransport;
+  close(): void;
+  private rejectAll;
 }
-interface WriteStreamOptions {
-  start?: bigint;
+//#endregion
+//#region src/url/url.d.ts
+declare class XRootDUrl {
+  protocol: string;
+  user?: string;
+  password?: string;
+  host: string;
+  port: number;
+  path: string;
+  constructor(url: string);
+  static parse(url: string): XRootDUrl;
+  toString(): string;
+  isValid(): boolean;
+  isSecure(): boolean;
+  getHostId(): string;
+  getChannelId(): string;
+  getLocation(): string;
+  private getAuthString;
 }
-interface CloneLocationRequest {
-  srcFile: File;
-  dstOffset: bigint | number;
-  srcOffset: bigint | number;
-  length: bigint | number;
+//#endregion
+//#region src/security/interface.d.ts
+interface SecEntity {
+  prot: string;
+  name?: string;
+  host?: string;
+  uid: number;
+  gid: number;
 }
 //#endregion
-//#region lib/enums.d.ts
+//#region src/session/handshake.d.ts
+interface Session {
+  sessid: Uint8Array;
+  protocolVersion: number;
+  secReqs?: string;
+  bifReqs?: string;
+  secEntity?: SecEntity;
+}
 /**
- * XrdCl::OpenFlags - 文件打开选项
- * @see src/XProtocol/XProtocol.hh:XOpenRequestOption
- * @see src/XrdCl/XrdClFileSystem.hh:OpenFlags::Flags
+ * Perform XRootD connection handshake:
+ * 1. Send ClientInitHandShake(20B) + kXR_protocol(24B) merged = 44 bytes
+ * 2. Receive handshake response frame (16B: ServerResponseHeader 8B with
+ *    dlen/msglen shared with ServerInitHandShake)
+ * 3. Receive kXR_ok + Protocol Response
+ * 4. Send kXR_login request
+ * 5. Receive kXR_ok + Login Response (sessid[16] + optional secToken)
+ * 6. [Optional] kXR_auth multi-round authentication
  */
+declare function handshake(mux: Multiplexer, url: XRootDUrl, options?: {
+  username?: string;
+  pid?: number;
+}): Promise<Session>;
+//#endregion
+//#region src/protocol/constants.d.ts
+declare const RequestId: {
+  readonly Auth: 3000;
+  readonly Query: 3001;
+  readonly Chmod: 3002;
+  readonly Close: 3003;
+  readonly Dirlist: 3004;
+  readonly Gpfile: 3005;
+  readonly Protocol: 3006;
+  readonly Login: 3007;
+  readonly Mkdir: 3008;
+  readonly Mv: 3009;
+  readonly Open: 3010;
+  readonly Ping: 3011;
+  readonly Chkpoint: 3012;
+  readonly Read: 3013;
+  readonly Rm: 3014;
+  readonly Rmdir: 3015;
+  readonly Sync: 3016;
+  readonly Stat: 3017;
+  readonly Set: 3018;
+  readonly Write: 3019;
+  readonly Fattr: 3020;
+  readonly Prepare: 3021;
+  readonly Statx: 3022;
+  readonly Endsess: 3023;
+  readonly Bind: 3024;
+  readonly ReadV: 3025;
+  readonly PgWrite: 3026;
+  readonly Locate: 3027;
+  readonly Truncate: 3028;
+  readonly Sigver: 3029;
+  readonly PgRead: 3030;
+  readonly WriteV: 3031;
+  readonly Clone: 3032;
+};
+type RequestId = typeof RequestId[keyof typeof RequestId];
+declare const ResponseStatus: {
+  readonly Ok: 0;
+  readonly Oksofar: 4000;
+  readonly Attn: 4001;
+  readonly Authmore: 4002;
+  readonly Error: 4003;
+  readonly Redirect: 4004;
+  readonly Wait: 4005;
+  readonly Waitresp: 4006;
+  readonly Status: 4007;
+};
+type ResponseStatus = typeof ResponseStatus[keyof typeof ResponseStatus];
+declare const ServerError: {
+  readonly ArgInvalid: 3000;
+  readonly ArgMissing: 3001;
+  readonly ArgTooLong: 3002;
+  readonly FileLocked: 3003;
+  readonly FileNotOpen: 3004;
+  readonly FSError: 3005;
+  readonly InvalidRequest: 3006;
+  readonly IOError: 3007;
+  readonly NoMemory: 3008;
+  readonly NoSpace: 3009;
+  readonly NotAuthorized: 3010;
+  readonly NotFound: 3011;
+  readonly ServerError: 3012;
+  readonly Unsupported: 3013;
+  readonly NoServer: 3014;
+  readonly NotFile: 3015;
+  readonly IsDirectory: 3016;
+  readonly Cancelled: 3017;
+  readonly ItExists: 3018;
+  readonly CheckSumErr: 3019;
+  readonly InProgress: 3020;
+  readonly OverQuota: 3021;
+  readonly SigVerErr: 3022;
+  readonly DecryptErr: 3023;
+  readonly Overloaded: 3024;
+  readonly FsReadOnly: 3025;
+  readonly BadPayload: 3026;
+  readonly AttrNotFound: 3027;
+  readonly TLSRequired: 3028;
+  readonly NoReplicas: 3029;
+  readonly AuthFailed: 3030;
+  readonly Impossible: 3031;
+  readonly Conflict: 3032;
+  readonly TooManyErrs: 3033;
+  readonly ReqTimedOut: 3034;
+  readonly TimerExpired: 3035;
+};
+type ServerError = typeof ServerError[keyof typeof ServerError];
+declare const ClientError: {
+  readonly Ok: 0;
+  readonly InvalidArgs: 300;
+  readonly NotFound: 301;
+  readonly Permission: 302;
+  readonly Serialization: 303;
+  readonly CommandNotFound: 304;
+  readonly HostNotFound: 305;
+  readonly ServiceUnavail: 306;
+  readonly InternalError: 307;
+  readonly BadRequest: 308;
+  readonly Timeout: 309;
+  readonly InsufficientData: 310;
+  readonly Uninitialized: 311;
+  readonly Disconnected: 312;
+  readonly Redirect: 313;
+  readonly LossyRetry: 314;
+  readonly TooManyRedirs: 315;
+  readonly ChunkChecksumErr: 316;
+  readonly UnexpectedResp: 317;
+  readonly ClientSkipped: 318;
+  readonly Failed: 501;
+  readonly WinNetworkError: 601;
+};
+type ClientError = typeof ClientError[keyof typeof ClientError];
 declare const OpenFlags: {
-  readonly None: 0;
-  readonly Compress: 1;
+  readonly Read: 16;
+  readonly Write: 32;
+  readonly Append: 512;
+  readonly New: 8;
   readonly Delete: 2;
   readonly Force: 4;
-  readonly New: 8;
-  readonly Read: 16;
-  readonly Update: 32;
+  readonly Compress: 1;
+  readonly Async: 64;
   readonly Refresh: 128;
-  readonly MakePath: 256;
-  readonly IntentDirList: 1024;
+  readonly Mkpath: 256;
+  readonly Retstat: 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;
+  readonly Posc: 4096;
+  readonly Nowait: 8192;
+  readonly Seqio: 16384;
+  readonly Wrto: 32768;
 };
 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;
+declare const PROTOCOL_VERSION = 1312;
+declare const REQUEST_HDR_SIZE = 24;
+declare const RESPONSE_HDR_SIZE = 8;
+declare const BODY_SIZE = 16;
+declare const SESS_ID_SIZE = 16;
+declare const FHANDLE_SIZE = 4;
+declare const REQUEST_OFFSET_STREAM_ID = 0;
+declare const REQUEST_OFFSET_REQUEST_ID = 2;
+declare const REQUEST_OFFSET_BODY = 4;
+declare const REQUEST_OFFSET_DLEN = 20;
+declare const RESPONSE_OFFSET_STREAM_ID = 0;
+declare const RESPONSE_OFFSET_STATUS = 2;
+declare const RESPONSE_OFFSET_DLEN = 4;
+declare const RESPONSE_OFFSET_BODY = 8;
+declare const HANDSHAKE_FIRST = 0;
+declare const HANDSHAKE_SECOND = 0;
+declare const HANDSHAKE_THIRD = 0;
+declare const HANDSHAKE_FOURTH = 4;
+declare const HANDSHAKE_FIFTH = 2012;
+declare const kXR_secreqs = 1;
+declare const kXR_ableTLS = 2;
+declare const kXR_wantTLS = 4;
+declare const kXR_bifreqs = 8;
+declare const kXR_ExpLogin = 1;
+declare const kXR_ExpBind = 2;
+declare const DEFAULT_PORT = 1094;
+declare const S_IFDIR = 16384;
+declare const S_IFLNK = 40960;
+declare const DirlistOptions: {
+  readonly Online: 1;
+  readonly Dstat: 2;
+  readonly Dcksm: 4;
+  readonly Dstatx: 8;
 };
-type MkDirFlags = typeof MkDirFlags[keyof typeof MkDirFlags];
+type DirlistOptions = typeof DirlistOptions[keyof typeof DirlistOptions];
+declare const CRED_TYPE: Record<string, number>;
 //#endregion
-//#region lib/file.d.ts
-type Combined = number & {};
+//#region src/api/types.d.ts
+declare const StatFlags: {
+  readonly XBitSet: 1;
+  readonly IsDir: 2;
+  readonly Other: 4;
+  readonly Offline: 8;
+  readonly Readable: 16;
+  readonly Writable: 32;
+  readonly POSCPending: 64;
+  readonly BackUpExists: 128;
+  readonly CacheResp: 512;
+};
+type StatFlags = typeof StatFlags[keyof typeof StatFlags];
+interface OpenOptions {
+  flags?: OpenFlags;
+  mode?: number;
+  signal?: AbortSignal;
+}
+interface StatInfo {
+  id: string;
+  size: bigint;
+  flags: number;
+  mtime: number;
+  ctime: number;
+  atime: number;
+  mode: number;
+  owner: string;
+  group: string;
+  get isDirectory(): boolean;
+  get isLink(): boolean;
+  get isOffline(): boolean;
+  get isCached(): boolean;
+}
 /**
- * XRootD File 客户端
- * 提供对远程文件的异步读写操作及 Node.js 风格的流式接口。
+ * Parse XRootD stat response string.
+ *
+ * Format: "<id> <size> <flags> <mtime> <ctime> <atime> <mode> <owner> <group>"
+ *   - id:     opaque 64-bit device id (string to avoid precision loss)
+ *   - size:   uint64 file size (bigint)
+ *   - flags:  XRootD flags bitmask (StatFlags)
+ *   - mtime:  modification time (epoch seconds)
+ *   - ctime:  change time (epoch seconds)
+ *   - atime:  access time (epoch seconds)
+ *   - mode:   POSIX mode (octal string, e.g. "100644")
+ *   - owner:  file owner
+ *   - group:  file group
  */
-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 | Combined, mode?: AccessMode | Combined): Promise<void>;
-  /**
-   * 关闭文件
-   */
+declare function createStatInfo(data: string): StatInfo;
+interface ChunkInfo {
+  fhandle: Uint8Array;
+  offset: number;
+  length: number;
+  data?: Uint8Array;
+}
+interface Location {
+  host: string;
+  port: number;
+}
+interface LocationInfo {
+  locations: Location[];
+  get isServer(): boolean;
+  get isManager(): boolean;
+  get isRedirect(): boolean;
+}
+interface DirectoryList {
+  name: string;
+  entries: DirectoryEntry[];
+}
+interface ProtocolInfo {
+  version: number;
+  flags: number;
+}
+interface AuthConfig {
+  username?: string;
+  password?: string;
+  protocol?: string;
+}
+interface DirectoryEntry {
+  name: string;
+  size: number;
+  flags: number;
+  mtime: number;
+}
+//#endregion
+//#region src/api/file.d.ts
+declare class File {
+  private mux;
+  private session;
+  private fhandle;
+  private _isOpen;
+  constructor(mux: Multiplexer, session: Session);
+  get isOpen(): boolean;
+  open(path: string, options?: {
+    flags?: number;
+    mode?: number;
+  }): Promise<void>;
+  read(offset: number, size: number): Promise<Uint8Array>;
+  write(offset: number, data: Uint8Array): Promise<number>;
   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>;
-  /**
-   * 写入文件块 (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>;
-  /**
-   * 同步文件缓冲区到磁盘
-   */
   sync(): Promise<void>;
-  /**
-   * 截断文件
-   * @param size 目标大小
-   */
-  truncate(size: bigint | number): Promise<void>;
-  /**
-   * 检查本地实例状态 (同步操作)
-   */
-  isOpen(): boolean;
-  getProperty(name: string): Promise<string>;
-  setProperty(name: string, value: string): Promise<boolean>;
-  /**
-   * 向量化读取 (Vector Read)
-   * 在单个请求中从文件的多个非连续区域读取数据，极大地减少网络往返开销。
-   * @param chunks 包含 offset 和 size 的读取请求数组
-   * @returns 与请求数组顺序对应的 Buffer 数组
-   */
-  vectorRead(chunks: ReadChunkRequest[]): Promise<Buffer[]>;
-  /**
-   * 读取块 (Read Chunks)
-   * 类似于 VectorRead，但底层实现可能利用更高级的预读或多路复用策略。
-   */
-  readChunks(chunks: ReadChunkRequest[]): Promise<Buffer[]>;
-  /**
-   * 设置文件的扩展属性
-   */
-  setXAttrs(attrs: Record<string, string>): Promise<XAttrStatusResult[]>;
-  /**
-   * 设置文件的扩展属性
-   */
-  setXAttr(key: string, value: string): Promise<boolean>;
-  /**
-   * 获取文件的扩展属性
-   */
-  getXAttrs(keys: string[]): Promise<Record<string, string>>;
-  getXAttr(key: string): Promise<string>;
-  /**
-   * 删除文件的扩展属性
-   */
-  delXAttrs(keys: string[]): Promise<XAttrStatusResult[]>;
-  delXAttr(key: string): Promise<boolean>;
-  /**
-   * 列出文件所有的扩展属性和内容
-   */
-  listXAttrs(): Promise<Record<string, 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;
+  truncate(size: number): Promise<void>;
 }
 //#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;
+//#region src/client.d.ts
+interface XRootDClientOptions {
+  credentials?: {
+    username: string;
+    password?: string;
   };
-  /**
-   * 设置文件系统属性
-   */
-  setProperty(name: string, value: string): boolean;
-  /**
-   * 设置扩展属性
-   * @param targetPath 目标路径
-   * @param attrs 扩展属性键值对记录
-   */
-  setXAttrs(targetPath: string, attrs: Record<string, string>): Promise<XAttrStatusResult[]>;
-  setXAttr(targetPath: string, key: string, value: string): Promise<boolean>;
-  /**
-   * 获取扩展属性
-   * @param targetPath 目标路径
-   * @param keys 需要获取的属性名数组
-   */
-  getXAttrs(targetPath: string, keys: string[]): Promise<Record<string, string>>;
-  getXAttr(targetPath: string, key: string): Promise<string>;
-  /**
-   * 删除指定的扩展属性
-   * @param targetPath 目标路径
-   * @param keys 需要删除的属性名数组
-   */
-  delXAttrs(targetPath: string, keys: string[]): Promise<XAttrStatusResult[]>;
-  delXAttr(targetPath: string, key: string): Promise<boolean>;
-  /**
-   * 列出目标文件或目录的所有扩展属性
-   */
-  listXAttr(targetPath: string): Promise<Record<string, string>>;
+  timeout?: number;
+  maxRedirects?: number;
+}
+declare class XRootDClient {
+  private readonly url;
+  private readonly options;
+  private transport;
+  private mux;
+  private session;
+  private fs;
+  constructor(url: string, options?: XRootDClientOptions);
+  connect(): Promise<void>;
+  private doConnect;
+  private handleRedirect;
+  open(path: string, options?: {
+    flags?: number;
+    mode?: number;
+  }): Promise<File>;
+  stat(path: string): Promise<StatInfo>;
+  statFilesystem(path: string): Promise<StatInfo>;
+  readdir(path: string): Promise<DirectoryList>;
+  mkdir(path: string, mode?: number): Promise<void>;
+  rmdir(path: string): Promise<void>;
+  rm(path: string): Promise<void>;
+  mv(source: string, target: string): Promise<void>;
+  close(): Promise<void>;
+  get isConnected(): boolean;
+  get location(): string;
+  private ensureConnected;
+  private ensureFileSystem;
+}
+//#endregion
+//#region src/api/filesystem.d.ts
+declare class FileSystem {
+  private mux;
+  constructor(mux: Multiplexer);
+  stat(path: string): Promise<StatInfo>;
+  readdir(path: string): Promise<DirectoryList>;
+  mkdir(path: string, mode?: number): Promise<void>;
+  rmdir(path: string): Promise<void>;
+  rm(path: string): Promise<void>;
+  mv(source: string, target: string): Promise<void>;
+  private handleError;
+}
+//#endregion
+//#region src/api/errors.d.ts
+/** Error codes that can be used with XRootDError. */
+type ErrorCode = ServerError | ClientError;
+declare class XRootDError extends Error {
+  readonly code: ErrorCode | number;
+  readonly errno?: number;
+  constructor(code: ErrorCode | number, message?: string, errno?: number);
+  static codeToMessage(code: ErrorCode | number): 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;
+//#region src/transport/transport.d.ts
+declare class Transport implements ITransport {
+  private socket;
+  private closeCallback;
+  private errorCallback;
+  private dataHandlers;
+  private dataListenerInstalled;
+  connect(host: string, port: number, useTls?: boolean): Promise<void>;
+  send(data: Buffer): Promise<void>;
+  onData(callback: (chunk: Buffer) => void): void;
+  removeDataHandler(callback: (chunk: Buffer) => void): void;
+  onClose(callback: () => void): void;
+  onError(callback: (err: Error) => void): void;
+  close(): Promise<void>;
+  destroy(): void;
+  private tcpConnect;
+  private tlsConnect;
 }
 //#endregion
-//#region lib/url.d.ts
+//#region src/protocol/message-class.d.ts
 /**
- * 纯 TypeScript 实现的 XRootD URL 解析器
- * 安全、轻量，避免跨越 C++ N-API 边界
+ * Message builder for constructing binary protocol messages.
+ * Tracks offset automatically during writes.
  */
-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;
+declare class Message {
+  private buffer;
+  private offset;
+  constructor(size: number);
+  writeInt32BE(value: number): void;
+  writeInt16BE(value: number): void;
+  writeUInt8(value: number): void;
+  writeBytes(data: Uint8Array): void;
+  readInt32BE(): number;
+  readInt16BE(): number;
+  readBytes(length: number): Buffer;
+  getBuffer(): Buffer;
 }
 //#endregion
-//#region lib/env.d.ts
-type String = string;
-type Int = number | bigint;
-type Bool = 'true' | 'false';
+//#region src/protocol/builders.d.ts
+/**
+ * Request builders for XRootD protocol messages.
+ * Each function creates a Buffer ready to send on the wire.
+ */
+/**
+ * Initial handshake (20 B) + kXR_protocol (24 B) merged into one 44-byte
+ * buffer ready to send immediately after TCP connect.
+ *
+ * Layout:
+ *   [0..19]  ClientInitHandShake
+ *   [20..43] kXR_protocol request (streamid=0, body, dlen)
+ */
+declare function buildHandshakeAndProtocol(streamId: number, flags?: number, expect?: number): Buffer;
+/**
+ * kXR_login request (24 B header only, or 24 B + CGI string).
+ *
+ * Body layout (16 B):
+ *   pid[4] + username[8] + ability2[1] + ability[1] + capver[1] + reserved[1]
+ */
+declare function buildLoginRequest(streamId: number, pid: number, username: string, ability?: number, cgi?: string): Buffer;
+/**
+ * kXR_open request (24 B header + path string).
+ *
+ * Body layout (16 B):
+ *   mode[2] + options[2] + optiont[2] + reserved[6] + fhtemplt[4]
+ */
+declare function buildOpenRequest(streamId: number, path: string, options: number, mode?: number): Buffer;
 /**
- * XRootD 底层客户端环境变量配置
- * 参考自: XrdClConstants.hh 与 XrdClDefaultEnv.cc
+ * kXR_read request (24 B header, no extra data).
+ *
+ * Body layout (16 B):
+ *   fhandle[4] + offset[8] + rlen[4]
  */
-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;
+declare function buildReadRequest(streamId: number, fhandle: Uint8Array, offset: number, rlen: number): Buffer;
+/**
+ * kXR_write request (24 B header + data bytes).
+ *
+ * Body layout (16 B):
+ *   fhandle[4] + offset[8] + pathid[1] + reserved[3]
+ */
+declare function buildWriteRequest(streamId: number, fhandle: Uint8Array, offset: number, data: Uint8Array): Buffer;
+/**
+ * kXR_close request (24 B header, no extra data).
+ *
+ * Body layout (16 B):
+ *   fhandle[4] + reserved[12]
+ */
+declare function buildCloseRequest(streamId: number, fhandle: Uint8Array): Buffer;
+/**
+ * kXR_stat request (24 B header + optional path string).
+ *
+ * Body layout (16 B):
+ *   options[1] + reserved[7] + wants[4] + fhandle[4]
+ */
+declare function buildStatRequest(streamId: number, path: string, fhandle?: Uint8Array): Buffer;
+//#endregion
+//#region src/protocol/parsers.d.ts
+/** Protocol response from kXR_protocol. */
+interface ProtocolResponse {
+  pval: number;
+  flags: number;
+  secReqs?: string;
+  bifReqs?: 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 extends XRootDEnvConfigStringKey | XRootDEnvConfigBoolKey>(key: Key, strVal: XRootDEnvConfig[Key]): 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;
+/** Login response from kXR_login. */
+interface LoginResponse {
+  sessid: Uint8Array;
+  secToken?: Uint8Array;
+  needsAuth: boolean;
 }
-declare const Env: XRootDEnvironment;
+/** Open response from kXR_open. */
+interface OpenResponse {
+  fhandle: Uint8Array;
+  cpsize: number;
+  cptype: string;
+}
+/** Error response from kXR_error. */
+interface ErrorResponse {
+  errnum: number;
+  errmsg: string;
+}
+/** Redirect response from kXR_redirect. */
+interface RedirectResponse {
+  port: number;
+  host: string;
+}
+/** Wait response from kXR_wait / kXR_waitresp. */
+interface WaitResponse {
+  seconds: number;
+  infomsg: string;
+}
+/**
+ * Parse kXR_protocol OK response body.
+ *
+ * Body layout:
+ *   pval[4] + flags[4] + secReqs (remaining bytes, NUL-terminated) +
+ *   bifReqs (remaining bytes, NUL-terminated)
+ */
+declare function parseProtocolResponse(body: Buffer): ProtocolResponse;
+/**
+ * Parse kXR_login OK response body.
+ *
+ * Body layout:
+ *   sessid[16] + optional secToken (remaining bytes)
+ */
+declare function parseLoginResponse(body: Buffer): LoginResponse;
+/**
+ * Parse kXR_open OK response body.
+ *
+ * Body layout:
+ *   fhandle[4] + cpsize[4] + cptype[4] + optional stat
+ */
+declare function parseOpenResponse(body: Buffer): OpenResponse;
+/**
+ * Parse kXR_error response body.
+ *
+ * Body layout:
+ *   errnum[4] + errmsg[variable, NUL-terminated]
+ */
+declare function parseErrorResponse(body: Buffer): ErrorResponse;
+/**
+ * Parse kXR_redirect response body.
+ *
+ * Body layout:
+ *   port[4] + host[variable, NUL-terminated]
+ */
+declare function parseRedirectResponse(body: Buffer): RedirectResponse;
+/**
+ * Parse kXR_wait / kXR_waitresp response body.
+ *
+ * Body layout:
+ *   seconds[4] + infomsg[variable, NUL-terminated]
+ */
+declare function parseWaitResponse(body: Buffer): WaitResponse;
+//#endregion
+//#region src/protocol/codec.d.ts
+/**
+ * Big-endian encoding / decoding utilities for the XRootD protocol.
+ *
+ * Every multi-byte field in XRootD is transmitted in network byte order
+ * (big-endian).  The helpers below keep offset tracking explicit so
+ * callers never forget to advance.
+ */
+/** Write `value` as uint16 BE at `offset`, return new offset. */
+declare function put16(buf: Buffer, offset: number, value: number): number;
+/** Read uint16 BE at `offset`, return `[value, newOffset]`. */
+declare function get16(buf: Buffer, offset: number): [number, number];
+/** Write `value` as uint32 BE at `offset`, return new offset. */
+declare function put32(buf: Buffer, offset: number, value: number): number;
+/** Read uint32 BE at `offset`, return `[value, newOffset]`. */
+declare function get32(buf: Buffer, offset: number): [number, number];
+/**
+ * Write `str` bytes into `buf` starting at `offset`, padded with zeros
+ * up to `maxLen`.  Returns the new offset (always `offset + maxLen`).
+ */
+declare function putString(buf: Buffer, offset: number, str: string, maxLen: number): number;
+/**
+ * Read a fixed-length string from `buf` at `offset` for `length` bytes.
+ * Trailing NUL bytes are stripped.
+ */
+declare function getString(buf: Buffer, offset: number, length: number): [string, number];
+/** Copy `data` into `buf` at `offset`, return new offset. */
+declare function putBytes(buf: Buffer, offset: number, data: Uint8Array): number;
+/** Slice `length` bytes from `buf` at `offset`, return `[slice, newOffset]`. */
+declare function getBytes(buf: Buffer, offset: number, length: number): [Buffer, number];
 //#endregion
-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 };
+export { type AuthConfig, BODY_SIZE, CRED_TYPE, type ChunkInfo, ClientError, DEFAULT_PORT, type DirectoryEntry, type DirectoryList, DirlistOptions, type ErrorResponse, FHANDLE_SIZE, File, FileSystem, type Frame, Framer, HANDSHAKE_FIFTH, HANDSHAKE_FIRST, HANDSHAKE_FOURTH, HANDSHAKE_SECOND, HANDSHAKE_THIRD, type ITransport, type Location, type LocationInfo, type LoginResponse, Message, Multiplexer, OpenFlags, type OpenOptions, type OpenResponse, PROTOCOL_VERSION, type ProtocolInfo, type ProtocolResponse, REQUEST_HDR_SIZE, REQUEST_OFFSET_BODY, REQUEST_OFFSET_DLEN, REQUEST_OFFSET_REQUEST_ID, REQUEST_OFFSET_STREAM_ID, RESPONSE_HDR_SIZE, RESPONSE_OFFSET_BODY, RESPONSE_OFFSET_DLEN, RESPONSE_OFFSET_STATUS, RESPONSE_OFFSET_STREAM_ID, type RedirectResponse, RequestId, ResponseStatus, SESS_ID_SIZE, S_IFDIR, S_IFLNK, ServerError, type Session, StatFlags, type StatInfo, Transport, type WaitResponse, XRootDClient, type XRootDClientOptions, XRootDError, XRootDUrl, buildCloseRequest, buildHandshakeAndProtocol, buildLoginRequest, buildOpenRequest, buildReadRequest, buildStatRequest, buildWriteRequest, createStatInfo, get16, get32, getBytes, getString, handshake, kXR_ExpBind, kXR_ExpLogin, kXR_ableTLS, kXR_bifreqs, kXR_secreqs, kXR_wantTLS, parseErrorResponse, parseLoginResponse, parseOpenResponse, parseProtocolResponse, parseRedirectResponse, parseWaitResponse, put16, put32, putBytes, putString };
+//# sourceMappingURL=index.d.mts.map