From 03216720a60cad28b1ebd8ca7c6f1c69e25aa51c Mon Sep 17 00:00:00 2001 From: DonislawDev Date: Mon, 31 Aug 2026 20:37:26 +0200 Subject: [PATCH 1/6] feat(core): gate impairment by address family, and lower the ceiling to fit it The engine can now be told to touch IPv4 only or IPv6 only. An out-of-family packet takes the same exit as one outside the destination target: passed through untouched and NOT in scope. It is not blocked and not slowed, which is the whole distinction the switch has to survive being misread about. Adding this would have been a thirtieth way through decide(), and that function sat exactly on the pinned complexity ceiling, where the rule is that splitting lowers the number rather than raising it. Its three targeting tests asked one question and returned one identical verdict, so they moved into _out_of_scope() and the ceiling came down with them: 29 -> 27, measured, and the PLR0912 figure quoted next to it re-measured too rather than left to drift. 105 core and scope assertions pass unchanged across the fold. Both switches at once is a legal request meaning "nothing qualifies", stored as an empty set so the contradiction needs no case of its own. Saying out loud that it is probably a mistake belongs to apply_settings, next to the identical warning for LAN mode plus Internet only; refusing it would break a run somebody meant. An address the gate cannot read has no family and is left alone while one is chosen - the direction utils.is_lan_ip already takes. A mapped address (::ffff:1.2.3.4) counts as IPv6, because that is what it is on the wire. --- beantester/core.py | 90 ++++++++++++++++++++++++++++++++++--- pyproject.toml | 18 +++++--- tests/test_core.py | 108 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 203 insertions(+), 13 deletions(-) diff --git a/beantester/core.py b/beantester/core.py index 88f4ad7..a7439b0 100644 --- a/beantester/core.py +++ b/beantester/core.py @@ -236,6 +236,21 @@ def __init__(self): self.dst_port = "" # raw expression text self.dst_ip_matcher = parse_matcher("", KIND_IP) self.dst_port_matcher = parse_matcher("", KIND_INT) + # Address family, part of the SAME question as the two matchers above: + # which remote ends are in scope. ``None`` means both families - the + # default, and the only value that costs nothing in decide(). + # + # Otherwise it is the SET of families that qualify, holding the answer to + # "is this address IPv6?": {False} for IPv4 only, {True} for IPv6 only, + # and the EMPTY set when the user asked for both at once, where no packet + # can qualify. The empty set is why this is a set and not a flag: the + # contradictory request then needs no case of its own, here or in the gate. + # + # It is deliberately NOT a `narrows` field: restricting to one family + # still reaches every connection of that family on the machine, so + # counting it as a bound would silence the blast-radius warning for a + # session that has bounded nothing. Same reasoning `--target *` gets. + self.family_wanted = None self.lan_only = False # LAN mode: cuts internet traffic (public addresses) # The mirror switch: cuts the local network and leaves the internet up. # NOT the exact opposite of the line above - loopback survives both (see @@ -347,6 +362,29 @@ def set_dest(self, active, ip=None, port=None): self.dst_ip_matcher = ip_matcher self.dst_port_matcher = port_matcher + def set_ip_family(self, ipv4_only=False, ipv6_only=False): + """Restrict the targeting to one address family (default: neither). + + Both flags at once is a legal request meaning "no packet qualifies", the + same way LAN mode plus Internet only means "nothing but loopback gets + through": refused nowhere, and said out loud once by ``apply_settings``. + Refusing it would break a run somebody meant. + """ + ipv4_only, ipv6_only = bool(ipv4_only), bool(ipv6_only) + with self._lock: + if not ipv4_only and not ipv6_only: + self.family_wanted = None # both families: no gate + else: + wanted = set() + if ipv4_only: + wanted.add(False) + if ipv6_only: + wanted.add(True) + # Both asked for: {False, True} would accept everything, which is + # the opposite of what the request means. Two mutually exclusive + # "only" switches leave nothing, so the set is emptied on purpose. + self.family_wanted = frozenset() if len(wanted) == 2 else frozenset(wanted) + def set_lan(self, enabled): with self._lock: self.lan_only = bool(enabled) @@ -355,6 +393,37 @@ def set_internet_only(self, enabled): with self._lock: self.internet_only = bool(enabled) + def _out_of_scope(self, remote_ip, remote_port): + """Is this remote end outside what the session is aiming at? + + Called only when something IS aimed (see the caller's left half), so the + cost of the checks here is paid by the session that asked for them. + + The family test is first because it is the cheapest: an IPv6 address in + text form always carries a colon and an IPv4 one never does, so this is a + substring test on a string the caller already has. ``::ffff:1.2.3.4`` + counts as IPv6, which is what it is on the wire. + + An address this cannot read at all (``None`` - ICMP, an unparsed packet) + is out of scope while a family is chosen, the same direction + ``utils.is_lan_ip`` takes with an address it cannot classify: what cannot + be identified must not be damaged. Without a family chosen it is left to + the destination matchers, exactly as before. + """ + if self.family_wanted is not None and ( + remote_ip is None or (":" in remote_ip) not in self.family_wanted): + return True + # ``dst_active`` is asked again rather than assumed from the caller: a + # family alone brings us here with no destination set, and the matchers + # must stay as ignorable then as they were before this gate existed - + # ``set_dest(False, ...)`` keeps whatever expressions it was handed. + if not self.dst_active: + return False + if self.dst_ip_matcher and not self.dst_ip_matcher.matches(remote_ip): + return True + return bool(self.dst_port_matcher + and not self.dst_port_matcher.matches(remote_port)) + def _address_class_cut(self, remote_ip): """Which address-class switch cuts this packet, or ``None``. @@ -578,12 +647,21 @@ def decide(self, size, is_outbound, local_port, now, rng, if not ((is_syn or not is_tcp) and self._owner_targeted is not None and self._owner_targeted(local_port)): return Decision(False, False, [now], scoped=False) - # 2) destination targeting (remote IP/port) - filter expressions - if self.dst_active: - if self.dst_ip_matcher and not self.dst_ip_matcher.matches(remote_ip): - return Decision(False, False, [now], scoped=False) - if self.dst_port_matcher and not self.dst_port_matcher.matches(remote_port): - return Decision(False, False, [now], scoped=False) + # 2) targeting: the destination expressions and the address family. + # + # One gate and one branch for all three, and that is not tidiness: + # this function sits ON the complexity ceiling pinned in + # pyproject.toml, where the rule is that splitting lowers the number + # rather than raising it. The three tests answer the same question + # ("is this remote end in scope?") and returned the identical verdict + # already, so the fold changes nothing a packet can tell apart. + # + # The left half keeps the common case cheap, exactly like step 2b: two + # attribute reads with no targeting armed, and the call happens only in + # a session that asked for it. + if (self.dst_active or self.family_wanted is not None) and self._out_of_scope( + remote_ip, remote_port): + return Decision(False, False, [now], scoped=False) # 2b) the two address-class switches: LAN mode (cut the internet) and # "Internet only" (cut the local network). Both are asked through one diff --git a/pyproject.toml b/pyproject.toml index 2e6c4b3..6ae1115 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -57,9 +57,10 @@ addopts = "-q" # PLR0913 pylint - how many arguments a function takes # # 🔴 Why PLR0913 ALONE out of the pylint refactor rules, and why not the obvious -# three next to it. PLR0912 (branches) scores `core.decide` at 30 where C90 scores -# it 29 - the same function, the same axis, a second number that moves at a -# different rate. PLR0915 (statements) is FUNCTION_CEILING measured worse, because +# three next to it. PLR0912 (branches) scores `core.decide` at 28 where C90 scores +# it 27 - the same function, the same axis, a second number that moves at a +# different rate. (Both were two higher until the targeting tests moved into +# `core._out_of_scope`; re-measured then rather than left to drift.) PLR0915 (statements) is FUNCTION_CEILING measured worse, because # the ratchet in tests/test_code_shape.py counts LOGIC lines and therefore leaves # comments free, which this repository is built on. PLR0911 (returns) needs a # branch per return, so C90 has already counted them. Argument count is the one @@ -97,9 +98,12 @@ max-args = 14 [tool.ruff.lint.mccabe] # 🔴 THE CEILING IS THE MEASUREMENT, like FILE_CEILING in tests/test_code_shape.py. -# 29 is `core.decide` today - the twelve-step packet pipeline, which is branchy -# because the thing it describes is - and 27 is `cli._run_session` behind it. -# Nothing else in the package passes 24. +# 27 is `cli._run_session` and `core.decide` today, level. It was 29, which was +# `decide` alone: adding the address-family gate would have been a thirtieth way +# through that function, so its three targeting tests - which asked one question +# and returned one verdict - moved into `core._out_of_scope` instead, and the +# number came down with them. That is the rule below applied rather than quoted. +# Nothing else in the package passes 25 (`summary.settings_summary`). # # The size ratchet already watches how LONG a function is. This watches how many # ways through it there are, which is the number that decides whether a person @@ -109,7 +113,7 @@ max-args = 14 # # Down is routine, up is a decision. Splitting something means lowering this in # the same change. -max-complexity = 29 +max-complexity = 27 [tool.ruff.lint.per-file-ignores] # A test suite for a packet mangler asserts, randomises, spawns subprocesses and diff --git a/tests/test_core.py b/tests/test_core.py index a29f5ca..fb2eb1d 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -133,6 +133,114 @@ def test_dest_port_targeting(): check("dest port: port 443 impaired", p443.drop is True) +def _family_verdicts(core): + """(IPv4 verdict, IPv6 verdict) for the same 100%-loss settings.""" + rng = random.Random(1) + v4 = core.decide(100, True, 5000, 0.0, rng, remote_ip="1.2.3.4", remote_port=80) + v6 = core.decide(100, True, 5000, 0.0, rng, remote_ip="2001:db8::1", remote_port=80) + return v4, v6 + + +def test_address_family_targeting(): + """One family in scope leaves the other ALONE - not blocked, not slowed. + + That distinction is the whole point of the switch and the thing its label has + to survive being misread about: an out-of-family packet takes the same exit as + a packet outside the destination target, which is "pass it through untouched". + """ + core = BeanCore() + core.set_params(100, 0, 0, 0, 0, 0, 0) # 100% loss for anything in scope + v4, v6 = _family_verdicts(core) + check("default: both families are impaired", v4.drop is True and v6.drop is True) + + core.set_ip_family(ipv4_only=True) + v4, v6 = _family_verdicts(core) + check("IPv4 only: IPv4 impaired", v4.drop is True) + check("IPv4 only: IPv6 passes untouched and out of scope", + v6.drop is False and v6.scoped is False and v6.releases == [0.0]) + + core.set_ip_family(ipv6_only=True) + v4, v6 = _family_verdicts(core) + check("IPv6 only: IPv6 impaired", v6.drop is True) + check("IPv6 only: IPv4 passes untouched", v4.drop is False and v4.scoped is False) + + core.set_ip_family() # back to the default + v4, v6 = _family_verdicts(core) + check("cleared: both families impaired again", + v4.drop is True and v6.drop is True) + + +def test_both_families_only_means_nothing_qualifies(): + """Two mutually exclusive "only" switches leave an empty set, and the engine + says so by impairing nothing - the same shape as LAN mode plus Internet only. + The warning that this is probably a mistake is `apply_settings`' job, not + this one: refusing it here would break a run somebody meant.""" + core = BeanCore() + core.set_params(100, 0, 0, 0, 0, 0, 0) + core.set_ip_family(ipv4_only=True, ipv6_only=True) + v4, v6 = _family_verdicts(core) + check("both 'only' switches: nothing is impaired", + v4.drop is False and v6.drop is False) + check("and nothing is in scope either", + v4.scoped is False and v6.scoped is False) + + +def test_an_address_the_family_gate_cannot_read_is_left_alone(): + """A packet with no remote address (ICMP, an unparsed frame) has no family. + + It goes out of scope while a family is chosen, which is the direction + `utils.is_lan_ip` already takes with an address it cannot classify: what + cannot be identified must not be damaged. With no family chosen it is left to + the destination matchers, exactly as before the gate existed. + """ + core = BeanCore() + core.set_params(100, 0, 0, 0, 0, 0, 0) + rng = random.Random(1) + check("no family chosen: an address-less packet is still impaired", + core.decide(100, True, 5000, 0.0, rng, + remote_ip=None, remote_port=None).drop is True) + core.set_ip_family(ipv4_only=True) + check("family chosen: an address-less packet is left alone", + core.decide(100, True, 5000, 0.0, rng, + remote_ip=None, remote_port=None).drop is False) + + +def test_an_ipv4_mapped_address_counts_as_the_family_it_is_on_the_wire(): + """`::ffff:1.2.3.4` is an IPv6 packet carrying an IPv4 address, and the gate + reads the packet rather than the intent behind the notation.""" + core = BeanCore() + core.set_params(100, 0, 0, 0, 0, 0, 0) + rng = random.Random(1) + core.set_ip_family(ipv6_only=True) + check("IPv6 only: a mapped address is IPv6", + core.decide(100, True, 5000, 0.0, rng, + remote_ip="::ffff:1.2.3.4", remote_port=80).drop is True) + core.set_ip_family(ipv4_only=True) + check("IPv4 only: a mapped address is not IPv4", + core.decide(100, True, 5000, 0.0, rng, + remote_ip="::ffff:1.2.3.4", remote_port=80).drop is False) + + +def test_the_family_gate_and_the_destination_target_both_have_to_pass(): + """Two halves of one question, and the fold that put them in one branch may + not have turned an AND into an OR.""" + core = BeanCore() + core.set_params(100, 0, 0, 0, 0, 0, 0) + core.set_dest(True, ip="1.2.3.4") + core.set_ip_family(ipv4_only=True) + rng = random.Random(1) + check("right family, right address: impaired", + core.decide(100, True, 5000, 0.0, rng, + remote_ip="1.2.3.4", remote_port=80).drop is True) + check("right family, wrong address: passed", + core.decide(100, True, 5000, 0.0, rng, + remote_ip="9.9.9.9", remote_port=80).drop is False) + core.set_ip_family(ipv6_only=True) + check("wrong family, address the target would accept: passed", + core.decide(100, True, 5000, 0.0, rng, + remote_ip="1.2.3.4", remote_port=80).drop is False) + + def test_syn_drop(): core = BeanCore() core.set_advanced(100, 0) # 100% dropped SYN From d4407384ea33df4c379be0bada028ad884c9d413 Mon Sep 17 00:00:00 2001 From: DonislawDev Date: Mon, 31 Aug 2026 20:40:21 +0200 Subject: [PATCH 2/6] feat(i18n): wire the address family into the registry, the CLI and the reports Two BOOL fields in the DESTINATION card, next to the IP and Port they refine - not next to LAN mode and Internet only. Those two CUT traffic; these two only say what is aimed at, and a checkbox that borrows their place inherits their meaning: the first reading of "IPv4 only" under them is "IPv6 is blocked", which is the opposite of what it does. The registry entry, the CLI flag and the seven translation keys land in one commit because the guards refuse anything less: a field without --ipv4-only, or without a label in all three languages, reddens test_field_registry on its own. The flags are --ipv4-only / --ipv6-only, mirroring --internet-only, and no abbreviation collides (there is no other option starting with --o or --ip). Not narrows=True, deliberately: "IPv4 only" still reaches every IPv4 connection on the machine, so marking it as a bound would silence the blast-radius warning for a session that has bounded nothing. Both switches at once is logged once per apply, beside the identical warning for LAN mode plus Internet only, in the words that matter here: nothing will be IMPAIRED, rather than nothing will get through. The default is untouched and the rendered output says so: "Active: 10% loss." and `--loss 10`, with no fragment and no flag added. --- beantester/cli.py | 10 ++++++++++ beantester/engine.py | 3 +++ beantester/fields.py | 24 +++++++++++++++++++++++- beantester/repro.py | 4 ++++ beantester/settings.py | 8 ++++++++ beantester/summary.py | 7 +++++++ lang/en.json | 7 +++++++ lang/pl.json | 7 +++++++ lang/zh.json | 7 +++++++ 9 files changed, 76 insertions(+), 1 deletion(-) diff --git a/beantester/cli.py b/beantester/cli.py index 8e289e9..e2bd3bf 100644 --- a/beantester/cli.py +++ b/beantester/cli.py @@ -143,6 +143,16 @@ def build_arg_parser(): help="affect only these remote ports: number, list, range a-b, " "comparison (>1024), wildcard, re: pattern, ! to exclude " "(e.g. '80,443,8000-8100' or '!53')") + # Part of the targeting, next to --dst-ip: they say WHICH traffic is aimed at, + # and neither blocks anything. The other family keeps flowing untouched. + p.add_argument("--ipv4-only", action="store_true", + help="impair IPv4 traffic only. IPv6 keeps flowing untouched - " + "this aims the tool, it does not block a protocol. Applies " + "with --dst-ip empty too, which means all addresses") + p.add_argument("--ipv6-only", action="store_true", + help="impair IPv6 traffic only. IPv4 keeps flowing untouched. " + "Both flags together exclude each other and nothing is " + "impaired, which the log says out loud") p.add_argument("--lan-mode", action="store_true", help="LAN mode: cut the internet (public addresses), keep the local network") # NOT --lan-cut or --lan-block: a second option starting with "lan-" makes diff --git a/beantester/engine.py b/beantester/engine.py index fa7647f..7d7a33a 100644 --- a/beantester/engine.py +++ b/beantester/engine.py @@ -486,6 +486,9 @@ def process_target_active(self): """ return self.core.process_target_active() + def set_ip_family(self, *a, **kw): + self.core.set_ip_family(*a, **kw) + def set_lan(self, *a): self.core.set_lan(*a) diff --git a/beantester/fields.py b/beantester/fields.py index a0bd90f..277149e 100644 --- a/beantester/fields.py +++ b/beantester/fields.py @@ -195,6 +195,25 @@ class Field(NamedTuple): Field("dst_port", EXPR, "fields.port", "destination", expr_kind=KIND_INT, bounds=PORT_BOUNDS, width=18, tip="tips.dest", span=True, cli="dst-port", narrows=True), + # Which address family the targeting covers - part of the same question as + # the IP field above it, which is why it lives in this card and not next to + # "LAN mode" and "Internet only". Those two CUT traffic (impairs=all); these + # two only say what is aimed at, and a reader who takes the wrong one of those + # meanings ends up believing the tool blocks a whole protocol. + # + # 🔴 NOT narrows=True, and that is a safety decision rather than an omission. + # "IPv4 only" still reaches every IPv4 connection on the machine, so counting + # it as a bound would silence the blast-radius warning for a session that has + # bounded nothing - the same hole `--target *` was fixed for on 2026-08-06. + # + # span=False on both: one decision seen from two sides, so they share a row + # (a BOOL takes a whole row by kind - see Field.span), and the section carries + # columns=2 for them. Both at once is legal and means "nothing qualifies"; + # settings.apply_settings says so once, like the LAN/Internet pair. + Field("ipv4_only", BOOL, "fields.ipv4_only", "destination", + tip="tips.ipv4_only", span=False, cli="ipv4-only"), + Field("ipv6_only", BOOL, "fields.ipv6_only", "destination", + tip="tips.ipv6_only", span=False, cli="ipv6-only"), # -- blocking (firewall) ---------------------------------------------- # # Drop traffic to matching destinations outright. IP OR port (each takes part @@ -323,7 +342,10 @@ class Section(NamedTuple): ("latency", "jitter", "spike_prob", "spike_ms"), columns=2), Section("impairments", "frames.impairments", ("loss", "corrupt", "dup"), columns=3), Section("flapping", "frames.flapping", ("flap_period", "flap_down"), columns=2), - Section("destination", "frames.destination", ("dst_ip", "dst_port"), columns=1), + # columns=2 for the family pair only: both expression fields above carry + # span=True and keep a row each regardless, so this changes nothing they do. + Section("destination", "frames.destination", + ("dst_ip", "dst_port", "ipv4_only", "ipv6_only"), columns=2), Section("block", "frames.block", ("block_ip", "block_port"), columns=1), Section("advanced", "frames.advanced", ("syn_drop", "max_size", "nat_timeout", "rst_prob", "rst_cooldown"), diff --git a/beantester/repro.py b/beantester/repro.py index d720f58..331edb5 100644 --- a/beantester/repro.py +++ b/beantester/repro.py @@ -43,6 +43,10 @@ def settings_to_cli(settings, seed=None, simulate=False): args += ["--block-port", block_port] if g("lan_mode"): args += ["--lan-mode"] + if g("ipv4_only"): + args += ["--ipv4-only"] + if g("ipv6_only"): + args += ["--ipv6-only"] if g("internet_only"): args += ["--internet-only"] # START-only, and it changes what the session even SAW - a command without it diff --git a/beantester/settings.py b/beantester/settings.py index a31ea84..cc1484f 100644 --- a/beantester/settings.py +++ b/beantester/settings.py @@ -23,6 +23,7 @@ loss=0, corrupt=0, dup=0, latency=0, jitter=0, down=0, up=0, buffer=1000, # link buffer (ms) for the speed limit; 0 = unbounded. See fields.py filter="both", target="", dst_ip="", dst_port="", lan_mode=False, + ipv4_only=False, ipv6_only=False, internet_only=False, # the mirror of lan_mode; loopback survives both block_ip="", block_port="", # firewall: drop traffic to matching IP/port @@ -531,6 +532,13 @@ def apply_settings(engine, s, log=lambda *_: None): # validate up front (validate_settings), so a user never reaches this. log(f"{T('log.filter_skipped')}: {e}") engine.set_dest(False) + engine.set_ip_family(bool(g("ipv4_only")), bool(g("ipv6_only"))) + # The same shape as the pair below, and said for the same reason: two "only" + # switches that exclude each other leave nothing to aim at, the symptom is a + # session that changes nothing, and that looks like a broken tool rather than + # like the tool doing what it was told. + if g("ipv4_only") and g("ipv6_only"): + log(T("log.ipv4_and_ipv6_only")) engine.set_lan(bool(g("lan_mode"))) engine.set_internet_only(bool(g("internet_only"))) # Both at once is a legal request - it is the union of two impairments, the diff --git a/beantester/summary.py b/beantester/summary.py index da50141..6e9e70e 100644 --- a/beantester/summary.py +++ b/beantester/summary.py @@ -55,6 +55,13 @@ def settings_summary(s, lang=None, prefix_key="summary.prefix"): parts.append(tr("summary.rst", v=num("rst_prob"))) if to_number(g("flap_period")) and to_number(g("flap_down")): parts.append(tr("summary.flap", v=num("flap_period"))) + # Scope, not damage - so they read next to the destination below rather than + # among the impairments. Nothing is added at the default (neither switch on), + # which keeps the summary of a fresh form exactly what it was. + if g("ipv4_only"): + parts.append(tr("summary.ipv4_only")) + if g("ipv6_only"): + parts.append(tr("summary.ipv6_only")) if g("lan_mode"): parts.append(tr("summary.lan")) if g("internet_only"): diff --git a/lang/en.json b/lang/en.json index 57785c7..682e65b 100644 --- a/lang/en.json +++ b/lang/en.json @@ -186,6 +186,8 @@ "fields.flap_down_pct": "Downtime percent:", "fields.internet_only": "Internet only (no local network)", "fields.ip": "IP:", + "fields.ipv4_only": "IPv4 addresses only", + "fields.ipv6_only": "IPv6 addresses only", "fields.jitter": "Jitter:", "fields.lan_mode": "LAN mode (local network only, no internet)", "fields.latency": "Latency:", @@ -273,6 +275,7 @@ "log.engine_fault": "Engine fault: {e} - the session was stopped, your network is back to normal.", "log.error": "Error", "log.filter_skipped": "This expression could not be read, so it was switched off for this session", + "log.ipv4_and_ipv6_only": "IPv4 addresses only and IPv6 addresses only are both on. No packet is both, so nothing will be impaired.", "log.lan_and_internet_only": "LAN mode and Internet only are both on - nothing but loopback gets through.", "log.layout_reset": "Window layout reset.", "log.loaded_profile": "Loaded profile", @@ -421,6 +424,8 @@ "summary.dup": "{v}% duplicates", "summary.flap": "outages every {v} s", "summary.internet_only": "internet only (no local network)", + "summary.ipv4_only": "IPv4 only", + "summary.ipv6_only": "IPv6 only", "summary.jitter": "jitter +/-{v} ms", "summary.lan": "LAN mode (no internet)", "summary.latency": "+{v} ms ping", @@ -499,6 +504,8 @@ "tips.flap": "Cyclic full outages: every 'Period' seconds the link is dead for the given percent of the time. Simulates a flapping connection (e.g. weak WiFi).", "tips.freeze": "Freeze the table so rows stop moving while you inspect or copy them.", "tips.internet_only": "Cuts the local network and leaves the internet up: traffic to and from local addresses (10.x, 192.168.x, 172.16-31.x, link-local, CGNAT) is dropped. Loopback (127.x) keeps working, so programs talking to themselves on this machine are left alone. Careful: if your PC asks the router for DNS, the internet stops working too, because those queries are local traffic.", + "tips.ipv4_only": "Impairments touch IPv4 traffic only. IPv6 keeps flowing normally: it is not blocked and not slowed, just left alone. This applies with the IP field empty too, which means all addresses.", + "tips.ipv6_only": "Impairments touch IPv6 traffic only. IPv4 keeps flowing normally: it is not blocked and not slowed, just left alone. This applies with the IP field empty too, which means all addresses.", "tips.jitter": "Random delay variation (+/- ms), drawn separately for every packet. Ping starts to jump instead of being steady. It also lightly reorders packets. The request and the reply each get their own draw, so the wobble on ping is wider than this number - about 1.4x usually, up to 2x at the extremes.", "tips.lan_mode": "Simulates a network with no internet access: traffic to/from public addresses is dropped, while the local network (LAN: 10.x, 192.168.x, 172.16-31.x, loopback) works. Tests how the app behaves when the internet is down but the intranet is up.", "tips.language": "Interface language. Switching rebuilds the UI but keeps the current session and settings. Locked while running.", diff --git a/lang/pl.json b/lang/pl.json index f72c7af..fa40f81 100644 --- a/lang/pl.json +++ b/lang/pl.json @@ -186,6 +186,8 @@ "fields.flap_down_pct": "Procent przerwy w łączu:", "fields.internet_only": "Tylko internet (bez sieci lokalnej)", "fields.ip": "IP:", + "fields.ipv4_only": "Tylko adresy IPv4", + "fields.ipv6_only": "Tylko adresy IPv6", "fields.jitter": "Jitter:", "fields.lan_mode": "Tryb LAN (tylko sieć lokalna, bez internetu)", "fields.latency": "Latencja:", @@ -273,6 +275,7 @@ "log.engine_fault": "Awaria silnika: {e} - sesja została zatrzymana, sieć działa normalnie.", "log.error": "Błąd", "log.filter_skipped": "Nie udało się odczytać tego wyrażenia, więc zostało wyłączone na tę sesję", + "log.ipv4_and_ipv6_only": "Włączone są naraz Tylko adresy IPv4 i Tylko adresy IPv6. Żaden pakiet nie jest jednym i drugim, więc nic nie zostanie zmienione.", "log.lan_and_internet_only": "Tryb LAN i Tylko internet są włączone naraz - poza loopbackiem nic nie przejdzie.", "log.layout_reset": "Układ okna zresetowany.", "log.loaded_profile": "Wczytano profil", @@ -421,6 +424,8 @@ "summary.dup": "{v}% duplikatów", "summary.flap": "przerwy co {v} s", "summary.internet_only": "tylko internet (bez sieci lokalnej)", + "summary.ipv4_only": "tylko IPv4", + "summary.ipv6_only": "tylko IPv6", "summary.jitter": "jitter +/-{v} ms", "summary.lan": "tryb LAN (bez internetu)", "summary.latency": "+{v} ms pingu", @@ -499,6 +504,8 @@ "tips.flap": "Cykliczne całkowite zrywanie ruchu: co 'Okres' sekund łącze jest martwe przez podany procent czasu. Symuluje migające połączenie (np. słabe WiFi).", "tips.freeze": "Zamroź tabelę, żeby wiersze nie uciekały podczas przeglądania i kopiowania.", "tips.internet_only": "Odcina sieć lokalną, a zostawia internet: ruch do i od adresów lokalnych (10.x, 192.168.x, 172.16-31.x, link-local, CGNAT) jest odrzucany. Loopback (127.x) działa dalej, więc programy rozmawiające same ze sobą na tej maszynie zostają nietknięte. Uwaga: jeśli komputer pyta o DNS router, internet też przestanie działać, bo takie zapytania to ruch lokalny.", + "tips.ipv4_only": "Zakłócenia dotykają tylko ruchu po IPv4. Ruch IPv6 płynie normalnie: nie jest blokowany ani spowalniany, po prostu zostaje bez zmian. Działa też przy pustym polu IP, czyli dla wszystkich adresów.", + "tips.ipv6_only": "Zakłócenia dotykają tylko ruchu po IPv6. Ruch IPv4 płynie normalnie: nie jest blokowany ani spowalniany, po prostu zostaje bez zmian. Działa też przy pustym polu IP, czyli dla wszystkich adresów.", "tips.jitter": "Losowe wahanie opóźnienia (+/- ms), losowane osobno dla każdego pakietu. Ping zaczyna skakać zamiast być stały. Powoduje też lekkie mieszanie kolejności pakietów. Zapytanie i odpowiedź losują niezależnie, więc wahania pingu są szersze niż ta liczba - zwykle około 1,4x, w skrajności 2x.", "tips.lan_mode": "Symuluje sieć bez dostępu do internetu: ruch do/od adresów publicznych jest odrzucany, a sieć lokalna (LAN: 10.x, 192.168.x, 172.16-31.x, loopback) działa. Test zachowania aplikacji, gdy internet jest niedostępny, a intranet tak.", "tips.language": "Język interfejsu. Przełączenie przebudowuje UI, ale zachowuje bieżącą sesję i ustawienia. Zablokowane w trakcie działania.", diff --git a/lang/zh.json b/lang/zh.json index e8d6800..7684f3a 100644 --- a/lang/zh.json +++ b/lang/zh.json @@ -186,6 +186,8 @@ "fields.flap_down_pct": "中断占比:", "fields.internet_only": "仅互联网（禁用本地网络）", "fields.ip": "IP:", + "fields.ipv4_only": "仅 IPv4 地址", + "fields.ipv6_only": "仅 IPv6 地址", "fields.jitter": "抖动:", "fields.lan_mode": "局域网模式（仅本地网络，不访问互联网）", "fields.latency": "延迟:", @@ -273,6 +275,7 @@ "log.engine_fault": "引擎故障：{e}。会话已停止，网络已恢复正常。", "log.error": "错误", "log.filter_skipped": "无法解析此表达式，本次会话已将其关闭", + "log.ipv4_and_ipv6_only": "同时启用了“仅 IPv4 地址”和“仅 IPv6 地址”。没有数据包同时属于两者，因此不会有任何改动。", "log.lan_and_internet_only": "“局域网模式”和“仅互联网”同时启用，因此除环回流量外，其他流量都无法通过。", "log.layout_reset": "窗口布局已重置。", "log.loaded_profile": "已加载配置方案", @@ -421,6 +424,8 @@ "summary.dup": "{v}% 重复包", "summary.flap": "每 {v} 秒发生中断", "summary.internet_only": "仅互联网（无本地网络）", + "summary.ipv4_only": "仅 IPv4", + "summary.ipv6_only": "仅 IPv6", "summary.jitter": "抖动 ±{v} ms", "summary.lan": "局域网模式（无互联网）", "summary.latency": "延迟 +{v} ms", @@ -499,6 +504,8 @@ "tips.flap": "周期性完全断线：每隔“周期”秒，链路会按设定的时间比例处于中断状态。可模拟反复掉线的连接，例如信号很弱的 Wi‑Fi。", "tips.freeze": "冻结表格，使各行暂时不再移动，方便检查或复制。", "tips.internet_only": "切断本地网络但保留互联网：与本地地址（10.x、192.168.x、172.16-31.x、链路本地地址、CGNAT）往返的流量会被丢弃。环回地址（127.x）仍可使用，因此本机程序之间的内部通信不受影响。注意：若电脑向路由器请求 DNS，互联网也会失效，因为这些 DNS 查询属于本地流量。", + "tips.ipv4_only": "只对 IPv4 流量施加弱网效果。IPv6 流量照常通过，既不会被阻断也不会被限速，只是保持原样。即使 IP 字段为空（即所有地址）也同样生效。", + "tips.ipv6_only": "只对 IPv6 流量施加弱网效果。IPv4 流量照常通过，既不会被阻断也不会被限速，只是保持原样。即使 IP 字段为空（即所有地址）也同样生效。", "tips.jitter": "为每个数据包分别随机增加或减少指定毫秒数的延迟，使 Ping 不再稳定并产生轻微乱序。请求和响应会各自独立随机，因此 Ping 的实际波动通常约为此数值的 1.4 倍，极端情况下可达到 2 倍。", "tips.lan_mode": "模拟无法访问互联网但局域网仍可用的环境：与公共地址往返的流量会被丢弃，而局域网地址（10.x、192.168.x、172.16-31.x、环回地址）仍可通信。可用于测试应用在断网但内网正常时的表现。", "tips.language": "界面语言。切换后会重建界面，但当前会话和设置都会保留。会话运行期间无法切换。", From dc1fcd907647b7f03b2fe7bc59ebbec49238a3a7 Mon Sep 17 00:00:00 2001 From: DonislawDev Date: Mon, 31 Aug 2026 20:45:02 +0200 Subject: [PATCH 3/6] test(core): pin the default that the family switch could quietly undo Capturing IPv6 was not free here: the filters once began with `ip and ...`, which in the WinDivert language is IPv4 ONLY, so every IPv6 packet went past the tool uncounted and unlisted. A switch that can ask for exactly that state deserves a guard on the state it starts in, rather than a promise in a commit message. Four assertions, each on a surface a regression would show up on: every driver filter still carries both families, character for character; both fields default to off; a default session impairs an IPv4 and an IPv6 packet alike; and the summary and the reproduction command gain nothing at the default, with the opposite direction asserted too so it cannot pass by the flags never existing. The filter strings are literals rather than values read from the code under test. A guard that builds its expectation the way the code does agrees with the code by construction, including when the code is wrong. The GUI needed no code: the registry places both checkboxes on one row under IP and Port by itself. Verified on real Tk at 1366x768 in all three languages. --- tests/test_ip_family_default.py | 87 +++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 tests/test_ip_family_default.py diff --git a/tests/test_ip_family_default.py b/tests/test_ip_family_default.py new file mode 100644 index 0000000..c0d22f8 --- /dev/null +++ b/tests/test_ip_family_default.py @@ -0,0 +1,87 @@ +"""Both address families are the default, and adding a way to choose one may not change that. + +WHY THIS FILE EXISTS AT ALL + Capturing IPv6 was not free here. The filters all began with ``ip and ...``, + which in the WinDivert language means IPv4 ONLY, so every IPv6 packet went + past the tool - not impaired, not counted, not listed - which on a dual-stack + machine is most of a browser's traffic. ``filters.py`` was rewritten around + that, and its module docstring still leads with the rule. + + The address-family switch is a way to ask for exactly the state that bug + produced. That makes the DEFAULT worth a guard of its own rather than a + shrug: everything here asserts what an untouched form does, and nothing here + asserts what the new switch does (``test_core.py`` covers that). + + The filter strings are written out as literals rather than computed from the + thing under test. A guard that builds its expectation the same way the code + does agrees with the code by construction, including when the code is wrong - + which is precisely the failure this file is here to catch. +""" +import random + +from beantester.core import BeanCore +from beantester.filters import FILTER_DEFS, windivert_for +from beantester.repro import settings_to_cli +from beantester.settings import DEFAULT_SETTINGS, settings_from_raw +from beantester.summary import settings_summary +from fakes import check + +# Every driver filter this program can ask for, spelled out. Both families in +# every one of them: `ip` is IPv4, `ipv6` is IPv6, and `ping` covers both through +# its two protocol names instead. +EXPECTED_FILTERS = { + "both": "(ip or ipv6) and (tcp or udp or icmp or icmpv6)", + "out": "outbound and (ip or ipv6) and (tcp or udp or icmp or icmpv6)", + "in": "inbound and (ip or ipv6) and (tcp or udp or icmp or icmpv6)", + "tcp": "(ip or ipv6) and tcp", + "udp": "(ip or ipv6) and udp", + "ping": "icmp or icmpv6", + "loopback": "loopback and (ip or ipv6) and (tcp or udp or icmp or icmpv6)", +} + + +def _settings(**overrides): + result = settings_from_raw(dict(overrides)) + return result[0] if isinstance(result, tuple) else result + + +def test_every_driver_filter_still_carries_both_families(): + """The one that would catch a family folded into the filter by accident.""" + check("the registry gained or lost no filter", + sorted(key for key, _, _ in FILTER_DEFS) == sorted(EXPECTED_FILTERS), + f"({sorted(key for key, _, _ in FILTER_DEFS)})") + for key, expected in EXPECTED_FILTERS.items(): + check(f"filter {key!r} is unchanged, character for character", + windivert_for(key) == expected, f"({windivert_for(key)!r})") + + +def test_the_default_settings_choose_neither_family(): + check("ipv4_only is off by default", DEFAULT_SETTINGS["ipv4_only"] is False) + check("ipv6_only is off by default", DEFAULT_SETTINGS["ipv6_only"] is False) + + +def test_a_default_session_impairs_both_families(): + """The behaviour the switch exists to narrow, asserted from the other side.""" + core = BeanCore() + core.set_params(100, 0, 0, 0, 0, 0, 0) + rng = random.Random(1) + v4 = core.decide(100, True, 5000, 0.0, rng, remote_ip="1.2.3.4", remote_port=80) + v6 = core.decide(100, True, 5000, 0.0, rng, remote_ip="2001:db8::1", remote_port=80) + check("IPv4 is impaired by default", v4.drop is True and v4.scoped is True) + check("IPv6 is impaired by default", v6.drop is True and v6.scoped is True) + + +def test_the_default_summary_and_repro_command_gained_nothing(): + """A field that says nothing at its default keeps the two things a user reads + exactly as they were - the sentence under the title and the command they copy.""" + settings = _settings(loss=10) + summary = settings_summary(settings, lang="en") + check("no family fragment in the summary of a default form", + "IPv4" not in summary and "IPv6" not in summary, f"({summary!r})") + args = settings_to_cli(settings) + check("no family flag in the reproduction command", + "--ipv4-only" not in args and "--ipv6-only" not in args, f"({args})") + # And the other direction, so this cannot pass by the flags never existing. + armed = settings_to_cli(_settings(loss=10, ipv4_only=True)) + check("the flag does appear once it is asked for", "--ipv4-only" in armed, + f"({armed})") From da93de23fbe8dc1e8e75edb73663961dc0e0cd21 Mon Sep 17 00:00:00 2001 From: DonislawDev Date: Mon, 31 Aug 2026 20:46:32 +0200 Subject: [PATCH 4/6] docs: document the family switches where a person actually looks for them Both READMEs get the flag row next to --lan-mode, and the guard that demands it is why this is one commit and not a forgotten follow-up: test_cli_docs reddens on an undocumented flag. The user-facing line leads with what the switch does NOT do, because that is the half a reader gets wrong: the other family keeps flowing, nothing is blocked and nothing is slowed. The internal entry records what was deliberately left out - the WinDivert filter, and the reasons folding the family in there is its own change - so the next session does not read the omission as an oversight. --- CHANGELOG.md | 7 +++++++ README.md | 1 + README.pl.md | 1 + 3 files changed, 9 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ac745d4..5c58f07 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ The format follows [Keep a Changelog](https://keepachangelog.com/); versions fol ### Added +- **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 + with the address field empty too, which means all addresses. Turning both on excludes + everything and the log says so. Left alone, the program does what it always did and + covers both families. + - **Simplified Chinese interface translation.** The GUI now ships with a complete `zh` language file alongside English and Polish. A system set to Simplified Chinese selects it automatically. A system set to Traditional Chinese starts in English instead, because the diff --git a/README.md b/README.md index f0f4829..59aab49 100644 --- a/README.md +++ b/README.md @@ -707,6 +707,7 @@ BeanNetworkTester.exe --simulate --duration 30 --format json > run.ndjson | `--rst-prob` `--rst-cooldown` | % / s | percentage of connections torn with RST and how long the tear-down is held | | `--flap-period` `--flap-down` | s / % | cyclic link outage: how often and for what fraction of the period | | `--rate-schedule` | - | changing throughput: `"time:download:upload,..."` in KB/s, looped | +| `--ipv4-only` `--ipv6-only` | - | impair one address family only. The other keeps flowing untouched - this aims the tool, it does not block a protocol. Works with `--dst-ip` empty too, which means all addresses. Both flags at once exclude each other, nothing is impaired, and the log says so | | `--lan-mode` | - | LAN mode: cut off the internet (public addresses), keep the local network | | `--internet-only` | - | the mirror: cut off the local network (10.x, 172.16-31.x, 192.168.x, link-local, CGNAT), keep the internet. Loopback keeps working. Careful: DNS asked of your router is local traffic, so the internet can stop working with it | | `--narrow-filter` | - | push `--dst-ip`/`--dst-port` into the WinDivert filter so the driver never hands over traffic that could not be impaired (much faster at high packet rates). START-time only. While it is on, statistics and connections cover the narrowed traffic only | diff --git a/README.pl.md b/README.pl.md index eedfd06..4efcb35 100644 --- a/README.pl.md +++ b/README.pl.md @@ -558,6 +558,7 @@ BeanNetworkTester.exe --simulate --duration 30 --format json > run.ndjson | `--rst-prob` `--rst-cooldown` | % / s | procent połączeń zrywanych RST-em i czas trzymania zerwanego | | `--flap-period` `--flap-down` | s / % | cykliczne zrywanie łącza: co ile i na jaki ułamek okresu | | `--rate-schedule` | - | zmienna przepustowość: `"czas:pobieranie:wysyłanie,..."` w KB/s, w pętli | +| `--ipv4-only` `--ipv6-only` | - | psuj ruch tylko jednej rodziny adresów. Druga płynie bez zmian - to celowanie, nie blokada protokołu. Działa też przy pustym `--dst-ip`, czyli dla wszystkich adresów. Obie flagi naraz wykluczają się, nic nie zostanie zmienione, a log to mówi | | `--lan-mode` | - | tryb LAN: odetnij internet (adresy publiczne), zostaw sieć lokalną | | `--internet-only` | - | lustro tamtego: odetnij sieć lokalną (10.x, 172.16-31.x, 192.168.x, link-local, CGNAT), zostaw internet. Loopback działa dalej. Uwaga: DNS pytany u routera to ruch lokalny, więc internet może przestać działać razem z siecią lokalną | | `--narrow-filter` | - | wepchnij `--dst-ip`/`--dst-port` do filtra WinDiverta, żeby sterownik w ogóle nie podawał ruchu, którego nie dałoby się popsuć (dużo szybciej przy dużej liczbie pakietów). Tylko przy STARCIE. Gdy działa, statystyki i połączenia obejmują wyłącznie zawężony ruch | From 47cb3e07d2683e78fad0dd9c0d2f669e7ba48760 Mon Sep 17 00:00:00 2001 From: DonislawDev Date: Mon, 31 Aug 2026 20:50:35 +0200 Subject: [PATCH 5/6] test(cli): teach the engine doubles the setter apply_settings now calls Eleven CLI runtime tests went red on a fake engine with no set_ip_family, and the failure looked nothing like its cause: the blast-radius warnings stopped appearing, because the run died before reaching them. The doubles are a consumer of the engine's interface, and they were the one consumer the analysis for this change did not enumerate. Adding the method is the whole fix - checked on master first, where the same file is green, so the question "is this mine or was it already broken" was answered by measurement rather than by assumption. --- tests/test_cli_runtime.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/test_cli_runtime.py b/tests/test_cli_runtime.py index b830bbe..b1f477a 100644 --- a/tests/test_cli_runtime.py +++ b/tests/test_cli_runtime.py @@ -214,6 +214,7 @@ def set_seed(self, *_a, **_k): pass def set_params(self, *_a, **_k): pass def set_buffer(self, *_a, **_k): pass def set_dest(self, *_a, **_k): pass + def set_ip_family(self, *_a, **_k): pass def set_lan(self, *_a, **_k): pass def set_internet_only(self, *_a, **_k): pass def set_block(self, *_a, **_k): pass @@ -374,6 +375,7 @@ def set_seed(self, *_a, **_k): pass def set_params(self, *_a, **_k): pass def set_buffer(self, *_a, **_k): pass def set_dest(self, *_a, **_k): pass + def set_ip_family(self, *_a, **_k): pass def set_lan(self, *_a, **_k): pass def set_internet_only(self, *_a, **_k): pass def set_block(self, *_a, **_k): pass From 80dca85291819560e00440b77748b5196d4dd6ae Mon Sep 17 00:00:00 2001 From: DonislawDev Date: Mon, 31 Aug 2026 21:03:18 +0200 Subject: [PATCH 6/6] refactor: answer the three shape ratchets the family switches tripped All three fired on CI, all three were right, and two of them are the opposite of what their numbers look like. build_arg_parser passed the size ceiling (135 > 133) when the two flags landed, and the ratchet's message says what to do rather than leaving it to taste: split it, do not raise the ceiling. The seam was already there. _add_scope_arguments now holds the ten flags that say WHICH traffic is aimed at - process, destination, address family, address class, blocking - and what stays behind says what is done to it. settings_summary had gone 25 -> 27 on two new branches, which is exactly the creep that ratchet exists to catch. Four plain on/off switches that each append one fixed phrase are now one loop over a table: back to 25, and a fifth switch costs nothing anything counts. COMPLEX_NEAR_CEILING moves 3 -> 5 and nothing grew into that band. Lowering max-complexity to 27 moved the 70% line from 20 to 18, so _capture_loop (20) and _module_level (19) are inside it without changing by a line. Re-measured and written down, because the count alone reads like a regression. The mutation that proves the guard can fail was re-anchored onto the new constant. Found by CI and not locally: the run here covered the surfaces this change touched, and these three scan the whole tree. --- beantester/cli.py | 88 +++++++++++++++++++-------------- beantester/summary.py | 25 +++++----- tests/test_code_shape.py | 15 +++++- tests/test_mutation_registry.py | 8 ++- 4 files changed, 84 insertions(+), 52 deletions(-) diff --git a/beantester/cli.py b/beantester/cli.py index e2bd3bf..3476989 100644 --- a/beantester/cli.py +++ b/beantester/cli.py @@ -93,44 +93,15 @@ def _fail(code, message): """ -def build_arg_parser(): - p = argparse.ArgumentParser( - prog=program_name(), - # One line, not the 24 argparse generates from about fifty flags. Those - # 24 lines sat above every readable thing in --help, and above the message - # on a typo too - so the one sentence saying what was wrong arrived at the - # bottom of a wall nobody reads. The flags are listed in full immediately - # below, which is where a list belongs (clig.dev). - usage="%(prog)s [options]", - formatter_class=argparse.RawDescriptionHelpFormatter, - description=_DESCRIPTION, - epilog=exitcodes.HELP_TABLE) - p.add_argument("--version", action="version", - version=f"{APP_NAME} {__version__}") - p.add_argument("--license", action="store_true", - help="print the licence and the third-party notices, then exit") - p.add_argument("--gui", action="store_true", - help="open the GUI (only valid on its own - the GUI has its " - "own controls, so it takes no settings flags)") - p.add_argument("--config", help="load settings from a JSON file") - p.add_argument("--save-config", help="save effective settings to a JSON file and exit") - p.add_argument("--preset", metavar="PRESET", - help="load a preset by canonical id or by its name in any UI " - "language (the README lists them)") - p.add_argument("--filter", choices=list(CLI_FILTERS), default=None, - 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("--corrupt", type=float, help="corruption [%%]") - p.add_argument("--dup", type=float, help="duplication [%%]") - p.add_argument("--latency", type=float, help="latency [ms]") - p.add_argument("--jitter", type=float, help="jitter [ms]") - p.add_argument("--down", type=float, help="download limit [KB/s]") - p.add_argument("--up", type=float, help="upload limit [KB/s]") - p.add_argument("--buffer", type=float, - help="link buffer for the speed limit [ms], 0 = unlimited. It " - "bounds the queueing delay a rate-limited link builds up " - "before it drops (bufferbloat)") +def _add_scope_arguments(p): + """The flags that say WHICH traffic is aimed at, rather than what is done to it. + + Split out of ``build_arg_parser`` when the two address-family switches pushed + that function past the size ratchet, and the ratchet said what to do about it: + split, do not raise the ceiling. This is where the seam already was - process, + destination, address family, address class and blocking all answer "which + packets", while everything left behind answers "how are they damaged". + """ p.add_argument("--target", help="target processes: name/PID, comma-separated list, range, " "wildcard, re: pattern, ! to exclude " @@ -176,6 +147,47 @@ def build_arg_parser(): help="block (drop) all traffic to these remote ports: number, list, " "range a-b, comparison (>1024), wildcard, re: pattern, ! to exclude " "(blocks on IP OR port, for example '--block-port 443')") + + +def build_arg_parser(): + p = argparse.ArgumentParser( + prog=program_name(), + # One line, not the 24 argparse generates from about fifty flags. Those + # 24 lines sat above every readable thing in --help, and above the message + # on a typo too - so the one sentence saying what was wrong arrived at the + # bottom of a wall nobody reads. The flags are listed in full immediately + # below, which is where a list belongs (clig.dev). + usage="%(prog)s [options]", + formatter_class=argparse.RawDescriptionHelpFormatter, + description=_DESCRIPTION, + epilog=exitcodes.HELP_TABLE) + p.add_argument("--version", action="version", + version=f"{APP_NAME} {__version__}") + p.add_argument("--license", action="store_true", + help="print the licence and the third-party notices, then exit") + p.add_argument("--gui", action="store_true", + help="open the GUI (only valid on its own - the GUI has its " + "own controls, so it takes no settings flags)") + p.add_argument("--config", help="load settings from a JSON file") + p.add_argument("--save-config", help="save effective settings to a JSON file and exit") + p.add_argument("--preset", metavar="PRESET", + help="load a preset by canonical id or by its name in any UI " + "language (the README lists them)") + p.add_argument("--filter", choices=list(CLI_FILTERS), default=None, + 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("--corrupt", type=float, help="corruption [%%]") + p.add_argument("--dup", type=float, help="duplication [%%]") + p.add_argument("--latency", type=float, help="latency [ms]") + p.add_argument("--jitter", type=float, help="jitter [ms]") + p.add_argument("--down", type=float, help="download limit [KB/s]") + p.add_argument("--up", type=float, help="upload limit [KB/s]") + p.add_argument("--buffer", type=float, + help="link buffer for the speed limit [ms], 0 = unlimited. It " + "bounds the queueing delay a rate-limited link builds up " + "before it drops (bufferbloat)") + _add_scope_arguments(p) p.add_argument("--syn-drop", type=float, help="dropped TCP SYN rate [%%]") p.add_argument("--max-size", type=int, help="MTU black hole: drop packets > N B") p.add_argument("--spike-prob", type=float, help="latency spike probability [%%]") diff --git a/beantester/summary.py b/beantester/summary.py index 6e9e70e..24d1c90 100644 --- a/beantester/summary.py +++ b/beantester/summary.py @@ -55,17 +55,20 @@ def settings_summary(s, lang=None, prefix_key="summary.prefix"): parts.append(tr("summary.rst", v=num("rst_prob"))) if to_number(g("flap_period")) and to_number(g("flap_down")): parts.append(tr("summary.flap", v=num("flap_period"))) - # Scope, not damage - so they read next to the destination below rather than - # among the impairments. Nothing is added at the default (neither switch on), - # which keeps the summary of a fresh form exactly what it was. - if g("ipv4_only"): - parts.append(tr("summary.ipv4_only")) - if g("ipv6_only"): - parts.append(tr("summary.ipv6_only")) - if g("lan_mode"): - parts.append(tr("summary.lan")) - if g("internet_only"): - parts.append(tr("summary.internet_only")) + # The plain on/off switches, as a table rather than four identical branches. + # Each one adds a fixed phrase when it is on and nothing when it is off, so + # there was never anything to tell them apart except the two names - and the + # size and complexity ratchets both count the branches, which is how a fifth + # switch would have started costing something it should not. + # + # Order is the reading order of the form: which traffic is aimed at + # (the family pair), then which address classes are cut. + for key, phrase in (("ipv4_only", "summary.ipv4_only"), + ("ipv6_only", "summary.ipv6_only"), + ("lan_mode", "summary.lan"), + ("internet_only", "summary.internet_only")): + if g(key): + parts.append(tr(phrase)) if scheduled: parts.append(tr("summary.schedule")) if str(g("target")).strip(): diff --git a/tests/test_code_shape.py b/tests/test_code_shape.py index ac58862..30f9d47 100644 --- a/tests/test_code_shape.py +++ b/tests/test_code_shape.py @@ -493,7 +493,20 @@ def test_the_ceilings_are_not_set_so_loosely_that_they_never_fire(): # counts, which walk the package only. That is deliberate: the ceiling this band # hangs from is repo-wide, so a band scoped to the package would be measuring a # different thing from the number it is a percentage of. -COMPLEX_NEAR_CEILING = 3 # decide, _run_session, settings_summary +# 🔴 5 since 2026-08-31, and the reason matters more than the number: NOTHING grew +# into this band. The band came down to two functions that were already there. +# `core.decide` was split for the address-family gate, which lowered the ceiling +# from 29 to 27 (the rule beside max-complexity), and 70% of 27 is 18 where 70% of +# 29 was 20 - so `engine._capture_loop` at 20 and `test_layering._module_level` at +# 19 are in the band without either of them changing by a line. +# +# That is worth writing down because the count alone reads like a regression and +# is the opposite: `decide` went 29 -> 27 and `summary.settings_summary` came back +# to 25 from the 27 the same change had pushed it to. Lowering a ceiling tightens +# the band that hangs off it, and this number has to be re-measured when it moves, +# exactly like the ceiling itself. +COMPLEX_NEAR_CEILING = 5 # decide, _run_session, settings_summary, + # _capture_loop, test_layering._module_level # Ruff is not in requirements-dev.txt: it lives in requirements-lint.txt, which a diff --git a/tests/test_mutation_registry.py b/tests/test_mutation_registry.py index 9e19500..490a8be 100644 --- a/tests/test_mutation_registry.py +++ b/tests/test_mutation_registry.py @@ -368,8 +368,12 @@ # function and cannot see the runners-up climbing together underneath it. "label": "ratchet: the complexity crowd count is frozen looser than the measurement", "file": "tests/test_code_shape.py", - "old": "COMPLEX_NEAR_CEILING = 3 # decide, _run_session, settings_summary", - "new": "COMPLEX_NEAR_CEILING = 5 # decide, _run_session, settings_summary", + # Re-anchored 2026-08-31: the constant moved 3 -> 5 when the complexity + # ceiling came down and the band came down with it. The mutation still + # proves the same thing - a count frozen looser than today's measurement + # is caught by the equality half of that test, not by the "at most" half. + "old": "COMPLEX_NEAR_CEILING = 5 # decide, _run_session, settings_summary,", + "new": "COMPLEX_NEAR_CEILING = 7 # decide, _run_session, settings_summary,", "test": "test_nothing_else_is_creeping_up_on_the_complexity_ceiling", }, {