shed_machines 0.1.1

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

@@ -0,0 +1,80 @@
+//! `ShedMachines::Codel`: shed by how long work waited.
+
+use std::cell::RefCell;
+
+use magnus::scan_args::{get_kwargs, scan_args};
+use magnus::{Error, RHash, RModule, Ruby, Symbol, Value, function, method, prelude::*};
+use shed_machines::Codel;
+use shed_machines::codel::{DEFAULT_INTERVAL_NS, DEFAULT_TARGET_NS};
+
+use crate::{duration, to_seconds, verdict};
+
+#[magnus::wrap(class = "ShedMachines::Codel", free_immediately, size)]
+struct Wrapper(RefCell<Codel>);
+
+impl Wrapper {
+    fn new(ruby: &Ruby, args: &[Value]) -> Result<Self, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let (target, interval) = get_kwargs::<_, (), (Option<f64>, Option<f64>), ()>(
+            args.keywords,
+            &[],
+            &["target", "interval"],
+        )?
+        .optional;
+        let queue = Codel::new(
+            target.map_or(Ok(DEFAULT_TARGET_NS), |seconds| {
+                duration(ruby, "target", seconds)
+            })?,
+            interval.map_or(Ok(DEFAULT_INTERVAL_NS), |seconds| {
+                duration(ruby, "interval", seconds)
+            })?,
+        );
+        Ok(Self(RefCell::new(queue)))
+    }
+
+    /// `sojourn:` is how long this work waited, `now:` the current time, both
+    /// in seconds. Answers `:admit` or `:shed`.
+    fn admit(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<Symbol, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let (sojourn, now) =
+            get_kwargs::<_, (f64, f64), (), ()>(args.keywords, &["sojourn", "now"], &[])?.required;
+        let sojourn_ns = duration(ruby, "sojourn", sojourn)?;
+        let now_ns = duration(ruby, "now", now)?;
+        let answer = rb_self.0.borrow_mut().admit(sojourn_ns, now_ns);
+        Ok(verdict(ruby, answer))
+    }
+
+    /// The acceptable waiting time, in seconds.
+    fn interval(&self) -> f64 {
+        to_seconds(self.0.borrow().interval_ns())
+    }
+
+    fn target(&self) -> f64 {
+        to_seconds(self.0.borrow().target_ns())
+    }
+
+    fn shedding(&self) -> bool {
+        self.0.borrow().shedding()
+    }
+
+    fn inspect(&self) -> String {
+        format!(
+            "#<ShedMachines::Codel target={} shedding={}>",
+            self.target(),
+            self.shedding()
+        )
+    }
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let class = module.define_class("Codel", ruby.class_object())?;
+    class.const_set("DEFAULT_TARGET_NS", DEFAULT_TARGET_NS)?;
+    class.const_set("DEFAULT_INTERVAL_NS", DEFAULT_INTERVAL_NS)?;
+    class.define_singleton_method("new", function!(Wrapper::new, -1))?;
+    class.define_method("admit", method!(Wrapper::admit, -1))?;
+    class.define_method("target", method!(Wrapper::target, 0))?;
+    class.define_method("interval", method!(Wrapper::interval, 0))?;
+    class.define_method("shedding?", method!(Wrapper::shedding, 0))?;
+    class.define_method("inspect", method!(Wrapper::inspect, 0))?;
+    Ok(())
+}

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

