agentenv-framework-protocol 0.1.448__tar.gz → 0.1.449__tar.gz

{agentenv_framework_protocol-0.1.448 → agentenv_framework_protocol-0.1.449}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.448
+Version: 0.1.449
 Summary: Open data-plane protocol and server SDK for agent environments.
 Project-URL: Homepage, https://www.agentenvframework.com
 Project-URL: Documentation, https://www.agentenvframework.com/docs
@@ -42,6 +42,7 @@ Requires-Dist: av>=17; extra == 'computer'
 Requires-Dist: mcp<2,>=1.25; extra == 'computer'
 Requires-Dist: pillow>=10.4; extra == 'computer'
 Requires-Dist: uvicorn>=0.30; extra == 'computer'
+Requires-Dist: websockets>=13; extra == 'computer'
 Provides-Extra: dev
 Requires-Dist: a2a-sdk[http-server]<0.4,>=0.3.26; extra == 'dev'
 Requires-Dist: av>=17; extra == 'dev'
@@ -52,6 +53,7 @@ Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest>=9.0; extra == 'dev'
 Requires-Dist: python-multipart>=0.0.13; extra == 'dev'
 Requires-Dist: regex>=2023.12.25; extra == 'dev'
+Requires-Dist: websockets>=13; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # agentenv-framework-protocol
@@ -826,7 +828,16 @@ launches one at a time, runs a load and a reset with the app stopped and relaunc
 follows a failed load with a reset, and fails a call that runs past `data_timeout_s` (300 s); a sync
 hook runs in a thread, which the reset and relaunch after it wait for. The driver fronts its apps:
 its card lists each one's card as a child environment, rooted at `/svc/<app>/`, where it forwards
-requests to the app's server.
+requests to the app's server, taking the control token:
+
+- every method, its body and the answer's streamed both ways, so a large answer isn't held whole;
+- headers passed on but the hop-by-hop ones, those a `Connection` header names and the control token's
+  `Authorization`; `Host` as the caller sent it, and in place of any address the caller forwarded,
+  the one it reached the driver at: `X-Forwarded-Host`, `X-Forwarded-Proto` and `X-Forwarded-Prefix`
+  (`/svc/<app>`), as the gateway sets them;
+- WebSockets, relayed to the app's server both ways with the subprotocol it picks until either side
+  closes, the other then closed with its code; refused before they open without the token, or with no
+  such app or one not answering. The `computer` extra brings `websockets` for this.
 
 `MailApp.declaration()` returns what the class declares, an `AppDeclaration`, which a `computer_app`
 env stores (`browser: true` for a website browser), and `python -m agentenv_protocol.computer._declare <folder> <file> <class>` prints it as

{agentenv_framework_protocol-0.1.448 → agentenv_framework_protocol-0.1.449}/README.md

@@ -770,7 +770,16 @@ launches one at a time, runs a load and a reset with the app stopped and relaunc
 follows a failed load with a reset, and fails a call that runs past `data_timeout_s` (300 s); a sync
 hook runs in a thread, which the reset and relaunch after it wait for. The driver fronts its apps:
 its card lists each one's card as a child environment, rooted at `/svc/<app>/`, where it forwards
-requests to the app's server.
+requests to the app's server, taking the control token:
+
+- every method, its body and the answer's streamed both ways, so a large answer isn't held whole;
+- headers passed on but the hop-by-hop ones, those a `Connection` header names and the control token's
+  `Authorization`; `Host` as the caller sent it, and in place of any address the caller forwarded,
+  the one it reached the driver at: `X-Forwarded-Host`, `X-Forwarded-Proto` and `X-Forwarded-Prefix`
+  (`/svc/<app>`), as the gateway sets them;
+- WebSockets, relayed to the app's server both ways with the subprotocol it picks until either side
+  closes, the other then closed with its code; refused before they open without the token, or with no
+  such app or one not answering. The `computer` extra brings `websockets` for this.
 
 `MailApp.declaration()` returns what the class declares, an `AppDeclaration`, which a `computer_app`
 env stores (`browser: true` for a website browser), and `python -m agentenv_protocol.computer._declare <folder> <file> <class>` prints it as

{agentenv_framework_protocol-0.1.448 → agentenv_framework_protocol-0.1.449}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentenv-framework-protocol"
-version = "0.1.448"
+version = "0.1.449"
 description = "Open data-plane protocol and server SDK for agent environments."
 readme = "README.md"
 license = "Apache-2.0"
@@ -41,13 +41,14 @@ app = [
     "mcp>=1.25,<2",
     "uvicorn>=0.30",
 ]
