Introducing a new way to review your PRs.

Read the announcement

2dust / v2rayn

A GUI client for Windows, Linux and macOS, support Xray and sing-box and others

View on GitHub

13 documents · Updated Nov 16, 2026

docs / build-tests-and-tools

Build, Tests, and Tooling

Overview

The repository's .NET entry point is v2rayN/v2rayN.slnx. It includes the desktop apps (v2rayN/v2rayN.csproj and v2rayN.Desktop/v2rayN.Desktop.csproj), ServiceLib, AmazTool, the GlobalHotKeys submodule, ServiceLib.Tests, ServiceLib.UdpTest, v2rayN.WebAPI, and v2rayN.WebAPI/Tests/v2rayN.WebAPI.Tests.csproj. The older v2rayN/v2rayN.sln covers the desktop/service/test projects and solution action files but does not include WebAPI, so changes involving the API should route through the .slnx or explicit project commands. Shared MSBuild defaults live in v2rayN/Directory.Build.props: all projects inherit net10.0, version 7.25.6, nullable annotations, implicit usings, overflow checks, release single-file publishing defaults, and an IsAot=true switch that enables AOT, trimming, and V2RAYN_IS_AOT. Package versions are centrally pinned in v2rayN/Directory.Packages.props, including TUnit/TUnit assertions, ReactiveUI, Avalonia, SQLite, NLog, YamlDotNet, and native Linux Skia/HarfBuzz assets. global.json selects Microsoft.Testing.Platform as the test runner.