@@ -0,0 +1,161 @@
+//! Ruby bindings for the `shed-machines` control laws.
+//!
+//! Durations cross this boundary as seconds and move through the control laws
+//! as nanoseconds. [`to_ns`] and [`to_seconds`] are the only places either
+//! representation changes.
+
+#![allow(clippy::needless_pass_by_value)]
+
+mod aimd;
+mod budget;
+mod codel;
+mod vegas;
+
+use std::cell::RefCell;
+
+use magnus::scan_args::{get_kwargs, scan_args};
+use magnus::{Error, Integer, RHash, Ruby, Symbol, TryConvert, Value, prelude::*};
+use shed_machines::{Bounds, Controller, DEFAULT_CEILING, LOWEST_FLOOR, Outcome, Sample, Verdict};
+
+/// Nanoseconds in a second.
+pub(crate) const NS_PER_SECOND: u32 = 1_000_000_000;
+
+#[expect(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
+pub(crate) fn to_ns(seconds: f64) -> u64 {
+    (seconds * f64::from(NS_PER_SECOND)).round() as u64
+}
+
+#[expect(clippy::cast_precision_loss)]
+pub(crate) fn to_seconds(nanoseconds: u64) -> f64 {
+    nanoseconds as f64 / f64::from(NS_PER_SECOND)
+}
+
+/// A whole number of things: a limit, a bound, a call count, a ratio's two
+/// sides.
+///
+/// magnus reads an integer through Ruby's `NUM2*` family, which truncates a
+/// `Float` towards zero instead of refusing it, so an argument that counts
+/// rather than measures is read as one of these and anything but an `Integer`
+/// is turned away. An `Integer` outside the target width still comes back as
+/// the `RangeError` magnus raises for it. Seconds stay [`duration`]'s.
+pub(crate) struct Whole<T>(pub(crate) T);
+
+impl<T: TryConvert> TryConvert for Whole<T> {
+    fn try_convert(value: Value) -> Result<Self, Error> {
+        if Integer::from_value(value).is_none() {
+            return Err(not_whole(value));
+        }
+        T::try_convert(value).map(Self)
+    }
+}
+
+fn not_whole(value: Value) -> Error {
+    let ruby = Ruby::get_with(value);
+    Error::new(
+        ruby.exception_type_error(),
+        format!(
+            "no implicit conversion of {} into Integer: {}",
+            value.class(),
+            value.inspect()
+        ),
+    )
+}
+
+/// Seconds as nanoseconds, rejecting a negative or non-finite duration.
+pub(crate) fn duration(ruby: &Ruby, name: &str, seconds: f64) -> Result<u64, Error> {
+    if !seconds.is_finite() || seconds < 0.0 {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            format!("{name} must be finite and not negative, got {seconds}"),
+        ));
+    }
+    Ok(to_ns(seconds))
+}
+
+/// The keywords every controller is opened with: a starting `limit:`, the
+/// `min:` and `max:` it moves within, and the two values it tunes itself with.
+pub(crate) fn opening(
+    ruby: &Ruby,
+    keywords: RHash,
+    tuning: [&str; 2],
+) -> Result<(Bounds, u32, [Option<u32>; 2]), Error> {
+    let keywords = get_kwargs::<
+        _,
+        (Whole<u32>,),
+        (
+            Option<Whole<u32>>,
+            Option<Whole<u32>>,
+            Option<Whole<u32>>,
+            Option<Whole<u32>>,
+        ),
+        (),
+    >(keywords, &["limit"], &["min", "max", tuning[0], tuning[1]])?;
+    let (Whole(limit),) = keywords.required;
+    let (min, max, first, second) = keywords.optional;
+    let floor = min.map_or(LOWEST_FLOOR, |Whole(min)| min);
+    let ceiling = max.map_or(DEFAULT_CEILING, |Whole(max)| max);
+    if floor < LOWEST_FLOOR || ceiling < floor {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            format!(
+                "min must be at least {LOWEST_FLOOR} and max at least min, got {floor}..{ceiling}"
+            ),
+        ));
+    }
+    let tuning = [first, second].map(|given| given.map(|Whole(value)| value));
+    Ok((Bounds::new(floor, ceiling), limit, tuning))
+}
+
+/// Folds one completed call, given as `rtt:` in seconds, `in_flight:` and
+/// `outcome:`, into a controller.
+pub(crate) fn observe<C: Controller>(
+    ruby: &Ruby,
+    control: &RefCell<C>,
+    args: &[Value],
+) -> Result<(), Error> {
+    let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+    let (rtt, Whole(in_flight), outcome) = get_kwargs::<_, (f64, Whole<u32>, Value), (), ()>(
+        args.keywords,
+        &["rtt", "in_flight", "outcome"],
+        &[],
+    )?
+    .required;
+    let sample = Sample {
+        rtt_ns: duration(ruby, "rtt", rtt)?,
+        in_flight,
+        outcome: self::outcome(ruby, outcome)?,
+    };
+    control.borrow_mut().observe(sample);
+    Ok(())
+}
+
+fn outcome(ruby: &Ruby, value: Value) -> Result<Outcome, Error> {
+    let name = Symbol::from_value(value).and_then(|symbol| symbol.name().ok());
+    match name.as_deref() {
+        Some("ok") => Ok(Outcome::Ok),
+        Some("overload") => Ok(Outcome::Overload),
+        _ => Err(Error::new(
+            ruby.exception_arg_error(),
+            format!("unknown outcome: {}", value.inspect()),
+        )),
+    }
+}
+
+pub(crate) fn verdict(ruby: &Ruby, verdict: Verdict) -> Symbol {
+    match verdict {
+        Verdict::Admit => ruby.to_symbol("admit"),
+        Verdict::Shed => ruby.to_symbol("shed"),
+    }
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("ShedMachines")?;
+    module.const_set("NS_PER_SECOND", NS_PER_SECOND)?;
+    module.const_set("LOWEST_FLOOR", LOWEST_FLOOR)?;
+    module.const_set("DEFAULT_CEILING", DEFAULT_CEILING)?;
+    aimd::define(ruby, module)?;
+    vegas::define(ruby, module)?;
+    codel::define(ruby, module)?;
+    budget::define(ruby, module)
+}

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

