@co0ontty/wand 4.72.2 → 4.75.0-beta.g1d477a2

package/dist/render-daemon-client.d.ts

@@ -0,0 +1,202 @@
+import { type RenderMethod } from "./render-protocol.js";
+import { type TerminalAttachResult, type TerminalHost, type TerminalSessionState, type TerminalSpawnRequest } from "./terminal-host.js";
+/**
+ * 鉴权层面的失败（与网络抖动区分）。
+ *
+ * 特征：连接建立成功、hello 发出后对端**一个字节都没回**就关闭 —— Render 对
+ * token 不符/协议不符的处理就是直接 `close()`。单独一个类型是为了让重连策略
+ * 能把「同一把废 token」和「daemon 不在了」区分开，而不是一律 10s 重试。
+ */
+export declare class RenderAuthError extends Error {
+    constructor(message: string);
+}
+/**
+ * 远端 PTY 句柄。Render 可能在这个对象挂上 listener 之前就推来 data/exit
+ * （大输出场景几乎必然发生），所以先做有界缓存，挂上后按序补发。
+ */
+/**
+ * 运行时自愈回调：把「端点已消失、且 config 上没有活着的 daemon」的 Render 重新拉起来。
+ * 返回 true 表示起了新进程（调用方应立刻重连）。
+ */
+export type RenderDaemonReviver = () => Promise<boolean>;
+/**
+ * Render（常驻 PTY 持有者）的 Node 客户端。
+ *
+ * 与 legacy `TerminalDaemonClient` 的关键差异：**这里只有 PTY**，没有结构化运行；
+ * 另外 `disconnect()` 只解绑 socket，Render 进程与其 PTY 全部保留 —— 这正是
+ * Server 因 `npm update` 重启而 PTY 不丢的前提。
+ */
+export declare class RenderDaemonClient implements TerminalHost {
+    private readonly socketPath;
+    private readonly token;
+    /**
+     * token 文件路径。给了它就在**每次 connect 时重读**：Render 崩溃/升级重启后
+     * 会 `generate_token()` 轮换 token，只缓存构造期的那一把会让重连永远鉴权失败
+     * （现象是 `createOrAttach` 全部失败、错误只显示 unavailable，旧会话被永久报成 running）。
+     */
+    private readonly tokenPath;
+    /** Persisted PTY IDs used only if v1 `list` exceeds its aggregate frame limit. */
+    private readonly knownSessionIds;
+    /**
+     * 运行时自愈回调：重连失败时问它能不能把 daemon 拉回来（返回 true = 起了新进程）。
+     * 只有「端点已消失 + config 上没有活着的 daemon」时它才动手，见 `render-host.ts`。
+     */
+    private readonly reviveDaemon;
+    readonly persistent = true;
+    private socket;
+    private nextRequestId;
+    private readonly pending;
+    private readonly inventory;
+    private readonly handles;
+    private readonly pendingEvents;
+    private readonly pendingEventOverflows;
+    private readonly refreshingSessions;
+    private reconciling;
+    private eventsDuringReconcile;
+    private reconcileDuringSync;
+    private headerParts;
+    private headerBytes;
+    private bodyParts;
+    private bodyBytes;
+    private frameLength;
+    private disposed;
+    private reconnectTimer;
+    private reconnectDelayMs;
+    private reconnectFailureLogged;
+    private offlineOperationLogged;
+    /** 协议版本不匹配是终态：重试无意义，也不允许降级运行。 */
+    private fatalProtocolError;
+    private daemonVersion;
+    /** 最近一次 connect 时实际使用的凭据。 */
+    private activeToken;
+    /** 最后一次成功读到的凭据；token 文件暂时读不到时用它，避免重连因一次 IO 失败直接放弃。 */
+    private lastKnownToken;
+    /** 已经因为「读不到 token 文件」告警过，避免每次重连都刷一行。 */
+    private tokenReadFailureLogged;
+    /** 当前 socket 上已解出的帧数，用来区分「未鉴权被直接关闭」与网络错误。 */
+    private framesOnCurrentSocket;
+    private connecting;
+    private stopHeartbeat;
+    constructor(socketPath: string, token: string, 
+    /**
+     * token 文件路径。给了它就在**每次 connect 时重读**：Render 崩溃/升级重启后
+     * 会 `generate_token()` 轮换 token，只缓存构造期的那一把会让重连永远鉴权失败
+     * （现象是 `createOrAttach` 全部失败、错误只显示 unavailable，旧会话被永久报成 running）。
+     */
+    tokenPath?: string | null, 
+    /** Persisted PTY IDs used only if v1 `list` exceeds its aggregate frame limit. */
+    knownSessionIds?: readonly string[], 
+    /**
+     * 运行时自愈回调：重连失败时问它能不能把 daemon 拉回来（返回 true = 起了新进程）。
+     * 只有「端点已消失 + config 上没有活着的 daemon」时它才动手，见 `render-host.ts`。
+     */
+    reviveDaemon?: RenderDaemonReviver | null);
+    get version(): string;
+    /** daemon 侧已知的会话数（`inventory` 是 `list`/`attach` 的权威投影）。 */
+    get sessionCount(): number;
+    /**
+     * 让 daemon 干净收摊（`shutdown mode=now`：杀掉所有 PTY 后退出）。
+     * **只允许用在「daemon 空闲」的升级场景**（sessionCount === 0）；持有活会话时
+     * 调用它会杀掉用户的 shell。
+     */
+    requestShutdownNow(): Promise<void>;
+    connect(): Promise<void>;
+    private open;
+    /**
+     * 对端一个字节都没回就断开：daemon 对 token/协议不符的处理是直接 `close()`
+     * （`wand-renderd` 的 `server.rs`），所以这是鉴权/版本问题的特征，不是网络抖动。
+     * 归类为 `RenderAuthError`，由重连策略决定「别再 10s 一次拿同一把废 token 试」。
+     */
+    private describeConnectFailure;
+    /**
+     * 读取当前凭据：每次都用 token 文件里的**最新**值（daemon 重启会轮换）。
+     * 文件暂时读不到（渲染器正在退出、路径还没建）不是致命错误，回落到上一次成功
+     * 读到的值并告警一次；下一次连接会重试读文件。
+     */
+    private readToken;
+    private warnTokenFileUnusable;
+    /** resize 走的是异步 RPC，但 inventory 必须立刻反映新尺寸（见 RemoteRenderProcess.resize）。 */
+    noteTerminalResize(sessionId: string, cols: number, rows: number): void;
+    attach(sessionId: string, afterSeq?: number): TerminalAttachResult | null;
+    createOrAttach(request: TerminalSpawnRequest, afterSeq?: number): Promise<TerminalAttachResult>;
+    forget(sessionId: string): void;
+    /**
+     * 只解绑：关闭 socket、清掉内存句柄，**Render 进程与它的所有 PTY 都保持运行**。
+     * 这是 Server / Render 分离的核心 —— 下一次启动 attach 回来仍拿到同一批会话。
+     */
+    disconnect(): void;
+    /**
+     * Best-effort 操作：Render 不可用时打 stderr，绝不把异常抛回调用方，
+     * 否则一次 PTY 抖动会顺着 ProcessManager 把整个会话路径打断。
+     */
+    fireOperation(sessionId: string, method: RenderMethod, params?: Record<string, unknown>): void;
+    confirmWrite(sessionId: string, data: string): Promise<void>;
+    reportOperationError(sessionId: string, method: RenderMethod, error: unknown): void;
+    private listSessions;
+    /** `list` locates sessions; each `attach` is the authoritative recovery state. */
+    private loadAuthoritativeSessions;
+    private parseHello;
+    private request;
+    private consume;
+    private resetFrameDecoder;
+    private handleFrame;
+    private handleResponse;
+    private routeEvent;
+    private queuePendingEvent;
+    /** Repair a bounded event-buffer overflow without replaying a partial stream. */
+    private refreshSession;
+    /**
+     * Render 主动告知当前会话集合（例如自身清掉了已 forget 的会话）。不在
+     * 集合里的会话要给既有句柄补一个退出事件，否则 ProcessManager 会永远停在 running。
+     */
+    private handleReconcileEvent;
+    /**
+     * Socket 断开后的重连。不做重连的话，Render 重启一次所有
+     * RemoteRenderProcess 就会静默失效，而 ProcessManager 仍显示 running。
+     */
+    private handleDisconnect;
+    /** 被同一个凭据反复拒绝时置位：下一次重连改用长退避（见 `scheduleReconnect`）。 */
+    private authBackoff;
+    /**
+     * 安排下一次重连（已有定时器时不重排：一次失败可能会从 close/error 两条路径
+     * 各调一次，重排会把退避倍率叠成指数增长）。需要**覆盖**已有定时器的场景
+     * （鉴权失败要把 10s 换成 60s）由调用方显式清掉再调。
+     */
+    private scheduleReconnect;
+    private tryReconnect;
+    private noteReconnectSuccess;
+    /** 自愈回调本身绝不能让重连路径抛错；失败按「没拉起」处理。 */
+    private reviveDaemonForRetry;
+    private noteReconnectFailureAndSchedule;
+    /**
+     * 重连失败的日志与「同一把废 token」判定。
+     *
+     * 判定依据：刚刚用掉的那把凭据（`activeToken`，每次连接开头从 token 文件重读）
+     * 与文件里**现在**这一把相同 → 再试同一个值不可能成功（对端持有的是别的 token，
+     * 多来自 `-c` 指到了另一个 config 或有人在手工改 token 文件），摆成 60s 长退避。
+     * 文件已经变了就按普通退避重试 —— 那正是 daemon 重启轮换 token 后的自愈路径。
+     * @returns 是否处于「同一把废凭据」状态（调用方据此换长退避）
+     */
+    private noteReconnectFailure;
+    /** 只读 token 文件当前值（不改状态）；读不到返回 null。 */
+    private currentTokenFileValue;
+    /**
+     * 断线期间 Render 可能新建/结束会话。用断线前的 inventory 与新的 `list` 对账：
+     * 活着的补发缺口 chunk；消失或已退出的给句柄补合成退出。
+     */
+    private reconcileAfterReconnect;
+    private resultFromState;
+    private rejectPending;
+}
+/**
+ * 运行期校验 Render 的 SessionState。
+ *
+ * 协议是跨语言契约（Rust 侧字段名漂移过一次就是静默的空终端），所以这里不做
+ * 结构断言直接使用，而是逐字段检查：能修的补默认值，修不了的整条丢弃并打警告。
+ */
+export declare function normalizeRenderSessionState(value: unknown): TerminalSessionState | null;
+/**
+ * 连接一个已经存在的 Render（socket + token 都在）。**不 spawn**，找不到就返回 null，
+ * 这样调用方可以区分「已被别处 adopt」和「需要自己拉起」。
+ */
+export declare function connectExistingRenderClient(configPath: string, knownSessionIds?: readonly string[], reviveDaemon?: RenderDaemonReviver | null): Promise<RenderDaemonClient | null>;