From b5a8be0049eed5cfbb834e0498ed5cc0bd1ed782 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sun, 4 Oct 2026 04:08:53 +0200 Subject: [PATCH] release: add rust_realease workflow --- .gitignore | 1 + CHANGELOG.md | 12 ++ Cargo.toml | 6 + README.md | 1 + docs/releasing.md | 89 +++++++++++++ release.sh | 48 +++++++ rust-release.toml | 3 + tests/release_wrapper.rs | 279 +++++++++++++++++++++++++++++++++++++++ 8 files changed, 439 insertions(+) create mode 100644 CHANGELOG.md create mode 100644 docs/releasing.md create mode 100755 release.sh create mode 100644 rust-release.toml create mode 100644 tests/release_wrapper.rs diff --git a/.gitignore b/.gitignore index 957eb72..f53457f 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ debug/ target/ coverage/ +dist/ # These are backup files generated by rustfmt **/*.rs.bk diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..a70180e --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,12 @@ +# Changelog + +Notable user-facing changes are recorded here. This project follows Semantic Versioning. + +## Unreleased + +## 0.1.0 - release pending + +- Construct and inspect IPv4 and IPv6 ICMP packets with configurable fields, payloads, sizes, padding, counts, timeouts, intervals, and hop limits. +- Send echo probes through datagram or raw sockets and match replies and quoted ICMP errors. +- Emit summaries, hexadecimal packet dumps, or newline-delimited JSON. +- Support privilege-free dry runs for packet inspection. diff --git a/Cargo.toml b/Cargo.toml index dac35e9..50bc95f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -5,6 +5,12 @@ edition = "2021" rust-version = "1.70" description = "A small IPv4 and IPv6 ICMP packet utility" license = "MIT" +repository = "https://proxy.dandaedre.com/gitea/Archive/rping" + +[package.metadata.binstall] +pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ target }-v{ version }.tgz" +pkg-fmt = "tgz" +bin-dir = "{ name }-{ target }-v{ version }/{ bin }{ binary-ext }" [dependencies] clap = { version = ">=4.4, <4.5", features = ["derive"] } diff --git a/README.md b/README.md index 6474e74..5a6a30f 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,7 @@ For a live probe, omit `--dry-run`. Review the Linux permissions described in [U - [Usage](docs/usage.md) covers address families, payloads, packet sizing, output formats, live probes, and raw sockets. - [Development and CI](docs/development.md) covers contributor commands, the minimum supported Rust version, dependency policy, coverage, and badge publication. +- [Releasing](docs/releasing.md) covers release preparation, local packaging, collision checks, and publication through `rust_realease`. The complete command reference is always available locally: diff --git a/docs/releasing.md b/docs/releasing.md new file mode 100644 index 0000000..fe4d4ef --- /dev/null +++ b/docs/releasing.md @@ -0,0 +1,89 @@ +# Release procedure + +This page documents release preparation and publication for the `rping` package and its `rping` binary. The package version in `Cargo.toml` is authoritative; version `X.Y.Z` uses tag `vX.Y.Z`. + +## Release contract + +- Canonical repository: `Archive/rping` +- Public release URL: `https://proxy.dandaedre.com/gitea/Archive/rping/releases` +- Package and binary: `rping` +- Profile: `release` +- Artifact format: cargo-binstall `.tgz` archives and standalone binaries (`both`) +- Targets: `x86_64-unknown-linux-musl`, `aarch64-unknown-linux-musl`, and `x86_64-pc-windows-gnu` +- Tag prefix: `v` + +The repository is public and contains cargo-binstall metadata. The local wrapper uses the default target matrix reported by `rust_realease`; pass explicit `--target` options only as a deliberate release-policy change. + +## Prerequisites + +Install and verify: + +- `rust_realease` +- Cross +- a working Docker or Podman backend +- `cargo-binstall` +- Git and the Rust toolchain pinned by `rust-toolchain.toml` + +The publisher executable intentionally uses the upstream spelling `rust_realease`. Its preferred installation method is: + +```sh +cargo binstall --git https://proxy.dandaedre.com/gitea/idle-org/rust_realease \ + rust_realease +rust_realease --help +``` + +See the [upstream repository](https://proxy.dandaedre.com/gitea/idle-org/rust_realease) for source-installation alternatives. + +Prepare a token file outside the repository. Its first line must contain a Gitea token able to inspect and create releases for `Archive/rping`. Restrict the file to the maintainer account, for example: + +```sh +chmod 600 /path/to/gitea-token.txt +``` + +Never commit the token or pass its value on the command line. `release.sh` reads the first line and exports it only as `GITEA_TOKEN` to `rust_realease`. + +## Prepare and verify + +1. Update `CHANGELOG.md`, `Cargo.toml`, and `Cargo.lock` so the changelog and package version agree. +2. Run every command in [Development and CI](development.md#quality-gates), including coverage. +3. Verify the release wrapper tests with `cargo test --locked --test release_wrapper`. +4. Commit the reviewed preparation. +5. Create an annotated or signed `vX.Y.Z` tag at that commit and push the commit and tag through the normal reviewed Git workflow. +6. Confirm the checkout is clean and that the local and remote tags resolve to `HEAD`. +7. Check the Gitea release-by-tag API or repository UI for an existing release and list all existing asset names. + +The wrapper never creates, moves, pushes, or deletes Git tags. It also does not edit Cargo metadata, Git remotes, or releases before invoking the publisher. + +## Dry run and packaging + +Always start with a dry run: + +```sh +./release.sh /path/to/gitea-token.txt --dry-run +``` + +Confirm the package, version, tag, three targets, artifact names, and proxy release destination. Treat every reported issue as a blocker. + +When local resources permit, build and inspect the complete package set without contacting Gitea: + +```sh +./release.sh /path/to/gitea-token.txt --compile-only +``` + +Inspect `SHA256SUMS`, archive contents, executable names and modes, and cargo-binstall metadata. Repeat the build in a clean checkout with the same toolchain and compare checksums when reproducibility is required. + +## Publish + +Immediately before publishing, repeat the tag, release, and asset collision checks. Then run: + +```sh +./release.sh /path/to/gitea-token.txt +``` + +A hyphenated package version such as `0.2.0-rc.1` automatically adds `--prerelease`; a stable version does not. Additional arguments are forwarded exactly to `rust_realease`. + +An existing release is not permission to overwrite assets. Stop on any asset-name collision. Use `--replace-assets` only after inspecting that exact release and explicitly deciding that the named assets should be replaced. + +## Repository fallback + +Development uses the unchanged SSH origin `git@git.dandaedre.com:Archive/rping.git`. `rust-release.toml` maps only that exact origin to `https://proxy.dandaedre.com/gitea/Archive/rping` for release API and download operations. The fallback does not rewrite the Git remote. diff --git a/release.sh b/release.sh new file mode 100755 index 0000000..cba633b --- /dev/null +++ b/release.sh @@ -0,0 +1,48 @@ +#!/bin/sh +set -eu + +usage() { + echo "usage: $0 [rust_realease options...]" >&2 + exit 2 +} + +[ "$#" -ge 1 ] || usage +token_file=$1 +shift + +if [ ! -f "$token_file" ] || [ ! -r "$token_file" ]; then + echo "token file is not a readable regular file: $token_file" >&2 + exit 2 +fi + +if ! command -v rust_realease >/dev/null 2>&1; then + echo "rust_realease is not installed or not available in PATH" >&2 + exit 2 +fi + +GITEA_TOKEN= +IFS= read -r GITEA_TOKEN <"$token_file" || : +if [ -z "$GITEA_TOKEN" ]; then + echo "token file is empty: $token_file" >&2 + exit 2 +fi +export GITEA_TOKEN + +repository_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +manifest_version=$(sed -n 's/^version = "\([^"]*\)"/\1/p' \ + "$repository_dir/Cargo.toml" | head -n 1) +if [ -z "$manifest_version" ]; then + echo "could not determine the selected package version" >&2 + exit 2 +fi + +set -- \ + "$repository_dir" \ + --package rping \ + --artifact-format both \ + "$@" +case "$manifest_version" in + *-*) set -- "$@" --prerelease ;; +esac + +exec rust_realease "$@" diff --git a/rust-release.toml b/rust-release.toml new file mode 100644 index 0000000..3280bb9 --- /dev/null +++ b/rust-release.toml @@ -0,0 +1,3 @@ +[[repository.fallbacks]] +origin = "git@git.dandaedre.com:Archive/rping.git" +fallback-url = "https://proxy.dandaedre.com/gitea/Archive/rping" diff --git a/tests/release_wrapper.rs b/tests/release_wrapper.rs new file mode 100644 index 0000000..46c0803 --- /dev/null +++ b/tests/release_wrapper.rs @@ -0,0 +1,279 @@ +#![cfg(unix)] + +use std::{ + env, fs, + os::unix::fs::PermissionsExt, + path::{Path, PathBuf}, + process::{Command, Output}, + sync::atomic::{AtomicUsize, Ordering}, +}; + +const DEVELOPMENT_ORIGIN: &str = "git@git.dandaedre.com:Archive/rping.git"; +const RELEASE_CONFIG: &str = "[[repository.fallbacks]]\n\ +origin = \"git@git.dandaedre.com:Archive/rping.git\"\n\ +fallback-url = \"https://proxy.dandaedre.com/gitea/Archive/rping\"\n"; +static NEXT_TEMPORARY: AtomicUsize = AtomicUsize::new(0); + +struct TemporaryDirectory(PathBuf); + +impl TemporaryDirectory { + fn new(label: &str) -> Self { + let serial = NEXT_TEMPORARY.fetch_add(1, Ordering::Relaxed); + let path = env::temp_dir().join(format!("rping-{label}-{}-{serial}", std::process::id())); + fs::create_dir(&path).expect("temporary directory should be created"); + Self(path) + } + + fn path(&self) -> &Path { + &self.0 + } +} + +impl Drop for TemporaryDirectory { + fn drop(&mut self) { + let _ = fs::remove_dir_all(&self.0); + } +} + +fn run(command: &mut Command) -> Output { + command.output().expect("test command should start") +} + +fn make_executable(path: &Path) { + let mut permissions = fs::metadata(path) + .expect("executable metadata should be readable") + .permissions(); + permissions.set_mode(0o755); + fs::set_permissions(path, permissions).expect("executable mode should be set"); +} + +fn prepare_repository(temporary: &TemporaryDirectory, version_line: &str) -> (PathBuf, PathBuf) { + let repository = temporary.path().join("repository with spaces"); + let fake_bin = temporary.path().join("fake bin"); + fs::create_dir(&repository).expect("repository should be created"); + fs::create_dir(&fake_bin).expect("fake binary directory should be created"); + + fs::copy( + Path::new(env!("CARGO_MANIFEST_DIR")).join("release.sh"), + repository.join("release.sh"), + ) + .expect("release wrapper should be copied"); + make_executable(&repository.join("release.sh")); + fs::copy( + Path::new(env!("CARGO_MANIFEST_DIR")).join("rust-release.toml"), + repository.join("rust-release.toml"), + ) + .expect("release configuration should be copied"); + fs::write( + repository.join("Cargo.toml"), + format!("[package]\nname = \"rping\"\n{version_line}\n"), + ) + .expect("manifest should be written"); + + assert!(run(Command::new("git") + .arg("-C") + .arg(&repository) + .args(["init", "--quiet"])) + .status + .success()); + assert!(run(Command::new("git").arg("-C").arg(&repository).args([ + "remote", + "add", + "origin", + DEVELOPMENT_ORIGIN + ])) + .status + .success()); + + (repository, fake_bin) +} + +fn install_fake_publisher(fake_bin: &Path) { + let publisher = fake_bin.join("rust_realease"); + fs::write( + &publisher, + "#!/bin/sh\n\ + [ \"$GITEA_TOKEN\" = test-token ] || exit 91\n\ + printf '%s\\n' \"$GITEA_TOKEN\" >\"$OBSERVED_TOKEN\"\n\ + printf '%s\\n' \"$@\" >\"$OBSERVED_ARGS\"\n\ + git -C \"$1\" remote get-url origin >\"$OBSERVED_ORIGIN\"\n\ + cat \"$1/rust-release.toml\" >\"$OBSERVED_CONFIG\"\n\ + printf 'fake publisher ran\\n'\n\ + exit \"$FAKE_RELEASE_STATUS\"\n", + ) + .expect("fake publisher should be written"); + make_executable(&publisher); +} + +fn wrapper_command( + repository: &Path, + fake_bin: &Path, + token_file: &Path, + temporary: &TemporaryDirectory, + status: i32, +) -> Command { + let mut command = Command::new(repository.join("release.sh")); + command + .arg(token_file) + .env( + "PATH", + format!( + "{}:{}", + fake_bin.display(), + env::var("PATH").expect("PATH should be available") + ), + ) + .env("FAKE_RELEASE_STATUS", status.to_string()) + .env("OBSERVED_TOKEN", temporary.path().join("observed token")) + .env("OBSERVED_ARGS", temporary.path().join("observed args")) + .env("OBSERVED_ORIGIN", temporary.path().join("observed origin")) + .env("OBSERVED_CONFIG", temporary.path().join("observed config")); + command +} + +#[test] +fn stable_release_forwards_exact_arguments_without_leaking_token() { + let temporary = TemporaryDirectory::new("stable-release"); + let (repository, fake_bin) = prepare_repository(&temporary, "version = \"0.1.0\""); + install_fake_publisher(&fake_bin); + let token_file = temporary.path().join("token file"); + fs::write(&token_file, "test-token\nignored-second-line\n").expect("token should be written"); + + let output = run( + wrapper_command(&repository, &fake_bin, &token_file, &temporary, 0).args([ + "--dry-run", + "--tag", + "tag with spaces", + ]), + ); + assert!(output.status.success()); + assert!(!String::from_utf8_lossy(&output.stdout).contains("test-token")); + assert!(!String::from_utf8_lossy(&output.stderr).contains("test-token")); + + let arguments = fs::read_to_string(temporary.path().join("observed args")) + .expect("arguments should be recorded"); + assert_eq!( + arguments.lines().collect::>(), + [ + repository + .to_str() + .expect("repository path should be UTF-8"), + "--package", + "rping", + "--artifact-format", + "both", + "--dry-run", + "--tag", + "tag with spaces", + ] + ); + assert!(!arguments.contains("test-token")); + assert_eq!( + fs::read_to_string(temporary.path().join("observed token")) + .expect("token should be recorded"), + "test-token\n" + ); + assert_eq!( + fs::read_to_string(temporary.path().join("observed config")) + .expect("config should be recorded"), + RELEASE_CONFIG + ); + assert_eq!( + fs::read_to_string(temporary.path().join("observed origin")) + .expect("origin should be recorded") + .trim(), + DEVELOPMENT_ORIGIN + ); + assert_eq!( + String::from_utf8( + run(Command::new("git") + .arg("-C") + .arg(&repository) + .args(["remote", "get-url", "origin"])) + .stdout + ) + .expect("origin should be UTF-8") + .trim(), + DEVELOPMENT_ORIGIN + ); +} + +#[test] +fn prerelease_is_added_and_publisher_status_is_preserved() { + let temporary = TemporaryDirectory::new("prerelease"); + let (repository, fake_bin) = prepare_repository(&temporary, "version = \"0.2.0-rc.1\""); + install_fake_publisher(&fake_bin); + let token_file = temporary.path().join("token"); + fs::write(&token_file, "test-token\n").expect("token should be written"); + + let output = run(&mut wrapper_command( + &repository, + &fake_bin, + &token_file, + &temporary, + 17, + )); + assert_eq!(output.status.code(), Some(17)); + let arguments = fs::read_to_string(temporary.path().join("observed args")) + .expect("arguments should be recorded"); + assert!(arguments.lines().any(|argument| argument == "--prerelease")); +} + +#[test] +fn invalid_inputs_fail_before_publishing() { + let temporary = TemporaryDirectory::new("invalid-inputs"); + let (repository, fake_bin) = prepare_repository(&temporary, "version = \"0.1.0\""); + install_fake_publisher(&fake_bin); + let wrapper = repository.join("release.sh"); + let empty_path = temporary.path().join("empty path"); + fs::create_dir(&empty_path).expect("empty PATH directory should be created"); + + assert!(!run(&mut Command::new(&wrapper)).status.success()); + assert!( + !run(Command::new(&wrapper).arg(temporary.path().join("missing token"))) + .status + .success() + ); + + let empty_token = temporary.path().join("empty token"); + fs::write(&empty_token, "").expect("empty token should be written"); + assert!(!run(Command::new(&wrapper).arg(&empty_token)) + .status + .success()); + + let unreadable_token = temporary.path().join("unreadable token"); + fs::write(&unreadable_token, "test-token\n").expect("token should be written"); + let mut permissions = fs::metadata(&unreadable_token) + .expect("token metadata should be readable") + .permissions(); + permissions.set_mode(0o000); + fs::set_permissions(&unreadable_token, permissions).expect("token mode should be set"); + assert!(!run(Command::new(&wrapper).arg(&unreadable_token)) + .status + .success()); + + let valid_token = temporary.path().join("valid token"); + fs::write(&valid_token, "test-token\n").expect("token should be written"); + let missing_publisher = run(Command::new(&wrapper) + .arg(&valid_token) + .env("PATH", &empty_path)); + assert_eq!(missing_publisher.status.code(), Some(2)); + assert!(String::from_utf8_lossy(&missing_publisher.stderr) + .contains("rust_realease is not installed")); + + fs::write( + repository.join("Cargo.toml"), + "[package]\nname = \"rping\"\n", + ) + .expect("manifest without a version should be written"); + let unresolved_version = run(&mut wrapper_command( + &repository, + &fake_bin, + &valid_token, + &temporary, + 0, + )); + assert_eq!(unresolved_version.status.code(), Some(2)); + assert!(String::from_utf8_lossy(&unresolved_version.stderr) + .contains("could not determine the selected package version")); +}