shed_machines 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 061e0fb85399ec23ed73e673a6ca55d406b3c1a775a6c3fade1a84e836bcb615
+  data.tar.gz: e02e410d9a5909bf71101a5d5cbe80cfc70e1aa6a42e0a6c3eb6509115078cb5
+SHA512:
+  metadata.gz: 274e603824e19a217e2762cec86d6c43b1756ac955b753afb1061b9b5ed4dcd96a745b92c10c96fe6b80d5221fb95be4d3b109ce652d857d76d2557d096c0b78
+  data.tar.gz: 6e928923121a47f7c38f963c3f5c09b4e77c408c7b7a6d122f18b1587e54983949c2067cd2d73b3e4d16784bc51b03ae2a5a7bd29967f4685ec6dc40366781ab

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## [0.1.1](https://github.com/seuros/shed_machines/compare/shed_machines-v0.1.0...shed_machines/v0.1.1) (2026-11-01)
+
+
+### Features
+
+* adaptive concurrency limits and load shedding ([e07f0dc](https://github.com/seuros/shed_machines/commit/e07f0dca6cc3dc65a49757d5eda0b96256310c61))
+* pass a rubygems OTP through the environment ([8a4d15b](https://github.com/seuros/shed_machines/commit/8a4d15bc46fed686dd67da5566b8d5c252de617c))
+* Ruby gem and magnus FFI for the control loops ([b323351](https://github.com/seuros/shed_machines/commit/b323351d11a2ee01782e93cafe769a24e4485ed0))
+
+
+### Bug Fixes
+
+* a configured CoDel duration goes through the same check as an observed one ([c424040](https://github.com/seuros/shed_machines/commit/c424040c95e419f88d20f06d19cd07bf5fba30f5))
+* a source install can build, and a failed gem push fails the release ([4975e7f](https://github.com/seuros/shed_machines/commit/4975e7fcc39820ec681d79e8d0e3213878c61487))
+* AIMD divided by zero, and both controllers saturated before dividing ([67006bd](https://github.com/seuros/shed_machines/commit/67006bdad51f9caef02594f042f2b5a5c7d34735))
+* avoid re-entrant borrow and u32 clipping in shed control ([d4a1b09](https://github.com/seuros/shed_machines/commit/d4a1b0950e6de32bb2756f5ef183e649ff04d829))
+* collect the built gems whatever depth the download puts them at ([7ffc2db](https://github.com/seuros/shed_machines/commit/7ffc2db96f97a1b30b3992b16d30dc45fd43f216))
+* refuse a fractional call count instead of truncating it to zero ([869c3d8](https://github.com/seuros/shed_machines/commit/869c3d8988ae4e1be5924899466522053fa47981))
+* reject durations and bounds the arithmetic cannot survive ([37edc6f](https://github.com/seuros/shed_machines/commit/37edc6f8849e9fff6192955cc41e910a930b3fcf))
+* ship the core's test files so the packaged crate builds ([9a3e00d](https://github.com/seuros/shed_machines/commit/9a3e00dffffff31bbebfbaf6e9c57e2d21cea43e))
+* the release tag carries the gem name, and the gate uses the aggregate output ([f0937ad](https://github.com/seuros/shed_machines/commit/f0937ad7ecbab770aaa81378c1035f80442291b7))
+
+## 0.1.0
+
+- Initial release.
+- `ShedMachines::Aimd`: additive increase per saturated success, multiplicative
+  decrease on overload, with a configurable `kept / of` backoff fraction.
+- `ShedMachines::Vegas`: TCP Vegas applied to a concurrency limit, steering by
+  the queue estimate drawn from the gap between current and best round-trip
+  time, with a configurable `alpha`/`beta` band.
+- `ShedMachines::Codel`: controlled delay, shedding queued work by how long it
+  waited once the wait stays above target for a full interval, with sheds that
+  come faster as the inverse square root of how many have happened.
+- `ShedMachines::Budget`: client-side adaptive throttling, reporting the
+  fraction of the next retry wave to drop rather than making the decision.
+- Durations cross the Ruby boundary as seconds in Floats and are converted once
+  to nanoseconds; the control laws themselves are integer-only.
+- `shed-machines` core crate: the four control laws in `no_std` Rust with zero
+  dependencies. Builds and lints clean on bare metal.
+- RBS signatures for the whole public API.

data/Cargo.lock

@@ -0,0 +1,286 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "bindgen"
+version = "0.72.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
+dependencies = [
+ "bitflags",
+ "cexpr",
+ "clang-sys",
+ "itertools",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "rustc-hash",
+ "shlex",
+ "syn",
+]
+
+[[package]]
+name = "bitflags"
+version = "2.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
+
+[[package]]
+name = "cexpr"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
+dependencies = [
+ "nom",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
+
+[[package]]
+name = "clang-sys"
+version = "1.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "157a8ba7b480713b56f4c09fd13fc3e0a22a5dfab8097ba61cbc5feef950788a"
+dependencies = [
+ "glob",
+ "libc",
+ "libloading",
+]
+
+[[package]]
+name = "either"
+version = "1.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0e9c71c2167ca323c882b99918929403426e2373ea17242ff5653e0d5e1058be"
+
+[[package]]
+name = "glob"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
+
+[[package]]
+name = "itertools"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "lazy_static"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "20870f649af7073d53e38067b2a84312175d56ea15217e1b15bc83506ec50afb"
+
+[[package]]
+name = "libc"
+version = "0.2.191"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
+
+[[package]]
+name = "libloading"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
+dependencies = [
+ "cfg-if",
+ "windows-link",
+]
+
+[[package]]
+name = "magnus"
+version = "0.9.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40ef424404d166cbb71c8b8d19c9c589c748c4547c1afa1928c5504299f6c713"
+dependencies = [
+ "magnus-macros",
+ "rb-sys",
+ "rb-sys-env",
+ "seq-macro",
+]
+
+[[package]]
+name = "magnus-macros"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9dafde2eeb66f090e0f326112323eb8324b12cb32b5d1210e541d3df6b0ce77e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "minimal-lexical"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+
+[[package]]
+name = "nom"
+version = "7.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+dependencies = [
+ "memchr",
+ "minimal-lexical",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rb-sys"
+version = "0.9.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "02faf625bb10ba893e3ae620f19c9fb1b5f8fcae0fe4eb86bb3f2230fad75edb"
+dependencies = [
+ "rb-sys-build",
+]
+
+[[package]]
+name = "rb-sys-build"
+version = "0.9.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05be6f9c86fe5482808162826f6c047d093b3670582296c770de1d94f8066694"
+dependencies = [
+ "bindgen",
+ "lazy_static",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "shell-words",
+ "syn",
+]
+
+[[package]]
+name = "rb-sys-env"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cca7ad6a7e21e72151d56fe2495a259b5670e204c3adac41ee7ef676ea08117a"
+
+[[package]]
+name = "regex"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
+[[package]]
+name = "seq-macro"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
+
+[[package]]
+name = "shed-machines"
+version = "0.2.0"
+
+[[package]]
+name = "shed_machines_native"
+version = "0.1.1"
+dependencies = [
+ "magnus",
+ "shed-machines",
+]
+
+[[package]]
+name = "shell-words"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc6fe69c597f9c37bfeeeeeb33da3530379845f10be461a66d16d03eca2ded77"
+
+[[package]]
+name = "shlex"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"

data/Cargo.toml

@@ -0,0 +1,24 @@
+[workspace]
+members = ["ext/shed_machines_native/core", "ext/shed_machines_native/ffi"]
+resolver = "3"
+
+[workspace.package]
+edition = "2024"
+rust-version = "1.99"
+
+[workspace.dependencies]
+shed-machines = { path = "ext/shed_machines_native/core" }
+
+[workspace.lints.rust]
+unsafe_code = "forbid"
+unused_must_use = "warn"
+
+[workspace.lints.clippy]
+all = { level = "warn", priority = -1 }
+pedantic = { level = "warn", priority = -1 }
+nursery = { level = "warn", priority = -1 }
+expect_used = "deny"
+unwrap_used = "deny"
+uninlined_format_args = "deny"
+needless_borrow = "deny"
+redundant_clone = "deny"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Abdelkader Boudih
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,174 @@
+# ShedMachines 🌊
+
+> **Adaptive concurrency limits and load shedding.** The escort that reads the
+> convoy's own telemetry and says how wide the lane is, right now.
+
+A fixed bulkhead is a guess that is wrong at every load except the one it was
+tuned for. **AMS Jacobson** does not carry a tuned number. These four control
+loops read what completed calls report and answer one question each: how many
+calls may be in flight, whether this queued piece of work is still worth
+running, and how much of the next retry wave to drop before it leaves the
+process.
+
+---
+
+## 🚀 Launch Sequence
+
+```bash
+# Add to your ship's Gemfile
+gem 'shed_machines'
+```
+
+Requires **Ruby 4.0+** and a Rust toolchain, or a platform gem.
+
+---
+
+## 🎯 Mission Brief
+
+```ruby
+require 'shed_machines'
+
+control = ShedMachines::Vegas.new(limit: 10, min: 1, max: 200)
+
+control.observe(rtt: 0.004, in_flight: 10, outcome: :ok)
+control.limit                                              # => 11
+
+control.observe(rtt: 0.040, in_flight: 11, outcome: :ok)
+control.limit                                              # => 10
+```
+
+The escort advises, it does not fire. Nothing here enforces anything. The
+caller owns the semaphore, the queue and the dice.
+
+---
+
+## 🔩 The Native Extension Is Required
+
+There is no pure-Ruby fallback and no switch to turn one on. `require
+'shed_machines'` loads the extension, and fails if it is not there. A control
+law with two implementations is a control law with two behaviours, and the whole
+point of these four is that they are the same arithmetic everywhere: the gem is
+a binding to the `shed-machines` crate in `ext/shed_machines_native/core`, which
+is `no_std` with zero dependencies and also runs on bare metal. It needs Ruby
+4.0 and a Rust toolchain, or a platform gem.
+
+---
+
+## 🎚️ Moving a Concurrency Limit
+
+`Aimd` grows the limit by one whenever a saturated call succeeds, and keeps
+three quarters of it on any overload. It needs no latency signal.
+
+```ruby
+control = ShedMachines::Aimd.new(limit: 10, min: 1, max: 100)
+
+control.observe(rtt: 0.004, in_flight: 10, outcome: :ok)        # saturated: grows
+control.limit                                                   # => 11
+
+control.observe(rtt: 0.004, in_flight: 11, outcome: :overload)
+control.limit                                                   # => 8
+```
+
+`Vegas` infers queue depth from the gap between the current round-trip time and
+the best one it has seen, because latency alone cannot tell a slow dependency
+from a deep queue. It grows while fewer than `alpha` calls look queued, shrinks
+above `beta`, and holds in between.
+
+```ruby
+control = ShedMachines::Vegas.new(limit: 10, min: 1, max: 200, alpha: 3, beta: 6)
+control.best_rtt     # => nil, until the first completed call
+```
+
+Both take `outcome: :ok` or `outcome: :overload`, where overload means the call
+timed out, was rejected, or otherwise says the dependency is loaded. Anything
+else raises `ArgumentError`. Both clamp a starting limit into `min..max`, which
+default to `LOWEST_FLOOR` and `DEFAULT_CEILING`.
+
+---
+
+## ⏱️ Shedding by Waiting Time
+
+Queue length is the wrong signal, since a fast queue can be long and a stalled
+one short. `Codel` watches how long work waited and sheds only once that stays
+above target for a full interval, so a burst passes through and a standing queue
+does not.
+
+```ruby
+queue = ShedMachines::Codel.new                 # 5 ms target, 100 ms interval
+
+queue.admit(sojourn: 0.020, now: 0.000)         # => :admit, the burst is tolerated
+queue.admit(sojourn: 0.020, now: 0.150)         # => :shed, it is a standing queue
+queue.shedding?                                 # => true
+queue.admit(sojourn: 0.001, now: 0.200)         # => :admit, and the state clears
+```
+
+Successive sheds come faster, as the inverse square root of how many have
+happened, so the control law converges instead of oscillating.
+
+---
+
+## 🌀 Not Amplifying an Outage
+
+A client that keeps retrying a failing dependency multiplies the load that broke
+it. `Budget` tracks what the client asked for against what was accepted and
+reports what fraction of the next wave to drop.
+
+```ruby
+budget = ShedMachines::Budget.new               # each accept earns 2 requests
+
+100.times { budget.requested.accepted }
+budget.shed_probability                         # => 0.0
+
+300.times { budget.requested }
+budget.shed_probability                         # => 0.4987...
+
+budget.decay                                    # halves both counts
+```
+
+`shed_probability` is a fraction, not a decision, so nothing here needs a random
+number generator.
+
+---
+
+## 📐 Seconds In, Nanoseconds Inside
+
+Every duration crosses this boundary as seconds in a `Float`, and is converted
+once to nanoseconds. The control laws are integer-only on purpose: a limit, a
+queue estimate and a backoff are counts, and counting in floats invites a
+limiter that is 10.999999 calls wide.
+
+---
+
+## 📊 Constants on the Instrument Panel
+
+The Ruby constants mirror the crate's, with the same names and values.
+
+| Constant                           | Value       |
+| ---------------------------------- | ----------- |
+| `ShedMachines::LOWEST_FLOOR`       | 1           |
+| `ShedMachines::DEFAULT_CEILING`    | 1000        |
+| `Aimd::DEFAULT_BACKOFF_KEPT`       | 3           |
+| `Aimd::DEFAULT_BACKOFF_OF`         | 4           |
+| `Vegas::DEFAULT_ALPHA`             | 3           |
+| `Vegas::DEFAULT_BETA`              | 6           |
+| `Vegas::OVERLOAD_DIVISOR`          | 2           |
+| `Codel::DEFAULT_TARGET_NS`         | 5_000_000   |
+| `Codel::DEFAULT_INTERVAL_NS`       | 100_000_000 |
+| `Budget::DEFAULT_MULTIPLIER`       | 2.0         |
+
+---
+
+## 📡 Credits
+
+**AMS Jacobson**, NCC-2012, *Jacobson*-class escort.
+
+Named for Kathleen Nichols and Van Jacobson, *Controlling Queue Delay* (2012),
+the paper that introduced controlled delay, CoDel, and argued that a queue
+should be judged by how long work waits in it rather than by how much work is
+in it.
+
+---
+
+## License
+
+MIT.

data/ext/shed_machines_native/core/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "shed-machines"
+version = "0.2.0"
+edition.workspace = true
+rust-version.workspace = true
+authors = ["Abdelkader Boudih <oss@seuros.com>"]
+license = "MIT"
+description = "Adaptive concurrency limits and load shedding - AIMD, Vegas, CoDel and retry budgets, no_std with zero dependencies"
+repository = "https://github.com/seuros/shed_machines"
+keywords = ["load-shedding", "concurrency", "codel", "backpressure", "no-std"]
+categories = ["no-std", "concurrency"]
+readme = "README.md"
+
+[lib]
+name = "shed_machines"
+crate-type = ["lib"]
+
+[features]
+default = ["std"]
+std = ["alloc"]
+alloc = []
+
+[lints]
+workspace = true

data/ext/shed_machines_native/core/src/aimd.rs

@@ -0,0 +1,89 @@
+//! Additive increase, multiplicative decrease.
+
+use crate::{Bounds, Controller, Outcome, Sample};
+
+/// Numerator of the fraction kept after an overload.
+pub const DEFAULT_BACKOFF_KEPT: u32 = 3;
+
+/// Denominator of the fraction kept after an overload. Three quarters backs
+/// off faster than a dependency usually recovers, without the halving that
+/// makes a limit oscillate.
+pub const DEFAULT_BACKOFF_OF: u32 = 4;
+
+/// Calls added per saturated success. One is what makes this additive.
+const INCREASE: u32 = 1;
+
+/// Grows the limit by one whenever a saturated call succeeds, and cuts it by a
+/// factor on any overload. The limit only grows while the caller is actually
+/// using it, so an idle client does not drift upward.
+///
+/// ```
+/// use shed_machines::{Aimd, Bounds, Controller, Sample};
+///
+/// let mut control = Aimd::new(Bounds::new(1, 100), 10);
+///
+/// control.observe(Sample::ok(1_000, 10));
+/// assert_eq!(control.limit(), 11);
+///
+/// control.observe(Sample::overload(1_000, 11));
+/// assert_eq!(control.limit(), 8);
+/// ```
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Aimd {
+    bounds: Bounds,
+    limit: u32,
+    kept: u32,
+    of: u32,
+}
+
+impl Aimd {
+    #[must_use]
+    pub const fn new(bounds: Bounds, limit: u32) -> Self {
+        Self {
+            bounds,
+            limit: bounds.clamp(limit),
+            kept: DEFAULT_BACKOFF_KEPT,
+            of: DEFAULT_BACKOFF_OF,
+        }
+    }
+
+    /// Keep `kept / of` of the limit after an overload. See
+    /// [`DEFAULT_BACKOFF_KEPT`].
+    #[must_use]
+    pub const fn backoff(mut self, kept: u32, of: u32) -> Self {
+        self.kept = kept;
+        self.of = of;
+        self
+    }
+}
+
+impl Aimd {
+    /// A zero denominator keeps the limit rather than dividing by zero, and the
+    /// product is widened so a representable quotient is not lost to saturation.
+    fn kept_limit(&self) -> u32 {
+        if self.of == 0 {
+            return self.limit;
+        }
+        let scaled = u64::from(self.limit) * u64::from(self.kept) / u64::from(self.of);
+        u32::try_from(scaled).unwrap_or(u32::MAX)
+    }
+}
+
+impl Controller for Aimd {
+    fn observe(&mut self, sample: Sample) {
+        self.limit = match sample.outcome {
+            Outcome::Overload => self.bounds.clamp(self.kept_limit()),
+            Outcome::Ok if sample.in_flight >= self.limit => {
+                self.bounds.clamp(self.limit.saturating_add(INCREASE))
+            }
+            Outcome::Ok => self.limit,
+        };
+    }
+
+    fn limit(&self) -> u32 {
+        self.limit
+    }
+}
+
+#[cfg(test)]
+mod tests;