rogue_machines 0.1.1

data/ext/rogue_machines_native/core/src/experiment.rs

@@ -0,0 +1,84 @@
+//! What a fault is, who gets it, and when it stops.
+
+use crate::PER_MILLION;
+
+/// What the caller does instead of the real call.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Fault {
+    /// Fail.
+    Raise,
+    /// Take this many nanoseconds longer, then make the real call.
+    Delay { ns: u64 },
+    /// Succeed, with a substitute value.
+    Garble,
+}
+
+/// The share of calls a fault reaches, in millionths.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub struct Fraction(u32);
+
+impl Fraction {
+    /// Reaches nothing.
+    pub const NONE: Self = Self(0);
+
+    /// Reaches every call.
+    pub const ALL: Self = Self(PER_MILLION);
+
+    /// Rejects a share above [`PER_MILLION`].
+    #[must_use]
+    pub const fn new(millionths: u32) -> Option<Self> {
+        if millionths > PER_MILLION {
+            None
+        } else {
+            Some(Self(millionths))
+        }
+    }
+
+    #[must_use]
+    pub const fn millionths(self) -> u32 {
+        self.0
+    }
+
+    /// Whether `draw`, which is below [`PER_MILLION`], falls in this share.
+    #[must_use]
+    pub const fn covers(self, draw: u32) -> bool {
+        draw < self.0
+    }
+}
+
+/// An armed fault.
+///
+/// The expiry is what keeps an experiment from outliving the person who armed
+/// it, so there is no way to build one without a reading it expires at.
+///
+/// An expiry is only meaningful against the clock it was computed on. This
+/// does not try to infer that a reading came from a different clock: with
+/// several threads taking their own readings, a reading older than the arming
+/// is ordinary interleaving rather than evidence of anything, and treating it
+/// as evidence retires experiments that were just armed.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Experiment {
+    pub fault: Fault,
+    pub fraction: Fraction,
+    /// The first reading at which this is no longer armed.
+    pub expires_at_ns: u64,
+}
+
+impl Experiment {
+    #[must_use]
+    pub const fn new(fault: Fault, fraction: Fraction, expires_at_ns: u64) -> Self {
+        Self {
+            fault,
+            fraction,
+            expires_at_ns,
+        }
+    }
+
+    #[must_use]
+    pub const fn spent(&self, now_ns: u64) -> bool {
+        now_ns >= self.expires_at_ns
+    }
+}
+
+#[cfg(test)]
+mod tests;

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

@@ -0,0 +1,30 @@
+#![cfg_attr(not(feature = "std"), no_std)]
+
+//! Fault injection: making a dependency fail, stall or lie on purpose.
+//!
+//! A [`Rogue`] holds the experiments a process is running and answers one
+//! question per call: inject a fault, or pass.
+//!
+//! Nothing here performs a fault. The caller raises, sleeps and substitutes,
+//! and supplies both the clock and the draw. Disarmed is the default and the
+//! fast path: with nothing armed a decision is one relaxed load.
+
+/// Compiles and runs the README's examples as doctests.
+#[cfg(doctest)]
+#[doc = include_str!("../README.md")]
+struct ReadmeDoctests;
+
+mod armed;
+pub mod experiment;
+pub mod rogue;
+
+pub(crate) use armed::Armed;
+pub use armed::Slot;
+pub use experiment::{Experiment, Fault, Fraction};
+pub use rogue::{Decision, Rogue};
+
+/// Slots a [`Rogue`] holds, which is the width of the mask tracking them.
+pub const EXPERIMENTS: usize = u32::BITS as usize;
+
+/// Millionths in a whole, the unit a [`Fraction`] is given in.
+pub const PER_MILLION: u32 = 1_000_000;

data/ext/rogue_machines_native/core/src/rogue.rs

