ovgate/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A userspace VPN gateway: OpenVPN 3 core builds a tunnel to a VPNGate node, lwIP terminates it in-process, and a SOCKS5 server (RFC 1928/1929) serves traffic over it. No root, no tun device, no routing table changes — that constraint is why the netstack exists at all, and it is not negotiable.

docs/FEASIBILITY.md and docs/ARCHITECTURE.md (both Chinese) are the design record. Read FEASIBILITY §1 before touching anything switch-related: carrying established TCP connections across a node switch is physically impossible, and the code is shaped around that fact.

Build and test

Two build trees by convention — the same source with the tunnel egress off and on:

cmake -S . -B build        -DCMAKE_BUILD_TYPE=Release -DOVG_WITH_TUNNEL=OFF
cmake -S . -B build-tunnel -DCMAKE_BUILD_TYPE=Release -DOVG_WITH_TUNNEL=ON
cmake --build build -j8 && cmake --build build-tunnel -j8

OFF compiles in seconds and is the right loop for everything except netstack/ovpn work; ON drags in openvpn3 and lwIP. Run both suites before declaring anything done — netstack tests only exist in the tunnel build, and app wiring is #if OVG_WITH_TUNNEL'd in places.

openvpn3 and lwIP are source dependencies. This working copy points at /tmp/ovpn3 and /tmp/lwip via OVG_OPENVPN3_DIR / OVG_LWIP_DIR; if /tmp was cleared, re-configure without those and FetchContent re-downloads.

./build/tests/ovg_tests                 # all
./build/tests/ovg_tests manager_walks   # substring filter on the test name — this is the only filter
ctest --test-dir build                  # wraps the whole binary as one test

Tests are OVG_TEST(name) { ... } with CHECK/CHECK_EQ/SKIP(reason) from tests/harness.h. No gtest. Expected: 155 passed / 2 skipped (no tunnel), 172 passed / 3 skipped (tunnel).

There is no linter or formatter config. Match the surrounding style: comments explain why, and several load-bearing ones exist specifically to stop a future reader "simplifying" a subtlety back out. Don't delete them to make a diff tidy.

Architecture: the parts that span files

Dependency direction is strictly one-way and enforced by review, not by tooling: app → {health, socks5, egress, selector} → {netstack, ovpn, vpngate} → common. socks5 must never learn that ovpn/netstack exist — it only holds an Egress. netstack must never learn ovpn exists — it only gets an fd.

egress::Egress is the seam. TunnelEgress and DirectEgress implement it; everything above is written against the interface, which is what makes egress_mode = direct (host sockets, no VPN) a usable test path and what makes hot-swapping a tunnel possible at all.

Refcount is the drain. shared_ptr<Egress>::use_count() is the live session count. A replaced egress is kept alive by the sessions still on it and disappears when the last one lets go. There is no separate session registry to keep consistent — don't add one, and don't stash an EgressPtr anywhere that outlives a session (a promotions vector in a test that holds egresses instead of labels will hang the drain forever).

Switching is make-before-break (EgressManager, SwitchController): the new tunnel is fully up before the old one is replaced. New sessions land on the new egress; zero-progress TCP sessions are re-dialled transparently; UDP associations are re-homed in place; everything else drains under switch.drain_grace and is then closed. The promote hook fans out in app/, socks5 first (it re-homes while the old egress is still whole), then the switch controller.

lwIP has one Stack per process (g_stack_live throws otherwise — its state is in globals) and every lwIP call happens on Stack::strand_. Public TcpStream/UdpSocket methods post themselves there, so callers may use them from any thread; completions post back to the caller's executor. Objects a raw lwIP callback can still reach are destroyed through common/strand_deleter.h, not by the last shared_ptr dropping.

Selection is two-phase (selector/): a cheap prior over the whole ~95-node list, then real TCP handshake timing of only the top K. Probing needs a TCP remote — a UDP "connect" completes locally and measures nothing — and VPNGate is mostly UDP-only, so a top-10 routinely yields 3–4 real probe targets. That is expected, and the selector logs it so it doesn't read as a broken filter.