ServiceLib.Tests is a TUnit executable (v2rayN/ServiceLib.Tests/ServiceLib.Tests.csproj) that references ServiceLib directly and publishes with AOT enabled. Its tests map to core library behavior rather than UI shells: formatter round trips and protocol share coverage live under v2rayN/ServiceLib.Tests/Fmt/**; core config generation, DNS, fake-IP, IPv6/TUN, and sing-box/Xray output behavior live under v2rayN/ServiceLib.Tests/CoreConfig/** and v2rayN/…/CoreConfigHandlerTests.cs; persistence and SQLite transaction behavior live under v2rayN/ServiceLib.Tests/Manager/**, v2rayN/…/SQLiteHelperTests.cs, and shared setup in v2rayN/…/TestDatabase.cs; service behavior such as speed-test batching and download headers lives under v2rayN/ServiceLib.Tests/Services/**; platform-sensitive handlers such as macOS autostart are guarded with fake tools in v2rayN/…/AutoStartupHandlerTests.cs; and ViewModel/transport persistence cases live in v2rayN/…/AddServerViewModelTests.cs. Several tests use reflection or singleton state (ConfigState, SQLiteHelper.Instance, ReactiveUI bootstrap), so NotInParallel in files such as SQLiteHelperTests.cs, AutoStartupHandlerTests.cs, and AddServerViewModelTests.cs is intentional.

v2rayN/v2rayN.WebAPI/Tests/v2rayN.WebAPI.Tests.csproj is the WebAPI TUnit executable. It references v2rayN.WebAPI, adds Microsoft.AspNetCore.App, excludes ProcessHelper/** from the main compilation, then builds v2rayN/v2rayN.WebAPI/Tests/ProcessHelper/InstanceLockProcessHelper.csproj as a non-reference output copied into the test output. That helper links v2rayN.WebAPI/…/WebInstanceLock.cs and exposes lock acquire/read-owner modes through ProcessHelper/Program.cs, which lets tests exercise instance-lock behavior across real processes. The WebAPI suite covers authentication/session/SSE semantics (WebAuth*, WebSessionServiceTests.cs, Sse*), listener and browser security (WebListenerSecurityPolicyTests.cs, WebSecurityHeadersTests.cs, WebCorsTests.cs), runtime mutation/restart/gating (Runtime*, WebRestartCoordinatorTests.cs, CoreRestartPreflightTests.cs), core and geo update staging/rollback (CoreUpdateWorkflowTests.cs, GeoFilesUpdateTransactionTests.cs, XrayGeoStagingTests.cs), native WebAPI self-update (NativeWebUpdate*, WebUpdate*, RestoreRuntimeRecoveryTests.cs), contract parity with desktop models (SubscriptionParityTests.cs, RoutingParityTests.cs, DnsEditorParityTests.cs, IpInfoColumnParityTests.cs, ParityValidationTests.cs), and API packaging/security boundaries. Integration scripts under v2rayN/v2rayN.WebAPI/Tests/Integration/** dry-run package layout and runtime workflows; notably test-release-packaging.sh validates full-install versus app-only WebAPI ZIP boundaries and manifest identity, while Test-Windows.ps1 runs Windows startup/update/restore smoke tests with isolated process environment variables.

ServiceLib.UdpTest is a library-style UDP test harness, not a normal TUnit test project. v2rayN/…/UdpTestService.cs chooses a probe type (ntp, dns, stun, or mcbe) from a target string, parses optional host/port including bracketed IPv6, opens a SOCKS5 UDP association to 127.0.0.1:<socks5Port>, sends two attempts, and returns the best verified round-trip time. v2rayN/…/Socks5UdpChannel.cs implements unauthenticated SOCKS5 TCP handshake plus UDP ASSOCIATE, SOCKS5 UDP packet wrapping/unwrapping, IPv4/IPv6/domain ATYP handling, and rejects fragmentation. The concrete testers in v2rayN/ServiceLib.UdpTest/Tester/** build and verify protocol-specific packets: NTP defaults to pool.ntp.org:123, DNS to 8.8.8.8:53, STUN to stun.voztovoice.org:3478, and Minecraft Bedrock ping to pms.mc-complex.com:19132.

AmazTool is the desktop upgrade/restart helper. v2rayN/…/Program.cs prints help when invoked without arguments, handles rebootas by starting v2rayN, and otherwise treats URI-decoded arguments as a ZIP path for upgrade. v2rayN/…/UpgradeApp.cs waits, verifies the ZIP exists, kills existing v2rayN processes whose executable path is under the current install directory, extracts archive entries after dropping the first path segment, blocks path traversal with Utils.IsPathUnderDirectory, moves the running helper executable aside before replacement, skips existing files under bin, retries extraction, then restarts v2rayN. v2rayN/AmazTool/AmazTool.csproj uses the shared build props and removes AOT satellite resource DLLs during publish.

CI is split between reusable build/test workflows and release packaging. .github/…/test.yml runs dotnet test --project ./v2rayN/ServiceLib.Tests -c Release -- --report-trx on ServiceLib-related path changes and publishes TRX comments. .github/…/build.yml is the reusable desktop build: it purges preinstalled SDKs, installs .NET 10, computes RIDs for Windows/Linux/macOS x64 and arm64, publishes AmazTool, then publishes either WPF or Avalonia output and uploads artifacts. Platform workflows (build-windows.yml, build-windows-desktop.yml, build-linux.yml, build-osx.yml, build-windows-x86.yml) call that reusable workflow and package outputs; build-linux.yml additionally runs DEB/RPM jobs for x64, arm64, riscv64, ppc64le, loong64, and x86 through package-*.sh, while build-osx.yml turns macOS artifacts into DMGs through package-osx.sh. .github/…/package-zip.yml merges build artifacts with v2rayN-core-bin ZIP contents, applies desktop/AOT suffixes, uploads artifacts, and calls .github/…/upload-sign.yml to GPG-sign and upload release files. .github/…/build-all.yml is the manual orchestrator that publishes the GPG public key, releases WebAPI, and dispatches Windows/Linux/macOS/desktop/x86 release builds. .github/…/winget-publish.yml submits the latest non-prerelease Windows x64 and arm64 ZIP URLs to WinGet.

WebAPI has its own release lane in .github/…/build-WebAPI.yml and .github/…/release-WebAPI.yml. The build workflow resolves a release identity (0.0.0-dev for development or a strict x.y.z tag), runs ServiceLib and WebAPI tests on macOS and Windows, runs backend/package verification on Ubuntu, publishes native WebAPI packages for Windows x64/arm64 and Linux x64/arm64/riscv64/loongarch64, fetches matching core bundles, smoke-tests core binaries and API startup, and packages full-install and app-only update ZIPs. release-WebAPI.yml signs/uploads the WebAPI ZIPs first and only then uploads WebAPI-update.json through the shared signer.

The root packaging scripts produce Linux desktop OS packages outside the GitHub ZIP path. package-debian.sh and package-rhel.sh support Debian-family and RHEL-family hosts for x64, arm64, riscv64, ppc64le, and loong64; their *-x86.sh counterparts target linux-x86/i386/i686 from x86_64 or aarch64 hosts. They enforce supported OS/kernel/architecture, install build tools and .NET 10 SDKs (including community/prebuilt SDKs for non-mainstream arches), sync the v2rayN/GlobalHotKeys submodule, optionally checkout a release tag/channel, download prebuilt NuGet/native package inputs, publish v2rayN.Desktop, stage Xray/sing-box and geo/rule assets either from v2rayN-core-bin bundles or separate upstream releases, then write launcher/desktop/maintainer or RPM spec files. package-osx.sh downloads the matching core bundle, copies it into the publish output, creates a v2rayN.app with Info.plist, adds NotStoreConfigHere.txt, and builds a DMG with create-dmg.

Repository-level contributor tooling is conventional but affects reviews. .editorconfig enforces CRLF by default, two-space YAML, four-space C#, file-scoped namespaces, explicit accessibility, sorted system usings, and many C# style warnings. .gitattributes leaves line endings on text=auto and does not force solution/project files to binary merges. .gitignore excludes build outputs, bin/, obj/, publish artifacts, package outputs, IDE state, coverage, logs, NuGet packages, Python caches, and local VS/Rider/VS Code state. .gitmodules declares only v2rayN/GlobalHotKeys, so release/build failures around missing hotkey sources usually mean submodules were not initialized. .github/dependabot.yml opens daily updates for GitHub Actions and NuGet packages under /v2rayN. .github/…/update-cert.yml runs .github/…/UpdateCert.cs daily/manually to refresh Mozilla and Chrome root PEM files under v2rayN/ServiceLib/Sample via a pull request.

Routing / covers

Route changes here when they affect repository build, test, CI, release, package, helper, or test-harness behavior under these owned globs:

  • v2rayN/*.sln
  • v2rayN/*.slnx
  • v2rayN/Directory.Build.props
  • v2rayN/Directory.Packages.props
  • v2rayN/ServiceLib.Tests/**
  • v2rayN/ServiceLib.UdpTest/**
  • v2rayN/v2rayN.WebAPI/Tests/**
  • v2rayN/AmazTool/**
  • global.json
  • package-*.sh
  • .github/**
  • .editorconfig
  • .gitattributes
  • .gitignore
  • .gitmodules

Coupling

Risks

  • v2rayN/…/UpgradeApp.cs is safety-critical during desktop self-upgrade: if archive path traversal checks in Utils.IsPathUnderDirectory or the first-segment stripping logic are weakened, a malicious or malformed ZIP can write outside the install directory before restarting v2rayN.
  • v2rayN/…/Socks5UdpChannel.cs only supports SOCKS5 UDP packets with FRAG == 0 and unauthenticated handshakes. If the proxy starts returning fragmented UDP or a domain relay address from UDP ASSOCIATE, UdpTestService.SendUdpRequestAsync can fail even when UDP proxying works for normal clients.
  • v2rayN/v2rayN.WebAPI/Tests/Integration/Test-Windows.ps1 mutates process-level environment variables and starts real native processes. If cleanup paths are bypassed or new variables are added without restoring them, later Windows smoke steps can target the wrong data home, API key, URL, or bundle extraction directory.
  • package-debian.sh, package-rhel.sh, and their x86 variants fetch latest upstream Xray, sing-box, geo databases, community SDKs, and prebuilt NuGet/native packages at package time. If an upstream asset is renamed or unavailable, package generation can fail without any source-code change; pin with XRAY_VER, SING_VER, or the script SDK/base URL environment variables when diagnosing release failures.
  • .github/…/build-WebAPI.yml publishes WebAPI-update.json only after signed packages via release-WebAPI.yml. If that dependency is removed, clients could discover an update manifest before the matching app-only ZIPs are uploaded, causing self-update download failures.