push

docs/ARCHITECTURE.md

@@ -1,46 +1,37 @@
 # Architecture
 
-## Release path
+## Components
 
-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.
+1. **Debian host** - Git polling, Docker engine, package assembly and optional publication.
+2. **Docker builder** - Rust 1.88, Clang/LLD and a verified FreeBSD 15.1 sysroot extracted from official `base.txz`.
+3. **OPNsense package** - `os-rustproxy-*.pkg`, installed directly with `pkg add -f`.
 
-The packaging repository deliberately contains no `app/` directory. This prevents stale application code from accidentally being packaged.
+No FreeBSD VM is used.
 
-## Upstream selection
+## Why the sysroot is enough for the binary build
 
-Default configuration:
+Rust provides `x86_64-unknown-freebsd`. Clang receives `--target=x86_64-unknown-freebsd15.1` and `--sysroot=/opt/freebsd-sysroot`, so Rust and C/assembly dependencies such as `ring` link against FreeBSD headers and libraries instead of Debian ones.
+
+The container is still Linux. It cannot execute the generated FreeBSD binary, so the pipeline performs Linux tests before cross-compilation and ELF inspection after cross-compilation. Runtime validation must happen on an OPNsense/FreeBSD test firewall.
+
+## Package construction
+
+FreeBSD pkg archives are compressed tar archives with metadata files beginning with `+` before package data. The Linux packager creates:
 
 ```text
-APP_REPO_URL=https://git.linuxiarz.pl/gru/RustProxy
-APP_REPO_REF=HEAD
++COMPACT_MANIFEST
++MANIFEST
+usr/local/...
 ```
 
-`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`.
+and compresses it with zstd to `.pkg`.
 
-## Why native FreeBSD for releases
+## Source isolation
 
-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.
+```text
+/opt/opn-rustproxy/packaging          packaging repository
+/opt/opn-rustproxy/source/RustProxy  dynamically fetched application
+/opt/opn-rustproxy/cache             Docker/Cargo cache
+```
 
-## 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.
+The exact RustProxy SHA and package version are written to `dist/BUILD-INFO.txt`.