rogue_machines 0.1.1

data/ext/rogue_machines_native/ffi/src/registry.rs

@@ -0,0 +1,288 @@
+//! `RogueMachines::Rogue`: the experiments a process is running, by name.
+
+use std::cell::{Cell, RefCell};
+use std::collections::HashMap;
+
+use magnus::scan_args::{get_kwargs, scan_args};
+use magnus::{Error, RArray, RHash, RModule, Ruby, Value, function, method, prelude::*};
+use rogue_machines::{Decision, EXPERIMENTS, Experiment, Fault, Rogue, Slot};
+
+use crate::injection::injection;
+use crate::{LONGEST_DELAY, LONGEST_EXPERIMENT, counted, draw, duration, error, reading, share};
+
+/// The core registry, and the names standing in for its slot indices.
+#[magnus::wrap(class = "RogueMachines::Rogue", free_immediately, size)]
+struct Wrapper {
+    rogue: RefCell<Rogue>,
+    slots: RefCell<HashMap<String, Slot>>,
+    /// Which clock the armed expiries were computed against.
+    ///
+    /// Every reading is only meaningful for one of these. A caller samples a
+    /// reading before it synchronises, so a reading that arrives after the
+    /// clock was replaced would otherwise be compared against expiries it has
+    /// no relation to, and `sweep` is destructive.
+    generation: Cell<u32>,
+}
+
+impl Wrapper {
+    fn new() -> Self {
+        Self {
+            rogue: RefCell::new(Rogue::new()),
+            slots: RefCell::new(HashMap::new()),
+            generation: Cell::new(0),
+        }
+    }
+
+    /// Whether any experiment is armed, which is the whole of the decision a
+    /// disarmed process takes.
+    fn any_armed(&self) -> bool {
+        self.rogue.borrow().any_armed()
+    }
+
+    const fn generation(&self) -> u32 {
+        self.generation.get()
+    }
+
+    /// Disarms everything and starts a generation, so readings taken against
+    /// the outgoing clock are refused rather than acted on.
+    fn invalidate(&self) -> u32 {
+        self.slots.borrow_mut().clear();
+        self.rogue.borrow_mut().disarm_all();
+        let next = self.generation.get().wrapping_add(1);
+        self.generation.set(next);
+        next
+    }
+
+    const fn current(&self, generation: u32) -> bool {
+        self.generation.get() == generation
+    }
+
+    fn armed_count(
+        ruby: &Ruby,
+        rb_self: &Self,
+        given_now: Value,
+        given_age: Value,
+    ) -> Result<u32, Error> {
+        let generation = counted(ruby, "generation", given_age)?;
+        if !rb_self.current(generation) {
+            return Ok(0);
+        }
+        let now_ns = reading(ruby, "now_ns", given_now)?;
+        let rogue = rb_self.rogue.borrow();
+        rogue.sweep(now_ns);
+        Ok(rogue.armed_count())
+    }
+
+    /// Arms `name`, replacing any experiment already under it.
+    ///
+    /// `fault:` is `:raise`, `:delay` or `:garble`, `share:` is the fraction of
+    /// calls it reaches, and `expires_in:` is how long it runs for from
+    /// `now_ns:`. A `:delay` also takes `delay:`, in seconds.
+    fn arm(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<(), Error> {
+        let args = scan_args::<(String,), (), (), (), RHash, ()>(args)?;
+        let (name,) = args.required;
+        let keywords = get_kwargs::<_, (String, f64, f64, Value, Value), (Option<f64>,), ()>(
+            args.keywords,
+            &["fault", "share", "expires_in", "now_ns", "generation"],
+            &["delay"],
+        )?;
+        let (named, given_share, expires_in, given_now, given_age) = keywords.required;
+        let generation = counted(ruby, "generation", given_age)?;
+        if !rb_self.current(generation) {
+            return Err(error(
+                ruby,
+                "the clock was replaced while arming; nothing was armed".to_owned(),
+            ));
+        }
+        let now_ns = reading(ruby, "now_ns", given_now)?;
+        let (delay,) = keywords.optional;
+
+        let expires_at_ns = now_ns
+            .checked_add(duration(
+                ruby,
+                "expires_in",
+                expires_in,
+                LONGEST_EXPERIMENT,
+            )?)
+            .ok_or_else(|| {
+                Error::new(
+                    ruby.exception_arg_error(),
+                    "expires_in puts the expiry past the end of the clock",
+                )
+            })?;
+        let fraction = share(ruby, given_share)?;
+        let fault = fault(ruby, &named, delay)?;
+        let slot = rb_self.slot_for(ruby, name, now_ns)?;
+
+        rb_self
+            .rogue
+            .borrow_mut()
+            .arm(slot, Experiment::new(fault, fraction, expires_at_ns));
+        Ok(())
+    }
+
+    /// Disarms `name`, freeing its slot. Reports whether it was still running,
+    /// which an experiment that expired on its own is not.
+    fn disarm(
+        ruby: &Ruby,
+        rb_self: &Self,
+        name: String,
+        given_now: Value,
+        given_age: Value,
+    ) -> Result<bool, Error> {
+        let generation = counted(ruby, "generation", given_age)?;
+        if !rb_self.current(generation) {
+            return Ok(false);
+        }
+        let now_ns = reading(ruby, "now_ns", given_now)?;
+        let Some(slot) = rb_self.slots.borrow_mut().remove(&name) else {
+            return Ok(false);
+        };
+        let was_running = rb_self.rogue.borrow().active(slot, now_ns).is_some();
+        rb_self.rogue.borrow_mut().disarm(slot);
+        Ok(was_running)
+    }
+
+    fn disarm_all(&self) {
+        self.slots.borrow_mut().clear();
+        self.rogue.borrow_mut().disarm_all();
+    }
+
+    /// The names still running at `now_ns`, in no particular order.
+    fn armed(
+        ruby: &Ruby,
+        rb_self: &Self,
+        given_now: Value,
+        given_age: Value,
+    ) -> Result<RArray, Error> {
+        let generation = counted(ruby, "generation", given_age)?;
+        if !rb_self.current(generation) {
+            return Ok(ruby.ary_new());
+        }
+        let now_ns = reading(ruby, "now_ns", given_now)?;
+        let running: Vec<String> = {
+            let rogue = rb_self.rogue.borrow();
+            rb_self
+                .slots
+                .borrow()
+                .iter()
+                .filter(|(_, slot)| rogue.active(**slot, now_ns).is_some())
+                .map(|(name, _)| name.clone())
+                .collect()
+        };
+        Ok(ruby.ary_from_iter(running))
+    }
+
+    /// The fault to perform for one call, or `nil` to make the real one.
+    ///
+    /// `draw` is the caller's, below `PER_MILLION`, and decides which calls an
+    /// experiment reaches.
+    fn decide(
+        ruby: &Ruby,
+        rb_self: &Self,
+        name: String,
+        given_now: Value,
+        given_draw: Value,
+        given_age: Value,
+    ) -> Result<Option<Value>, Error> {
+        let generation = counted(ruby, "generation", given_age)?;
+        if !rb_self.current(generation) {
+            return Ok(None);
+        }
+        let now_ns = reading(ruby, "now_ns", given_now)?;
+        let drawn = draw(ruby, given_draw)?;
+        let decision = {
+            let rogue = rb_self.rogue.borrow();
+            if !rogue.any_armed() {
+                return Ok(None);
+            }
+            rogue.sweep(now_ns);
+            let Some(slot) = rb_self.slots.borrow().get(&name).copied() else {
+                return Ok(None);
+            };
+            rogue.decide(slot, now_ns, drawn)
+        };
+        match decision {
+            Decision::Pass => Ok(None),
+            Decision::Inject(fault) => injection(ruby, fault).map(Some),
+        }
+    }
+
+    /// The slot already standing for `name`, or the lowest free one.
+    ///
+    /// An expired experiment releases its bit in the core but not its name, so
+    /// the names of everything no longer armed are dropped first; otherwise a
+    /// run of short experiments exhausts the slots.
+    fn slot_for(&self, ruby: &Ruby, name: String, now_ns: u64) -> Result<Slot, Error> {
+        let existing = {
+            let rogue = self.rogue.borrow();
+            let mut slots = self.slots.borrow_mut();
+            slots.retain(|held, slot| *held == name || rogue.active(*slot, now_ns).is_some());
+            slots.get(&name).copied()
+        };
+        if let Some(slot) = existing {
+            return Ok(slot);
+        }
+        let mut slots = self.slots.borrow_mut();
+        let taken: Vec<usize> = slots.values().map(|slot| slot.index()).collect();
+        let free = (0..EXPERIMENTS)
+            .find(|index| !taken.contains(index))
+            .and_then(Slot::new)
+            .ok_or_else(|| {
+                error(
+                    ruby,
+                    format!("all {EXPERIMENTS} experiment slots are taken; disarm one first"),
+                )
+            })?;
+        slots.insert(name, free);
+        Ok(free)
+    }
+
+    /// Reports the mask as it stood at the last decision, since `inspect`
+    /// takes no reading and so cannot retire an expired experiment itself.
+    fn inspect(&self) -> String {
+        format!(
+            "#<RogueMachines::Rogue armed={} of {EXPERIMENTS} at the last decision>",
+            self.rogue.borrow().armed_count()
+        )
+    }
+}
+
+/// The fault a `fault:` keyword names.
+fn fault(ruby: &Ruby, named: &str, delay: Option<f64>) -> Result<Fault, Error> {
+    match named {
+        "raise" => Ok(Fault::Raise),
+        "garble" => Ok(Fault::Garble),
+        "delay" => {
+            let seconds = delay.ok_or_else(|| {
+                Error::new(
+                    ruby.exception_arg_error(),
+                    "a :delay fault needs delay: in seconds",
+                )
+            })?;
+            Ok(Fault::Delay {
+                ns: duration(ruby, "delay", seconds, LONGEST_DELAY)?,
+            })
+        }
+        other => Err(Error::new(
+            ruby.exception_arg_error(),
+            format!("fault must be :raise, :delay or :garble, got {other:?}"),
+        )),
+    }
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let class = module.define_class("Rogue", ruby.class_object())?;
+    class.define_singleton_method("new", function!(Wrapper::new, 0))?;
+    class.define_method("any_armed?", method!(Wrapper::any_armed, 0))?;
+    class.define_method("armed_count", method!(Wrapper::armed_count, 2))?;
+    class.define_method("arm", method!(Wrapper::arm, -1))?;
+    class.define_method("disarm", method!(Wrapper::disarm, 3))?;
+    class.define_method("disarm_all", method!(Wrapper::disarm_all, 0))?;
+    class.define_method("generation", method!(Wrapper::generation, 0))?;
+    class.define_method("invalidate", method!(Wrapper::invalidate, 0))?;
+    class.define_method("armed", method!(Wrapper::armed, 2))?;
+    class.define_method("decide", method!(Wrapper::decide, 4))?;
+    class.define_method("inspect", method!(Wrapper::inspect, 0))?;
+    Ok(())
+}

data/lib/rogue_machines/version.rb

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

data/lib/rogue_machines.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require 'deadline_machines'
+
+require_relative 'rogue_machines/version'
+
+# Rogue, Injection, Error and Injected are defined by the native extension;
+# there is no pure-Ruby implementation to fall back to.
+require 'rogue_machines_native/rogue_machines_native'
+
+# Fault injection: making a dependency fail, stall or lie on purpose.
+#
+# Disarmed is the default. `run` costs one native call that reads one word
+# until something is armed.
+module RogueMachines
+  # Attempts at one consistent reading before giving up on a clock that is
+  # being replaced faster than it can be read.
+  READINGS = 100
+
+  @registry = Rogue.new
+  @substitutes = {}.freeze
+  @lock = Mutex.new
+
+  class << self
+    attr_writer :random
+
+    # Monotonic nanoseconds. Delegates to deadline_machines rather than
+    # memoising it, so replacing that gem's clock moves every expiry with it.
+    def clock
+      @clock || DeadlineMachines.clock
+    end
+
+    # Installing a clock disarms everything first. Every armed expiry was
+    # computed against the outgoing clock, and an expiry measured against a
+    # clock it did not come from is not an expiry.
+    #
+    # It also starts a generation, so a reading already taken against the
+    # outgoing clock is refused rather than compared against expiries it has
+    # no relation to. `sweep` is destructive, so such a reading would retire
+    # experiments armed after the swap.
+    def clock=(clock)
+      @lock.synchronize do
+        # The native call goes last here, against the rule the other two-store
+        # writes follow, because this order is observable: `reading` is
+        # lock-free, and bumping the generation first would pair an outgoing
+        # reading with the incoming generation, which every consumer accepts.
+        Thread.handle_interrupt(Object => :never) do
+          @substitutes = {}.freeze
+          @clock = clock
+          registry.invalidate
+        end
+      end
+    end
+
+    def random
+      @random ||= Random.new
+    end
+
+    def registry
+      @registry
+    end
+
+    # Arms an experiment under `name`, replacing any already there.
+    #
+    #   RogueMachines.arm(:payments, fault: :raise, share: 0.01, expires_in: 300)
+    #   RogueMachines.arm(:slow, fault: :delay, delay: 2, share: 1.0, expires_in: 60)
+    #   RogueMachines.arm(:lies, fault: :garble, garbled: [], share: 0.5, expires_in: 60)
+    #
+    # `expires_in` is required and counts from now, so no experiment outlives
+    # the person who armed it.
+    def arm(name, fault:, share:, expires_in:, delay: nil, garbled: nil)
+      key = named(name)
+
+      # The reading is taken before the lock so that a caller's clock never
+      # runs inside it, which means the expiry is measured from slightly
+      # before the arming. See "The clock is deadline_machines'" in the README.
+      pair = reading
+      unless pair
+        raise Error, "the clock was replaced #{READINGS} times while taking one reading; " \
+                     'nothing is armed'
+      end
+
+      now, age = pair
+      options = { fault: fault.to_s, share: Float(share), expires_in: Float(expires_in),
+                  now_ns: now, generation: age }
+      options[:delay] = Float(delay) if delay
+
+      @lock.synchronize do
+        # Two stores. An interrupt landing between them would leave an armed
+        # garble with nothing to return for the rest of its life, and nothing
+        # repairs that, because publishing only ever removes keys.
+        Thread.handle_interrupt(Object => :never) do
+          registry.arm(key, **options)
+          payload = options[:fault] == 'garble' ? garbled : nil
+          publish(substitutes.merge(key => payload), registry.armed(now, age))
+        end
+      end
+      name
+    end
+
+    # Reports whether `name` was still running, which an experiment that
+    # expired on its own is not.
+    #
+    # The substitute goes first: a call landing between the two sees a garble
+    # with nothing to return rather than the real value it was armed against.
+    def disarm(name)
+      key = named(name)
+      pair = reading
+      return false unless pair
+
+      now, age = pair
+      @lock.synchronize do
+        # A reading from a replaced clock must not drop a substitute belonging
+        # to the generation that replaced it.
+        break false unless registry.generation == age
+
+        # The native call validates its reading and can raise, so it goes
+        # first: nothing is mutated unless it succeeds. Ordering no longer
+        # matters to a reader, since a decision and its payload are read
+        # under this same lock.
+        Thread.handle_interrupt(Object => :never) do
+          was_running = registry.disarm(key, now, age)
+          @substitutes = substitutes.except(key).freeze
+          was_running
+        end
+      end
+    end
+
+    def disarm_all
+      @lock.synchronize do
+        Thread.handle_interrupt(Object => :never) do
+          registry.disarm_all
+          @substitutes = {}.freeze
+        end
+      end
+    end
+
+    # With no name, whether anything at all is armed. Asked through the name
+    # list rather than the gate `run` reads, because the gate only drops an
+    # expired experiment when something next decides.
+    def armed?(name = nil)
+      names = running
+      return names.any? if name.nil?
+
+      names.include?(named(name))
+    end
+
+    # The experiments still running, which excludes any that has expired.
+    def armed
+      running.map(&:to_sym)
+    end
+
+    # Runs the block, or the fault armed under `name` instead.
+    def run(name)
+      check(name)
+      unless registry.any_armed?
+        release unless substitutes.empty?
+        return yield
+      end
+
+      key = named(name)
+      pair = reading
+      return yield unless pair
+
+      now, age = pair
+      drawn = random.rand(PER_MILLION)
+
+      # The decision and the payload live in different stores, so reading them
+      # one after the other is wrong in both orders: a name published between
+      # the two is in the decision and not the table, and one retired between
+      # them is in the table and not the decision. They are read together.
+      # Nothing caller-supplied runs inside the lock, since the clock and the
+      # draw are already taken.
+      injection, payload = @lock.synchronize do
+        found = registry.decide(key, now, drawn, age)
+        [found, found && substitutes[key]]
+      end
+      reconcile(now, age)
+      return yield unless injection
+
+      case injection.fault
+      when :raise then raise Injected, "#{name} is armed to raise"
+      when :garble then payload
+      when :delay
+        stall(injection.delay_ns)
+        yield
+      end
+    end
+
+    private
+
+    def substitutes
+      @substitutes
+    end
+
+    # A reading and the generation it belongs to.
+    #
+    # The generation is read on both sides of the reading. Reading it only
+    # afterwards would adopt the new one and hand a stale reading to a
+    # destructive sweep; reading it only before would pair an outgoing
+    # reading with the incoming generation, which every consumer accepts. The
+    # pair cannot be sampled in one step, so a change means retry.
+    def reading
+      READINGS.times do
+        age = registry.generation
+        now = clock.now_ns
+        unless now.is_a?(Integer) && !now.negative?
+          raise Error, "#{clock.class} returned #{now.inspect}; a reading must be a " \
+                       'non-negative Integer of nanoseconds'
+        end
+        return [now, age] if registry.generation == age
+      end
+      nil
+    end
+
+    # Rejects a name the native table could not key on, without converting it,
+    # so a call site answers the same way whether or not anything is armed.
+    def check(name)
+      case name
+      when Symbol then legible(name.name)
+      when String then legible(name)
+      else raise ArgumentError, "an experiment name must be a Symbol or a String, got #{name.class}"
+      end
+    end
+
+    def legible(name)
+      raise ArgumentError, 'an experiment needs a name' if name.empty?
+      return if name.ascii_only?
+      return if name.encoding == Encoding::UTF_8 && name.valid_encoding?
+      raise ArgumentError, "an experiment name must be valid UTF-8, got #{name.encoding}" \
+        unless name.encoding == Encoding::UTF_8
+
+      raise ArgumentError, 'an experiment name holds bytes that are not valid UTF-8'
+    end
+
+    # The checked name, as something the native table can key on. Not `to_s`:
+    # a String subclass can override it, which armed one name and reported
+    # another.
+    def named(name)
+      check(name)
+      name.is_a?(Symbol) ? name.name : name
+    end
+
+    # The names still running, releasing the substitutes of everything that is
+    # not.
+    def running
+      pair = reading
+      return [] unless pair
+
+      now, age = pair
+      @lock.synchronize do
+        # A reading from a replaced clock lists nothing, and must not be used
+        # to prune: publishing against an empty list would wipe the table.
+        break [] unless registry.generation == age
+
+        names = registry.armed(now, age)
+        publish(substitutes, names)
+        names
+      end
+    end
+
+    # Releases the substitutes of anything no longer running, so one armed
+    # experiment holding the gate open cannot keep another's substitute, and
+    # the caller's object, alive until the next `arm`.
+    def reconcile(now_ns, age)
+      return if substitutes.size <= registry.armed_count(now_ns, age)
+
+      @lock.synchronize do
+        publish(substitutes, registry.armed(now_ns, age)) if registry.generation == age
+      end
+    end
+
+    # Only if nothing is armed once the lock is held. The gate `run` reads is
+    # sampled before it, so an `arm` landing in between would otherwise have
+    # its just-published substitute discarded, leaving an armed garble with
+    # nothing to return for the rest of its life.
+    def release
+      @lock.synchronize { @substitutes = {}.freeze unless registry.any_armed? }
+    end
+
+    # Replaces the table with the entries `names` still covers, in one
+    # assignment.
+    def publish(table, names)
+      @substitutes = table.slice(*names).freeze
+    end
+
+    # Spends the delay against the caller's deadline rather than past it, so a
+    # slow dependency trips the timeout that was already there.
+    def stall(delay_ns)
+      DeadlineMachines.check!
+      seconds = DeadlineMachines.clamp_sleep(delay_ns.fdiv(NS_PER_SECOND))
+      sleep(seconds) if seconds.positive?
+      DeadlineMachines.check!
+    end
+  end
+end