service_skeleton 0.0.0.1.ENOTAG

data/ultravisor/spec/ultravisor/child/shutdown_spec.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "../../spec_helper"
+
+require_relative "../../../lib/ultravisor/child"
+require_relative "../../../lib/ultravisor/error"
+
+describe Ultravisor::Child do
+  uses_logger
+
+  let(:base_args) { { id: :bob, klass: mock_class, method: :run } }
+  let(:child) { Ultravisor::Child.new(**args) }
+  let(:mock_class) { Class.new.tap { |k| k.class_eval { def run; end; def sigterm; end } } }
+  let(:mock_instance) { instance_double(mock_class) }
+  let(:term_queue) { instance_double(Queue) }
+
+  describe "#shutdown" do
+    let(:args) { base_args }
+
+    context "when the child isn't running" do
+      it "returns immediately" do
+        child.shutdown
+      end
+    end
+
+    context "when the child is running" do
+      before(:each) do
+        orig_thread_new = Thread.method(:new)
+        allow(Thread).to receive(:new) do |&b|
+          orig_thread_new.call(&b).tap do |th|
+            @thread = th
+            allow(th).to receive(:kill).and_call_original
+            allow(th).to receive(:join).and_call_original
+          end
+        end
+
+        allow(mock_class).to receive(:new).and_return(mock_instance)
+        allow(mock_instance).to receive(:run)
+
+        allow(term_queue).to receive(:<<)
+      end
+
+      it "kills the thread" do
+        child.spawn(term_queue).shutdown
+
+        expect(@thread).to have_received(:kill)
+      end
+
+      it "waits for the thread to be done" do
+        child.spawn(term_queue).shutdown
+
+        expect(@thread).to have_received(:join).with(1)
+      end
+
+      it "doesn't put anything on the queue" do
+        expect(term_queue).to_not receive(:<<)
+
+        child.spawn(term_queue).shutdown
+      end
+
+      context "when there's a shutdown spec" do
+        let(:args) { base_args.merge(shutdown: { method: :sigterm, timeout: 0.05 }) }
+
+        before(:each) do
+          allow(mock_instance).to receive(:sigterm)
+        end
+
+        it "calls the specified shutdown method" do
+          expect(mock_instance).to receive(:sigterm)
+
+          child.spawn(term_queue).shutdown
+        end
+
+        it "waits for up to the timeout period" do
+          child.spawn(term_queue).shutdown
+
+          expect(@thread).to have_received(:join).with(0.05)
+        end
+
+        context "the worker doesn't finish quickly enough" do
+          before(:each) do
+            allow(mock_instance).to receive(:run) { sleep 15 }
+          end
+
+          it "kills the thread" do
+            child.spawn(term_queue).shutdown
+
+            expect(@thread).to have_received(:kill)
+          end
+        end
+      end
+
+      context "when the thread infinihangs" do
+        # No need for a big timeout, we know it's not going to succeed
+        let(:args) { base_args.merge(shutdown: { timeout: 0.000001 }) }
+        let(:m) { Mutex.new }
+        let(:cv) { ConditionVariable.new }
+
+        before(:each) do
+          allow(mock_instance).to receive(:run) do
+            Thread.handle_interrupt(Numeric => :never) do
+              m.synchronize do
+                @state = 1
+                cv.signal
+                cv.wait(m) until @state == 2
+              end
+            end
+          end
+
+          allow(logger).to receive(:error)
+        end
+
+        it "logs an error" do
+          expect(logger).to receive(:error)
+
+          child.spawn(term_queue)
+          m.synchronize { cv.wait(m) until @state == 1 }
+          child.shutdown
+          m.synchronize { @state = 2; cv.signal }
+        end
+      end
+    end
+  end
+end