@@ -0,0 +1,61 @@
+//! `ShedMachines::Vegas`: steer the limit by how many calls look queued.
+
+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::vegas::{DEFAULT_ALPHA, DEFAULT_BETA, OVERLOAD_DIVISOR};
+use shed_machines::{Controller, Vegas};
+
+use crate::{observe, opening, to_seconds};
+
+#[magnus::wrap(class = "ShedMachines::Vegas", free_immediately, size)]
+struct Wrapper(RefCell<Vegas>);
+
+impl Wrapper {
+    fn new(ruby: &Ruby, args: &[Value]) -> Result<Self, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let (bounds, limit, [alpha, beta]) = opening(ruby, args.keywords, ["alpha", "beta"])?;
+        let control = Vegas::new(bounds, limit)
+            .band(alpha.unwrap_or(DEFAULT_ALPHA), beta.unwrap_or(DEFAULT_BETA));
+        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()
+    }
+
+    /// The best round-trip time seen so far, in seconds.
+    fn best_rtt(&self) -> Option<f64> {
+        self.0.borrow().best_rtt_ns().map(to_seconds)
+    }
+
+    fn inspect(&self) -> String {
+        let best_rtt = self
+            .best_rtt()
+            .map_or_else(|| "nil".to_owned(), |rtt| rtt.to_string());
+        format!(
+            "#<ShedMachines::Vegas limit={} best_rtt={best_rtt}>",
+            self.limit()
+        )
+    }
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let class = module.define_class("Vegas", ruby.class_object())?;
+    class.const_set("DEFAULT_ALPHA", DEFAULT_ALPHA)?;
+    class.const_set("DEFAULT_BETA", DEFAULT_BETA)?;
+    class.const_set("OVERLOAD_DIVISOR", OVERLOAD_DIVISOR)?;
+    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("best_rtt", method!(Wrapper::best_rtt, 0))?;
+    class.define_method("inspect", method!(Wrapper::inspect, 0))?;
+    Ok(())
+}

data/lib/shed_machines/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ShedMachines
+  VERSION = '0.1.1'
+end

data/lib/shed_machines.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'shed_machines/version'
+
+# Aimd, Vegas, Codel and Budget are defined by the native extension; there is no
+# pure-Ruby implementation to fall back to.
+require 'shed_machines_native/shed_machines_native'

data/sig/shed_machines.rbs