-# A computer driver: ComputerDriverEnvironment serves its tools over mcp's FastMCP, crops and encodes frames, and
-# records the display as H.264 with PyAV (computer-recording/v1).
+# A computer driver: ComputerDriverEnvironment serves its tools over mcp's FastMCP, crops and encodes frames, records
+# the display as H.264 with PyAV (computer-recording/v1), and relays WebSockets to its apps on /svc/<app>/.
 computer = [
     "av>=17",
     "mcp>=1.25,<2",
     "Pillow>=10.4",
     "uvicorn>=0.30",
+    "websockets>=13",
 ]
 dev = [
     "a2a-sdk[http-server]>=0.3.26,<0.4",
@@ -59,6 +60,7 @@ dev = [
     "fastmcp>=3.4,<4",  # the standalone-fastmcp mount path
     "Pillow>=10.4",  # the computer extra's frame crops and encodings
     "av>=17",  # the computer extra's encoder, and the tests' decoder
+    "websockets>=13",  # the computer extra's /svc/<app>/ relay
 ]
 [project.urls]
 Homepage = "https://www.agentenvframework.com"

{agentenv_framework_protocol-0.1.448 → agentenv_framework_protocol-0.1.449}/src/agentenv_protocol/agent_env_environment.py

@@ -1546,18 +1546,27 @@ def _error_response(error: AgentEnvError) -> Response:
     return _json_response(error_body(**error.fields()), error.status)
 
 
+def control_check() -> Callable[[Any], bool]:
+    """Whether a call's headers carry the env's control token as their bearer, with ``CONTROL_TOKEN_ENV`` set; without
+    it, any do."""
+    token = os.environ.get(CONTROL_TOKEN_ENV)
+    if not token:
+        return lambda headers: True
+    expected = f"Bearer {token}".encode()
+    return lambda headers: hmac.compare_digest(headers.get("authorization", "").encode(), expected)
+
+
 def control_guard() -> Callable[[Callable], Callable]:
     """What wraps a framework-only route, everything an env serves but its MCP endpoint and its card: with
     ``CONTROL_TOKEN_ENV`` set, a call that doesn't carry that token as its bearer is refused before the route runs;
     without it, nothing."""
-    token = os.environ.get(CONTROL_TOKEN_ENV)
-    if not token:
+    if not os.environ.get(CONTROL_TOKEN_ENV):
         return lambda handler: handler
-    expected = f"Bearer {token}".encode()
+    allowed = control_check()
 
     def guard(handler: Callable) -> Callable:
         async def guarded(request: Request) -> Response:
-            if not hmac.compare_digest(request.headers.get("authorization", "").encode(), expected):
+            if not allowed(request.headers):
                 return _error_response(AgentEnvError(
                     "unauthorized", "this route is agent-env's own: it takes the env's control token", status=401))
             return await handler(request)

{agentenv_framework_protocol-0.1.448 → agentenv_framework_protocol-0.1.449}/src/agentenv_protocol/computer/apps.py

@@ -3,7 +3,7 @@ Each app's own server answers on its folder's socket (``serve_app``): its card s
 paths it owns, and its ``computer-app/v1`` ``ready`` whether it's ready. Every app's server must answer before the
 computer is ready; an app that starts with the computer must also be ready, and a ``demand`` app is checked once
 something launches it. The driver lists each app as a child environment named for its folder, its card's paths under
-``/svc/<name>/``, and forwards each request there to the app's server."""
+``/svc/<name>/``, where it forwards each request to the app's server (``svc``)."""
 from __future__ import annotations
 
 import asyncio
@@ -91,15 +91,6 @@ async def owned_paths(folders: list[Path]) -> list[str]:
             for path in client.extension_params(card, COMPUTER_APP).get("paths") or []]
 
 
-async def forward(folder: Path, method: str, path: str, query: str, body: bytes,
-                  content_type: Optional[str]) -> httpx.Response:
-    """The app's server's answer to the request, sent on as it came; it takes as long as the app does."""
-    async with httpx.AsyncClient(transport=httpx.AsyncHTTPTransport(uds=str(folder / SOCKET)), base_url="http://app",
-                                 timeout=None) as http:
-        return await http.request(method, f"/{path}" + (f"?{query}" if query else ""), content=body,
-                                  headers={"content-type": content_type} if content_type else None)
-
-
 def endpoint(card: dict, method: str) -> str:
     """The path of a ``computer-app/v1`` method, as the app's card advertises it."""
     return client.find_extension_method(card, COMPUTER_APP, method)["endpoint"]