data/ultravisor/spec/ultravisor/child/spawn_spec.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "../../spec_helper"
+
+require_relative "../../../lib/ultravisor/child"
+require_relative "../../../lib/ultravisor/error"
+
+describe Ultravisor::Child do
+  let(:child) { Ultravisor::Child.new(**args) }
+  let(:mock_class) { Class.new.tap { |k| k.class_eval { def run; end } } }
+  let(:mock_instance) { double(mock_class) }  # rubocop:disable RSpec/VerifiedDoubles
+  let(:term_queue) { instance_double(Queue) }
+
+  describe "#spawn" do
+    before(:each) do
+      allow(term_queue).to receive(:<<)
+    end
+
+    context "with minimal arguments" do
+      let(:args) { { id: :bob, klass: mock_class, method: :run } }
+
+      before(:each) do
+        allow(mock_class).to receive(:new).and_return(mock_instance)
+        allow(mock_instance).to receive(:run)
+      end
+
+      it "instantiates the class" do
+        expect(mock_class).to receive(:new).with(no_args)
+
+        child.spawn(term_queue).wait
+      end
+
+      it "calls the run method on the class instance" do
+        expect(mock_instance).to receive(:run).with(no_args)
+
+        child.spawn(term_queue).wait
+      end
+
+      it "registers the thread it is running in" do
+        expect(mock_instance).to receive(:run) do
+          expect(child.instance_variable_get(:@thread)).to eq(Thread.current)
+        end
+
+        child.spawn(term_queue).wait
+      end
+
+      it "notes the start time" do
+        expect(mock_instance).to receive(:run) do
+          # Can only check @start_time while the child is running, as the
+          # variable gets nil'd after the run completes
+          expect(child.instance_variable_get(:@start_time).to_f).to be_within(0.01).of(Time.now.to_f)
+        end
+
+        child.spawn(term_queue).wait
+      end
+
+      it "notes the termination value" do
+        expect(mock_instance).to receive(:run).with(no_args).and_return(42)
+
+        child.spawn(term_queue)
+
+        expect(child.termination_value).to eq(42)
+      end
+
+      it "tells the ultravisor it terminated" do
+        expect(term_queue).to receive(:<<).with(child)
+
+        child.spawn(term_queue).wait
+      end
+
+      it "creates a new thread" do
+        expect(Thread).to receive(:new)
+
+        child.spawn(term_queue).wait
+      end
+
+      context "when the worker object's run method raises an exception" do
+        before(:each) do
+          allow(mock_instance).to receive(:run).and_raise(RuntimeError.new("FWACKOOM"))
+        end
+
+        it "makes a note of the exception" do
+          child.spawn(term_queue)
+
+          expect(child.termination_exception).to be_a(RuntimeError)
+        end
+
+        it "tells the ultravisor it terminated" do
+          expect(term_queue).to receive(:<<).with(child)
+
+          child.spawn(term_queue).wait
+        end
+      end
+    end
+
+    context "with a worker class that takes args" do
+      let(:args) { { id: :testy, klass: mock_class, args: ["foo", "bar", baz: "wombat"], method: :run } }
+      let(:mock_class) { Class.new.tap { |k| k.class_eval { def initialize(*x); end; def run; end } } }
+
+      it "creates the class instance with args" do
+        expect(mock_class).to receive(:new).with("foo", "bar", baz: "wombat").and_call_original
+
+        child.spawn(term_queue).wait
+      end
+    end
+  end
+end

