Skip to content

The agent that grows with you

fix(webapp): stream an SSH profile's audio and video from its workspace

unsupportedpastelscb366b0c676e
diff --git a/hermes_cli/ssh_workspace_fs.py b/hermes_cli/ssh_workspace_fs.py
index dff054088e7..0d757ffdb81 100644
--- a/hermes_cli/ssh_workspace_fs.py
+++ b/hermes_cli/ssh_workspace_fs.py
@@ -185,11 +185,21 @@ printf '__HERMES_FS_SIZE__:%s\\n' "$size"
raise SshWorkspaceFsError("EIO", "SSH filesystem returned invalid file metadata") from exc
return resolved, size
- def stream_file(self, path: str, chunk_size: int = 64 * 1024) -> Iterator[bytes]:
- """Stream an already-authorized remote file without buffering it in memory."""
+ def stream_file(
+ self, path: str, chunk_size: int = 64 * 1024, *, offset: int = 0, length: int | None = None,
+ ) -> Iterator[bytes]:
+ """Stream an already-authorized remote file without buffering it in memory. ``offset`` and
+ ``length`` read one byte range of it instead (a media element's ``Range`` request)."""
target = self._normalize(path)
+ source = f"< {shlex.quote(target)}"
+ if offset or length is not None:
+ script = f"tail -c +{int(offset) + 1} {source}"
+ if length is not None:
+ script += f" | head -c {int(length)}"
+ else:
+ script = f"exec cat {source}"
command = self._env._build_ssh_command()
- command.extend(["bash", "-c", shlex.quote(f"exec cat < {shlex.quote(target)}")])
+ command.extend(["bash", "-c", shlex.quote(script)])
process = subprocess.Popen(
command,
stdin=subprocess.DEVNULL,
diff --git a/hermes_cli/web_routers/files.py b/hermes_cli/web_routers/files.py
index fd14558b92a..cf7a4ea3567 100644
--- a/hermes_cli/web_routers/files.py
+++ b/hermes_cli/web_routers/files.py
@@ -33,6 +33,7 @@ from hermes_cli.staged_uploads import (
ensure_profile_subdir, is_staged_upload, removed_on_failure, resolve_upload_home,
)
from hermes_cli.web_deps import late
+from hermes_cli.web_server_remote_media import remote_media_response
from hermes_cli.web_upload_limit import CHAT_IMAGE_MAX_BYTES
from hermes_cli.web_server_surface import route_on
from hermes_cli.web_server_files import (
@@ -776,10 +777,13 @@ async def issue_file_ticket(payload: FileTicketRequest, request: Request):
request, payload.path, payload.profile, payload.session_id, owner,
)
else:
+ # An SSH profile's clip is captured on its SSH machine; a host-staged file on this host.
+ authority = await _remote_file_authority(payload.path, payload.profile, owner, _remote_stream_target)
path = payload.path
- if payload.session_id is not None or path.lower().startswith("file:"):
+ if authority is None and (payload.session_id is not None or path.lower().startswith("file:")):
path = str(await _fs_download_path(path, payload.profile, payload.session_id))
- authority = await asyncio.to_thread(capture)
+ if authority is None:
+ authority = await asyncio.to_thread(capture)
except FileNotFoundError as exc:
raise HTTPException(status_code=404, detail="File ticket profile is unavailable") from exc
query = {"path": payload.path, "profile": payload.profile, "session_id": payload.session_id}
@@ -821,10 +825,19 @@ async def stream_managed_file(
path-bound ``?ticket=``; the session token is never accepted in this URL.
Same size cap, sensitive guard and MIME detection as download. A
``session_id`` resolves ``/workspace`` in that session's own sandbox, as the
- ticket route does."""
- if getattr(request.state, "file_ticket_authority", None) is None and (
- session_id is not None or path.lower().startswith("file:")):
- path = str(await _fs_download_path(path, profile, session_id))
+ ticket route does. An SSH profile's clip streams from its SSH machine
+ (``_remote_fs_backend``, the rule download uses), one Range at a time."""
+ authority = getattr(request.state, "file_ticket_authority", None)
+ if authority is not None and authority.workspace is not None:
+ target, size = await _ticketed_remote_target(authority, _remote_stream_target)
+ return remote_media_response(request, authority.workspace, target, size, _fs_mime_type(Path(target)))
+ if authority is None:
+ backend = await asyncio.to_thread(_remote_fs_backend, path, profile)
+ if backend is not None:
+ target, size = await asyncio.to_thread(_remote_stream_target, backend, path)
+ return remote_media_response(request, backend, target, size, _fs_mime_type(Path(target)))
+ if session_id is not None or path.lower().startswith("file:"):
+ path = str(await _fs_download_path(path, profile, session_id))
return await _managed_file_response(request, path, content_disposition_type="inline", media_only=True)
@@ -1176,6 +1189,45 @@ def _remote_download_target(backend, path: str) -> tuple[str, int]:
return target, size
+def _remote_stream_target(backend, path: str) -> tuple[str, int]:
+ """*path* on the SSH workspace as media the stream route may serve, and its size: download's
+ checks, then the host stream's media-type and size caps."""
+ from hermes_cli.web_server import _MANAGED_FILE_MAX_BYTES
+
+ target, size = _remote_download_target(backend, path)
+ if PurePosixPath(target).suffix.lower() not in _STREAMABLE_MEDIA_EXTENSIONS:
+ raise HTTPException(status_code=415, detail="Unsupported media type")
+ if size > _MANAGED_FILE_MAX_BYTES:
+ raise HTTPException(status_code=413, detail="File is too large")
+ return target, size
+
+
+async def _remote_file_authority(
+ path: str, profile: Optional[str], owner: Path, inspect,
+) -> Optional[file_tickets.FileAuthority]:
+ """A ticket's authority for *path* on the profile's SSH workspace, checked by *inspect*
+ (download's or the stream's rules), or None when this host owns the path."""
+ backend = await asyncio.to_thread(_remote_fs_backend, path, profile)
+ if backend is None:
+ return None
+ target, _size = await asyncio.to_thread(inspect, backend, path)
+ authority = file_tickets.FileAuthority(PurePosixPath(target), (owner,), workspace=backend)
+ await asyncio.to_thread(authority.check_live)
+ return authority
+
+
+async def _ticketed_remote_target(authority: file_tickets.FileAuthority, inspect) -> tuple[str, int]:
+ """The SSH file a ticket captured, re-checked by *inspect* while its profile is still live."""
+ try:
+ await asyncio.to_thread(authority.check_live)
+ except FileNotFoundError as exc:
+ raise HTTPException(status_code=404, detail="File ticket profile or resource is unavailable") from exc
+ target, size = await asyncio.to_thread(inspect, authority.workspace, str(authority.target))
+ if target != str(authority.target):
+ raise HTTPException(status_code=403, detail="File ticket target changed")
+ return target, size
+
+
def _remote_download_response(request: Optional[Request], backend, target: str, size: int) -> Response:
"""*target* streamed from the SSH workspace as an attachment; a HEAD reads none of it."""
target_path = Path(target)
@@ -1194,12 +1246,9 @@ async def _fs_download_authority(
profile's SSH workspace when it has one, else on this host under the same read rules."""
from hermes_constants import named_profile_home
- backend = await asyncio.to_thread(_remote_fs_backend, path, profile)
- if backend is not None:
- target, _size = await asyncio.to_thread(_remote_download_target, backend, path)
- authority = file_tickets.FileAuthority(PurePosixPath(target), (owner,), workspace=backend)
- await asyncio.to_thread(authority.check_live)
- return authority
+ remote = await _remote_file_authority(path, profile, owner, _remote_download_target)
+ if remote is not None:
+ return remote
local = await _fs_download_path(path, profile, session_id)
def capture():
@@ -1221,13 +1270,7 @@ async def _ticketed_fs_download(
) -> Response:
"""Serve the file a download ticket captured while its profile homes are still live."""
if authority.workspace is not None:
- try:
- await asyncio.to_thread(authority.check_live)
- except FileNotFoundError as exc:
- raise HTTPException(status_code=404, detail="File ticket profile or resource is unavailable") from exc
- target, size = await asyncio.to_thread(_remote_download_target, authority.workspace, str(authority.target))
- if target != str(authority.target):
- raise HTTPException(status_code=403, detail="File ticket target changed")
+ target, size = await _ticketed_remote_target(authority, _remote_download_target)
return _remote_download_response(request, authority.workspace, target, size)
from hermes_cli.web_server_file_response import OpenedFileResponse
diff --git a/hermes_cli/web_server_remote_media.py b/hermes_cli/web_server_remote_media.py
new file mode 100644
index 00000000000..093d91d50db
--- /dev/null
+++ b/hermes_cli/web_server_remote_media.py
@@ -0,0 +1,68 @@
+"""Inline audio/video from a profile's SSH workspace for ``/api/files/stream``.
+
+A host file streams through Starlette's ``FileResponse``, which answers ``Range`` itself. A file on
+the SSH machine has no local handle, so this answers the one byte range a media element asks for
+by reading exactly that slice through the workspace adapter (``SshWorkspaceFs.stream_file``).
+The caller has already chosen the backend and checked the file (sensitive path, media type, size).
+"""
+
+from __future__ import annotations
+
+import re
+import urllib.parse
+from pathlib import PurePosixPath
+from typing import Any
+
+from fastapi import HTTPException, Request
+from fastapi.responses import Response, StreamingResponse
+
+_SINGLE_RANGE = re.compile(r"^\s*bytes\s*=\s*(\d*)\s*-\s*(\d*)\s*$", re.IGNORECASE)
+
+
+def _unsatisfiable(size: int) -> HTTPException:
+ return HTTPException(
+ status_code=416, detail="Requested range not satisfiable", headers={"Content-Range": f"bytes */{size}"},
+ )
+
+
+def byte_range(header: str | None, size: int) -> tuple[int, int] | None:
+ """The inclusive ``(first, last)`` byte span one ``bytes=`` range asks of a *size*-byte file,
+ or None to serve the whole file. A header this does not read (several ranges, another unit, a
+ last byte before the first) is ignored, as RFC 9110 allows; a range the file cannot satisfy
+ raises 416."""
+ match = _SINGLE_RANGE.match(header or "")
+ if match is None or match.groups() == ("", ""):
+ return None
+ first, last = match.groups()
+ if not first: # a suffix: the last N bytes
+ if int(last) == 0 or size == 0:
+ raise _unsatisfiable(size)
+ return max(size - int(last), 0), size - 1
+ if last and int(last) < int(first):
+ return None
+ if int(first) >= size:
+ raise _unsatisfiable(size)
+ return int(first), min(int(last), size - 1) if last else size - 1
+
+
+def remote_media_response(request: Request, workspace: Any, target: str, size: int, media_type: str) -> Response:
+ """*target* on the SSH *workspace* as inline media: 200 for the whole file, 206 for the range
+ the request asks, 416 for one it cannot have. A HEAD reads none of it."""
+ span = byte_range(request.headers.get("range"), size)
+ first, last = span if span is not None else (0, size - 1)
+ length = max(last - first + 1, 0)
+ name = urllib.parse.quote(PurePosixPath(target).name)
+ headers = {
+ "Accept-Ranges": "bytes",
+ "Content-Disposition": f"inline; filename*=UTF-8''{name}",
+ "Content-Length": str(length),
+ "X-Content-Type-Options": "nosniff",
+ }
+ status = 200
+ if span is not None:
+ status = 206
+ headers["Content-Range"] = f"bytes {first}-{last}/{size}"
+ if request.method == "HEAD" or length == 0:
+ return Response(status_code=status, media_type=media_type, headers=headers)
+ body = workspace.stream_file(target, offset=first, length=length) if span else workspace.stream_file(target)
+ return StreamingResponse(body, status_code=status, media_type=media_type, headers=headers)
diff --git a/tests/hermes_cli/test_web_server_ssh_media_stream.py b/tests/hermes_cli/test_web_server_ssh_media_stream.py
new file mode 100644
index 00000000000..7f6e3a8b0c5
--- /dev/null
+++ b/tests/hermes_cli/test_web_server_ssh_media_stream.py
@@ -0,0 +1,249 @@
+"""WA-5 part 4: an SSH profile's audio/video streams from the SSH workspace with HTTP Range, behind
+the same ticket, profile and file checks as the host path. Fake SSH adapters only."""
+
+import shlex
+from pathlib import Path
+
+import pytest
+
+from hermes_cli import ssh_workspace_fs, web_server
+from hermes_cli.web_routers import files as file_routes
+
+pytest.importorskip("starlette.testclient")
+from starlette.testclient import TestClient
+
+CLIP = "/srv/media/clip one.mp4"
+BYTES = b"0123456789abcdef"
+UNAVAILABLE = (503, {"detail": "SSH workspace is unavailable"})
+
+
+class FakeSshWorkspace:
+ """The SSH machine: a few files, one link, and a record of every byte range read."""
+
+ def __init__(self):
+ self.files = {CLIP: BYTES, "/srv/media/notes.txt": b"notes"}
+ self.links = {"/srv/media/linked.mp4": "/home/dev/.hermes/mcp-tokens/token.mp4"}
+ self.reads = []
+
+ def inspect_file(self, path):
+ target = self.links.get(path, path)
+ if target not in self.files and target not in self.links.values():
+ raise ssh_workspace_fs.SshWorkspaceFsError("ENOENT", f"{path} is not on the SSH machine")
+ return target, len(self.files.get(target, b"secret"))
+
+ def stream_file(self, path, chunk_size=64 * 1024, *, offset=0, length=None):
+ self.reads.append((path, offset, length))
+ data = self.files[path][offset:None if length is None else offset + length]
+ yield data[:3]
+ yield data[3:]
+
+
+def client():
+ previous = getattr(web_server.app.state, "auth_required", None)
+ web_server.app.state.auth_required = False
+ test_client = TestClient(web_server.app)
+ test_client.headers[web_server._SESSION_HEADER_NAME] = web_server._SESSION_TOKEN
+ try:
+ yield test_client
+ finally:
+ test_client.close()
+ if previous is None:
+ if hasattr(web_server.app.state, "auth_required"):
+ delattr(web_server.app.state, "auth_required")
+ else:
+ web_server.app.state.auth_required = previous
+
+
+def ssh(monkeypatch, tmp_path):
+ """A default profile on this host and a ``remote-dev`` profile whose workspace is the fake
+ SSH machine; the browser's ticket routes are on (the Webapp)."""
+ home = tmp_path / ".hermes"
+ profile = home / "profiles" / "remote-dev"
+ profile.mkdir(parents=True)
+ (profile / "config.yaml").write_text("{}", encoding="utf-8")
+ monkeypatch.setattr(Path, "home", lambda: tmp_path)
+ monkeypatch.setenv("HERMES_HOME", str(home))
+ monkeypatch.delenv("HERMES_DASHBOARD_FILES_ROOT", raising=False)
+ monkeypatch.setattr(web_server.app.state, "ui_surface", "webapp", raising=False)
+ workspace = FakeSshWorkspace()
+ monkeypatch.setattr(
+ file_routes, "_fs_backend", lambda profile=None: workspace if profile == "remote-dev" else None,
+ )
+ return profile, workspace
+
+
+def _stream(client, *, headers=None, method="GET", **params):
+ return client.request(method, "/api/files/stream", params={"path": CLIP, "profile": "remote-dev", **params},
+ headers=headers or {})
+
+
+def test_ssh_stream_serves_the_whole_clip_inline(client, ssh):
+ _profile, workspace = ssh
+
+ full = _stream(client)
+ head = _stream(client, method="HEAD")
+
+ assert (full.status_code, full.content) == (200, BYTES)
+ assert full.headers["content-type"] == "video/mp4"
+ assert full.headers["content-length"] == str(len(BYTES))
+ assert full.headers["accept-ranges"] == "bytes"
+ assert full.headers["content-disposition"].startswith("inline;")
+ assert full.headers["x-content-type-options"] == "nosniff"
+ assert (head.status_code, head.content, head.headers["content-length"]) == (200, b"", str(len(BYTES)))
+ assert workspace.reads == [(CLIP, 0, None)] # the HEAD read nothing
+
+
[email protected](("header", "first", "last"), [
+ ("bytes=2-5", 2, 5),
+ ("bytes=10-", 10, 15),
+ ("bytes=-4", 12, 15),
+ ("bytes=14-99", 14, 15),
+])
+def test_ssh_stream_answers_a_range_with_206(client, ssh, header, first, last):
+ _profile, workspace = ssh
+
+ partial = _stream(client, headers={"Range": header})
+
+ assert (partial.status_code, partial.content) == (206, BYTES[first:last + 1])
+ assert partial.headers["content-range"] == f"bytes {first}-{last}/{len(BYTES)}"
+ assert partial.headers["content-length"] == str(last - first + 1)
+ assert partial.headers["accept-ranges"] == "bytes"
+ assert workspace.reads == [(CLIP, first, last - first + 1)]
+
+
[email protected]("header", ["bytes=16-", "bytes=99-120", "bytes=-0"])
+def test_ssh_stream_answers_an_unsatisfiable_range_with_416(client, ssh, header):
+ _profile, workspace = ssh
+
+ response = _stream(client, headers={"Range": header})
+
+ assert response.status_code == 416
+ assert response.headers["content-range"] == f"bytes */{len(BYTES)}"
+ assert workspace.reads == []
+
+
[email protected](("path", "status"), [
+ ("/srv/media/linked.mp4", 403), # resolves into a credential folder on the SSH machine
+ ("/srv/media/notes.txt", 415),
+ ("/srv/media/missing.mp4", 404),
+])
+def test_ssh_stream_refuses_a_file_download_or_media_rules_refuse(client, ssh, path, status):
+ _profile, workspace = ssh
+
+ direct = _stream(client, path=path)
+ minted = client.post("/api/files/ticket", json={"route": "stream", "path": path, "profile": "remote-dev"})
+
+ assert direct.status_code == status, direct.text
+ assert minted.status_code == status, minted.text
+ assert workspace.reads == []
+
+
+def test_an_ssh_stream_ticket_plays_ranges_and_only_its_own_profile_and_path(client, ssh):
+ from hermes_constants import mark_named_profile_deleted
+
+ profile, workspace = ssh
+ query = {"path": CLIP, "profile": "remote-dev"}
+ minted = client.post("/api/files/ticket", json={"route": "stream", **query})
+ assert minted.status_code == 200, minted.text
+ ticket = minted.json()["ticket"]
+ player = TestClient(web_server.app) # a media element sends no session header
+ try:
+ for _ in range(2): # a stream ticket serves every Range request of one source
+ partial = player.get("/api/files/stream", params={**query, "ticket": ticket},
+ headers={"Range": "bytes=1-3"})
+ assert (partial.status_code, partial.content) == (206, BYTES[1:4])
+ for foreign in (
+ {**query, "profile": "default"},
+ {"path": CLIP},
+ {**query, "path": "/srv/media/other.mp4"},
+ ):
+ assert player.get("/api/files/stream", params={**foreign, "ticket": ticket}).status_code == 401, foreign
+ # The default profile's own ticket names no SSH workspace: this host has no such clip.
+ assert client.post("/api/files/ticket", json={"route": "stream", "path": CLIP}).status_code == 404
+
+ mark_named_profile_deleted(profile)
+ gone = player.get("/api/files/stream", params={**query, "ticket": ticket})
+ assert gone.status_code in (401, 403, 404), gone.text
+ assert workspace.reads == [(CLIP, 1, 3), (CLIP, 1, 3)]
+ finally:
+ player.close()
+
+
+def test_a_host_staged_clip_of_an_ssh_profile_streams_from_this_host(client, ssh):
+ _profile, workspace = ssh
+ staged = client.post("/api/chat/file-upload", params={"profile": "remote-dev"},
+ files={"file": ("clip.mp4", b"host clip", "video/mp4")})
+ assert staged.status_code == 200, staged.text
+ query = {"path": staged.json()["path"], "profile": "remote-dev"}
+
+ direct = client.get("/api/files/stream", params=query, headers={"Range": "bytes=0-3"})
+ minted = client.post("/api/files/ticket", json={"route": "stream", **query})
+ assert minted.status_code == 200, minted.text
+ del client.headers[web_server._SESSION_HEADER_NAME]
+ ticketed = client.get("/api/files/stream", params={**query, "ticket": minted.json()["ticket"]})
+
+ assert (direct.status_code, direct.content) == (206, b"host")
+ assert (ticketed.status_code, ticketed.content) == (200, b"host clip")
+ assert workspace.reads == []
+
+
+def test_a_down_ssh_host_is_unavailable_to_the_stream(client, ssh, monkeypatch):
+ from tools.environments.base import EnvironmentConnectionError
+
+ class DownHost:
+ def __init__(self, **_options):
+ raise EnvironmentConnectionError("SSH connection failed: Connection refused")
+
+ monkeypatch.undo()
+ monkeypatch.setattr(web_server.app.state, "ui_surface", "webapp", raising=False)
+ monkeypatch.setattr(ssh_workspace_fs, "SSHEnvironment", DownHost)
+ monkeypatch.setattr(ssh_workspace_fs, "_BACKENDS", {})
+ monkeypatch.setattr(
+ file_routes, "load_config",
+ lambda: {"terminal": {"backend": "ssh", "ssh_host": "127.0.0.1", "ssh_user": "dev", "ssh_port": 1}},
+ )
+ monkeypatch.setattr(file_routes, "load_env", dict)
+
+ direct = client.get("/api/files/stream", params={"path": CLIP}, headers={"Range": "bytes=0-3"})
+ minted = client.post("/api/files/ticket", json={"route": "stream", "path": CLIP})
+
+ assert (direct.status_code, direct.json()) == UNAVAILABLE
+ assert (minted.status_code, minted.json()) == UNAVAILABLE
+
+
+def test_the_adapter_reads_one_range_with_the_path_quoted(monkeypatch):
+ """The SSH command reads exactly the asked bytes, and a hostile file name stays one word."""
+ launched = []
+
+ class Process:
+ def __init__(self, command, **_options):
+ launched.append(command)
+ import io
+
+ self.stdout = io.BytesIO(b"slice")
+
+ def poll(self):
+ return 0
+
+ def wait(self):
+ return 0
+
+ class Env:
+ cwd, _remote_home = "/srv", "/home/dev"
+
+ def _build_ssh_command(self):
+ return ["ssh", "dev@host"]
+
+ monkeypatch.setattr(ssh_workspace_fs.subprocess, "Popen", Process)
+ adapter = ssh_workspace_fs.SshWorkspaceFs(Env())
+ hostile = "/srv/media/a b $(touch pwned) ';x'.mp4"
+
+ assert b"".join(adapter.stream_file(hostile, offset=10, length=4)) == b"slice"
+ assert b"".join(adapter.stream_file(hostile)) == b"slice"
+
+ ranged, whole = (shlex.split(command[-1])[0] for command in launched)
+ assert launched[0][:4] == ["ssh", "dev@host", "bash", "-c"]
+ assert shlex.split(ranged) == ["tail", "-c", "+11", "<", hostile, "|", "head", "-c", "4"]
+ assert shlex.split(whole) == ["exec", "cat", "<", hostile]