rustproxy-opnsense-repo/docs/ARCHITECTURE.md

Architecture

Release path

1. Debian cron runs once per hour.
2. It refreshes the packaging repository containing this plugin/build logic.
3. Independently, it fetches APP_REPO_REF from https://git.linuxiarz.pl/gru/RustProxy into APP_WORKDIR.
4. It compares both current commits with the last successful build state.
5. If either commit changed, Debian rsyncs the packaging tree and the RustProxy checkout separately to a FreeBSD 15.1 amd64 builder.
6. FreeBSD reads the application version from the downloaded Cargo.toml, runs Cargo tests and a release build.
7. The binary is injected into opnsense-plugin/www/rustproxy/src/sbin/rust-proxy inside a clean checkout of the official OPNsense plugins tree.
8. make package creates os-rustproxy-<version>_<revision>.pkg.
9. pkg repo creates a signed package repository.
10. Debian downloads dist/ and optionally publishes it over rsync/SSH.
11. OPNsense consumes only the custom RustProxy package repository.

The packaging repository deliberately contains no app/ directory. This prevents stale application code from accidentally being packaged.

Upstream selection

Default configuration:

APP_REPO_URL=https://git.linuxiarz.pl/gru/RustProxy
APP_REPO_REF=HEAD

HEAD follows the repository's default branch. To freeze releases, set APP_REPO_REF to a branch, tag or other fetchable ref. The exact commit used for each package is written to dist/BUILD-INFO.txt.

Why native FreeBSD for releases

Rust can cross-compile to x86_64-unknown-freebsd, but a release also needs the target ABI and FreeBSD/OPNsense packaging behavior. A native FreeBSD builder makes both the Rust link step and pkg metadata/catalog generation match the target platform. The Docker/cross path is intended for fast developer validation only.

OPNsense plugin behavior

The first UI version exposes only general.enabled.

• Enabled: the service controller renders configuration and starts RustProxy through configd.
• Disabled: the service controller stops RustProxy.
• Boot: an OPNsense syshook regenerates configuration and starts the service only when enabled.

RustProxy runs as the unprivileged rustproxy user. Its data is stored in /var/db/rustproxy and logs in /var/log/rustproxy/rustproxy.log.

Ports 80 and 443

The MVP does not run RustProxy as root. Keep initial listeners above port 1023. If public 80/443 is required later, prefer an explicit PF redirect from 80/443 to high RustProxy listener ports instead of running the whole proxy as root.