data/ultravisor/spec/ultravisor/child/unsafe_instance_spec.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "../../spec_helper"
+
+require_relative "../../../lib/ultravisor/child"
+require_relative "../../../lib/ultravisor/error"
+
+describe Ultravisor::Child do
+  let(:args) { { id: :bob, klass: Object, method: :to_s } }
+  let(:child) { Ultravisor::Child.new(**args) }
+
+  describe "#unsafe_instance" do
+    context "by default" do
+      it "explodes" do
+        expect { child.unsafe_instance }.to raise_error(Ultravisor::ThreadSafetyError)
+      end
+    end
+
+    context "with access: :unsafe" do
+      let(:args) { { id: :bob, klass: Object, method: :to_s, access: :unsafe } }
+
+      context "when there's no instance object" do
+        it "waits for the instance object to appear" do
+          expect(child.instance_variable_get(:@spawn_cv)).to receive(:wait) do
+            child.instance_variable_set(:@instance, "gogogo")
+          end
+
+          child.unsafe_instance
+        end
+      end
+
+      context "when there's an instance object" do
+        before(:each) do
+          child.instance_variable_set(:@instance, "bob")
+        end
+
+        it "returns the instance object" do
+          expect(child.unsafe_instance).to eq("bob")
+        end
+      end
+    end
+
+    context "when the child is running" do
+      it "only exits once the child has finished" do
+        child.instance_variable_set(:@thread, Thread.new {})
+
+        expect(child.instance_variable_get(:@spawn_cv)).to receive(:wait).with(child.instance_variable_get(:@spawn_m)) do
+          child.instance_variable_set(:@thread, nil)
+        end
+
+        child.wait
+      end
+    end
+  end
+end

data/ultravisor/spec/ultravisor/child/wait_spec.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../../spec_helper"
+
+require_relative "../../../lib/ultravisor/child"
+require_relative "../../../lib/ultravisor/error"
+
+describe Ultravisor::Child do
+  let(:args) { { id: :bob, klass: mock_class, method: :run } }
+  let(:child) { Ultravisor::Child.new(**args) }
+  let(:mock_class) { Class.new.tap { |k| k.class_eval { def run; end } } }
+
+  describe "#wait" do
+    context "when the child isn't running" do
+      it "just returns straight away" do
+        child.wait
+      end
+    end
+
+    context "when the child is running" do
+      it "only exits once the child has finished" do
+        child.instance_variable_set(:@thread, Thread.new {})
+
+        expect(child.instance_variable_get(:@spawn_cv)).to receive(:wait).with(child.instance_variable_get(:@spawn_m)) do
+          child.instance_variable_set(:@thread, nil)
+        end
+
+        child.wait
+      end
+    end
+  end
+end

data/ultravisor/spec/ultravisor/new_spec.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+require_relative "../spec_helper"
+
+require_relative "../../lib/ultravisor"
+
+describe Ultravisor do
+  describe ".new" do
+    context "without arguments" do
+      it "does not explode" do
+        expect { Ultravisor.new }.to_not raise_error
+      end
+
+      it "gives us an Ultravisor instance" do
+        expect(Ultravisor.new).to be_a(Ultravisor)
+      end
+    end
+
+    context "with empty children" do
+      it "does not explode" do
+        expect { Ultravisor.new children: [] }.to_not raise_error
+      end
+    end
+
+    context "with children that isn't an array" do
+      it "raises an error" do
+        [{}, "ohai!", nil, 42].each do |v|
+          expect { Ultravisor.new children: v }.to raise_error(ArgumentError)
+        end
+      end
+    end
+
+    context "with valid children" do
+      let(:ultravisor) { Ultravisor.new(children: [{ id: :testy, klass: Object, method: :to_s }]) }
+
+      it "registers the child by its ID" do
+        expect(ultravisor[:testy]).to be_a(Ultravisor::Child)
+      end
+    end
+
+    context "with two children with the same ID" do
+      it "explodes" do
+        expect do
+          Ultravisor.new(
+            children: [
+              { id: :testy, klass: Object, method: :to_s },
+              { id: :testy, klass: Class, method: :to_s },
+            ]
+          )
+        end.to raise_error(Ultravisor::DuplicateChildError)
+      end
+    end
+
+    context "with a valid strategy" do
+      it "does not explode" do
+        expect { Ultravisor.new strategy: :all_for_one }.to_not raise_error
+      end
+    end
+
+    [
+      { strategy: :bob },
+      { strategy: "all_for_one" },
+      { strategy: ["games"] },
+    ].each do |s|
+      context "with invalid strategy #{s.inspect}" do
+        it "explodes" do
+          expect { Ultravisor.new **s }.to raise_error(ArgumentError)
+        end
+      end
+    end
+  end
+end

