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
+[](https://github.com/librespeed/speedtest-cli-rust/actions/workflows/ci.yml)
+[](https://crates.io/crates/librespeed-cli)
+[](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