aria2-rust-pro/docs/testing/quality-gates.md

Quality Gates

Primary test runner:

rtk cargo nextest run --workspace --all-targets --all-features

Required final gates:

rtk cargo fmt --all --check
rtk cargo check --workspace --all-targets --all-features --locked
rtk cargo nextest run --workspace --all-targets --all-features --locked
rtk cargo clippy --workspace --all-targets --all-features --locked --no-deps -- -D warnings -D clippy::pedantic -D clippy::nursery
rtk cargo +nightly udeps --workspace --all-targets --all-features --locked
rtk cargo deny --locked check

On this Windows host, cargo deny may inherit a broken Git schannel HTTPS path and fail with SEC_E_NO_CREDENTIALS. The repository's strict sweep now forces Git's http.sslbackend=openssl for the deny lane so the final gate does not depend on ambient machine Git TLS settings.

If an rtk equivalent is unavailable or broken for a command, record the fallback command in progress.md.

Recommended one-shot local sweep:

pwsh ./scripts/testing/strict-sweep.ps1

Self-Hosted Gitea Runner Notes

The self-hosted Gitea Actions runner image used for this repository must keep CARGO_BUILD_JOBS=2 for CI and release jobs. Do not lower it to 1 as a generic resource-throttling tweak.

The fast gate runs cargo clippy across the workspace with strict lint levels. On the NAS runner image, CARGO_BUILD_JOBS=1 caused the clippy lane to stall in a nested Cargo metadata / jobserver / target-lock chain. Keeping two build jobs gives the nested Cargo process enough scheduling room while still bounding runner load.

Do not add -D clippy::cargo back to CI or the local strict sweep without a fresh runner-side validation pass. That lint group spawns nested cargo metadata from clippy-driver, which can wait behind the parent cargo/clippy target lock on this NAS runner. Dependency, license, and advisory policy remains covered by the strict gate's cargo deny and cargo udeps lanes.

The runner image should keep cargo-nextest, cargo-deny, and cargo-udeps preinstalled. Baking those tools into the image reduced the Install Cargo tools step from roughly 26 minutes to 0-1 seconds on the self-hosted runner. Future image updates should preserve that tool cache before looking for more invasive target-directory caching.

docker/entrypoint.sh must retain executable mode (100755) in Git. Linux runner smokes execute it directly, and a non-executable checkout fails with Permission denied before the entrypoint behavior is tested.

xtask docker defaults DOCKER_BUILDKIT=0 when the caller has not set a builder preference. Synology Docker 24 left buildx sessions idle on the full release Dockerfile, while the classic builder completed the release image build and export path. Override DOCKER_BUILDKIT only after testing the runner's Docker daemon behavior.

Current runner timing evidence shows the remaining long steps are the Rust quality gates themselves: cold registry/download work, Rust compilation, nightly build-std, and NAS small-file IO. Docker image tar export was measured around 20 seconds and was not the bottleneck in the recovered release run.

Keep the value aligned in both places:

• the runner image or image Dockerfile, such as /volume1/docker/gitea/runner-images/aria2-rust-1.88/Dockerfile;
• .gitea/workflows/ci.yml and .gitea/workflows/release.yml.

If a future CI run appears stuck rather than failing with a compiler or test error, check this before changing source code:

docker logs --tail 300 gitea-runner
docker inspect gitea-runner --format '{{json .Config.Env}}' | jq .

CLI/tests/docs slice fallback lane

When lower-layer workspace crates are still red on strict docs or pedantic lint, the CLI/tests/docs owner should still keep the owned surface ready for final closeout with slice-scoped verification against the alternate target directory:

$env:CARGO_TARGET_DIR='.\target-alt'
rtk cargo check -p aria2-rust-pro-cli -p aria2-rust-pro-tests --all-targets
rtk cargo test -p aria2-rust-pro-cli
rtk cargo test -p aria2-rust-pro-tests
rtk cargo bench -p aria2-rust-pro-tests --bench rpc_pressure --no-run
rtk rustfmt --check crates/aria2-rust-pro-cli/src/lib.rs crates/aria2-rust-pro-cli/src/main.rs crates/aria2-rust-pro-tests/src/lib.rs crates/aria2-rust-pro-tests/benches/rpc_pressure.rs
rtk cargo clippy -p aria2-rust-pro-cli -p aria2-rust-pro-tests --all-targets --no-deps -- -D warnings -D clippy::pedantic

Notes for this lane:

• cargo clippy --no-deps is still useful for owned-file cleanup, but if workspace-path dependencies fail before the CLI/tests targets are linted, record the exact blocker in progress.md instead of widening the edit scope.
• rustfmt is file-scoped here on purpose so the lane can avoid touching unrelated crates while another worker is active elsewhere in the workspace.

Compatibility Evidence Slice

Lane F extends the integration suite in crates/aria2-rust-pro-tests/src/lib.rs with representative RPC parity checks that do not modify dispatcher or transport implementation files.

Recommended focused pass while iterating on RPC compatibility:

rtk cargo test -p aria2-rust-pro-tests parsed_jsonrpc_change_option_request_shape_matches_manual_dispatch_state
rtk cargo test -p aria2-rust-pro-tests xmlrpc_and_jsonrpc

Representative coverage kept for compatibility relock work:

• Raw JSON-RPC request parsing drives the same downstream aria2.changeOption state as a manually constructed request object.
• aria2.getGlobalOption returns the same object payload through JSON-RPC and XML-RPC after option normalization.
• Filtered BitTorrent aria2.tellStatus responses keep the same request-shape semantics and runtime field values across JSON-RPC and XML-RPC.
• system.multicall preserves nested result structure consistently across both RPC front doors for mixed payloads such as version, session, and BT status.
• Invalid-GID failures keep the same underlying RPC error message across JSON-RPC and XML-RPC, with XML-RPC still wrapping it in the upstream-style fault envelope.

Remaining scope limits for this lane:

• These tests prove in-process request/response parity, not socket-level server transport framing.
• XML-RPC number coercion is only covered where aria2-style payloads are expected to round-trip through the shared RpcValue surface.
• Full dispatcher internals, router behavior, and transport implementations are intentionally left to the lanes that own those files.