RustProxy/AGENTS.md

RustProxy source and documentation maintenance

Current source version: 0.34.9. The Cargo package and binary are named rust-proxy.

Before editing, read README.md, ROADMAP.md, the relevant documentation guide and the actual code and tests. Historical release experiments are not current specifications. Use the bundled src/admin/openapi.json for API routes and payloads; the source implementation is authoritative for runtime behavior.

Keep documentation in sync

• Write product documentation in English. Prefer focused instructions: purpose, configuration, defaults, restrictions, verification and common failures. Keep change history technical but user/operator-facing, not a series of profiling notes.
• Update the guide, docs index, changelog, embedded Reader registry (src/admin/documentation/documents.rs) and API schema/tests together when functionality changes.
• Reader Markdown is compiled into the binary using include_str!. Renaming/deleting a guide without updating the registry breaks compilation. Avoid broken relative links.
• Keep per-component optional defaults accurate (for example COLD off, Prometheus off, backend tls_verify off unless explicitly set, and optional Web Server sendfile off). Mark source-only or untested changes accordingly.
• Maintain existing langs/*.json packs; build.rs discovers available locales. Do not add credentials, databases, real certificates, environment secrets or build artifacts to source archives.

Engineering safeguards

• Keep proxy traffic independent of control-plane database/provider calls. Prefer asynchronous streaming, bounded queues, resource limits and explicit cancellation. Hold backend permits for the entire body or tunnel lifetime.
• Run access rules before connecting to or reusing an upstream. Resolve only configured origin hosts; validate resolved addresses before use. Preserve controls against loopback/private/control-plane destinations unless explicitly authorized.
• Backend TLS verification's compatibility default must not weaken certificate verification for external authentication/integration clients. Preserve validation of Host, listener, authority, forwarded identity, IP/ACL and control-plane access.
• Vhosts bind to named frontends via listener IDs; never derive listener identity from spoofable forwarding headers. Listener and transport changes can require a restart. Health status is observation, not desired configuration.
• Keep HOT/COLD cache privacy, freshness, validators, scoped invalidation and persistent format compatibility. Do not expose cached private content across hosts, credentials, cookies, or Vary dimensions.
• Preserve administrator session, CSRF, Host/Origin, certificate-scoped credentials and the authenticated offline documentation/OpenAPI assets. Do not expose private API routes without updating access tests.
• Preserve safe deployment/upgrade behavior: stop or reject incompatible legacy layouts, validate changes before activation, respect data/secrets outside the source tree, and keep full encrypted recovery usable.

Verification and delivery

• Run python3 scripts/preflight.py and documentation/link checks after restructuring documentation. When Rust is available, run ./dev.sh check and ./dev.sh test; run platform/protocol and restore tests before claiming production readiness.
• Python mock origins or static source inspection do not constitute testing of the real RustProxy binary. Record verification limits; do not claim measured performance gains from source changes.
• Ship complete reproducible source archives with make_zip.py, SHA256SUMS, the application scripts, current tests and docs. Never ship live state, private keys or generated build directories. Keep the technical deep-history backup outside the authenticated documentation Reader.