From a8aaf1c4ff9c4ead6b6fe3a43d28f2a0f5726cd7 Mon Sep 17 00:00:00 2001 From: Leon Krix Date: Wed, 11 Nov 2026 15:12:33 +0100 Subject: [PATCH 1/2] chore: release 0.3.0 --- CHANGELOG.md | 41 ++++++++++++++++++++++++ Cargo.lock | 12 +++---- Cargo.toml | 12 +++---- docs/ACCEPTANCE.md | 5 +++ python/pytest-netscenario/pyproject.toml | 4 +-- uv.lock | 6 ++-- 6 files changed, 63 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b2af878..d0b1ff3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,47 @@ Every release of netscenario, newest first. The lines are the titles of the pull requests; the rules for what a version may change are in [docs/VERSIONING.md](docs/VERSIONING.md). +## 0.3.0 (2026-11-11) + +Release 0.3 "Shapes". A scenario is no longer one link between two nodes: it is a network of nodes, routers and routes, written out or built from the shortcuts chain, star, dumbbell and multipath, over IPv4 and IPv6, with an MTU, the don't-fragment bit and queues with their disciplines and statistics. Traffic gets the TCP of the machine (bulk transfers and request/response), the echo of a UDP stream and the replay of a trace from a CSV file or a capture, and your own program can still run in a node. A link can follow a model over time, a trace or a table of samples, and a link profile library (LTE, 5G, satellite) gives starting values with published sources. Scenario files take parameters, templates and includes, and carry their `expect` checks, so the file is the whole test. In Python a link can be changed while a run goes, with `asyncio`, data frames and a fuller builder, and every run reports the precision of the timers of the machine. The README says what 0.3 does and does not do, and [docs/ACCEPTANCE.md](https://github.com/leonkrix/netscenario/blob/main/docs/ACCEPTANCE.md) how each criterion of the release is proven, among them the fairness of two flows over a bottleneck, two paths, Reno against the formula of Mathis, and everything written for 0.2 still working. + +**Breaking.** The format of the scenario file and of the result is version 0, which a minor release may change ([docs/VERSIONING.md](https://github.com/leonkrix/netscenario/blob/main/docs/VERSIONING.md)): the files of 0.2 still read and run, results made by 0.2 are read by the reports, `replay` and the Python package, and the result has new fields. No command, option or name in Python was removed. What breaks is the Rust API of `netscenario-model` and `netscenario-core` ([#94](https://github.com/leonkrix/netscenario/pull/94), [#96](https://github.com/leonkrix/netscenario/pull/96), [#99](https://github.com/leonkrix/netscenario/pull/99), [#100](https://github.com/leonkrix/netscenario/pull/100), [#101](https://github.com/leonkrix/netscenario/pull/101), [#102](https://github.com/leonkrix/netscenario/pull/102), [#104](https://github.com/leonkrix/netscenario/pull/104), [#108](https://github.com/leonkrix/netscenario/pull/108), [#113](https://github.com/leonkrix/netscenario/pull/113), [#114](https://github.com/leonkrix/netscenario/pull/114), [#115](https://github.com/leonkrix/netscenario/pull/115)): + +- Types of the scenario are `non_exhaustive`: `Scenario`, `Link`, `Jitter`, `Event` and `Topology`, and `Problem` of the errors; so is `Provisioned` of the core and the enum `Basis` of the recovery. A new field or variant is no longer a break from now on. +- `Impairments` has the field `queue`, and `JitterDistribution` has the variants `Pareto`, `ParetoNormal` and `Table`. `Jitter` and `series::Input` are no longer `Copy`. +- `netscenario_core::check` takes two parameters and not three, and `sha256_hex` moved from `netscenario-core` to `netscenario-model`. + +### Features + +- **Breaking:** Read networks of several nodes, links and routes in the scenario format ([#94](https://github.com/leonkrix/netscenario/pull/94)) +- Add the shortcuts chain, star, dumbbell and multipath and the commands expand and show ([#95](https://github.com/leonkrix/netscenario/pull/95)) +- **Breaking:** Build networks of several nodes, routers and routes in the Kernel backend ([#96](https://github.com/leonkrix/netscenario/pull/96)) +- Account for packets link by link along a path and test the fidelity of paths ([#97](https://github.com/leonkrix/netscenario/pull/97)) +- Add the MTU of a link and account for the fragments of a packet ([#98](https://github.com/leonkrix/netscenario/pull/98)) +- **Breaking:** Add IPv6 and dont-fragment, and the MTU in the values of a shortcut ([#99](https://github.com/leonkrix/netscenario/pull/99)) +- **Breaking:** Add queues with disciplines and their statistics ([#100](https://github.com/leonkrix/netscenario/pull/100)) +- **Breaking:** Add the pareto, paretonormal and table distributions of the jitter ([#101](https://github.com/leonkrix/netscenario/pull/101)) +- **Breaking:** Add the trace-replay workload with CSV files and captures ([#102](https://github.com/leonkrix/netscenario/pull/102)) +- **Breaking:** Add the TCP agents, the stream records, the UDP echo and a limit on the segments of a link ([#104](https://github.com/leonkrix/netscenario/pull/104)) +- Add the workloads tcp-bulk and request-response to the format ([#105](https://github.com/leonkrix/netscenario/pull/105)) +- Run the TCP workloads and report them in the result ([#106](https://github.com/leonkrix/netscenario/pull/106)) +- Add the echo of a UDP stream and report its round trip ([#107](https://github.com/leonkrix/netscenario/pull/107)) +- **Breaking:** Recover TCP workloads on their goodput and name their metrics ([#108](https://github.com/leonkrix/netscenario/pull/108)) +- **Breaking:** Add models over time for links and repeating events of the timeline ([#113](https://github.com/leonkrix/netscenario/pull/113)) +- **Breaking:** Add trace-driven links, a rate that follows its steps, and allow-limited ([#114](https://github.com/leonkrix/netscenario/pull/114)) +- **Breaking:** Add parameters, templates and includes for scenario files ([#115](https://github.com/leonkrix/netscenario/pull/115)) +- Add expect checks to the scenario file ([#122](https://github.com/leonkrix/netscenario/pull/122)) +- Add the link profile library and the profiles and capabilities commands ([#123](https://github.com/leonkrix/netscenario/pull/123)) +- Change a link from test code while a run goes, add asyncio, data frames and a fuller builder ([#124](https://github.com/leonkrix/netscenario/pull/124)) +- Report the precision of the timers in every run and with doctor --timers ([#125](https://github.com/leonkrix/netscenario/pull/125)) + +### Fixes + +- Name the node address as the source in the routes of a node ([#109](https://github.com/leonkrix/netscenario/pull/109)) +- Run TCP workloads with many connections and add the acceptance experiments of TCP ([#111](https://github.com/leonkrix/netscenario/pull/111)) +- Raise the listener queue of the TCP agent and widen the delay of the seed test ([#112](https://github.com/leonkrix/netscenario/pull/112)) +- Refuse unread link traces, order faults deterministically and guard zero packet size ([#121](https://github.com/leonkrix/netscenario/pull/121)) + ## 0.2.0 (2026-11-03) Release 0.2 "Time and noise". This is the state of `0.2.0-rc.1`; the release only removes the notes that say it is a candidate. diff --git a/Cargo.lock b/Cargo.lock index ff59e35..25dab82 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -545,7 +545,7 @@ checksum = "743fb55ba31b18fb1ecef6bdc9aa2743314978ac084044301a7eee33fb99a20d" [[package]] name = "netscenario-agent" -version = "0.2.0" +version = "0.3.0" dependencies = [ "nix", "rustix", @@ -555,7 +555,7 @@ dependencies = [ [[package]] name = "netscenario-backend-kernel" -version = "0.2.0" +version = "0.3.0" dependencies = [ "netscenario-agent", "netscenario-core", @@ -568,7 +568,7 @@ dependencies = [ [[package]] name = "netscenario-cli" -version = "0.2.0" +version = "0.3.0" dependencies = [ "netscenario-backend-kernel", "netscenario-core", @@ -579,7 +579,7 @@ dependencies = [ [[package]] name = "netscenario-core" -version = "0.2.0" +version = "0.3.0" dependencies = [ "insta", "netscenario-agent", @@ -591,7 +591,7 @@ dependencies = [ [[package]] name = "netscenario-model" -version = "0.2.0" +version = "0.3.0" dependencies = [ "granit-parser", "insta", @@ -606,7 +606,7 @@ dependencies = [ [[package]] name = "netscenario-py" -version = "0.2.0" +version = "0.3.0" dependencies = [ "netscenario-backend-kernel", "netscenario-core", diff --git a/Cargo.toml b/Cargo.toml index 0dcccbd..2cf217e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -5,7 +5,7 @@ members = ["crates/*"] exclude = ["spikes", "fuzz"] [workspace.package] -version = "0.2.0" +version = "0.3.0" edition = "2024" # The lowest supported Rust version (D-020, which raised it from 1.85 of D-014). It is what serde-saphyr, the # YAML parser of the scenario files, needs. @@ -17,11 +17,11 @@ keywords = ["network", "emulation", "netem", "testing", "scenario"] categories = ["development-tools::testing", "network-programming", "simulation"] [workspace.dependencies] -netscenario-model = { path = "crates/netscenario-model", version = "0.2.0" } -netscenario-core = { path = "crates/netscenario-core", version = "0.2.0" } -netscenario-backend-kernel = { path = "crates/netscenario-backend-kernel", version = "0.2.0" } -netscenario-agent = { path = "crates/netscenario-agent", version = "0.2.0" } -netscenario-cli = { path = "crates/netscenario-cli", version = "0.2.0" } +netscenario-model = { path = "crates/netscenario-model", version = "0.3.0" } +netscenario-core = { path = "crates/netscenario-core", version = "0.3.0" } +netscenario-backend-kernel = { path = "crates/netscenario-backend-kernel", version = "0.3.0" } +netscenario-agent = { path = "crates/netscenario-agent", version = "0.3.0" } +netscenario-cli = { path = "crates/netscenario-cli", version = "0.3.0" } # Third-party dependencies are listed once here; a crate says `name.workspace = true` serde = { version = "1", features = ["derive"] } diff --git a/docs/ACCEPTANCE.md b/docs/ACCEPTANCE.md index ba2e6aa..935b98d 100644 --- a/docs/ACCEPTANCE.md +++ b/docs/ACCEPTANCE.md @@ -52,6 +52,11 @@ Every release of the [ledger](../FEATURES.md) has criteria that all have to hold | TCP follows what is known of it | Reno against the formula of Mathis at two points (the constant is 1.0 to 1.5, measured 1.17 to 1.32), and CoDel and FQ-CoDel keep the standing queue near their target where a FIFO of the same size keeps most of a second; each has a canary on the wrong side | [`test_acceptance_tcp_models.py`](../python/netscenario/tests/test_acceptance_tcp_models.py), [`tcp.rs`](../crates/netscenario-backend-kernel/tests/tcp.rs) | | The profile library has one test per profile | Every profile of library version 1 (14) runs on a link and the delays it has on the wire are the published ones; a test fails if a profile is added to the library and not to the table, and a canary shows the meter can fail. The sources of the values are in [PROFILES.md](PROFILES.md) | [`profiles.rs`](../crates/netscenario-backend-kernel/tests/profiles.rs) | | The documentation is complete for everything in 0.3, the ledger and the coverage matrix are up to date, and each check mark has a test | Every feature with the release 0.3 in the ledger is `done` with a link to what proves it, a test fails for a row that is not, and the matrix of coverage agrees with the code and links every faithful mark to a test. The guide at https://leonkrix.github.io/netscenario/ is checked page by page: its scenarios validate, the marked ones and the Python run | [`test_ledger.py`](../python/netscenario/tests/test_ledger.py), [`coverage.rs`](../crates/netscenario-backend-kernel/tests/coverage.rs), [`test_book.py`](../python/netscenario/tests/test_book.py) | +| Everything written for 0.2 still works | The scenario files of the tag `v0.2.0` (15 valid ones) pass `validate`; four results and a set of five runs made by the wheel `netscenario==0.2.0` from PyPI are read by the reports (Markdown, JUnit, HTML), by `replay` and by Python (`Result.from_json`, `RunSet.from_json`); the same seed loses the same packets in both builds (67 on `lte-like`, 51 on `capture-a-link`). A run of a program under test was not repeated, because it needs a server that is not part of the repository | by hand with the PyPI wheel, not a test of the repository | +| The new parsers of input that is not trusted are fuzzed | 14 targets run every week and by hand; the run on `main` before the release found nothing | [fuzz/](../fuzz/), [`fuzz.yml`](../.github/workflows/fuzz.yml) | +| The acceptance of 0.2 and of TCP is stable | `just stability 100` (the test of the confidence interval) and `just stability-tcp 10` (the TCP acceptance and the models) ran as a service on the development machine, see below | [`stability.yml`](../.github/workflows/stability.yml), [`test_acceptance_tcp.py`](../python/netscenario/tests/test_acceptance_tcp.py) | + +**Stability before the release** (development machine, Debian 13, recorded on 2026-11-11): the 100 rounds of the test of the confidence interval had **1 round that failed, and that one was disturbed**: the temporary directory of the running test was removed by hand (`flow-0.records: No such file or directory`), which is no fault of the test. One more round was run afterwards and passed, so 100 undisturbed rounds passed. The 10 rounds of the TCP acceptance and the models took about 8.5 minutes each: **0 of 10 rounds failed**. ### What this does not cover diff --git a/python/pytest-netscenario/pyproject.toml b/python/pytest-netscenario/pyproject.toml index 7c7cd1a..184151d 100644 --- a/python/pytest-netscenario/pyproject.toml +++ b/python/pytest-netscenario/pyproject.toml @@ -4,14 +4,14 @@ build-backend = "hatchling.build" [project] name = "pytest-netscenario" -version = "0.2.0" +version = "0.3.0" description = "pytest plugin for netscenario: fixtures and markers to run network scenarios in tests" requires-python = ">=3.11" license = "MIT OR Apache-2.0" license-files = ["LICENSE-*"] readme = "README.md" # Released together with the package, so the exact version (python/release/version.py keeps it) -dependencies = ["netscenario==0.2.0", "pytest>=8"] +dependencies = ["netscenario==0.3.0", "pytest>=8"] classifiers = [ "Development Status :: 3 - Alpha", "Framework :: Pytest", diff --git a/uv.lock b/uv.lock index 9ac7f10..b63435d 100644 --- a/uv.lock +++ b/uv.lock @@ -6,10 +6,10 @@ resolution-markers = [ "python_full_version >= '3.14' and sys_platform == 'emscripten'", "python_full_version >= '3.14' and sys_platform != 'emscripten' and sys_platform != 'win32'", "python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform == 'win32'", - "python_full_version < '3.12' and sys_platform == 'win32'", "python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform == 'emscripten'", - "python_full_version < '3.12' and sys_platform == 'emscripten'", "python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform != 'emscripten' and sys_platform != 'win32'", + "python_full_version < '3.12' and sys_platform == 'win32'", + "python_full_version < '3.12' and sys_platform == 'emscripten'", "python_full_version < '3.12' and sys_platform != 'emscripten' and sys_platform != 'win32'", ] @@ -417,7 +417,7 @@ wheels = [ [[package]] name = "pytest-netscenario" -version = "0.2.0" +version = "0.3.0" source = { editable = "python/pytest-netscenario" } dependencies = [ { name = "netscenario" }, From 8fba66c08d1e5e2fd2f81016352481aeba65e07b Mon Sep 17 00:00:00 2001 From: Leon Krix Date: Wed, 11 Nov 2026 22:45:34 +0100 Subject: [PATCH 2/2] docs: link the TCP row of the coverage matrix to its tests --- docs/COVERAGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/COVERAGE.md b/docs/COVERAGE.md index e193769..03c6253 100644 --- a/docs/COVERAGE.md +++ b/docs/COVERAGE.md @@ -152,7 +152,7 @@ One-way delay is exact because all nodes share one machine and one clock. For th | Feature | Kernel | Engine | Proxy | | --- | --- | --- | --- | | UDP and everything on it (QUIC, RTP, custom protocols) | ✔ 0.1 ([test](../crates/netscenario-backend-kernel/tests/fidelity.rs): UDP streams of any packet size) | ✔ 0.4 | ✔ 0.5 | -| TCP behaviour under loss and delay (congestion control) | ✔ 0.3 | ✔ 0.4 | ✘ | +| TCP behaviour under loss and delay (congestion control) | ✔ 0.3 ([test](../python/netscenario/tests/test_acceptance_tcp_models.py): Reno follows the formula of Mathis at two points, CoDel and FQ-CoDel keep the queue near their target where a FIFO does not; [fairness](../python/netscenario/tests/test_acceptance_tcp.py)) | ✔ 0.4 | ✘ | | ICMP | ✔ 0.1 ([test](../crates/netscenario-backend-kernel/tests/provision.rs): `a_ping_takes_the_round_trip_of_both_directions`) | ✔ 0.4 | ✘ | ## Reproducibility