shed_machines 0.1.1

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

@@ -0,0 +1,101 @@
+//! Client-side adaptive throttling, so retries cannot amplify an outage.
+
+/// Each [`Budget::decay`] halves both counts.
+const DECAY_DIVISOR: u64 = 2;
+
+/// Denominator bias from the formula in Google's SRE book.
+const DENOMINATOR_BIAS: f64 = 1.0;
+
+/// Requests each accepted one entitles the client to, from Google's SRE book.
+pub const DEFAULT_MULTIPLIER: f64 = 2.0;
+
+/// Reports how much outbound work to drop before it leaves the process.
+///
+/// ```
+/// use shed_machines::Budget;
+///
+/// let mut budget = Budget::new(2.0);
+///
+/// // Everything is being accepted, so nothing is held back.
+/// for _ in 0..100 {
+///     budget.requested();
+///     budget.accepted();
+/// }
+/// assert_eq!(budget.shed_probability(), 0.0);
+///
+/// // The dependency stops accepting and the client keeps asking.
+/// for _ in 0..300 {
+///     budget.requested();
+/// }
+/// assert!(budget.shed_probability() > 0.0);
+/// ```
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Budget {
+    requests: u64,
+    accepts: u64,
+    multiplier: f64,
+}
+
+impl Budget {
+    /// `multiplier` is how many requests each accepted one entitles the client
+    /// to. See [`DEFAULT_MULTIPLIER`].
+    #[must_use]
+    pub const fn new(multiplier: f64) -> Self {
+        Self {
+            requests: 0,
+            accepts: 0,
+            multiplier,
+        }
+    }
+
+    pub const fn requested(&mut self) {
+        self.requests = self.requests.saturating_add(1);
+    }
+
+    pub const fn accepted(&mut self) {
+        self.accepts = self.accepts.saturating_add(1);
+    }
+
+    /// Halve both counts.
+    pub const fn decay(&mut self) {
+        self.requests /= DECAY_DIVISOR;
+        self.accepts /= DECAY_DIVISOR;
+    }
+
+    #[must_use]
+    pub const fn multiplier(&self) -> f64 {
+        self.multiplier
+    }
+
+    #[must_use]
+    pub const fn requests(&self) -> u64 {
+        self.requests
+    }
+
+    #[must_use]
+    pub const fn accepts(&self) -> u64 {
+        self.accepts
+    }
+
+    /// The fraction of outbound work to drop locally, in `0.0..1.0`.
+    #[must_use]
+    #[expect(clippy::cast_precision_loss)]
+    pub fn shed_probability(&self) -> f64 {
+        let requests = self.requests as f64;
+        let entitled = self.accepts as f64 * self.multiplier;
+        let excess = requests - entitled;
+        if excess <= 0.0 {
+            return 0.0;
+        }
+        excess / (requests + DENOMINATOR_BIAS)
+    }
+}
+
+impl Default for Budget {
+    fn default() -> Self {
+        Self::new(DEFAULT_MULTIPLIER)
+    }
+}
+
+#[cfg(test)]
+mod tests;

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

