Files
firezone/rust
Thomas Eizinger 55304b3d2a refactor(snownet): learn host candidates from TURN traffic (#9998)
Presently, for each UDP packet that we process in `snownet`, we check if
we have already seen this local address of ours and if not, add it to
our list of host candidates. This is a safe way for ensuring that we
consider all addresses that we receive data on as ones that we tell our
peers that they should try and contact us on.

Performance profiling has shown that hashing the socket address of each
packet that is coming in is quite wasteful. We spend about 4-5% of our
main thread time doing this. For comparison, decrypting packets is only
about 30%.

Most of the time, we will already know about this address and therefore,
spending all this CPU time is completely pointless. At the same time
though, we need to be sure that we do discover our local address
correctly.

Inspired by STUN, we therefore move this responsibility to the
`allocation` module. The `allocation` module is responsible for
interacting with our TURN servers and will yield server-reflexive and
relay candidates as a result. It also knows, what the local address is
that it received traffic on so we simply extend that to yield host
candidates as well in addition to server-reflexive and relay candidates.

On my local machine, this bumps us across the 3.5 Gbits/sec mark:

```
Connecting to host 172.20.0.110, port 5201
[  5] local 100.93.174.92 port 57890 connected to 172.20.0.110 port 5201
[ ID] Interval           Transfer     Bitrate         Retr  Cwnd
[  5]   0.00-1.00   sec   319 MBytes  2.67 Gbits/sec   18    548 KBytes       
[  5]   1.00-2.00   sec   413 MBytes  3.46 Gbits/sec    4    884 KBytes       
[  5]   2.00-3.00   sec   417 MBytes  3.50 Gbits/sec    4   1.10 MBytes       
[  5]   3.00-4.00   sec   425 MBytes  3.56 Gbits/sec  415    785 KBytes       
[  5]   4.00-5.00   sec   430 MBytes  3.60 Gbits/sec  154    820 KBytes       
[  5]   5.00-6.00   sec   434 MBytes  3.64 Gbits/sec  251    793 KBytes       
[  5]   6.00-7.00   sec   436 MBytes  3.66 Gbits/sec  123    811 KBytes       
[  5]   7.00-8.00   sec   435 MBytes  3.65 Gbits/sec    2    788 KBytes       
[  5]   8.00-9.00   sec   423 MBytes  3.55 Gbits/sec    0   1.06 MBytes       
[  5]   9.00-10.00  sec   433 MBytes  3.63 Gbits/sec    8   1017 KBytes
- - - - - - - - - - - - - - - - - - - - - - - - -
[ ID] Interval           Transfer     Bitrate         Retr
[  5]   0.00-20.00  sec  8.21 GBytes  3.53 Gbits/sec  1728             sender
[  5]   0.00-20.00  sec  8.21 GBytes  3.53 Gbits/sec                  receiver

iperf Done.
```
2025-07-28 21:38:39 +00:00
..
2025-07-22 13:24:58 +00:00
2023-05-10 07:58:32 -07:00

Rust development guide

Firezone uses Rust for all data plane components. This directory contains the Linux and Windows clients, and low-level networking implementations related to STUN/TURN.

We target the last stable release of Rust using rust-toolchain.toml. If you are using rustup, that is automatically handled for you. Otherwise, ensure you have the latest stable version of Rust installed.

Reading Client logs

The Client logs are written as JSONL for machine-readability.

To make them more human-friendly, pipe them through jq like this:

cd path/to/logs  # e.g. `$HOME/.cache/dev.firezone.client/data/logs` on Linux
cat *.log | jq -r '"\(.time) \(.severity) \(.message)"'

Resulting in, e.g.

2024-04-01T18:25:47.237661392Z INFO started log
2024-04-01T18:25:47.238193266Z INFO GIT_VERSION = 1.0.0-pre.11-35-gcc0d43531
2024-04-01T18:25:48.295243016Z INFO No token / actor_name on disk, starting in signed-out state
2024-04-01T18:25:48.295360641Z INFO null

Benchmarking on Linux

The recommended way for benchmarking any of the Rust components is Linux' perf utility. For example, to attach to a running application, do:

  1. Ensure the binary you are profiling is compiled with the release profile.
  2. sudo perf record -g --freq 10000 --pid $(pgrep <your-binary>).
  3. Run the speed test or whatever load-inducing task you want to measure.
  4. sudo perf script > profile.perf
  5. Open profiler.firefox.com and load profile.perf

Instead of attaching to a process with --pid, you can also specify the path to executable directly. That is useful if you want to capture perf data for a test or a micro-benchmark.