Health probing must stay a TCP handshake through the egress (health/). A DNS lookup can be answered from cache without a byte crossing the tunnel, which reports a dead tunnel as the healthiest node in the fleet. Scores drop terms whose inputs are unavailable and renormalise the remaining weights: missing signal ≠ bad signal.

Traps this codebase has already been bitten by

• ec == std::errc::connection_refused is false for asio errors. They live in the asio.system category, whose default_error_condition doesn't map to std::errc. Normalise through DirectEgress::map_ec (and the errno fallback in socks5_reply_for) rather than comparing raw.
• Anything that re-arms on the io_context prevents shutdown. Dropping the work guard cannot retire pending work. The lwIP timer (Stack::stop()) and the re-armed signal_set (signals_.cancel()) both had to be shut down explicitly; without them the process logged a flawless graceful shutdown and then hung forever. If you add a self-rescheduling timer, add its teardown to App::begin_shutdown in the same commit.
• The test suite is structurally blind to that class of bug: tests drive the loop in io.run_for(2ms) slices, while the service calls run() once and waits for it to return. See stack_stop_lets_the_io_context_drain for the shape of a test that actually checks it.
• A cold start with no directory yet is not a switch failure. Charging it to the backoff ladder cost 30s of dead service on every start and could exhaust the startup budget. Selector::directory_loaded() distinguishes "nothing has arrived yet" from "everything was rejected"; the former uses retry_startup, which touches neither backoff nor failure counters.
• Phase transitions must be claimed atomically. claim_switch_phase() exists because releasing the phase during a retry let the tunnel-down watchdog and the startup poll both start selections and build two tunnels for one slot.
• Never cat/head the VPNGate CSV. Lines run to ~13.5 KB because the whole .ovpn profile is base64 in the last column. Decode field 15 in a script and print only what you need.

This sandbox

Outbound TCP is transparently intercepted: connects to unroutable addresses (e.g. 192.0.2.1:1213) "succeed" in ~0.9 ms and then return nothing. Consequences, all environmental rather than bugs — do not go chasing them in the code:

• every latency probe reports ~1 ms, so selection here is effectively arbitrary;
• OpenVPN handshakes die with NETWORK_EOF_ERROR, so the tunnel data plane cannot be verified here. The control path (selection, connect attempts, reconnect, graceful shutdown) can be, and is;
• three tests SKIP for exactly this reason;
• a local OpenVPN server is not an option either: no /dev/net/tun, TUNSETIFF gives EPERM, no kernel modules.

tools/tunnel_smoke.cpp (built as ovg_tunnel_smoke, meaningful only in the tunnel build) brings up one tunnel, pings through it, and exits — the first thing to run on a machine with real network access.

Running it

./build/src/openvpngate -c etc/openvpngate.conf --check   # validate + print config, don't start
./build/src/openvpngate -c etc/openvpngate.conf --egress direct --listen 127.0.0.1:1080

There is a container build too (Dockerfile, docker-compose.yml, docs/DOCKER.md). Two things about it are load-bearing: it clones openvpn3/lwIP at pinned refs and passes them via OVG_OPENVPN3_DIR/OVG_LWIP_DIR, because FetchContent's GIT_TAG master would otherwise make the image a different VPN client every week; and docker/openvpngate.conf overrides the two host defaults that are silently wrong in a container — loopback listen addresses (a published port then reaches nothing) and relative state paths (the node history dies with the container).

.github/workflows/publish-image.yml publishes that image to GHCR. It has no test job on purpose — the builder stage runs ovg_tests, so a red test cannot produce an image. If you ever make the Dockerfile skip the suite by default, CI stops testing anything and nothing will say so.

etc/openvpngate.conf documents every key with its default and the reasoning. Admin HTTP (default 127.0.0.1:9080, no auth) exposes /status /nodes /sessions /health /metrics /healthz and POST /switch; /nodes explains each node's score, which is the fastest way to understand a selection decision. SIGHUP reloads credentials and the node list without dropping sessions.