ssh_workspace_fs.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327
  1. """Filesystem adapter for Desktop workspaces executed over SSH."""
  2. from __future__ import annotations
  3. import base64
  4. import binascii
  5. import posixpath
  6. import shlex
  7. import subprocess
  8. import threading
  9. import uuid
  10. from dataclasses import dataclass
  11. from typing import Any, Iterator
  12. from hermes_cli._subprocess_compat import windows_hide_flags
  13. from tools.environments.ssh import SSHEnvironment
  14. class SshWorkspaceFsError(RuntimeError):
  15. """A filesystem error reported by the SSH execution target."""
  16. def __init__(self, code: str, message: str | None = None):
  17. super().__init__(message or code)
  18. self.code = code
  19. @dataclass(frozen=True)
  20. class _SshFsConfig:
  21. host: str
  22. user: str
  23. port: int
  24. key_path: str
  25. cwd: str
  26. timeout: int
  27. # ``_CACHE_LOCK`` guards only the dicts and is never held across a dial or cleanup, so one
  28. # unreachable host cannot stall file requests on every other SSH profile. A dial or cleanup holds
  29. # its profile's lock plus that endpoint's lock: profiles on one user@host:port share a control
  30. # socket, and one profile's cleanup would otherwise unlink the socket another profile's dial just
  31. # created. At most one endpoint lock is held at a time, always inside the profile's lock.
  32. _CACHE_LOCK = threading.Lock()
  33. _BACKENDS: dict[str, tuple[_SshFsConfig, SshWorkspaceFs]] = {}
  34. _DIAL_LOCKS: dict[str, threading.Lock] = {}
  35. _ENDPOINT_LOCKS: dict[tuple[str, str, int], threading.Lock] = {}
  36. def _lock_for(locks: dict, key) -> threading.Lock:
  37. with _CACHE_LOCK:
  38. return locks.setdefault(key, threading.Lock())
  39. def _endpoint(config: _SshFsConfig) -> tuple[str, str, int]:
  40. """The key ``SSHEnvironment`` derives its control socket from."""
  41. return config.user, config.host, config.port
  42. class SshWorkspaceFs:
  43. """Binary-safe workspace operations using the configured SSH transport."""
  44. def __init__(self, env: SSHEnvironment):
  45. self._env = env
  46. self._lock = threading.RLock()
  47. @property
  48. def cwd(self) -> str:
  49. return self._normalize(self._env.cwd)
  50. def _normalize(self, path: str) -> str:
  51. raw = str(path or "").strip()
  52. if not raw:
  53. raise SshWorkspaceFsError("EINVAL", "Path is required")
  54. if "\0" in raw or raw.lower().startswith("file:"):
  55. raise SshWorkspaceFsError("EINVAL", "Invalid path")
  56. if raw == "~":
  57. raw = self._env._remote_home
  58. elif raw.startswith("~/"):
  59. raw = posixpath.join(self._env._remote_home, raw[2:])
  60. elif not raw.startswith("/"):
  61. raw = posixpath.join(self._env.cwd, raw)
  62. return posixpath.normpath(raw)
  63. def _execute(self, command: str, *, stdin_data: str | None = None, timeout: int | None = None) -> dict:
  64. with self._lock:
  65. return self._env.execute(
  66. command,
  67. cwd=self._env.cwd,
  68. stdin_data=stdin_data,
  69. timeout=timeout or self._env.timeout,
  70. )
  71. @staticmethod
  72. def _error_code(output: str, fallback: str = "EIO") -> str:
  73. marker = "__HERMES_FS_ERROR__:"
  74. for line in (output or "").splitlines():
  75. if line.startswith(marker):
  76. return line[len(marker) :].strip() or fallback
  77. return fallback
  78. def list_dir(self, path: str, hidden_names: set[str] | frozenset[str]) -> dict[str, Any]:
  79. target = self._normalize(path)
  80. quoted = shlex.quote(target)
  81. command = f"""
  82. p={quoted}
  83. if [ ! -e "$p" ] && [ ! -L "$p" ]; then printf '__HERMES_FS_ERROR__:ENOENT\\n'; exit 44; fi
  84. if [ ! -d "$p" ]; then printf '__HERMES_FS_ERROR__:ENOTDIR\\n'; exit 45; fi
  85. if [ ! -r "$p" ]; then printf '__HERMES_FS_ERROR__:EACCES\\n'; exit 46; fi
  86. for child in "$p"/* "$p"/.[!.]* "$p"/..?*; do
  87. [ -e "$child" ] || [ -L "$child" ] || continue
  88. name=${{child##*/}}
  89. name64=$(printf '%s' "$name" | base64 | tr -d '\\r\\n')
  90. path64=$(printf '%s' "$child" | base64 | tr -d '\\r\\n')
  91. if [ -d "$child" ]; then kind=d; else kind=f; fi
  92. printf '%s\\t%s\\t%s\\n' "$name64" "$path64" "$kind"
  93. done
  94. """
  95. result = self._execute(command)
  96. if result.get("returncode") != 0:
  97. return {"entries": [], "error": self._error_code(result.get("output", ""), "read-error")}
  98. entries = []
  99. try:
  100. for line in result.get("output", "").splitlines():
  101. if not line.strip():
  102. continue
  103. name64, path64, kind = line.split("\t", 2)
  104. name = base64.b64decode(name64, validate=True).decode("utf-8", errors="replace")
  105. child_path = base64.b64decode(path64, validate=True).decode("utf-8", errors="replace")
  106. if name in hidden_names:
  107. continue
  108. entries.append({"name": name, "path": child_path, "isDirectory": kind == "d"})
  109. except (ValueError, UnicodeError, binascii.Error) as exc:
  110. raise SshWorkspaceFsError("EIO", "SSH filesystem returned an invalid directory listing") from exc
  111. entries.sort(key=lambda item: (not item["isDirectory"], item["name"].lower(), item["name"]))
  112. return {"entries": entries}
  113. def read_bytes(
  114. self,
  115. path: str,
  116. *,
  117. max_bytes: int,
  118. read_limit: int | None = None,
  119. ) -> tuple[bytes, int, str]:
  120. target = self._normalize(path)
  121. quoted = shlex.quote(target)
  122. read_command = (
  123. f"set -o pipefail; head -c {int(read_limit)} < \"$p\" | base64"
  124. if read_limit is not None
  125. else 'base64 < "$p"'
  126. )
  127. command = f"""
  128. p={quoted}
  129. if [ ! -e "$p" ] && [ ! -L "$p" ]; then printf '__HERMES_FS_ERROR__:ENOENT\\n'; exit 44; fi
  130. if [ ! -f "$p" ]; then printf '__HERMES_FS_ERROR__:ENOTREG\\n'; exit 45; fi
  131. size=$(stat -c %s "$p" 2>/dev/null || stat -f %z "$p" 2>/dev/null) || {{ printf '__HERMES_FS_ERROR__:EACCES\\n'; exit 46; }}
  132. if [ "$size" -gt {int(max_bytes)} ]; then printf '__HERMES_FS_ERROR__:EFBIG\\n'; exit 47; fi
  133. printf '__HERMES_FS_SIZE__:%s\\n' "$size"
  134. {{ {read_command}; }} || {{ printf '__HERMES_FS_ERROR__:EACCES\\n'; exit 46; }}
  135. """
  136. result = self._execute(command)
  137. output = result.get("output", "")
  138. if result.get("returncode") != 0:
  139. raise SshWorkspaceFsError(self._error_code(output))
  140. lines = output.splitlines()
  141. if not lines or not lines[0].startswith("__HERMES_FS_SIZE__:"):
  142. raise SshWorkspaceFsError("EIO", "SSH filesystem did not return a file size")
  143. try:
  144. size = int(lines[0].split(":", 1)[1])
  145. except ValueError as exc:
  146. raise SshWorkspaceFsError("EIO", "SSH filesystem returned an invalid file size") from exc
  147. encoded = "".join(lines[1:])
  148. try:
  149. data = base64.b64decode(encoded, validate=True)
  150. except (ValueError, binascii.Error) as exc:
  151. raise SshWorkspaceFsError("EIO", "SSH filesystem returned invalid file data") from exc
  152. return data, size, target
  153. def inspect_file(self, path: str) -> tuple[str, int]:
  154. """Return a regular file's resolved remote path and size without reading it."""
  155. target = self._normalize(path)
  156. command = f"""
  157. p={shlex.quote(target)}
  158. target=$(realpath "$p" 2>/dev/null || readlink -f "$p" 2>/dev/null) || {{ printf '__HERMES_FS_ERROR__:ENOENT\\n'; exit 44; }}
  159. if [ ! -f "$target" ]; then printf '__HERMES_FS_ERROR__:ENOTREG\\n'; exit 45; fi
  160. size=$(stat -c %s "$target" 2>/dev/null || stat -f %z "$target" 2>/dev/null) || {{ printf '__HERMES_FS_ERROR__:EACCES\\n'; exit 46; }}
  161. printf '__HERMES_FS_TARGET__:%s\\n' "$(printf '%s' "$target" | base64 | tr -d '\\r\\n')"
  162. printf '__HERMES_FS_SIZE__:%s\\n' "$size"
  163. """
  164. result = self._execute(command)
  165. output = result.get("output", "")
  166. if result.get("returncode") != 0:
  167. raise SshWorkspaceFsError(self._error_code(output))
  168. target_line = next((line for line in output.splitlines() if line.startswith("__HERMES_FS_TARGET__:")), "")
  169. size_line = next((line for line in output.splitlines() if line.startswith("__HERMES_FS_SIZE__:")), "")
  170. if not target_line or not size_line:
  171. raise SshWorkspaceFsError("EIO", "SSH filesystem did not return file metadata")
  172. try:
  173. resolved = base64.b64decode(target_line.split(":", 1)[1], validate=True).decode("utf-8", errors="strict")
  174. size = int(size_line.split(":", 1)[1])
  175. except (ValueError, UnicodeError, binascii.Error) as exc:
  176. raise SshWorkspaceFsError("EIO", "SSH filesystem returned invalid file metadata") from exc
  177. return resolved, size
  178. def stream_file(
  179. self, path: str, chunk_size: int = 64 * 1024, *, offset: int = 0, length: int | None = None,
  180. ) -> Iterator[bytes]:
  181. """Stream an already-authorized remote file without buffering it in memory. ``offset`` and
  182. ``length`` read one byte range of it instead (a media element's ``Range`` request)."""
  183. target = self._normalize(path)
  184. source = f"< {shlex.quote(target)}"
  185. if offset or length is not None:
  186. script = f"tail -c +{int(offset) + 1} {source}"
  187. if length is not None:
  188. script += f" | head -c {int(length)}"
  189. else:
  190. script = f"exec cat {source}"
  191. command = self._env._build_ssh_command()
  192. command.extend(["bash", "-c", shlex.quote(script)])
  193. process = subprocess.Popen(
  194. command,
  195. stdin=subprocess.DEVNULL,
  196. stdout=subprocess.PIPE,
  197. stderr=subprocess.DEVNULL,
  198. creationflags=windows_hide_flags(),
  199. )
  200. try:
  201. assert process.stdout is not None
  202. while chunk := process.stdout.read(chunk_size):
  203. yield chunk
  204. finally:
  205. if process.poll() is None:
  206. process.terminate()
  207. process.wait()
  208. def write_text(self, path: str, content: str, *, max_bytes: int) -> tuple[str, int]:
  209. target = self._normalize(path)
  210. encoded_size = len(content.encode("utf-8"))
  211. if encoded_size > max_bytes:
  212. raise SshWorkspaceFsError("EFBIG")
  213. parent = posixpath.dirname(target) or "/"
  214. temp_path = posixpath.join(parent, f".{posixpath.basename(target)}.hermes-tmp-{uuid.uuid4().hex[:12]}")
  215. q_target = shlex.quote(target)
  216. q_parent = shlex.quote(parent)
  217. q_temp = shlex.quote(temp_path)
  218. command = f"""
  219. target={q_target}
  220. parent={q_parent}
  221. tmp={q_temp}
  222. if [ ! -d "$parent" ]; then printf '__HERMES_FS_ERROR__:ENOENT\\n'; exit 44; fi
  223. if [ -e "$target" ] && [ ! -f "$target" ]; then printf '__HERMES_FS_ERROR__:ENOTREG\\n'; exit 45; fi
  224. trap 'rm -f "$tmp"' EXIT HUP INT TERM
  225. cat > "$tmp" && mv -f "$tmp" "$target"
  226. """
  227. result = self._execute(command, stdin_data=content)
  228. if result.get("returncode") != 0 or result.get("stdin_error"):
  229. raise SshWorkspaceFsError(self._error_code(result.get("output", "")))
  230. return target, encoded_size
  231. def git_root(self, path: str) -> str | None:
  232. target = self._normalize(path)
  233. quoted = shlex.quote(target)
  234. command = f"""
  235. p={quoted}
  236. [ -d "$p" ] || p=${{p%/*}}
  237. while [ -n "$p" ]; do
  238. if [ -e "$p/.git" ]; then printf '%s\\n' "$p"; exit 0; fi
  239. [ "$p" = / ] && break
  240. p=${{p%/*}}; [ -n "$p" ] || p=/
  241. done
  242. exit 1
  243. """
  244. result = self._execute(command)
  245. if result.get("returncode") != 0:
  246. return None
  247. return (result.get("output") or "").strip() or None
  248. def git_branch(self, path: str) -> str:
  249. target = self._normalize(path)
  250. result = self._execute(f"git -C {shlex.quote(target)} branch --show-current 2>/dev/null")
  251. return (result.get("output") or "").strip() if result.get("returncode") == 0 else ""
  252. def get_ssh_workspace_fs(profile_key: str, terminal_config: dict[str, Any]) -> SshWorkspaceFs | None:
  253. """Return a cached adapter when this profile selects the SSH backend."""
  254. if str(terminal_config.get("backend") or "local").strip().lower() != "ssh":
  255. return None
  256. config = _SshFsConfig(
  257. host=str(terminal_config.get("ssh_host") or "").strip(),
  258. user=str(terminal_config.get("ssh_user") or "").strip(),
  259. port=int(terminal_config.get("ssh_port") or 22),
  260. key_path=str(terminal_config.get("ssh_key") or "").strip(),
  261. cwd=str(terminal_config.get("cwd") or "~").strip() or "~",
  262. timeout=int(terminal_config.get("timeout") or 180),
  263. )
  264. if not config.host or not config.user:
  265. raise SshWorkspaceFsError("ECONN", "SSH host and user are required")
  266. with _lock_for(_DIAL_LOCKS, profile_key):
  267. with _CACHE_LOCK:
  268. cached = _BACKENDS.get(profile_key)
  269. if cached and cached[0] == config:
  270. return cached[1]
  271. _BACKENDS.pop(profile_key, None)
  272. # Close the replaced connection before dialing: the control socket is keyed on
  273. # user@host:port only, so a dial with new credentials would otherwise ride the old master.
  274. if cached:
  275. with _lock_for(_ENDPOINT_LOCKS, _endpoint(cached[0])):
  276. cached[1]._env.cleanup()
  277. try:
  278. with _lock_for(_ENDPOINT_LOCKS, _endpoint(config)):
  279. env = SSHEnvironment(
  280. host=config.host,
  281. user=config.user,
  282. cwd=config.cwd,
  283. timeout=config.timeout,
  284. port=config.port,
  285. key_path=config.key_path,
  286. sync_files=False,
  287. )
  288. except Exception as exc:
  289. raise SshWorkspaceFsError("ECONN", "Could not connect to the SSH workspace") from exc
  290. backend = SshWorkspaceFs(env)
  291. with _CACHE_LOCK:
  292. _BACKENDS[profile_key] = (config, backend)
  293. return backend