feat: lose packets in runs, not one at a time (burst loss)

CHANGELOG.md

@@ -7,6 +7,18 @@ The format follows [Keep a Changelog](https://keepachangelog.com/); versions fol
 
 ### Added
 
+- **Lose packets in runs instead of one at a time.** A new "Losses in a row" field, and
+  `--loss-burst`, sets how many packets are lost in a row on average. "Loss" still decides how
+  much goes missing overall, so 5 percent stays 5 percent and simply arrives in clusters. Spread
+  out, most connections absorb it. In runs of twenty it stalls transfers and forces reconnects,
+  which is usually what you meant to test. Set 0, the default, to spread it evenly as before.
+  Profiles remember it, and the log says how often to expect a run.
+
+- **A "Loss runs" counter** on the Statistics tab, in the stats CSV and in the reproduction
+  report, says how many runs of lost packets a session actually produced. Zero there, with a
+  run length set, means the session was too short to see one rather than the setting doing
+  nothing.
+
 - **Aim at one address family.** Two new switches under the destination target, in the GUI
   and on the command line, impair IPv4 only or IPv6 only. The other family keeps flowing
   untouched: nothing is blocked and nothing is slowed, it is simply left alone. They work

README.md

@@ -296,14 +296,30 @@ one. With the given probability it appends extra delay (ms) to a **single packet
 momentary "lag" actually arrives. The chance is per packet and applies **in each direction**, so a
 round trip hits it about twice as often as the number suggests.
 
-**Impairment (%)** - *Loss*: percentage of packets vanishing without a trace (5% is already a
+**Impairments** - *Loss*: percentage of packets vanishing without a trace (5% is already a
 clearly failing network). *Corruption*: percentage of packets with a flipped data bit - it affects
 **only payload-bearing packets**. Packets with no data (e.g. pure ACK, SYN) have nothing to flip,
 so they pass untouched and are **not counted as corrupted**. *Duplication*: percentage of packets
 sent twice.
 
+**Losses in a row** - real links rarely lose packets one at a time. A microwave oven, a lift or a
+switch between transmitters takes the connection away for a moment, and everything sent in that
+moment is gone. This field says how many packets are lost in a row **on average**, while *Loss*
+still decides how much is lost in total. It matters more than it looks: 5% spread out is something
+most connections absorb, while the same 5% in runs of twenty stalls a transfer, breaks a live
+connection and sends an application down its reconnect path. Set 0 to spread the loss evenly, which
+is what the tool did before this setting existed.
+
+Two limits worth knowing, and the log states both when you apply the settings. A very high loss
+cannot arrive in very short runs, because runs that short leave too little room between them, so
+the run says what it will really deliver. And a long run length puts the runs far apart, so a short
+session may not see one at all. Each direction gets its own runs, so a run of twenty means twenty
+in a row in that direction.
+
 **Link flapping** - cyclic total loss of traffic: every *Period* seconds the link is dead for the
-given percentage of the time. Simulates a flickering connection.
+given percentage of the time. Simulates a flickering connection. This is **not** the same as losses
+in a row: flapping is a fixed cycle you can predict, the runs above are random and short in the
+middle of otherwise normal traffic.
 
 **Advanced (NAT / connections):**
 - *Target destination (IP/port)* - impair only traffic to/from chosen servers. Both fields accept
@@ -370,7 +386,8 @@ next to the value says so instead of inventing a source. A few of them are worth
   measured median, not a worst case. Aircraft with newer low-orbit equipment behave like
   "Satellite (low orbit)" instead.
 
-A profile stores **what the link is like**: loss, corruption, duplication, latency, jitter, latency
+A profile stores **what the link is like**: loss, how much of it arrives in a row, corruption,
+duplication, latency, jitter, latency
 spikes, link outages (flapping), the speed limits and the buffer. Everything else - the target, the
 destination, blocking, RST, MTU, NAT expiry, the schedule, the seed - stays out of it. Saving a
 profile warns you about the ones you currently have switched on. Use **"Save file..."** for the
@@ -566,7 +583,8 @@ beneath it (in the UI language), and the CLI ends with a readable `error: ...` -
 
 The throughput chart has a Y axis with values (KB/s), a grid, a "nicely" rounded scale and current
 down/up readouts in the corner. Download/Upload (KB/s live), Packets (how many passed), Queued
-(waiting - grows with delay/limit), Lost, Corrupted, Duplicated, Buffer overflow (dropped when the
+(waiting - grows with delay/limit), Lost, Loss runs (how many RUNS that loss arrived
+in - see "Losses in a row"), Corrupted, Duplicated, Buffer overflow (dropped when the
 tool is overloaded), Dropped at stop (were still queued when STOP was pressed), Send failed (the
 tool captured them but could not put them back on the wire - the connection went down, or the driver
 refused), Rate-limit drop (dropped by a full speed-limit buffer - counted separately from
@@ -694,6 +712,7 @@ BeanNetworkTester.exe --simulate --duration 30 --format json > run.ndjson
 | Flag | Unit | Description |
 |---|---|---|
 | `--loss` | % | percentage of dropped packets |
+| `--loss-burst` | packets | average number of packets lost in a row (0 = loss spread evenly). Shapes `--loss`, it does not add to it |
 | `--corrupt` | % | percentage of packets with a flipped bit |
 | `--dup` | % | percentage of packets sent twice |
 | `--latency` | ms | fixed delay added to every packet |
@@ -916,6 +935,7 @@ what `packets_seen` counted in the first place - so every row records it in `cap
 | `packets_seen` | packets captured |
 | `packets_in_scope` | of those, the ones targeting selected for impairment |
 | `dropped_loss` | dropped by the Loss setting |
+| `loss_runs` | how many RUNS that loss arrived in (see "Losses in a row"). 0 with a run length set means the session was too short to see one |
 | `dropped_overflow` | dropped because the tool's own queue was full (see the note on it below) |
 | `corrupted` | packets whose payload was flipped |
 | `duplicated` | extra copies queued |

README.pl.md

@@ -231,14 +231,30 @@ Z podanym prawdopodobieństwem dokleja dodatkowe opóźnienie (ms) do **pojedync
 tak, jak chwilowy „lag” naprawdę wygląda. Szansa liczona jest na pakiet i działa **w każdą stronę**,
 więc pojedyncze odpytanie trafia na nią mniej więcej dwa razy częściej, niż sugeruje ta liczba.
 
-**Zakłócenia (%)** - *Utrata*: procent pakietów znikających bez śladu (5% to już wyraźnie
+**Zakłócenia** - *Utrata*: procent pakietów znikających bez śladu (5% to już wyraźnie
 zrywająca się sieć). *Uszkodzenie*: procent pakietów z przekłamanym bitem danych - dotyczy
 tylko pakietów z ładunkiem (payloadem). Pakiety bez danych (np. czyste ACK, SYN) nie mają czego
 przekłamać, więc przechodzą nietknięte i **nie są liczone jako uszkodzone**.
 *Duplikacja*: procent pakietów wysyłanych podwójnie.
 
+**Straty pod rząd** - prawdziwe łącza rzadko gubią pakiety po jednym. Mikrofalówka, winda albo
+przełączenie się między nadajnikami zabiera połączenie na moment, a wszystko wysłane w tym
+momencie przepada. To pole mówi, ile pakietów ginie pod rząd **średnio**, a *Utrata* nadal
+decyduje, ile ginie w sumie. To znaczy więcej, niż wygląda: 5% rozłożonych równomiernie
+większość połączeń wchłania, a te same 5% w seriach po dwadzieścia zatrzymuje transfer, zrywa
+połączenie na żywo i wysyła aplikację w ścieżkę ponownego łączenia. Ustaw 0, żeby rozłożyć stratę
+równomiernie, czyli tak, jak narzędzie działało, zanim to ustawienie powstało.
+
+Dwa ograniczenia, o których warto wiedzieć, i log mówi o obu przy zastosowaniu ustawień. Bardzo
+wysoka strata nie zmieści się w bardzo krótkich seriach, bo tak krótkie serie zostawiają za mało
+miejsca między sobą, więc przebieg mówi, ile naprawdę zgubi. A długa seria stawia serie daleko od
+siebie, więc krótka sesja może nie zobaczyć żadnej. Każdy kierunek ma własne serie, więc seria po
+dwadzieścia znaczy dwadzieścia pod rząd w tym kierunku.
+
 **Przerwy w łączu (flapping)** - cykliczne całkowite zrywanie ruchu: co *Okres* sekund łącze
-jest martwe przez podany procent czasu. Symuluje migające połączenie.
+jest martwe przez podany procent czasu. Symuluje migające połączenie. To **nie** to samo co straty
+pod rząd: flapping jest stałym cyklem, który da się przewidzieć, a serie wyżej są losowe i krótkie,
+w środku normalnego ruchu.
 
 **Zaawansowane (NAT / połączenia):**
 - *Celuj w cel (IP/port)* - psuj tylko ruch do/od wybranych serwerów. Oba pola przyjmują listy, zakresy, CIDR, wildcardy, porównania, wykluczenia i wyrażenia regularne - patrz [Składnia filtrów](#składnia-filtrów-proces--ip--port). Np. IP `10.0.0.1-10.0.0.50,!10.0.0.7`, port `80,443,8000-8100`. Puste = dowolne.
@@ -269,7 +285,7 @@ Ich liczby pochodzą z opublikowanych pomiarów wszędzie tam, gdzie pomiary ist
 - **Pociąg / metro (tunele)** - jedyny preset, który kładzie łącze całkowicie na kilka sekund (3 s na każde 30), więc aplikacja musi się **połączyć od nowa**, a nie tylko zwolnić.
 - **Wi-Fi w samolocie** - ten klasyczny, satelitarny: ~750 ms pingu i 7% strat, przy czym to jest zmierzona **mediana**, nie najgorszy przypadek. Samoloty z nowszym sprzętem niskoorbitalnym zachowują się jak „Satelita niskoorbitalny”.
 
-Profil zapisuje to, **jakie jest łącze**: stratę, uszkodzenia, duplikację, opóźnienie, jitter, skoki latencji, przerwy w łączu (flapping), limity prędkości i bufor. Reszta ustawień - cel, adres docelowy, blokada, RST, MTU, wygasanie NAT, harmonogram, seed - do profilu nie wchodzi. Przy zapisie zobaczysz ostrzeżenie z listą tych, które akurat masz włączone. Pełną konfigurację zapisujesz przyciskiem **„Zapisz plik...”**. Wybranie profilu albo presetu ustawia **wszystkie** te pola naraz, także te, których dany preset nie wymienia - wracają wtedy do wartości domyślnej, żeby „Idealna sieć” naprawdę znaczyła idealną. Profile zapisane wcześniejszą wersją wczytują się bez zmian.
+Profil zapisuje to, **jakie jest łącze**: stratę, to ile jej przychodzi pod rząd, uszkodzenia, duplikację, opóźnienie, jitter, skoki latencji, przerwy w łączu (flapping), limity prędkości i bufor. Reszta ustawień - cel, adres docelowy, blokada, RST, MTU, wygasanie NAT, harmonogram, seed - do profilu nie wchodzi. Przy zapisie zobaczysz ostrzeżenie z listą tych, które akurat masz włączone. Pełną konfigurację zapisujesz przyciskiem **„Zapisz plik...”**. Wybranie profilu albo presetu ustawia **wszystkie** te pola naraz, także te, których dany preset nie wymienia - wracają wtedy do wartości domyślnej, żeby „Idealna sieć” naprawdę znaczyła idealną. Profile zapisane wcześniejszą wersją wczytują się bez zmian.
 
 W CLI (`--preset`) preset można podać przez **kanoniczne id** albo **nazwę w dowolnym języku UI** (bez rozróżniania wielkości liter i polskich znaków - `"Idealna siec"` też zadziała). Id: `presets.perfect`, `presets.good_wifi`, `presets.5g`, `presets.dsl`, `presets.lte`, `presets.leo`, `presets.distant`, `presets.weak_wifi`, `presets.cafe`, `presets.bufferbloat`, `presets.metro`, `presets.3g`, `presets.roaming`, `presets.satellite`, `presets.inflight`, `presets.modem56k`, `presets.terrible`.
 
@@ -450,7 +466,8 @@ powód (w języku interfejsu), a CLI kończy się czytelnym `error: ...` - nigdy
 ## Statystyki (co znaczą liczniki)
 
 Wykres przepustowości ma teraz oś Y z wartościami (KB/s), siatkę, „ładnie” zaokrągloną skalę oraz bieżące odczyty down/up w rogu. Pobieranie/Wysyłanie (KB/s na żywo), Pakiety (ile przeszło), W kolejce (czekające - rośnie przy
-opóźnieniu/limicie), Utracone, Uszkodzone, Zduplikowane, Bufor przepełn. (porzucone przy
+opóźnieniu/limicie), Utracone, Serie strat (w ilu SERIACH przyszła ta strata - patrz
+„Straty pod rząd”), Uszkodzone, Zduplikowane, Bufor przepełn. (porzucone przy
 przeciążeniu narzędzia), Porzuc. przy stopie (czekały w kolejce, gdy nacisnięto STOP), Nie odesłane
 (narzędzie je przechwyciło, ale nie zdołało odesłać do sieci - padło połączenie albo sterownik
 odrzucił pakiet), Odrzuc. przez limit (porzucone przez pełny bufor limitu prędkości -
@@ -545,6 +562,7 @@ BeanNetworkTester.exe --simulate --duration 30 --format json > run.ndjson
 | Flaga | Jednostka | Opis |
 |---|---|---|
 | `--loss` | % | procent gubionych pakietów |
+| `--loss-burst` | pakietów | średnia liczba pakietów gubionych pod rząd (0 = strata rozłożona równomiernie). Kształtuje `--loss`, nie dokłada się do niego |
 | `--corrupt` | % | procent pakietów z przekłamanym bitem |
 | `--dup` | % | procent pakietów wysłanych podwójnie |
 | `--latency` | ms | stałe opóźnienie doklejane do każdego pakietu |
@@ -766,6 +784,7 @@ w ogóle policzył - więc każdy wiersz zapisuje to w kolumnie `capture_narrowe
 | `packets_seen` | przechwycone pakiety |
 | `packets_in_scope` | z tego te, które celowanie wybrało do psucia |
 | `dropped_loss` | odrzucone przez ustawienie Strata |
+| `loss_runs` | w ilu SERIACH przyszła ta strata (patrz „Straty pod rząd”). 0 przy ustawionej długości serii znaczy, że sesja była za krótka, żeby zobaczyć choć jedną |
 | `dropped_overflow` | odrzucone, bo kolejka samego narzędzia była pełna |
 | `corrupted` | pakiety z przekłamaną zawartością |
 | `duplicated` | dołożone kopie |

beantester/cli.py

@@ -177,6 +177,8 @@ def build_arg_parser():
                    help="which traffic to capture at all (IPv4 and IPv6). Ports are "
                         "filtered with --dst-port, not here")
     p.add_argument("--loss", type=float, help="packet loss [%%]")
+    p.add_argument("--loss-burst", type=float,
+                   help="average packets lost in a row (0 = spread evenly)")
     p.add_argument("--corrupt", type=float, help="corruption [%%]")
     p.add_argument("--dup", type=float, help="duplication [%%]")
     p.add_argument("--latency", type=float, help="latency [ms]")