supervisor_machines 0.1.1

data/ext/supervisor_machines_native/core/src/supervisor.rs

@@ -0,0 +1,155 @@
+//! The decision machine itself.
+
+use crate::{Decision, Exit, Intensity, Policy, Span, Strategy};
+
+/// Holds the strategy, the restart intensity, and the recent restart history.
+///
+/// `CHILDREN` is how many children the supervisor owns, which fixes the
+/// strategy spans. `HISTORY` is the restart timestamps kept; it must exceed the
+/// intensity's restart count, or a single burst could not be measured.
+///
+/// ```
+/// use supervisor_machines::{Decision, Exit, Intensity, Policy, Span, Strategy, Supervisor};
+///
+/// const SECOND: u64 = 1_000_000_000;
+///
+/// // Three children that only work as a set, two restarts per minute allowed.
+/// let mut tree: Supervisor<3, 8> = Supervisor::new(
+///     Strategy::OneForAll,
+///     Intensity::new(2, 60 * SECOND),
+/// );
+///
+/// // The middle child dies badly, so all three come back.
+/// let decision = tree.stopped(1, Policy::Permanent, Exit::Abnormal, 0);
+/// assert_eq!(decision, Decision::Restart(Span { first: 0, last: 2 }));
+///
+/// // A temporary child is never worth restarting.
+/// assert_eq!(
+///     tree.stopped(2, Policy::Temporary, Exit::Abnormal, SECOND),
+///     Decision::Ignore,
+/// );
+/// ```
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Supervisor<const CHILDREN: usize, const HISTORY: usize> {
+    strategy: Strategy,
+    intensity: Intensity,
+    history: [u64; HISTORY],
+    recorded: usize,
+    next: usize,
+    terminated: bool,
+}
+
+impl<const CHILDREN: usize, const HISTORY: usize> Supervisor<CHILDREN, HISTORY> {
+    /// Rejects a shape that could not measure its own intensity.
+    const SHAPE: () = {
+        assert!(
+            CHILDREN > 0,
+            "a supervisor with no children has nothing to decide"
+        );
+        assert!(
+            HISTORY > 0,
+            "restart history needs room for at least one restart"
+        );
+    };
+
+    #[must_use]
+    pub const fn new(strategy: Strategy, intensity: Intensity) -> Self {
+        let () = Self::SHAPE;
+        Self {
+            strategy,
+            intensity,
+            history: [0; HISTORY],
+            recorded: 0,
+            next: 0,
+            terminated: false,
+        }
+    }
+
+    #[must_use]
+    pub const fn strategy(&self) -> Strategy {
+        self.strategy
+    }
+
+    #[must_use]
+    pub const fn intensity(&self) -> Intensity {
+        self.intensity
+    }
+
+    /// True once the supervisor has escalated. It stays true: a supervisor that
+    /// gave up does not change its mind.
+    #[must_use]
+    pub const fn terminated(&self) -> bool {
+        self.terminated
+    }
+
+    /// Restarts still inside the window as of `now_ns`.
+    #[must_use]
+    pub const fn recent_restarts(&self, now_ns: u64) -> u32 {
+        let cutoff = now_ns.saturating_sub(self.intensity.window_ns);
+        let mut counted = 0;
+        let mut index = 0;
+        while index < self.recorded {
+            if self.history[index] >= cutoff {
+                counted += 1;
+            }
+            index += 1;
+        }
+        counted
+    }
+
+    /// The children a failure at `index` takes with it under this strategy.
+    #[must_use]
+    pub const fn span(&self, index: usize) -> Span {
+        match self.strategy {
+            Strategy::OneForOne => Span::single(index),
+            Strategy::OneForAll => Span {
+                first: 0,
+                last: CHILDREN - 1,
+            },
+            Strategy::RestForOne => Span {
+                first: index,
+                last: CHILDREN - 1,
+            },
+        }
+    }
+
+    const fn record(&mut self, now_ns: u64) {
+        self.history[self.next] = now_ns;
+        self.next = (self.next + 1) % HISTORY;
+        if self.recorded < HISTORY {
+            self.recorded += 1;
+        }
+    }
+
+    /// Decide what to do about the child at `index`.
+    ///
+    /// One restart is recorded per failure handled, not per child restarted.
+    pub const fn stopped(
+        &mut self,
+        index: usize,
+        policy: Policy,
+        exit: Exit,
+        now_ns: u64,
+    ) -> Decision {
+        if self.terminated {
+            return Decision::Escalate;
+        }
+
+        match policy {
+            Policy::Temporary => return Decision::Ignore,
+            Policy::Transient if matches!(exit, Exit::Normal) => return Decision::Ignore,
+            Policy::Permanent | Policy::Transient => {}
+        }
+
+        self.record(now_ns);
+        if self.recent_restarts(now_ns) > self.intensity.restarts {
+            self.terminated = true;
+            return Decision::Escalate;
+        }
+
+        Decision::Restart(self.span(index))
+    }
+}
+
+#[cfg(test)]
+mod tests;

