Don't call System.exit() when the tunnel is embedded

[jochen-testingbot]

The problem

App is used as a library as well as a command line client. The TeamCity agent plugin constructs an App and calls boot() inside the build agent JVM.

When the tunnel fails to start, boot() called System.exit(1). Embedded, that terminates the host process. Observed on a TeamCity 2024.12 agent with deliberately invalid credentials:

[16:49:10] : Starting TestingBot Tunnel
[16:49:10] : Processing shutdown hook: JVM process got terminate signal
[16:49:10] : Stopping build on agent. Reason: agent shutdown (Build agent shutdown)

The running build then hung in "running" indefinitely, and the agent never re-registered — it needed a manual restart. The calling plugin already wraps boot() in a try/catch, but that cannot help, because System.exit() does not throw.

This is long-standing rather than new: boot() has had a System.exit since at least 2.4.

The fix

Replace the exits on the embedding path with a TunnelFailedException carrying the exit code, and let main() catch it and exit with exactly the same codes as before, so command line behaviour is unchanged.

• boot() throws instead of exiting when tunnel creation fails or the API returns an error (including 401)
• startProxies() throws instead of exiting when the local proxy port cannot be opened. tunnelReady() rethrows TunnelFailedException (while still swallowing/logging everything else as before) so the failure reaches main() on the synchronous path
• doctor() throws instead of exiting
• trackPid() moves from boot() into main(). The pid file exists so an external supervisor can stop the process — a command line concern — and PidPoller calls System.exit(0) from a timer thread when the file disappears. That was a background thread able to kill a host JVM at any moment, e.g. if a CI workspace cleaner removed the file. Embedders no longer get it.
• stop() now removes the shutdown hook registered by init(), cancels the pid poller, and tolerates a null api. Starting a tunnel per job previously leaked one shutdown hook per App for the lifetime of the JVM, and stop() after a failed boot() logged a confusing NPE stack trace.

After this, the only remaining System.exit calls are in main(), plus PidPoller, which is now only reachable from main().

Compatibility

• TunnelFailedException extends RuntimeException, so no existing signature changes and nothing that compiles today stops compiling. This also matches the existing HttpProxyStartException idiom in this codebase.
• CLI exit codes are unchanged: 1 for tunnel/auth/proxy/doctor failures, 2 for argument parse errors.
• One deliberate behaviour change worth review: embedders that relied on boot() creating the pid file will no longer get one. That seemed clearly desirable, but say the word if you'd rather keep it and gate it on a flag instead.

Tests

mvn test: 192 passing, 0 failures (184 before, 8 added).

AppEmbeddedTest drives boot() against a WireMock-stubbed API and asserts the failure surfaces as an exception. These tests are somewhat self-enforcing: if boot() ever goes back to calling System.exit, they don't just fail, they crash the surefire JVM.

To make that testable I added a package-private App.createApi() seam so a test subclass can point the API at WireMock — boot() previously constructed new Api(this) inline with no way to intercept it. Happy to change the approach if you'd prefer a different seam.

Known limitation

On the asynchronous path (TunnelPoller timer thread calling tunnelReady()), there is no caller to propagate to, so a proxy setup failure is now logged with its real message instead of terminating the process. Previously it called System.exit(1) from that timer thread. Surfacing it properly would need a failure callback from the poller back to the caller, which felt like a design decision for you rather than something to slip into this PR.