Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
12 changes: 6 additions & 6 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

12 changes: 6 additions & 6 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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"] }
Expand Down
5 changes: 5 additions & 0 deletions docs/ACCEPTANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/COVERAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions python/pytest-netscenario/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
6 changes: 3 additions & 3 deletions uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.