{agentenv_framework_protocol-0.1.448 → agentenv_framework_protocol-0.1.449}/src/agentenv_protocol/computer/driver.py

@@ -4,21 +4,22 @@ computer's apps as child environments, each reached at ``/svc/<name>/`` through
 from __future__ import annotations
 
 import asyncio
-from typing import Any, Callable, ClassVar, Literal
+from pathlib import Path
+from typing import Any, Callable, ClassVar, Literal, Optional
 
-import httpx
 from pydantic import BaseModel, ConfigDict
 from starlette.requests import Request
 from starlette.responses import Response
+from starlette.websockets import WebSocket
 
 from ..agent_env_environment import (_CARD_CONFIG_ATTR, AgentEnvEnvironment, AgentEnvFastMCPApplication,
                                      _error_response, control_guard, environment_card)
 from ..tool_context import ToolContext
 from ..types import EnvironmentCard, EnvironmentExtension, EnvironmentTool
-from . import _linux, apps, card
+from . import _linux, apps, card, svc
 from .checks import check_features, check_names
 from .dataplane import DataPlane
-from .errors import DeliveryFailed, TargetUnavailable
+from .errors import TargetUnavailable
 from .extensions import Extensions
 from .operations import ReadyCheck, check_class, default_for
 from .platform import Platform, detect