data/ext/supervisor_machines_native/extconf.rb

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

data/ext/supervisor_machines_native/ffi/Cargo.toml

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

data/ext/supervisor_machines_native/ffi/extconf.rb

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

@@ -0,0 +1,199 @@
+//! `SupervisorMachines::Decider`: the core's decision machine, bound to Ruby.
+//!
+//! `Supervisor` carries its child count and its restart history in the type,
+//! so a runtime child count is dispatched to one monomorphised shape per
+//! supported count and kept behind [`Decide`].
+
+use std::cell::RefCell;
+
+use magnus::scan_args::{get_kwargs, scan_args};
+use magnus::{Error, RArray, RHash, RModule, Ruby, Value, function, method, prelude::*};
+use supervisor_machines::{Decision, Exit, Intensity, Policy, Strategy, Supervisor};
+
+use crate::{Whole, decision, exit, policy, strategy, strategy_name};
+
+/// Restart timestamps every shape keeps.
+const HISTORY: usize = 64;
+
+/// The core escalates one restart past the intensity, so the history has to
+/// hold one more timestamp than the intensity tolerates.
+#[expect(clippy::cast_possible_truncation)]
+const MAX_RESTARTS: u32 = HISTORY as u32 - 1;
+
+/// The child counts a [`Decider`] can be built for.
+const SUPPORTED_CHILDREN: [usize; 17] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 32];
+
+/// A [`Supervisor`] with its child count erased. A supervision tree is plain
+/// data, so `Send` costs nothing and is what magnus asks of wrapped types.
+trait Decide: Send {
+    fn children(&self) -> usize;
+    fn strategy(&self) -> Strategy;
+    fn terminated(&self) -> bool;
+    fn recent_restarts(&self, now_ns: u64) -> u32;
+    fn stopped(&mut self, index: usize, policy: Policy, exit: Exit, now_ns: u64) -> Decision;
+}
+
+/// One monomorphised supervision tree. The newtype keeps the trait's method
+/// names from shadowing the core's inherent ones.
+struct Shape<const CHILDREN: usize>(Supervisor<CHILDREN, HISTORY>);
+
+impl<const CHILDREN: usize> Decide for Shape<CHILDREN> {
+    fn children(&self) -> usize {
+        CHILDREN
+    }
+
+    fn strategy(&self) -> Strategy {
+        self.0.strategy()
+    }
+
+    fn terminated(&self) -> bool {
+        self.0.terminated()
+    }
+
+    fn recent_restarts(&self, now_ns: u64) -> u32 {
+        self.0.recent_restarts(now_ns)
+    }
+
+    fn stopped(&mut self, index: usize, policy: Policy, exit: Exit, now_ns: u64) -> Decision {
+        self.0.stopped(index, policy, exit, now_ns)
+    }
+}
+
+/// Each shape is built behind its own call frame. Inlined, a debug build sizes
+/// one frame for every arm of the match in [`Wrapper::new`] at once, which
+/// overflows Ruby's fiber stack.
+#[inline(never)]
+fn boxed<const CHILDREN: usize>(strategy: Strategy, intensity: Intensity) -> Box<dyn Decide> {
+    Box::new(Shape(Supervisor::<CHILDREN, HISTORY>::new(
+        strategy, intensity,
+    )))
+}
+
+fn unsupported(ruby: &Ruby, children: usize) -> Error {
+    Error::new(
+        ruby.exception_arg_error(),
+        format!(
+            "{children} children is not a supported shape, expected one of {SUPPORTED_CHILDREN:?}"
+        ),
+    )
+}
+
+#[magnus::wrap(class = "SupervisorMachines::Decider", free_immediately, size)]
+struct Wrapper(RefCell<Box<dyn Decide>>);
+
+impl Wrapper {
+    fn new(ruby: &Ruby, args: &[Value]) -> Result<Self, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let (Whole(children), name, Whole(restarts), Whole(window_ns)) =
+            get_kwargs::<_, (Whole<usize>, Value, Whole<u32>, Whole<u64>), (), ()>(
+                args.keywords,
+                &["children", "strategy", "restarts", "window_ns"],
+                &[],
+            )?
+            .required;
+        if restarts > MAX_RESTARTS {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                format!("{restarts} restarts cannot escalate, the most is {MAX_RESTARTS}"),
+            ));
+        }
+        let strategy = strategy(ruby, name)?;
+        let intensity = Intensity::new(restarts, window_ns);
+        let tree = match children {
+            1 => boxed::<1>(strategy, intensity),
+            2 => boxed::<2>(strategy, intensity),
+            3 => boxed::<3>(strategy, intensity),
+            4 => boxed::<4>(strategy, intensity),
+            5 => boxed::<5>(strategy, intensity),
+            6 => boxed::<6>(strategy, intensity),
+            7 => boxed::<7>(strategy, intensity),
+            8 => boxed::<8>(strategy, intensity),
+            9 => boxed::<9>(strategy, intensity),
+            10 => boxed::<10>(strategy, intensity),
+            11 => boxed::<11>(strategy, intensity),
+            12 => boxed::<12>(strategy, intensity),
+            13 => boxed::<13>(strategy, intensity),
+            14 => boxed::<14>(strategy, intensity),
+            15 => boxed::<15>(strategy, intensity),
+            16 => boxed::<16>(strategy, intensity),
+            32 => boxed::<32>(strategy, intensity),
+            _ => return Err(unsupported(ruby, children)),
+        };
+        Ok(Self(RefCell::new(tree)))
+    }
+
+    /// Feeds one stopped child to the core and returns what it decided:
+    /// `:ignore`, `:escalate`, or the inclusive range of children to restart.
+    fn stopped(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<Value, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let (Whole(index), name, ending, Whole(now_ns)) =
+            get_kwargs::<_, (Whole<usize>, Value, Value, Whole<u64>), (), ()>(
+                args.keywords,
+                &["index", "policy", "exit", "now_ns"],
+                &[],
+            )?
+            .required;
+        let (policy, ending) = (policy(ruby, name)?, exit(ruby, ending)?);
+        let children = rb_self.0.borrow().children();
+        if index >= children {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                format!("index {index} is outside the {children} children"),
+            ));
+        }
+        let verdict = rb_self
+            .0
+            .borrow_mut()
+            .stopped(index, policy, ending, now_ns);
+        decision(ruby, verdict)
+    }
+
+    fn children(&self) -> usize {
+        self.0.borrow().children()
+    }
+
+    fn strategy(ruby: &Ruby, rb_self: &Self) -> Value {
+        strategy_name(ruby, rb_self.0.borrow().strategy()).as_value()
+    }
+
+    fn terminated(&self) -> bool {
+        self.0.borrow().terminated()
+    }
+
+    fn recent_restarts(&self, Whole(now_ns): Whole<u64>) -> u32 {
+        self.0.borrow().recent_restarts(now_ns)
+    }
+
+    fn inspect(ruby: &Ruby, rb_self: &Self) -> String {
+        format!(
+            "#<SupervisorMachines::Decider strategy={} children={} terminated={}>",
+            Self::strategy(ruby, rb_self).inspect(),
+            rb_self.children(),
+            rb_self.terminated()
+        )
+    }
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let class = module.define_class("Decider", ruby.class_object())?;
+    class.const_set("HISTORY", HISTORY)?;
+    class.const_set("MAX_RESTARTS", MAX_RESTARTS)?;
+    class.const_set("SUPPORTED_CHILDREN", supported_children(ruby)?)?;
+    class.define_singleton_method("new", function!(Wrapper::new, -1))?;
+    class.define_method("stopped", method!(Wrapper::stopped, -1))?;
+    class.define_method("children", method!(Wrapper::children, 0))?;
+    class.define_method("strategy", method!(Wrapper::strategy, 0))?;
+    class.define_method("terminated?", method!(Wrapper::terminated, 0))?;
+    class.define_method("recent_restarts", method!(Wrapper::recent_restarts, 1))?;
+    class.define_method("inspect", method!(Wrapper::inspect, 0))?;
+    Ok(())
+}
+
+fn supported_children(ruby: &Ruby) -> Result<RArray, Error> {
+    let array = ruby.ary_new_capa(SUPPORTED_CHILDREN.len());
+    for children in SUPPORTED_CHILDREN {
+        array.push(children)?;
+    }
+    array.freeze();
+    Ok(array)
+}

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