@@ -0,0 +1,122 @@
+//! Controlled delay: shed by how long work waited, not by how much there is.
+
+/// Acceptable waiting time, from the `CoDel` paper.
+pub const DEFAULT_TARGET_NS: u64 = 5_000_000;
+
+/// How long the target may be exceeded before shedding starts, from the paper.
+pub const DEFAULT_INTERVAL_NS: u64 = 100_000_000;
+
+/// What to do with a piece of work that has been waiting.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Verdict {
+    /// Run it.
+    Admit,
+    /// Drop it. The queue has been slow for longer than one interval.
+    Shed,
+}
+
+/// Sheds by how long work waited rather than by how much of it there is.
+///
+/// ```
+/// use shed_machines::{Codel, Verdict};
+///
+/// const MS: u64 = 1_000_000;
+/// let mut queue = Codel::new(5 * MS, 100 * MS);
+///
+/// // A burst above target is tolerated until the interval elapses.
+/// assert_eq!(queue.admit(20 * MS, 0), Verdict::Admit);
+/// assert_eq!(queue.admit(20 * MS, 50 * MS), Verdict::Admit);
+/// assert_eq!(queue.admit(20 * MS, 150 * MS), Verdict::Shed);
+///
+/// // Dropping back under target clears the state.
+/// assert_eq!(queue.admit(1 * MS, 200 * MS), Verdict::Admit);
+/// ```
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Codel {
+    target_ns: u64,
+    interval_ns: u64,
+    above_since_ns: Option<u64>,
+    next_shed_at_ns: u64,
+    shed_count: u64,
+    shedding: bool,
+}
+
+impl Codel {
+    /// See [`DEFAULT_TARGET_NS`] and [`DEFAULT_INTERVAL_NS`] for the values the
+    /// paper settled on.
+    #[must_use]
+    pub const fn new(target_ns: u64, interval_ns: u64) -> Self {
+        Self {
+            target_ns,
+            interval_ns,
+            above_since_ns: None,
+            next_shed_at_ns: 0,
+            shed_count: 0,
+            shedding: false,
+        }
+    }
+
+    #[must_use]
+    pub const fn target_ns(&self) -> u64 {
+        self.target_ns
+    }
+
+    #[must_use]
+    pub const fn interval_ns(&self) -> u64 {
+        self.interval_ns
+    }
+
+    #[must_use]
+    pub const fn shedding(&self) -> bool {
+        self.shedding
+    }
+
+    /// Successive sheds come faster, as the inverse square root of how many
+    /// have happened.
+    const fn shed_gap_ns(&self) -> u64 {
+        let count = if self.shed_count == 0 {
+            1
+        } else {
+            self.shed_count
+        };
+        let root = count.isqrt();
+        self.interval_ns / root
+    }
+
+    /// `sojourn_ns` is how long this work waited before being considered.
+    pub const fn admit(&mut self, sojourn_ns: u64, now_ns: u64) -> Verdict {
+        if sojourn_ns < self.target_ns {
+            self.above_since_ns = None;
+            self.shedding = false;
+            self.shed_count = 0;
+            return Verdict::Admit;
+        }
+
+        let Some(since) = self.above_since_ns else {
+            self.above_since_ns = Some(now_ns);
+            return Verdict::Admit;
+        };
+
+        if now_ns.saturating_sub(since) < self.interval_ns {
+            return Verdict::Admit;
+        }
+
+        if self.shedding && now_ns < self.next_shed_at_ns {
+            return Verdict::Admit;
+        }
+
+        self.shedding = true;
+        self.shed_count = self.shed_count.saturating_add(1);
+        self.next_shed_at_ns = now_ns.saturating_add(self.shed_gap_ns());
+        Verdict::Shed
+    }
+}
+
+impl Default for Codel {
+    fn default() -> Self {
+        Self::new(DEFAULT_TARGET_NS, DEFAULT_INTERVAL_NS)
+    }
+}
+
+#[cfg(test)]
+mod tests;

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