@@ -138,21 +139,28 @@ class ComputerDriverEnvironment(Tools, Extensions, DataPlane, AgentEnvEnvironmen
         return await apps.children(self._computer.apps) if self._computer.apps else None
 
     def _computer_front_apps(self, app: Any) -> Any:
-        app.custom_route("/svc/{name}/{path:path}", methods=["GET", "POST"])(control_guard()(self._computer_forward))
+        app.custom_route("/svc/{name}/{path:path}", methods=svc.METHODS)(control_guard()(self._computer_forward))
+        svc.websocket_route(app, "/svc/{name}/{path:path}", self._computer_relay)
         return app
 
+    def _computer_app_folder(self, name: str) -> Optional[Path]:
+        return next((folder for folder in self._computer.apps if folder.name == name), None)
+
     async def _computer_forward(self, request: Request) -> Response:
         """A request under ``/svc/<name>/``, sent on to the app named so: its own server answers it."""
         name = request.path_params["name"]
-        folder = next((folder for folder in self._computer.apps if folder.name == name), None)
-        if folder is None:
+        if (folder := self._computer_app_folder(name)) is None:
             return _error_response(TargetUnavailable(f"this computer has no app named {name!r}"))
-        try:
-            answer = await apps.forward(folder, request.method, request.path_params["path"], request.url.query,
-                                        await request.body(), request.headers.get("content-type"))
-        except (httpx.HTTPError, OSError) as e:
-            return _error_response(DeliveryFailed(f"app {name}'s server isn't answering: {type(e).__name__}: {e}"))
-        return Response(answer.content, status_code=answer.status_code, media_type=answer.headers.get("content-type"))
+        return await svc.forward(folder, name, request)
+
+    async def _computer_relay(self, websocket: WebSocket) -> None:
+        """A WebSocket under ``/svc/<name>/``, relayed both ways to the app named so; refused, before it opens, with no
+        such app."""
+        name = websocket.path_params["name"]
+        if (folder := self._computer_app_folder(name)) is None:
+            await websocket.close(code=1008)
+            return
+        await svc.relay(folder, name, websocket)
 
     # The card: what the driver's operations support.
 

agentenv_framework_protocol-0.1.449/src/agentenv_protocol/computer/svc.py

@@ -0,0 +1,182 @@
+"""The driver's ``/svc/<name>/`` route to each app on its computer: a request sent on to the app's server with its body
+and its answer streamed, and a WebSocket relayed to it both ways. It needs the ``computer`` extra's ``websockets``, so
+only the driver imports it; an app's venv, with the ``app`` extra, imports ``apps`` and never this."""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import re
+from collections.abc import AsyncIterator, Iterable
+from pathlib import Path
+from typing import Any, Callable
+from urllib.parse import quote, unquote
+
+import httpx
+import websockets
+from starlette.background import BackgroundTask
+from starlette.requests import Request
+from starlette.responses import Response, StreamingResponse
+from starlette.routing import WebSocketRoute
+from starlette.websockets import WebSocket, WebSocketDisconnect
+from websockets.asyncio.client import ClientConnection, unix_connect
+
+from ..agent_env_environment import _error_response, control_check
+from .app import SOCKET
+from .errors import DeliveryFailed
+
+#: The methods the route forwards.
+METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
+#: The headers that belong to one connection, which a proxy doesn't pass on.
+HOP_HEADERS = frozenset({"connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "proxy-connection",
+                         "te", "trailer", "transfer-encoding", "upgrade"})
+#: The address a request reached the driver at, which the driver sets for the app in place of any the caller sent.
+FORWARDED = ("x-forwarded-host", "x-forwarded-proto", "x-forwarded-prefix")
+#: A WebSocket close code that means the connection ended without one, which a close can't send on.
+UNSENDABLE_CLOSES = (1005, 1006, 1015)
+#: A Host header that names a host, and its port or not, and nothing else.
+HOST = re.compile(r"(?:[A-Za-z0-9.-]+|\[[0-9A-Fa-f:.]+\])(?::[0-9]{1,5})?")
+#: What a path's segments may hold unescaped, besides letters, digits and ``_.-~``.
+PATH_SAFE = "/:@!$&'()*+,;="
+
+
+def passed_on(headers: Iterable[tuple[str, str]], *dropped: str) -> list[tuple[str, str]]:
+    """``headers`` as a proxy passes them on: without the hop-by-hop ones, those a ``Connection`` header names, and
+    ``dropped``."""
+    headers = list(headers)
+    named = {token.strip().lower() for name, value in headers if name.lower() == "connection"
+             for token in value.split(",")}
+    skipped = HOP_HEADERS | named | set(dropped)
+    return [(name, value) for name, value in headers if name.lower() not in skipped]
+
+
+def to_app(headers: Iterable[tuple[str, str]], host: str, scheme: str, prefix: str) -> list[tuple[str, str]]:
+    """A caller's headers as the app gets them: passed on without the control token's ``Authorization`` or any address
+    the caller forwarded, and with the one it reached the driver at, its ``host``, ``scheme`` and the app's
+    ``prefix``."""
+    return passed_on(headers, "authorization", *FORWARDED) + [
+        ("x-forwarded-host", host), ("x-forwarded-proto", scheme), ("x-forwarded-prefix", prefix)]
+
+
+def target(connection: Request | WebSocket) -> str:
+    """The path and query a request under ``/svc/<name>/`` asks its app for, as it came: still percent-encoded, so an
+    escaped ``?``, ``#`` or ``/`` stays one. The raw path's segments past any the driver is mounted under must be
+    ``svc`` and the app's name, else the routed path is escaped again."""
+    mounted = len([segment for segment in connection.scope.get("root_path", "").split("/") if segment])
+    parts = (connection.scope.get("raw_path") or b"").decode("latin-1").split("/")[1 + mounted:]
+    if len(parts) > 2 and [unquote(part) for part in parts[:2]] == ["svc", connection.path_params["name"]]:
+        tail = "/".join(parts[2:])
+    else:
+        tail = quote(connection.path_params["path"], safe=PATH_SAFE)
+    query = connection.scope.get("query_string", b"").decode("latin-1")
+    return f"/{tail}" + (f"?{query}" if query else "")
+
+
+def _bytes(headers: Iterable[tuple[str, str]]) -> list[tuple[bytes, bytes]]:
+    """Headers decoded as Latin-1, as Starlette and the helpers here hold them, as the bytes they came as."""
+    return [(name.encode("latin-1"), value.encode("latin-1")) for name, value in headers]
+
+
+def websocket_route(app: Any, path: str, endpoint: Callable) -> None:
+    """``endpoint`` served at ``path`` as a WebSocket route of ``app``, an mcp or a standalone fastmcp FastMCP, which
+    have no API for one."""
+    for routes in ("_custom_starlette_routes", "_additional_http_routes"):
+        if isinstance(getattr(app, routes, None), list):
+            getattr(app, routes).append(WebSocketRoute(path, endpoint))
+            return
+    raise TypeError(f"a driver's app takes WebSocket routes on an mcp or a fastmcp FastMCP, not a {type(app).__name__}")
+
+
+async def forward(folder: Path, name: str, request: Request) -> Response:
+    """``request`` sent on to the app ``name``'s server in ``folder`` with the caller's headers and none of the
+    client's own, its body and its answer streamed; it takes as long as the app does."""
+    headers = to_app(request.headers.items(), request.headers.get("host", ""), request.url.scheme, f"/svc/{name}")
+    has_body = request.headers.get("content-length", "0") != "0" or "transfer-encoding" in request.headers
+    http = httpx.AsyncClient(transport=httpx.AsyncHTTPTransport(uds=str(folder / SOCKET)), base_url="http://app",
+                             timeout=None)
+    http.headers.clear()
+    try:
+        answer = await http.send(http.build_request(request.method, target(request), headers=_bytes(headers),
+                                                    content=request.stream() if has_body else None), stream=True)
+    except (httpx.HTTPError, OSError) as e:
+        await http.aclose()
+        return _error_response(DeliveryFailed(f"app {name}'s server isn't answering: {type(e).__name__}: {e}"))
+    except BaseException:
+        await http.aclose()
+        raise
+
+    async def close() -> None:
+        await answer.aclose()
+        await http.aclose()
+
+    async def streamed() -> AsyncIterator[bytes]:
+        try:
+            async for chunk in answer.aiter_raw():
+                yield chunk
+        finally:
+            await close()
+
+    response = StreamingResponse(streamed(), status_code=answer.status_code, background=BackgroundTask(close))
+    response.raw_headers = _bytes(passed_on((name.decode("latin-1"), value.decode("latin-1"))
+                                            for name, value in answer.headers.raw))
+    return response
+
+
+async def relay(folder: Path, name: str, websocket: WebSocket) -> None:
+    """``websocket`` relayed both ways to the app ``name``'s server in ``folder`` until either side closes; refused,
+    before it opens, without the control token, with a Host that isn't a host and port, or with the app's server not
+    answering."""
+    host = websocket.headers.get("host", "")
+    if not control_check()(websocket.headers) or (host and not HOST.fullmatch(host)):
+        await websocket.close(code=1008)
+        return
+    headers = [(key, _utf8(value)) for key, value in to_app(
+        websocket.headers.items(), host, "https" if websocket.url.scheme == "wss" else "http", f"/svc/{name}")
+        if key.lower() != "host" and not key.lower().startswith("sec-websocket-")]
+    offered = [p.strip() for p in websocket.headers.get("sec-websocket-protocol", "").split(",") if p.strip()]
+    try:
+        upstream = await unix_connect(str(folder / SOCKET), f"ws://{host or 'app'}{target(websocket)}",
+                                      additional_headers=headers, subprotocols=offered or None, max_size=None,
+                                      compression=None, ping_interval=None, user_agent_header=None)
+    except (OSError, ValueError, asyncio.TimeoutError, websockets.WebSocketException):
+        await websocket.close(code=1011)
+        return
+    async with upstream:
+        await websocket.accept(subprotocol=upstream.subprotocol)
+        await _both_ways(websocket, upstream)
+
+
+def _utf8(value: str) -> str:
+    """A header value decoded as Latin-1 as the string ``websockets`` sends as the same bytes, which it encodes as
+    UTF-8; bytes that aren't UTF-8 become replacement characters."""
+    return value.encode("latin-1").decode("utf-8", "replace")
+
+
+async def _both_ways(client: WebSocket, app: ClientConnection) -> None:
+    """Each message from either side sent to the other until one side closes, then the other closed with its code."""
+    async def inbound() -> None:
+        while True:
+            message = await client.receive()
+            if message["type"] == "websocket.disconnect":
+                code = message.get("code") or 1000
+                await app.close(1000 if code in UNSENDABLE_CLOSES else code)
+                return
+            await app.send(message["text"] if message.get("text") is not None else message["bytes"])
+
+    async def outbound() -> None:
+        with contextlib.suppress(websockets.ConnectionClosed):
+            async for message in app:
+                if isinstance(message, str):
+                    await client.send_text(message)
+                else:
+                    await client.send_bytes(message)
+        code = app.close_code or 1000
+        with contextlib.suppress(RuntimeError, WebSocketDisconnect):
+            await client.close(1000 if code in UNSENDABLE_CLOSES else code)
+
+    tasks = [asyncio.ensure_future(inbound()), asyncio.ensure_future(outbound())]
+    try:
+        await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+    finally:
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)