@@ -0,0 +1,135 @@
+//! Ruby bindings for the `supervisor-machines` decision machine.
+//!
+//! The core decides and nothing else: this crate converts Ruby symbols into
+//! its enums, hands back a `Decision` as a symbol or a `Range`, and leaves
+//! spawning, joining and killing to `SupervisorMachines::Supervisor`.
+//!
+//! Durations cross into the core as nanosecond integers. Seconds belong to the
+//! Ruby surface, which converts them with [`NS_PER_SECOND`].
+
+#![allow(clippy::needless_pass_by_value)]
+
+mod decider;
+
+use magnus::{Error, Integer, RArray, Ruby, Symbol, TryConvert, Value, prelude::*};
+use supervisor_machines::{DEFAULT_RESTARTS, DEFAULT_WINDOW_NS, Decision, Exit, Policy, Strategy};
+
+/// Nanoseconds in a second.
+pub(crate) const NS_PER_SECOND: u32 = 1_000_000_000;
+
+/// A whole number of things: a child count, a child index, a restart
+/// intensity, a nanosecond reading.
+///
+/// magnus reads an integer through Ruby's `NUM2*` family, which truncates a
+/// `Float` towards zero instead of refusing it, so an argument that means an
+/// integer 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 belong to the Ruby surface,
+/// which converts them before they reach here.
+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()
+        ),
+    )
+}
+
+/// Every [`Strategy`], in the order the core declares them.
+pub(crate) const STRATEGIES: [(&str, Strategy); 3] = [
+    ("one_for_one", Strategy::OneForOne),
+    ("one_for_all", Strategy::OneForAll),
+    ("rest_for_one", Strategy::RestForOne),
+];
+
+/// Every [`Policy`], in the order the core declares them.
+pub(crate) const POLICIES: [(&str, Policy); 3] = [
+    ("permanent", Policy::Permanent),
+    ("transient", Policy::Transient),
+    ("temporary", Policy::Temporary),
+];
+
+/// Every [`Exit`], in the order the core declares them.
+pub(crate) const EXITS: [(&str, Exit); 2] =
+    [("normal", Exit::Normal), ("abnormal", Exit::Abnormal)];
+
+/// Resolves a symbol against one of the closed sets above.
+fn member<T: Copy>(ruby: &Ruby, kind: &str, value: Value, set: &[(&str, T)]) -> Result<T, Error> {
+    let name = Symbol::from_value(value).and_then(|symbol| symbol.name().ok());
+    name.as_deref()
+        .and_then(|name| set.iter().find(|(known, _)| *known == name))
+        .map(|&(_, member)| member)
+        .ok_or_else(|| {
+            Error::new(
+                ruby.exception_arg_error(),
+                format!("unknown {kind}: {}", value.inspect()),
+            )
+        })
+}
+
+pub(crate) fn strategy(ruby: &Ruby, value: Value) -> Result<Strategy, Error> {
+    member(ruby, "strategy", value, &STRATEGIES)
+}
+
+pub(crate) fn policy(ruby: &Ruby, value: Value) -> Result<Policy, Error> {
+    member(ruby, "policy", value, &POLICIES)
+}
+
+pub(crate) fn exit(ruby: &Ruby, value: Value) -> Result<Exit, Error> {
+    member(ruby, "exit", value, &EXITS)
+}
+
+pub(crate) fn strategy_name(ruby: &Ruby, strategy: Strategy) -> Symbol {
+    let name = STRATEGIES
+        .iter()
+        .find(|&&(_, known)| known == strategy)
+        .map_or("", |&(name, _)| name);
+    ruby.to_symbol(name)
+}
+
+/// A [`Decision`] as Ruby reads it: `:ignore`, `:escalate`, or the inclusive
+/// range of child indices to restart.
+pub(crate) fn decision(ruby: &Ruby, decision: Decision) -> Result<Value, Error> {
+    match decision {
+        Decision::Ignore => Ok(ruby.to_symbol("ignore").as_value()),
+        Decision::Escalate => Ok(ruby.to_symbol("escalate").as_value()),
+        Decision::Restart(span) => ruby
+            .range_new(span.first, span.last, false)
+            .map(magnus::value::ReprValue::as_value),
+    }
+}
+
+/// A frozen array of the symbols naming a closed set.
+fn names<T>(ruby: &Ruby, set: &[(&str, T)]) -> Result<RArray, Error> {
+    let array = ruby.ary_new_capa(set.len());
+    for &(name, _) in set {
+        array.push(ruby.to_symbol(name))?;
+    }
+    array.freeze();
+    Ok(array)
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("SupervisorMachines")?;
+    module.const_set("NS_PER_SECOND", NS_PER_SECOND)?;
+    module.const_set("DEFAULT_RESTARTS", DEFAULT_RESTARTS)?;
+    module.const_set("DEFAULT_WINDOW_NS", DEFAULT_WINDOW_NS)?;
+    module.const_set("STRATEGIES", names(ruby, &STRATEGIES)?)?;
+    module.const_set("POLICIES", names(ruby, &POLICIES)?)?;
+    decider::define(ruby, module)
+}

data/lib/supervisor_machines/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SupervisorMachines
+  class Error < StandardError; end
+
+  # Raised once a supervisor has spent its restart intensity. Its children are
+  # down and the decision now belongs to whatever supervises the supervisor.
+  class Escalated < Error; end
+end