From a95cbacd597cdd6a55581c9a89710ff55c526e96 Mon Sep 17 00:00:00 2001 From: Josef Schlehofer Date: Tue, 10 Nov 2026 11:15:47 +0100 Subject: [PATCH] docs: shorten the README The README is now tables and callouts instead of long paragraphs. Only the steps for running the parity test by hand and for regenerating the golden data are collapsed. How to release and the crates.io setup move to RELEASING.md unchanged. The ChaCha20 row of the cipher table is gone. Its numbers no longer match a newer measurement and have to be taken again on the board. Cargo.toml and tls.rs no longer say ring fails to build outside x86 and ARM. Stock OpenWrt ships mbedTLS, so libopenssl is a dependency of the package. --- Cargo.toml | 10 +- README.md | 464 ++++++++++++++++++------------------------------ RELEASING.md | 90 +++++++++- src/http/tls.rs | 10 +- 4 files changed, 271 insertions(+), 303 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index b7261d7..0da9ff5 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -44,16 +44,18 @@ path = "src/main.rs" [features] default = ["rustls-tls"] # rustls with the ring crypto provider. Statically linked, no system TLS -# library needed, but ring builds only for x86, x86_64, aarch64, arm and wasm32. +# library needed. ring has assembly only for x86, x86_64, aarch64 and arm and +# runs portable C elsewhere, which is slow on a core without crypto instructions. rustls-tls = [ "dep:hyper-rustls", "dep:rustls", "dep:rustls-native-certs", "dep:rustls-pki-types", ] -# Link against the system OpenSSL instead. Required on targets ring does not -# support, such as the 32-bit PowerPC e500v2 in Turris 1.x routers. This is what -# OpenWrt packaging wants: it reuses the libopenssl already in the image. +# Link against the system OpenSSL instead. Faster where ring has no assembly, +# such as the 32-bit PowerPC e500v2 in Turris 1.x routers. This is what OpenWrt +# packaging uses: it depends on the libopenssl package instead of carrying a +# TLS library of its own. native-tls = ["dep:hyper-tls", "dep:native-tls", "dep:tokio-native-tls"] [dependencies] diff --git a/README.md b/README.md index 81e3f19..2f7541d 100644 --- a/README.md +++ b/README.md @@ -1,108 +1,33 @@ # librespeed-cli (Rust) -A command line interface for [LibreSpeed](https://github.com/librespeed/speedtest), written in Rust. - -LibreSpeed ships two backend implementations — one in Go -([speedtest-go](https://github.com/librespeed/speedtest-go)) and one in Rust -([speedtest-rust](https://github.com/librespeed/speedtest-rust)) — but the CLI -existed only in Go. This is a port of -[librespeed/speedtest-cli](https://github.com/librespeed/speedtest-cli) to Rust, -addressing [issue #105](https://github.com/librespeed/speedtest-cli/issues/105). - -It speaks the same protocol as the Go CLI and works against any LibreSpeed -backend, Go or Rust. - -## Status - -Feature-complete with the Go CLI: every command line flag is implemented, -including telemetry/`--share`, JSON and CSV reports, ICMP and HTTP ping, -IPv4/IPv6 forcing, source-address, interface and firewall-mark socket binding, -custom CA bundles, and the server list filters. - -Agreement with the Go client is a test rather than a claim. `tests/parity` -runs both binaries against the same in-process backend and compares their -output, their error output and their exit status. For every case it declares -either that the two agree or exactly which lines differ and which entry of the -list below accounts for them, so an undocumented difference fails the run and -so does one that quietly went away. CI builds the Go client from the commit -`tests/parity/cases.rs` names and runs the comparison against it. - -What it shows, once the measured numbers are set aside -- those differ between -any two runs: `--list`, `--csv-header`, `--simple`, `--csv`, `--json`, -`--json-stream` and the `--debug` lines agree, and so do the usage errors, the -error lines and the exit status of a failed run. The text columns are the -exception, because what a server says about itself is rewritten on its way -into a report; the first entry below says how. In `--help` every option the Go -client has reads the same apart from a typo corrected in `--telemetry-json`, -`--http2` is an option it does not have, and `--version` names this repository -instead of the Go one. - -## Building +[![CI](https://github.com/librespeed/speedtest-cli-rust/actions/workflows/ci.yml/badge.svg)](https://github.com/librespeed/speedtest-cli-rust/actions/workflows/ci.yml) +[![crates.io](https://img.shields.io/crates/v/librespeed-cli.svg)](https://crates.io/crates/librespeed-cli) +[![License](https://img.shields.io/crates/l/librespeed-cli.svg)](LICENSE) -```sh -cargo build --release -``` - -The binary lands in `target/release/librespeed-cli`. Set `SOURCE_DATE_EPOCH` for -a reproducible build date in `--version`. - -### TLS backends - -| Feature | Crypto | System dependency | Architectures | -| --- | --- | --- | --- | -| `rustls-tls` (default) | rustls + ring | none, statically linked | anything | -| `native-tls` | system OpenSSL | libopenssl | anything OpenSSL builds for | - -`ring` builds everywhere, falling back to portable C where it has no -hand-written assembly, which is everything outside x86, x86_64, aarch64 and -arm. On a core with no crypto instructions that costs throughput, so the -OpenSSL backend is the better choice there. Measured on the e500v2 in a -Turris 1.x, 8 KiB buffers: - -| | ring | OpenSSL | -| --- | --- | --- | -| ChaCha20-Poly1305 | 48.6 MB/s | 46.9 MB/s | -| AES-128-GCM | 8.5 MB/s | 18.8 MB/s | +Command line client for [LibreSpeed](https://github.com/librespeed/speedtest), +a Rust port of the Go [librespeed-cli](https://github.com/librespeed/speedtest-cli) +([issue #105](https://github.com/librespeed/speedtest-cli/issues/105)). -ChaCha20 in portable C already matches the assembly; AES does not, and AES is -what servers pick. An HTTPS run against a backend negotiating AES-256-GCM -measured 138 Mbps with OpenSSL against 37 Mbps with rustls. Build the OpenSSL -backend for such targets: +- Same protocol, options and output formats as the Go client. +- Works against any LibreSpeed backend, [Go](https://github.com/librespeed/speedtest-go) + or [Rust](https://github.com/librespeed/speedtest-rust). +- Runs where Go does not, such as the 32-bit PowerPC in Turris 1.x routers. -```sh -cargo build --release --no-default-features --features native-tls -``` - -### OpenWrt and Turris - -The Go CLI cannot run on 32-bit PowerPC at all — Go's toolchain only targets -`ppc64` and `ppc64le`, which is why LibreSpeed's CLI is packaged for Turris -Omnia and MOX but not for Turris 1.x. Rust does reach that hardware through the -Tier 3 `powerpc-unknown-linux-muslspe` target that the OpenWrt build system -supports, so this port can go where the Go one cannot. +## Install -Build it against the OpenWrt SDK with the OpenSSL backend, for the throughput -reason above and because it links against the libopenssl already in the image -rather than carrying its own: - -```sh -cargo build --release --no-default-features --features native-tls \ - --target powerpc-unknown-linux-muslspe -``` +| Where | How | +| --- | --- | +| OpenWrt | `apk add librespeed-cli-rust`, on 24.10 `opkg install librespeed-cli-rust` | +| Cargo | `cargo install --locked librespeed-cli` | +| Linux binaries | [Releases](https://github.com/librespeed/speedtest-cli-rust/releases) for x86_64, aarch64, armv7 and arm (musl) | +| From source | `cargo build --release`, the binary is `target/release/librespeed-cli` | -Being a Tier 3 target, `powerpc-unknown-linux-muslspe` has no prebuilt `std`, so -it needs a nightly toolchain with `-Z build-std` — which is what OpenWrt's Rust -packaging already arranges. Point the `openssl` crate at the SDK's OpenSSL via -`OPENSSL_DIR`, or let `pkg-config` find it through the SDK environment. +Set `SOURCE_DATE_EPOCH` for a reproducible build date in `--version`. It +fixes only the date and does not make the binary bit-for-bit reproducible, see +[RELEASING.md](RELEASING.md#how-to-release). ## Usage -``` -librespeed-cli [OPTIONS] -``` - -Run `librespeed-cli --help` for the full list. The common ones: - ```sh # Test against the automatically selected fastest server librespeed-cli @@ -126,83 +51,133 @@ librespeed-cli --interface eth1 librespeed-cli --fwmark 42 # Linux only ``` +> [!TIP] +> `librespeed-cli --help` lists every option. + +## TLS backends + +| Feature | Crypto | Links against | Architectures | +| --- | --- | --- | --- | +| `rustls-tls` (default) | rustls + ring | nothing, static | anything, with assembly on x86, x86_64, aarch64 and arm | +| `native-tls` | system OpenSSL | libopenssl | anything OpenSSL builds for | + +```sh +cargo build --release --no-default-features --features native-tls +``` + +> [!IMPORTANT] +> `ring` has assembly only for x86, x86_64, aarch64 and arm. Elsewhere it runs +> portable C. On a slow core without crypto instructions that can cost enough +> throughput for a speed test to measure the CPU instead of the link, and the +> OpenSSL backend is the better choice there. +> +> One measurement, on the e500v2 of a Turris 1.x: an HTTPS run against a +> backend negotiating AES-256-GCM reached 138 Mbps with OpenSSL and 37 Mbps +> with rustls. AES-128-GCM alone, with 8 KiB buffers, does 18.8 MB/s with +> OpenSSL and 8.5 MB/s with ring. Other CPUs will give other numbers. + +## OpenWrt and Turris + +The Go client cannot run on 32-bit PowerPC, because Go targets only `ppc64` and +`ppc64le`. Rust reaches that hardware through the Tier 3 target +`powerpc-unknown-linux-muslspe`, so this port also covers Turris 1.x. + +The OpenWrt package `librespeed-cli-rust` builds the `native-tls` backend and +depends on `libopenssl`. + +To build for Turris 1.x by hand: + +```sh +cargo build --release --no-default-features --features native-tls \ + --target powerpc-unknown-linux-muslspe +``` + +A Tier 3 target has no prebuilt `std`, so this needs a nightly toolchain with +`-Z build-std`, which OpenWrt's Rust packaging arranges. Point the `openssl` +crate at the SDK's OpenSSL with `OPENSSL_DIR`, or let `pkg-config` find it +through the SDK environment. + +## Parity with the Go client + +Every option of the Go client is implemented, including telemetry and `--share`, +JSON and CSV reports, ICMP and HTTP ping, IPv4 and IPv6 forcing, source address, +interface and firewall mark binding, custom CA bundles and the server list +filters. + +> [!NOTE] +> Agreement is a test, not a claim. `tests/parity` runs both binaries against +> the same backend and compares their output, error output and exit status. +> A difference that is not in the list below fails CI, and so does a listed one +> that went away. + +| Compared | Result | +| --- | --- | +| Reports and errors | Same: `--list`, `--csv-header`, `--simple`, `--csv`, `--json`, `--json-stream`, the `--debug` lines, usage errors, error lines and the exit status of a failed run | +| `--help` | Every shared option reads the same apart from a typo corrected in `--telemetry-json` | +| Only here | `--http2`, and `--version` names this repository instead of the Go one | + ## Differences from the Go implementation -The protocol, the flags and the output formats match. These behaviours are -deliberately different: - -- **Everything a server says is sanitized.** Server names, sponsor strings, - addresses and the backend's getIP answer are attacker-influenced text. The - control characters (C0, DEL, C1), the line and paragraph separators, every - Unicode format character — bidi overrides, zero-width joiners, the soft - hyphen, the Arabic letter mark, the byte order mark — and the invisible tag - block are dropped before any of it is printed, in terminal output, in CSV and - in JSON alike. Spacing characters such as no-break space are kept: they - render, and dropping them would run words together and misreport a name. The - Go client cleans C0, DEL and C1 from its terminal output only, so its CSV and - JSON carry escape sequences and bidi overrides straight through. A text - column here is therefore a transformation of what the server sent rather than - an escaping of it: the characters are removed, not encoded, and in CSV a - field that would start a formula gains a leading apostrophe as well. Neither - is reversible, which is the point -- nothing downstream can be steered by - what a server called itself. -- **CSV formulas are defused.** A field starting with `=`, `+`, `-` or `@` is - prefixed with a single quote, because spreadsheets strip the CSV quoting and - then evaluate what is left. -- **CSV quoting follows the csv crate.** Go also quotes a field that starts - with a space or is exactly `\.`; here only the delimiter, a quote or a line - break causes quoting. -- **Response sizes are capped.** A server list and a getIP answer are read to - 8 MiB and a telemetry reply to 64 KiB, rather than to whatever the peer - decides to send, and the check that a backend is up reads no more than 8 KiB - of its answer. The cap bounds memory and not time: a peer that stays under it - while sending slowly is left to the request timeout, and `--timeout 0` leaves - no time bound at all. -- **A redirect may not leave https for http.** A server reached over https - that answers with a `Location` on http is an error: the request was made - over TLS deliberately, and following the downgrade would put the rest of - the exchange on the wire in clear. Go follows it, leaving out only the - Referer. A redirect that stays on http, and one that stays on https, is - followed as it is in Go. +The protocol, the options and the output formats match. These behaviours are +deliberately different. + +### Security + +- **Everything a server says is sanitized.** Server names, sponsors, addresses + and the getIP answer lose their control characters, Unicode format characters + such as bidi overrides and zero-width joiners, and the invisible tag block, + in terminal, CSV and JSON output alike. The characters are removed, not + escaped. Go cleans only C0, DEL and C1, and only in terminal output. +- **CSV formulas are defused.** A field starting with `=`, `+`, `-` or `@` gets + a leading single quote, because spreadsheets evaluate what is left after + unquoting. +- **Response sizes are capped.** 8 MiB for a server list or a getIP answer, + 64 KiB for a telemetry reply and 8 KiB for the check that a backend is up. + The cap bounds memory, not time, and `--timeout 0` leaves no time bound. +- **A redirect may not leave https for http.** It is an error here. Go follows + it and only leaves out the Referer. - **A request body is not sent on to another origin.** A 307 or 308 that would - send the telemetry POST to another scheme, host or port is refused, because - the POST carries the measurement, the client's address and its ISP; Go sends - the body on. A redirected request also carries no Referer. + move the telemetry POST to another scheme, host or port is refused, because + the POST carries the measurement, the client's address and its ISP. Go sends + it on. A redirected request also carries no Referer. - **A telemetry reply other than 2xx fails the upload.** The error names the - HTTP status, and no share link is printed. Go does not check the status: it - takes a share ID from any body with exactly one space in it, so a 500 reply - can still yield a share link. -- **HTTP/1.1 by default, HTTP/2 behind `--http2`.** HTTP/2 carries every stream - over one TCP connection, so `--concurrent` would stop meaning concurrent - connections — and multiple connections is the standard way a speed test - saturates a link. Go's client negotiates h2 whenever a server offers it. - `--http2` enables it here too, with the flow-control windows raised to what - Go's transport uses (4 MiB per stream, 1 GiB per connection); the protocol - default of 64 KiB caps a stream at window/RTT, about 105 Mbps at 5 ms. -- **Scheme-less server URLs with a port work.** `example.com/backend` becomes - `http://example.com/backend` in both clients, but Go's URL parser takes - `example.com:8080/backend` for a URL whose scheme is `example.com`, and - `127.0.0.1:8080/` makes it reject the whole list. Here both become `http://` - URLs. -- **`--interface` works on macOS** via `IP_BOUND_IF`; the Go version supports - interface binding on Linux only. `--fwmark` remains Linux-only (`SO_MARK`). -- **Numbers the Go client cannot act on are refused.** It accepts any int64 and - then panics on `--upload-size -1` or wraps a `--duration` past the - `time.Duration` range. Here a negative value, a duration or timeout past that - range, and a count, size or mark past 32 bits are refused as out of range; - Go instead gives a negative `--concurrent` its own message and ignores a - negative `--fwmark`. A negative `--server` or `--exclude` is still taken, so - `--server -1` tests every server as it does in Go. Zero `--duration`, - `--chunks` and `--upload-size` run as they do in Go. + HTTP status and no share link is printed. Go takes a share ID from any body + with exactly one space in it, so a 500 reply can still yield a link. - **TLS verification is stricter.** rustls rejects a self-signed certificate - presented as both the leaf and its own trust anchor even when passed via - `--ca-cert`. A normal private CA works; use `--skip-cert-verify` for the - degenerate case. -- **The process exits rather than returning from `main`.** Dropping the tokio - runtime joins its worker threads, and on 32-bit PowerPC musl (Turris 1.x) - that never completed: every successful run hung after printing its output. - `process::exit(0)` at the end of `main` is a workaround, still under - investigation; all output is flushed as it is written, so nothing is lost. + that is both the leaf and its own trust anchor, even with `--ca-cert`. + A normal private CA works, and `--skip-cert-verify` covers the other case. + +### Behaviour + +- **HTTP/1.1 by default, HTTP/2 behind `--http2`.** HTTP/2 carries every stream + over one TCP connection, so `--concurrent` would stop meaning connections. + Go negotiates h2 whenever a server offers it. With `--http2` the flow-control + windows are raised to Go's values, 4 MiB per stream and 1 GiB per connection. +- **Scheme-less server URLs with a port work.** `example.com:8080/backend` + becomes an `http://` URL. Go takes `example.com` for the scheme, and + `127.0.0.1:8080/` makes it reject the whole list. +- **`--interface` works on macOS** through `IP_BOUND_IF`. Go binds interfaces + on Linux only. `--fwmark` stays Linux-only (`SO_MARK`). +- **Numbers the Go client cannot act on are refused.** A negative value, + a duration or timeout past the `time.Duration` range, and a count, size or + mark past 32 bits are out of range. Go panics on `--upload-size -1`. + A negative `--server` or `--exclude` is still taken, so `--server -1` tests + every server as it does in Go. +- **CSV quoting follows the csv crate.** Only the delimiter, a quote or a line + break causes quoting. Go also quotes a field that starts with a space or is + exactly `\.`. +- **Error causes use this client's libraries' words.** The prefixes match Go, + such as `Error when fetching server list:`. The cause after them, a refused + connection or a JSON syntax error, reads differently. +- **A server URL's scheme keeps its case.** Go lowercases `HTTP://` when it + parses the list. +- **The process exits rather than returning from `main`.** On 32-bit PowerPC + musl, dropping the tokio runtime never finished and every run hung after its + output. `main` ends with `process::exit(0)` as a workaround. Output is flushed + as it is written, so nothing is lost. + +### Command line + - **Go's command line quirks are not copied.** The command line is parsed by clap, so: - `-json` is not `--json`: long options take two dashes. @@ -210,59 +185,39 @@ deliberately different: - An argument that is not an option is refused. Go ignores it, and every option after it. - An option other than `--server` and `--exclude` given twice is refused, - and `--server 1,2` is not split into two servers; Go keeps the last value + and `--server 1,2` is not split into two servers. Go keeps the last value and splits the list. - A boolean option takes no value, so `--json=false` is refused. - `--csv-delimiter` must be one ASCII character other than `"`. Go uses the - first character of a longer value, and with `"` prints no header and no - rows. + first character of a longer value. - `--help` is answered as soon as it is seen, even if an unknown option - follows; Go reports the unknown option. - - Rarer usage errors read differently: a repeated option or `--ipv4 -4`, + follows. Go reports the unknown option. + - Rarer usage errors read differently: a repeated option, `--ipv4 -4`, `---list`, `--json-stream` with `--json` or `--csv`, and `--server` with - `--exclude`, which Go reports as "incompatible options" and "either - --exclude or --server can be used" (`--specific` for a local list). + `--exclude`. - A malformed or out-of-range `--server` or `--exclude` value ends in - `parse error` or `value out of range`, as any other number does; Go puts - strconv's message there, such as `strconv.ParseInt: parsing "x": invalid - syntax`. -- **Error causes use this client's libraries' words.** The prefixes match Go - (`Error when fetching server list:`, `Terminated due to error:` and the - rest), but a cause such as a refused connection or a JSON syntax error reads - differently after them. -- **A server URL's scheme keeps its case.** Go lowercases `HTTP://` when it - parses the list; `--list` and the reports show it here as the list gave it. + `parse error` or `value out of range`. Go prints strconv's message. ## Testing ```sh -cargo test # unit + end-to-end tests +cargo test cargo clippy --all-targets cargo fmt --check ``` -`tests/integration.rs` starts an in-process LibreSpeed backend and drives the -built binary against it, covering the whole flow — server list, ping, download, -upload, telemetry and every output mode — with no network access, including the -Go client's error messages and what a backend full of hostile text does not get -to print. The unit tests cover the jitter estimator, Go-compatible path joining, -rounding, timestamps, CSV and JSON rendering, server list filtering and URL -scheme handling. - -`tests/golden.rs` checks the report rendering against data Go itself wrote. -`tools/golden/main.go` runs `encoding/json`, `strconv` and `time` — the -packages the Go client renders its reports with — over a corpus of floats, -timestamps and whole documents, and the test feeds the same inputs to this -client. Only the recorded data is needed, so it runs everywhere; regenerating -it needs Go: +| Suite | What it covers | +| --- | --- | +| `tests/integration.rs` | The whole flow against an in-process backend, with no network: server list, ping, download, upload, telemetry and every output mode | +| `tests/golden.rs` | Report rendering against data the Go standard library wrote | +| `tests/parity` | The differential test against the Go client | +| unit tests | Jitter, path joining, rounding, timestamps, CSV and JSON rendering, server list filters and URL schemes | -```sh -go run tools/golden/main.go tests/data -``` +
+Running the parity test by hand -`tests/parity` is the differential test the Status section describes. Without -`LIBRESPEED_GO_BIN` it skips the comparison and prints why, so a plain -`cargo test` still passes; CI sets it, and by hand it is: +Without `LIBRESPEED_GO_BIN` the comparison is skipped and says why, so a plain +`cargo test` passes. CI sets it. ```sh # GO_COMMIT is the commit tests/parity/cases.rs names. @@ -272,103 +227,28 @@ git -C go-client checkout "$GO_COMMIT" LIBRESPEED_GO_BIN=$PWD/go-client/librespeed-go cargo test --test parity ``` -## Releasing +
-[RELEASING.md](RELEASING.md) says when a release goes out, when one goes to -OpenWrt, and how dependencies are kept up to date. - -### How to release +
+Regenerating the golden data -A release is a tag. Bump `version` in `Cargo.toml`, run `cargo update --workspace` -so that `Cargo.lock` follows, commit both, then: +Only the recorded data is needed to run the test. Regenerating it needs Go: ```sh -git tag -a v1.2.1 -m "librespeed-cli 1.2.1" -git push origin v1.2.1 +go run tools/golden/main.go tests/data ``` -The tag starts [release.yml](.github/workflows/release.yml), which runs in -one chain and stops at the first step that fails: - -1. **Resolve the commit** turns the tag into a commit, once. Every step - after it is handed that commit instead of resolving the tag again, so a - tag that moves mid-release cannot split the run across two of them. -2. **Checks** run [ci.yml](.github/workflows/ci.yml) against that commit: - tests on three platforms, both TLS backends, the minimum supported Rust - version, lint, the fuzz targets, the differential test against the Go - client and `cargo package`, and a tag with a known advisory in its - `Cargo.lock` stops too. Nothing is built or published until they pass. -3. **Package the crate** verifies the tag against `version` in `Cargo.toml` - and builds the `.crate` once, recording its SHA-256. A tag that disagrees - stops the run here, before a release exists to leave behind. -4. **Build** cross-builds the musl binaries. -5. **Publish release** attaches the tarballs and `SHA256SUMS` to a GitHub - release. -6. **Publish to crates.io** checks the tag again against the commit it is - about to upload, rebuilds the crate and refuses to publish unless it comes - out byte for byte the one step 3 validated. `cargo` cannot upload a - `.crate` it did not just build, so this comparison is what ties the two - together. A dry run goes first, so a crate that cannot be published is - distinguishable from an upload that failed. Only then does the job ask - crates.io for a publishing token, through Trusted Publishing. - -Running the workflow by hand rebuilds the binaries for a tag that is already -out; that path never publishes. - -The tag is checked again before the GitHub release is cut and once more -immediately before the upload, because a run takes long enough for a tag to -move. That is detection, not a lock: a tag can still move a moment after a -check returns. Protecting `v*` tags against force-pushes and deletion with a -repository ruleset is what prevents it, and these checks catch what slips past. - -Releases are built with the compiler named in `RELEASE_TOOLCHAIN`, with -`cross` pinned to a version, and with every action pinned to a commit. CI -keeps using whatever `stable` is that day: the two answer different -questions, CI that the code has not fallen behind the compiler, a release -what it was actually built with. Moving a release to a newer compiler is -therefore a commit, not a Tuesday. - -That makes a release repeatable in the ways this repository controls: the -same source, the same dependency versions from `Cargo.lock`, the same -compiler, the same `cross` and the same actions. It does not make the -binaries bit-for-bit reproducible — the `cross` container images and the -runner environment are outside it. `SOURCE_DATE_EPOCH` only fixes the build -date `--version` prints. - -### crates.io credentials - -There are none. The publish job authenticates with -[Trusted Publishing](https://crates.io/docs/trusted-publishing): it asks -GitHub for an OIDC token naming the repository and the workflow file, and -`rust-lang/crates-io-auth-action` trades that with crates.io for a registry -token that lasts 30 minutes and is revoked when the job ends. That is what -`id-token: write` on the job is for; it grants nothing in this repository. - -The crate side is one-time setup, and only an owner of the crate can do it, -under the crate's Settings → Trusted Publishing → Add, publisher GitHub: - -| Field | Value | -| --- | --- | -| Repository owner | `librespeed` | -| Repository name | `speedtest-cli-rust` | -| Workflow filename | `release.yml` | -| Environment name | leave empty | - -The environment field is optional, and left empty it mints a token for any -run of that workflow on this repository. Naming one would narrow that -further, but only an environment with protection rules is worth the second -place to keep in step, and configuring those needs repository admin. - -Trusted Publishing cannot be configured for a crate that does not exist yet, -so the first version went out with an API token from -, stored as the repository secret -`CARGO_REGISTRY_TOKEN`. Nothing reads that secret any more and it can be -deleted. +
+ +## Releasing + +[RELEASING.md](RELEASING.md) says when a release goes out, when one goes to +OpenWrt, how dependencies are kept up to date and how a tag becomes a release. ## License GNU Lesser General Public License v3.0, the same as the Go implementation. See [LICENSE](LICENSE). -- LibreSpeed — Copyright (C) 2016-2020 Federico Dossena -- librespeed-cli — Copyright (C) 2020 Maddie Zhan +- LibreSpeed, Copyright (C) 2016-2020 Federico Dossena +- librespeed-cli, Copyright (C) 2020 Maddie Zhan diff --git a/RELEASING.md b/RELEASING.md index 186340e..d996f65 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,7 +1,5 @@ # Releasing -How to cut a release is in the [README](README.md#how-to-release). - ## When to release A release publishes to crates.io and cannot be taken back, so it stays a tag @@ -76,3 +74,91 @@ in OpenWrt's oldest stable branch, or a fix can no longer reach it. Keep merging the monthly updates. Without activity GitHub disables the scheduled Audit run after 60 days, and a Dependabot pull request left untouched for 90 days pauses Dependabot, security updates included. + +## How to release + +A release is a tag. Bump `version` in `Cargo.toml`, run `cargo update --workspace` +so that `Cargo.lock` follows, commit both, then: + +```sh +git tag -a v1.2.1 -m "librespeed-cli 1.2.1" +git push origin v1.2.1 +``` + +The tag starts [release.yml](.github/workflows/release.yml), which runs in +one chain and stops at the first step that fails: + +1. **Resolve the commit** turns the tag into a commit, once. Every step + after it is handed that commit instead of resolving the tag again, so a + tag that moves mid-release cannot split the run across two of them. +2. **Checks** run [ci.yml](.github/workflows/ci.yml) against that commit: + tests on three platforms, both TLS backends, the minimum supported Rust + version, lint, the fuzz targets, the differential test against the Go + client and `cargo package`, and a tag with a known advisory in its + `Cargo.lock` stops too. Nothing is built or published until they pass. +3. **Package the crate** verifies the tag against `version` in `Cargo.toml` + and builds the `.crate` once, recording its SHA-256. A tag that disagrees + stops the run here, before a release exists to leave behind. +4. **Build** cross-builds the musl binaries. +5. **Publish release** attaches the tarballs and `SHA256SUMS` to a GitHub + release. +6. **Publish to crates.io** checks the tag again against the commit it is + about to upload, rebuilds the crate and refuses to publish unless it comes + out byte for byte the one step 3 validated. `cargo` cannot upload a + `.crate` it did not just build, so this comparison is what ties the two + together. A dry run goes first, so a crate that cannot be published is + distinguishable from an upload that failed. Only then does the job ask + crates.io for a publishing token, through Trusted Publishing. + +Running the workflow by hand rebuilds the binaries for a tag that is already +out; that path never publishes. + +The tag is checked again before the GitHub release is cut and once more +immediately before the upload, because a run takes long enough for a tag to +move. That is detection, not a lock: a tag can still move a moment after a +check returns. Protecting `v*` tags against force-pushes and deletion with a +repository ruleset is what prevents it, and these checks catch what slips past. + +Releases are built with the compiler named in `RELEASE_TOOLCHAIN`, with +`cross` pinned to a version, and with every action pinned to a commit. CI +keeps using whatever `stable` is that day: the two answer different +questions, CI that the code has not fallen behind the compiler, a release +what it was actually built with. Moving a release to a newer compiler is +therefore a commit, not a Tuesday. + +That makes a release repeatable in the ways this repository controls: the +same source, the same dependency versions from `Cargo.lock`, the same +compiler, the same `cross` and the same actions. It does not make the +binaries bit-for-bit reproducible — the `cross` container images and the +runner environment are outside it. `SOURCE_DATE_EPOCH` only fixes the build +date `--version` prints. + +## crates.io credentials + +There are none. The publish job authenticates with +[Trusted Publishing](https://crates.io/docs/trusted-publishing): it asks +GitHub for an OIDC token naming the repository and the workflow file, and +`rust-lang/crates-io-auth-action` trades that with crates.io for a registry +token that lasts 30 minutes and is revoked when the job ends. That is what +`id-token: write` on the job is for; it grants nothing in this repository. + +The crate side is one-time setup, and only an owner of the crate can do it, +under the crate's Settings → Trusted Publishing → Add, publisher GitHub: + +| Field | Value | +| --- | --- | +| Repository owner | `librespeed` | +| Repository name | `speedtest-cli-rust` | +| Workflow filename | `release.yml` | +| Environment name | leave empty | + +The environment field is optional, and left empty it mints a token for any +run of that workflow on this repository. Naming one would narrow that +further, but only an environment with protection rules is worth the second +place to keep in step, and configuring those needs repository admin. + +Trusted Publishing cannot be configured for a crate that does not exist yet, +so the first version went out with an API token from +, stored as the repository secret +`CARGO_REGISTRY_TOKEN`. Nothing reads that secret any more and it can be +deleted. diff --git a/src/http/tls.rs b/src/http/tls.rs index 66df8d9..0fef333 100644 --- a/src/http/tls.rs +++ b/src/http/tls.rs @@ -1,10 +1,10 @@ //! TLS backend selection. //! -//! Two backends are available, because `ring` — the crypto provider behind -//! rustls — supports only x86, x86_64, aarch64, arm and wasm32, and fails the -//! build outright on anything else. Platforms outside that set (notably the -//! 32-bit PowerPC e500v2 in CZ.NIC Turris 1.x routers) can link against the -//! system OpenSSL instead: +//! Two backends are available, because `ring`, the crypto provider behind +//! rustls, has assembly only for x86, x86_64, aarch64 and arm. Elsewhere it +//! runs portable C, which is slow on a core without crypto instructions. +//! Platforms outside that set (notably the 32-bit PowerPC e500v2 in CZ.NIC +//! Turris 1.x routers) can link against the system OpenSSL instead: //! //! ```sh //! cargo build --release --no-default-features --features native-tls