@@ -0,0 +1,118 @@
+#![cfg_attr(not(feature = "std"), no_std)]
+
+//! Adaptive concurrency limits and load shedding.
+//!
+//! A [`Controller`] watches completed calls and moves a concurrency limit. A
+//! [`Codel`] decides whether to admit work based on how long it waited. A
+//! [`Budget`] stops a client from amplifying an outage with retries.
+//!
+//! Nothing here enforces anything. These are the control loops; the caller owns
+//! the semaphore, the queue and the dice.
+
+/// Compiles and runs the README's examples as doctests.
+#[cfg(doctest)]
+#[doc = include_str!("../README.md")]
+struct ReadmeDoctests;
+
+pub mod aimd;
+pub mod budget;
+pub mod codel;
+pub mod vegas;
+
+pub use aimd::Aimd;
+pub use budget::Budget;
+pub use codel::{Codel, Verdict};
+pub use vegas::Vegas;
+
+/// How a completed call ended, from the limiter's point of view.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Outcome {
+    /// It finished. The round-trip time is a usable signal.
+    Ok,
+    /// It timed out, was rejected, or otherwise says the dependency is loaded.
+    Overload,
+}
+
+/// One completed call.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Sample {
+    /// Round-trip time in nanoseconds.
+    pub rtt_ns: u64,
+    /// Calls in flight when this one started, including itself.
+    pub in_flight: u32,
+    /// How it ended.
+    pub outcome: Outcome,
+}
+
+impl Sample {
+    #[must_use]
+    pub const fn ok(rtt_ns: u64, in_flight: u32) -> Self {
+        Self {
+            rtt_ns,
+            in_flight,
+            outcome: Outcome::Ok,
+        }
+    }
+
+    #[must_use]
+    pub const fn overload(rtt_ns: u64, in_flight: u32) -> Self {
+        Self {
+            rtt_ns,
+            in_flight,
+            outcome: Outcome::Overload,
+        }
+    }
+}
+
+/// A control loop over a concurrency limit.
+pub trait Controller {
+    /// Fold one completed call into the limit.
+    fn observe(&mut self, sample: Sample);
+
+    /// Calls allowed in flight right now.
+    fn limit(&self) -> u32;
+}
+
+/// The bounds every controller moves its limit within.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Bounds {
+    /// Never go below this. A limit of zero would wedge the caller shut.
+    pub min: u32,
+    /// Never go above this.
+    pub max: u32,
+}
+
+impl Bounds {
+    #[must_use]
+    pub const fn new(min: u32, max: u32) -> Self {
+        Self { min, max }
+    }
+
+    #[must_use]
+    pub const fn clamp(&self, limit: u32) -> u32 {
+        if limit < self.min {
+            self.min
+        } else if limit > self.max {
+            self.max
+        } else {
+            limit
+        }
+    }
+}
+
+/// A limit of zero would wedge the caller shut, so one is the lowest floor
+/// that still makes progress.
+pub const LOWEST_FLOOR: u32 = 1;
+
+/// Arbitrary, and deliberately so: there is no principled default ceiling for
+/// an unknown dependency. Set it from what the pool behind it can take.
+pub const DEFAULT_CEILING: u32 = 1_000;
+
+impl Default for Bounds {
+    fn default() -> Self {
+        Self::new(LOWEST_FLOOR, DEFAULT_CEILING)
+    }
+}
+
+#[cfg(test)]
+mod tests;

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

@@ -0,0 +1,113 @@
+//! TCP Vegas, applied to a concurrency limit instead of a window.
+
+use crate::{Bounds, Controller, Outcome, Sample};
+
+/// Grow while fewer than this many calls look queued. From the Vegas paper,
+/// which uses one to three packets; a concurrency limit tolerates the top of
+/// that range.
+pub const DEFAULT_ALPHA: u32 = 3;
+
+/// Shrink once more than this many look queued. Twice `DEFAULT_ALPHA`, so the
+/// hold band is wide enough that a single slow call does not trigger a cut.
+pub const DEFAULT_BETA: u32 = 6;
+
+/// Denominator of the fraction kept after an overload.
+pub const OVERLOAD_DIVISOR: u32 = 2;
+
+/// Calls added or removed per sample.
+const STEP: u32 = 1;
+
+/// Estimates how many calls are queued rather than working, from the gap
+/// between the current round-trip time and the best one ever seen, then steers
+/// the limit to keep that estimate inside a band.
+///
+/// ```
+/// use shed_machines::{Bounds, Controller, Sample, Vegas};
+///
+/// let mut control = Vegas::new(Bounds::new(1, 100), 10);
+///
+/// // Establishes the baseline, then grows while the queue estimate stays low.
+/// control.observe(Sample::ok(1_000_000, 10));
+/// assert_eq!(control.limit(), 11);
+///
+/// // Ten times the baseline latency means the queue is deep.
+/// control.observe(Sample::ok(10_000_000, 11));
+/// assert!(control.limit() < 11);
+/// ```
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Vegas {
+    bounds: Bounds,
+    limit: u32,
+    best_rtt_ns: u64,
+    alpha: u32,
+    beta: u32,
+}
+
+impl Vegas {
+    #[must_use]
+    pub const fn new(bounds: Bounds, limit: u32) -> Self {
+        Self {
+            bounds,
+            limit: bounds.clamp(limit),
+            best_rtt_ns: u64::MAX,
+            alpha: DEFAULT_ALPHA,
+            beta: DEFAULT_BETA,
+        }
+    }
+
+    /// Grow below `alpha` queued calls, shrink above `beta`, hold between.
+    #[must_use]
+    pub const fn band(mut self, alpha: u32, beta: u32) -> Self {
+        self.alpha = alpha;
+        self.beta = beta;
+        self
+    }
+
+    /// The best round-trip time seen so far, the stand-in for zero queueing.
+    #[must_use]
+    pub const fn best_rtt_ns(&self) -> Option<u64> {
+        if self.best_rtt_ns == u64::MAX {
+            None
+        } else {
+            Some(self.best_rtt_ns)
+        }
+    }
+
+    /// `limit * (rtt - best) / rtt`, the Vegas estimate of how many calls in
+    /// flight are waiting rather than working.
+    fn queued(&self, rtt_ns: u64) -> u64 {
+        if rtt_ns == 0 || self.best_rtt_ns >= rtt_ns {
+            return 0;
+        }
+        let excess = rtt_ns - self.best_rtt_ns;
+        let scaled = u128::from(self.limit) * u128::from(excess) / u128::from(rtt_ns);
+        u64::try_from(scaled).unwrap_or(u64::MAX)
+    }
+}
+
+impl Controller for Vegas {
+    fn observe(&mut self, sample: Sample) {
+        if sample.outcome == Outcome::Overload {
+            self.limit = self.bounds.clamp(self.limit / OVERLOAD_DIVISOR);
+            return;
+        }
+
+        self.best_rtt_ns = self.best_rtt_ns.min(sample.rtt_ns);
+        let queued = self.queued(sample.rtt_ns);
+
+        self.limit = if queued < u64::from(self.alpha) {
+            self.bounds.clamp(self.limit.saturating_add(STEP))
+        } else if queued > u64::from(self.beta) {
+            self.bounds.clamp(self.limit.saturating_sub(STEP))
+        } else {
+            self.limit
+        };
+    }
+
+    fn limit(&self) -> u32 {
+        self.limit
+    }
+}
+
+#[cfg(test)]
+mod tests;

