shed_machines 0.1.1-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 269a137c58effa8b2fd460e4904611cd107447326174d7ed21b961ae35fcd8f7
+  data.tar.gz: 8a4010d5116e9b0fe502bb786138c94aefca9458aba96140f5f19569b569ae6d
+SHA512:
+  metadata.gz: b10db4366ee3ffdb1e06444feaf31040a85be364d1f0bb6bd3af07495bc6a925dea49ba90661837b69bae059ce478dac2f82dd61d5190482b05845f6711f5135
+  data.tar.gz: 159c5c7f7d6c91c46967424ec9d46e7783708b8cdbf23b7f4464066eb0648457e43932bad4200437b9b733b23cb200a7a8f02d738468e434faa8e97c2a61c3fd

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/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/extconf.rb

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

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,63 @@
+--- !ruby/object:Gem::Specification
+name: shed_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: x86_64-linux
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-01 00:00:00.000000000 Z
+dependencies: []
+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: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/shed_machines_native/extconf.rb
+- lib/shed_machines.rb
+- lib/shed_machines/version.rb
+- lib/shed_machines_native/shed_machines_native.so
+- 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
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Adaptive concurrency limits and load shedding for Ruby
+test_files: []