{agentenv_framework_protocol-0.1.448 → agentenv_framework_protocol-0.1.449}/src/agentenv_protocol/website_browser.py

@@ -430,7 +430,10 @@ class BrowserControl:
         return {**({"png": png} if png is not None else {"blank": True}), "page": self._state_of(target)}
 
     async def _capture(self, session: str) -> Optional[str]:
+        """The tab's page as it shows now; with a dialog open on it, which keeps it from painting, the last it took."""
         target = self._sessions[session]
+        if session in self._open_dialogs:
+            return self._shots.get(target)
         navigated = self.tabs.get(target, {}).get("url")
         try:
             shot = await self.devtools.call("Page.captureScreenshot", {"format": "png", "optimizeForSpeed": True},

agentenv_framework_protocol-0.1.449/tests/test_computer_svc_forward.py

@@ -0,0 +1,227 @@
+"""The driver's /svc/<app>/ in front of an app's own server on its socket: a WebSocket is relayed both ways, with the
+subprotocol the app picks, until the app closes it with its code, and only with the control token and a Host that's a
+host; an answer streams through as the app sends it, 20 MB whole; every method and body goes on to the path as it came,
+still escaped, and the caller's headers, and only those, pass on as their bytes but for the hop-by-hop ones, the
+control token and any address the caller forwarded, which the driver sets as the one it was reached at."""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import hashlib
+import json
+import tempfile
+from pathlib import Path
+from types import SimpleNamespace
+
+import httpx
+import pytest
+import uvicorn
+
+pytest.importorskip("mcp.server.fastmcp")
+pytest.importorskip("PIL")
+
+from computer_fake import FakeDriver  # noqa: E402
+from probe_fake import served  # noqa: E402
+from starlette.requests import Request  # noqa: E402
+from starlette.responses import JSONResponse, Response, StreamingResponse  # noqa: E402
+from starlette.routing import WebSocketRoute  # noqa: E402
+from starlette.websockets import WebSocket  # noqa: E402
+from websockets.asyncio.client import connect  # noqa: E402
+from websockets.exceptions import ConnectionClosedError, InvalidStatus  # noqa: E402
+
+from agentenv_protocol import CONTROL_TOKEN_ENV, client  # noqa: E402
+from agentenv_protocol.computer import ComputerAppEnvironment, apps, linux, svc  # noqa: E402
+from agentenv_protocol.computer.app import SOCKET  # noqa: E402
+
+MB = 1 << 20
+TOKEN = "s3cret"
+
+
+@linux()
+class Echo(ComputerAppEnvironment):
+    """An app whose own server echoes what a WebSocket sends it until "bye", which it closes with 4001; answers with
+    the headers it got and the size of what it was sent; and streams 20 MB, its first MB at once and the rest once
+    ``released``."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.released = asyncio.Event()
+
+    def create_app(self):
+        mcp = super().create_app()
+        mcp.custom_route("/headers", methods=["GET"])(self._headers)
+        mcp.custom_route("/upload", methods=["PUT", "DELETE"])(self._upload)
+        mcp.custom_route("/big", methods=["GET"])(self._big)
+        mcp.custom_route("/raw/{rest:path}", methods=["GET"])(self._raw)
+        mcp._custom_starlette_routes += [WebSocketRoute("/echo", self._echo), WebSocketRoute("/raw/{rest:path}",
+                                                                                             self._raw_socket)]
+        return mcp
+
+    async def _raw(self, request: Request) -> Response:
+        scope = request.scope
+        return JSONResponse({"path": scope["raw_path"].decode(), "query": scope["query_string"].decode()})
+
+    async def _raw_socket(self, websocket: WebSocket) -> None:
+        await websocket.accept()
+        await websocket.send_text(websocket.scope["raw_path"].decode())
+        await websocket.close()
+
+    async def _headers(self, request: Request) -> Response:
+        answer = JSONResponse({"host": request.headers.get("host"), "headers": dict(request.headers.items())})
+        for header in ("set-cookie: a=1", "set-cookie: b=2", "connection: x-secret", "x-secret: 1", "x-kept: 1",
+                       'content-disposition: attachment; filename="报告.zip"'):
+            name, _, value = header.partition(": ")
+            answer.raw_headers.append((name.encode(), value.encode()))
+        return answer
+
+    async def _upload(self, request: Request) -> Response:
+        body = await request.body()
+        return JSONResponse({"method": request.method, "bytes": len(body), "sha256": hashlib.sha256(body).hexdigest()})
+
+    async def _big(self, request: Request) -> Response:
+        async def chunks():
+            yield b"a" * MB
+            await self.released.wait()
+            for _ in range(19):
+                yield b"b" * MB
+        return StreamingResponse(chunks(), media_type="application/octet-stream")
+
+    async def _echo(self, websocket: WebSocket) -> None:
+        await websocket.accept(subprotocol="cdp" if "cdp" in websocket.scope.get("subprotocols", []) else None)
+        await websocket.send_text(json.dumps({"forwarded": websocket.headers.get("x-forwarded-prefix"),
+                                              "authorization": websocket.headers.get("authorization")}))
+        while (message := await websocket.receive())["type"] != "websocket.disconnect":
+            if message.get("text") == "bye":
+                await websocket.close(code=4001)
+                return
+            await (websocket.send_text(message["text"]) if message.get("text") is not None
+                   else websocket.send_bytes(message["bytes"][::-1]))
+
+
+@contextlib.asynccontextmanager
+async def _computer(monkeypatch):
+    """The Echo app served on its socket in a computer's apps folder, and a driver in front of it on loopback, with a
+    control token; the app, and the driver's URL."""
+    with tempfile.TemporaryDirectory(dir="/tmp", prefix="apps-") as root:
+        folder = Path(root) / "echo"
+        (folder / SOCKET).parent.mkdir(parents=True)
+        monkeypatch.setattr(apps, "APPS", Path(root))
+        monkeypatch.setenv("ENVIRONMENT_NAME", "echo")
+        app = Echo()
+        server = uvicorn.Server(uvicorn.Config(app.create_app().streamable_http_app(), uds=str(folder / SOCKET),
+                                               log_level="warning", lifespan="off"))
+        serving = asyncio.create_task(server.serve())
+        while not server.started:
+            await asyncio.sleep(0.01)
+        monkeypatch.delenv("ENVIRONMENT_NAME")
+        monkeypatch.setenv(CONTROL_TOKEN_ENV, TOKEN)
+        try:
+            with served(FakeDriver()) as url:
+                yield app, url
+        finally:
+            server.should_exit = True
+            await serving
+
+
+@pytest.mark.asyncio
+async def test_a_websocket_through_svc_reaches_the_app_both_ways_until_it_closes_and_only_with_the_token(monkeypatch):
+    async with _computer(monkeypatch) as (_, url):
+        ws = url.replace("http", "ws") + "/svc/echo/echo"
+        async with connect(ws, additional_headers=client.control_headers(TOKEN), subprotocols=["cdp"]) as socket:
+            hello = json.loads(await socket.recv())
+            await socket.send("Page.navigate")
+            text = await socket.recv()
+            await socket.send(b"\x01\x02\x03")
+            data = await socket.recv()
+            await socket.send("bye")
+            with pytest.raises(ConnectionClosedError) as closed:
+                await socket.recv()
+            subprotocol = socket.subprotocol
+        refused = []
+        for headers, path in (({}, "/svc/echo/echo"), (client.control_headers("guess"), "/svc/echo/echo"),
+                              (client.control_headers(TOKEN), "/svc/notes/echo")):
+            with pytest.raises(InvalidStatus) as status:
+                async with connect(url.replace("http", "ws") + path, additional_headers=headers):
+                    pass
+            refused.append(status.value.response.status_code)
+        malformed = [await _handshake(url, host) for host in ("x/y", "[::1")]
+        async with connect(url.replace("http", "ws") + "/svc/echo/raw/a%3Fb",
+                           additional_headers=client.control_headers(TOKEN)) as socket:
+            raw = await socket.recv()
+
+    assert hello == {"forwarded": "/svc/echo", "authorization": None} and subprotocol == "cdp"
+    assert (text, data) == ("Page.navigate", b"\x03\x02\x01") and closed.value.rcvd.code == 4001
+    assert refused == [403, 403, 403] and malformed == [b"HTTP/1.1 403 Forbidden", b"HTTP/1.1 403 Forbidden"]
+    assert raw == "/raw/a%3Fb"
+
+
+@pytest.mark.asyncio
+async def test_an_answer_streams_through_svc_as_the_app_sends_it_20_mb_whole(monkeypatch):
+    async with _computer(monkeypatch) as (app, url):
+        async with httpx.AsyncClient(base_url=url, headers=client.control_headers(TOKEN), timeout=30) as http:
+            async with http.stream("GET", "/svc/echo/big") as answer:
+                chunks, first = answer.aiter_raw(), []
+
+                async def first_mb() -> None:
+                    while sum(map(len, first)) < MB:
+                        first.append(await chunks.__anext__())
+                await asyncio.wait_for(first_mb(), 10)
+                app.released.set()
+                body = b"".join(first) + b"".join([chunk async for chunk in chunks])
+
+    assert answer.status_code == 200 and len(body) == 20 * MB
+    assert body[:MB] == b"a" * MB and body[MB:] == b"b" * (19 * MB)
+
+
+@pytest.mark.asyncio
+async def test_every_method_and_body_goes_on_and_headers_pass_but_the_hop_ones_token_and_forwarded_address(
+        monkeypatch):
+    payload = b"x" * (3 * MB)
+    async with _computer(monkeypatch) as (_, url):
+        async with httpx.AsyncClient(base_url=url, headers=client.control_headers(TOKEN), timeout=30) as http:
+            seen = await http.get("/svc/echo/headers", headers={
+                "x-forwarded-host": "evil.test", "x-forwarded-prefix": "/elsewhere", "connection": "x-drop",
+                "x-drop": "1", "x-kept": "1"})
+            put = (await http.put("/svc/echo/upload", content=payload)).json()
+            deleted = (await http.delete("/svc/echo/upload")).json()
+            refused = await httpx.AsyncClient(base_url=url).get("/svc/echo/headers")
+            utf8 = (await http.get("/svc/echo/headers", headers=[(b"x-name", "报告".encode())])).json()["headers"]
+            raw = (await http.get("/svc/echo/raw/a%3Fb%2Fc?q=1")).json()
+            escaped = (await http.get(httpx.URL(url, raw_path=b"/%73vc/echo/raw/a%3Fb?q=1"))).json()
+            http.headers.clear()
+            bare = (await http.get("/svc/echo/headers", headers=client.control_headers(TOKEN))).json()["headers"]
+    got, host = seen.json()["headers"], url.removeprefix("http://")
+
+    assert seen.json()["host"] == host and got["x-kept"] == "1"
+    assert {key: got[key] for key in svc.FORWARDED} == {
+        "x-forwarded-host": host, "x-forwarded-proto": "http", "x-forwarded-prefix": "/svc/echo"}
+    assert "authorization" not in got and "x-drop" not in got
+    assert seen.headers.get_list("set-cookie") == ["a=1", "b=2"] and "x-secret" not in seen.headers
+    assert seen.headers["x-kept"] == "1"
+    assert put == {"method": "PUT", "bytes": 3 * MB, "sha256": hashlib.sha256(payload).hexdigest()}
+    assert deleted["method"] == "DELETE" and deleted["bytes"] == 0 and refused.status_code == 401
+    assert not {"accept", "accept-encoding", "user-agent"} & set(bare)
+    assert (b"content-disposition", 'attachment; filename="报告.zip"'.encode()) in seen.headers.raw
+    assert utf8["x-name"] == "报告".encode().decode("latin-1")
+    assert raw == {"path": "/raw/a%3Fb%2Fc", "query": "q=1"} and escaped == {"path": "/raw/a%3Fb", "query": "q=1"}
+
+
+@pytest.mark.parametrize(("raw", "root", "routed"), [(b"/svc/echo/raw/a%2Fb", "", "raw/a/b"),
+                                                     (b"/gw/svc/echo/raw/a%2Fb", "/gw", "raw/a/b")])
+def test_the_apps_path_is_the_raw_one_past_svc_and_its_name_wherever_the_driver_is_mounted(raw, root, routed):
+    connection = SimpleNamespace(scope={"raw_path": raw, "root_path": root, "query_string": b"q=1"},
+                                 path_params={"name": "echo", "path": routed})
+
+    assert svc.target(connection) == "/raw/a%2Fb?q=1"
+
+
+async def _handshake(url: str, host: str) -> bytes:
+    """The status line the driver answers a WebSocket handshake for the app's echo route with, sent with ``host`` as
+    its Host and the control token."""
+    reader, writer = await asyncio.open_connection(*url.removeprefix("http://").split(":"))
+    writer.write((f"GET /svc/echo/echo HTTP/1.1\r\nHost: {host}\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n"
+                  "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\nSec-WebSocket-Version: 13\r\n"
+                  f"Authorization: Bearer {TOKEN}\r\n\r\n").encode())
+    status = (await asyncio.wait_for(reader.readline(), 10)).strip()
+    writer.close()
+    return status

{agentenv_framework_protocol-0.1.448 → agentenv_framework_protocol-0.1.449}/tests/test_website_browser.py

@@ -782,7 +782,7 @@ async def test_its_page_capture_names_the_tab_it_captured_though_another_becomes
 
 
 @pytest.mark.asyncio
-async def test_while_a_dialog_keeps_its_page_from_painting_its_capture_is_the_last_it_took():
+async def test_while_a_dialog_keeps_its_page_from_painting_its_capture_is_the_last_it_took_without_waiting_on_it():
     devtools = Tabbed()
     control = await _tabs(devtools, "a")
     before = await control.capture()
@@ -790,6 +790,7 @@ async def test_while_a_dialog_keeps_its_page_from_painting_its_capture_is_the_la
     devtools.send("Page.javascriptDialogOpening", {"type": "alert", "message": "Saved"}, session="s-a")
 
     assert before == "png of s-a" and await control.capture() == "png of s-a"
+    assert len(devtools.timeouts) == 1
 
 
 @pytest.mark.asyncio