gru/RustProxy
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.34.0_fina;

Browse Source
This commit is contained in:
Mateusz Gruszczyński committed 2026-10-18 12:00:59 +02:00
1 parent 1ca019d849
commit c207e8a03f
69 files changed
+1496 -13838
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

AGENTS.md
+21 -75
View File
@@ -1,83 +1,29 @@
# RustProxy implementation rules
# RustProxy source and documentation maintenance
Read README.md, ROADMAP.md and docs/TEST_REPORT.md before making changes.
The project name is RustProxy; the Cargo package/binary remains `rust-proxy` for
compatibility. Current source version: 0.34.0.
Current source version: **0.34.0**. The Cargo package and binary are named `rust-proxy`.
## Delivery
Before editing, read [README.md](README.md), [ROADMAP.md](ROADMAP.md), the relevant [documentation guide](docs/README.md) 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.
Maintain English documentation and Markdown files. Keep translations in discovered langs/*.json packs, with en_US as fallback. Never hardcode a two-language switch. Preserve the existing logo.
CHANGELOG.md uses version headings with no release dates. Patch increments may be
bundled; substantial optional integrations raise the minor version. 0.7.0 adds managed renewal, server deployment helpers, Basic Auth and visual locations. The reported compression threshold type mismatch is removed without narrowing. Cloudflare Tunnel and Docker discovery are deferred.
## Keep documentation in sync
Deliver a complete archive with dev.sh and the existing tests. Keep verification results outside the repository; do not add iteration reports, standalone benchmark scripts, or micro-optimization notes to CHANGELOG.md.
Do not include databases, credentials, real certificates/keys, target directories,
node_modules or fabricated Cargo.lock content. Preserve an actually resolved
lockfile when a compiler-enabled environment can produce it.
- 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](docs/README.md), [changelog](CHANGELOG.md), 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
## Engineering safeguards
Keep proxy traffic independent from control-plane database queries and providers.
Use async I/O, streaming bodies, bounded DNS work, bounded queues and explicit
cancellation. Hold request and connection permits through full body/tunnel lifetimes.
Run ACLs before opening OR reusing an upstream connection. Resolve only configured
backend origins; validate every DNS answer and use the validated addresses directly.
Backend TLS certificate verification defaults OFF when `tls_verify` is omitted for vhost
backends. Administrators may explicitly enable chain/identity verification per HTTPS backend.
This compatibility default is limited to application backends: never widen it to Tinyauth or
other verifier clients. Disabling verification must not weaken backend address/DNS/loop/control-
plane protections.
- 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.
Preserve the explicit auth module path and upgrade regression coverage. Replace
managed source directories instead of leaving obsolete modules during upgrades.
Keep administrator intent, provider observations and live connection state separate.
Hot changes must publish validated, immutable snapshots after a successful revisioned
SQLite write. Invalid updates leave the old snapshot active.
## Verification and delivery
## Verification
Keep production Rust source files within 500 lines. Rust unit and integration
**test files are exempt** from this limit: do not create numbered `part_XX.rs`
fragments to satisfy source-size checks. Consolidate coherent test suites in
`tests.rs` and preserve the existing test cases.
Run `./dev.sh check` and `./dev.sh test` when Rust is available. Run
existing SQL and upgrade checks when available; do not restore removed auxiliary scripts. UI tests use a simulated API; the Python protocol-peer
self-test is not a test of RustProxy. Record these distinctions accurately.
Do not mark a stage accepted or production-ready on the basis of static inspection.
Review real protocol behavior, restored data and resource bounds before expanding
scope. Do not expand provider work ahead of the core real-runtime acceptance gate. Keep that gate explicitly open until Rust runs.
## Vhost invariants
Use the accepted socket's actual local address and TLS state for frontend selection;
never infer a private binding or sticky identity from forwarding headers. Vhosts receive
frontend sockets only through `frontend.listener_ids` referencing `listeners.endpoints`.
Keep hostname ownership unambiguous. Socket/ALPN changes require restart, with actual
and desired plans visible.
Keep health observations separate from desired configuration. Preserve observations
only for compatible members; re-enabled/changed origins require new health checks.
Keep backend leases through request/response/tunnel completion. Do not replay failed
writes to another backend. Cookies are routing affinity, never authentication. Health
probes must use the same origin/DNS policy, bounded concurrency and cancellation.
Retain HTTP/1.1 in TLS Auto negotiation; require H2 in explicit HTTPS H2 mode,
and do not implement fallback by replaying traffic.
## Vhost configuration invariants
The pre-production route/inline-listener compatibility importer has been removed.
Persist only the current vhost document and named listener references; old documents
must fail validation instead of being silently converted. Keep path-pinned origins
distinct from balanced pools. Do not silently widen listener bindings.
ACME secrets belong in private credentials files, not SQLite, stdout, argv or API.
HTTP-01 only serves bounded tokens for domains in the active job. No CA call on boot.
The exporter checks actual peer CIDRs and is disabled by default; secret configuration
stores a variable name, never a token. Keep metric labels bounded by configuration.
## Administration access regression gate (0.8.1)
No new public admin routes without updating the exact method/path allowlist and
access tests. Operational assets and the OpenAPI schema are private. Keep the
public login document/bundle separate from the dashboard. Documentation uses
the existing cookie session/CSRF, not a second auth mechanism. Preserve the pinned
Swagger build configuration and keep external validators/CDNs disabled.
- 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.