@@ -0,0 +1,135 @@
+//! The experiments a process is running.
+
+use crate::{Armed, EXPERIMENTS, Experiment, Fault, PER_MILLION, Slot};
+
+/// What to do with one call.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Decision {
+    /// Make the real call.
+    Pass,
+    /// Do this instead.
+    Inject(Fault),
+}
+
+/// A slot table and the mask over it.
+///
+/// ```
+/// use rogue_machines::{Decision, Experiment, Fault, Fraction, Rogue, Slot};
+///
+/// const SECOND: u64 = 1_000_000_000;
+/// let Some(slot) = Slot::new(0) else { unreachable!() };
+/// let mut rogue = Rogue::new();
+///
+/// // Disarmed, which is where every process starts.
+/// assert_eq!(rogue.decide(slot, 0, 0), Decision::Pass);
+///
+/// rogue.arm(slot, Experiment::new(Fault::Raise, Fraction::ALL, 5 * SECOND));
+/// assert_eq!(rogue.decide(slot, SECOND, 0), Decision::Inject(Fault::Raise));
+///
+/// // Past its expiry it disarms itself, and stays disarmed.
+/// assert_eq!(rogue.decide(slot, 5 * SECOND, 0), Decision::Pass);
+/// assert!(!rogue.any_armed());
+/// ```
+#[derive(Debug)]
+pub struct Rogue {
+    armed: Armed,
+    experiments: [Option<Experiment>; EXPERIMENTS],
+}
+
+impl Default for Rogue {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Rogue {
+    #[must_use]
+    pub const fn new() -> Self {
+        Self {
+            armed: Armed::new(),
+            experiments: [None; EXPERIMENTS],
+        }
+    }
+
+    /// Arms `slot`, replacing whatever it held.
+    pub fn arm(&mut self, slot: Slot, experiment: Experiment) {
+        self.experiments[slot.index()] = Some(experiment);
+        self.armed.hold(slot);
+    }
+
+    pub fn disarm(&mut self, slot: Slot) {
+        self.experiments[slot.index()] = None;
+        self.armed.release(slot);
+    }
+
+    pub fn disarm_all(&mut self) {
+        self.experiments = [None; EXPERIMENTS];
+        self.armed.release_all();
+    }
+
+    /// Whether any experiment is armed as of the last [`sweep`](Self::sweep),
+    /// which is the only read a call runs when none is.
+    #[must_use]
+    pub fn any_armed(&self) -> bool {
+        self.armed.any()
+    }
+
+    /// How many experiments are armed as of the last [`sweep`](Self::sweep).
+    #[must_use]
+    pub fn armed_count(&self) -> u32 {
+        self.armed.count()
+    }
+
+    /// Releases every slot whose experiment has expired by `now_ns`.
+    ///
+    /// [`any_armed`](Self::any_armed) is a bare mask read, so without this an
+    /// experiment that expired on a slot nothing decides on again would hold
+    /// the gate open for the life of the process. Both readers below sweep
+    /// first, so the next call of either restores the disarmed fast path.
+    pub fn sweep(&self, now_ns: u64) {
+        if !self.armed.any() {
+            return;
+        }
+        for index in 0..EXPERIMENTS {
+            let Some(slot) = Slot::new(index) else {
+                continue;
+            };
+            if self.armed.holds(slot) && self.spent(slot, now_ns) {
+                self.armed.release(slot);
+            }
+        }
+    }
+
+    /// The experiment arming `slot` at `now_ns`.
+    #[must_use]
+    pub fn active(&self, slot: Slot, now_ns: u64) -> Option<&Experiment> {
+        self.sweep(now_ns);
+        if !self.armed.holds(slot) {
+            return None;
+        }
+        self.experiments[slot.index()].as_ref()
+    }
+
+    /// What to do with one call: retires anything expired by `now_ns`, then
+    /// injects if `slot` is armed and `draw`, which is below
+    /// [`PER_MILLION`](crate::PER_MILLION), falls in the share it covers.
+    #[must_use]
+    pub fn decide(&self, slot: Slot, now_ns: u64, draw: u32) -> Decision {
+        debug_assert!(draw < PER_MILLION, "a draw must be below PER_MILLION");
+        match self.active(slot, now_ns) {
+            Some(experiment) if experiment.fraction.covers(draw) => {
+                Decision::Inject(experiment.fault)
+            }
+            _ => Decision::Pass,
+        }
+    }
+
+    /// Whether `slot` holds nothing, or holds something already expired. An
+    /// empty slot counts as spent so a bit can never outlive its experiment.
+    fn spent(&self, slot: Slot, now_ns: u64) -> bool {
+        self.experiments[slot.index()].is_none_or(|experiment| experiment.spent(now_ns))
+    }
+}
+
+#[cfg(test)]
+mod tests;

data/ext/rogue_machines_native/extconf.rb

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

data/ext/rogue_machines_native/ffi/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "rogue_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 rogue-machines fault injector"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[lints]
+workspace = true
+
+[dependencies]
+rogue-machines = { workspace = true, features = ["std"] }
+magnus = { version = ">= 0.9.3", default-features = false, features = ["io"] }

data/ext/rogue_machines_native/ffi/extconf.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'mkmf'
+require 'pathname'
+require 'rb_sys/mkmf'
+
+create_rust_makefile('rogue_machines_native/rogue_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/rogue_machines_native/ffi/src/injection.rs

@@ -0,0 +1,44 @@
+//! The frozen `Data` object a decision hands back when it injects.
+
+use std::sync::OnceLock;
+
+use magnus::value::Opaque;
+use magnus::{Error, RClass, RModule, RStruct, Ruby, Value, prelude::*};
+use rogue_machines::Fault;
+
+use crate::error;
+
+static INJECTION: OnceLock<Opaque<RClass>> = OnceLock::new();
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let injection = ruby.define_data(None, ("fault", "delay_ns"))?;
+    module.const_set("Injection", injection)?;
+    INJECTION
+        .set(injection.into())
+        .map_err(|_| error(ruby, "Injection was defined twice".to_owned()))
+}
+
+/// The fault to perform, and how long to wait when it is a delay.
+pub fn injection(ruby: &Ruby, fault: Fault) -> Result<Value, Error> {
+    let class = INJECTION
+        .get()
+        .map(|class| ruby.get_inner(*class))
+        .ok_or_else(|| error(ruby, "Injection was not defined".to_owned()))?;
+    let instance = RStruct::try_convert(class.obj_alloc()?)?;
+    let (name, delay_ns) = match fault {
+        Fault::Raise => ("raise", 0),
+        Fault::Delay { ns } => ("delay", ns),
+        Fault::Garble => ("garble", 0),
+    };
+    for (index, member) in [
+        ruby.into_value(ruby.to_symbol(name)),
+        ruby.into_value(delay_ns),
+    ]
+    .into_iter()
+    .enumerate()
+    {
+        instance.aset(index, member)?;
+    }
+    instance.freeze();
+    Ok(instance.as_value())
+}

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

@@ -0,0 +1,173 @@
+//! Ruby bindings for the `rogue-machines` fault injector.
+//!
+//! The core decides; this layer names the experiments and converts seconds to
+//! the nanoseconds the core counts in. The clock and the draw come from the
+//! caller, so `RogueMachines.clock` and `RogueMachines.random` are swappable
+//! and an experiment replays exactly.
+
+#![allow(clippy::needless_pass_by_value)]
+
+mod injection;
+mod registry;
+
+use std::sync::OnceLock;
+
+use magnus::value::Opaque;
+use magnus::{Error, ExceptionClass, Integer, RModule, Ruby, Value, prelude::*};
+use rogue_machines::{Fraction, PER_MILLION};
+
+static ERROR: OnceLock<Opaque<ExceptionClass>> = OnceLock::new();
+static INJECTED: OnceLock<Opaque<ExceptionClass>> = OnceLock::new();
+
+/// Nanoseconds in a second.
+pub(crate) const NS_PER_SECOND: u32 = 1_000_000_000;
+
+/// Longest an experiment may run for. An experiment is something a person is
+/// waiting on, so a day is already generous; past that it is configuration,
+/// and it must be re-armed deliberately.
+pub(crate) const LONGEST_EXPERIMENT: f64 = 24.0 * 60.0 * 60.0;
+
+/// Longest a single delay may wait. Bounds how long a stall can hold a caller
+/// that has no deadline of its own.
+pub(crate) const LONGEST_DELAY: f64 = 5.0 * 60.0;
+
+/// Seconds as nanoseconds, rejecting a duration no experiment should run for.
+///
+/// An unbounded duration is not merely untidy: `as u64` saturates rather than
+/// wrapping, so without `longest` a large `delay` becomes a stall of centuries.
+#[expect(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
+pub(crate) fn duration(ruby: &Ruby, name: &str, seconds: f64, longest: f64) -> Result<u64, Error> {
+    if !seconds.is_finite() || seconds <= 0.0 || seconds > longest {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            format!("{name} must be above 0 and at most {longest} seconds, got {seconds}"),
+        ));
+    }
+    let nanoseconds = seconds * f64::from(NS_PER_SECOND);
+    if nanoseconds < 1.0 {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            format!("{name} of {seconds} is below the one nanosecond resolution"),
+        ));
+    }
+    Ok(nanoseconds.round() as u64)
+}
+
+/// A reading in nanoseconds.
+///
+/// A Float is refused rather than truncated, and so is a value outside the
+/// range: magnus would reject that with its own `RangeError`, which would
+/// leak out of a protected call site as something the gem never documents.
+pub(crate) fn reading(ruby: &Ruby, name: &str, value: Value) -> Result<u64, Error> {
+    whole(ruby, name, value)?.to_u64().map_err(|_| {
+        Error::new(
+            ruby.exception_arg_error(),
+            format!(
+                "{name} must be a non-negative Integer of at most {}",
+                u64::MAX
+            ),
+        )
+    })
+}
+
+/// A draw below [`PER_MILLION`].
+///
+/// A truncated draw becomes 0, which every share covers, so a caller whose
+/// `rand` returns a Float would inject on every call instead of none.
+pub(crate) fn draw(ruby: &Ruby, value: Value) -> Result<u32, Error> {
+    let drawn = whole(ruby, "draw", value)?.to_u32().map_err(|_| {
+        Error::new(
+            ruby.exception_arg_error(),
+            format!("draw must be a non-negative Integer below {PER_MILLION}"),
+        )
+    })?;
+    if drawn >= PER_MILLION {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            format!("draw must be below {PER_MILLION}, got {drawn}"),
+        ));
+    }
+    Ok(drawn)
+}
+
+/// A generation tag.
+pub(crate) fn counted(ruby: &Ruby, name: &str, value: Value) -> Result<u32, Error> {
+    whole(ruby, name, value)?.to_u32().map_err(|_| {
+        Error::new(
+            ruby.exception_arg_error(),
+            format!(
+                "{name} must be a non-negative Integer of at most {}",
+                u32::MAX
+            ),
+        )
+    })
+}
+
+fn whole(ruby: &Ruby, name: &str, value: Value) -> Result<Integer, Error> {
+    Integer::from_value(value).ok_or_else(|| {
+        Error::new(
+            ruby.exception_arg_error(),
+            format!("{name} must be an Integer"),
+        )
+    })
+}
+
+/// A share of calls, rejecting one outside a whole or too small to express.
+#[expect(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
+pub(crate) fn share(ruby: &Ruby, given: f64) -> Result<Fraction, Error> {
+    if !given.is_finite() || !(0.0..=1.0).contains(&given) {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            format!("share must be between 0 and 1, got {given}"),
+        ));
+    }
+    let millionths = given * f64::from(PER_MILLION);
+    if given > 0.0 && millionths < 1.0 {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            format!("share of {given} is below the one millionth resolution"),
+        ));
+    }
+    let millionths = millionths.round() as u32;
+    Fraction::new(millionths).ok_or_else(|| {
+        Error::new(
+            ruby.exception_arg_error(),
+            format!("share of {millionths} millionths is not a whole"),
+        )
+    })
+}
+
+pub(crate) fn error(ruby: &Ruby, message: String) -> Error {
+    ERROR.get().map_or_else(
+        || {
+            Error::new(
+                ruby.exception_runtime_error(),
+                "RogueMachines was not initialised",
+            )
+        },
+        |class| Error::new(ruby.get_inner(*class), message),
+    )
+}
+
+fn define_errors(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let base = module.define_error("Error", ruby.exception_standard_error())?;
+    ERROR
+        .set(base.into())
+        .map_err(|_| error(ruby, "Error was defined twice".to_owned()))?;
+
+    let injected = module.define_error("Injected", base)?;
+    INJECTED
+        .set(injected.into())
+        .map_err(|_| error(ruby, "Injected was defined twice".to_owned()))
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("RogueMachines")?;
+    module.const_set("NS_PER_SECOND", NS_PER_SECOND)?;
+    module.const_set("PER_MILLION", PER_MILLION)?;
+    module.const_set("EXPERIMENTS", rogue_machines::EXPERIMENTS)?;
+    define_errors(ruby, module)?;
+    injection::define(ruby, module)?;
+    registry::define(ruby, module)
+}