Metadata-Version: 2.5
Name: vpn-connection-test
Version: 0.1.0
Summary: Is a VPN more stable than your direct connection? Per-connection loss and RTT, route traces and a recommendation, from the system tray.
Project-URL: homepage, https://github.com/raman78/vpn-connection-test
Project-URL: repository, https://github.com/raman78/vpn-connection-test
Project-URL: issues, https://github.com/raman78/vpn-connection-test/issues
Author: raman78
License: MIT License
        
        Copyright (c) 2026 raman78
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: gaming,latency,linux,network,packet-loss,vpn,wireguard
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: X11 Applications :: Qt
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.11
Requires-Dist: pyqt6>=6.5
Description-Content-Type: text/markdown

# vpn-connection-test

Tells you whether a VPN makes your connection to a game (or any other
service) more stable than your normal connection, and whether the extra
latency is worth it. It sits in the system tray while you play, measures
the connection the program really uses, and says which path to use, with
the numbers behind it.

The idea: a connection that stutters now and then usually suffers short
bursts of packet loss somewhere on its internet route, not on your machine
and not at the server. A VPN sends your traffic along a different route, so
it helps only if that route avoids the bad part. The only way to know is to
measure both: the game's own packets on whichever path it uses, and at the
same time a steady ping of your normal connection, so that the two paths are
compared in the same minutes, not on different evenings. When the normal
connection starts losing, the program traces the route to see where the
loss begins.

It never switches the VPN by itself. Some programs (games especially) break
when their connection disappears, so it tells you, and you pick the moment.

Linux only. Tested on CachyOS (Arch) with Proton VPN (WireGuard), playing
AION 2. Nothing in it is specific to that game or that VPN.

## Quick start

1. Install the system tools and allow packet capture — see
   [Installing](https://github.com/raman78/vpn-connection-test/blob/main/docs/INSTALL.md).
2. `pipx install vpn-connection-test`
3. `vpnct install-desktop`, then start **VPN connection test** from the
   application menu.
4. Use your program as usual: on the normal connection, on the VPN, on
   different VPN servers. The window shows which one is the most stable.

## Documentation

- [docs/INSTALL.md](https://github.com/raman78/vpn-connection-test/blob/main/docs/INSTALL.md) — what it needs, installing,
  updating, removing.
- [docs/USING.md](https://github.com/raman78/vpn-connection-test/blob/main/docs/USING.md) — the window and tray icon, what the
  numbers mean, hints and the recommendation, the terminal commands,
  problems and questions.
- [docs/ARCHITECTURE.md](https://github.com/raman78/vpn-connection-test/blob/main/docs/ARCHITECTURE.md) — how it works and why,
  every log column, failure modes, tests, releases.
- [CHANGELOG.md](https://github.com/raman78/vpn-connection-test/blob/main/CHANGELOG.md) — what changed in each version.

## What it keeps, and what it never does

- **No `sudo`.** Packet capture works through membership in the
  `wireshark` group, ping through the system's normal unprivileged ping.
- **No packet contents on disk.** Only the first 96 bytes of each packet
  are captured: the headers, which are enough to count lost packets, and
  on most packets the first few dozen bytes of what they carry. They go
  through a pipe to the counting tool, which reads only the packet numbers
  from them, and are never written anywhere.
- **Only numbers are kept**: per-second and per-minute figures, ping
  results and route hops, as plain files in
  `~/.local/share/vpn-connection-test/sessions/`.
- **Nothing is sent anywhere.** Router names on a traced route come from
  your system's own name lookup only.