@@ -0,0 +1,131 @@
+# Adaptive concurrency limits and load shedding. Every class here is defined by
+# the native extension, which binds the `shed-machines` crate.
+#
+# Nothing here enforces anything: these are the control loops, and the caller
+# owns the semaphore, the queue and the dice.
+module ShedMachines
+  VERSION: String
+
+  # Nanoseconds in a second. Durations cross this boundary as seconds and move
+  # through the control laws as nanoseconds.
+  NS_PER_SECOND: Integer
+
+  # A limit of zero would wedge the caller shut, so one is the lowest floor that
+  # still makes progress.
+  LOWEST_FLOOR: Integer
+
+  # Arbitrary, and deliberately so: there is no principled default ceiling for
+  # an unknown dependency. Set it from what the pool behind it can take.
+  DEFAULT_CEILING: Integer
+
+  # How a completed call ended, from the limiter's point of view. `:overload`
+  # means it timed out, was rejected, or otherwise says the dependency is
+  # loaded. Anything else raises `ArgumentError`.
+  type outcome = :ok | :overload
+
+  # What to do with a piece of work that has been waiting.
+  type verdict = :admit | :shed
+
+  # Additive increase, multiplicative decrease: grows the limit by one whenever
+  # a saturated call succeeds, and keeps `kept / of` of it on any overload.
+  class Aimd
+    DEFAULT_BACKOFF_KEPT: Integer
+    DEFAULT_BACKOFF_OF: Integer
+
+    # `limit` outside `min..max` is pulled inside it.
+    def self.new: (
+      limit: Integer,
+      ?min: Integer,
+      ?max: Integer,
+      ?kept: Integer,
+      ?of: Integer
+    ) -> instance
+
+    # Folds one completed call into the limit. `rtt` is in seconds, `in_flight`
+    # counts the calls in flight when this one started, including itself.
+    def observe: (rtt: Float, in_flight: Integer, outcome: outcome) -> self
+
+    # Calls allowed in flight right now.
+    def limit: () -> Integer
+
+    def inspect: () -> String
+  end
+
+  # TCP Vegas applied to a concurrency limit: estimates how many calls are
+  # queued rather than working from the gap between the current round-trip time
+  # and the best one seen, then steers the limit to keep that estimate between
+  # `alpha` and `beta`.
+  class Vegas
+    DEFAULT_ALPHA: Integer
+    DEFAULT_BETA: Integer
+    OVERLOAD_DIVISOR: Integer
+
+    def self.new: (
+      limit: Integer,
+      ?min: Integer,
+      ?max: Integer,
+      ?alpha: Integer,
+      ?beta: Integer
+    ) -> instance
+
+    def observe: (rtt: Float, in_flight: Integer, outcome: outcome) -> self
+
+    def limit: () -> Integer
+
+    # The best round-trip time seen so far in seconds, the stand-in for zero
+    # queueing. `nil` until the first completed call.
+    def best_rtt: () -> Float?
+
+    def inspect: () -> String
+  end
+
+  # Controlled delay: sheds by how long work waited rather than by how much of
+  # it there is, and only once the wait stays above target for a full interval.
+  class Codel
+    DEFAULT_TARGET_NS: Integer
+    DEFAULT_INTERVAL_NS: Integer
+
+    # Both in seconds, defaulting to the values the CoDel paper settled on.
+    def self.new: (?target: Float, ?interval: Float) -> instance
+
+    # `sojourn` is how long this work waited before being considered, `now` is
+    # the current time, both in seconds.
+    def admit: (sojourn: Float, now: Float) -> verdict
+
+    # The acceptable waiting time, in seconds.
+    def target: () -> Float
+    def interval: () -> Float
+
+    def shedding?: () -> bool
+
+    def inspect: () -> String
+  end
+
+  # Client-side adaptive throttling, so retries cannot amplify an outage.
+  class Budget
+    DEFAULT_MULTIPLIER: Float
+
+    # `multiplier` is how many requests each accepted one entitles the client
+    # to.
+    def self.new: (?multiplier: Float) -> instance
+
+    def requested: () -> self
+
+    def accepted: () -> self
+
+    # Halves both counts, so the budget forgets an outage instead of holding it
+    # against the dependency forever.
+    def decay: () -> self
+
+    def multiplier: () -> Float
+    def requests: () -> Integer
+
+    def accepts: () -> Integer
+
+    # The fraction of outbound work to drop locally, in `0.0..1.0`. A fraction
+    # rather than a decision: the caller owns the dice.
+    def shed_probability: () -> Float
+
+    def inspect: () -> String
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: shed_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Abdelkader Boudih
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: 'AIMD and Vegas move a concurrency limit from what completed calls report,
+  CoDel sheds queued work by how long it waited, and a retry budget stops a client
+  from amplifying an outage. Bound to Ruby from the no_std shed-machines crate: the
+  control loops only, with the semaphore, the queue and the dice left to the caller.'
+email:
+- oss@seuros.com
+executables: []
+extensions:
+- ext/shed_machines_native/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Cargo.lock
+- Cargo.toml
+- LICENSE.txt
+- README.md
+- ext/shed_machines_native/core/Cargo.toml
+- ext/shed_machines_native/core/src/aimd.rs
+- ext/shed_machines_native/core/src/budget.rs
+- ext/shed_machines_native/core/src/codel.rs
+- ext/shed_machines_native/core/src/lib.rs
+- ext/shed_machines_native/core/src/vegas.rs
+- ext/shed_machines_native/extconf.rb
+- ext/shed_machines_native/ffi/Cargo.toml
+- ext/shed_machines_native/ffi/extconf.rb
+- ext/shed_machines_native/ffi/src/aimd.rs
+- ext/shed_machines_native/ffi/src/budget.rs
+- ext/shed_machines_native/ffi/src/codel.rs
+- ext/shed_machines_native/ffi/src/lib.rs
+- ext/shed_machines_native/ffi/src/vegas.rs
+- lib/shed_machines.rb
+- lib/shed_machines/version.rb
+- sig/shed_machines.rbs
+homepage: https://github.com/seuros/shed_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/shed_machines
+  changelog_uri: https://github.com/seuros/shed_machines/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/seuros/shed_machines/issues
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: shed_machines_native
+  cargo_manifest_path: ext/shed_machines_native/ffi/Cargo.toml
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Adaptive concurrency limits and load shedding for Ruby
+test_files: []