data/ultravisor/spec/ultravisor/remove_child_spec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+require_relative "../spec_helper"
+
+require_relative "../../lib/ultravisor"
+
+describe Ultravisor do
+  let(:args) { {} }
+  let(:ultravisor) { Ultravisor.new(**args) }
+  let(:mock_child) { instance_double(Ultravisor::Child) }
+
+  describe "#remove_child" do
+    before(:each) do
+      ultravisor.instance_variable_set(:@children, [[:lamb, mock_child]])
+    end
+
+    context "when the ultravisor isn't running" do
+      it "removes the child from the list of children" do
+        ultravisor.remove_child(:lamb)
+
+        expect(ultravisor[:lamb]).to be(nil)
+      end
+
+      it "doesn't explode if asked to remove a child that doesn't exist" do
+        expect { ultravisor.remove_child(:no_such_child) }.to_not raise_error
+      end
+    end
+
+    context "while the ultravisor is running" do
+      let(:mock_thread) { instance_double(Thread) }
+
+      before(:each) do
+        allow(mock_child).to receive(:shutdown)
+        ultravisor.instance_variable_set(:@running_thread, mock_thread)
+      end
+
+      it "shuts down the child" do
+        expect(mock_child).to receive(:shutdown)
+
+        ultravisor.remove_child(:lamb)
+      end
+
+      it "removes the child from the list of children" do
+        ultravisor.remove_child(:lamb)
+
+        expect(ultravisor[:lamb]).to be(nil)
+      end
+    end
+  end
+end

