From 8c1402d465d3ea1258b7c15beea7cb27d016f315 Mon Sep 17 00:00:00 2001 From: tison Date: Tue, 17 Nov 2026 12:01:50 +0800 Subject: [PATCH 1/7] chore: prepare v0.1.1 --- .github/workflows/ci.yml | 20 +++++++++++++++----- CHANGELOG.md | 9 +++++++++ Cargo.lock | 2 +- bases/ARCHITECTURE.md | 1 + bases/CHANGELOG.md | 1 + bases/Cargo.toml | 2 +- bases/benchmarks/README.md | 1 + bases/examples/src/base64_field.rs | 1 + bases/examples/src/format_bytes.rs | 1 + bases/examples/src/profiles.rs | 1 + bases/examples/src/reusable_buffers.rs | 1 + bases/examples/src/stream_io.rs | 1 + bases/examples/src/url_cursor.rs | 1 + examples/src/stream_io.rs | 17 +++++++++++++---- 14 files changed, 48 insertions(+), 11 deletions(-) create mode 120000 bases/ARCHITECTURE.md create mode 120000 bases/CHANGELOG.md create mode 120000 bases/benchmarks/README.md create mode 120000 bases/examples/src/base64_field.rs create mode 120000 bases/examples/src/format_bytes.rs create mode 120000 bases/examples/src/profiles.rs create mode 120000 bases/examples/src/reusable_buffers.rs create mode 120000 bases/examples/src/stream_io.rs create mode 120000 bases/examples/src/url_cursor.rs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6923fc0..8535230 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -204,16 +204,22 @@ jobs: shell: bash run: | package_files="$(cargo package --package bases --locked --list)" - for required in Cargo.lock Cargo.toml README.md LICENSE src/lib.rs; do + for required in Cargo.lock Cargo.toml README.md LICENSE src/lib.rs \ + ARCHITECTURE.md CHANGELOG.md benchmarks/README.md examples/src/*.rs; do grep -Fxq "$required" <<< "$package_files" || { echo "missing required package file: $required" >&2 exit 1 } done - if grep -Eq '^(benchmarks|examples|tests-integration|xtask|target)/' <<< "$package_files"; then - echo "development-only files leaked into the package" >&2 - exit 1 - fi + while IFS= read -r file; do + case "$file" in + benchmarks/README.md|examples/src/*.rs) ;; + benchmarks/*|examples/*|tests-integration/*|xtask/*|target/*) + echo "development-only file leaked into the package: $file" >&2 + exit 1 + ;; + esac + done <<< "$package_files" - name: Build package run: cargo package --package bases --locked @@ -223,6 +229,10 @@ jobs: run: | package_dir="$(find target/package -mindepth 1 -maxdepth 1 -type d -name 'bases-*' -print -quit)" test -n "$package_dir" + for document in README.md ARCHITECTURE.md CHANGELOG.md benchmarks/README.md examples/src/*.rs; do + test -f "$package_dir/$document" && test ! -L "$package_dir/$document" + cmp "$document" "$package_dir/$document" + done cargo test --manifest-path "$package_dir/Cargo.toml" --all-features --locked cargo test --manifest-path "$package_dir/Cargo.toml" --no-default-features --locked cargo test --manifest-path "$package_dir/Cargo.toml" --no-default-features --features alloc,serde --locked diff --git a/CHANGELOG.md b/CHANGELOG.md index d3a6963..8e9f0e9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,15 @@ All significant changes to this project will be documented in this file. +## v0.1.1 (2026-11-17) + +- Write owned, appended, and fixed-array results directly into their destination storage, avoiding redundant initialization, copying, and UTF-8 validation. +- Reuse decoded-length and padding analysis across decoding paths, and encode formatted output in complete quanta without an intermediate stream encoder. +- Improve scalar and SIMD handling of short inputs and tails across Base16, Base32, and Base64, including simpler x86 Base64 character mapping and Base16 decoding. +- Size I/O writer chunks for each encoding profile and retain reusable output buffers across short reads in the streaming example. +- Include the architecture guide, changelog, benchmark guide, and linked example sources in the crate package so README links resolve within the published version. +- Expand contract tests across encoding profiles, buffer boundaries, malformed inputs, streaming retries, I/O, and Serde, including fixed-array Serde support without `alloc`. + ## v0.1.0 (2026-11-15) This is the initial release. diff --git a/Cargo.lock b/Cargo.lock index c840104..b79ee19 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -103,7 +103,7 @@ checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06" [[package]] name = "bases" -version = "0.1.0" +version = "0.1.1" dependencies = [ "serde", "serde_core", diff --git a/bases/ARCHITECTURE.md b/bases/ARCHITECTURE.md new file mode 120000 index 0000000..6763c82 --- /dev/null +++ b/bases/ARCHITECTURE.md @@ -0,0 +1 @@ +../ARCHITECTURE.md \ No newline at end of file diff --git a/bases/CHANGELOG.md b/bases/CHANGELOG.md new file mode 120000 index 0000000..04c99a5 --- /dev/null +++ b/bases/CHANGELOG.md @@ -0,0 +1 @@ +../CHANGELOG.md \ No newline at end of file diff --git a/bases/Cargo.toml b/bases/Cargo.toml index 53a08a8..08d2b42 100644 --- a/bases/Cargo.toml +++ b/bases/Cargo.toml @@ -15,7 +15,7 @@ [package] description = "Fast, strict RFC 4648 Base16, Base32, and Base64 codecs for Rust." name = "bases" -version = "0.1.0" +version = "0.1.1" categories = ["encoding", "no-std"] documentation = "https://docs.rs/bases" diff --git a/bases/benchmarks/README.md b/bases/benchmarks/README.md new file mode 120000 index 0000000..95f2818 --- /dev/null +++ b/bases/benchmarks/README.md @@ -0,0 +1 @@ +../../benchmarks/README.md \ No newline at end of file diff --git a/bases/examples/src/base64_field.rs b/bases/examples/src/base64_field.rs new file mode 120000 index 0000000..78d0ec0 --- /dev/null +++ b/bases/examples/src/base64_field.rs @@ -0,0 +1 @@ +../../../examples/src/base64_field.rs \ No newline at end of file diff --git a/bases/examples/src/format_bytes.rs b/bases/examples/src/format_bytes.rs new file mode 120000 index 0000000..115a5b5 --- /dev/null +++ b/bases/examples/src/format_bytes.rs @@ -0,0 +1 @@ +../../../examples/src/format_bytes.rs \ No newline at end of file diff --git a/bases/examples/src/profiles.rs b/bases/examples/src/profiles.rs new file mode 120000 index 0000000..7546958 --- /dev/null +++ b/bases/examples/src/profiles.rs @@ -0,0 +1 @@ +../../../examples/src/profiles.rs \ No newline at end of file diff --git a/bases/examples/src/reusable_buffers.rs b/bases/examples/src/reusable_buffers.rs new file mode 120000 index 0000000..6858638 --- /dev/null +++ b/bases/examples/src/reusable_buffers.rs @@ -0,0 +1 @@ +../../../examples/src/reusable_buffers.rs \ No newline at end of file diff --git a/bases/examples/src/stream_io.rs b/bases/examples/src/stream_io.rs new file mode 120000 index 0000000..a44f5f7 --- /dev/null +++ b/bases/examples/src/stream_io.rs @@ -0,0 +1 @@ +../../../examples/src/stream_io.rs \ No newline at end of file diff --git a/bases/examples/src/url_cursor.rs b/bases/examples/src/url_cursor.rs new file mode 120000 index 0000000..53a9368 --- /dev/null +++ b/bases/examples/src/url_cursor.rs @@ -0,0 +1 @@ +../../../examples/src/url_cursor.rs \ No newline at end of file diff --git a/examples/src/stream_io.rs b/examples/src/stream_io.rs index 9697827..0ee1685 100644 --- a/examples/src/stream_io.rs +++ b/examples/src/stream_io.rs @@ -66,13 +66,17 @@ fn encode( // Stream sizing accounts for bytes retained from the preceding read. let required = encoder.update_output_len(read)?; - output.resize(required, 0); + if output.len() < required { + output.resize(required, 0); + } let encoded = encoder.update(&input[..read], &mut output)?; destination.write_all(encoded.as_bytes())?; } let required = encoder.finish_output_len(); - output.resize(required, 0); + if output.len() < required { + output.resize(required, 0); + } destination.write_all(encoder.finish(&mut output)?.as_bytes())?; destination.flush()?; Ok(()) @@ -95,14 +99,19 @@ fn decode( }; let available = decoder.max_update_output_len(read); - output.resize(available, 0); + if output.len() < available { + output.resize(available, 0); + } let decoded = decoder.update(&input[..read], &mut output)?; // A later read or finish can still reject the message after a prefix has been written. destination.write_all(decoded)?; } // Even with no buffered output, finish is required to validate the final input fragment. - output.resize(decoder.finish_output_len()?, 0); + let required = decoder.finish_output_len()?; + if output.len() < required { + output.resize(required, 0); + } destination.write_all(decoder.finish(&mut output)?)?; destination.flush()?; Ok(()) From 8df8dfef77eb979c7a670fc0554da56b6c55fa2f Mon Sep 17 00:00:00 2001 From: tison Date: Tue, 17 Nov 2026 12:06:01 +0800 Subject: [PATCH 2/7] ci: test the current release package --- .github/workflows/ci.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8535230..2486048 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -227,8 +227,9 @@ jobs: - name: Test package shell: bash run: | - package_dir="$(find target/package -mindepth 1 -maxdepth 1 -type d -name 'bases-*' -print -quit)" - test -n "$package_dir" + package_dir="$(cargo metadata --format-version 1 --no-deps --locked | + jq -er '.target_directory as $target | .packages[] | select(.name == "bases") | "\($target)/package/\(.name)-\(.version)"')" + test -d "$package_dir" for document in README.md ARCHITECTURE.md CHANGELOG.md benchmarks/README.md examples/src/*.rs; do test -f "$package_dir/$document" && test ! -L "$package_dir/$document" cmp "$document" "$package_dir/$document" From 80b0438be5cc9a844b8892d4b293888523422192 Mon Sep 17 00:00:00 2001 From: tison Date: Tue, 17 Nov 2026 13:39:52 +0800 Subject: [PATCH 3/7] ci: unify package validation and simplify workflows --- .github/workflows/ci.yml | 92 ++++---------------------- Cargo.lock | 1 + RELEASE.md | 4 +- xtask/Cargo.toml | 1 + xtask/src/main.rs | 138 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 155 insertions(+), 81 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2486048..3071226 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,7 +18,6 @@ on: pull_request: push: branches: [main] - tags: ["v*"] workflow_dispatch: permissions: @@ -122,62 +121,33 @@ jobs: run: cargo x test target: - name: Target (${{ matrix.name }}) + name: Targets runs-on: ubuntu-24.04 timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - include: - - name: x86_64 AVX2 - target: x86_64-unknown-linux-gnu - features: --all-features - rustflags: -C target-feature=+avx2 - - name: x86_64 SSSE3 - target: x86_64-unknown-linux-gnu - features: --no-default-features - rustflags: -C target-feature=+ssse3 - - name: AArch64 NEON - target: aarch64-unknown-linux-gnu - features: --no-default-features - rustflags: -C target-feature=+neon - - name: WebAssembly - target: wasm32-unknown-unknown - features: --no-default-features - rustflags: "" - - name: WebAssembly SIMD128 - target: wasm32-unknown-unknown - features: --no-default-features - rustflags: -C target-feature=+simd128 - - name: bare metal - target: thumbv7em-none-eabi - features: --no-default-features - rustflags: "" env: RUSTUP_TOOLCHAIN: stable - RUSTFLAGS: -D warnings ${{ matrix.rustflags }} + RUSTFLAGS: -D warnings steps: - name: Check out repository uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - - name: Install Rust target + - name: Install Rust targets run: | rustup toolchain install stable --profile minimal --no-self-update - rustup target add "${{ matrix.target }}" + rustup target add x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu wasm32-unknown-unknown thumbv7em-none-eabi - name: Restore Rust cache uses: swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 - with: - key: ${{ matrix.target }} - - - name: Check target - run: cargo check --package bases --target "${{ matrix.target }}" --locked ${{ matrix.features }} - - - name: Check no_std feature combinations - if: matrix.target == 'thumbv7em-none-eabi' + - name: Check targets and no_std features run: | + RUSTFLAGS="-D warnings -C target-feature=+avx2" cargo check --package bases --target x86_64-unknown-linux-gnu --locked --all-features + RUSTFLAGS="-D warnings -C target-feature=+ssse3" cargo check --package bases --target x86_64-unknown-linux-gnu --locked --no-default-features + RUSTFLAGS="-D warnings -C target-feature=+neon" cargo check --package bases --target aarch64-unknown-linux-gnu --locked --no-default-features + cargo check --package bases --target wasm32-unknown-unknown --locked --no-default-features + RUSTFLAGS="-D warnings -C target-feature=+simd128" cargo check --package bases --target wasm32-unknown-unknown --locked --no-default-features + cargo check --package bases --target thumbv7em-none-eabi --locked --no-default-features cargo check --package bases --target thumbv7em-none-eabi --locked --no-default-features --features alloc cargo check --package bases --target thumbv7em-none-eabi --locked --no-default-features --features serde cargo check --package bases --target thumbv7em-none-eabi --locked --no-default-features --features alloc,serde @@ -200,44 +170,8 @@ jobs: - name: Restore Rust cache uses: swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 - - name: Validate package contents - shell: bash - run: | - package_files="$(cargo package --package bases --locked --list)" - for required in Cargo.lock Cargo.toml README.md LICENSE src/lib.rs \ - ARCHITECTURE.md CHANGELOG.md benchmarks/README.md examples/src/*.rs; do - grep -Fxq "$required" <<< "$package_files" || { - echo "missing required package file: $required" >&2 - exit 1 - } - done - while IFS= read -r file; do - case "$file" in - benchmarks/README.md|examples/src/*.rs) ;; - benchmarks/*|examples/*|tests-integration/*|xtask/*|target/*) - echo "development-only file leaked into the package: $file" >&2 - exit 1 - ;; - esac - done <<< "$package_files" - - - name: Build package - run: cargo package --package bases --locked - - - name: Test package - shell: bash - run: | - package_dir="$(cargo metadata --format-version 1 --no-deps --locked | - jq -er '.target_directory as $target | .packages[] | select(.name == "bases") | "\($target)/package/\(.name)-\(.version)"')" - test -d "$package_dir" - for document in README.md ARCHITECTURE.md CHANGELOG.md benchmarks/README.md examples/src/*.rs; do - test -f "$package_dir/$document" && test ! -L "$package_dir/$document" - cmp "$document" "$package_dir/$document" - done - cargo test --manifest-path "$package_dir/Cargo.toml" --all-features --locked - cargo test --manifest-path "$package_dir/Cargo.toml" --no-default-features --locked - cargo test --manifest-path "$package_dir/Cargo.toml" --no-default-features --features alloc,serde --locked - cargo test --manifest-path "$package_dir/Cargo.toml" --no-default-features --features serde --locked + - name: Validate package + run: cargo x package required: name: Required diff --git a/Cargo.lock b/Cargo.lock index b79ee19..e137254 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -681,6 +681,7 @@ name = "x" version = "0.0.0" dependencies = [ "clap", + "serde_json", "which", ] diff --git a/RELEASE.md b/RELEASE.md index 61aa059..3fad87c 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -6,8 +6,8 @@ Releases are published manually to crates.io. For the first release, check that 1. Update the version in `bases/Cargo.toml` and refresh `Cargo.lock`. 2. Move user-visible entries from `Unreleased` in `CHANGELOG.md` into a versioned section. -3. Run `cargo x lint`, `cargo x check`, `cargo x test`, and `cargo package --package bases --locked`. -4. Inspect the archive with `cargo package --package bases --locked --list`. Run `cargo publish --dry-run --package bases --locked` from the clean release commit to verify the package without uploading it. +3. Run `cargo x lint`, `cargo x check`, `cargo x test`, and `cargo x package`. The package command builds the archive, verifies its contents and documentation, and tests the extracted crate. Use `cargo x package --allow-dirty` to validate uncommitted changes during development. +4. Run `cargo publish --dry-run --package bases --locked` from the clean release commit to verify the package without uploading it. ## Publish diff --git a/xtask/Cargo.toml b/xtask/Cargo.toml index 3718576..780d2b9 100644 --- a/xtask/Cargo.toml +++ b/xtask/Cargo.toml @@ -26,6 +26,7 @@ release = false [dependencies] clap = { workspace = true } +serde_json = { workspace = true } which = { workspace = true } [lints] diff --git a/xtask/src/main.rs b/xtask/src/main.rs index 152aac5..2ecdef7 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -12,7 +12,10 @@ // See the License for the specific language governing permissions and // limitations under the License. +use std::collections::BTreeSet; +use std::fs; use std::path::Path; +use std::path::PathBuf; use std::process; use clap::Parser; @@ -67,6 +70,7 @@ impl Command { SubCommand::Build(cmd) => cmd.run(), SubCommand::Check(cmd) => cmd.run(), SubCommand::Lint(cmd) => cmd.run(), + SubCommand::Package(cmd) => cmd.run(), SubCommand::Test(cmd) => cmd.run(), } } @@ -82,6 +86,8 @@ enum SubCommand { Check(CommandCheck), #[command(about = "Run workspace quality checks.")] Lint(CommandLint), + #[command(about = "Build, inspect, and test the bases release package.")] + Package(CommandPackage), #[command(about = "Run workspace tests.")] Test(CommandTest), } @@ -188,6 +194,138 @@ impl CommandLint { } } +#[derive(Parser)] +struct CommandPackage { + #[arg( + long, + help = "Allow packaging uncommitted changes for local validation." + )] + allow_dirty: bool, +} + +impl CommandPackage { + fn run(self) { + let workspace = Path::new(env!("CARGO_WORKSPACE_DIR")); + let mut metadata_cmd = cargo(); + metadata_cmd.args(["metadata", "--format-version", "1", "--no-deps", "--locked"]); + let metadata: serde_json::Value = serde_json::from_str(&command_output(metadata_cmd)) + .expect("Cargo metadata must be valid JSON"); + let package = metadata["packages"] + .as_array() + .expect("Cargo metadata must contain packages") + .iter() + .find(|package| package["name"].as_str() == Some(PACKAGE_NAME)) + .expect("bases must be a workspace package"); + let version = package["version"] + .as_str() + .expect("package version missing"); + let package_dir = Path::new( + metadata["target_directory"] + .as_str() + .expect("Cargo target directory missing"), + ) + .join("package") + .join(format!("{PACKAGE_NAME}-{version}")); + + let mut documents: Vec = [ + "README.md", + "ARCHITECTURE.md", + "CHANGELOG.md", + "benchmarks/README.md", + ] + .into_iter() + .map(PathBuf::from) + .collect(); + for entry in fs::read_dir(workspace.join("examples/src")).expect("cannot read examples") { + let path = entry.expect("cannot read example entry").path(); + if path.extension().is_some_and(|extension| extension == "rs") { + documents.push(path.strip_prefix(workspace).unwrap().to_path_buf()); + } + } + documents.sort(); + + let mut list_cmd = cargo(); + list_cmd.args(["package", "--package", PACKAGE_NAME, "--locked", "--list"]); + if self.allow_dirty { + list_cmd.arg("--allow-dirty"); + } + let files: BTreeSet = command_output(list_cmd) + .lines() + .map(PathBuf::from) + .collect(); + for required in ["Cargo.lock", "Cargo.toml", "LICENSE", "src/lib.rs"] { + assert!( + files.contains(Path::new(required)), + "missing package file: {required}" + ); + } + for document in &documents { + assert!( + files.contains(document), + "missing package document: {}", + document.display() + ); + } + for file in &files { + let development_only = [ + "benchmarks", + "examples", + "tests-integration", + "xtask", + "target", + ] + .iter() + .any(|directory| file.starts_with(directory)); + assert!( + !development_only || documents.contains(file), + "development-only file in package: {}", + file.display() + ); + } + + let mut package_cmd = cargo(); + package_cmd.args(["package", "--package", PACKAGE_NAME, "--locked"]); + if self.allow_dirty { + package_cmd.arg("--allow-dirty"); + } + run_command(package_cmd); + + for document in &documents { + let path = package_dir.join(document); + let metadata = fs::symlink_metadata(&path).expect("cannot inspect packaged document"); + assert!( + metadata.is_file(), + "expected a regular file: {}", + path.display() + ); + assert!( + fs::read(&path).expect("cannot read packaged document") + == fs::read(workspace.join(document)).expect("cannot read source document"), + "packaged document differs from its source: {}", + document.display() + ); + } + + let mut test_cmd = cargo(); + test_cmd + .arg("test") + .arg("--manifest-path") + .arg(package_dir.join("Cargo.toml")); + test_cmd.args(["--all-features", "--locked"]); + run_command(test_cmd); + } +} + +fn command_output(mut cmd: process::Command) -> String { + println!("{cmd:?}"); + let output = cmd + .stderr(process::Stdio::inherit()) + .output() + .expect("failed to execute process"); + assert!(output.status.success(), "command failed: {}", output.status); + String::from_utf8(output.stdout).expect("command output must be UTF-8") +} + fn find_command(command: &str) -> process::Command { match which::which(command) { Ok(executable) => { From 247122db9aefaae09122d10f740bde984b6b6eee Mon Sep 17 00:00:00 2001 From: tison Date: Tue, 17 Nov 2026 13:56:05 +0800 Subject: [PATCH 4/7] chore: simplify release validation and organize guides --- .github/workflows/ci.yml | 23 +---- ARCHITECTURE.md | 27 ----- CHANGELOG.md | 2 +- Cargo.lock | 1 - Cargo.toml | 1 - README.md | 71 +++---------- RELEASE.md | 8 +- bases/ARCHITECTURE.md | 32 +++++- bases/CHANGELOG.md | 1 - bases/Cargo.toml | 2 +- bases/README.md | 85 +++++++++++++++ bases/benchmarks/README.md | 1 - bases/examples/src/base64_field.rs | 1 - bases/examples/src/format_bytes.rs | 1 - bases/examples/src/profiles.rs | 1 - bases/examples/src/reusable_buffers.rs | 1 - bases/examples/src/stream_io.rs | 1 - bases/examples/src/url_cursor.rs | 1 - examples/README.md | 27 +++++ xtask/Cargo.toml | 1 - xtask/src/main.rs | 138 ------------------------- 21 files changed, 167 insertions(+), 259 deletions(-) delete mode 100644 ARCHITECTURE.md mode change 120000 => 100644 bases/ARCHITECTURE.md delete mode 120000 bases/CHANGELOG.md create mode 100644 bases/README.md delete mode 120000 bases/benchmarks/README.md delete mode 120000 bases/examples/src/base64_field.rs delete mode 120000 bases/examples/src/format_bytes.rs delete mode 120000 bases/examples/src/profiles.rs delete mode 120000 bases/examples/src/reusable_buffers.rs delete mode 120000 bases/examples/src/stream_io.rs delete mode 120000 bases/examples/src/url_cursor.rs create mode 100644 examples/README.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3071226..0d99403 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -152,31 +152,10 @@ jobs: cargo check --package bases --target thumbv7em-none-eabi --locked --no-default-features --features serde cargo check --package bases --target thumbv7em-none-eabi --locked --no-default-features --features alloc,serde - package: - name: Package - runs-on: ubuntu-24.04 - timeout-minutes: 10 - env: - RUSTUP_TOOLCHAIN: stable - steps: - - name: Check out repository - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - run: rustup toolchain install stable --profile minimal --no-self-update - - - name: Restore Rust cache - uses: swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 - - - name: Validate package - run: cargo x package - required: name: Required if: ${{ always() }} - needs: [lint, msrv, test, target, package] + needs: [lint, msrv, test, target] runs-on: ubuntu-24.04 timeout-minutes: 5 steps: diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 62642df..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,27 +0,0 @@ -# Architecture - -Bases separates observable encoding semantics from execution strategy. - -## Public layers - -- Parameterized zero-sized family types (`base16::Base16`, `base32::Base32`, `base64::Base64`) combined with `policy` markers (`Padded`, `Unpadded`, `Lower`, `Upper`, `Mixed`, `Strict`) define an alphabet, padding policy, and case policy, alongside ten crate-root aliases (`Base16Lower`, `Base16Upper`, `Base32`, `Base32Unpadded`, `Base32Hex`, `Base32HexUnpadded`, `Base64`, `Base64Unpadded`, `Base64Url`, `Base64UrlUnpadded`). -- Concrete family types provide direct inherent methods, including `const fn` sizing and constructors (`new`, `name`, `encoded_len`, `max_decoded_len`, `display`, `encoder`, `decoder`), while the sealed `Codec` trait provides the shared contract for generic `C: Codec` callers. -- Slice, in-place, and fixed-array primitives (`encode_into`, `decode_into`, `decode_in_place`, `decode_array`) operate without allocation; `alloc` adds `encode`, `encode_append`, `decode`, and transactional `decode_append`; `serde` adds `serialize`, `deserialize_array`, and (`alloc`) `deserialize`. -- `Encoder` and `Decoder` preserve one partial quantum for incremental operation without allocation; `std` adds `bases::io::{EncoderWriter, DecoderReader}` over `std::io::{Write, Read}`. -- Formatting adapters (`EncodedDisplay` and explicit-case `HexDisplay`) stream encoded output through `core::fmt`. - -## Backend boundary - -Each profile maps at compile time to private backend dispatch functions that pair scalar reference implementations with architecture-specific SIMD kernels: - -- `aarch64` NEON (`target_feature = "neon"`) for Base16, Base32, and Base64. -- `x86` and `x86_64` AVX2 and SSSE3 for Base16, Base32, and Base64, using runtime `is_x86_feature_detected!` dispatch under `std` or compile-time `target_feature` selection in `no_std`. -- `wasm32` `simd128` (`target_feature = "simd128"`) for Base16 and Base64. - -SIMD backends process aligned bulk prefixes and fall back to the scalar reference implementations for tails and under `cfg!(miri)`. Callers cannot select or observe a backend, and every SIMD kernel preserves exact scalar output, error precedence, error byte offsets, and stream-state contracts. While the workspace denies `unsafe_code`, private `backend/*/arch` modules carry scoped `#[allow(unsafe_code)]` with `missing_safety_doc` and `undocumented_unsafe_blocks` enforced. - -## Performance contract - -The primary API writes into caller-owned slices, arrays, or in-place mutable buffers without allocating. Sizing methods let callers reuse exact encoding buffers and safe upper-bound decoding buffers. Successful stream updates consume the complete input slice; failures leave stream state unchanged so callers can retry with more output capacity. - -In-place decoding (`decode_in_place`) writes the decoded prefix back over the encoded buffer and leaves buffer contents unspecified on `DecodeError`. Constant-time execution and in-place encoding are not provided. diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e9f0e9..c8f345e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ All significant changes to this project will be documented in this file. - Reuse decoded-length and padding analysis across decoding paths, and encode formatted output in complete quanta without an intermediate stream encoder. - Improve scalar and SIMD handling of short inputs and tails across Base16, Base32, and Base64, including simpler x86 Base64 character mapping and Base16 decoding. - Size I/O writer chunks for each encoding profile and retain reusable output buffers across short reads in the streaming example. -- Include the architecture guide, changelog, benchmark guide, and linked example sources in the crate package so README links resolve within the published version. +- Ship a self-contained usage guide and architecture documentation with the crate, and organize repository navigation for examples, benchmarks, and release notes. - Expand contract tests across encoding profiles, buffer boundaries, malformed inputs, streaming retries, I/O, and Serde, including fixed-array Serde support without `alloc`. ## v0.1.0 (2026-11-15) diff --git a/Cargo.lock b/Cargo.lock index e137254..b79ee19 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -681,7 +681,6 @@ name = "x" version = "0.0.0" dependencies = [ "clap", - "serde_json", "which", ] diff --git a/Cargo.toml b/Cargo.toml index d971afa..60177d1 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -19,7 +19,6 @@ resolver = "3" [workspace.package] edition = "2024" license = "Apache-2.0" -readme = "README.md" repository = "https://github.com/fast/bases" rust-version = "1.88.0" diff --git a/README.md b/README.md index 18405f5..cacc5e5 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Fast, strict RFC 4648 Base16, Base32, and Base64 codecs for Rust. -Bases provides configurable zero-sized family types (`base16::Base16`, `base32::Base32`, `base64::Base64`) parameterized by `policy` markers alongside ten crate-root profile aliases (`Base16Lower`, `Base16Upper`, `Base32`, `Base32Unpadded`, `Base32Hex`, `Base32HexUnpadded`, `Base64`, `Base64Unpadded`, `Base64Url`, `Base64UrlUnpadded`). Every profile exposes direct inherent methods (including `const fn` sizing and constructors) without requiring trait imports, and implements the sealed `Codec` trait for generic callers. +Bases supports allocation-free caller buffers, owned results, incremental streaming, formatting, and Serde integration. It works in `no_std` without dependencies by default. ```rust use bases::{Base64, Base64UrlUnpadded}; @@ -31,67 +31,30 @@ let encoded = Base64UrlUnpadded::encode_into(b"hello", &mut buffer).unwrap(); assert_eq!(encoded, "aGVsbG8"); ``` -## API layers +## Documentation -- `encoded_len`, `max_decoded_len`, `encode_into`, `decode_into`, `decode_in_place`, and `decode_array` provide allocation-free operations, with `const fn` support on concrete profile `name`, `encoded_len`, `max_decoded_len`, `display`, `encoder`, and `decoder`. -- `encode`, `encode_append`, `decode`, and `decode_append` provide `String` and `Vec` helpers when the `alloc` feature is enabled. -- `Encoder` and `Decoder` process arbitrarily chunked input while retaining at most one partial quantum; the `std` feature adds `bases::io::{EncoderWriter, DecoderReader}` for `std::io::{Write, Read}`. -- `display` (`EncodedDisplay`) and `HexDisplay` (`LowerHex` `{:x}` and `UpperHex` `{:X}` only) write encoded data directly through `core::fmt`. -- `serialize`, `deserialize_array`, and (with `alloc`) `deserialize` integrate with `#[serde(with = "...")]` when the `serde` feature is enabled. +Add `bases = "0.1"` to your dependencies. The [usage guide](bases/README.md) covers profiles, feature flags, streaming, and error handling. -```rust -use bases::Base64; - -let mut encoder = Base64::encoder(); -let mut output = [0_u8; 4]; -assert_eq!(encoder.update(b"fo", &mut output).unwrap(), ""); -assert_eq!(encoder.update(b"o", &mut output).unwrap(), "Zm9v"); -assert_eq!(encoder.finish(&mut output).unwrap(), ""); -``` - -Bases is `#![no_std]` by default (`default = []`), exposing caller-buffer, in-place, fixed-array, streaming, and formatting APIs with zero default features. The `alloc` feature adds `String` and `Vec` helpers; `std` enables `alloc`, `bases::io::{EncoderWriter, DecoderReader}`, and runtime x86/x86_64 CPU feature detection; `serde` adds `serde_core` serialization and fixed-array deserialization in `no_std`, plus `Vec` deserialization when combined with `alloc`. - -Successful `finish()` consumes the stream. On failure, `FinishError::into_inner()` recovers the unchanged encoder or decoder for retrying with a larger output buffer. Callers that do not need recovery can use `?` to convert `FinishError` into the underlying `EncodeError`, `DecodeError`, or `DecodeSliceError`, discarding the stream. +| Task | Read | +| ----------------------------- | ----------------------------------------- | +| Choose a profile or API | [Usage guide](bases/README.md) | +| Look up public contracts | [API reference](https://docs.rs/bases) | +| Run application examples | [Examples](examples/README.md) | +| Understand the implementation | [Architecture](bases/ARCHITECTURE.md) | +| Measure a workload | [Benchmarks](benchmarks/README.md) | +| Review release changes | [Changelog](CHANGELOG.md) | -## Examples +## Development -Runnable examples live in the `examples` workspace crate. Each program uses local sample data and can run without arguments from the repository root: +The workspace separates the library, examples, integration tests, benchmarks, and repository tooling. Run checks from the repository root: ```shell -cargo run --package examples --example url_cursor +cargo x check +cargo x test +cargo x lint ``` -| Example | Application | APIs to start with | -|--------------------------------------------------------|---------------------------------------------------------------------------------------------|----------------------------------------------------------| -| [`base64_field`](examples/src/base64_field.rs) | Carry binary data in a JSON string field and reject a malformed field. | `Base64::encode`, `Base64::decode`, `DecodeError` | -| [`url_cursor`](examples/src/url_cursor.rs) | Encode a record ID into an unpadded URL-safe pagination cursor and recover it. | `Base64UrlUnpadded::encode`, `decode_array` | -| [`reusable_buffers`](examples/src/reusable_buffers.rs) | Reuse output buffers across a batch of records with different encoding profiles. | `C: Codec`, sizing helpers, `encode_into`, `decode_into` | -| [`stream_io`](examples/src/stream_io.rs) | Convert a file or network stream with bounded buffers and explicit finalization. | `Encoder`, `Decoder`, `update`, `finish` | -| [`format_bytes`](examples/src/format_bytes.rs) | Format binary IDs and payloads in diagnostic output without an intermediate encoded string. | `HexDisplay` (`{:x}`/`{:X}`), `Base64::display` | -| [`profiles`](examples/src/profiles.rs) | Compare Base16, Base32, Base64, and Base64URL representations. | `Base16Lower`, `Base16Upper`, `Base32`, `Base64` | - -The `stream_io` example also accepts `encode` or `decode` to transform standard input into standard output using padded Base64: - -```shell -printf 'hello, world' | cargo run --quiet --package examples --example stream_io -- encode -printf 'aGVsbG8sIHdvcmxk' | cargo run --quiet --package examples --example stream_io -- decode -``` - -Its `encode` and `decode` helpers accept any `Read` and `Write`, including files and sockets. Successful updates consume the complete input chunk; `finish()` handles the final fragment at EOF. A decoding error can arrive after earlier output has been written, so callers should treat the destination as complete only after the whole operation succeeds. - -## Strictness - -Decoders reject whitespace, bytes outside the selected alphabet, misplaced or forbidden padding, and non-zero unused trailing bits. Padded and unpadded protocols use different profile types; `Base16Lower` and `Base16Upper` default to RFC 4648 case-insensitive decoding (`policy::Mixed`), while strict single-case Base16 and case-insensitive Base32 (such as RFC 5155 `Base32`) can be selected explicitly via `policy` markers. - -Base encoding is not encryption. Bases does not provide constant-time guarantees and uses data-dependent branches, table lookups, and private scalar or SIMD backends (`aarch64` NEON, `x86`/`x86_64` SSSE3 and AVX2, and `wasm32` `simd128`). - -## Architecture - -[Architecture](ARCHITECTURE.md) records the public layers, private backend boundary, and performance contracts. See [CHANGELOG.md](CHANGELOG.md) for release notes. - -## Benchmarks - -Run `cargo x bench` to compare caller buffers, owned results, formatting, streaming, and invalid-input handling against other Rust codecs. The [benchmark guide](benchmarks/README.md) lists the workloads and explains how to read the timings. +Use `cargo x bench` for performance comparisons and see the [benchmark guide](benchmarks/README.md) for workloads and measurement limits. See [Releasing Bases](RELEASE.md) for release validation and publication. ## Minimum Rust version policy diff --git a/RELEASE.md b/RELEASE.md index 3fad87c..dbe1d63 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,13 +1,13 @@ # Releasing Bases -Releases are published manually to crates.io. For the first release, check that the crate name is still available and the repository linked in the package metadata is accessible to its intended readers. +Releases are published manually to crates.io from a clean commit that has passed CI. ## Prepare 1. Update the version in `bases/Cargo.toml` and refresh `Cargo.lock`. -2. Move user-visible entries from `Unreleased` in `CHANGELOG.md` into a versioned section. -3. Run `cargo x lint`, `cargo x check`, `cargo x test`, and `cargo x package`. The package command builds the archive, verifies its contents and documentation, and tests the extracted crate. Use `cargo x package --allow-dirty` to validate uncommitted changes during development. -4. Run `cargo publish --dry-run --package bases --locked` from the clean release commit to verify the package without uploading it. +2. Add a versioned section to the [changelog](CHANGELOG.md) for user-visible changes. +3. Run `cargo x lint`, `cargo x check`, and `cargo x test`. +4. From the clean release commit, review `cargo package --list --package bases --locked` and run `cargo publish --dry-run --package bases --all-features --locked`. Cargo builds the archive and verifies that the extracted crate compiles without uploading it. Check that the package contains its README, architecture guide, and license, with relative documentation links resolving inside the package. ## Publish diff --git a/bases/ARCHITECTURE.md b/bases/ARCHITECTURE.md deleted file mode 120000 index 6763c82..0000000 --- a/bases/ARCHITECTURE.md +++ /dev/null @@ -1 +0,0 @@ -../ARCHITECTURE.md \ No newline at end of file diff --git a/bases/ARCHITECTURE.md b/bases/ARCHITECTURE.md new file mode 100644 index 0000000..01edba2 --- /dev/null +++ b/bases/ARCHITECTURE.md @@ -0,0 +1,31 @@ +# Architecture + +Bases separates observable encoding semantics from execution strategy. + +## Public layers + +- Parameterized zero-sized family types (`base16::Base16`, `base32::Base32`, `base64::Base64`) combined with `policy` markers (`Padded`, `Unpadded`, `Lower`, `Upper`, `Mixed`, `Strict`) define an alphabet, padding policy, and case policy, alongside ten crate-root aliases (`Base16Lower`, `Base16Upper`, `Base32`, `Base32Unpadded`, `Base32Hex`, `Base32HexUnpadded`, `Base64`, `Base64Unpadded`, `Base64Url`, `Base64UrlUnpadded`). +- Concrete family types provide direct inherent methods, including `const fn` sizing and constructors (`new`, `name`, `encoded_len`, `max_decoded_len`, `display`, `encoder`, `decoder`), while the sealed `Codec` trait provides the shared contract for generic `C: Codec` callers. +- Slice, in-place, and fixed-array primitives (`encode_into`, `decode_into`, `decode_in_place`, `decode_array`) operate without allocation; `alloc` adds `encode`, `encode_append`, `decode`, and transactional `decode_append`; `serde` adds `serialize`, `deserialize_array`, and (`alloc`) `deserialize`. +- `Encoder` and `Decoder` preserve one partial quantum for incremental operation without allocation; `std` adds `bases::io::{EncoderWriter, DecoderReader}` over `std::io::{Write, Read}`. +- Formatting adapters (`EncodedDisplay` and explicit-case `HexDisplay`) stream encoded output through `core::fmt`. + +## Backend boundary + +Each profile maps at compile time to private backend dispatch functions that pair scalar reference implementations with architecture-specific SIMD kernels: + +- `aarch64` NEON (`target_feature = "neon"`) for Base16, Base32, and Base64. +- `x86` and `x86_64` AVX2 and SSSE3 for Base16, Base32, and Base64, using runtime `is_x86_feature_detected!` dispatch under `std` or compile-time `target_feature` selection in `no_std`. +- `wasm32` `simd128` (`target_feature = "simd128"`) for Base16 and Base64. + +SIMD backends process bulk prefixes and fall back to the scalar reference implementations for tails and under `cfg!(miri)`. Backend selection is private, and every SIMD kernel preserves exact scalar output, error precedence, error byte offsets, and stream-state contracts. + +The workspace denies `unsafe_code` by default. Scoped allowances cover architecture intrinsics and internal buffer operations, including writing into uninitialized storage and converting initialized ASCII bytes to strings. These operations document their safety invariants, with `missing_safety_doc` and `undocumented_unsafe_blocks` enforced. + +## Performance contract + +The primary API writes into caller-owned slices, arrays, or in-place mutable buffers without allocating. Sizing methods let callers reuse exact encoding buffers and safe upper-bound decoding buffers. Successful stream updates consume the complete input slice; failures leave stream state unchanged so callers can retry with more output capacity. + +Owned, appended, and fixed-array results are written directly into their destination storage. Only initialized output is exposed to callers; spare capacity does not require zeroing or a second copy. Formatting encodes complete input quanta into a bounded scratch buffer before writing to the formatter. + +In-place decoding (`decode_in_place`) writes the decoded prefix back over the encoded buffer and leaves buffer contents unspecified on `DecodeError`. Constant-time execution and in-place encoding are not provided. diff --git a/bases/CHANGELOG.md b/bases/CHANGELOG.md deleted file mode 120000 index 04c99a5..0000000 --- a/bases/CHANGELOG.md +++ /dev/null @@ -1 +0,0 @@ -../CHANGELOG.md \ No newline at end of file diff --git a/bases/Cargo.toml b/bases/Cargo.toml index 08d2b42..ff57b91 100644 --- a/bases/Cargo.toml +++ b/bases/Cargo.toml @@ -15,6 +15,7 @@ [package] description = "Fast, strict RFC 4648 Base16, Base32, and Base64 codecs for Rust." name = "bases" +readme = "README.md" version = "0.1.1" categories = ["encoding", "no-std"] @@ -22,7 +23,6 @@ documentation = "https://docs.rs/bases" edition.workspace = true keywords = ["base16", "base32", "base64", "encoding", "no-std"] license.workspace = true -readme.workspace = true repository.workspace = true rust-version.workspace = true diff --git a/bases/README.md b/bases/README.md new file mode 100644 index 0000000..d82e0db --- /dev/null +++ b/bases/README.md @@ -0,0 +1,85 @@ +# bases + +Fast, strict RFC 4648 Base16, Base32, and Base64 codecs for Rust. + +## Quick start + +Add Bases to your application: + +```toml +[dependencies] +bases = "0.1" +``` + +The default configuration works in `no_std` without an allocator or dependencies. Encode into a caller-provided buffer, or decode into a fixed-size array when the decoded length is known: + +```rust +use bases::{Base64, Base64UrlUnpadded}; + +let mut buffer = [0_u8; 8]; +let encoded = Base64::encode_into(b"hello", &mut buffer).unwrap(); +assert_eq!(encoded, "aGVsbG8="); + +let decoded: [u8; 5] = Base64::decode_array(encoded).unwrap(); +assert_eq!(&decoded, b"hello"); + +let cursor = Base64UrlUnpadded::encode_into(b"hello", &mut buffer).unwrap(); +assert_eq!(cursor, "aGVsbG8"); +``` + +## Choose a profile + +Ten crate-root aliases cover standard encoding profiles: + +- `Base16Lower` and `Base16Upper` emit lowercase and uppercase hex respectively, and both accept either case when decoding. +- `Base32` and `Base32Unpadded` use the uppercase RFC 4648 alphabet, with or without padding. +- `Base32Hex` and `Base32HexUnpadded` use the uppercase extended-hex alphabet, with or without padding. +- `Base64` and `Base64Unpadded` use the standard Base64 alphabet, with or without padding. +- `Base64Url` and `Base64UrlUnpadded` use the URL-safe alphabet, with or without padding. + +Every profile exposes inherent methods without requiring trait imports, and implements the sealed `Codec` trait for generic callers. Configurable zero-sized family types (`base16::Base16`, `base32::Base32`, and `base64::Base64`) accept `policy` markers for other combinations, such as strict single-case Base16 or RFC 5155 Base32Hex with lowercase output and case-insensitive decoding. See the [API reference](https://docs.rs/bases) for types, methods, and their contracts. + +## API layers and features + +- **Caller buffers (`no_std`):** `encoded_len`, `max_decoded_len`, `encode_into`, `decode_into`, `decode_in_place`, and `decode_array` operate without allocation. Concrete profiles provide `const fn` constructors and sizing methods. +- **Owned output (`alloc`):** `encode` and `decode` return `String` and `Vec`; `encode_append` and transactional `decode_append` extend existing buffers. +- **Streaming (`no_std` / `std`):** `Encoder` and `Decoder` process arbitrarily chunked input while retaining at most one partial quantum. The `std` feature adds `io::EncoderWriter` and `io::DecoderReader` for `std::io::Write` and `std::io::Read`. +- **Formatting (`no_std`):** `display` (`EncodedDisplay`) and `HexDisplay` (`{:x}` and `{:X}` only) write encoded text through `core::fmt` without an intermediate string. +- **Serde (`serde`):** `serialize` and `deserialize_array` integrate with `#[serde(with = "...")]`; `deserialize` returns a byte vector when `alloc` is also enabled. + +| Feature | Effect | +| --------- | -------------------------------------------------------------------------------------------------- | +| Default | No features or dependencies; caller-buffer, in-place, fixed-array, streaming, and formatting APIs. | +| `alloc` | Adds owned and append helpers for `String` and `Vec`. | +| `std` | Enables `alloc`, I/O adapters, and runtime x86/x86_64 CPU feature detection. | +| `serde` | Adds `serde_core` serialization and fixed-array deserialization, including without an allocator. | + +## Streaming and errors + +```rust +use bases::Base64; + +let mut encoder = Base64::encoder(); +let mut output = [0_u8; 4]; +assert_eq!(encoder.update(b"fo", &mut output).unwrap(), ""); +assert_eq!(encoder.update(b"o", &mut output).unwrap(), "Zm9v"); +assert_eq!(encoder.finish(&mut output).unwrap(), ""); +``` + +Successful updates consume the complete input chunk. Successful `finish()` consumes the stream and handles the final fragment. On failure, `FinishError::into_inner()` recovers the unchanged encoder or decoder for retrying with a larger output buffer. Callers that do not need recovery can use `?` to convert `FinishError` into the underlying `EncodeError`, `DecodeError`, or `DecodeSliceError`, discarding the stream. + +A decoding error can arrive after earlier output has been written. Treat a streamed destination as complete only after finalization or reading to EOF succeeds. + +## Strictness and security + +Decoders reject whitespace, bytes outside the selected alphabet, misplaced or forbidden padding, and non-zero unused trailing bits. Padded and unpadded protocols use different profile types; case handling follows the selected profile. + +Base encoding is not encryption. Bases does not provide constant-time guarantees and uses data-dependent branches, table lookups, and private scalar or SIMD backends. The [architecture guide](ARCHITECTURE.md) describes backend dispatch and performance contracts. + +## Minimum Rust version policy + +The minimum supported Rust version is 1.88.0. It may be increased in a minor release, but not in a patch release. + +## License + +Licensed under the [Apache License, Version 2.0](LICENSE). diff --git a/bases/benchmarks/README.md b/bases/benchmarks/README.md deleted file mode 120000 index 95f2818..0000000 --- a/bases/benchmarks/README.md +++ /dev/null @@ -1 +0,0 @@ -../../benchmarks/README.md \ No newline at end of file diff --git a/bases/examples/src/base64_field.rs b/bases/examples/src/base64_field.rs deleted file mode 120000 index 78d0ec0..0000000 --- a/bases/examples/src/base64_field.rs +++ /dev/null @@ -1 +0,0 @@ -../../../examples/src/base64_field.rs \ No newline at end of file diff --git a/bases/examples/src/format_bytes.rs b/bases/examples/src/format_bytes.rs deleted file mode 120000 index 115a5b5..0000000 --- a/bases/examples/src/format_bytes.rs +++ /dev/null @@ -1 +0,0 @@ -../../../examples/src/format_bytes.rs \ No newline at end of file diff --git a/bases/examples/src/profiles.rs b/bases/examples/src/profiles.rs deleted file mode 120000 index 7546958..0000000 --- a/bases/examples/src/profiles.rs +++ /dev/null @@ -1 +0,0 @@ -../../../examples/src/profiles.rs \ No newline at end of file diff --git a/bases/examples/src/reusable_buffers.rs b/bases/examples/src/reusable_buffers.rs deleted file mode 120000 index 6858638..0000000 --- a/bases/examples/src/reusable_buffers.rs +++ /dev/null @@ -1 +0,0 @@ -../../../examples/src/reusable_buffers.rs \ No newline at end of file diff --git a/bases/examples/src/stream_io.rs b/bases/examples/src/stream_io.rs deleted file mode 120000 index a44f5f7..0000000 --- a/bases/examples/src/stream_io.rs +++ /dev/null @@ -1 +0,0 @@ -../../../examples/src/stream_io.rs \ No newline at end of file diff --git a/bases/examples/src/url_cursor.rs b/bases/examples/src/url_cursor.rs deleted file mode 120000 index 53a9368..0000000 --- a/bases/examples/src/url_cursor.rs +++ /dev/null @@ -1 +0,0 @@ -../../../examples/src/url_cursor.rs \ No newline at end of file diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..8d06673 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,27 @@ +# Examples + +Runnable examples live in this workspace crate. Each program uses local sample data and can run without arguments from the repository root: + +```shell +cargo run --package examples --example url_cursor +``` + +| Example | Application | APIs to start with | +| --------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------- | +| [`base64_field`](src/base64_field.rs) | Carry binary data in a JSON string field and reject a malformed field. | `Base64::encode`, `Base64::decode`, `DecodeError` | +| [`url_cursor`](src/url_cursor.rs) | Encode a record ID into an unpadded URL-safe pagination cursor and recover it. | `Base64UrlUnpadded::encode`, `decode_array` | +| [`reusable_buffers`](src/reusable_buffers.rs) | Reuse output buffers across a batch of records with different encoding profiles. | `C: Codec`, sizing helpers, `encode_into`, `decode_into` | +| [`stream_io`](src/stream_io.rs) | Convert a file or network stream with bounded buffers and explicit finalization. | `Encoder`, `Decoder`, `update`, `finish` | +| [`format_bytes`](src/format_bytes.rs) | Format binary IDs and payloads in diagnostic output without an intermediate encoded string. | `HexDisplay` (`{:x}`/`{:X}`), `Base64::display` | +| [`profiles`](src/profiles.rs) | Compare Base16, Base32, Base64, and Base64URL representations. | `Base16Lower`, `Base16Upper`, `Base32`, `Base64` | + +## Stream I/O + +The `stream_io` example also accepts `encode` or `decode` to transform standard input into standard output using padded Base64: + +```shell +printf 'hello, world' | cargo run --quiet --package examples --example stream_io -- encode +printf 'aGVsbG8sIHdvcmxk' | cargo run --quiet --package examples --example stream_io -- decode +``` + +Its `encode` and `decode` helpers accept any `Read` and `Write`, including files and sockets. Successful updates consume the complete input chunk; `finish()` handles the final fragment at EOF. A decoding error can arrive after earlier output has been written, so callers should treat the destination as complete only after the whole operation succeeds. diff --git a/xtask/Cargo.toml b/xtask/Cargo.toml index 780d2b9..3718576 100644 --- a/xtask/Cargo.toml +++ b/xtask/Cargo.toml @@ -26,7 +26,6 @@ release = false [dependencies] clap = { workspace = true } -serde_json = { workspace = true } which = { workspace = true } [lints] diff --git a/xtask/src/main.rs b/xtask/src/main.rs index 2ecdef7..152aac5 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -12,10 +12,7 @@ // See the License for the specific language governing permissions and // limitations under the License. -use std::collections::BTreeSet; -use std::fs; use std::path::Path; -use std::path::PathBuf; use std::process; use clap::Parser; @@ -70,7 +67,6 @@ impl Command { SubCommand::Build(cmd) => cmd.run(), SubCommand::Check(cmd) => cmd.run(), SubCommand::Lint(cmd) => cmd.run(), - SubCommand::Package(cmd) => cmd.run(), SubCommand::Test(cmd) => cmd.run(), } } @@ -86,8 +82,6 @@ enum SubCommand { Check(CommandCheck), #[command(about = "Run workspace quality checks.")] Lint(CommandLint), - #[command(about = "Build, inspect, and test the bases release package.")] - Package(CommandPackage), #[command(about = "Run workspace tests.")] Test(CommandTest), } @@ -194,138 +188,6 @@ impl CommandLint { } } -#[derive(Parser)] -struct CommandPackage { - #[arg( - long, - help = "Allow packaging uncommitted changes for local validation." - )] - allow_dirty: bool, -} - -impl CommandPackage { - fn run(self) { - let workspace = Path::new(env!("CARGO_WORKSPACE_DIR")); - let mut metadata_cmd = cargo(); - metadata_cmd.args(["metadata", "--format-version", "1", "--no-deps", "--locked"]); - let metadata: serde_json::Value = serde_json::from_str(&command_output(metadata_cmd)) - .expect("Cargo metadata must be valid JSON"); - let package = metadata["packages"] - .as_array() - .expect("Cargo metadata must contain packages") - .iter() - .find(|package| package["name"].as_str() == Some(PACKAGE_NAME)) - .expect("bases must be a workspace package"); - let version = package["version"] - .as_str() - .expect("package version missing"); - let package_dir = Path::new( - metadata["target_directory"] - .as_str() - .expect("Cargo target directory missing"), - ) - .join("package") - .join(format!("{PACKAGE_NAME}-{version}")); - - let mut documents: Vec = [ - "README.md", - "ARCHITECTURE.md", - "CHANGELOG.md", - "benchmarks/README.md", - ] - .into_iter() - .map(PathBuf::from) - .collect(); - for entry in fs::read_dir(workspace.join("examples/src")).expect("cannot read examples") { - let path = entry.expect("cannot read example entry").path(); - if path.extension().is_some_and(|extension| extension == "rs") { - documents.push(path.strip_prefix(workspace).unwrap().to_path_buf()); - } - } - documents.sort(); - - let mut list_cmd = cargo(); - list_cmd.args(["package", "--package", PACKAGE_NAME, "--locked", "--list"]); - if self.allow_dirty { - list_cmd.arg("--allow-dirty"); - } - let files: BTreeSet = command_output(list_cmd) - .lines() - .map(PathBuf::from) - .collect(); - for required in ["Cargo.lock", "Cargo.toml", "LICENSE", "src/lib.rs"] { - assert!( - files.contains(Path::new(required)), - "missing package file: {required}" - ); - } - for document in &documents { - assert!( - files.contains(document), - "missing package document: {}", - document.display() - ); - } - for file in &files { - let development_only = [ - "benchmarks", - "examples", - "tests-integration", - "xtask", - "target", - ] - .iter() - .any(|directory| file.starts_with(directory)); - assert!( - !development_only || documents.contains(file), - "development-only file in package: {}", - file.display() - ); - } - - let mut package_cmd = cargo(); - package_cmd.args(["package", "--package", PACKAGE_NAME, "--locked"]); - if self.allow_dirty { - package_cmd.arg("--allow-dirty"); - } - run_command(package_cmd); - - for document in &documents { - let path = package_dir.join(document); - let metadata = fs::symlink_metadata(&path).expect("cannot inspect packaged document"); - assert!( - metadata.is_file(), - "expected a regular file: {}", - path.display() - ); - assert!( - fs::read(&path).expect("cannot read packaged document") - == fs::read(workspace.join(document)).expect("cannot read source document"), - "packaged document differs from its source: {}", - document.display() - ); - } - - let mut test_cmd = cargo(); - test_cmd - .arg("test") - .arg("--manifest-path") - .arg(package_dir.join("Cargo.toml")); - test_cmd.args(["--all-features", "--locked"]); - run_command(test_cmd); - } -} - -fn command_output(mut cmd: process::Command) -> String { - println!("{cmd:?}"); - let output = cmd - .stderr(process::Stdio::inherit()) - .output() - .expect("failed to execute process"); - assert!(output.status.success(), "command failed: {}", output.status); - String::from_utf8(output.stdout).expect("command output must be UTF-8") -} - fn find_command(command: &str) -> process::Command { match which::which(command) { Ok(executable) => { From 9d7de5cf8b2021554a28f6805cdfef93952bbf6f Mon Sep 17 00:00:00 2001 From: tison Date: Tue, 17 Nov 2026 15:06:41 +0800 Subject: [PATCH 5/7] Apply suggestion from @tisonkun Signed-off-by: tison --- bases/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bases/README.md b/bases/README.md index d82e0db..710a599 100644 --- a/bases/README.md +++ b/bases/README.md @@ -4,7 +4,7 @@ Fast, strict RFC 4648 Base16, Base32, and Base64 codecs for Rust. ## Quick start -Add Bases to your application: +Add `bases` to your application: ```toml [dependencies] From a2d62dd192effc418080f3b8433dcd9f9b745a36 Mon Sep 17 00:00:00 2001 From: tison Date: Tue, 17 Nov 2026 15:14:08 +0800 Subject: [PATCH 6/7] docs: align naming, MSRV guidance, and release notes --- CHANGELOG.md | 19 ++++++++++++------- README.md | 6 +++--- bases/README.md | 6 +++--- benchmarks/benches/throughput/harness.rs | 2 +- xtask/src/main.rs | 2 +- 5 files changed, 20 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c8f345e..8f2f0e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,15 +1,20 @@ -# CHANGELOG +# Changelog All significant changes to this project will be documented in this file. ## v0.1.1 (2026-11-17) -- Write owned, appended, and fixed-array results directly into their destination storage, avoiding redundant initialization, copying, and UTF-8 validation. -- Reuse decoded-length and padding analysis across decoding paths, and encode formatted output in complete quanta without an intermediate stream encoder. -- Improve scalar and SIMD handling of short inputs and tails across Base16, Base32, and Base64, including simpler x86 Base64 character mapping and Base16 decoding. -- Size I/O writer chunks for each encoding profile and retain reusable output buffers across short reads in the streaming example. -- Ship a self-contained usage guide and architecture documentation with the crate, and organize repository navigation for examples, benchmarks, and release notes. -- Expand contract tests across encoding profiles, buffer boundaries, malformed inputs, streaming retries, I/O, and Serde, including fixed-array Serde support without `alloc`. +### Improvements + +* Include a self-contained usage guide and architecture documentation in the crate package, and organize repository navigation for examples, benchmarks, and release notes. + +### Performance improvements + +* Avoid redundant initialization, copying, and UTF-8 validation when encoding or decoding owned results, appending to existing buffers, and decoding fixed-size arrays. +* Reuse decoded-length and padding analysis across decoding paths to avoid repeated validation. +* Reduce formatting and incremental streaming overhead by processing complete encoding quanta directly. +* Improve scalar and SIMD handling of short inputs and tails across Base16, Base32, and Base64, including simpler x86 Base64 character mapping and Base16 decoding. +* Let `io::EncoderWriter` process larger input chunks according to the encoding profile, and avoid redundant buffer initialization across short reads in the streaming example. ## v0.1.0 (2026-11-15) diff --git a/README.md b/README.md index cacc5e5..63ada56 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# bases +# Bases [![Crates.io][crates-badge]][crates-url] [![Documentation][docs-badge]][docs-url] @@ -56,9 +56,9 @@ cargo x lint Use `cargo x bench` for performance comparisons and see the [benchmark guide](benchmarks/README.md) for workloads and measurement limits. See [Releasing Bases](RELEASE.md) for release validation and publication. -## Minimum Rust version policy +## Supported Rust Versions (MSRV 1.88.0) -The minimum supported Rust version is 1.88.0. It may be increased in a minor release, but not in a patch release. +Bases is built against the latest stable release. The minimum supported version is 1.88.0. The current Bases version is not guaranteed to build on Rust versions earlier than the minimum supported version. ## License diff --git a/bases/README.md b/bases/README.md index 710a599..9d58bf8 100644 --- a/bases/README.md +++ b/bases/README.md @@ -1,4 +1,4 @@ -# bases +# Bases Fast, strict RFC 4648 Base16, Base32, and Base64 codecs for Rust. @@ -76,9 +76,9 @@ Decoders reject whitespace, bytes outside the selected alphabet, misplaced or fo Base encoding is not encryption. Bases does not provide constant-time guarantees and uses data-dependent branches, table lookups, and private scalar or SIMD backends. The [architecture guide](ARCHITECTURE.md) describes backend dispatch and performance contracts. -## Minimum Rust version policy +## Supported Rust Versions (MSRV 1.88.0) -The minimum supported Rust version is 1.88.0. It may be increased in a minor release, but not in a patch release. +Bases is built against the latest stable release. The minimum supported version is 1.88.0. The current Bases version is not guaranteed to build on Rust versions earlier than the minimum supported version. ## License diff --git a/benchmarks/benches/throughput/harness.rs b/benchmarks/benches/throughput/harness.rs index 09ad83d..87c2c18 100644 --- a/benchmarks/benches/throughput/harness.rs +++ b/benchmarks/benches/throughput/harness.rs @@ -81,7 +81,7 @@ struct Options { /// Number of timing samples per implementation. #[arg(long, default_value = "5")] repeat: NonZeroUsize, - /// Run only bases, for instance when sizing a new workload. + /// Run only Bases, for instance when sizing a new workload. #[arg(long)] baseline_only: bool, /// Print every sample in measurement order. diff --git a/xtask/src/main.rs b/xtask/src/main.rs index 152aac5..9723d16 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -78,7 +78,7 @@ enum SubCommand { Bench(CommandBench), #[command(about = "Compile workspace packages.")] Build(CommandBuild), - #[command(about = "Check bases under its feature configurations.")] + #[command(about = "Check Bases under its feature configurations.")] Check(CommandCheck), #[command(about = "Run workspace quality checks.")] Lint(CommandLint), From 2d29341e5d8dc0c02bbcf20ad683b27c78c75c41 Mon Sep 17 00:00:00 2001 From: tison Date: Tue, 17 Nov 2026 15:23:16 +0800 Subject: [PATCH 7/7] docs: align MSRV policy with Asyncband --- README.md | 6 ++++-- bases/README.md | 6 ++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 63ada56..a2d2a9e 100644 --- a/README.md +++ b/README.md @@ -56,9 +56,11 @@ cargo x lint Use `cargo x bench` for performance comparisons and see the [benchmark guide](benchmarks/README.md) for workloads and measurement limits. See [Releasing Bases](RELEASE.md) for release validation and publication. -## Supported Rust Versions (MSRV 1.88.0) +## Minimum Supported Rust Version (MSRV) -Bases is built against the latest stable release. The minimum supported version is 1.88.0. The current Bases version is not guaranteed to build on Rust versions earlier than the minimum supported version. +This crate is built against the latest stable release, and its minimum supported rustc version is 1.88.0. + +The policy is that the minimum Rust version required to use this crate can be increased in minor version updates. For example, if Bases 1.0 requires Rust 1.20.0, then Bases 1.0.z for all values of z will also require Rust 1.20.0 or newer. However, Bases 1.y for y > 0 may require a newer minimum version of Rust. ## License diff --git a/bases/README.md b/bases/README.md index 9d58bf8..178190f 100644 --- a/bases/README.md +++ b/bases/README.md @@ -76,9 +76,11 @@ Decoders reject whitespace, bytes outside the selected alphabet, misplaced or fo Base encoding is not encryption. Bases does not provide constant-time guarantees and uses data-dependent branches, table lookups, and private scalar or SIMD backends. The [architecture guide](ARCHITECTURE.md) describes backend dispatch and performance contracts. -## Supported Rust Versions (MSRV 1.88.0) +## Minimum Supported Rust Version (MSRV) -Bases is built against the latest stable release. The minimum supported version is 1.88.0. The current Bases version is not guaranteed to build on Rust versions earlier than the minimum supported version. +This crate is built against the latest stable release, and its minimum supported rustc version is 1.88.0. + +The policy is that the minimum Rust version required to use this crate can be increased in minor version updates. For example, if Bases 1.0 requires Rust 1.20.0, then Bases 1.0.z for all values of z will also require Rust 1.20.0 or newer. However, Bases 1.y for y > 0 may require a newer minimum version of Rust. ## License