data/ext/shed_machines_native/extconf.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'ffi/extconf'

data/ext/shed_machines_native/ffi/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "shed_machines_native"
+version = "0.1.1"
+edition.workspace = true
+rust-version.workspace = true
+authors = ["Abdelkader Boudih <oss@seuros.com>"]
+license = "MIT"
+description = "Ruby bindings for the shed-machines control laws"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[lints]
+workspace = true
+
+[dependencies]
+shed-machines = { workspace = true, features = ["std"] }
+magnus = { version = ">= 0.9.3", default-features = false, features = ["io"] }

data/ext/shed_machines_native/ffi/extconf.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'mkmf'
+require 'pathname'
+require 'rb_sys/mkmf'
+
+create_rust_makefile('shed_machines_native/shed_machines_native') do |r|
+  r.ext_dir = Pathname(__dir__).relative_path_from(Pathname(Dir.pwd)).to_s
+  r.profile = ENV.fetch('RB_SYS_CARGO_PROFILE', :release).to_sym
+end
+
+# rake-compiler builds from tmp/, where the generated relative manifest path no
+# longer resolves.
+makefile = File.join(Dir.pwd, 'Makefile')
+File.write(
+  makefile,
+  File.read(makefile).gsub(
+    /^RB_SYS_CARGO_MANIFEST_DIR \?=.*$/,
+    "RB_SYS_CARGO_MANIFEST_DIR ?= #{File.expand_path(__dir__)}"
+  )
+)

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

@@ -0,0 +1,50 @@
+//! `ShedMachines::Aimd`: grow by one per saturated success, cut on overload.
+
+use std::cell::RefCell;
+
+use magnus::scan_args::scan_args;
+use magnus::typed_data::Obj;
+use magnus::{Error, RHash, RModule, Ruby, Value, function, method, prelude::*};
+use shed_machines::aimd::{DEFAULT_BACKOFF_KEPT, DEFAULT_BACKOFF_OF};
+use shed_machines::{Aimd, Controller};
+
+use crate::{observe, opening};
+
+#[magnus::wrap(class = "ShedMachines::Aimd", free_immediately, size)]
+struct Wrapper(RefCell<Aimd>);
+
+impl Wrapper {
+    fn new(ruby: &Ruby, args: &[Value]) -> Result<Self, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let (bounds, limit, [kept, of]) = opening(ruby, args.keywords, ["kept", "of"])?;
+        let control = Aimd::new(bounds, limit).backoff(
+            kept.unwrap_or(DEFAULT_BACKOFF_KEPT),
+            of.unwrap_or(DEFAULT_BACKOFF_OF),
+        );
+        Ok(Self(RefCell::new(control)))
+    }
+
+    fn observe(ruby: &Ruby, rb_self: Obj<Self>, args: &[Value]) -> Result<Obj<Self>, Error> {
+        observe(ruby, &rb_self.0, args)?;
+        Ok(rb_self)
+    }
+
+    fn limit(&self) -> u32 {
+        self.0.borrow().limit()
+    }
+
+    fn inspect(&self) -> String {
+        format!("#<ShedMachines::Aimd limit={}>", self.limit())
+    }
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let class = module.define_class("Aimd", ruby.class_object())?;
+    class.const_set("DEFAULT_BACKOFF_KEPT", DEFAULT_BACKOFF_KEPT)?;
+    class.const_set("DEFAULT_BACKOFF_OF", DEFAULT_BACKOFF_OF)?;
+    class.define_singleton_method("new", function!(Wrapper::new, -1))?;
+    class.define_method("observe", method!(Wrapper::observe, -1))?;
+    class.define_method("limit", method!(Wrapper::limit, 0))?;
+    class.define_method("inspect", method!(Wrapper::inspect, 0))?;
+    Ok(())
+}

