Skip to content

Set up Cloud Agent dev environment + document caveats in AGENTS.md #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
arloor wants to merge 1 commit into from
Closed

Set up Cloud Agent dev environment + document caveats in AGENTS.md #39

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,3 +84,23 @@ This guide helps Codex/agents contribute safely and consistently to this reposit
- Avoid destructive commands (`git reset --hard`, `rm -rf`) unless explicitly asked.
- Never delete or rewrite user changes you did not make.
- Ask for confirmation before behavior-changing refactors.

## Cursor Cloud specific instructions
These notes cover non-obvious caveats for this repo in the Cloud Agent VM. Standard build/lint/test/run commands live in the `Quick Start` / `Standard Workflows` sections above; use those.

### Toolchain
- The crate is `edition = "2024"` (MSRV `1.85.0`), so it needs Rust >= 1.85. The base image ships an older system `rustc` (1.83), so the environment sets rustup's `stable` toolchain as the default (`rustup default stable`). Just use `cargo` normally; do not fall back to the 1.83 toolchain.
- Default features are `aws_lc_rs` + `mimalloc`; `aws_lc_rs` needs `cmake` + a C toolchain (already present). No OpenSSL is used.

### Lint caveats
- Plain `cargo clippy -- -D warnings` (lib + bins) is clean.
- `cargo clippy --all-targets --all-features` pulls in the optional `bpf*` features, which build `libbpf` from source and need extra system packages (`autoconf autopoint flex bison gawk clang pkg-config make libelf-dev zlib1g-dev`, installed in this environment). Without them it fails with `autoreconf is required to compile libbpf-sys`.
- `cargo clippy --all-targets ...` (i.e. including the test target) currently fails because `#![deny(clippy::unwrap_used)]` flags an existing `.unwrap()` in a `#[cfg(test)]` test in `rust_http_proxy/src/config.rs`. This is pre-existing (CI does not run clippy) — not an environment problem.

### Test caveats
- `cargo test` runs fully self-contained e2e tests (proxy + upstreams are spawned in-process; no external services needed).
- Known pre-existing failures: 6 HTTP/2-upstream e2e tests fail with `hyper::Error(Io, BrokenPipe)` (`reverse_proxy_e2e_tests` H2 cases, `forward_bypass_e2e_tests` mitm-h2 cases, `mitm_stub_e2e_tests` h2 cases). Trace logs show the proxy actually returns `200 OK`; the error is a race in HTTP/2 connection teardown. CI (`.github/workflows/combined_build.yml`) never runs `cargo test`, so this is ungated. The other 100 tests pass. Tests do not initialize the proxy logger — to debug, temporarily call `log_x::init_log("/tmp", "debug.log", "trace")` inside a test.

### Running the app
- Single self-contained binary; default port `3128` (README examples use `7788`). The MITM React console (`/mitm`) is pre-built and embedded via `rust-embed` from `mitm-ui/dist/` (committed), so no Node build is needed to run the proxy — Node is only needed to rebuild `mitm-ui`.
- Quick smoke test: `./target/debug/rust_http_proxy -p 7788 --web-content-path <dir> --users user:pass`, then static serving is `curl http://127.0.0.1:7788/`, forward proxy is `curl -x http://user:pass@127.0.0.1:7788 http://<origin>`, and metrics are `curl -u user:pass http://127.0.0.1:7788/metrics`. Without `--users`, the proxy/metrics/mitm endpoints are unauthenticated.