87 lines
4.7 KiB
Markdown
87 lines
4.7 KiB
Markdown
# Application scripts
|
|
|
|
This directory contains scripts coupled to RustProxy application/build/deployment behavior.
|
|
External development and QA helpers live under `tools/`; external platform integrations live under `integrations/`.
|
|
|
|
- `runtime/` - application-owned helpers embedded or invoked by RustProxy (`acme_provider.py`).
|
|
- `build/` - build-time asset preparation used by `build.rs`.
|
|
- `deploy/` - install/update and stopped source-tree upgrade implementation.
|
|
- `migration/` - application migration utilities, currently the Nginx Proxy Manager importer.
|
|
|
|
Keep these paths stable because Rust source, `build.rs` and shell entry points reference them directly.
|
|
|
|
## Panel stylesheet sources
|
|
|
|
The dashboard stylesheet lives in `src/admin/web/css/`, with its complete cascade
|
|
order declared in `manifest.json`. Edit those modules, not a generated bundle.
|
|
`build.rs` invokes `build/panel_css.py` using Python 3.10+ (or
|
|
`RUST_PROXY_PYTHON`) and embeds the compact `OUT_DIR/panel-style.css`. Login and
|
|
the dashboard continue to load one fingerprinted stylesheet, using the existing
|
|
panel compression and access rules; no npm install or runtime CSS imports are
|
|
needed. The documentation page retains its separate `src/admin/web/docs.css`.
|
|
|
|
```bash
|
|
python3 scripts/build/panel_css.py --check
|
|
python3 tools/dev/test_panel_css.py
|
|
python3 scripts/audit_css_usage.py --strict
|
|
```
|
|
|
|
The first two commands use only the Python standard library. The optional
|
|
selector/structure audit needs `tinycss2` and `cssselect2`; it checks all manifest
|
|
modules together and reviews the documentation stylesheet separately. Use
|
|
`--json PATH` for selector references and `--structure-json PATH` for repeated
|
|
selectors, conditional blocks, properties and identical declaration blocks.
|
|
Missing class tokens are review candidates: classes assembled by JavaScript
|
|
must be checked before deleting their styles. Strict mode also rejects identical
|
|
declaration bodies within a compatible selector family. It permits separate
|
|
standard/WebKit/Gecko rules only when joining them would create an incompatible
|
|
vendor selector list. Choose shared-rule placement by checking the cascade,
|
|
not by mechanically moving every matching block to the beginning of a module.
|
|
|
|
Preflight rejects missing, repeated or unlisted CSS modules and stale monolithic
|
|
`style.css` files. `./dev.sh repair` backs up only the exact original 0.34.9
|
|
monolith; custom or unknown content requires manual review and is never moved
|
|
or discarded automatically. Rebuild the Rust binary after changing CSS.
|
|
|
|
Keep `scripts/__init__.py` and `scripts/build/__init__.py` in the source package.
|
|
They keep preflight, audit, tests and packaging imports local even when unrelated
|
|
Python packages named `scripts` or `build` are installed. An older CSS-refactor
|
|
archive without the build marker can fail
|
|
with `ModuleNotFoundError: No module named 'build.panel_css'`; restore the marker
|
|
from the complete source archive and run `bash dev.sh repair` again. Installing
|
|
another Python package is not required.
|
|
|
|
### Missing generated CSS during Rust compilation
|
|
|
|
`panel-style.css` is generated inside Cargo's `OUT_DIR`. `bash dev.sh repair`
|
|
validates the source layout and preserves known obsolete files; it does not
|
|
generate Cargo outputs. Preflight also checks that the current `build.rs` calls
|
|
the panel generator from `main` and reports a mixed source tree before Cargo.
|
|
|
|
After overlaying a source ZIP onto a previously built checkout, a compiler error
|
|
for a missing `OUT_DIR/panel-style.css` can indicate an old cached build script
|
|
or a `build.rs` from another source version. Restore the complete matching
|
|
archive, including the root `build.rs`, then run from the project root:
|
|
|
|
```bash
|
|
bash dev.sh repair
|
|
touch build.rs
|
|
bash dev.sh build
|
|
```
|
|
|
|
The source ZIP uses reproducible timestamps. Cargo's
|
|
[build-script change detection](https://doc.rust-lang.org/cargo/reference/build-scripts.html#change-detection)
|
|
uses file modification times, so refreshing `build.rs` forces regeneration after
|
|
an archive overlay. This works with the target directory selected by `dev.sh`.
|
|
The generator now also registers its output as a watched Cargo dependency and
|
|
recreates a removed bundle. An identical bundle keeps its modification time.
|
|
The Rust build script rejects a missing, empty or non-file output immediately
|
|
after the helper returns.
|
|
|
|
## Stream TCP/UDP test helpers
|
|
|
|
- `start_stream_backends.sh` — launches two TCP echo mocks (9101, 9102) and two UDP echo/probe mocks (9201, 9202), defaulting to loopback, and terminates all on Ctrl+C.
|
|
- `test_stream_tcp.py`, `test_stream_udp.py` — independent `server`, `client` and `selftest` modes. See `docs/STREAMS.md` for RustProxy listener setup and test commands.
|
|
|
|
The selftests test only Python mock peers, **not** RustProxy forwarding.
|