ms-remote 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,388 @@
1
+ Metadata-Version: 2.5
2
+ Name: ms-remote
3
+ Version: 0.1.0
4
+ Summary: 统一远程节点操作库(HTTP & SSH 双通道),供 msmodeling / OptiX 插件依赖
5
+ License-Expression: MulanPSL-2.0
6
+ Requires-Python: >=3.10
7
+ Provides-Extra: all
8
+ Requires-Dist: fabric>=2.0; extra == 'all'
9
+ Requires-Dist: loguru; extra == 'all'
10
+ Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'all'
11
+ Provides-Extra: ssh
12
+ Requires-Dist: fabric>=2.0; extra == 'ssh'
13
+ Requires-Dist: loguru; extra == 'ssh'
14
+ Provides-Extra: toml
15
+ Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'toml'
16
+ Description-Content-Type: text/markdown
17
+
18
+ # ms-remote (msremote)
19
+
20
+ ssh_by_http 项目的统一远程节点操作库,同时支持 **HTTP** 和 **SSH** 两种传输方式。通过单一 `DistributedPlugin` 门面,调用方无需关心底层协议。
21
+
22
+ ## 功能特性
23
+
24
+ - ✅ 统一接口:`run` / `put` / `get` / `background` / `check_health` / `close`
25
+ - ✅ 用户显式指定后端:`backend="http"` 或 `backend="ssh"`,不猜不探测
26
+ - ✅ 文件传输:同时支持文件上传和文件下载:HTTP 走 multipart 上传 + `/download` 流式下载;SSH 走 SFTP
27
+ - ✅ 后台进程:支持 `nohup` 方式启动并追踪 PID
28
+ - ✅ Docker 支持:自动包装 `docker exec` / `docker cp`
29
+ - ✅ 懒加载:`fabric` 仅在 SSH 后端首次使用时才导入
30
+
31
+ ## 安装
32
+
33
+ ```bash
34
+ # 源码(开发期 / git URL 依赖,不发布到包索引)
35
+ pip install -e .
36
+ # 或按需开启 SSH / TOML 特性
37
+ pip install -e '.[ssh,toml]'
38
+ ```
39
+
40
+ ## 快速开始
41
+
42
+ ```python
43
+ from msremote import DistributedPlugin, HttpRemote, RemoteResult
44
+
45
+ # 修改为你的实际节点信息
46
+ HOST = "192.168.1.100"
47
+ HTTP_PORT = 22000
48
+
49
+ # 方式一:直接构造后端
50
+ plugin = DistributedPlugin(
51
+ remote=HttpRemote(host=HOST, http_port=HTTP_PORT),
52
+ )
53
+
54
+ # 方式二:通过 from_node 指定后端
55
+ class MyNode:
56
+ host = HOST
57
+ http_port = HTTP_PORT
58
+
59
+ plugin = DistributedPlugin.from_node(MyNode(), preferred_backend="http")
60
+
61
+ # 执行命令
62
+ result = plugin.run("hostname")
63
+ print(result.stdout)
64
+
65
+ # 文件传输
66
+ plugin.put("model.pt", "/tmp/model.pt")
67
+ plugin.get("/tmp/model.pt", "./model_downloaded.pt")
68
+
69
+ # 健康检查
70
+ health = plugin.check_health()
71
+ print(health) # {"status": "healthy", "active_async_tasks": 0}
72
+
73
+ # 清理
74
+ plugin.close()
75
+ ```
76
+
77
+ ### 从配置文件加载
78
+
79
+ 通过 TOML 配置文件管理集群节点,避免在代码中硬编码连接信息:
80
+
81
+ ```toml
82
+ # cluster.toml
83
+ [[node]]
84
+ host = "192.168.1.100"
85
+ backend = "http"
86
+ http_port = 22000
87
+
88
+ [[node]]
89
+ host = "192.168.1.101"
90
+ backend = "ssh"
91
+ ssh_user = "root"
92
+ password = ""
93
+ ```
94
+
95
+ ```python
96
+ from msremote import DistributedPlugin, ClusterConfig
97
+
98
+ cluster = ClusterConfig.from_file("cluster.toml")
99
+ plugin = DistributedPlugin.from_config(cluster.get("192.168.1.100"))
100
+ result = plugin.run("hostname")
101
+ ```
102
+
103
+ 配置采用扁平结构,每个 `[[node]]` 自包含所有参数。必填 `host` 和 `backend`,其余参数使用默认值。
104
+ 参考 [cluster_config.toml](cluster_config.toml) 查看完整示例。
105
+
106
+ > 需要 TOML 解析器:Python 3.11+ 自带 `tomllib`,低版本需 `pip install tomli`
107
+
108
+ ## 后端选择
109
+
110
+ 通过 `preferred_backend` 或配置文件中的 `backend` 参数指定后端:
111
+
112
+ | 值 | 行为 |
113
+ |----|------|
114
+ | `"http"`(默认) | 使用 `HttpRemote`(HTTP API) |
115
+ | `"ssh"` | 使用 `SshRemote`(fabric/SSH) |
116
+
117
+ ### HTTP 后端 (HttpRemote)
118
+
119
+ 通过 ssh_by_http 服务器的 REST API 执行命令,适用于已部署 `cmdserver` 的场景。
120
+
121
+ | 参数 | 默认值 | 说明 |
122
+ |------|--------|------|
123
+ | `host` | — | 服务器 IP 或域名 |
124
+ | `http_port` | 22000 | 服务器端口 |
125
+ | `docker_container_id` | None | Docker 容器 ID,设置后命令包装为 `docker exec` |
126
+ | `docker_use_sudo` | False | 是否在命令前加 `sudo` |
127
+
128
+ **命令执行模式:**
129
+
130
+ - **短命令**(≤30s 且 ≤1000 字符):单次 POST `/execute` 同步返回,无额外轮询
131
+ - **长命令**:通过状态文件追踪,定期轮询,命令超时后自动终止
132
+
133
+ ### SSH 后端 (SshRemote)
134
+
135
+ 通过 fabric 库走 SSH 协议,适用于传统 SSH 可达的节点。
136
+
137
+ | 参数 | 默认值 | 说明 |
138
+ |------|--------|------|
139
+ | `host` | — | 服务器 IP 或域名 |
140
+ | `ssh_port` | 22 | SSH 端口 |
141
+ | `ssh_user` | "root" | SSH 用户名 |
142
+ | `password` | None | SSH 密码(base64 编码也会自动解码) |
143
+ | `docker_container_id` | None | Docker 容器 ID |
144
+ | `docker_use_sudo` | False | 是否在命令前加 `sudo` |
145
+ | `ssh_command_timeout` | 30 | 单条 SSH 命令超时 |
146
+
147
+ ## API 参考
148
+
149
+ ### 接口总览
150
+
151
+ | 方法 | 说明 |
152
+ |------|------|
153
+ | `run(command, **kwargs) → RemoteResult` | 执行命令,返回结果对象 |
154
+ | `put(local_path, remote_path) → None` | 上传本地文件到远程 |
155
+ | `get(remote_path, local_path) → None` | 下载远程文件到本地 |
156
+ | `background(inner_cmd, node_label, remote_pids, **kwargs) → (pid, log_file)` | 后台启动命令,返回 PID 和日志路径 |
157
+ | `check_health() → dict` | 健康检查,返回 `{"status": "healthy", ...}` |
158
+ | `close() → None` | 释放连接(SSH 关闭连接,HTTP 无操作) |
159
+ | `from_node(node, preferred_backend="http", **kwargs) → DistributedPlugin` | 从节点对象构建插件实例 |
160
+ | `from_config(node_config) → DistributedPlugin` | 从配置文件加载的 NodeConfig 构建插件实例 |
161
+
162
+ ### run(command, \*\*kwargs) → RemoteResult
163
+
164
+ 在远程主机上执行命令,返回 `RemoteResult`。
165
+
166
+ ```python
167
+ result = plugin.run("nvidia-smi")
168
+ print(result.stdout) # 标准输出
169
+ print(result.ok) # True 表示退出码为 0
170
+ print(result.exited) # 退出码
171
+
172
+ # 超时控制(秒),超时后命令被自动终止
173
+ result = plugin.run("sleep 9999", timeout=1200)
174
+
175
+ # 失败不抛异常,返回结果对象
176
+ result = plugin.run("cat /nonexistent", warn=True)
177
+ print(result.failed) # True
178
+ ```
179
+
180
+ **HTTP 后端额外行为:**
181
+ - ≤30s 的命令走同步路径,一次请求返回
182
+ - 长命令通过状态文件轮询,连接断开也不丢失
183
+
184
+ **SSH 后端额外参数:**
185
+ - `hide=True`:隐藏远程输出
186
+ - `pty=True`:分配伪终端
187
+
188
+ ### put(local_path, remote_path) → None
189
+
190
+ 上传本地文件到远程主机。
191
+
192
+ ```python
193
+ plugin.put("model.pt", "/tmp/model.pt")
194
+ ```
195
+
196
+ - **HTTP**:multipart POST 上传到暂存区 → sha256 校验 → mv 到目标路径
197
+ - **SSH**:通过 SFTP 传输
198
+
199
+ ### get(remote_path, local_path) → None
200
+
201
+ 下载远程文件到本地。
202
+
203
+ ```python
204
+ plugin.get("/tmp/output.log", "./output.log")
205
+ ```
206
+
207
+ - **HTTP**:GET `/download?path=...` 流式下载。注意:只能下载 `/tmp`、`DOWNLOAD_DIR`、`LOG_DIR` 下的文件
208
+ - **SSH**:通过 SFTP 下载
209
+
210
+ ### background(inner_cmd, node_label, remote_pids, \*\*kwargs) → (pid, log_file)
211
+
212
+ 在后台启动命令,立即返回 PID 和日志路径。
213
+
214
+ ```python
215
+ remote_pids = {}
216
+ pid, log_file = plugin.background(
217
+ "python train.py --epochs 100",
218
+ node_label="gpu-01",
219
+ remote_pids=remote_pids,
220
+ )
221
+ print(f"PID: {pid}, log: {log_file}")
222
+
223
+ # 稍后下载日志
224
+ plugin.get(log_file, "./train_output.log")
225
+ ```
226
+
227
+ 参数说明:
228
+
229
+ | 参数 | 说明 |
230
+ |------|------|
231
+ | `inner_cmd` | 要执行的 shell 命令 |
232
+ | `node_label` | 节点标签,用作 `remote_pids` 的 key |
233
+ | `remote_pids` | 会被原地修改的字典,写入 `{node_label: pid}` |
234
+ | `remote_pid_nodes` | 可选,记录 `{node_label: node}` 映射 |
235
+ | `node` | 可选,节点对象 |
236
+ | `log_file` | 可选,复用已有日志文件路径 |
237
+ | `append` | 可选,日志追加模式(默认 False 截断) |
238
+
239
+ ### check_health() → dict
240
+
241
+ 验证远程端点是否可达。
242
+
243
+ ```python
244
+ health = plugin.check_health()
245
+ # {"status": "healthy", "active_async_tasks": 0}
246
+ ```
247
+
248
+ ### close() → None
249
+
250
+ 释放底层连接。HTTP 后端为无操作,SSH 后端关闭连接。
251
+
252
+ ### from_node(node, preferred_backend="http", \*\*kwargs) → DistributedPlugin
253
+
254
+ 工厂方法,从节点对象构建插件实例。
255
+
256
+ ```python
257
+ class MyNode:
258
+ host = "192.168.1.100"
259
+ http_port = 22000
260
+
261
+ plugin = DistributedPlugin.from_node(MyNode())
262
+ plugin = DistributedPlugin.from_node(MyNode(), preferred_backend="ssh")
263
+ ```
264
+
265
+ ### from_config(node_config) → DistributedPlugin
266
+
267
+ 从 `NodeConfig`(由 `ClusterConfig.from_file()` 加载)构建插件实例。
268
+
269
+ ```python
270
+ cluster = ClusterConfig.from_file("cluster.toml")
271
+ plugin = DistributedPlugin.from_config(cluster.get("192.168.1.100"))
272
+ ```
273
+
274
+ ### RemoteResult
275
+
276
+ ```python
277
+ @dataclass(frozen=True)
278
+ class RemoteResult:
279
+ stdout: str # 标准输出
280
+ stderr: str # 标准错误
281
+ exited: int # 退出码
282
+
283
+ @property
284
+ def ok(self) -> bool: ... # exited == 0
285
+ @property
286
+ def failed(self) -> bool: ... # not ok
287
+ @property
288
+ def return_code(self) -> int: ...
289
+ @property
290
+ def returncode(self) -> int: ... # 兼容 subprocess 命名
291
+ ```
292
+
293
+ ## 使用示例
294
+
295
+ ### 后台进程
296
+
297
+ ```python
298
+ remote_pids = {}
299
+ plugin = DistributedPlugin.from_node(node)
300
+
301
+ pid, log_file = plugin.background(
302
+ "python train.py --epochs 100",
303
+ node_label="gpu-01",
304
+ remote_pids=remote_pids,
305
+ )
306
+
307
+ print(f"PID: {pid}, log: {log_file}")
308
+ # 稍后下载日志
309
+ plugin.get(log_file, "./train_output.log")
310
+ ```
311
+
312
+ ### 文件上传下载
313
+
314
+ ```python
315
+ # 上传本地文件
316
+ plugin.put("model.pt", "/tmp/model.pt")
317
+
318
+ # 下载远程文件
319
+ plugin.get("/tmp/model.pt", "./model_downloaded.pt")
320
+ ```
321
+
322
+ ### Docker 容器内执行
323
+
324
+ ```python
325
+ plugin = DistributedPlugin.from_node(
326
+ node,
327
+ preferred_backend="http",
328
+ docker_use_sudo=True,
329
+ )
330
+
331
+ # 宿主机命令(container_exec=False)
332
+ plugin.run("docker ps", container_exec=False)
333
+
334
+ # 容器内命令(默认 container_exec=True)
335
+ result = plugin.run("nvidia-smi")
336
+ ```
337
+
338
+ ### 健康检查 + 重试
339
+
340
+ ```python
341
+ import time
342
+
343
+ plugin = DistributedPlugin.from_node(node)
344
+
345
+ for i in range(3):
346
+ health = plugin.check_health()
347
+ if health.get("status") == "healthy":
348
+ break
349
+ print(f"Waiting... ({health.get('detail', '')})")
350
+ time.sleep(2)
351
+ else:
352
+ raise RuntimeError("Node not healthy")
353
+ ```
354
+
355
+ ## 与 ssh_by_http 服务端配合
356
+
357
+ 1. 在目标机器上启动 ssh_by_http 服务:
358
+
359
+ ```bash
360
+ cd http/server
361
+ cp .env.example .env
362
+ python main.py # 默认监听 0.0.0.0:22000
363
+ ```
364
+
365
+ 2. 在控制端使用 HTTP 后端连接:
366
+
367
+ ```python
368
+ from msremote import DistributedPlugin
369
+
370
+ class TargetNode:
371
+ host = "192.168.1.100"
372
+ http_port = 22000
373
+
374
+ plugin = DistributedPlugin.from_node(TargetNode())
375
+ result = plugin.run("hostname")
376
+ print(result.stdout)
377
+ ```
378
+
379
+ ## 依赖
380
+
381
+ | 依赖 | 需要场景 | 说明 |
382
+ |------|----------|------|
383
+ | `fabric` | SSH 后端 | 懒加载,仅纯 HTTP 场景不需要 |
384
+ | `loguru` | 可选 | 日志增强,未安装则回退到标准 `logging` |
385
+
386
+ ## 许可证
387
+
388
+ MIT
@@ -0,0 +1,13 @@
1
+ msremote/__init__.py,sha256=3AeOSDZpfpSUvsRnygi0poRINs-DAre7QT-akbFVqF8,930
2
+ msremote/cluster_config.toml,sha256=qLA6r6Q-FZbnGTST9c5uVErVZ39LsPZAvymC6LvX00A,1147
3
+ msremote/config.py,sha256=hjTx2ER4VFL12RcoK-Lgmb9kBODxcUn0deoPMiCAJ_k,4228
4
+ msremote/plugin.py,sha256=Tin_dqS9p7iJtVUIwjWc6xQOxCWptlRtPrLBdZF7YDY,7377
5
+ msremote/remote_client.py,sha256=mPeFUb_H7w6H-7C-dT2drPjNDOkFAWHJD7JKVJihxZs,6214
6
+ msremote/result.py,sha256=Sd4jNT9sRWFaCN26FJPpC-zjK3V1LOmI-juuU7fNe2c,747
7
+ msremote/http/__init__.py,sha256=2bi2e_2W6WNmKOK_ENS90u0CRM5UHNJF8Om1qV8oUc0,194
8
+ msremote/http/http_remote_client.py,sha256=G2N74boLU9oE3VkXVmxsSyszk-oE2zZJoZSec1ZzkYo,30565
9
+ msremote/ssh/__init__.py,sha256=VCnwpMcSCr3wR8OzsHPFrnTgFpkt_7nmw9Jk1RebQDs,206
10
+ msremote/ssh/ssh_remote_client.py,sha256=Jgt0vz8qrI-8R7um1i3yHgm6QTBXMoVekHTzcWb4OcA,14301
11
+ ms_remote-0.1.0.dist-info/METADATA,sha256=h-O88hf0j42eStnpvTBMTkGsfQQ1yLrh0t5OGiuwzig,10704
12
+ ms_remote-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
13
+ ms_remote-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
msremote/__init__.py ADDED
@@ -0,0 +1,35 @@
1
+ """分布式执行插件,支持 HTTP 和 SSH 两种后端。
2
+
3
+ 提供统一的门面类 :class:`DistributedPlugin`,同时支持
4
+ HTTP 和 SSH 远程命令执行、文件传输和后台进程管理。
5
+
6
+ 快速开始::
7
+
8
+ from msremote import DistributedPlugin
9
+
10
+ plugin = DistributedPlugin.from_node(my_node)
11
+ result = plugin.run("hostname")
12
+ print(result.stdout)
13
+ plugin.close()
14
+ """
15
+
16
+ from .result import RemoteResult
17
+ from .remote_client import RemoteClient, NodeProtocol
18
+ from .http import HttpRemote, HttpRemoteError
19
+ from .ssh import SshRemote, SshRemoteError
20
+ from .plugin import DistributedPlugin, DistributedPluginError
21
+ from .config import NodeConfig, ClusterConfig
22
+
23
+ __all__ = [
24
+ "RemoteClient",
25
+ "NodeProtocol",
26
+ "DistributedPlugin",
27
+ "DistributedPluginError",
28
+ "RemoteResult",
29
+ "HttpRemote",
30
+ "HttpRemoteError",
31
+ "SshRemote",
32
+ "SshRemoteError",
33
+ "NodeConfig",
34
+ "ClusterConfig",
35
+ ]
@@ -0,0 +1,25 @@
1
+ # msremote 集群配置文件
2
+ # ===============================================
3
+ #
4
+ # 每个 [[node]] 自包含所有配置,不依赖全局默认值或分组继承。
5
+ # 需要 TOML 解析器:Python 3.11+ 自带 tomllib,低版本执行 pip install tomli
6
+ #
7
+ # 必填:host、backend("http" 或 "ssh")
8
+ # 可选:http_port(默认 22000)、ssh_port(默认 22)、ssh_user(默认 root)、password 等
9
+ # 节点标识:可直接用 host 查找,也可指定 name 作为别名
10
+
11
+
12
+ # HTTP 节点(需要目标机器上部署了 cmdserver)
13
+ [[node]]
14
+ host = "192.168.1.100" # 节点 IP 或域名(作为标识)
15
+ backend = "http" # 后端类型:http 或 ssh
16
+ http_port = 22000 # HTTP 服务端口
17
+
18
+
19
+ # SSH 节点(传统 SSH 可达的节点)
20
+ [[node]]
21
+ host = "192.168.1.102" # 节点 IP 或域名(作为标识)
22
+ backend = "ssh" # 后端类型:http 或 ssh
23
+ ssh_user = "root" # 登录用户名
24
+ password = "" # SSH 密码,填写你的密码
25
+ docker_container_id = "my-training-container" # 容器名或 ID(docker ps 查看)
msremote/config.py ADDED
@@ -0,0 +1,152 @@
1
+ """DistributedPlugin 的节点配置加载器。
2
+
3
+ 从 TOML 文件中加载节点连接配置,让你可以声明式地管理集群,
4
+ 而无须在代码中手动构造节点对象。
5
+
6
+ TOML 结构::
7
+
8
+ [[node]]
9
+ host = "192.168.1.100"
10
+ backend = "http"
11
+ http_port = 22000
12
+
13
+ [[node]]
14
+ host = "192.168.1.101"
15
+ backend = "ssh"
16
+ ssh_user = "root"
17
+ password = ""
18
+
19
+ 用法::
20
+
21
+ from msremote import DistributedPlugin, ClusterConfig
22
+
23
+ cluster = ClusterConfig.from_file("cluster.toml")
24
+ plugin = DistributedPlugin.from_config(cluster.get("192.168.1.100"))
25
+ result = plugin.run("nvidia-smi")
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ from dataclasses import dataclass, field
31
+ from pathlib import Path
32
+ from typing import List, Optional
33
+
34
+
35
+ def _load_toml(text: str) -> dict:
36
+ """解析 TOML 文本,依次尝试标准库和第三方解析器。"""
37
+ for mod_name in ("tomllib", "tomli"):
38
+ try:
39
+ mod = __import__(mod_name, fromlist=["loads"])
40
+ return mod.loads(text)
41
+ except ImportError:
42
+ continue
43
+ try:
44
+ import toml # 旧版第三方包
45
+ return toml.loads(text)
46
+ except ImportError:
47
+ raise ImportError(
48
+ "需要 TOML 解析器。"
49
+ "请使用 Python 3.11+,或执行: pip install tomli"
50
+ )
51
+
52
+
53
+ # ---------------------------------------------------------------------------
54
+ # 所有已识别的字段名,TOML 中的额外键(如 chips_per_node)会被静默忽略
55
+ # ---------------------------------------------------------------------------
56
+ _NODE_FIELDS = {
57
+ "name", "host", "backend",
58
+ "docker_container_id", "docker_use_sudo",
59
+ "http_port",
60
+ "ssh_port", "ssh_user", "password", "ssh_command_timeout",
61
+ }
62
+
63
+
64
+ @dataclass
65
+ class NodeConfig:
66
+ """单个远程节点的配置。
67
+
68
+ 字段与 :class:`HttpRemote` 和 :class:`SshRemote` 的参数对应。
69
+ 只有 ``name`` 和 ``host`` 是必填项;其余字段均使用合理的默认值。
70
+ """
71
+
72
+ name: str
73
+ host: str
74
+ backend: str = "http"
75
+
76
+ # --- 通用 ---
77
+ docker_container_id: Optional[str] = None
78
+ docker_use_sudo: bool = False
79
+
80
+ # --- HTTP 后端 ---
81
+ http_port: int = 22000
82
+
83
+ # --- SSH 后端 ---
84
+ ssh_port: int = 22
85
+ ssh_user: str = "root"
86
+ password: Optional[str] = None
87
+ ssh_command_timeout: int = 30
88
+
89
+
90
+ @dataclass
91
+ class ClusterConfig:
92
+ """从 TOML 文件加载的命名节点配置集合。
93
+
94
+ TOML 文件使用 ``[[node]]`` 数组表语法定义节点,每个节点自包含所有配置。
95
+ """
96
+
97
+ nodes: List[NodeConfig] = field(default_factory=list)
98
+
99
+ @classmethod
100
+ def from_file(cls, path: str | Path) -> "ClusterConfig":
101
+ """从 TOML 文件加载集群配置。
102
+
103
+ 参数:
104
+ path: ``.toml`` 文件的路径。
105
+
106
+ 返回值:
107
+ 新的 ``ClusterConfig`` 实例。
108
+
109
+ 异常:
110
+ FileNotFoundError: 文件不存在。
111
+ ImportError: 无可用的 TOML 解析器。
112
+ """
113
+ path = Path(path)
114
+ data = _load_toml(path.read_text(encoding="utf-8"))
115
+
116
+ raw_nodes = data.get("node", [])
117
+ if not isinstance(raw_nodes, list):
118
+ raw_nodes = []
119
+
120
+ nodes: List[NodeConfig] = []
121
+ for node_data in raw_nodes:
122
+ if not isinstance(node_data, dict):
123
+ continue
124
+ if "host" not in node_data:
125
+ continue
126
+
127
+ if "name" not in node_data:
128
+ node_data["name"] = node_data["host"]
129
+
130
+ filtered = {k: v for k, v in node_data.items() if k in _NODE_FIELDS}
131
+ nodes.append(NodeConfig(**filtered))
132
+
133
+ return cls(nodes=nodes)
134
+
135
+ def get(self, name: str) -> NodeConfig:
136
+ """按 ``name`` 查找节点配置。
137
+
138
+ 异常:
139
+ KeyError: 不存在该名称的节点。
140
+ """
141
+ for node in self.nodes:
142
+ if node.name == name:
143
+ return node
144
+ raise KeyError(f"节点 {name!r} 在集群配置中未找到")
145
+
146
+ def __iter__(self):
147
+ """遍历所有 :class:`NodeConfig` 条目。"""
148
+ return iter(self.nodes)
149
+
150
+ def __len__(self) -> int:
151
+ """返回节点数量。"""
152
+ return len(self.nodes)
@@ -0,0 +1,8 @@
1
+ """HTTP 后端。
2
+
3
+ 通过 ssh_by_http 服务器的 REST 接口进行通信。
4
+ """
5
+
6
+ from .http_remote_client import HttpRemote, HttpRemoteError
7
+
8
+ __all__ = ["HttpRemote", "HttpRemoteError"]