v0.1.0 — Scaffold

throttle-net v0.1.0 — Scaffold

The repository bootstrap. v0.1.0 establishes the structure, tooling, and quality gates the implementation will be built on — crate metadata, the feature-flag layout, the test-stack dev-dependencies, the CI matrix, the security gates (cargo-deny + cargo-audit), and the docs/API.md reference skeleton. There is no throttling logic yet; the algorithm surface lands across the 0.x series per the roadmap. Zero public API beyond the crate root.

What is throttle-net?

A general-purpose outbound throttling and resilience library. Where rate-net protects your service from being overwhelmed (inbound), throttle-net protects your service from overwhelming downstream APIs and from being banned by them (outbound). It composes rate-limiting algorithms into hybrid and layered policies and adds the parts nobody ships: multi-dimensional cost-aware limits and adaptive throttling. The common case is one builder and one acquire().await?.

What's in 0.1.0

Crate metadata and release profile

Cargo.toml carries the full published-crate metadata: description, keywords, categories, repository / homepage / documentation links, dual Apache-2.0 OR MIT license, Rust 2024 edition, MSRV 1.85, and docs.rs configuration (all-features + --cfg docsrs). The release profile is tuned for the eventual hot paths: opt-level = 3, fat LTO, a single codegen unit, panic = "abort", and symbol stripping.

Feature-flag layout

The flag surface is declared up front so downstream wiring is stable as features land:

[features]
default = ["std", "tokio"]
std             = []
tokio           = ["dep:tokio"]
adaptive        = []
circuit-breaker = []
provider-headers = []
provider-llm    = ["provider-headers"]
metrics         = ["dep:metrics"]
tracing         = ["dep:tracing"]
serde           = ["dep:serde"]

Runtime adapters beyond tokio (async-std, smol) are scheduled for v0.8.0 and are intentionally not wired until there is code that uses them — this keeps the dependency graph minimal and avoids carrying an unused, upstream-discontinued runtime through seven phases of development.

Test-stack dev-dependencies

The full verification stack is pinned and ready: criterion for hot-path benchmarks, proptest for invariant coverage, and loom (under cfg(loom)) for concurrency model checks. A harness = false benchmark target is registered so cargo bench resolves cleanly before the first benchmark lands.

Crate-root lint posture

src/lib.rs sets the non-negotiable posture from line one: #![forbid(unsafe_code)], #![deny(missing_docs)], no_std-ready behind the std feature, and doc_cfg annotations under docsrs. A single smoke test proves the crate compiles, links, and runs.

CI matrix and gates

.github/workflows/ci.yml runs three jobs:

• test — fmt --check, clippy --all-targets --all-features -D warnings, test --all-features, and doc with -D warnings, across Linux / macOS / Windows on both stable and the 1.85 MSRV.
• loom — the concurrency model-check slot, wired ahead of the first lock-free path.
• security — cargo audit against the RustSec advisory database and cargo deny check for advisories, bans, licenses, and sources.

.gitattributes normalises line endings to LF so the Windows runner does not fail fmt --check against the newline_style = "Unix" rule.

Breaking changes

None. This is the initial release.

Verification

Run on Windows x86_64, Rust stable 1.93.1; the same commands run in the CI matrix on Linux, macOS, and Windows across stable and MSRV 1.85:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo deny check
cargo audit

All green. At this tag: 1 unit test (smoke), 0 doctests; cargo deny reports advisories ok, bans ok, licenses ok, sources ok; cargo audit scans the dependency tree with zero advisories.

What's next

• v0.2.0 — Composition. The differentiators, front-loaded: hybrid limiters (a request must pass every constituent), layered scopes (global / per-key / per-endpoint), per-key state with a sharded map and inactive-key cleanup, and cost-aware acquisition (acquire_with_cost plus multi-dimensional acquire_costs). Exit criteria include a 10k-key lookup benchmarked under 1µs and an end-to-end multi-dimensional LLM example.

Installation

[dependencies]
throttle-net = "0.1"

MSRV: Rust 1.85.

Documentation

• README
• API Reference
• CHANGELOG

---

Changelog: CHANGELOG.md.