data/ultravisor/spec/ultravisor/run_spec.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+require_relative "../spec_helper"
+
+require_relative "../../lib/ultravisor"
+
+describe Ultravisor do
+  uses_logger
+
+  describe "#run" do
+    let(:mock_class) { Class.new.tap { |k| k.class_eval { def run; end } } }
+    let(:args) { { children: [{ id: :testy, klass: mock_class, method: :run }] } }
+    let(:ultravisor) { Ultravisor.new(**args) }
+    let(:mock_thread) { instance_double(Thread) }
+
+    before(:each) do
+      allow(ultravisor.instance_variable_get(:@queue)).to receive(:pop).and_return(:shutdown)
+    end
+
+    context "with no children" do
+      let(:args) { {} }
+
+      it "doesn't start anything" do
+        expect(Thread).to_not receive(:new)
+
+        expect { ultravisor.run }.to_not raise_error
+      end
+    end
+
+    context "when already running" do
+      before(:each) do
+        ultravisor.instance_variable_set(:@running_thread, mock_thread)
+      end
+
+      it "raises an exception" do
+        expect { ultravisor.run }.to raise_error(Ultravisor::AlreadyRunningError)
+      end
+    end
+
+    context "when the event handler gets an unknown event" do
+      before(:each) do
+        allow(ultravisor.instance_variable_get(:@queue)).to receive(:pop).and_return("wassamatta", :shutdown)
+        allow(logger).to receive(:error)
+      end
+
+      it "logs an error" do
+        expect(logger).to receive(:error).with(match(/^Ultravisor#.*process_events/))
+
+        ultravisor.run
+      end
+    end
+
+    context "with a single child" do
+      let(:child) { Ultravisor::Child.new(id: :testy, klass: Object, method: :to_s) }
+
+      before(:each) do
+        allow(child).to receive(:spawn)
+        ultravisor.instance_variable_set(:@children, [[child.id, child]])
+      end
+
+      it "spawns a child worker" do
+        expect(child).to receive(:spawn)
+
+        ultravisor.run
+      end
+
+      it "shuts down the child on termination" do
+        expect(ultravisor.instance_variable_get(:@children).first.last).to receive(:shutdown)
+
+        ultravisor.run
+      end
+
+      context "that terminates" do
+        before(:each) do
+          allow(ultravisor.instance_variable_get(:@queue)).to receive(:pop).and_return(child, :shutdown)
+          allow(ultravisor).to receive(:sleep)
+        end
+
+        context "within the limits of its restart policy" do
+          it "spawns the child again" do
+            expect(child).to receive(:spawn).exactly(:twice)
+
+            ultravisor.run
+          end
+
+          it "sleeps between restart" do
+            expect(ultravisor).to receive(:sleep).with(1)
+
+            ultravisor.run
+          end
+        end
+
+        context "too often for its restart policy" do
+          before(:each) do
+            allow(child).to receive(:restart?).and_raise(Ultravisor::BlownRestartPolicyError)
+            allow(logger).to receive(:error)
+          end
+
+          it "terminates the ultravisor" do
+            expect(ultravisor.instance_variable_get(:@queue)).to receive(:<<).with(:shutdown)
+
+            ultravisor.run
+          end
+
+          it "logs an error" do
+            expect(logger).to receive(:error)
+
+            ultravisor.run
+          end
+        end
+
+        context "with a restart_policy delay range" do
+          let(:child) { Ultravisor::Child.new(id: :testy, klass: mock_class, method: :run, restart_policy: { delay: 7..12 }) }
+
+          it "sleeps for a period within the range" do
+            expect(ultravisor).to receive(:sleep).with(be_between(7, 12))
+
+            ultravisor.run
+          end
+        end
+
+        context "while we're in the process of shutting down" do
+          before(:each) do
+            allow(ultravisor.instance_variable_get(:@queue)).to receive(:pop) do
+              if ultravisor.instance_variable_get(:@running_thread)
+                ultravisor.instance_variable_set(:@running_thread, nil)
+                child
+              else
+                :shutdown
+              end
+            end
+          end
+
+          it "doesn't respawn the child" do
+            expect(child).to receive(:spawn).exactly(:once)
+
+            ultravisor.run
+          end
+        end
+
+        context "with restart: :never" do
+          let(:child) { Ultravisor::Child.new(id: :once, klass: mock_class, restart: :never, method: :run) }
+
+          it "doesn't respawn the child" do
+            expect(child).to receive(:spawn).exactly(:once)
+
+            ultravisor.run
+          end
+        end
+
+        context "with restart: :on_failure" do
+          let(:child) { Ultravisor::Child.new(id: :once, klass: mock_class, restart: :on_failure, method: :run) }
+
+          it "doesn't respawn the child" do
+            expect(child).to receive(:spawn).exactly(:once)
+
+            ultravisor.run
+          end
+        end
+
+        context "with an error" do
+          before(:each) do
+            allow(logger).to receive(:error)
+            ex = Errno::ENOENT.new("I stiiiiiiiill haven't found, what I'm lookin' for")
+            ex.set_backtrace(caller)
+            allow(child).to receive(:termination_exception).and_return(ex)
+          end
+
+          it "logs the error" do
+            expect(logger).to receive(:error).with(match(/:testy/))
+
+            ultravisor.run
+          end
+
+          it "respawns the child" do
+            expect(child).to receive(:spawn).exactly(:twice)
+
+            ultravisor.run
+          end
+
+          context "with restart: :on_failure" do
+            let(:child) { Ultravisor::Child.new(id: :once, klass: mock_class, restart: :on_failure, method: :run) }
+
+            it "respawns the child" do
+              expect(child).to receive(:spawn).exactly(:twice)
+
+              ultravisor.run
+            end
+          end
+        end
+      end
+    end
+
+    context "with two children" do
+      let(:args) do
+        {
+          children: [
+            {
+              id: :one,
+              klass: Object,
+              method: :to_s,
+            },
+            {
+              id: :two,
+              klass: Object,
+              method: :to_s,
+            }
+          ]
+        }
+      end
+
+      it "starts the children in order of their definition" do
+        expect(ultravisor[:one]).to receive(:spawn).ordered
+        expect(ultravisor[:two]).to receive(:spawn).ordered
+
+        ultravisor.run
+      end
+
+      it "shuts the children down in the opposite order" do
+        expect(ultravisor[:two]).to receive(:shutdown).ordered
+        expect(ultravisor[:one]).to receive(:shutdown).ordered
+
+        ultravisor.run
+      end
+    end
+
+    context "with an all_for_one strategy" do
+      let(:args) do
+        {
+          strategy: :all_for_one,
+          children: [
+            {
+              id: :one,
+              klass: Object,
+              method: :to_s,
+            },
+            {
+              id: :two,
+              klass: Object,
+              method: :to_s,
+            },
+            {
+              id: :three,
+              klass: Object,
+              method: :to_s,
+            },
+          ]
+        }
+      end
+
+      let(:child1) { Ultravisor::Child.new(id: :one, klass: Object, method: :to_s) }
+      let(:child2) { Ultravisor::Child.new(id: :two, klass: Object, method: :to_s) }
+      let(:child3) { Ultravisor::Child.new(id: :three, klass: Object, method: :to_s) }
+
+      before(:each) do
+        ultravisor.instance_variable_set(:@children, [[:one, child1], [:two, child2], [:three, child3]])
+        allow(ultravisor.instance_variable_get(:@queue)).to receive(:pop).and_return(child2, :shutdown)
+        allow(ultravisor).to receive(:sleep)
+        ultravisor.instance_variable_set(:@running_thread, mock_thread)
+      end
+
+      it "shuts down all the other children in reverse order" do
+        expect(child3).to receive(:shutdown).ordered
+        expect(child1).to receive(:shutdown).ordered
+
+        ultravisor.__send__(:process_events)
+      end
+
+      it "starts up all children in order" do
+        expect(child1).to receive(:spawn).ordered
+        expect(child2).to receive(:spawn).ordered
+        expect(child3).to receive(:spawn).ordered
+
+        ultravisor.__send__(:process_events)
+      end
+    end
+
+    context "with a rest_for_one strategy" do
+      let(:args) do
+        {
+          strategy: :rest_for_one,
+          children: [
+            {
+              id: :one,
+              klass: Object,
+              method: :to_s,
+            },
+            {
+              id: :two,
+              klass: Object,
+              method: :to_s,
+            },
+            {
+              id: :three,
+              klass: Object,
+              method: :to_s,
+            },
+            {
+              id: :four,
+              klass: Object,
+              method: :to_s,
+            },
+          ]
+        }
+      end
+
+      let(:child1) { Ultravisor::Child.new(id: :one, klass: Object, method: :to_s) }
+      let(:child2) { Ultravisor::Child.new(id: :two, klass: Object, method: :to_s) }
+      let(:child3) { Ultravisor::Child.new(id: :three, klass: Object, method: :to_s) }
+      let(:child4) { Ultravisor::Child.new(id: :four, klass: Object, method: :to_s) }
+
+      before(:each) do
+        ultravisor.instance_variable_set(:@children, [[:one, child1], [:two, child2], [:three, child3], [:four, child4]])
+        allow(ultravisor.instance_variable_get(:@queue)).to receive(:pop).and_return(child2, :shutdown)
+        allow(ultravisor).to receive(:sleep)
+        ultravisor.instance_variable_set(:@running_thread, mock_thread)
+      end
+
+      it "shuts down only the children after the failed one, in reverse order" do
+        expect(child4).to receive(:shutdown).ordered
+        expect(child3).to receive(:shutdown).ordered
+
+        ultravisor.__send__(:process_events)
+      end
+
+      it "starts up all the relevant children in order" do
+        expect(child2).to receive(:spawn).ordered
+        expect(child3).to receive(:spawn).ordered
+        expect(child4).to receive(:spawn).ordered
+
+        ultravisor.__send__(:process_events)
+      end
+    end
+  end
+end