diff --git a/deploy/Dockerfile.toolchain b/deploy/Dockerfile.toolchain index 9d6b887..0e517a5 100644 --- a/deploy/Dockerfile.toolchain +++ b/deploy/Dockerfile.toolchain @@ -40,6 +40,27 @@ RUN GOBIN=/usr/local/bin go install "google.golang.org/protobuf/cmd/protoc-gen-g # the toolchain image rather than a host prerequisite. RUN GOBIN=/usr/local/bin go install "github.com/tc-hib/go-winres@v${GO_WINRES_VERSION}" +# Optional compact release packaging. Keep this after the Go tooling so adding +# the packer does not invalidate those expensive cached build layers. +ARG UPX_VERSION=5.2.1 +ARG UPX_AMD64_SHA256=402162aad30af47e60dbd767fb2e64ca394ace9727ba1f40283641f1d1b91657 +ARG UPX_ARM64_SHA256=a72d112c5970a904a31da0b9c84f919bc16b9a311787c12245508544a78c7d36 +RUN apt-get update \ + && apt-get install -y --no-install-recommends xz-utils \ + && rm -rf /var/lib/apt/lists/* \ + && case "${TARGETARCH}" in \ + amd64) upx_sha="${UPX_AMD64_SHA256}" ;; \ + arm64) upx_sha="${UPX_ARM64_SHA256}" ;; \ + *) echo "unsupported UPX host architecture: ${TARGETARCH}" >&2; exit 1 ;; \ + esac \ + && curl --fail --location --retry 3 --connect-timeout 15 --max-time 180 \ + "https://github.com/upx/upx/releases/download/v${UPX_VERSION}/upx-${UPX_VERSION}-${TARGETARCH}_linux.tar.xz" \ + -o /tmp/upx.tar.xz \ + && echo "${upx_sha} /tmp/upx.tar.xz" | sha256sum -c - \ + && tar -xJf /tmp/upx.tar.xz -C /usr/local/bin --strip-components=1 \ + "upx-${UPX_VERSION}-${TARGETARCH}_linux/upx" \ + && rm /tmp/upx.tar.xz + RUN mkdir -p /cache/go-build /cache/go/pkg/mod /cache/xdg /workspace \ && chown -R 1001:1001 /cache /workspace diff --git a/docs/dependency-decisions.md b/docs/dependency-decisions.md index aa494b5..538027f 100644 --- a/docs/dependency-decisions.md +++ b/docs/dependency-decisions.md @@ -8,6 +8,7 @@ All versions are exact in `go.mod`, generated code, or the toolchain image. | coder/websocket 1.8.15 | Context-aware WebSocket server/client transport | Maintained Go WebSocket implementation with bounded message reads and explicit Ping support; RVBox keeps protobuf validation, session fencing, origin policy, and backpressure in its own code. | | Buf 1.72.0 | Protobuf formatting, linting, and deterministic generation | Current stable release when the v1 implementation began; installed only in the toolchain image. | | protoc 35.0 | Protobuf compiler and well-known includes | Pinned archive with a checked SHA-256; included even though normal generation is driven by Buf. | +| UPX 5.2.1 | Optional compact Windows release packaging | Official AMD64/ARM64 Linux archives pinned by SHA-256 in the Docker toolchain. Opt-in LZMA packing preserves resources/relocations, retains an unpacked fallback, and runs before signing. Native runtime acceptance is still required. | | protobuf-go 1.36.12 | Go protobuf runtime and generator | Official maintained Go protobuf implementation. | | protoc-gen-go-grpc 1.6.2 | Go gRPC generator | Official maintained gRPC-Go generator. | | google/uuid 1.6.0 | Parse canonical UUIDs and verify RFC variant/version bits | Stable maintained package; RVBox owns the monotonic UUIDv7 generator so clock and ordering behavior remain directly testable. | diff --git a/docs/implementation-plan.v1.md b/docs/implementation-plan.v1.md index eec9b1c..05fd0ec 100644 --- a/docs/implementation-plan.v1.md +++ b/docs/implementation-plan.v1.md @@ -2423,6 +2423,16 @@ stderr. Flush warnings/errors promptly, redact as elsewhere, and make `Open log` target the current file after rotation. Add native icon/version/service metadata; release signing and checksum publication are Phase 8 gates. +Provide opt-in `scripts/release build --windows-compression upx` packaging with +checksum-pinned UPX in the Docker toolchain. Retain an unpacked same-version +fallback; never require a packer/extractor on the Windows host. Keep version, +manifest, and icon resources uncompressed and compare extracted resources; +retain relocations and require UPX integrity plus size reduction. Pack before +optional signing, sign/checksum both variants, and record compression in the +release manifest. Keep ordinary packaging as the default until compressed +service/tray/launcher/helper execution passes native acceptance. Document the +startup/memory and antivirus tradeoffs and fallback procedure. + ### 7.6 Windows-first client unit and native integration tests Unit-test shared runtime/spool behavior with fake transport/clock/storage fault diff --git a/docs/operations-runbook.md b/docs/operations-runbook.md index d0a4ce0..be5e2d9 100644 --- a/docs/operations-runbook.md +++ b/docs/operations-runbook.md @@ -89,6 +89,30 @@ dist/rvbox-1.0.0-rc.1/rvc-linux-ARCH --version Replace `ARCH` with `amd64` or `arm64` for the Linux host. Both variants are created from the same pinned toolchain and have the same embedded version. +For a compact, directly runnable Windows package, add +`--windows-compression upx` to that command. The default `none` retains the +ordinary executable. Compact builds use checksum-pinned UPX 5.2.1 with LZMA, +retain PE relocations, and leave icons/manifest/version resources uncompressed. +Packaging checks UPX integrity, compares every extracted Windows resource to +the original, and requires a smaller result before publication. The bundle +also retains `rvbox-windows-amd64-unpacked.exe`; both variants are included in +`SHA256SUMS`, and the manifest records `windows_compression`. Optional signing +runs **after** packing and signs both variants before checksumming. The packer +runs only inside Docker; release automatically rebuilds an older toolchain +that lacks it. Existing build-image/cache cleanup and recovery still apply. + +UPX expands the image in memory at each process start, including service, tray, +launcher, and signal-helper modes. This trades smaller files/downloads for +startup work and reduced sharing of executable memory between processes. +Antivirus products may flag packed executables; use the unpacked fallback if +that occurs rather than weakening protection. Resource/integrity checks are +not native execution evidence. Before choosing compressed packages for regular +distribution, exercise fresh install, upgrade, same-version activation, service +restart/reboot, tray, and ordinary/elevated command execution on Windows. +The installer still needs no external extractor or separate resident process. +See the [UPX manual](https://github.com/upx/upx/blob/v5.2.1/doc/upx.pod) and +[upstream antivirus issue](https://github.com/upx/upx/issues/437). + For a Windows-signed release, provide an executable host-side signing hook via `--sign-windows-hook /absolute/path/to/hook`. The wrapper invokes it with the Windows executable path and version, then records `windows_signed: true` in the diff --git a/docs/testing.md b/docs/testing.md index e827b88..9fabba1 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -295,6 +295,16 @@ while Helium is offline; passing portable tests and Windows cross-compilation does not prove them. Retain the previous installer for recovery during physical testing, and collect `service-startup.log` if service start fails. +For releases built with `--windows-compression upx`, the packaging gate requires +UPX integrity, smaller output, and identical extracted icon/version/manifest +resources. Repeat the native lifecycle checks above using the **packed** +installer, then verify reconnection, SCM restart/reboot, tray actions, and both +ordinary and elevated commands. Every launcher/signal-helper also runs from +the packed executable; checking only its install dialog is insufficient. +Keep the same-release unpacked fallback for isolating compression-specific +failures. Packed execution remains unverified while no Windows fixture is +available; Linux-side UPX integrity is not a Windows test result. + Regression `BH-WINTRAY-06` checks successful HRESULTs (`S_OK` and `S_FALSE`) versus actual failures. On the Windows 10 fixture, the installed, responsive tray returned `S_FALSE` (`1`) with valid icon coordinates; a readiness check diff --git a/scripts/release b/scripts/release index 35accdd..b203dd7 100755 --- a/scripts/release +++ b/scripts/release @@ -9,7 +9,7 @@ compose_file=$repo_root/deploy/compose.yaml usage() { cat <<'EOF' -usage: scripts/release build --version VERSION --bootstrap-server-url WSS_URL [--output DIR] [--sign-windows-hook FILE] +usage: scripts/release build --version VERSION --bootstrap-server-url WSS_URL [--windows-compression none|upx] [--output DIR] [--sign-windows-hook FILE] Builds a fresh immutable bundle containing: rvbox-server-linux-amd64 @@ -20,6 +20,15 @@ Builds a fresh immutable bundle containing: SHA256SUMS manifest.json +--windows-compression upx creates a compact, directly runnable Windows executable +with pinned UPX/LZMA and keeps rvbox-windows-amd64-unpacked.exe as a fallback. +The default is none. Icons, manifest, and version resources stay uncompressed +and are compared against the original. Relocations are retained. UPX integrity +and smaller-output checks must pass before signing/checksumming either variant. +Packed binaries still require native Windows acceptance; they may encounter +antivirus false positives or higher runtime memory/startup costs. No external +extractor is needed on Windows. Rebuilding an outdated toolchain is automatic. + The default output is dist/rvbox-VERSION. --output must remain below this repository's ignored dist/ tree. VERSION must be a safe release label ([0-9A-Za-z][0-9A-Za-z._+-]{0,63}); an existing final output is never replaced. @@ -46,10 +55,12 @@ version= output= sign_hook= bootstrap_server_url= +windows_compression=none while [ "$#" -gt 0 ]; do case $1 in --version) [ "$#" -ge 2 ] || fail "--version needs a value"; version=$2; shift 2 ;; --bootstrap-server-url) [ "$#" -ge 2 ] || fail "--bootstrap-server-url needs a value"; bootstrap_server_url=$2; shift 2 ;; + --windows-compression) [ "$#" -ge 2 ] || fail "--windows-compression needs a value"; windows_compression=$2; shift 2 ;; --output) [ "$#" -ge 2 ] || fail "--output needs a directory"; output=$2; shift 2 ;; --sign-windows-hook) [ "$#" -ge 2 ] || fail "--sign-windows-hook needs an executable file"; sign_hook=$2; shift 2 ;; --help|-h) usage; exit 0 ;; @@ -57,6 +68,11 @@ while [ "$#" -gt 0 ]; do esac done +case $windows_compression in + none|upx) ;; + *) fail "--windows-compression must be none or upx" ;; +esac + case $version in ''|[!0-9A-Za-z]*|*[!0-9A-Za-z._+-]*|?????????????????????????????????????????????????????????????????*) fail "--version must match [0-9A-Za-z][0-9A-Za-z._+-]{0,63}" @@ -88,6 +104,11 @@ fi docker version >/dev/null 2>&1 || fail "Docker is unavailable" docker compose -f "$compose_file" version >/dev/null 2>&1 || fail "Docker Compose is unavailable" +if [ "$windows_compression" = upx ]; then + if ! docker compose -f "$compose_file" run --rm toolchain sh -ec 'command -v upx >/dev/null' >/dev/null 2>&1; then + docker compose -f "$compose_file" build toolchain + fi +fi partial=$parent/.rvbox-$version.partial-$$ mkdir "$partial" || fail "could not create private release staging directory" @@ -115,28 +136,49 @@ docker compose -f "$compose_file" run --rm toolchain sh -ec ' CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags "$flags" -o "$out/rvc-linux-amd64" ./cmd/rvc CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -trimpath -ldflags "$flags" -o "$out/rvc-linux-arm64" ./cmd/rvc CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -trimpath -ldflags "-H=windowsgui $windows_flags" -o "$out/rvbox-windows-amd64.exe" ./cmd/rvbox -' sh "$version" "$container_partial" "$bootstrap_server_url" + if [ "$4" = upx ]; then + cp "$out/rvbox-windows-amd64.exe" "$out/rvbox-windows-amd64-unpacked.exe" + upx --no-env --best --lzma --compress-icons=0 --compress-resources=0 --strip-relocs=0 \ + -o "$out/.rvbox-packed.exe" "$out/rvbox-windows-amd64.exe" + upx --no-env -t "$out/.rvbox-packed.exe" + go-winres extract --dir "$out/.resources-original" "$out/rvbox-windows-amd64.exe" + go-winres extract --dir "$out/.resources-packed" "$out/.rvbox-packed.exe" + diff -r "$out/.resources-original" "$out/.resources-packed" + rm -rf -- "$out/.resources-original" "$out/.resources-packed" + test "$(wc -c < "$out/.rvbox-packed.exe")" -lt "$(wc -c < "$out/rvbox-windows-amd64.exe")" + mv "$out/.rvbox-packed.exe" "$out/rvbox-windows-amd64.exe" + fi +' sh "$version" "$container_partial" "$bootstrap_server_url" "$windows_compression" +windows_artifacts=rvbox-windows-amd64.exe +if [ "$windows_compression" = upx ]; then + windows_artifacts="$windows_artifacts rvbox-windows-amd64-unpacked.exe" +fi signed=false if [ -n "$sign_hook" ]; then - RVBOX_ARTIFACT=$partial/rvbox-windows-amd64.exe RVBOX_VERSION=$version "$sign_hook" "$partial/rvbox-windows-amd64.exe" "$version" + for artifact in $windows_artifacts; do + RVBOX_ARTIFACT=$partial/$artifact RVBOX_VERSION=$version "$sign_hook" "$partial/$artifact" "$version" + done signed=true fi -for artifact in rvbox-server-linux-amd64 rvbox-server-linux-arm64 rvc-linux-amd64 rvc-linux-arm64 rvbox-windows-amd64.exe; do +for artifact in rvbox-server-linux-amd64 rvbox-server-linux-arm64 rvc-linux-amd64 rvc-linux-arm64 $windows_artifacts; do [ -f "$partial/$artifact" ] && [ ! -L "$partial/$artifact" ] || fail "builder did not create regular $artifact" done -(cd "$partial" && sha256sum rvbox-server-linux-amd64 rvbox-server-linux-arm64 rvc-linux-amd64 rvc-linux-arm64 rvbox-windows-amd64.exe) >"$partial/SHA256SUMS" +(cd "$partial" && sha256sum rvbox-server-linux-amd64 rvbox-server-linux-arm64 rvc-linux-amd64 rvc-linux-arm64 $windows_artifacts) >"$partial/SHA256SUMS" { printf '{\n' printf ' "schema": 1,\n' printf ' "version": "%s",\n' "$version" printf ' "git_commit": "%s",\n' "$commit" printf ' "windows_signed": %s,\n' "$signed" + printf ' "windows_compression": "%s",\n' "$windows_compression" printf ' "artifacts": "SHA256SUMS"\n' printf '}\n' } >"$partial/manifest.json" -chmod 0755 "$partial/rvbox-server-linux-amd64" "$partial/rvbox-server-linux-arm64" "$partial/rvc-linux-amd64" "$partial/rvc-linux-arm64" "$partial/rvbox-windows-amd64.exe" +for artifact in rvbox-server-linux-amd64 rvbox-server-linux-arm64 rvc-linux-amd64 rvc-linux-arm64 $windows_artifacts; do + chmod 0755 "$partial/$artifact" +done chmod 0644 "$partial/SHA256SUMS" "$partial/manifest.json" mv -- "$partial" "$output" trap - EXIT HUP INT TERM