first commit

docs/ARCHITECTURE.md

@@ -0,0 +1,46 @@
+# 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:
+
+```text
+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.