diff --git a/AGENTS.md b/AGENTS.md index 62d6457c7..d9787b95f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -121,7 +121,7 @@ and deserialized through a registry. | Package | Contents | |---|---| -| `env/` | `Env` base class: a subclass declares `type`, implements `from_dict` and `async deploy(...) -> DeployedEnv`, and may override `reset`, `close` and `load_file_artifact_universe`; teardown closes each env a run deployed before terminating its sandboxes by id. Built-ins in `env/envs/`: `MCPServerEnv` (`mcp_server`), `MultiEnv` (`multi`, MCP servers plus websites), `ServiceDBEnv` (`service_db`, PostgreSQL), `WebsiteEnv` (`website`, one site: a server image, `backend_image` in its env.toml, serving the pages and API, ready when its card's `website/v1` `ready` answers a `WebsiteReadiness` that says so, as `agentenv_protocol.website` (`website_readiness`, `env_readiness`) defines a website env's health for the deploy and `DeployedEnv.readiness()` alike, or, for a card without `ready`, when its `health` path answers 200, which is deprecated; the gateway container's `env/gateway/constants.py` mirrors the URI and op, a test keeping them equal; a separate frontend image is deprecated, warned of at put and optional in a bundle, and a stored `backend_docker_image_artifact` reads as the server image; a live one, `live = true`, is a real site whose server serves none of its pages, its `live`, `domains` and `allow_hosts` read at put from its server's `@website(...)` (`utils/card_naming.py` `WebsiteSource`) unless given, its `settings`' secrets only as references the gateway resolves as it writes the site's container (`WEBSITE_SETTINGS_ENV`); the gateway gives it no site route, a computer's site table leaves it out, a computer whose network is an allowlist is let reach its names (`MultiEnv.live_hosts`), a browser alone's forward port takes them straight to the real site (`site_proxy.py` `direct`), and a run that deploys one is marked live, `reproducible: false`), `GatewayEnv` (`gateway_server`), `ComputerDriverEnv` (`computer_driver`, `env/envs/computer/driver_env.py`: a computer driver's files and what its class declares for each platform it supports, read at put in a process of its own, `agentenv_protocol.computer._declare`, where the driver's own dependencies needn't be installed, with the `port` it serves on and its install by OS, `[install.]`, or for one distribution `[install."/"]`, which replaces its OS type's there, as its `known_failures` do (`env/envs/computer/utils/install.py`): files, apt `packages` with extra `sources`, a `python` requirements file for a venv, `downloads` by URL and sha256, `run` scripts, the services the base's init runs, and `ports`; it deploys only as a computer env's driver), `ComputerEnv` (`computer`, in `env/envs/computer/`: a base computer and a driver, matched at put by gate 1 before anything is stored, then composed by `composer.py` into an image for each form and arch on a builder of the put's sandbox provider, by default the env's (`utils/builder.py`; `--sandbox` on `env build`, `bundle register` and `run`): this machine's Docker for `local`, else a VM of the provider, which fetches the put's stored files by signed URL, takes the rest inline and pushes to the image store itself, so it builds only with stores a remote VM reaches; each arch goes to the first link that runs it natively, else one that emulates it (a VM registers QEMU; `--no-emulate` leaves it `skipped` instead, for a later put), and its pair records the provider that built it (`builder`); a run or register that reuses a computer env composes what it has left (`pending`), a run only the forms its sandbox's deploys boot (`booted_forms`: on each link, the first form it boots natively, by the deploy's own rule, `boot.first_native`; a compose of a disk adds its container), and a deploy composes first what it boots that no compose started, and a container it runs natively that was built but not probed, as one whose probe a setting that didn't resolve stopped, booting it only once ready (`ComputerEnv.compose_unstarted`); tagged `agentenv-computers:` in the image store by a key of the image's Dockerfile, build context and lock so any env with the same inputs reuses it; every layer's packages, requirements and downloads are resolved at put in a container of the base for each arch (`utils/packages.py`, `utils/resolve_in_base.py`), stored in the object store by sha256 under `agentenv-packages/`, and listed in a lock stored by a digest of its inputs, which any env with the same inputs reuses, and builds install only the lock's files, every install step `RUN --network=none`; each pair's status goes into its metadata, `composed`, the arches built are written as its computer, a `computer` artifact over one index, and `agent-env env build` resumes what a put left; gate 3 (`utils/probing.py`) then boots each native build on the put's sandbox provider and probes it at `full`, making it `ready` or `failed`, and a build no provider runs natively stays `unverified`. Its deploy, through the `computer` env provider (`providers/env_providers/env_computer_provider.py`), boots its first `ready` build on a sandbox provider that runs its arch natively (`native_platforms()`), with no gateway in front and the driver's card as the env card, its `/dev/shm` the most its apps' Linux installs ask for (`shm_mb`, in MiB, which its composed computer and the deploy record keep; `--shm-size` on a container, `AGENTENV_SHM_MB` read by a Linux disk's init, passed only to a provider whose `SHARED_MEMORY` says it gives that much, else the sandbox's default, which the deploy logs), then checks its `display`; `deploy_env` `env_params` take a `form`, `computer_settings` (deploy-phase values of the base's settings; a secret one, here or on the env, only as a bare `secret:`/`env:` reference) and `driver_settings` (the driver's `ComputerSettings`, such as its default coordinate space); a `network` that allows nothing runs it on local Docker's internal network behind a relay (`providers/sandbox_providers/local_docker/relay/`); `reset` and `close` have the driver end its recordings first (`computer-recording/v1` `end_all`, each uploading what's left and its manifest under the grant it started with), and `reset` then boots a fresh container in its place (`reset_container`), keeping the computer's address but not an agent's MCP session to the old driver; its `load_file_artifact_universe` writes files under the session user's home through the driver's `data/add`, `Downloads` by default, each file's bytes through a read grant when the store's grants reach it and its network allows everything, else inline (`env/envs/computer/utils/inside.py`)), `ComputerAppEnv` (`computer_app`, `env/envs/computer/app_env.py`: an app on a computer, a `ComputerAppEnvironment` class its env.toml's `module` names, read at put by the same `_declare`, which declares each OS with its own decorator (`@linux(...)`, or `@install(os_type, spec)` for any OS type; `@linux(distribution=...)` or `@install("/", spec)` for one distribution, which replaces its OS type's there) holding its install, its launch and, optionally, a skill and settings and build settings that add to the class's there, and install steps and ready checks for every OS or those their `os=` names; everything that reads its settings, launch or steps asks for the computer's OS type; deployed alone it is a one-app computer env, a `ComputerEnv` of the computer and driver its env.toml names, the composer installing it under `/opt/agentenv/apps//` with its services as supervisord programs beside its own server (`agentenv_protocol.computer.serve_app`, in a venv with the protocol's `app` extra, on `.agentenv/server.sock` in its folder), which adds its launcher, launches a `boot` app once per boot and says through `computer-app/v1` whether it's ready, as the driver's `computer-ready` asks, its card named after it, and `env_params` `app_settings` handing it values of its `Settings` in `AGENTENV_APP_SETTINGS`, a secret one only as a bare reference, over its env.toml's `[settings]` and a computer env's `settings` beside it in `apps`, each by top-level field (`params.app_settings`; checked at put, a required one left to the deploy; the deploy record keeps the merged values as `app_settings`, secrets withheld); its env.toml's `build_settings`, values of its `BuildSettings` checked at put, are written to `.agentenv/build_settings.json` in its folder, so they're part of the image's key, its install steps read them, and a deploy can't change them). An env type whose services take environment data defines `load_environment_artifact` and `load_environment_universe_artifact`; `load_artifact` refuses an environment artifact aimed at a type that doesn't, at save and before it loads. An env built on the protocol SDK can serve agents a skill (`@agent_skill`, `skill/v1`), which `add_skills` `env_ids` installs under its environment name (behind a gateway, each server's under that server's name); a skill with files beside its SKILL.md goes as a bundle stored once per content under `agentenv-env-skills/` in the object store. `env/gateway/gateway.py` is the env-side gateway server, container-only code. Its site route, `/website//`, never forwards a site's data plane or card (`/agentenv/…`, `/.well-known/agent-env.json`), which agentenv reaches through `/svc//`; a site with no frontend image is served by its server image there. Its CDP route, `/browser//cdp//` (`env/gateway/browser_proxy.py`), reaches the website browser behind the `/svc` child ``, found from that child's card (it, or an app among its children, offering `browser/v1` `cdp` with `/cdp/` in its `computer-app/v1` `agent_routes`): it relays the browser's discovery and WebSocket both ways, each leg pinged every 20 s, and every CDP address the browser hands out, in `json/version`, `json/list` and its `cdp` answer through `/svc//`, comes back at the gateway, everything before `/cdp//` becoming the address the caller reached the gateway at and `/browser/`; each connection is a `browser_connection` trajectory event, without its token. While its clock is armed it serves agents `get_time` (`env/gateway/get_time.py`), which answers in UTC and, given an IANA `time_zone`, also in that zone; executors' working `hours` (`env/gateway/triggers.py`) take a fixed `utc_offset` or an IANA `time_zone`. | +| `env/` | `Env` base class: a subclass declares `type`, implements `from_dict` and `async deploy(...) -> DeployedEnv`, and may override `reset`, `close` and `load_file_artifact_universe`; teardown closes each env a run deployed before terminating its sandboxes by id. Built-ins in `env/envs/`: `MCPServerEnv` (`mcp_server`), `MultiEnv` (`multi`, MCP servers plus websites), `ServiceDBEnv` (`service_db`, PostgreSQL), `WebsiteEnv` (`website`, one site: a server image, `backend_image` in its env.toml, serving the pages and API, ready when its card's `website/v1` `ready` answers a `WebsiteReadiness` that says so, as `agentenv_protocol.website` (`website_readiness`, `env_readiness`) defines a website env's health for the deploy and `DeployedEnv.readiness()` alike, or, for a card without `ready`, when its `health` path answers 200, which is deprecated; the gateway container's `env/gateway/constants.py` mirrors the URI and op, a test keeping them equal; a separate frontend image is deprecated, warned of at put and optional in a bundle, and a stored `backend_docker_image_artifact` reads as the server image; a live one, `live = true`, is a real site whose server serves none of its pages, its `live`, `domains` and `allow_hosts` read at put from its server's `@website(...)` (`utils/card_naming.py` `WebsiteSource`) unless given, its `settings`' secrets only as references the gateway resolves as it writes the site's container (`WEBSITE_SETTINGS_ENV`); the gateway gives it no site route, a computer's site table leaves it out, a computer whose network is an allowlist is let reach its names (`MultiEnv.live_hosts`), a browser alone's forward port takes them straight to the real site (`site_proxy.py` `direct`), as the headless base's stand-in proxy takes any host, refusing nothing, each proxy logging each such connection as a JSON line, and a run that deploys one is marked live, `reproducible: false`), `GatewayEnv` (`gateway_server`), `ComputerDriverEnv` (`computer_driver`, `env/envs/computer/driver_env.py`: a computer driver's files and what its class declares for each platform it supports, read at put in a process of its own, `agentenv_protocol.computer._declare`, where the driver's own dependencies needn't be installed, with the `port` it serves on and its install by OS, `[install.]`, or for one distribution `[install."/"]`, which replaces its OS type's there, as its `known_failures` do (`env/envs/computer/utils/install.py`): files, apt `packages` with extra `sources`, a `python` requirements file for a venv, `downloads` by URL and sha256, `run` scripts, the services the base's init runs, and `ports`; it deploys only as a computer env's driver), `ComputerEnv` (`computer`, in `env/envs/computer/`: a base computer and a driver, matched at put by gate 1 before anything is stored, then composed by `composer.py` into an image for each form and arch on a builder of the put's sandbox provider, by default the env's (`utils/builder.py`; `--sandbox` on `env build`, `bundle register` and `run`): this machine's Docker for `local`, else a VM of the provider, which fetches the put's stored files by signed URL, takes the rest inline and pushes to the image store itself, so it builds only with stores a remote VM reaches; each arch goes to the first link that runs it natively, else one that emulates it (a VM registers QEMU; `--no-emulate` leaves it `skipped` instead, for a later put), and its pair records the provider that built it (`builder`); a run or register that reuses a computer env composes what it has left (`pending`), a run only the forms its sandbox's deploys boot (`booted_forms`: on each link, the first form it boots natively, by the deploy's own rule, `boot.first_native`; a compose of a disk adds its container), and a deploy composes first what it boots that no compose started, and a container it runs natively that was built but not probed, as one whose probe a setting that didn't resolve stopped, booting it only once ready (`ComputerEnv.compose_unstarted`); tagged `agentenv-computers:` in the image store by a key of the image's Dockerfile, build context and lock so any env with the same inputs reuses it; every layer's packages, requirements and downloads are resolved at put in a container of the base for each arch (`utils/packages.py`, `utils/resolve_in_base.py`), stored in the object store by sha256 under `agentenv-packages/`, and listed in a lock stored by a digest of its inputs, which any env with the same inputs reuses, and builds install only the lock's files, every install step `RUN --network=none`; each pair's status goes into its metadata, `composed`, the arches built are written as its computer, a `computer` artifact over one index, and `agent-env env build` resumes what a put left; gate 3 (`utils/probing.py`) then boots each native build on the put's sandbox provider and probes it at `full`, making it `ready` or `failed`, and a build no provider runs natively stays `unverified`. Its deploy, through the `computer` env provider (`providers/env_providers/env_computer_provider.py`), boots its first `ready` build on a sandbox provider that runs its arch natively (`native_platforms()`), with no gateway in front and the driver's card as the env card, its `/dev/shm` the most its apps' Linux installs ask for (`shm_mb`, in MiB, which its composed computer and the deploy record keep; `--shm-size` on a container, `AGENTENV_SHM_MB` read by a Linux disk's init, passed only to a provider whose `SHARED_MEMORY` says it gives that much, else the sandbox's default, which the deploy logs), then checks its `display`; `deploy_env` `env_params` take a `form`, `computer_settings` (deploy-phase values of the base's settings; a secret one, here or on the env, only as a bare `secret:`/`env:` reference) and `driver_settings` (the driver's `ComputerSettings`, such as its default coordinate space); a `network` that allows nothing runs it on local Docker's internal network behind a relay (`providers/sandbox_providers/local_docker/relay/`); `reset` and `close` have the driver end its recordings first (`computer-recording/v1` `end_all`, each uploading what's left and its manifest under the grant it started with), and `reset` then boots a fresh container in its place (`reset_container`), keeping the computer's address but not an agent's MCP session to the old driver; its `load_file_artifact_universe` writes files under the session user's home through the driver's `data/add`, `Downloads` by default, each file's bytes through a read grant when the store's grants reach it and its network allows everything, else inline (`env/envs/computer/utils/inside.py`)), `ComputerAppEnv` (`computer_app`, `env/envs/computer/app_env.py`: an app on a computer, a `ComputerAppEnvironment` class its env.toml's `module` names, read at put by the same `_declare`, which declares each OS with its own decorator (`@linux(...)`, or `@install(os_type, spec)` for any OS type; `@linux(distribution=...)` or `@install("/", spec)` for one distribution, which replaces its OS type's there) holding its install, its launch and, optionally, a skill and settings and build settings that add to the class's there, and install steps and ready checks for every OS or those their `os=` names; everything that reads its settings, launch or steps asks for the computer's OS type; deployed alone it is a one-app computer env, a `ComputerEnv` of the computer and driver its env.toml names, the composer installing it under `/opt/agentenv/apps//` with its services as supervisord programs beside its own server (`agentenv_protocol.computer.serve_app`, in a venv with the protocol's `app` extra, on `.agentenv/server.sock` in its folder), which adds its launcher, launches a `boot` app once per boot and says through `computer-app/v1` whether it's ready, as the driver's `computer-ready` asks, its card named after it, and `env_params` `app_settings` handing it values of its `Settings` in `AGENTENV_APP_SETTINGS`, a secret one only as a bare reference, over its env.toml's `[settings]` and a computer env's `settings` beside it in `apps`, each by top-level field (`params.app_settings`; checked at put, a required one left to the deploy; the deploy record keeps the merged values as `app_settings`, secrets withheld); its env.toml's `build_settings`, values of its `BuildSettings` checked at put, are written to `.agentenv/build_settings.json` in its folder, so they're part of the image's key, its install steps read them, and a deploy can't change them). An env type whose services take environment data defines `load_environment_artifact` and `load_environment_universe_artifact`; `load_artifact` refuses an environment artifact aimed at a type that doesn't, at save and before it loads. An env built on the protocol SDK can serve agents a skill (`@agent_skill`, `skill/v1`), which `add_skills` `env_ids` installs under its environment name (behind a gateway, each server's under that server's name); a skill with files beside its SKILL.md goes as a bundle stored once per content under `agentenv-env-skills/` in the object store. `env/gateway/gateway.py` is the env-side gateway server, container-only code. Its site route, `/website//`, never forwards a site's data plane or card (`/agentenv/…`, `/.well-known/agent-env.json`), which agentenv reaches through `/svc//`; a site with no frontend image is served by its server image there. Its CDP route, `/browser//cdp//` (`env/gateway/browser_proxy.py`), reaches the website browser behind the `/svc` child ``, found from that child's card (it, or an app among its children, offering `browser/v1` `cdp` with `/cdp/` in its `computer-app/v1` `agent_routes`): it relays the browser's discovery and WebSocket both ways, each leg pinged every 20 s, and every CDP address the browser hands out, in `json/version`, `json/list` and its `cdp` answer through `/svc//`, comes back at the gateway, everything before `/cdp//` becoming the address the caller reached the gateway at and `/browser/`; each connection is a `browser_connection` trajectory event, without its token. While its clock is armed it serves agents `get_time` (`env/gateway/get_time.py`), which answers in UTC and, given an IANA `time_zone`, also in that zone; executors' working `hours` (`env/gateway/triggers.py`) take a fixed `utc_offset` or an IANA `time_zone`. | | `artifact/` | Immutable versioned artifacts; every `put()` creates a new version. The document goes to the document store, binary payloads to the object store. Every artifact but an environment universe, whose `metadata` key holds its legacy metadata file ids, carries a `metadata` dict outside its versioned fields, changed by compare-and-swap (`merge_metadata`). Built-ins: `CliArtifact` (`cli`), `ComputerArtifact` (`computer`, a base computer: its architectures, OS, session user, settings and container form, whose image `put` reads from its registry into `metadata.validated_images`), `FileArtifact` (`file`), `FileArtifactUniverse` (`file_artifact_universe`), `DockerImageArtifact` (`docker_image`), `EnvironmentArtifact` (`environment`: its environment's files by path, stored as the one wrapped `file_artifact_ref` every environment artifact had when it has one file at its filename, else as `file_artifact_refs`; `get_file_artifacts()` reads either, and a load hands each file to the env's `data/add` with its path, which a pre-v1 load, taking one file, refuses), `EnvironmentUniverseArtifact` (`environment_universe`), `SkillArtifact` (`skill`); `[artifacts] type_aliases` maps another stored spelling of a type onto one of them. A `DockerImageArtifact` holds a tar.gz of its image, or, written by `put_ref` (`--image-ref` on `env mcp-server put` and `a2a-agent put`), only a registry reference with its tag pinned to a digest, which sandboxes pull, or a published image's tag with its `image_digest` and its build context, which sandboxes pull by the digest and build from the context when they can't (the infra images, and a bundle agent built from a shipped agent's sources, `Plan.published`), or, written by `put_context`, only its build context, which a VM sandbox builds before running it (`VmSandbox.load_docker_images`) and Modal builds before creating its container (`ModalSandboxProvider.prepare_image`, outside a fallback chain's deadline); anything else that runs images by name (a container on the local provider, a lone server on any provider but Modal) refuses such an image. A build context (`utils/docker/context.py`) is what `docker build` would send, `.dockerignore` applied, written so equal files give equal bytes and an equal `source_digest`. | | `task/`, `task_step/` | A `Task` holds its `TaskStep`s inline; `Task.run()` executes them as a DAG. `depends_on` (None means all prior steps) gates a step, independent steps run concurrently, `fail_task_on_error` makes a failure fatal or tolerated, `retry_config` rolls a failed span back through the step journal and re-dispatches it. Built-in steps live in `task_step/task_steps/` (`deploy_env`, `deploy_agent`, `prompt_agent`, the verifiers under `verifiers/`, among them `start_computer_recording` and `end_computer_recording`, and more). On an env whose card serves computer-exec/v1 (a computer), `run_code` with `env_id` and `run_container_unit_tests_verifier` with `env_id` run inside it as its session user through the driver: files staged with `data/add` and read with `data/get`, commands run with `run`; `env_outcome_verifier` hands a `verify` that takes an `env_url` keyword the env's address. A computer's framework-only routes (everything but MCP and the card) take the per-deploy control token its provider boots it with (`DeployedEnv.control_token`, `AGENTENV_CONTROL_TOKEN`); framework calls send `deployed.control_headers`, `Task.run` runs every step under `protocol_v1.authorized` with each deployed env's (a `verify` included), and a `run_code` script inside the computer gets `input["env"]["headers"]`. `teardown_run` and the `teardown_sandboxes` step share one core (`task/teardown.py` `tear_down`): the recordings the run left open end with fresh grants, each env still up closes (`Env.close`; a computer env ends any recording still open), what stayed open is registered from its namespace, then every sandbox is terminated by id. `task/episode/` runs a task with some of its agents played from outside, as a training loop does (`EpisodeSpec`). | | `store/` | Four store ABCs with local and cloud implementations: `DocumentStore` (SQLite, MongoDB, DynamoDB, Firestore with MongoDB compatibility), `ObjectStore` (filesystem, S3, Cloud Storage), `ImageStore` (local OCI registry, ECR), `SecretStore` (env vars or file, AWS Secrets Manager, Google Cloud Secret Manager). `VersionedEntityStore` implements the shared versioned get/put logic, `QueryBuilder` is the immutable chained query API, `store/base.py` holds the error types. `store/routing.py` is the local namespaces, `@local` and `@hf` (`is_local_id`), each with a documents file of its own: while the CLI or a `build_app` server runs, a local id and what a local task's run records go to local stores beside the configured ones, and that run's writes to the configured stores are refused. A new backend must pass the conformance kits in `tst/store/`. | diff --git a/src/agent_env/computers/README.md b/src/agent_env/computers/README.md index c5e8ca415..4ebc98282 100644 --- a/src/agent_env/computers/README.md +++ b/src/agent_env/computers/README.md @@ -14,9 +14,10 @@ building it. Name it from another bundle as `ubuntu-24.04`, the alias `aliases.t (`display = "none"`), for one website browser, which runs headless there, and the `page` driver, whose screen is the browser's page: a browser computer, which agentenv's `chromium` deploys alone as. supervisord runs every program as the session user, among them a stand-in site proxy on `127.0.0.1:3128`, the browser's only route out when the computer -routes no sites, which forwards every request to wherever it names, refusing nothing: the sandbox's network policy is -all that limits it. A computer that routes sites names the shared site proxy's forward port, `127.0.0.1:3129`, to the -browser instead: it serves the run's sites, refuses every other host and runs out of the agent's reach. It has a +routes no sites. It forwards a request or a `CONNECT` tunnel to any host, never decrypting a tunnel and refusing +nothing: the sandbox's network policy is all that limits it. Every line it writes to `/var/log/agentenv/site-proxy.log` +is JSON, one per connection and one per connection that fails, in the same shapes as the shared site proxy's. A computer that routes sites names the shared site proxy's forward port, +`127.0.0.1:3129`, to the browser instead: it serves the run's sites, refuses every other host and runs out of the agent's reach. It has a container form only. Name it from another bundle as `ubuntu-24.04-headless`, or by its id, `@local/agentenv-framework/computers/ubuntu-24.04-headless`. diff --git a/src/agent_env/computers/artifacts/ubuntu-24.04-headless/site-proxy.py b/src/agent_env/computers/artifacts/ubuntu-24.04-headless/site-proxy.py index 5eacb8004..a874525ae 100644 --- a/src/agent_env/computers/artifacts/ubuntu-24.04-headless/site-proxy.py +++ b/src/agent_env/computers/artifacts/ubuntu-24.04-headless/site-proxy.py @@ -1,68 +1,150 @@ -"""A stand-in for the shared site proxy in this base: it forwards every request the browser sends it, absolute-form -HTTP and CONNECT tunnels alike, to wherever it names, refusing nothing, on 127.0.0.1:3128.""" +"""A stand-in for the shared site proxy in this base, on 127.0.0.1:3128: it forwards every request the browser sends +it, absolute-form HTTP and CONNECT tunnels alike, to the host it names, refusing nothing and never decrypting a tunnel. +The sandbox's own network policy still decides where a connection can go. Every line it logs is JSON, in the same +shapes as the shared site proxy's: ``connection`` (host, port, address, bytes each way, start, duration) when one +ends, and ``failed`` (method, host, port, ``reason`` "doesn't resolve" or "no answer", and the error) for one that +couldn't open.""" import http.server -import select +import json +import selectors import socket import socketserver +import time import urllib.parse PORT = 3128 -IDLE_S = 60 +CONNECT_TIMEOUT_S = 30 +IDLE_S = 300 HOP = {"connection", "keep-alive", "proxy-connection", "proxy-authorization"} +def log(**fields) -> None: + print(json.dumps(fields), flush=True) + + +def _error(error: BaseException) -> str: + return f"{type(error).__name__}: {error}".removesuffix(": ") + + class Proxy(http.server.BaseHTTPRequestHandler): protocol_version = "HTTP/1.1" def do_CONNECT(self): host, _, port = self.path.rpartition(":") host = host.removeprefix("[").removesuffix("]") - try: - upstream = socket.create_connection((host, int(port)), timeout=10) - except (OSError, ValueError): - self.send_error(502) + if not port.isdigit(): + self.send_error(400) + return + if (opened := self._open(host, int(port), "CONNECT")) is None: return self.send_response(200, "Connection established") self.end_headers() self.close_connection = True - _pipe(self.connection, upstream) + self._relay(*opened, host, int(port), b"") def forward(self): url = urllib.parse.urlsplit(self.path) - try: - upstream = socket.create_connection((url.hostname, url.port or 80), timeout=10) - except (OSError, TypeError): - self.send_error(502) + if not url.hostname: + self.send_error(400) + return + port = url.port or 80 + if (opened := self._open(url.hostname, port, self.command)) is None: return target = (url.path or "/") + (f"?{url.query}" if url.query else "") headers = "".join(f"{k}: {v}\r\n" for k, v in self.headers.items() if k.lower() not in HOP) - upstream.sendall(f"{self.command} {target} HTTP/1.1\r\n{headers}Connection: close\r\n\r\n".encode("latin-1")) - if length := int(self.headers.get("Content-Length") or 0): - upstream.sendall(self.rfile.read(length)) + head = f"{self.command} {target} HTTP/1.1\r\n{headers}Connection: close\r\n\r\n".encode("latin-1") + body = self.rfile.read(length) if (length := int(self.headers.get("Content-Length") or 0)) else b"" self.close_connection = True - _pipe(self.connection, upstream) + self._relay(*opened, url.hostname, port, head + body) do_GET = do_POST = do_PUT = do_PATCH = do_DELETE = do_HEAD = do_OPTIONS = forward + def _open(self, host: str, port: int, method: str) -> tuple[socket.socket, str] | None: + """A connection to an address ``host`` resolves to, tried in turn within one ``CONNECT_TIMEOUT_S`` for them + all, and that address; or None once the browser has its answer, a 502 for a host that doesn't resolve or + answer. The connection keeps an ``IDLE_S`` timeout, so a write to a peer that stopped reading ends too.""" + deadline = time.monotonic() + CONNECT_TIMEOUT_S + try: + found = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM) + except OSError as error: + log(failed={"method": method, "host": host, "port": port, "reason": "doesn't resolve", + "error": _error(error)}) + self._answer(502, f"{host} doesn't resolve\n") + return None + last = None + for address in dict.fromkeys(info[4][0] for info in found): + if (left := deadline - time.monotonic()) <= 0: + break + try: + upstream = socket.create_connection((address, port), timeout=left) + except OSError as error: + last = error + continue + upstream.settimeout(IDLE_S) + return upstream, address + log(failed={"method": method, "host": host, "port": port, "reason": "no answer", + "error": _error(last) if last else f"none within {CONNECT_TIMEOUT_S} s"}) + self._answer(502, f"{host}:{port} didn't answer\n") + return None + + def _answer(self, status: int, body: str) -> None: + data = body.encode() + self.send_response(status) + self.send_header("Content-Type", "text/plain; charset=utf-8") + self.send_header("Content-Length", str(len(data))) + self.send_header("X-Agentenv-Site-Proxy", "failed") + self.send_header("Connection", "close") + self.end_headers() + self.wfile.write(data) + self.close_connection = True + + def _relay(self, upstream: socket.socket, address: str, host: str, port: int, first: bytes) -> None: + started, began = time.time(), time.monotonic() + sent, received = len(first), 0 + self.connection.settimeout(IDLE_S) + try: + if first: + upstream.sendall(first) + more, received = _pipe(self.connection, upstream) + sent += more + finally: + log(connection={"host": host, "port": port, "address": address, "bytes_sent": sent, + "bytes_received": received, + "started": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(started)), + "duration_s": round(time.monotonic() - began, 3)}) + def log_message(self, *args): pass -def _pipe(a: socket.socket, b: socket.socket) -> None: +def _pipe(client: socket.socket, upstream: socket.socket) -> tuple[int, int]: + """Relay both ways until either side closes or both are idle ``IDLE_S``; the bytes sent upstream and received. + It waits with a selector (epoll on Linux), not ``select()``, which refuses a socket numbered past 1023.""" + sent = received = 0 + waiting = selectors.DefaultSelector() try: + waiting.register(client, selectors.EVENT_READ) + waiting.register(upstream, selectors.EVENT_READ) while True: - ready, _, _ = select.select([a, b], [], [], IDLE_S) + ready = waiting.select(IDLE_S) if not ready: - return - for s in ready: + break + for key, _ in ready: + s = key.fileobj data = s.recv(65536) if not data: - return - (b if s is a else a).sendall(data) + return sent, received + (upstream if s is client else client).sendall(data) + if s is client: + sent += len(data) + else: + received += len(data) except OSError: - return + pass finally: - b.close() + waiting.close() + upstream.close() + return sent, received class Server(socketserver.ThreadingMixIn, http.server.HTTPServer): @@ -71,4 +153,5 @@ class Server(socketserver.ThreadingMixIn, http.server.HTTPServer): if __name__ == "__main__": + log(listening={"address": "127.0.0.1", "port": PORT}) Server(("127.0.0.1", PORT), Proxy).serve_forever() diff --git a/src/agent_env/env/envs/computer/utils/site_proxy.py b/src/agent_env/env/envs/computer/utils/site_proxy.py index 6442dab12..eddacff70 100644 --- a/src/agent_env/env/envs/computer/utils/site_proxy.py +++ b/src/agent_env/env/envs/computer/utils/site_proxy.py @@ -106,6 +106,26 @@ def matches(pattern: str, host: str) -> bool: return host == pattern +def log_event(**fields) -> None: + """One JSON line in the proxy's log, every line it writes being one: ``connection`` (host, port, address, bytes each + way, start, duration) when a connection to a live site's host ends, ``failed`` (method, host, port, ``reason`` + "doesn't resolve" or "no answer", and the error) for one that couldn't open, both in the same shapes as the + headless base's stand-in proxy's; ``refused`` for a host that's no site, ``error`` for a connection that failed + unexpectedly, and ``restarted`` when ``keep`` starts the proxy again.""" + print(json.dumps(fields), file=sys.stderr, flush=True) + + +def described(error: BaseException) -> str: + return f"{type(error).__name__}: {error}".removesuffix(": ") + + +class Count: + """The bytes a relay has carried one way, counted as it goes, so a connection that ends on an error keeps them.""" + + def __init__(self, start: int = 0): + self.bytes = start + + @dataclass class Site: """One site as the proxy serves it: its names, the route on the gateway it forwards to, and its certificate and key @@ -361,10 +381,13 @@ async def relay_chunked(reader: asyncio.StreamReader, writer: asyncio.StreamWrit await relay_exact(reader, writer, size + 2) -async def relay_until_eof(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None: +async def relay_until_eof(reader: asyncio.StreamReader, writer: asyncio.StreamWriter, + count: Optional[Count] = None) -> None: while data := await reader.read(CHUNK): writer.write(data) await writer.drain() + if count is not None: + count.bytes += len(data) async def relay_body(reader: asyncio.StreamReader, writer: asyncio.StreamWriter, headers: list[tuple[str, str]], @@ -380,10 +403,11 @@ async def relay_body(reader: asyncio.StreamReader, writer: asyncio.StreamWriter, await relay_until_eof(reader, writer) -async def splice(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None: - """One direction of an upgraded connection, closing the other side when it ends, which ends the other direction.""" +async def splice(reader: asyncio.StreamReader, writer: asyncio.StreamWriter, count: Optional[Count] = None) -> None: + """One direction of an upgraded connection, closing the other side when it ends, which ends the other direction; + the bytes it carries counted in ``count`` when given.""" try: - await relay_until_eof(reader, writer) + await relay_until_eof(reader, writer, count) except (ConnectionError, OSError, ssl.SSLError): pass finally: @@ -455,22 +479,37 @@ async def _tunnel(self, reader: asyncio.StreamReader, writer: asyncio.StreamWrit async def _direct(reader: asyncio.StreamReader, writer: asyncio.StreamWriter, host: str, port: int, head: Optional[bytes] = None) -> None: """``host``, a live site's, reached straight at ``port``: a tunnel, answered as established, for a ``CONNECT``, - else ``head`` sent on; then both ends relayed until either closes.""" + else ``head`` sent on; then both ends relayed until either closes, and the connection logged (``log_event``). + One that doesn't resolve or answer within ``UPSTREAM_TIMEOUT_S``, the lookup and every address's attempt + together, is a 502, logged too.""" try: up_reader, up_writer = await asyncio.wait_for(asyncio.open_connection(host, port), UPSTREAM_TIMEOUT_S) except (OSError, asyncio.TimeoutError) as e: - writer.write(simple_response("502 Bad Gateway", f"{host}:{port} didn't answer: {e}\n", FAILED)) + unresolved = isinstance(e, socket.gaierror) + log_event(failed={"method": "CONNECT" if head is None else head.split(b" ", 1)[0].decode("latin-1"), + "host": host, "port": port, "reason": "doesn't resolve" if unresolved else "no answer", + "error": described(e)}) + writer.write(simple_response("502 Bad Gateway", f"{host} doesn't resolve\n" if unresolved else + f"{host}:{port} didn't answer\n", FAILED)) return + address = (up_writer.get_extra_info("peername") or ("",))[0] + started, began, sent, received = time.time(), time.monotonic(), Count(len(head or b"")), Count() if head is None: writer.write(b"HTTP/1.1 200 Connection established\r\n\r\n") else: up_writer.write(head) - await asyncio.gather(writer.drain(), up_writer.drain()) - await asyncio.gather(splice(reader, up_writer), splice(up_reader, writer)) + try: + await asyncio.gather(writer.drain(), up_writer.drain()) + await asyncio.gather(splice(reader, up_writer, sent), splice(up_reader, writer, received)) + finally: + log_event(connection={"host": host, "port": port, "address": address, "bytes_sent": sent.bytes, + "bytes_received": received.bytes, + "started": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(started)), + "duration_s": round(time.monotonic() - began, 3)}) @staticmethod def _refuse(writer: asyncio.StreamWriter, method: str, host: str) -> None: - print(f"site proxy: refused {method} {host}: no site of this computer", file=sys.stderr, flush=True) + log_event(refused={"method": method, "host": host, "reason": "no site of this computer"}) writer.write(simple_response("403 Forbidden", f"{host} is no site of this computer, and the browser reaches " "its sites alone\n", FAILED)) @@ -483,7 +522,7 @@ async def _serving(writer: asyncio.StreamWriter, label: str, serving: Awaitable[ except (ConnectionError, asyncio.IncompleteReadError, ssl.SSLError, OSError): pass except Exception as e: - print(f"site proxy: a {label} connection failed: {type(e).__name__}: {e}", file=sys.stderr, flush=True) + log_event(error={"connection": label, "error": described(e)}) finally: try: await writer.drain() @@ -1101,7 +1140,7 @@ def keep(serve_path: str) -> None: while True: ended = subprocess.run([sys.executable, os.path.abspath(__file__), "serve", serve_path], stdin=subprocess.DEVNULL).returncode - print(f"the site proxy ended ({ended}); starting it again", flush=True) + print(json.dumps({"restarted": {"exit_code": ended}}), flush=True) time.sleep(RESTART_DELAY_S) diff --git a/tst/integration/computer/browser_computer_test.py b/tst/integration/computer/browser_computer_test.py index eeca7dba5..490c62d40 100644 --- a/tst/integration/computer/browser_computer_test.py +++ b/tst/integration/computer/browser_computer_test.py @@ -23,6 +23,7 @@ localhost:5000, and Node 20 or later and npm for the CDP clients.""" import asyncio +import itertools import json import platform import re @@ -38,6 +39,7 @@ from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client from PIL import Image +from websockets.asyncio.client import connect from agentenv_protocol import client as protocol_v1 from agentenv_protocol.computer import COMPUTER_PAGE, COMPUTER_READY @@ -535,11 +537,45 @@ async def _ready(deployed) -> dict: """ -async def _through_port(deployed, url: str) -> str: - done = await inside.run(deployed, ["python3", "-c", THROUGH_PROXY, url, "http://127.0.0.1:3129"], timeout_s=60) +async def _through_port(deployed, url: str, proxy: str = "http://127.0.0.1:3129") -> str: + done = await inside.run(deployed, ["python3", "-c", THROUGH_PROXY, url, proxy], timeout_s=60) return done["stdout"].strip() +#: What a CDP agent sees of the tab it navigates: its title, its first words, and whether it finished loading. +PAGE_SEEN = ("JSON.stringify({ready: document.readyState, title: document.title, " + "text: document.body ? document.body.innerText.slice(0, 200) : ''})") + + +async def _cdp_agent_loads(ws_url: str, urls: list[str]) -> dict: + """What a CDP agent at ``ws_url`` sees navigating a tab of its own to each of ``urls``, one after another: + ``Page.navigate``'s error, if any, and the page once it has loaded.""" + async with connect(ws_url, max_size=None, open_timeout=60) as ws: + ids = itertools.count(1) + + async def call(method: str, params: dict, session: str | None = None) -> dict: + message_id = next(ids) + await ws.send(json.dumps({"id": message_id, "method": method, "params": params, + **({"sessionId": session} if session else {})})) + while (reply := json.loads(await asyncio.wait_for(ws.recv(), 90))).get("id") != message_id: + pass + return reply + + target = (await call("Target.createTarget", {"url": "about:blank"}))["result"]["targetId"] + session = (await call("Target.attachToTarget", {"targetId": target, "flatten": True}))["result"]["sessionId"] + seen = {} + for url in urls: + navigated = await call("Page.navigate", {"url": url}, session) + page, deadline = {}, time.monotonic() + 30 + while page.get("ready") != "complete" and time.monotonic() < deadline: + await asyncio.sleep(1) + evaluated = await call("Runtime.evaluate", {"expression": PAGE_SEEN, "returnByValue": True}, session) + page = json.loads(evaluated.get("result", {}).get("result", {}).get("value") or "{}") + seen[url] = {"error": navigated.get("result", {}).get("errorText") or navigated.get("error", {}).get( + "message"), **page} + return seen + + async def _container_of(deployed) -> str: """The Docker container ``deployed``'s computer runs in, on this machine's local provider.""" return (await LocalSandboxProvider().get_sandbox(deployed.sandbox_id)).container_name @@ -610,8 +646,9 @@ async def test_routing_sites_it_goes_out_only_through_the_forward_port_which_the assert (status, line) == ("200", "data: first") and int(seconds) < 15, pages assert all(pages[url].startswith("error") and "403" in pages[url] for url in ( "https://example.com/", "http://127.0.0.1:18765/", "https://127.0.0.1:18765/")), pages - assert "site proxy: refused CONNECT example.com:443: no site of this computer" in logged - assert "site proxy: refused GET 127.0.0.1:18765: no site of this computer" in logged + refused = [json.loads(line)["refused"] for line in logged.splitlines() if line.startswith('{"refused"')] + assert {"method": "CONNECT", "host": "example.com:443", "reason": "no site of this computer"} in refused, logged + assert {"method": "GET", "host": "127.0.0.1:18765", "reason": "no site of this computer"} in refused, logged assert stopped["exit_code"] != 0 and still == serving and after_stop.startswith("200 "), (stopped, after_stop) assert back.startswith("200 ") and restarted and restarted != serving, (back, restarted) assert after_reset.startswith("200 ") and after_reset.endswith("alpha"), after_reset @@ -649,6 +686,30 @@ async def test_routing_sites_beside_live_ones_its_forward_port_takes_the_live_ho assert not report.failed +@pytest.mark.asyncio +async def test_alone_on_the_open_web_it_loads_a_public_site_through_its_proxy_and_an_agents_tab_and_logs_each_connection( + browser_computer): + public, nowhere = "https://github.com/", "https://agentenv-no-such-host.invalid/" + with namespace_routing(): + deployed = await Env.get(browser_computer.id).deploy( + env_params={"app_settings": {"chromium": {"start_urls": [DATA_PAGE]}}}) + context = TaskStepContext(deployed_envs=[deployed]) + try: + through = {url: await _through_port(deployed, url, "http://127.0.0.1:3128") for url in (public, nowhere)} + seen = await _cdp_agent_loads((await _cdp(deployed, "ada"))["ws_url"], [public]) + logged = _as_root(await _container_of(deployed), "cat /var/log/agentenv/site-proxy.log") + finally: + report = await teardown_run(context) + + assert through[public].startswith("200 ") and "502" in through[nowhere], through + assert seen[public]["title"].startswith("GitHub") and not seen[public]["error"], seen + entries = [json.loads(line) for line in logged.splitlines() if line.startswith("{")] + github = [entry["connection"] for entry in entries if entry.get("connection", {}).get("host") == "github.com"] + assert github and all(entry["bytes_received"] > 0 for entry in github), logged[-2000:] + assert any(entry.get("failed", {}).get("host") == "agentenv-no-such-host.invalid" for entry in entries), logged[-2000:] + assert not report.failed + + async def _kill(deployed, pattern: str, oldest: bool = False) -> None: """SIGKILL the newest, or oldest, process matching ``pattern``, a second after computer-exec has answered, since the driver that runs the command may be the one killed.""" diff --git a/tst/unit/env/envs/test_computer_site_proxy.py b/tst/unit/env/envs/test_computer_site_proxy.py index a6e28d6b8..a25492f71 100644 --- a/tst/unit/env/envs/test_computer_site_proxy.py +++ b/tst/unit/env/envs/test_computer_site_proxy.py @@ -16,6 +16,7 @@ import struct import subprocess import sys +import time import urllib.error from datetime import timedelta from pathlib import Path @@ -32,6 +33,8 @@ from agent_env.env.envs.computer.utils.site_proxy import Config, Site, SiteProxy from agent_env.env.gateway.constants import AGENT_ENV_SITE_ROOT_HEADER from agent_env.env.gateway.gateway import Gateway +from tst.unit.env.envs.test_computer_stand_in_proxy import _ask, _logged +from tst.unit.env.envs.test_computer_stand_in_proxy import _serving as _stand_in_serving from tst.unit.env.gateway.website_websocket_test import EchoSite pytestmark = pytest.mark.usefixtures("socket_enabled") @@ -351,7 +354,8 @@ async def test_a_request_in_a_sites_tunnel_naming_another_host_is_refused_and_lo assert start == "HTTP/1.1 403 Forbidden" and headers["x-agentenv-site-proxy"] == "failed" assert upstream.requests == [] - assert "site proxy: refused GET evil.test: no site of this computer" in capsys.readouterr().err + assert _logged(capsys.readouterr().err, "refused") == [ + {"method": "GET", "host": "evil.test", "reason": "no site of this computer"}] @pytest.mark.asyncio @@ -389,7 +393,8 @@ async def test_the_forward_port_refuses_any_other_host_at_once_and_logs_it(tmp_p assert body == f"{named} is no site of this computer, and the browser reaches its sites alone\n".encode() assert upstream.requests == [] method = request_line.split(b" ")[0].decode() - assert f"site proxy: refused {method} {named}: no site of this computer" in capsys.readouterr().err + assert _logged(capsys.readouterr().err, "refused") == [ + {"method": method, "host": named, "reason": "no site of this computer"}] @contextlib.contextmanager @@ -410,7 +415,7 @@ async def open_connection(host, port, **kwargs): @pytest.mark.asyncio async def test_the_forward_port_tunnels_a_live_sites_host_straight_to_it_and_sends_its_url_on_as_a_path( - tmp_path, monkeypatch): + tmp_path, monkeypatch, capsys): async with Upstream() as upstream, Upstream() as live: config, _ = _config(tmp_path, upstream.port) config.direct = ["github.com", "*.githubassets.com"] @@ -425,12 +430,88 @@ async def test_the_forward_port_tunnels_a_live_sites_host_straight_to_it_and_sen plain = await _exchange(port, b"GET http://github.com/a?b=1 HTTP/1.1\r\nHost: github.com\r\n" b"Proxy-Connection: keep-alive\r\n\r\n") plain[3][1].close() + await asyncio.sleep(0.3) # each connection is logged as it ends assert established.startswith(b"HTTP/1.1 200 ") and opened == [("github.githubassets.com", 8443), ("github.com", 80)] assert (tunnelled[0], tunnelled[2], plain[0], plain[2]) == ("HTTP/1.1 200 OK", b"hello", "HTTP/1.1 200 OK", b"hello") assert [request[0] for request in live.requests] == ["GET /x HTTP/1.1", "GET /a?b=1 HTTP/1.1"] assert live.requests[1][1]["connection"] == "close" and "proxy-connection" not in live.requests[1][1] - assert upstream.requests == [] + assert live.requests[1][1]["host"] == "github.com" and upstream.requests == [] + logged = _logged(capsys.readouterr().err, "connection") + assert [(entry["host"], entry["port"], entry["address"]) for entry in logged] == [ + ("github.githubassets.com", 8443, "127.0.0.1"), ("github.com", 80, "127.0.0.1")] + assert all(entry["bytes_sent"] > 0 and entry["bytes_received"] > 0 and entry["duration_s"] >= 0 for entry in logged) + + +@pytest.mark.asyncio +async def test_a_live_host_that_doesnt_answer_in_time_is_a_502_and_logged(tmp_path, monkeypatch, capsys): + monkeypatch.setattr(site_proxy, "UPSTREAM_TIMEOUT_S", 0.5) + real_open = asyncio.open_connection + + async def hangs(host, port, **kwargs): + if host == "127.0.0.1": + return await real_open(host, port, **kwargs) + await asyncio.sleep(60) + + async with Upstream() as upstream: + config, _ = _config(tmp_path, upstream.port) + config.direct = ["github.com"] + monkeypatch.setattr(site_proxy.asyncio, "open_connection", hangs) + async with _forward_port(config) as port: + began = time.monotonic() + answer = await _exchange(port, b"CONNECT github.com:443 HTTP/1.1\r\nHost: github.com:443\r\n\r\n") + took = time.monotonic() - began + + assert answer[0] == "HTTP/1.1 502 Bad Gateway" and answer[1]["x-agentenv-site-proxy"] == "failed" and took < 1.2 + [failed] = _logged(capsys.readouterr().err, "failed") + assert failed == {"method": "CONNECT", "host": "github.com", "port": 443, "reason": "no answer", + "error": "TimeoutError"} + assert answer[2] == b"github.com:443 didn't answer\n" + + +@pytest.mark.asyncio +async def test_both_proxies_log_a_connection_and_each_way_one_fails_in_the_same_json_lines(tmp_path, monkeypatch, + capsys): + """The stand-in a browser alone uses and the forward port's tunnel to a live site's hosts write the same records: + each line JSON, a ``connection`` with the same fields, and a ``failed`` with the same fields and reason, whichever + proxy a run took.""" + requests = [b"GET http://site.test/ HTTP/1.1\r\nHost: site.test\r\n\r\n", + b"CONNECT nowhere.test:443 HTTP/1.1\r\nHost: nowhere.test:443\r\n\r\n", + b"CONNECT slow.test:443 HTTP/1.1\r\nHost: slow.test:443\r\n\r\n"] + with _stand_in_serving(monkeypatch, names={"nowhere.test": [], "slow.test": ["140.82.112.9"]}, + acts={"140.82.112.9": "hangs"}, CONNECT_TIMEOUT_S=0.3) as stand_in: + for request in requests: + _ask(stand_in.port, request) + stand_in_log = capsys.readouterr().out + + monkeypatch.setattr(site_proxy, "UPSTREAM_TIMEOUT_S", 0.3) + real_open = asyncio.open_connection + + async def open_connection(host, port, **kwargs): + if host == "nowhere.test": + raise socket.gaierror(-2, "Name or service not known") + if host == "slow.test": + await asyncio.sleep(60) + return await real_open("127.0.0.1", port if host == "127.0.0.1" else live.port, **kwargs) + + async with Upstream() as upstream, Upstream() as live: + config, _ = _config(tmp_path, upstream.port) + config.direct = ["site.test", "nowhere.test", "slow.test"] + monkeypatch.setattr(site_proxy.asyncio, "open_connection", open_connection) + async with _forward_port(config) as port: + for request in requests: + answer = await _exchange(port, request) + answer[3][1].close() + await asyncio.sleep(0.3) # each connection is logged as it ends + shared_log = capsys.readouterr().err + + def shape(log: str) -> list: + return [(kind, sorted(record), record.get("reason")) for entry in _logged(log) for kind, record in entry.items()] + + assert sorted(shape(stand_in_log)) == sorted(shape(shared_log)) == [ + ("connection", ["address", "bytes_received", "bytes_sent", "duration_s", "host", "port", "started"], None), + ("failed", ["error", "host", "method", "port", "reason"], "doesn't resolve"), + ("failed", ["error", "host", "method", "port", "reason"], "no answer")] @pytest.mark.asyncio diff --git a/tst/unit/env/envs/test_computer_stand_in_proxy.py b/tst/unit/env/envs/test_computer_stand_in_proxy.py new file mode 100644 index 000000000..7e7728ec5 --- /dev/null +++ b/tst/unit/env/envs/test_computer_stand_in_proxy.py @@ -0,0 +1,216 @@ +"""The headless base's stand-in proxy on 3128, a browser alone's route out with no site routing: it forwards any +host, HTTP and CONNECT alike, without decrypting and refusing nothing, the sandbox's network policy deciding where it +can go; it bounds every wait, and logs each connection, and each one that fails, as a JSON line. The proxy is a +network program, so these tests open sockets, on loopback alone.""" + +from __future__ import annotations + +import contextlib +import importlib.util +import json +import os +import resource +import socket +import threading +import time +from pathlib import Path +from types import SimpleNamespace + +import pytest + +import agent_env + +pytestmark = pytest.mark.usefixtures("socket_enabled") + +STAND_IN = Path(agent_env.__file__).parent / "computers" / "artifacts" / "ubuntu-24.04-headless" / "site-proxy.py" +GITHUB = "140.82.112.3" +OK = b"HTTP/1.1 200 OK\r\nContent-Length: 5\r\nConnection: close\r\n\r\nhello" + + +def _stand_in(): + spec = importlib.util.spec_from_file_location("headless_site_proxy", STAND_IN) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +def _accepting(server: socket.socket, each) -> None: + """``each`` run on every connection ``server`` accepts, on a thread of its own, until it closes.""" + def run(): + while True: + try: + conn, _ = server.accept() + except OSError: + return + each(conn) + + threading.Thread(target=run, daemon=True).start() + + +@contextlib.contextmanager +def _serving(monkeypatch, names: dict | None = None, acts: dict | None = None, **settings): + """The stand-in serving on a free port, with its module's ``settings`` set first. Each of ``names`` resolves to the + addresses it gives (none: it doesn't resolve), ``site.test`` to one of GitHub's unless given. A connection to an + address off loopback acts as ``acts`` says, ``"refuses"``, ``"hangs"`` (for its whole timeout) or ``"never + reads"``, else lands on a local upstream that answers each request with ``OK``. Yields the port, each address and + port the proxy connected to, what the upstream read, and the upstream's own port.""" + module = _stand_in() + for name, value in settings.items(): + monkeypatch.setattr(module, name, value) + names, acts = {"site.test": [GITHUB], **(names or {})}, acts or {} + real_resolve, real_connect = socket.getaddrinfo, socket.create_connection + upstream, sink = socket.create_server(("127.0.0.1", 0)), socket.create_server(("127.0.0.1", 0)) + read, opened, held = [], [], [] + + def answer(conn): + with conn: + read.append(conn.recv(65536)) + conn.sendall(OK) + + def getaddrinfo(host, port, *args, **kwargs): + if host not in names: + return real_resolve(host, port, *args, **kwargs) + if not names[host]: + raise socket.gaierror(-2, "Name or service not known") + return [(socket.AF_INET, socket.SOCK_STREAM, 6, "", (address, port)) for address in names[host]] + + def create_connection(address, *args, **kwargs): + if address[0] in ("127.0.0.1", "localhost"): + return real_connect(address, *args, **kwargs) + opened.append(address) + if (act := acts.get(address[0])) == "refuses": + raise ConnectionRefusedError(f"{address[0]} refused") + if act == "hangs": + time.sleep(kwargs.get("timeout") or 0) + raise TimeoutError("timed out") + return real_connect((sink if act == "never reads" else upstream).getsockname(), *args, **kwargs) + + monkeypatch.setattr(module.socket, "getaddrinfo", getaddrinfo) + monkeypatch.setattr(module.socket, "create_connection", create_connection) + _accepting(upstream, answer) + _accepting(sink, held.append) + server = module.Server(("127.0.0.1", 0), module.Proxy) + threading.Thread(target=server.serve_forever, daemon=True).start() + try: + yield SimpleNamespace(port=server.server_address[1], opened=opened, read=read, + upstream_port=upstream.getsockname()[1]) + finally: + server.shutdown() + upstream.close() + sink.close() + + +@pytest.fixture +def proxy(monkeypatch): + with _serving(monkeypatch) as serving: + yield serving + + +def _ask(port: int, request: bytes, then: bytes = b"") -> bytes: + """What the proxy answers ``request``, and in a tunnel it opened, ``then``.""" + with socket.create_connection(("127.0.0.1", port), timeout=10) as conn: + conn.sendall(request) + answer = conn.recv(65536) + if then and answer.startswith(b"HTTP/1.1 200"): + conn.sendall(then) + while chunk := conn.recv(65536): + answer += chunk + return answer + + +def _logged(text: str, kind: str | None = None) -> list[dict]: + """A proxy's log, every line of which is JSON: each line's record, or, given ``kind`` (``connection``, + ``failed``, ...), the records of that kind.""" + entries = [json.loads(line) for line in text.splitlines() if line.strip()] + return entries if kind is None else [entry[kind] for entry in entries if kind in entry] + + +def test_the_stand_in_tunnels_and_forwards_a_public_host_and_logs_each_connection(proxy, capsys): + tunnelled = _ask(proxy.port, b"CONNECT site.test:443 HTTP/1.1\r\nHost: site.test:443\r\n\r\n", + then=b"GET / HTTP/1.1\r\nHost: site.test\r\n\r\n") + forwarded = _ask(proxy.port, b"GET http://site.test/a?b=1 HTTP/1.1\r\nHost: site.test\r\n" + b"Proxy-Connection: keep-alive\r\n\r\n") + + assert tunnelled.startswith(b"HTTP/1.1 200 Connection established") and tunnelled.endswith(b"hello"), tunnelled + assert forwarded.startswith(b"HTTP/1.1 200 OK") and forwarded.endswith(b"hello"), forwarded + assert proxy.opened == [(GITHUB, 443), (GITHUB, 80)] + assert proxy.read[0] == b"GET / HTTP/1.1\r\nHost: site.test\r\n\r\n" + assert proxy.read[1].startswith(b"GET /a?b=1 HTTP/1.1\r\n") and b"Host: site.test" in proxy.read[1] + assert b"Proxy-Connection" not in proxy.read[1] and b"Connection: close" in proxy.read[1] + logged = _logged(capsys.readouterr().out, "connection") + assert [(entry["host"], entry["port"], entry["address"]) for entry in logged] == [ + ("site.test", 443, GITHUB), ("site.test", 80, GITHUB)] + assert all(entry["bytes_sent"] > 0 and entry["bytes_received"] > 0 for entry in logged), logged + assert all(set(entry) >= {"started", "duration_s"} for entry in logged) + + +def test_the_stand_in_refuses_nothing_it_reaches_the_computers_own_loopback_and_an_internal_address_alike(proxy): + own = _ask(proxy.port, f"GET http://127.0.0.1:{proxy.upstream_port}/page HTTP/1.1\r\nHost: x\r\n\r\n".encode()) + private = _ask(proxy.port, b"GET http://10.0.0.1/ HTTP/1.1\r\nHost: x\r\n\r\n") + + assert own.startswith(b"HTTP/1.1 200 OK") and private.startswith(b"HTTP/1.1 200 OK"), (own, private) + assert proxy.read[0].startswith(b"GET /page HTTP/1.1") and proxy.opened == [("10.0.0.1", 80)] + + +def test_the_stand_in_answers_a_name_that_doesnt_resolve_at_once_and_logs_it(monkeypatch, capsys): + with _serving(monkeypatch, names={"nowhere.test": []}) as proxy: + answer = _ask(proxy.port, b"CONNECT nowhere.test:443 HTTP/1.1\r\nHost: nowhere.test:443\r\n\r\n") + + assert answer.startswith(b"HTTP/1.1 502 ") and b"nowhere.test doesn't resolve" in answer, answer + assert b"X-Agentenv-Site-Proxy: failed" in answer and proxy.opened == [] + [failed] = _logged(capsys.readouterr().out, "failed") + assert (failed["reason"], failed["error"]) == ("doesn't resolve", "gaierror: [Errno -2] Name or service not known") + + +@pytest.mark.parametrize("first", ["refuses", "hangs"]) +def test_the_stand_in_tries_a_names_addresses_in_turn_within_one_deadline_for_them_all(monkeypatch, capsys, first): + with _serving(monkeypatch, names={"site.test": [GITHUB, "140.82.112.4"]}, acts={GITHUB: first}, + CONNECT_TIMEOUT_S=0.5) as proxy: + began = time.monotonic() + answer = _ask(proxy.port, b"GET http://site.test/ HTTP/1.1\r\nHost: site.test\r\n\r\n") + took = time.monotonic() - began + + if first == "refuses": + assert answer.startswith(b"HTTP/1.1 200 OK") and proxy.opened == [(GITHUB, 80), ("140.82.112.4", 80)], answer + else: + assert answer.startswith(b"HTTP/1.1 502 ") and b"site.test:80 didn't answer" in answer, answer + assert proxy.opened == [(GITHUB, 80)] and took < 1.5, (proxy.opened, took) + [failed] = _logged(capsys.readouterr().out, "failed") + assert (failed["reason"], failed["error"]) == ("no answer", "TimeoutError: timed out") + + +def test_the_stand_in_relays_a_connection_whose_sockets_are_numbered_past_1023(proxy): + soft, hard = resource.getrlimit(resource.RLIMIT_NOFILE) + if hard != resource.RLIM_INFINITY and hard < 1400: + pytest.skip(f"this machine allows {hard} open files, too few to number a socket past 1023") + resource.setrlimit(resource.RLIMIT_NOFILE, (max(soft, 1400) if hard == resource.RLIM_INFINITY else + min(max(soft, 1400), hard), hard)) + held = [os.pipe() for _ in range(520)] + try: + answer = _ask(proxy.port, b"CONNECT site.test:443 HTTP/1.1\r\nHost: site.test:443\r\n\r\n", + then=b"GET / HTTP/1.1\r\nHost: site.test\r\n\r\n") + finally: + for pair in held: + os.close(pair[0]) + os.close(pair[1]) + resource.setrlimit(resource.RLIMIT_NOFILE, (soft, hard)) + + assert answer.startswith(b"HTTP/1.1 200 Connection established") and answer.endswith(b"hello"), answer + assert proxy.opened == [(GITHUB, 443)] + + +def test_the_stand_in_ends_a_tunnel_whose_server_stopped_reading_instead_of_waiting_on_it_for_ever(monkeypatch, capsys): + with _serving(monkeypatch, acts={GITHUB: "never reads"}, IDLE_S=1) as proxy: + with socket.create_connection(("127.0.0.1", proxy.port), timeout=20) as conn: + conn.sendall(b"CONNECT site.test:443 HTTP/1.1\r\nHost: site.test:443\r\n\r\n") + assert conn.recv(4096).startswith(b"HTTP/1.1 200") + began, ended = time.monotonic(), None + try: + while time.monotonic() - began < 20: + conn.sendall(b"x" * 65536) + except OSError: + ended = time.monotonic() - began + + assert ended is not None and ended < 15, ended + [logged] = _logged(capsys.readouterr().out, "connection") + assert logged["host"] == "site.test" and logged["bytes_sent"] > 0