data/ext/shed_machines_native/ffi/src/budget.rs

@@ -0,0 +1,79 @@
+//! `ShedMachines::Budget`: how much outbound work to drop before it leaves.
+
+use std::cell::RefCell;
+
+use magnus::scan_args::{get_kwargs, scan_args};
+use magnus::typed_data::Obj;
+use magnus::{Error, RHash, RModule, Ruby, Value, function, method, prelude::*};
+use shed_machines::Budget;
+use shed_machines::budget::DEFAULT_MULTIPLIER;
+
+#[magnus::wrap(class = "ShedMachines::Budget", free_immediately, size)]
+struct Wrapper(RefCell<Budget>);
+
+impl Wrapper {
+    fn new(args: &[Value]) -> Result<Self, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let (multiplier,) =
+            get_kwargs::<_, (), (Option<f64>,), ()>(args.keywords, &[], &["multiplier"])?.optional;
+        let budget = Budget::new(multiplier.unwrap_or(DEFAULT_MULTIPLIER));
+        Ok(Self(RefCell::new(budget)))
+    }
+
+    fn requested(rb_self: Obj<Self>) -> Obj<Self> {
+        rb_self.0.borrow_mut().requested();
+        rb_self
+    }
+
+    fn accepted(rb_self: Obj<Self>) -> Obj<Self> {
+        rb_self.0.borrow_mut().accepted();
+        rb_self
+    }
+
+    /// Halves both counts, so the budget forgets an outage.
+    fn decay(rb_self: Obj<Self>) -> Obj<Self> {
+        rb_self.0.borrow_mut().decay();
+        rb_self
+    }
+
+    fn multiplier(&self) -> f64 {
+        self.0.borrow().multiplier()
+    }
+
+    fn requests(&self) -> u64 {
+        self.0.borrow().requests()
+    }
+
+    fn accepts(&self) -> u64 {
+        self.0.borrow().accepts()
+    }
+
+    /// The fraction of outbound work to drop locally, in `0.0..1.0`.
+    fn shed_probability(&self) -> f64 {
+        self.0.borrow().shed_probability()
+    }
+
+    fn inspect(&self) -> String {
+        format!(
+            "#<ShedMachines::Budget requests={} accepts={} shed_probability={}>",
+            self.requests(),
+            self.accepts(),
+            self.shed_probability()
+        )
+    }
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let class = module.define_class("Budget", ruby.class_object())?;
+    class.const_set("DEFAULT_MULTIPLIER", DEFAULT_MULTIPLIER)?;
+    class.define_singleton_method("new", function!(Wrapper::new, -1))?;
+    class.define_method("requested", method!(Wrapper::requested, 0))?;
+    class.define_method("accepted", method!(Wrapper::accepted, 0))?;
+    class.define_method("decay", method!(Wrapper::decay, 0))?;
+    class.define_method("multiplier", method!(Wrapper::multiplier, 0))?;
+    class.define_method("requests", method!(Wrapper::requests, 0))?;
+    class.define_method("accepts", method!(Wrapper::accepts, 0))?;
+    class.define_method("shed_probability", method!(Wrapper::shed_probability, 0))?;
+    class.define_method("inspect", method!(Wrapper::inspect, 0))?;
+    Ok(())
+}