# 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.