RustProxy/AGENTS.md

RustProxy source and documentation maintenance

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

Before editing, read README.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, feature list, 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.

Authentication provider extension contract

• Keep provider implementations isolated under src/<provider>/mod.rs and tests.rs; the request pipeline only sees the object-safe auth_provider::Provider trait and the single CompiledFrontend.auth_provider slot. Preserve existing Vhost JSON fields on upgrades.
• Prefer the shared forward_auth::Adapter transport for compatible HTTP verifiers, and reserve protected-host callback routes through reserved_path / serve_reserved only when required.
• Return fail-closed provider errors using auth_provider::gateway_failure and one src/admin/web/error_auth_provider.html template (with escaped provider names); never create a separate HTML file per vendor or expose backend diagnostics to clients. AuthenticationResponse prevents custom Vhost error pages from overriding auth errors/redirects, and Identity / CookieSink keep identities and cookies request-scoped.
• Keep the authentication provider/method selector in auth_provider/choice.rs separate from the shared OIDC integration transport. Extend the allowed provider/method combinations without duplicating OIDC protocol code. Accept legacy Vhost settings without a selector; when present, reject selectors inconsistent with enabled settings. Update the panel, mutual-exclusion validation, config compiler, OpenAPI, docs and tests together. Prove access/denial, redirects, header stripping, timeouts, and reserved routes with real verifiers before deployment.

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.